Repository navigation
Conversation
- Remove todo.md (outdated internal plan, not in English) and usage.md (maintainer notes); move the still-useful docs commands to CONTRIBUTING.md - Replace unverifiable claims in README and docs home page, and add a "Status and Guarantees" section describing at-least-once delivery - Add a Known Issues page with current limitations and workarounds - SECURITY.md: private reporting via GitHub Security Advisories, supported versions, best-effort response targets and scope - Extend the bug report and pull request templates
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Clean up repository and add known issues documentation
What changes
Removed
todo.md(410 lines, not in English): a historical implementation plan written before the Redis Streams rewrite. It references code that no longer exists (runner.py:131-153, polling loop, prototype files). Almost everything it proposed is already implemented (worker identity, Redis Streams with consumer groups, reconciliation, leader election, centralized Redis keys, stream-based statistics, priority streams). The only item still open, real retries with a retry limit and a dead-letter stream, is mentioned in one line on the new Known Issues page ("planned"). No Roadmap page was added: a page with a single item would not be useful.usage.md(maintainer notes marked "needs to be moved inside the doc"):uv run mkdocs servewas already inCONTRIBUTING.md; it is now preceded by the missinguv sync --group docsstep and followed byuv run mkdocs build --strict.uv run mkdocs gh-deployis obsolete: docs are deployed by.github/workflows/docs.yml.CONTRIBUTING.mdnow says so.uv build/uv releaseare maintainer release steps (anduv releaseis not a uv command), so they were not moved to the public docs.README and docs home page
docs/docs/index.mdwere changed the same way.New page: Known Issues (
docs/docs/known-issues.md, added to the nav)Describes the current behaviors with workarounds:
running_heartbeat_interval * 9). Workarounds: idempotent tasks, raiserunning_heartbeat_interval, run very long jobs outside the scheduler. Notes thatallow_parallel=Falsedoes not prevent it.POST /tasks/trigger,POST /tasks/reset-retry, monitoring the failure log.include_router(..., dependencies=[Depends(...)])(example included), separate health endpoint for probes, no secrets in kwargs,register=False.Community files
SECURITY.md: private reporting through GitHub Security Advisories (email kept as fallback); supported versions = latest 1.x minor, no backports; honest best-effort response targets (7 days acknowledgement, 14 days assessment); a "Scope" section listing what is not a vulnerability (unauthenticated router by design, attacks that need Redis write access, application task code, non-exploitable dependency CVEs, configuration-induced DoS).CONTRIBUTING.md: docs dependency group and strict build, docs deployment note, Known Issues check before reporting bugs, richer bug report details, CHANGELOG step in the PR checklist..github/ISSUE_TEMPLATE/bug_report.yml: links to Known Issues and Security Policy; new fields for redis-py version, logs,Config, deployment (instances/workers)..github/ISSUE_TEMPLATE/config.yml: the security contact link now opens the private advisory form..github/PULL_REQUEST_TEMPLATE.md: strict docs build and CHANGELOG checklist items; bug fixes include a failing-without-fix test.CODE_OF_CONDUCT.mdandfeature_request.ymlwere reviewed and left unchanged.No source code or tests were changed.
CHANGELOG.mdhas noUnreleasedsection, so no entry was added.How to verify
uv sync --group docsthenuv run mkdocs build --strict: passes (no broken links to removed files).pre-commit run --all-files: all hooks pass.grepfor Italian words over the repository (excluding.venv,.git, build output): no matches. No other non-English files remain.grep -rn "todo.md\|usage.md": no references left.Mutations
None: documentation-only change, no behavior to guard with a test.
Notes for the maintainer
config.ymllink to work.SECURITY.md(7/14 days) and the supported versions policy (latest minor only) are proposals; adjust them if they do not match what you can commit to.Development Status :: 5 - Production/Stablewas not changed. Recommendation: switch toDevelopment Status :: 4 - Betauntil the release that fixes the duplicate execution of long-running tasks and the retry behavior (planned for 1.1.2/1.2.0), then move back to5 - Production/Stable. Reason: the classifier is the first signal users see on PyPI, and today the library can run a task twice or skip a retry under default settings; the Known Issues page mitigates this, but the classifier contradicts it.docs/docs/features.mdanddocs/docs/learn/architecture.mdstill claim "exactly once", andconfigurations.md/architecture.mddescribe retries that do not happen. They were left out of scope here (documentation accuracy fix tracked separately); the Known Issues page and the README now state the real behavior.Text for the GitHub Release note / pinned issue (1.1.1)
Title: Known issues in 1.1.1 and recommended workarounds
FastAPI Task Manager 1.1.1 has the following known behaviors. Fixes are in progress; this issue will be updated when they are released. Full details: https://fastapi-task-manager.morry98.com/known-issues.html
Delivery guarantees. Task execution is at-least-once with best-effort deduplication, not exactly-once. Write tasks that are safe to run twice (upserts, "already done" checks, processed markers keyed by the scheduled time).
1. Long-running tasks can run twice in multi-instance deployments.
With more than one instance or uvicorn worker, a task that runs longer than about 9 ×
running_heartbeat_interval(27 s by default) can be started again by another worker while the first execution is still running. Starting new instances (rolling deploys, autoscaling) makes it more likely.allow_parallel=Falsedoes not prevent it.Workaround: make long tasks idempotent and raise
running_heartbeat_intervalso that 9 × its value exceeds your longest task (for example, at least 70 s for tasks up to 10 minutes). Crashed workers will then be detected more slowly.2. Failed tasks are not retried before the next cron occurrence.
The retry backoff delays the next execution but does not schedule an extra one. A daily task that fails runs again the next day; occurrences inside a backoff window longer than the cron interval are skipped.
Workaround: handle transient errors inside the task, and after fixing the cause run it with
POST /tasks/trigger(which also clears the backoff) or clear the backoff withPOST /tasks/reset-retry.3. The management router has no authentication.
Anyone who can reach the router from
get_manager_router()can list, create, delete, trigger, disable and enable tasks.Workaround: do not expose it to untrusted networks and protect it with a FastAPI dependency:
Do not pass secrets as task keyword arguments, and use
register=Falseon tasks whose functions must not be callable through the API.Found something else? Open a bug report. Security vulnerabilities: please report them privately as described in SECURITY.md.
🤖 Generated with Claude Code
https://claude.ai/code/session_01HVysDtCKsBLcXJcnZY2R7S