Choose the Support bundle generation and download contract

[frankieramirez]

Question

Given the settled data contract, what authenticated API, generation lifecycle, concurrency behavior, temporary-file ownership, cleanup guarantees, filename behavior, and failure responses should produce and download a Support bundle?

Resolve the boundary between the FastAPI system domain and the legacy generator, including whether that generator can be hardened or should be replaced.

Settled input

Define the disclosure-safe Support bundle data contract prohibits the legacy collect-and-redact data path. The generator must produce exactly README.txt, manifest.json, and diagnostics.json from closed, versioned projections; it may reuse isolated safe normalization helpers but may not copy the database, config, logs, environment, paths, or arbitrary error text.

[frankieramirez]

Resolution

The Support bundle is generated once, in memory, inside the authenticated download request. The modern path has no server-side artifact lifecycle: no persistent file, temporary directory, cache, job record, polling endpoint, or cleanup task.

HTTP contract

POST /api/system/support-bundle is the only endpoint.

• Authentication: the existing UI session via require_session; no API-key or unauthenticated variant.
• CSRF: the existing global X-Requested-With: ComicarrFrontend requirement applies.
• Request body and query parameters: none. The caller cannot select paths, members, verbosity, format, destination, or a legacy mode.
• Success: 200 application/zip with the complete ZIP bytes in the response.
• Content-Disposition: fixed attachment filename comicarr-support-bundle-v1.zip; it never contains a branch, version, timestamp, host, user, path, or source-derived value.
• Caching: Cache-Control: no-store, private, Pragma: no-cache; no ETag or Last-Modified.
• Response metadata: X-Comicarr-Support-Bundle-Contract: 1 and X-Comicarr-Support-Bundle-Status: complete|partial. A partial bundle is still a complete representation and returns 200; its fixed source-unavailability reasons live in manifest.json.
• The response uses in-memory bytes through FastAPI/Starlette Response, not FileResponse or a stream. FastAPI explicitly supports byte content in a direct Response: https://fastapi.tiangolo.com/advanced/custom-response/

POST is deliberate: generation is an authenticated, resource-consuming action that must not be prefetched or cached as a safe read. The frontend performs a same-origin credentialed fetch, validates the response, converts it to a Blob, triggers the fixed filename download, and revokes the object URL. The existing JSON-only apiRequest is not used for the binary success path.

Every retry generates a fresh snapshot. There is no retained artifact to resume, retrieve, enumerate, or delete, and retrying after an ambiguous network failure is safe.

Deep module and seam

Create a dedicated comicarr.app.system.support_bundle module. Its external interface is one operation:

generate_support_bundle(ctx) -> SupportBundleArtifact

SupportBundleArtifact is immutable and exposes only:

• content: bytes
• contract_version: int
• filename: str
• status: complete|partial

The interface invariants are the entire settled data contract: fixed three-member archive, closed schemas, fixed ordering and ZIP metadata policy, source-resolution from the active AppContext, bounded local reads, final validation, and no source-derived fallback. Callers never see collectors, paths, database rows, raw configuration, log input, archive writers, or validators.

The router is a thin HTTP adapter: inject AppContext, call the module, map typed module errors, and set fixed response headers. Tests exercise generation through the same single interface. Collector and clock seams stay internal to the module; they are not exposed as public adapters.

Dependencies are local or local-substitutable: the active context/configuration and active database engine. Generation performs no network request and invokes no subprocess. It never consults the rejected carePackage collector.

Generation lifecycle

1. The module acquires a private, process-wide non-blocking single-flight lock.
2. Capture one UTC generation time and one active-runtime snapshot authority.
3. Collect only the versioned, bounded projections settled by the data contract. Database facts come from the active engine in a read transaction; custom config/data/log/database paths are inputs only and never emitted.
4. Normalize into closed manifest.json and diagnostics.json objects.
5. Validate every field, enum, bound, source status, and exclusion before serialization.
6. Serialize deterministically, assemble README.txt, manifest.json, and diagnostics.json into an in-memory ZIP in fixed order, and normalize ZIP member metadata.
7. Re-open and validate the final ZIP bytes: exact members, schemas, member digests/sizes, total bounds, and disclosure guards.
8. Return immutable bytes and release the lock in finally.

The endpoint is synchronous (def), allowing FastAPI/Starlette to run the blocking local reads and ZIP work in its managed thread pool while the HTTP request remains the owner. Starlette documents that synchronous endpoints run in its thread pool: https://www.starlette.io/threadpool/

If the client disconnects, the bounded generation is allowed to finish in that request worker; the result is discarded and the lock releases. Because all state is memory-only, there is no partial artifact or cleanup race. Normal server shutdown treats the active HTTP request as the owner; hard process exit simply discards memory.

Concurrency and bounds

Only one generation may run per process. A simultaneous request fails immediately; it never waits and never shares another caller's bytes.

Generation has no unbounded collector:

• no network or subprocess work;
• a fixed number of aggregate database queries;
• no row export;
• log-derived counts scan at most the configured tail byte limit of the active log and never rotations;
• fixed collection cardinalities and closed enums;
• README.txt maximum 16 KiB;
• each JSON member maximum 256 KiB;
• total uncompressed members maximum 512 KiB;
• final ZIP maximum 512 KiB.

Cross-process coordination is unnecessary because bytes and locks are not shared; each process reads safe projections and owns its own response. The supported Comicarr deployment remains free to use one process.

Typed failures

The module exposes typed failures, never raw exception text or source values. The router maps them to fixed JSON bodies:

• Concurrent request: 409, code support_bundle_in_progress, retryable true, with Retry-After: 2.
• Runtime is shutting down or mandatory source authority is unavailable: 503, code support_bundle_unavailable, retryable true.
• Closed-schema, member, size, or disclosure validation failure: 500, code support_bundle_validation_failed, retryable false.
• Unexpected generation failure: 500, code support_bundle_generation_failed, retryable true.

The body shape is {"detail": "<fixed safe sentence>", "code": "<fixed enum>", "retryable": <bool>}. Existing auth and CSRF failures remain 401 and 403.

An unavailable optional collector is not an HTTP failure: it becomes a fixed omission reason and produces a valid partial bundle. No error path returns a partially assembled ZIP.

Server logging records only fixed outcome code, contract version, complete/partial status, duration bucket, output-size bucket, and exception class where necessary. It never logs the artifact bytes, username, path, source value, request headers/cookies, or raw exception message.

Legacy boundary

The modern endpoint and module never instantiate, import, or call the legacy carePackage class. That class's collect-and-redact model is incompatible with the settled data contract.

CLI maintenance-mode redesign is already out of scope, so the legacy class may remain isolated for that existing path until a separate effort removes or replaces it. Safe generic normalization helpers may be shared only when they accept already-allowlisted primitives; none of the legacy broad collectors, filenames, temp paths, redaction inventory, or ZIP publication behavior crosses the new module seam.

Rejected alternatives

• GET: easier browser navigation, but vulnerable to prefetching/caching semantics for resource-consuming generation.
• Generate then poll/download: creates identifiers, persistence, expiry, authorization, cleanup, and stale-artifact states with no benefit for a bounded sub-512-KiB projection.
• FileResponse or streaming ZIP: introduces filesystem ownership or mid-stream failure after headers; the bounded artifact fits safely in memory.
• Harden the legacy generator: its broad collector is the wrong seam; removing prohibited data would replace its implementation in all but name while retaining unsafe lifecycle assumptions.
• Caller-selected detail levels: multiplies disclosure contracts and test surfaces; version 1 has one reviewed shape.