diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
index 993e4fe..a3d11c8 100644
--- a/.github/ISSUE_TEMPLATE/bug_report.yml
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -8,6 +8,9 @@ body:
value: |
Thank you for taking the time to report a bug. Please fill out the form below to help us investigate.
+ Before opening the issue, check the [Known Issues](https://fastapi-task-manager.morry98.com/known-issues.html) page.
+ **Do not report security vulnerabilities here**: follow the [Security Policy](https://github.com/Morry98/fastapi-task-manager/blob/main/SECURITY.md) instead.
+
- type: textarea
id: description
attributes:
@@ -45,6 +48,33 @@ body:
validations:
required: true
+ - type: textarea
+ id: logs
+ attributes:
+ label: Logs
+ description: Relevant log output, ideally with the `fastapi.task-manager` loggers at DEBUG or INFO level. Remove secrets before pasting.
+ render: shell
+ validations:
+ required: false
+
+ - type: textarea
+ id: config
+ attributes:
+ label: Configuration
+ description: The `Config` you pass to `TaskManager` (remove passwords) and any per-group or per-task overrides involved.
+ render: python
+ validations:
+ required: false
+
+ - type: input
+ id: deployment
+ attributes:
+ label: Deployment
+ description: Number of app instances and uvicorn workers sharing the same Redis.
+ placeholder: "2 containers x 4 uvicorn workers"
+ validations:
+ required: false
+
- type: input
id: version
attributes:
@@ -63,10 +93,19 @@ body:
validations:
required: true
+ - type: input
+ id: redis-py-version
+ attributes:
+ label: redis-py Version
+ description: "Output of: pip show redis"
+ placeholder: "7.4.0"
+ validations:
+ required: true
+
- type: input
id: redis-version
attributes:
- label: Redis Version
+ label: Redis Server Version
description: "Output of: redis-server --version"
placeholder: "7.2.0"
validations:
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
index c2cacbe..0443763 100644
--- a/.github/ISSUE_TEMPLATE/config.yml
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -1,8 +1,8 @@
blank_issues_enabled: false
contact_links:
- name: Security Vulnerability
- url: https://github.com/Morry98/fastapi-task-manager/blob/main/SECURITY.md
- about: Please report security vulnerabilities privately. Do NOT open a public issue.
+ url: https://github.com/Morry98/fastapi-task-manager/security/advisories/new
+ about: Report security vulnerabilities privately through GitHub Security Advisories. Do NOT open a public issue.
- name: Documentation
url: https://fastapi-task-manager.morry98.com
about: Check the documentation before opening an issue.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
index e76f1f8..cfdc97a 100644
--- a/.github/PULL_REQUEST_TEMPLATE.md
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -18,7 +18,8 @@
- [ ] My code follows the project's code style
- [ ] I have added/updated comments where necessary
-- [ ] I have added/updated tests for my changes
+- [ ] I have added/updated tests for my changes (bug fixes include a test that fails without the fix)
- [ ] All tests pass (`uv run pytest`)
- [ ] Pre-commit hooks pass (`pre-commit run --all-files`)
-- [ ] I have updated the documentation (if applicable)
+- [ ] I have updated the documentation (if applicable) and `uv run mkdocs build --strict` passes
+- [ ] I have added an entry to `CHANGELOG.md` (for user-visible changes)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 6bd856e..0174064 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -78,22 +78,41 @@ It's good practice to run this periodically to keep your local tags in sync with
### Documentation
-Documentation is built with MkDocs Material. To preview locally:
+Documentation is built with MkDocs Material and lives in `docs/docs/`. The MkDocs dependencies are in a separate dependency group:
+
+```bash
+uv sync --group docs
+```
+
+Preview locally:
```bash
uv run mkdocs serve
```
+Before opening a PR that touches the documentation, check that it builds without warnings (broken links fail the build):
+
+```bash
+uv run mkdocs build --strict
+```
+
+The documentation site is deployed automatically from `main` by GitHub Actions; there is no manual deploy step.
+
## How to Contribute
### Reporting Bugs
+First check the [Known Issues](https://fastapi-task-manager.morry98.com/known-issues.html) page: the behavior may already be documented, with a workaround.
+
Use the [Bug Report](https://github.com/Morry98/fastapi-task-manager/issues/new?template=bug_report.yml) issue template. Include:
- Steps to reproduce
- Expected vs actual behavior
-- Python version and OS
+- Versions of FastAPI Task Manager, Python, redis-py and the Redis server, and your OS
+- Your `Config` (without passwords) and the number of app instances
- Relevant logs or error messages
+Security vulnerabilities must **not** be reported as issues: follow the [Security Policy](SECURITY.md).
+
### Suggesting Features
Use the [Feature Request](https://github.com/Morry98/fastapi-task-manager/issues/new?template=feature_request.yml) issue template. Please describe:
@@ -108,8 +127,9 @@ Use the [Feature Request](https://github.com/Morry98/fastapi-task-manager/issues
3. Write your code following the project's code style
4. Add or update tests as needed
5. Ensure all checks pass (`pre-commit run --all-files` and `uv run pytest`)
-6. Update documentation if your change affects the public API
-7. Submit your PR against the `main` branch
+6. Update documentation if your change affects the public API or user-visible behavior
+7. Add an entry to `CHANGELOG.md` for user-visible changes, following the existing style
+8. Submit your PR against the `main` branch
#### PR Guidelines
diff --git a/README.md b/README.md
index c09eab2..5825074 100644
--- a/README.md
+++ b/README.md
@@ -32,14 +32,21 @@ FastAPI Task Manager is a lightweight and efficient scheduled task management sy
- **FastAPI Extension** - Built as an extension to FastAPI, making it easy to integrate into existing FastAPI applications and leverage its features
- **Redis-Based** - Uses Redis as the backend for storing task information, ensuring high performance and single-instance execution
-- **Fast to Code** - Increase the speed to develop scheduled tasks by about 400% to 500%, only a wrapper function is needed*
-- **Fewer Bugs** - Reduce about 60% of human (developer) induced errors managing lock, Redis keys and task execution*
+- **Fast to Code** - A decorator turns a function into a scheduled task
+- **Less Boilerplate** - Locking, Redis keys and scheduling state are handled by the library instead of hand-written code in each task
- **Scheduled Tasks** - Provides a simple and intuitive API for defining and scheduling tasks to run at specific intervals or times
- **Task Management** - Includes FastAPI router to manage tasks, such as pausing, resuming, and monitoring execution information
- **Easy to Use** - Designed to be easy to use and learn. Less time reading docs
-- **Robust** - Get production-ready code
-* estimation based on real production task migrated to FastAPI task manager from custom "cron job" solution.
+## Status and Guarantees
+
+FastAPI Task Manager runs cron-scheduled tasks inside your FastAPI application. With several instances sharing one Redis, a single elected leader schedules the tasks and every instance can execute them.
+
+- **Delivery semantics**: task execution is currently **at-least-once with best-effort deduplication**, not exactly-once. A run can occasionally execute more than once (for example, long-running tasks in multi-instance deployments) or be skipped, so write tasks that are safe to run twice.
+- **Retries**: after a failure, the backoff delays the next execution; the failed run is not retried before the next cron occurrence.
+- **Management API**: the router returned by `get_manager_router()` has no built-in authentication. Do not expose it to untrusted networks, and protect it with a FastAPI dependency when you include it.
+
+See [Known Issues](https://fastapi-task-manager.morry98.com/known-issues.html) for details and workarounds, and the [issue tracker](https://github.com/Morry98/fastapi-task-manager/issues) for open bugs.
## Requirements
diff --git a/SECURITY.md b/SECURITY.md
index ae2caf8..e270695 100644
--- a/SECURITY.md
+++ b/SECURITY.md
@@ -2,31 +2,50 @@
## Supported Versions
-The following table shows which versions currently receive security patches.
+Security fixes are released as a new patch version of the latest minor release. Older minor releases do not receive backports, so upgrade to the latest release to get fixes.
-| Version | Supported |
-|---------|-----------|
-| 1.x | Yes |
-| < 1.0 | No |
+| Version | Supported |
+|----------------------|-----------|
+| Latest 1.x minor | Yes |
+| Older 1.x minors | No |
+| < 1.0 | No |
## Reporting a Vulnerability
-If you discover a security vulnerability in this project, please report it responsibly.
+**Do NOT open a public GitHub issue, discussion or pull request for security vulnerabilities.**
-**Do NOT open a public GitHub issue for security vulnerabilities.**
+Report vulnerabilities privately through GitHub Security Advisories:
-Instead, please send an email to **matteo.morando98@gmail.com** with:
+1. Go to the [Security tab](https://github.com/Morry98/fastapi-task-manager/security) of the repository.
+2. Click **Report a vulnerability**.
+3. Fill in the form.
-- A description of the vulnerability
-- Steps to reproduce it
+If you cannot use GitHub, send an email to **matteo.morando98@gmail.com** instead.
+
+Please include:
+
+- A description of the vulnerability and the affected versions
+- Steps to reproduce it, or a minimal proof of concept
- The potential impact
- Any suggested fix (if available)
## Response Timeline
-- **Acknowledgement**: within 48 hours
-- **Initial assessment**: within 1 week
-- **Fix and disclosure**: as soon as a patch is ready, typically within 30 days
+This project is maintained by a single maintainer on a best-effort basis. The targets below are goals, not guarantees:
+
+- **Acknowledgement**: within 7 days
+- **Initial assessment**: within 14 days
+- **Fix and disclosure**: as soon as a patch is ready; we will keep you informed of progress and agree on a disclosure date with you
+
+## Scope
+
+The following are **not** considered vulnerabilities in this library:
+
+- **Unauthenticated access to the management router.** The router returned by `get_manager_router()` has no built-in authentication by design; protecting it is the responsibility of the application that mounts it (see [Known Issues](https://fastapi-task-manager.morry98.com/known-issues.html)). Missing or incorrect documentation about this is welcome as a regular issue.
+- **Attacks that require write access to the Redis instance** used by the library. Anyone who can write to that Redis can control task scheduling; secure Redis with authentication and network isolation.
+- **Behavior of the task functions** registered by the application, including what they do with the arguments they receive.
+- **Vulnerabilities in dependencies** (FastAPI, Starlette, redis-py, Pydantic, cronsim) that are not exploitable through this library. Report them to the affected project.
+- **Denial of service caused by the application configuration**, such as very frequent cron expressions or a high `concurrent_tasks` value.
## Disclosure Policy
@@ -36,4 +55,4 @@ We follow a coordinated disclosure process. We ask that you:
2. Avoid exploiting the vulnerability beyond what is necessary to demonstrate it
3. Do not access or modify other users' data
-We are committed to working with security researchers and will credit reporters in the release notes (unless anonymity is preferred).
+Fixed vulnerabilities are published as GitHub Security Advisories. We will credit reporters in the advisory and in the release notes, unless anonymity is preferred.
diff --git a/docs/docs/index.md b/docs/docs/index.md
index a721152..410a545 100644
--- a/docs/docs/index.md
+++ b/docs/docs/index.md
@@ -45,17 +45,18 @@ FastAPI Task Manager is a lightweight and efficient scheduled task management sy
- **FastAPI Extension** - Built as an extension to FastAPI, making it easy to integrate into existing FastAPI applications and leverage its features
- **Redis Streams Architecture** - Uses Redis Streams with leader election for distributed task scheduling and single-instance execution safety
-- **Fast to Code** - Increase the speed to develop scheduled tasks by about 400% to 500%, only a wrapper function is needed*
-- **Fewer Bugs** - Reduce about 60% of human (developer) induced errors managing lock, Redis keys and task execution*
+- **Fast to Code** - A decorator turns a function into a scheduled task
+- **Less Boilerplate** - Locking, Redis keys and scheduling state are handled by the library instead of hand-written code in each task
- **Scheduled Tasks** - Provides a simple and intuitive API for defining and scheduling tasks to run at specific intervals or times
- **Task Management** - Includes FastAPI router with 12 endpoints to manage tasks: disable, enable, trigger, monitor health, and more
- **Dynamic Tasks** - Create and delete tasks at runtime via REST API without redeploying
- **Retry with Backoff** - Automatic exponential backoff on task failures with configurable per-task overrides
- **Fault Tolerant** - Task heartbeat monitoring, automatic reconciliation of stale tasks, and leader failover
- **Easy to Use** - Designed to be easy to use and learn. Less time reading docs
-- **Robust** - Get production-ready code
-* estimation based on real production task migrated to FastAPI task manager from custom "cron job" solution.
+//// note | Status and guarantees
+Task execution is currently **at-least-once with best-effort deduplication**, not exactly-once, and the management router has no built-in authentication. Read [Known Issues](known-issues.md) before running in production.
+////
## Requirements
diff --git a/docs/docs/known-issues.md b/docs/docs/known-issues.md
new file mode 100644
index 0000000..d223d33
--- /dev/null
+++ b/docs/docs/known-issues.md
@@ -0,0 +1,94 @@
+---
+title: Known Issues
+description: Current limitations of FastAPI Task Manager, the delivery guarantees it gives today, and how to work around them.
+---
+
+# Known Issues
+
+This page lists behaviors of the current release (1.1.1) that you should know about before running FastAPI Task Manager in production, together with the recommended workarounds. Fixes are being worked on; each item will be updated when a release addresses it.
+
+## Delivery guarantees
+
+Task execution is **at-least-once with best-effort deduplication**. In normal operation each scheduled run executes once, but there are situations, described below, in which the same run can execute more than once, or in which a run is skipped.
+
+Write your tasks so that running them twice has no harmful effect (idempotent tasks): for example, use upserts instead of inserts, check whether the work was already done before doing it, or record a processed marker keyed by the scheduled time.
+
+---
+
+## Long-running tasks can be executed again while still running
+
+**Affects:** deployments with more than one instance (or more than one uvicorn worker), and tasks that run longer than about 9 times `running_heartbeat_interval` (27 seconds with the default of 3 seconds).
+
+A task message is acknowledged only when the task finishes. The recovery logic (the periodic Reconciler and the pending-message recovery that runs when an instance starts) treats a message that has been pending for longer than `running_heartbeat_interval * 9` seconds as abandoned by a crashed worker, and queues it again. If the original worker is still executing the task, another worker starts a second execution of the same run. Rolling deploys and autoscaling make this more likely, because every starting instance runs the recovery step.
+
+`allow_parallel=False` does **not** prevent this, because that check happens when a task is scheduled, not when a recovered message is consumed.
+
+**What to do today:**
+
+- Make long-running tasks idempotent (see [Delivery guarantees](#delivery-guarantees)).
+- Raise `running_heartbeat_interval` so that `running_heartbeat_interval * 9` is longer than the longest expected run of your slowest task. For example, for tasks that can take up to 10 minutes, use a value of at least 70 seconds. The trade-off is that a genuinely crashed worker is detected later: its task is recovered only after the same delay.
+- If a task can take hours, consider running it outside the scheduler (for example, schedule a short task that enqueues the work in a dedicated job queue).
+
+---
+
+## Failed tasks are not retried before the next cron occurrence
+
+**Affects:** every task that raises an exception.
+
+When a task fails, the configured backoff (`retry_backoff`, `retry_backoff_max`, `retry_backoff_multiplier`) **delays** the next execution but does not schedule an extra one. The failed run is not executed again after the backoff: the task runs at its next cron occurrence, provided that the backoff has expired by then. For a daily task, a failure means the work is done the next day. If the backoff is longer than the cron interval, the occurrences that fall inside the backoff window are skipped.
+
+**What to do today:**
+
+- Handle transient errors inside the task, for example with a retry loop around the call that can fail, so that a single run succeeds whenever possible.
+- After fixing the cause of a failure, run the task immediately with `POST /tasks/trigger`, which also clears the backoff state (see the [API Reference](learn/api-reference.md)).
+- Use `POST /tasks/reset-retry` to clear the backoff state without triggering a run.
+- Monitor the `Task / failed` log event (see [Logging](learn/deployment.md#logging)).
+
+Real retries, with a configurable retry limit and a dead-letter stream for runs that keep failing, are planned.
+
+---
+
+## The management router has no authentication
+
+**Affects:** every application that mounts the router returned by `get_manager_router()`.
+
+The management router does not authenticate requests. Anyone who can reach it can list tasks (including their keyword arguments), create and delete dynamic tasks that call any registered function with arbitrary arguments, trigger tasks, and disable or enable them. The health endpoint also reports the worker hostname and process ID.
+
+**What to do today:**
+
+- Do not expose the router to untrusted networks. Mount it only on an internal service, or behind a gateway that enforces authentication.
+- Protect it with a FastAPI dependency when you include it. FastAPI applies `dependencies` passed to `include_router()` to every route of the router:
+
+ ```python
+ import secrets
+
+ from fastapi import Depends, FastAPI, HTTPException, Security
+ from fastapi.security import APIKeyHeader
+
+ app = FastAPI()
+ admin_token_header = APIKeyHeader(name="X-Admin-Token")
+
+
+ async def verify_admin(token: str = Security(admin_token_header)) -> None:
+ # Compare in constant time; load the expected token from your settings
+ if not secrets.compare_digest(token, settings.admin_token):
+ raise HTTPException(status_code=403, detail="Forbidden")
+
+
+ app.include_router(
+ task_manager.get_manager_router(),
+ prefix="/task-manager",
+ tags=["task-manager"],
+ dependencies=[Depends(verify_admin)],
+ )
+ ```
+
+- If your orchestrator probes `/task-manager/health` and you protect the router, expose a separate, unauthenticated health endpoint that calls `task_manager.is_healthy()` (see [Health Checks](learn/deployment.md#health-checks)).
+- Do not pass secrets (tokens, passwords, URLs with credentials) as task keyword arguments: they are returned by `GET /tasks`.
+- By default, `@task_group.add_task()` also registers the decorated function for dynamic task creation. Pass `register=False` to every task whose function must not be callable through `POST /tasks`.
+
+---
+
+## Reporting a new issue
+
+If you find a behavior that is not listed here, please open an issue using the [bug report template](https://github.com/Morry98/fastapi-task-manager/issues/new?template=bug_report.yml){ .external-link target="_blank" }. Security vulnerabilities must be reported privately, as described in the [security policy](https://github.com/Morry98/fastapi-task-manager/blob/main/SECURITY.md){ .external-link target="_blank" }.
diff --git a/mkdocs.yml b/mkdocs.yml
index 54601de..35b53f8 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -147,6 +147,7 @@ nav:
- learn/dynamic-tasks.md
- learn/architecture.md
- learn/deployment.md
+ - Known Issues: known-issues.md
- About: about/index.md
- People: about/people.md
- Release Notes: release_notes/index.md
diff --git a/todo.md b/todo.md
deleted file mode 100644
index 9ef00f0..0000000
--- a/todo.md
+++ /dev/null
@@ -1,410 +0,0 @@
-# TODO - Analisi Miglioramenti fastapi-task-manager
-
-Questo documento analizza i file di esempio (`claudio*.py`) e propone un piano di implementazione per migliorare la libreria.
-
----
-
-## Panoramica degli Esempi Analizzati
-
-| File | Classe | Concetto Principale |
-|------|--------|---------------------|
-| `claudio.py` | `MultiStreamPriorityScheduler` | Stream separati per priorità (high/normal) |
-| `claudio1.py` / `claudio2.py` | `RobustTaskScheduler` | Sistema robusto con reconciliation e token window |
-| `claudio3.py` | `OptimizedReconciliation` | Tracking veloce con Redis SET O(1) |
-| `claudio4.py` | `ReconciliationCoordinator` | Coordinator completo con loop di reconciliation |
-| `claudio5.py` | `LeaderOnlyConsumerPattern` | Pattern leader/worker con command stream |
-| `worker_identity.py` | `WorkerIdentity` | Identificazione univoca dei worker |
-
----
-
-## 1. Worker Identity (Priorità: ALTA)
-
-**File di riferimento:** `worker_identity.py`
-
-**Stato attuale:** Il runner usa un semplice UUID generato con `uuid4().int`
-
-**Miglioramento proposto:** Implementare una classe `WorkerIdentity` che fornisce:
-- Identificazione univoca e tracciabile del worker
-- Informazioni diagnostiche (hostname, pid, thread_id)
-- Timestamp di avvio
-- ID composto leggibile per logging
-
-**Tasks:**
-- [ ] Creare `src/fastapi_task_manager/schema/worker_identity.py` (già presente come esempio)
-- [ ] Integrare `WorkerIdentity` nel `Runner`
-- [ ] Aggiungere worker info nelle statistiche esposte via API
-- [ ] Utilizzare `short_id` nei log per debug facilitato
-
----
-
-## 2. Redis Streams invece di Polling (Priorità: ALTA)
-
-**File di riferimento:** `claudio.py`, `claudio5.py`
-
-**Stato attuale:** Il runner usa polling con `asyncio.sleep(0.1)` per controllare i task da eseguire.
-
-**Miglioramento proposto:** Utilizzare Redis Streams per la coda dei task:
-- Pubblicazione task da eseguire in uno stream
-- Consumer group per garantire elaborazione unica
-- Acknowledgment (ACK) dopo esecuzione
-
-**Vantaggi:**
-- Minore carico su Redis (no polling continuo)
-- Delivery garantita
-- Possibilità di recovery dei task non completati
-- Scalabilità orizzontale nativa
-
-**Tasks:**
-- [ ] Creare modulo `stream_scheduler.py` per gestione stream
-- [ ] Implementare setup automatico consumer group
-- [ ] Modificare `Runner` per usare `XREADGROUP` invece di polling
-- [ ] Implementare ACK dopo esecuzione task
-- [ ] Gestire pending messages per task falliti
-
----
-
-## 3. Sistema di Priorità Multi-Stream (Priorità: MEDIA)
-
-**File di riferimento:** `claudio.py`
-
-**Stato attuale:** Esiste `high_priority` flag nel task ma la gestione è limitata al semaforo `force_acquire`.
-
-**Miglioramento proposto:** Stream separati per livelli di priorità:
-- `tasks:stream:high` - Task critici
-- `tasks:stream:normal` - Task standard
-
-**Comportamento:**
-- Worker controlla prima stream high, poi normal
-- Block timeout diversi per priorità (es. 100ms high, 1s normal)
-- Garantisce che task high-priority siano processati prima
-
-**Tasks:**
-- [ ] Creare enum `TaskPriority` (HIGH, NORMAL, LOW)
-- [ ] Implementare routing automatico ai diversi stream
-- [ ] Modificare worker loop per controllare stream in ordine di priorità
-- [ ] Aggiungere metriche per latenza per priorità
-
----
-
-## 4. Reconciliation System (Priorità: ALTA)
-
-**File di riferimento:** `claudio3.py`, `claudio4.py`
-
-**Stato attuale:** Se un task viene perso (es. crash durante scheduling), non c'è meccanismo di recovery.
-
-**Miglioramento proposto:** Sistema di reconciliation periodico:
-
-### 4.1 Tracking Set (approccio ottimizzato da `claudio3.py`)
-- Mantiene `tasks:scheduled` SET per tracking O(1)
-- Mantiene `tasks:running:{task_name}` key per task in esecuzione
-- Verifica rapida senza scansione stream
-
-### 4.2 Reconciliation Loop (da `claudio4.py`)
-- Ogni N secondi verifica task "overdue"
-- Se task è overdue e non in stream/running -> ri-pubblica
-- Log dettagliato per debug
-
-**Tasks:**
-- [ ] Creare modulo `reconciliation.py`
-- [ ] Implementare tracking set per task schedulati
-- [ ] Implementare tracking per task in esecuzione
-- [ ] Creare reconciliation loop nel coordinator
-- [ ] Aggiungere configurazione `reconciliation_interval` in `Config`
-- [ ] Aggiungere metriche per task riconciliati
-
----
-
-## 5. Leader Election e Coordinator Pattern (Priorità: MEDIA)
-
-**File di riferimento:** `claudio5.py`
-
-**Stato attuale:** Ogni istanza ha il proprio runner che compete per il lock del task.
-
-**Miglioramento proposto (opzionale):** Pattern Leader/Follower:
-- Un solo "coordinator" (leader) schedula i task
-- Tutti i worker eseguono i task dallo stream
-- Leader election via Redis lock
-
-**Vantaggi:**
-- Scheduling centralizzato più predicibile
-- Riduzione race conditions
-- Semplifica reconciliation
-
-**Svantaggi:**
-- Singolo punto di failure (mitigato da failover)
-- Maggiore complessità
-
-**Tasks:**
-- [ ] Valutare se implementare (discussione architetturale)
-- [ ] Se sì: implementare leader election con Redis lock + TTL
-- [ ] Se sì: separare logica coordinator da worker
-- [ ] Se sì: implementare command stream per operazioni admin
-
----
-
-## 6. Miglioramenti Redis Keys (Priorità: BASSA)
-
-**Stato attuale:** Le chiavi Redis sono costruite con concatenazione di stringhe nel codice.
-
-**Miglioramento proposto:**
-- Creare classe `RedisKeyBuilder` per costruzione chiavi
-- Centralizzare pattern delle chiavi
-- Documentare tutti i key patterns
-
-**Tasks:**
-- [ ] Creare `redis_keys.py` con costanti e builder
-- [ ] Refactor runner.py per usare il builder
-- [ ] Aggiornare documentazione con key patterns
-
----
-
-## 7. Miglioramento Storage Statistiche (Priorità: BASSA)
-
-**Stato attuale:** Runs e durations salvate come stringhe separate da `\n` in Redis.
-
-**Miglioramento proposto:** Usare Redis List (`LPUSH`/`LTRIM`) invece di stringhe:
-- Operazioni atomiche
-- `LTRIM` per limitare automaticamente la lista
-- Niente parsing manuale
-
-**Tasks:**
-- [ ] Migrare `_runs` a Redis List
-- [ ] Migrare `_durations_second` a Redis List
-- [ ] Aggiungere migration script per dati esistenti
-
----
-
-## 8. Gestione Errori e Retry (Priorità: MEDIA)
-
-**Stato attuale:** Se un task fallisce, l'errore viene loggato ma non c'è retry.
-
-**Miglioramento proposto:**
-- Configurazione retry per task (max_retries, backoff)
-- Dead Letter Queue per task falliti definitivamente
-- Metriche errori per task
-
-**Tasks:**
-- [ ] Aggiungere `max_retries` e `retry_backoff` a Task schema
-- [ ] Implementare retry logic nel worker
-- [ ] Creare DLQ stream per task falliti
-- [ ] Aggiungere endpoint API per visualizzare/riprovare task falliti
-
----
-
-## Piano di Implementazione Suggerito
-
-### Fase 1 - Fondamenta (Breaking changes minimi)
-1. Worker Identity
-2. Redis Key Builder
-3. Storage statistiche con Lists
-
-### Fase 2 - Core Improvements
-4. Redis Streams base
-5. Reconciliation System
-6. Gestione Errori e Retry
-
-### Fase 3 - Advanced Features
-7. Sistema Priorità Multi-Stream
-8. Leader Election (opzionale)
-
----
-
-## Note Tecniche
-
-### Compatibilità
-- Valutare migration path per utenti esistenti
-- Considerare feature flags per nuove funzionalità
-- Mantenere backward compatibility dove possibile
-
-### Testing
-- Ogni feature richiede unit test
-- Aggiungere integration test con Redis reale
-- Test di failover e recovery
-
-### Documentazione
-- Aggiornare README con nuove features
-- Documentare architettura Redis Streams
-- Aggiungere esempi per nuovi pattern
-
----
-
-## NUOVA SEZIONE: Findings Analisi Multi-Agente
-
-### Bug Critici da Fixare IMMEDIATAMENTE
-
-#### 1. Race Condition nel Lock Distribuito (`runner.py:131-153`)
-
-**Problema**: Pattern `EXISTS` + `SET` non atomico
-
-```python
-# ATTUALE (VULNERABILE)
-redis_uuid_exists = await self._redis_client.exists(...)
-if not redis_uuid_exists:
- await self._redis_client.set(..., ex=15)
- await asyncio.sleep(0.2) # Workaround fragile!
-```
-
-**Fix**: Usare `SET NX` (atomico)
-```python
-lock_acquired = await self._redis_client.set(
- lock_key, self._uuid, nx=True, ex=15
-)
-if not lock_acquired:
- return
-```
-
-#### 2. Pattern Anti-Pattern EXISTS + GET (`runner.py:79-96`)
-
-**Problema**: Due round-trip Redis invece di uno
-
-```python
-# ATTUALE (INEFFICIENTE)
-if await self._redis_client.exists(key):
- value = await self._redis_client.get(key)
-
-# FIX
-value = await self._redis_client.get(key)
-if value is not None:
- ...
-```
-
-**Impatto**: -50% operazioni Redis immediate
-
----
-
-### Proiezioni Performance (100 tasks, 10 workers)
-
-| Metrica | Polling Attuale | Quick Fixes | Redis Streams |
-|---------|-----------------|-------------|---------------|
-| Redis ops/sec (idle) | 20,000 | 10,000 | 100-200 |
-| Latenza pickup task | 53ms avg | 53ms | 3ms |
-| CPU worker (idle) | 15-20% | 10-12% | 1-2% |
-| Redis CPU | 10-15% | 5-8% | 1-2% |
-| Memory Redis | 300KB | 300KB | 3MB |
-
----
-
-### Architettura Raccomandata: Redis Streams Hybrid
-
-```
-+------------------+ +-----------------+ +------------------+
-| Cron Scheduler | --> | Redis Stream | --> | Worker Consumers|
-| (evaluates cron)| | (Task Queue) | | (XREADGROUP) |
-+------------------+ +-----------------+ +------------------+
- | | |
- v v v
- ZSET pending Stream entries Task execution
- (score=next_run) (ready tasks) (with XACK)
-```
-
----
-
-### Lua Scripts Richiesti per Atomicità
-
-Le operazioni multi-step in `claudio3.py` e `claudio4.py` richiedono Lua scripts:
-
-```lua
--- publish_task.lua (esempio)
-local stream = KEYS[1]
-local scheduled_set = KEYS[2]
-local pending_zset = KEYS[3]
-local task_name = ARGV[1]
-
-local msg_id = redis.call('XADD', stream, '*', 'task_name', task_name, ...)
-redis.call('SADD', scheduled_set, task_name)
-redis.call('ZREM', pending_zset, task_name)
-return msg_id
-```
-
----
-
-### Roadmap Aggiornata (5 Fasi)
-
-#### Fase 0 - Quick Wins (1-2 giorni) ⚡ NUOVA
-- [ ] Fix race condition lock con `SET NX`
-- [ ] Rimuovere pattern `EXISTS` + `GET`
-- [ ] Pipeline operazioni statistiche
-- [ ] Ridurre frequenza lock renewal (da 10/sec a 0.5/sec)
-
-#### Fase 1 - Fondamenta (1-2 settimane)
-- [ ] Worker Identity
-- [ ] Redis Key Builder
-- [ ] Storage statistiche con Lists
-- [ ] Configurazione: `worker_service_name`, `poll_interval`, `lock_ttl`
-
-#### Fase 2 - Redis Streams Core (2-3 settimane)
-- [ ] `StreamScheduler` class
-- [ ] `StreamConsumer` class con XREADGROUP
-- [ ] Consumer group initialization
-- [ ] ACK logic
-- [ ] Feature flag: `use_streams: bool = False`
-- [ ] Config: `stream_max_len`, `stream_block_ms`
-
-#### Fase 3 - Reconciliation & Recovery (1-2 settimane)
-- [ ] `ReconciliationService` class
-- [ ] Tracking SET per task schedulati
-- [ ] Running task tracking con TTL keys
-- [ ] Pending message recovery on startup
-- [ ] Config: `reconciliation_interval_seconds`, `task_running_ttl_seconds`
-
-#### Fase 4 - Priority Streams (1 settimana)
-- [ ] `TaskPriority` enum
-- [ ] Multi-stream routing
-- [ ] Priority-ordered consumption
-
-#### Fase 5 - Error Handling & DLQ (1-2 settimane)
-- [ ] `max_retries`, `retry_backoff` in Task schema
-- [ ] Exponential backoff retry logic
-- [ ] Dead Letter Queue stream
-- [ ] API endpoints per DLQ management
-
----
-
-### Rischi e Mitigazioni
-
-| Rischio | Impatto | Probabilità | Mitigazione |
-|---------|---------|-------------|-------------|
-| Learning curve Redis Streams | Medio | Alta | Documentazione, test, feature flag off by default |
-| Migration path utenti esistenti | Alto | Media | Version detection, auto-migration, upgrade docs |
-| Memory usage streams | Medio | Media | `MAXLEN ~`, configurable retention |
-| Consumer group race on startup | Medio | Bassa | `XGROUP CREATE ... MKSTREAM` con error handling |
-
----
-
-### Nuove Configurazioni da Aggiungere a `Config`
-
-```python
-class Config(BaseModel):
- # ... existing ...
-
- # Fase 0 - Quick wins
- poll_interval: float = 0.1
- lock_renewal_interval: float = 2.0
- running_lock_ttl: int = 5
-
- # Fase 1 - Foundation
- worker_service_name: str = "fastapi-task-manager"
-
- # Fase 2 - Streams
- use_streams: bool = False
- stream_max_len: int = 10000
- stream_block_ms: int = 1000
-
- # Fase 3 - Reconciliation
- reconciliation_enabled: bool = True
- reconciliation_interval_seconds: int = 30
- task_running_ttl_seconds: int = 3600
-```
-
----
-
-## File da Rimuovere dopo Implementazione
-
-I seguenti file sono esempi/prototipi e vanno rimossi dopo aver completato l'implementazione:
-- `claudio.py`
-- `claudio1.py`
-- `claudio2.py`
-- `claudio3.py`
-- `claudio4.py`
-- `claudio5.py`
-- `src/fastapi_task_manager/schema/worker_identity.py` (da integrare nel progetto, non rimuovere)
diff --git a/usage.md b/usage.md
deleted file mode 100644
index 771906c..0000000
--- a/usage.md
+++ /dev/null
@@ -1,17 +0,0 @@
-# Usage notes
-> [!IMPORTANT]
-> This needs to be moved inside the doc
-
-local docs development:
-```
-uv run mkdocs serve
-```
-new version creation:
-```
-uv build
-uv release
-```
-publish docs to github pages:
-```
-uv run mkdocs gh-deploy
-```