feat: add FastStream worker integration to temporal-boost (#35)

* feat: add FastStream worker integration to temporal-boost

- Add FastStreamBoostWorker class with anyio.run support
- Implement add_faststream_worker method in BoostApp
- Add FastStream worker to workers module exports
- Update logging configuration for FastStream loggers
- Add example usage with Redis and Kafka brokers

This enables running FastStream message broker applications
alongside Temporal workers in the same BoostApp instance.

* fix(no-ref): update docs

* Bump version

---------

Co-authored-by: Oleg Romanov <[email protected]>

Author: dmastapkovich

.vscode/launch.json

@@ -4,6 +4,7 @@
     // Для получения дополнительной информации посетите: https://go.microsoft.com/fwlink/?linkid=830387
     "version": "0.2.0",
     "configurations": [
+
         {
             "name": "Python Debugger: Current File with Arguments",
             "type": "debugpy",
@@ -21,6 +22,15 @@
             "args": ["run", "worker_3"],
             "justMyCode": false
         },
+        {
+            "name": "Python Debugger: Example Simple Faststream",
+            "type": "debugpy",
+            "request": "launch",
+            "program": "examples/example_simple_faststream.py",
+            "console": "integratedTerminal",
+            "args": ["run", "message_processor"],
+            "justMyCode": false
+        },
         {
             "name": "Python Debugger: Example App ASGI",
             "type": "debugpy",

README.md

@@ -6,23 +6,41 @@
 [![PyPI](https://img.shields.io/pypi/v/temporal-boost.svg?style=for-the-badge)](https://pypi.org/project/temporal-boost)
 [![MIT](https://img.shields.io/pypi/l/temporalio.svg?style=for-the-badge)](LICENSE)
 
-Documentation is available [on GH pages](https://northpowered.github.io/temporal-boost/)
+Documentation is available on [GitHub Pages](https://northpowered.github.io/temporal-boost/)
 
 Small framework based on [temporalio/sdk-python](https://github.com/temporalio/sdk-python) - create [Temporal](https://temporal.io/) microservices as fast as you can
 
-# Requirements
+## Requirements
 
-* Python >= 3.10
+- Python >= 3.10
 
-# Features
+## Features
 
-* Create Temporal workers with FastAPI-style
-* Add CRON workers with one code line
-* Append ASGI (ex. FastAPI) workers like Temporal
-* Auto documentation with web UI (like SwaggerUI in FastAPI)
-* Build-in logger and OTLP tracer
+- Create Temporal workers with FastAPI-style
+- Add CRON workers with one code line
+- Append ASGI (ex. FastAPI) workers like Temporal
+- Auto documentation with web UI (like SwaggerUI in FastAPI)
+- Build-in logger and OTLP tracer
+
+## Installation
+
+Install core:
+
+```bash
+pip install temporal-boost
+# or
+poetry add temporal-boost
+```
+
+Optional extras:
+
+- faststream integration: `pip install "temporal-boost[faststream]"` or `poetry add temporal-boost -E faststream`
+- uvicorn ASGI: `pip install "temporal-boost[uvicorn]"` or `poetry add temporal-boost -E uvicorn`
+- hypercorn ASGI: `pip install "temporal-boost[hypercorn]"` or `poetry add temporal-boost -E hypercorn`
+- granian ASGI: `pip install "temporal-boost[granian]"` or `poetry add temporal-boost -E granian`
+
+## Quick start
 
-# Quick start
 ```python
 from temporal_boost import BoostApp
 from temporalio import activity
@@ -83,7 +101,7 @@ app.run()
 ```bash
 python3 main.py
 
-# Usage: main.py [OPTIONS] COMMAND [ARGS]...
+Usage: main.py [OPTIONS] COMMAND [ARGS]...
 
 # Options:
 #   --install-completion [bash|zsh|fish|powershell|pwsh]
@@ -93,25 +111,25 @@ python3 main.py
 #                                   copy it or customize the installation.
 #   --help                          Show this message and exit.
 
-# Commands:
-#   cron
-#   run
+Commands:
+  cron
+  run
 
 ```
 
 ```bash
 python3 main.py run
 
-# Usage: main.py run [OPTIONS] COMMAND [ARGS]...
+Usage: main.py run [OPTIONS] COMMAND [ARGS]...
 
 # Options:
 #   --help  Show this message and exit.
 
-# Commands:
-#   all
-#   test_cron
-#   worker_1
-#   worker_2
+Commands:
+  all
+  test_cron
+  worker_1
+  worker_2
 ```
 
 ```bash
@@ -123,3 +141,39 @@ python3 main.py run worker_1
 # 2023-09-20T21:25:12 | INFO     | Worker worker_1 started on task_q_1 queue
 
 ```
+
+## Environment variables
+
+Core configuration is managed via environment variables (see `temporal_boost/temporal/config.py`):
+
+- `TEMPORAL_TARGET_HOST` (default: `localhost:7233`)
+- `TEMPORAL_NAMESPACE` (default: `default`)
+- `TEMPORAL_TLS` (default: `false`)
+- `TEMPORAL_API_KEY` (optional)
+- `TEMPORAL_IDENTITY` (optional)
+- `TEMPORAL_USE_PYDANTIC_DATA_CONVERTER` (default: `false`)
+
+Worker tuning:
+
+- `TEMPORAL_MAX_CONCURRENT_WORKFLOW_TASKS` (default: `300`)
+- `TEMPORAL_MAX_CONCURRENT_ACTIVITIES` (default: `300`)
+- `TEMPORAL_MAX_CONCURRENT_LOCAL_ACTIVITIES` (default: `100`)
+- `TEMPORAL_MAX_WORKFLOW_TASK_POLLS` (default: `10`)
+- `TEMPORAL_MAX_ACTIVITY_TASK_POLLS` (default: `10`)
+- `TEMPORAL_NONSTICKY_TO_STICKY_RATIO` (default: `0.2`)
+- `TEMPORAL_GRACEFUL_SHUTDOWN_TIMEOUT` (seconds, default: `30`)
+
+Telemetry (Prometheus runtime):
+
+- `TEMPORAL_PROMETHEUS_BIND_ADDRESS` (e.g. `0.0.0.0:8801`)
+- `TEMPORAL_PROMETHEUS_COUNTERS_TOTAL_SUFFIX` (default: `false`)
+- `TEMPORAL_PROMETHEUS_UNIT_SUFFIX` (default: `false`)
+- `TEMPORAL_PROMETHEUS_DURATIONS_AS_SECONDS` (default: `false`)
+
+Example:
+
+```bash
+export TEMPORAL_TARGET_HOST=temporal.example.com:7233
+export TEMPORAL_NAMESPACE=production
+export TEMPORAL_USE_PYDANTIC_DATA_CONVERTER=true
+```

docs/index.md

@@ -11,7 +11,7 @@ Temporal-boost is a lightweight framework for fast and comfortable development o
 - [x] [Temporal SDK (python)](https://github.com/temporalio/sdk-python)
 - [x] [Pydantic - for serialization](https://github.com/pydantic/pydantic)
 - [x] [Typer - for CLI interface](https://github.com/fastapi/typer)
-- [x] [Loguru - for extended logging](https://github.com/Delgan/loguru)
+- [x] [Python logging - built-in logging configuration]
 - [x] [Hypercorn, Uvicorn, Granian - for running ASGI applications](https://github.com/pgjones/hypercorn)
 
 ### Main features
@@ -92,7 +92,7 @@ if __name__ == "__main__":
 
 ### Configuration
 
-All configuration (Temporal endpoint, namespace, TLS, metrics, etc.) is now handled via environment variables. See the documentation for `temporal_boost/temporal/config.py` for all available options.
+All configuration (Temporal endpoint, namespace, TLS, metrics, etc.) is handled via environment variables. See `temporal_boost/temporal/config.py` for available options.
 
 ### Start example application
 

docs/runnig_application.md renamed to docs/running_application.md

@@ -47,7 +47,7 @@ async def test_boost_activity_2(payload: TestModel) -> TestModel:  # noqa: RUF02
 
 @activity.defn(name="custom_test_boost_activity_3")
 async def test_boost_activity_3(payload: TestModel, foo: str, bar: int) -> TestModel:  # noqa: RUF029
-    payload.foo = f"{payload.foo}+activity2"
+    payload.foo = f"{payload.foo}+activity3"
     payload.bar += 1
     return payload
 
@@ -56,7 +56,7 @@ async def test_boost_activity_3(payload: TestModel, foo: str, bar: int) -> TestM
 class MyWorkflow:
     @workflow.run
     async def run(self, foo: str) -> TestModel:  # noqa: ARG002
-        logger.info("Sync logger")
+        logger.info("Sync logger: starting workflow")
 
         start_payload: TestModel = TestModel(foo="hello", bar=0)
         result_1 = await workflow.execute_activity(

examples/example_app.py

@@ -0,0 +1,41 @@
+import logging
+
+from faststream import FastStream
+from faststream.redis import RedisBroker
+from pydantic import BaseModel
+
+from temporal_boost import BoostApp
+
+
+logging.basicConfig(level=logging.INFO)
+logger = logging.getLogger(__name__)
+
+faststream_logger = logger.getChild("faststream")
+
+
+class TaskMessage(BaseModel):
+    task_id: str
+    description: str
+    priority: int
+
+
+broker = RedisBroker("redis://localhost:6379")
+app = FastStream(broker)
+
+
+@broker.subscriber("tasks")
+async def process_task(message: TaskMessage) -> None:  # noqa: RUF029
+    logger.info(f"Processing task: {message.task_id} - {message.description}")
+
+    if message.priority > 5:  # noqa: PLR2004
+        logger.info(f"High priority task {message.task_id} processed immediately")
+    else:
+        logger.info(f"Normal priority task {message.task_id} queued for processing")
+
+
+boost_app = BoostApp("simple-faststream-example")
+boost_app.add_faststream_worker("message_processor", app)
+
+
+if __name__ == "__main__":
+    boost_app.run()

examples/example_simple_faststream.py

@@ -1,5 +1,5 @@
 site_name: Temporal-boost
-site_description: Extemely fast development for Temporal-based microservices
+site_description: Extremely fast development for Temporal-based microservices
 repo_url: https://github.com/northpowered/temporal-boost
 repo_name: northpowered/temporal-boost
 
@@ -11,6 +11,8 @@ theme:
   features:
   - navigation.tracking
   - content.code.copy
+  - navigation.instant
+  - content.tabs.link
   icon:
     annotation: material/arrow-right-circle
 
@@ -38,4 +40,4 @@ markdown_extensions:
 nav:
   - Getting started: index.md
   - Creating application: creating_application.md
-  - Running application: runnig_application.md
+  - Running application: running_application.md