{ "summary": "The shutdown deadline does not bound SIGTERM completion: _drain_for_shutdown() times out, but its TaskGroup still owns the poller and consumers and may continue waiting (lines 415-438, 515-533). Cancellation cleanup can also leave failure persistence incomplete (lines 469-474), while the delivery race cancels tasks without awaiting them (lines 380-383). Queue.shutdown(False) and explicit worker-child cancellation provide the clearest incremental fix.", "detectedLanguage": "Python", "framework": null, "runtime": "Python 3.14", "detectedTechniques": [ { "name": "Asyncio structured concurrency", "category": "Concurrency", "evidence": "Worker.run() creates poller and consumers in one TaskGroup at lines 415-425; race_lease_and_delivery() creates independent tasks at lines 358-383." }, { "name": "Cancellation propagation", "category": "Async control flow", "evidence": "LeaseHeartbeat._run() re-raises CancelledError at lines 331-332; Worker._execute() records cancellation and re-raises at lines 469-475." }, { "name": "Graceful shutdown and draining", "category": "Lifecycle", "evidence": "_drain_for_shutdown() awaits queue.join() and supervisor.wait() inside timeout() at lines 515-523." }, { "name": "Timeout-based cancellation", "category": "Cancellation", "evidence": "asyncio.timeout() bounds attempts and shutdown at lines 458-464 and 515-523; wait_for() bounds queue.get() at lines 449-453." }, { "name": "SIGTERM shutdown", "category": "Signals", "evidence": "SIGTERM and SIGINT are registered with loop.add_signal_handler() at lines 563-568." }, { "name": "Bounded producer-consumer queue", "category": "Concurrency", "evidence": "The queue is bounded at lines 407-408; consumers call task_done() at lines 458-468." } ], "modernityAnalysis": [ { "technique": "Asyncio structured concurrency", "status": "modern", "explanation": "TaskGroup is the structured owner for related poller and consumer tasks. The delivery race remains outside that owner.", "recommendation": "Keep TaskGroup for worker children; put the delivery and lease-wait tasks under a TaskGroup or explicitly await their cancellation. Keep TaskSupervisor only for intentionally detached tasks.", "citations": [ "S7" ] }, { "technique": "Cancellation propagation", "status": "acceptable", "explanation": "The code generally re-raises CancelledError, but cancellation cleanup awaits store.fail(), and race cleanup does not await every cancelled task.", "recommendation": "Preserve propagation while defining whether failure persistence must complete under cancellation; await all race tasks after cancelling them.", "citations": [ "S7" ] }, { "technique": "Graceful shutdown and draining", "status": "outdated", "explanation": "queue.join() tracks task_done() calls but is not a global worker deadline. The timeout covers only _drain_for_shutdown().", "recommendation": "Stop production, shut down the queue, drain or release queued claims, then explicitly cancel and await remaining worker children before TaskGroup exit.", "citations": [ "S7", "WEB-1" ] }, { "technique": "Timeout-based cancellation", "status": "modern", "explanation": "asyncio.timeout() is used for attempt and shutdown scopes; wait_for() is used for periodic queue polling.", "recommendation": "Place persistence inside the attempt deadline when an end-to-end bound is required; use queue shutdown to wake consumers during shutdown.", "citations": [ "S7" ] }, { "technique": "SIGTERM shutdown", "status": "modern", "explanation": "loop.add_signal_handler() schedules the stop callback through the event loop on non-Windows platforms.", "recommendation": "Make the callback initiate producer shutdown and define a second-stage cancellation deadline for owned children.", "citations": [ "citation undiscovered" ] }, { "technique": "Bounded producer-consumer queue", "status": "acceptable", "explanation": "The bounded queue supplies backpressure and task_done() accounting. full() is advisory and the queue is never closed.", "recommendation": "Call Queue.shutdown(False) when production stops and handle QueueShutDown in consumers.", "citations": [ "WEB-1" ] } ], "securityConcerns": [ { "title": "Lease fencing is essential after cancellation or lease loss.", "severity": "high", "codeEvidence": "completed = await self.store.complete(\n claim=claim,", "explanation": "Delivery can race with lease loss, but the supplied JobStore contract does not state that complete() and fail() reject stale owner/token combinations. This is a protocol gap, not a proven vulnerability.", "recommendation": "Require store-side compare-and-set fencing on owner, lease_token, and lease expiry for complete(), fail(), and renew(); treat false results as non-authoritative.", "citations": [ "S7" ], "codeLocation": { "filename": "asyncio-worker.py", "startLine": 452, "endLine": 453 } }, { "title": "Cancellation cleanup can leave claims ambiguous.", "severity": "high", "codeEvidence": "except asyncio.CancelledError:\n await self._record_failure(", "explanation": "A subsequent cancellation can interrupt store.fail(), leaving no recorded outcome while the lease remains active.", "recommendation": "Choose reliable failure recording before propagation, or explicitly fence the claim and rely on release or lease expiry. Test cancellation during store.fail().", "citations": [ "S7" ], "codeLocation": { "filename": "asyncio-worker.py", "startLine": 460, "endLine": 461 } } ], "performanceConcerns": [ { "title": "Race cleanup may leave short-lived orphan tasks.", "severity": "medium", "codeEvidence": "if not task.done():\n task.cancel(\"race cleanup\")", "explanation": "Cancelled tasks are not awaited in the final cleanup path, so cancellation and exception handling can overlap the caller’s return.", "recommendation": "Await all race tasks with gather(return_exceptions=True).", "citations": [ "S7" ], "codeLocation": { "filename": "asyncio-worker.py", "startLine": 346, "endLine": 347 } }, { "title": "Polling adds avoidable wakeups.", "severity": "low", "codeEvidence": "await asyncio.sleep(self.policy.poll_seconds)", "explanation": "The poller sleeps when full or empty, and consumers periodically wake through wait_for().", "recommendation": "Prefer event-driven wakeups where supported; otherwise measure idle wakeups and claim latency.", "citations": [ "WEB-1" ], "codeLocation": { "filename": "asyncio-worker.py", "startLine": 400, "endLine": 400 } } ], "maintainability": { "assessment": "The lifecycle is separated into polling, consumption, heartbeat, race, and signal-handler components, but ownership and shutdown responsibilities cross TaskGroup, TaskSupervisor, and raw tasks.", "strengths": [ "TaskGroup names and owns the main poller and consumers.", "Cancellation is logged and usually propagated.", "Queue task_done() is placed in a consumer finally block." ], "improvements": [ "Document ownership for every created task.", "Centralize shutdown phases: stop production, close queue, drain or release, cancel overdue children, await all children.", "Separate shutdown cancellation from retry policy explicitly." ] }, "modernAlternatives": [ { "current": "queue.full() polling plus open queue during shutdown", "alternative": "Queue.shutdown(False) with QueueShutDown handling", "rationale": "Stops future puts and wakes blocked queue operations while preserving normal draining semantics.", "citations": [ "WEB-1" ] }, { "current": "Independent delivery_task and lease_task", "alternative": "A structured owner for both race participants", "rationale": "Makes cancellation and awaiting obligations explicit.", "citations": [ "S7" ] }, { "current": "TaskGroup exit after drain timeout", "alternative": "Explicit cancellation of worker-owned children before leaving TaskGroup", "rationale": "Prevents TaskGroup exit from extending SIGTERM beyond the configured drain deadline.", "citations": [ "S7" ] } ], "upgradeSuggestions": [ { "priority": "now", "title": "Make shutdown deadline real.", "steps": [ "Stop the poller and call queue.shutdown(False).", "Drain existing items or define release/expiry behavior for queued claims.", "When the deadline expires, explicitly cancel and await the poller and consumers before TaskGroup exit." ], "citations": [ "S7", "WEB-1" ] }, { "priority": "now", "title": "Close the race cleanup gap.", "steps": [ "Cancel both race tasks in every exit path.", "Await both with gather(return_exceptions=True).", "Preserve the primary delivery or lease-loss exception." ], "citations": [ "S7" ] }, { "priority": "next", "title": "Define cancellation and lease outcomes.", "steps": [ "Fence complete(), fail(), and renew() by owner and lease token.", "Decide whether shutdown cancellation retries or releases a claim.", "Test repeated cancellation during failure persistence." ], "citations": [ "S7" ] } ], "educationalExamples": [ { "title": "Await cancelled race tasks", "concept": "Cancellation ownership", "explanation": "Every task created for a race should be cancelled and awaited before the race returns.", "code": "async def cancel_all(tasks: list[asyncio.Task[object]]) -> None:\n for task in tasks:\n if not task.done():\n task.cancel(\"race cleanup\")\n await asyncio.gather(*tasks, return_exceptions=True)\n\nasync def race_cleanup(a: asyncio.Task[object], b: asyncio.Task[object]) -> None:\n await cancel_all([a, b])", "language": "Python", "citations": [ "S7" ] }, { "title": "Gracefully close an asyncio queue", "concept": "Queue shutdown and draining", "explanation": "Non-immediate shutdown rejects new puts while allowing queued items to be processed and joined.", "code": "queue: asyncio.Queue[int] = asyncio.Queue()\n\nasync def producer() -> None:\n for value in range(3):\n await queue.put(value)\n queue.shutdown(False)\n\nasync def consumer() -> None:\n try:\n while True:\n item = await queue.get()\n try:\n print(item)\n finally:\n queue.task_done()\n except asyncio.QueueShutDown:\n return", "language": "Python", "citations": [ "WEB-1" ] } ], "generatedAt": "2026-08-12T14:36:42.202Z", "sources": [ { "title": "Python 3.14 task cancellation guidance", "url": "https://docs.python.org/3.14/library/asyncio-task.html#task-cancellation", "publisher": "Python Software Foundation", "kind": "official-doc", "summary": "Documents cancellation delivery, CancelledError propagation, and cleanup guidance for asyncio tasks.", "relevance": "Defines the cancellation behavior relevant to setup and shutdown paths.", "official": true, "publishedAt": null, "id": "S7" }, { "id": "WEB-1", "title": "Python 3.14 asyncio Queue.shutdown", "url": "https://docs.python.org/3.14/library/asyncio-queue.html#asyncio.Queue.shutdown", "publisher": "docs.python.org", "kind": "official-doc", "summary": "Current evidence retrieved by Luna web research.", "relevance": "Supplemental evidence used to verify current practice.", "official": true, "publishedAt": null } ] }