Refactor: Extract transcoding job state machine into explicit code (#438)#499
Merged
filthyrake merged 2 commits intodevfrom Jan 4, 2026
Merged
Refactor: Extract transcoding job state machine into explicit code (#438)#499filthyrake merged 2 commits intodevfrom
filthyrake merged 2 commits intodevfrom
Conversation
) - Add api/job_state.py with TranscodingJobStateMachine class - JobState enum: unclaimed, claimed, expired, completed, failed, retrying - State predicates: is_unclaimed(), is_claimed(), is_expired(), etc. - SQL condition generators: sql_unclaimed(), sql_claimed(), etc. - Transition validation: can_claim(), can_complete(), can_fail() - JobRow dataclass for type-safe state determination - Add comprehensive tests (49 test cases) for state machine - Simplify 109-line comment block in database.py to 6 lines - Update worker_api.py to reference new state machine module The implicit state machine derived from nullable field combinations is now explicit, self-documenting code that reads like requirements. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Security fixes: - Add SQL identifier validation to prevent injection in table_alias - Add SQL parameter validation to prevent injection in now_param - Sanitize error messages to avoid leaking internal state details Reliability fixes: - Add timezone normalization in JobRow.from_mapping() for naive datetimes - Add defensive completed_at checks in is_failed() and is_retrying() - Validate numeric fields (attempt_number, max_attempts >= 1) - Improve indeterminate state error logging Consistency fixes: - Fix sql_claimable() to include both unclaimed AND retrying jobs - Update is_unclaimed() to check last_error is None (distinguishes from retrying) - Rename 'now' parameter to 'current_time' for clarity Performance: - Remove unused jobs_table constructor parameter - Add _normalize_job() helper to reduce code duplication Documentation: - Add state transition diagram to module and class docstrings - Add thread safety and distributed safety notes - Improve docstrings with worker identity verification notes Tests (71 total): - Add SQL injection prevention tests - Add timezone normalization tests - Add boundary condition tests (exact expiration time) - Add indeterminate state test - Add numeric validation tests 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
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
1 participant
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.
Summary
api/job_state.pywithTranscodingJobStateMachineclass that makes the implicit state machine explicit and self-documentingJobStateenum with 6 states:unclaimed,claimed,expired,completed,failed,retryingis_unclaimed(),is_claimed(), etc.), SQL condition generators, and transition validation methodsdatabase.pyto 6 lines that reference the new moduleChanges
New file:
api/job_state.py- ContainsTranscodingJobStateMachineclass with:JobStateenum for explicit state representationJobRowdataclass for type-safe state determinationis_unclaimed(),is_claimed(),is_expired(),is_completed(),is_failed(),is_retrying()sql_unclaimed(),sql_claimed(),sql_expired(), etc. for query compositioncan_claim(),can_reclaim(),can_complete(),can_fail()job_state_machinefor convenienceNew file:
tests/test_job_state.py- 49 comprehensive tests covering:Updated:
api/database.py- Simplified comments to reference new moduleUpdated:
api/worker_api.py- Updated docstring to reference new moduleBenefits
Closes #438
Test plan
🤖 Generated with Claude Code