Add support for execution_ttl=0 and timeout/deadline parameters

[chrisguidry]

This adds several improvements for high-throughput applications and API clarity:

• Support execution_ttl=timedelta(0) to skip state/result persistence entirely, returning to "fire-and-forget" mode with no observability overhead
• Reduce default execution_ttl from 1 hour to 15 minutes
• Add both timeout (timedelta) and deadline (datetime) parameters to get_result() following standard naming conventions
• Add tests for perpetual tasks to verify they correctly reuse the same key across cycles without accumulating state records

When execution_ttl is 0, the system skips storing results and exceptions entirely, and deletes execution state records immediately upon completion. This provides maximum throughput for applications that don't need observability.

The get_result() method now accepts either timeout (a duration) or deadline (an absolute datetime), with validation to prevent specifying both. This makes the API more intuitive and follows Python conventions where timeout is a duration and deadline is a point in time.

🤖 Generated with Claude Code

[claude]

Claude finished @chrisguidry's task —— View job

---

Code Review for PR #189

Review Tasks

• Read and analyze main implementation changes
• Review test coverage and quality
• Check for potential bugs and edge cases
• Evaluate performance implications
• Assess security concerns
• Provide comprehensive feedback

Overall Assessment

This PR provides valuable performance and API improvements for high-throughput scenarios. The implementation is solid with excellent test coverage maintained at 100%. The changes are well-structured and backwards-compatible.

✅ Strengths

1. Fire-and-forget mode (execution_ttl=0): Excellent implementation that completely skips state persistence for maximum throughput. The immediate deletion of state records in mark_as_completed() and mark_as_failed() (src/docket/execution.py:711-715, 748-753) is clean and efficient.

2. API improvements: The addition of both timeout (timedelta) and deadline (datetime) parameters to get_result() (src/docket/execution.py:767-794) follows Python conventions and improves usability. The validation preventing both parameters is appropriate.

3. Test coverage: Comprehensive test suite in tests/test_ttl_zero.py covering:

   • Basic execution with TTL=0
   • State record deletion verification
   • Result storage behavior
   • Failed task handling
   • Mixed TTL workloads

4. Perpetual task testing: New tests in tests/test_perpetual_state.py verify that perpetual tasks correctly reuse the same key across cycles without accumulating state records - important for preventing memory leaks.

5. Deterministic test synchronization: The improvements in tests/cli/waiting.py and tests/cli/test_watch.py using wait_for_watch_subscribed() eliminate race conditions in tests.

🔍 Potential Issues & Suggestions

1. Reduced default TTL impact: The reduction from 1 hour to 15 minutes (src/docket/docket.py:153) is reasonable but could impact users relying on longer observability windows. Consider documenting this breaking change prominently in release notes.

2. Edge case in result storage: When execution_ttl=0, results are not stored (src/docket/worker.py:692-703, 729-739). The tests show this causes TimeoutError when calling get_result(), but the error message could be more informative:

   # Consider adding a check in get_result():
   if self.docket.execution_ttl == timedelta(0):
       raise ValueError("Cannot retrieve results when execution_ttl is 0 (fire-and-forget mode)")

3. Race condition possibility: In mark_as_completed() and mark_as_failed() when execution_ttl=0, the state is written then immediately deleted (src/docket/execution.py:706-715). This could theoretically allow a brief window where partial state exists. Consider using a Lua script for atomicity or skipping the write entirely when TTL=0.

4. Documentation: The docstring for execution_ttl parameter (src/docket/docket.py:169-170) should mention that setting it to 0 enables fire-and-forget mode with no observability.

⚡ Performance Considerations

• Positive: Fire-and-forget mode (execution_ttl=0) eliminates all Redis state operations after task completion, significantly improving throughput for high-volume scenarios.
• Positive: Skipping result serialization when execution_ttl=0 saves CPU cycles.
• Neutral: The reduced default TTL (15 minutes) will reduce Redis memory usage but may require users to adjust monitoring tools.
• Consider: The conditional checks for execution_ttl in the worker hot path are minimal and shouldn't impact performance.

🔒 Security Assessment

No security concerns identified. The changes:

• Don't introduce new attack vectors
• Maintain proper input validation (timeout/deadline parameters)
• Don't expose sensitive information
• Preserve existing security boundaries

🎯 Recommendations

1. Document the breaking change: The default TTL reduction should be prominently documented in release notes and migration guides.

2. Improve error messaging: When get_result() is called with execution_ttl=0, provide a clearer error message explaining why results aren't available.

3. Consider atomic operations: For the edge case in state deletion with TTL=0, consider making the operation atomic or skip the write entirely.

4. Add usage examples: Consider adding documentation examples showing when to use execution_ttl=0 vs normal TTL settings.

✅ Test Coverage

Test coverage remains at 100% with excellent new tests:

• test_ttl_zero.py: 166 lines covering all TTL=0 scenarios
• test_perpetual_state.py: 179 lines verifying perpetual task behavior
• Enhanced test_results.py with timeout/deadline parameter tests
• Improved test synchronization utilities in waiting.py

Conclusion

This is a well-implemented PR that adds valuable functionality for high-throughput use cases while maintaining backward compatibility. The code quality is high, test coverage is comprehensive, and the implementation is thoughtful. With the minor suggestions above (especially around documentation and error messages), this PR is ready for merge.

Great work on maintaining 100% test coverage and adding deterministic test synchronization! 🎉

[github-actions]

📚 Documentation has been built for this PR!

You can download the documentation directly here:
https://github.com/chrisguidry/docket/actions/runs/19172859974/artifacts/4500632549

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (799bb6d) to head (088940b).

Additional details and impacted files

@@            Coverage Diff             @@
##              main      #189    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files           39        41     +2     
  Lines         6557      6781   +224     
  Branches       326       345    +19     
==========================================
+ Hits          6557      6781   +224     

Flag	Coverage Δ
python-3.10	100.00% <100.00%> (ø)
python-3.11	99.02% <100.00%> (+0.03%)	⬆️
python-3.12	100.00% <100.00%> (ø)
python-3.13	100.00% <100.00%> (ø)
python-3.14	100.00% <100.00%> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
src/docket/cli.py	100.00% <ø> (ø)
src/docket/docket.py	100.00% <ø> (ø)
src/docket/execution.py	100.00% <100.00%> (ø)
src/docket/worker.py	100.00% <100.00%> (ø)
tests/cli/test_watch.py	100.00% <100.00%> (ø)
tests/cli/waiting.py	100.00% <100.00%> (ø)
tests/test_perpetual_state.py	100.00% <100.00%> (ø)
tests/test_results.py	100.00% <100.00%> (ø)
tests/test_ttl_zero.py	100.00% <100.00%> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.