Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 40 additions & 1 deletion .github/ISSUE_TEMPLATE/bug_report.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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:
Expand All @@ -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:
Expand Down
4 changes: 2 additions & 2 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -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.
5 changes: 3 additions & 2 deletions .github/PULL_REQUEST_TEMPLATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
28 changes: 24 additions & 4 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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

Expand Down
15 changes: 11 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

<small>* estimation based on real production task migrated to FastAPI task manager from custom "cron job" solution.</small>
## 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

Expand Down
47 changes: 33 additions & 14 deletions SECURITY.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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.
9 changes: 5 additions & 4 deletions docs/docs/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

<small>* estimation based on real production task migrated to FastAPI task manager from custom "cron job" solution.</small>
//// 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

Expand Down
94 changes: 94 additions & 0 deletions docs/docs/known-issues.md
Original file line number Diff line number Diff line change
@@ -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 <group>/<name> 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" }.
1 change: 1 addition & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Loading
Loading