DataTalksClub / DataTalksClub/website

Add bounded redacted reasons for ECS terminal-count capture failures

Open
#165 16 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

bug human infra operations P1 testing
Dominant language
Python
Stars
0
Forks
0
PR merge metrics
No merged PRs in 30d

Description

Parent/related issues: #102, #160, #164
Normative references: _docs/runbooks/development-release.md, _docs/specs/08-aws-development-terraform.md, _docs/specs/10-verification-strategy.md

Problem

The deployment controller correctly fails closed when the captured ECS service or PRIMARY deployment is not terminal, but the current public-safe error is only web captured terminal counts differ. In the recent exact-SHA run 31857913389, automatic prior capture passed and the pre-mutation deploy checkpoint later failed with the same generic message. The evidence intentionally redacts provider payloads, so an authorized operator cannot tell which allowlisted predicate failed without a separate AWS read-only inventory.

Outcome

Add a deterministic, machine-readable, redacted reason code to the deployment error/evidence for each capture-contract failure. The diagnostic must identify the failed contract category and workload, without exposing provider payloads, exact resource identifiers, account/region details, task definitions, environment values, credentials, headers, cookies, or raw response data.

The existing safety contract remains unchanged: capture is still fail-closed, no retry/eventual-convergence override is added, no fallback/fabricated readiness is allowed, and no AWS operation is introduced.

Scope

  • Define a versioned allowlist of safe capture reason codes covering the existing checks (service identity/lookup, unique PRIMARY, target mismatch, terminal/failed tasks, and each service/PRIMARY running/pending invariant).
  • Preserve the existing human-readable error text where compatibility requires it, while attaching the reason code and workload through the existing redacted deployment-evidence path.
  • Keep diagnostics deterministic when more than one predicate is false (document the precedence or ordered list); never include raw provider dictionaries or unbounded exception text.
  • Add unit/contract tests for every reason-code branch, redaction, schema/version validation, deterministic ordering, and unchanged fail-closed behavior.
  • Update the development-release runbook with the safe diagnostic vocabulary and operator interpretation. No production or AWS configuration changes.

Acceptance criteria

  • Every existing capture_service failure branch emits exactly one allowlisted reason code (or a documented ordered bounded list) and workload; unknown/internal exceptions fail closed without leaking details.
  • The serialized evidence/log projection contains only the approved code, schema version, workload, and existing safe release context; no ARN, account, region, task definition, environment, token, header, cookie, provider payload, exact secret, or raw exception text appears.
  • The four terminal-count predicates are distinguishable without revealing raw counts; tests cover service running/desired, service pending, PRIMARY running/desired, and PRIMARY pending.
  • Existing return status and mutation ordering are unchanged: mismatches remain fatal before release mutation, with no retry, fallback, or eventual-convergence success path.
  • Focused deployment tests, redaction/evidence validation, lint/type/format checks, and the relevant CI contract tests pass under SQLite/ordinary CI.
  • Runbook/spec updates are readable and include a bounded operator example; no HTML/template minification or unrelated route/content changes.
  • Independent tester and PM acceptance bind the exact candidate; the issue is committed only after the normal process gates.

Non-goals

  • No AWS readback, workflow dispatch, deployment rerun, Terraform/IAM/DNS change, or protected data access.
  • No weakening of #102's exact terminal-pair/recovery proof or #160's readiness repair.
  • No raw ECS counts or provider payloads in public logs/artifacts.
  • No changes to application routes, course/content data, email, or frontend.

Follow _docs/PROCESS.md: PM grooming, isolated engineer, independent tester, PM acceptance, local --no-ff merge/push; no pull request.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the existing capture_service failure branches and the referenced development-release runbook and AWS Terraform and verification specs. Define the bounded reason vocabulary and evidence projection there, then use the focused deployment, redaction/evidence, lint/type/format, and CI contract checks named in the issue; done means every branch is covered without changing fail-closed behavior or mutation ordering.

Written by the indexing model from the issue text.

Assessment

Tech stack
aws, python
Domain
devops, infrastructure
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.