Set an explicit gunicorn worker timeout in the website entrypoint

[alexeygrigorev]

Set an explicit gunicorn worker timeout in the website entrypoint

PM-groomed specification

Reviewed 2026-09-02 against origin/main at
2d3c28d1b8d1c2f3844f47f664945b42849d5eb9 (tree
f7af08192c09361a3d064e8f8282b11d568ff211). This is an XS target-native
deployment hardening issue. It is independent of the unrelated dirty local
worktree edits and does not authorize provider or production changes.

Product outcome

The web branch of the website's target-owned entrypoint.sh gives Gunicorn
an explicit 90-second worker timeout. A slow configured outbound call therefore
reaches its own bounded client timeout first and can follow its ordinary safe
failure path instead of being killed at Gunicorn's implicit 30-second default.

The value is evidence-based: the largest currently configured application
outbound timeout is Datamailer's 60 seconds, and the selected 90 seconds adds a
10-second completion/logging margin. This matches the reviewed CMP precedent in
e49c575ce3f567cc14a8f66a89d3ccaca3bfe2f4 without copying CMP files.

Current outbound-timeout inventory

Surface	Configured timeout	Runtime relevance
course_management/datamailer/client.py (DATAMAILER_TIMEOUT_SECONDS, default from website/settings/base.py)	60s	Largest application HTTP client; deployment currently leaves the Datamailer URL/API key disabled. An explicit future environment override above 80s is outside this issue and must be reviewed together with the deployment timeout contract.
content_sync/course_repository_sync.py GitHub codeload fetch	30s	Durable content-sync job/worker, not the Gunicorn web request path; included to show it is below 90s.
courses/validators/custom_url_validators.py injected HEAD/GET transport	3s	Controlled/test transport only; production callers intentionally perform no synchronous user-controlled HTTP.
course_management/observability/cloudwatch_dashboard.py	connect 1s/read 3s	Staff Studio dashboard request; below 90s.
S3 development-content transport	none explicitly configured	Management-command transport; its SDK default is not a reviewed bound and is a separate hardening concern, not a reason to invent a Gunicorn value.

CI, E2E, deployment probes, local Git subprocesses, and test harness timeouts
are tooling/process budgets, not application outbound clients served by this
entrypoint. The website has no Relay client yet; the specifications require
future Relay network work to run only after commit through a durable worker.

Scope

• Add the literal --timeout 90 pair to the Gunicorn command in the web) case
  of target-owned entrypoint.sh.
• Extend core.source_policy.validate_gunicorn_entrypoint so it parses that
  web command and requires exactly one numeric --timeout value of 90; a
  missing, duplicated, malformed, interpolated, or lower timeout fails closed.
  Existing access-log privacy checks remain unchanged.
• Add a focused regression to the existing source-policy test that reads the
  real entrypoint.sh, checks the parser, and mutates/removes the timeout to
  prove rejection. The regression must derive the safety assertion from
  course_management.datamailer.client.DEFAULT_TIMEOUT_SECONDS and assert
  gunicorn_timeout >= DEFAULT_TIMEOUT_SECONDS + 10, so a future change to the
  reviewed Datamailer default cannot silently invalidate the relationship.

Explicit non-goals

• Do not copy CMP's Dockerfile change or courses/tests/test_deploy_config.py;
  the website's deployment contract is entrypoint.sh plus core.source_policy.
• No Dockerfile/CMP source-pin/adoption-manifest change, container command
  redesign, worker/job retry change, or new timeout environment variable.
• No change to Datamailer enablement, client behavior, Relay integration,
  email purpose/sender, S3/CloudWatch/URL-validator timeout policy, business
  semantics, provider/network calls, production data, deployment, commit, or
  push.
• A deploy-time DATAMAILER_TIMEOUT_SECONDS override above 80 seconds is not
  silently accepted by this issue; it requires a separately reviewed change to
  the timeout contract/value.

Dependencies and ownership

This issue is target-owned and independently implementable. #305/#50 own the
Datamailer disablement/retirement and future Relay boundary; they are related
coordination, not prerequisites. No owner decision is required for this
fixed, source-evidenced 90-second hardening.

Acceptance criteria

• entrypoint.sh's web) Gunicorn command contains exactly one literal
  --timeout 90; the worker) command is unchanged and no Dockerfile CMD is
  used as the source of truth.
• validate_gunicorn_entrypoint extracts/parses the web command and fails
  closed for absent, duplicate, malformed, interpolated, or lower timeout
  values while preserving the existing access-log privacy contract.
• The focused regression proves the real command passes, each timeout
  mutation fails, and the parsed 90 seconds is at least the current
  Datamailer default plus the 10-second margin. It also proves the reviewed
  30/3-second application client bounds do not exceed the selected value.
• make migrations-check, the focused Django/source-policy tests, and the
  graph-selected uv-backed quality/type/CI/container checks pass. No
  migration is expected; a discovered model or deployment-schema change stops
  the issue for re-grooming.
• The engineer leaves an uncommitted frozen handoff with exact base/head,
  plan digest, changed-file list, tests, and the timeout inventory. The
  independent tester recomputes the plan and verifies all criteria before PM
  acceptance.

Verification plan and browser evidence

This is an internal entrypoint/source-policy change with no product-page or
rendered error-surface change. The tester runs focused Django and applicable
control-plane/container checks plus the graph-selected backend Playwright tier;
screenshots are not_applicable only when the recomputed graph confirms no
render inputs changed. No browser/provider/network session is needed for the
acceptance claim.

After tester PASS, PM posts product acceptance. Only then may the engineer
create a focused commit with Closes #304; the orchestrator performs the
normal local no-ff merge/push and on-call observes resulting CI. No pull
request, deployment, or live send is part of this issue.

[alexeygrigorev]

Grooming Complete

PM grooming is complete against origin/main @ 2d3c28d1b8d1c2f3844f47f664945b42849d5eb9. #304 is now a groomed P2/infra/operations/testing XS issue and is ready for engineering.

• The target-native contract is a literal --timeout 90 in the web) Gunicorn command of entrypoint.sh; core.source_policy.validate_gunicorn_entrypoint must parse and reject missing, duplicate, malformed, interpolated, or lower values.
• The reviewed outbound timeout inventory is Datamailer 60s (largest), GitHub codeload 30s, controlled URL-validation transport 3s, and CloudWatch connect/read 1/3s. The selected 90s is 60 + 10 and follows CMP commit e49c575ce3f567cc14a8f66a89d3ccaca3bfe2f4.
• The regression derives the Datamailer relationship from DEFAULT_TIMEOUT_SECONDS; S3 has no explicit reviewed bound and remains separate. A deploy-time Datamailer override above 80s requires a separately reviewed timeout-contract change.
• CMP Dockerfile/test copying, provider/Relay/Datamailer behavior, new env settings, business semantics, network/provider operations, deployment, and rendered-page changes are out of scope. Screenshots are not_applicable for this internal source-policy/entrypoint change when the graph confirms no render inputs changed.

The engineer may proceed only with the frozen-base, uncommitted handoff; an independent tester must verify the parser mutations, focused Django/control-plane checks, and the graph-derived plan before PM acceptance. No owner decision or prerequisite is outstanding.

[alexeygrigorev]

Software Engineer Report — #304

Disposition: implementation complete and frozen for independent testing. The candidate adds
the target-native Gunicorn worker timeout and a fail-closed source-policy parser/regression. It
contains no commit, push, merge, deployment, provider call, or product-page change.

Candidate identity

• Worktree: .tmp/issue-304-engineer-20260902-c96578f
• Frozen base/head: c96578f09b1284b3c81a11634bdb81599b409733 / c96578f09b1284b3c81a11634bdb81599b409733
• Worktree status: exactly these three tracked paths are modified; no other tracked paths changed
• Candidate diff SHA-256 (git diff --binary HEAD): 6d1ceba63846d28532fa77365717df4f41a4817d863e792676fb76a7c2f1ef29
• Verification plan: .tmp/issue-304-verification/verification-plan.json
• Verification plan SHA-256: b2438dce132f16c26f96b8e763437cb3fa2f1ac45707a8689b866440b6967522
• Selection artifact: .tmp/issue-304-verification/ci-selection.json
• Selection SHA-256: c0db2c2fd86a50031d06dde5ad3f7e08316b6e06ff3652885b3316123c919ad8
• Plan source-tree manifest SHA-256: 3f7849943be4a04f0b37c8f6cb731bd0fafd6d8469122838bc0f752e7c5e4924
• Plan source-tree OID: 6df97a33876e513e8652172da2785cf754ba27f6
• Ownership graph SHA-256: 05ffeee99244c9becd5e98e40be08188f1c5e2a61204daece984c3beb1d1bce6
• Policy version: 5

Changed paths

• entrypoint.sh
• core/source_policy.py
• core/tests/test_development_seo_source.py

The web) command now contains exactly one literal --timeout 90; the worker) command and
Dockerfile are unchanged.

parse_gunicorn_timeout extracts the one target-native exec uv run --no-sync gunicorn command
inside web), rejects missing/duplicate/malformed/--timeout=/quoted/interpolated/lower/higher
values, and returns the parsed integer. validate_gunicorn_entrypoint retains the existing
access-log privacy checks and invokes this parser.

The focused regression reads the real entrypoint, exercises missing, duplicate, malformed,
interpolated, lower, and higher mutations, and derives the safety relationship from
course_management.datamailer.client.DEFAULT_TIMEOUT_SECONDS: the selected 90 seconds is at least
60 + 10; reviewed codeload and URL-validation bounds are 30 and 3 seconds and are both below
the selected value. No deploy-time override or provider behavior was changed.

Versioned plan and four dispositions

The plan is valid and binds the exact candidate worktree at profile full, reason
unknown_impact, browser profile smoke, with entrypoint.sh recorded as an unmapped path.
Render impact is false and the plan has no required screenshot captures.

• rerun: selector, evidence_validation, quality, django, playwright, and container
  (always_fresh_control_plane or fresh_full_regression as recorded in the plan)
• reused: none
• skipped: none in the generated plan
• not_applicable: compatibility (outside_impact_closure), content_invariants
  (outside_large_content_closure), and screenshots
  (render_inputs_unchanged_without_reusable_visual)

The independent tester must recompute this plan from the frozen base/head. The smoke-browser
component was deliberately not started in this engineer lane; no browser or screenshot artifact
was produced. The tester owns the required graph-selected smoke verification. Screenshots remain
not_applicable only because the graph proves no render inputs changed.

Passing evidence

• DJANGO_SETTINGS_MODULE=website.settings.test uv run --frozen pytest core/tests/test_development_seo_source.py -q — 12 passed, 30 subtests passed
• DJANGO_SETTINGS_MODULE=website.settings.test uv run --frozen python manage.py test core.tests.test_development_seo_source --noinput — 12 passed
• uv run --frozen ruff check core/source_policy.py core/tests/test_development_seo_source.py — passed
• uv run --frozen ruff format --check core/source_policy.py core/tests/test_development_seo_source.py — passed
• sh -n entrypoint.sh and git diff --check — passed
• make lint — passed
• make format-check — passed (653 files already formatted)
• make typecheck — passed (472 source files)
• make migrations-check — passed (no changes detected)
• make database-portability-check — passed
• make django-check — passed (OpenAPI, management parity, Django system check)
• make deployment-check — passed
• make security-check — passed
• make verification-container VERIFY_PLAN=.tmp/issue-304-verification/verification-plan.json VERIFY_EVIDENCE_DIR=.tmp/issue-304-verification/evidence — passed (13 assertions); evidence SHA-256 06482794762051fab7b5234da795b82a4c5a3dc4deca49c6196c9fc2dac29dde
• Direct parser matrix — valid source returned 90; missing, duplicate, --timeout=90,
  interpolation, quoted/suffixed values, lower 89, and higher 91 were rejected.

Logs and artifacts are retained below .tmp/issue-304-verification/:
test-ci.log, test-django-full.log, verification-quality.log, security-check.log, and
evidence/container-check.json.

Inherited/current-base failures

• make test-ci — 616 passed, 1 failed. The unchanged
  ci/tests/test_content_update.py::test_source_specific_counts_are_safe_aggregates expects
  Podwiki graph_links=13006, graph_nodes=1072, and search_documents=2998; the current
  checked source reports 12987, 1070, and 2996 (Wiki pages remain 282). The candidate does
  not change content projections or this test.
• make verification-quality / terminology-check — fails on 102 unclassified legacy-term
  findings in unchanged _docs/runbooks/production-hosting-and-dns-migration.md; the aggregate
  stops at this first target. Full output is in verification-quality.log.
• make test-django-full — starts 2,598 tests but fails on the same 102-finding terminology
  inventory assertion, followed by the known Python 3.13 TypeError: cannot pickle 'traceback' object parallel failure path. No failure points to the changed files.

No issue-specific criterion is marked accepted by this engineer report. The worktree is frozen,
uncommitted, and ready for independent tester review and the separate PM gate.

[alexeygrigorev]

Tester QA Review — #304

Verdict: HOLD (issue-specific checks pass; required full/control-plane gates are red and the required smoke-browser run could not be started while another session owned the exclusive browser slot).

Candidate and independent plan

• Candidate worktree: .tmp/issue-304-engineer-20260902-c96578f
• Independent tester worktree: .tmp/verification/issue-304-tester-20260902
• Frozen base/head: c96578f09b1284b3c81a11634bdb81599b409733 / c96578f09b1284b3c81a11634bdb81599b409733
• Candidate diff SHA-256 (git diff --binary HEAD): 6d1ceba63846d28532fa77365717df4f41a4817d863e792676fb76a7c2f1ef29
• Tester worktree diff SHA-256: 6d1ceba63846d28532fa77365717df4f41a4817d863e792676fb76a7c2f1ef29
• Tester plan: .tmp/issue-304-tester-verification/verification-plan.json
• Tester plan SHA-256: d5b17e8728fe121519cde137c959b1edf8b0cc0cadd39e49baee4a6b4f02ddae
• Engineer plan SHA-256: b2438dce132f16c26f96b8e763437cb3fa2f1ac45707a8689b866440b6967522
• Plan comparison: exact match after removing only created_at; normalized SHA-256 483f80c0cf7a2b3e80d7269a1032774ce814bcbefd0a9b214f84ce4223236f1c. The only drift is the expected plan-generation timestamp.
• Source-tree manifest SHA-256: 3f7849943be4a04f0b37c8f6cb731bd0fafd6d8469122838bc0f752e7c5e4924
• Source-tree OID: 6df97a33876e513e8652172da2785cf754ba27f6
• Graph SHA-256: 05ffeee99244c9becd5e98e40be08188f1c5e2a61204daece984c3beb1d1bce6
• Policy version: 5
• Selection artifact SHA-256: c0db2c2fd86a50031d06dde5ad3f7e08316b6e06ff3652885b3316123c919ad8

The independent plan selects profile=full, reason=unknown_impact, and browser_profile=smoke with render.impact=false. It requires fresh selector, evidence-validation/CI, quality, Django, Playwright smoke, and container components. Compatibility, content invariants, and screenshots are not_applicable under the plan; no render inputs changed.

Acceptance criteria

1. Web timeout and scope — PASS. entrypoint.sh has exactly one literal --timeout 90 in web). The worker) command is unchanged, and the diff contains no Dockerfile, CMP, AWS/provider, or product-page changes. Changed paths are exactly core/source_policy.py, core/tests/test_development_seo_source.py, and entrypoint.sh.
2. Fail-closed parser — PASS. Independent parser matrix: valid 90 accepted; missing, duplicate, --timeout=90, missing value, interpolated, quoted, suffixed, lower 89, and higher 91 all rejected with SourcePolicyError. Existing access-log validation remains exercised by the focused suite.
3. Timeout relationship — PASS. Independent runtime values: Gunicorn 90, Datamailer default 60.0, codeload 30, URL validation 3; 90 >= 60 + 10, 90 >= 30, and 90 >= 3.
4. Required gates — HOLD/FAIL. Focused source-policy tests and individual controls pass, but full graph-selected CI and Django gates reproduce current-base failures; Playwright smoke remains unexecuted because active foreign Playwright sessions occupy the exclusive browser slot.
5. Frozen handoff and plan — PASS. Candidate remained uncommitted and unchanged; the independent tester recomputed the exact plan and recorded separate artifacts below .tmp/issue-304-tester-verification/.

Fresh evidence

• DJANGO_SETTINGS_MODULE=website.settings.test uv run --frozen pytest core/tests/test_development_seo_source.py -q: 12 passed, 30 subtests passed. Log SHA-256 c664a09e6daf8be2dac636ce7cd2db76725527bf2a1802782ede34db5df81a05.
• DJANGO_SETTINGS_MODULE=website.settings.test uv run --frozen python manage.py test core.tests.test_development_seo_source --noinput: 12 tests, OK. Log SHA-256 670897aff283b5105784265330efbc846707ec01d5f6fe99f17d53a668a10886.
• make migrations-check: exit 0.
• make database-portability-check: exit 0.
• make security-check: exit 0.
• make lint: exit 0.
• make format-check: exit 0.
• make typecheck: exit 0.
• make django-check: exit 0.
• make deployment-check: exit 0.
• make verification-container VERIFY_CONTAINER_OUTPUT=.tmp/issue-304-tester-verification/evidence/container-check.json: exit 0; 13 assertions, status pass. Artifact SHA-256 06482794762051fab7b5234da795b82a4c5a3dc4deca49c6196c9fc2dac29dde.
• make test-ci: 616 passed, 1 failed. The unchanged ci/tests/test_content_update.py::test_source_specific_counts_are_safe_aggregates expects Podwiki graph_links=13006, graph_nodes=1072, search_documents=2998; current source reports 12987, 1070, 2996 (wiki pages 282). Log SHA-256 49f3ba6ebaf9c782f0c75f26e986216b28b69b6fb1aa2c1177cd16a1df11303a.
• uv run --frozen python -m ci.quality_contract --repository .: exit 2 at terminology-check, with 102 unclassified legacy-term findings in unchanged _docs/runbooks/production-hosting-and-dns-migration.md. Log SHA-256 4bb6221d1a9e1a9624f16fa8155d77d27eae1244b3e6b25240dc0c5cf6ade35b.
• make test-django-full: 2,598 tests discovered, fails on the same 102 terminology findings and the known Python 3.13 traceback-pickling failure path. Log SHA-256 7beda52a2562ec8ee3a02a7deaee01efb74971c4cc1eb0b82e829ad37bd27486.
• make test-playwright-smoke: not launched; active unrelated/foreign Playwright sessions were observed and the browser slot is exclusive. No browser evidence is claimed.

Artifact paths

• Plan: .tmp/issue-304-tester-verification/verification-plan.json
• Selection: .tmp/issue-304-tester-verification/ci-selection.json
• Parser matrix: .tmp/issue-304-tester-verification/parser-matrix.log
• Timeout contract: .tmp/issue-304-tester-verification/timeout-contract.log
• Container evidence: .tmp/issue-304-tester-verification/evidence/container-check.json
• Individual control logs and full-suite logs: .tmp/issue-304-tester-verification/

The candidate has no issue-specific defect from this review. PM acceptance must wait until the current-base Podwiki/terminology failures are repaired or explicitly resolved and an independent smoke-browser run completes without contention; no merge, commit, push, or deployment is authorized by this report.

[alexeygrigorev]

Product Acceptance — #304

Verdict: HOLD / NOT ACCEPTED.

The issue-specific evidence is sound: web) contains exactly one literal --timeout 90; the fail-closed parser matrix and timeout relationship pass. The implementation scope remains the two source files entrypoint.sh and core/source_policy.py, plus their regression test; there are no CMP, Docker/provider/AWS, business/product, or rendered-page changes.

PM acceptance is withheld because the shared baseline is not green and the independent browser disposition is incomplete:

• make test-ci fails the unchanged Podwiki aggregate-count assertion (616 passed, 1 failed).
• Quality/full Django fail on the unchanged 102-item terminology inventory (with the known traceback-pickling failure path).
• The graph-selected make test-playwright-smoke was not run because the exclusive browser slot was occupied.

These gates cannot be waived as “baseline” for acceptance. No commit, merge, push, or deployment is authorized.

Required order: recover the shared baseline, rebase the frozen candidate onto that baseline and regenerate its plan/digests; then the independent tester reruns the graph-selected gates and records the smoke-browser result/disposition and posts PASS; then PM reviews and posts acceptance; only afterward may the engineer create the focused commit and the orchestrator locally merge/push.

[alexeygrigorev]

Product Acceptance

HOLD / NOT ACCEPTED. The fresh candidate’s scope and all listed broad gates are otherwise green, but the independent tester envelope is not internally terminal-green.

Verified:

• base/head: 8422a7ab841af845f339371ee3c1f69b7021ca9f;
• exactly entrypoint.sh, core/source_policy.py, and core/tests/test_development_seo_source.py;
• canonical diff SHA-256: 6d1ceba63846d28532fa77365717df4f41a4817d863e792676fb76a7c2f1ef29;
• worker command unchanged; no Dockerfile, CMP, adoption, provider, or deployment/config drift;
• plan/selection alignment and the reported focused, CI, Django, container, and 30-test smoke results match the candidate.

The blocker is the referenced parser evidence: .tmp/issue-304-tester-20260903/evidence/parser-matrix.log (SHA-256 030e5a3d1a59a925da2b1525e4a9b3b82c1ee1520bf9f6c2c4fc69934d547c4e) ends with second_gunicorn_line: ACCEPTED (unexpected) and exit_status=1. That contradicts the tester report’s PASS, its claim that the parser matrix passed, and the fail-closed parser acceptance criterion. The report does not identify whether this probe is an intentionally out-of-scope command or a malformed web) command.

Re-entry requires the tester/engineer to identify and classify that exact mutation. If it is within the web) command or otherwise in scope, harden the parser/regression and rerun the required gates with a fresh diff/envelope. If it is intentionally outside scope, update the matrix/report with the exact mutation and rationale, rerun the matrix to a terminal-green result, and obtain a corrected tester-final report. No timeout contract, Dockerfile/CMP/config, or unrelated behavior should be added.

No commit, merge, push, deployment, or issue closure is authorized from this PM review.

[alexeygrigorev]

Product Acceptance

PM ACCEPT. The corrected #304 candidate resolves the prior parser-matrix blocker and satisfies the groomed timeout contract.

Verified candidate:

• frozen base/head: 8422a7ab841af845f339371ee3c1f69b7021ca9f;
• exactly three modified paths: entrypoint.sh, core/source_policy.py, and core/tests/test_development_seo_source.py;
• canonical diff SHA-256: ad4b4d1f4484c8e3fe6d9894c768a4ea5ab94875d60c2f800c75aff6085707fc;
• exactly one literal --timeout 90 in web); worker) is byte-for-byte unchanged;
• no Dockerfile, CMP, adoption, provider, or unrelated deployment/configuration path changed.

The corrected parser now rejects the previously accepted second executable Gunicorn line. The rerun parser matrix is terminal green (exit 0), including missing, duplicate, equals-form, missing-value, interpolated, quoted, signed/leading-zero/suffixed, lower/higher, extra web/outside-web, and second-line mutations. The timeout relationship remains 90 >= 60 + 10, with reviewed codeload and URL-validation bounds 30 and 3.

The independent tester recomputed the full/unknown-impact plan and matched the engineer rerun plan after timestamp normalization; ci.verification validate-plan passed. Fresh required evidence is green: 12 focused tests / 31 subtests, 617 CI and quality checks, 2,615 Django with 9 skipped, container status pass with 13 assertions, and 30/30 Playwright smoke across desktop/mobile and no-JavaScript scenarios. Render impact is false, so screenshots are correctly not applicable.

CMP provenance remains scoped to reviewed commit e49c575ce3f567cc14a8f66a89d3ccaca3bfe2f4; the target-native implementation stays in entrypoint.sh and core.source_policy, with the website CMP pin unchanged.

This is PM acceptance only. #304 remains open until the engineer creates the focused Closes #304 commit, the orchestrator performs the prescribed merge/push, and on-call reports green post-push CI/deployment.