Files
canina/backend/src/orchestration-worker/worker-registration.md
T

2.7 KiB

Prepare worker startup boundary

Parent integration API (AppModule remains untouched here):

import { registerPrepareWorker } from './orchestration-worker/worker-registration';
// In AppModule imports:
...registerPrepareWorker(),

Only literal PREPARE_WORKER_ENABLED=true registers the transport. Missing or other values register nothing (404 routes), do not read configuration, and do not instantiate Prisma. Enabled malformed/missing configuration throws synchronously before Nest starts, with one generic error and no secret logging.

The fixed mount /run/secrets/prepare_worker_grants contains JSON with exactly grants, workerIds, stageCiIds, artifactBaseUrl. Each grant contains exactly id, role (WORKFLOW_WORKER or STAGE_CI), credentialSha256 (64 lowercase hexadecimal characters; never the bearer credential). Require at least one worker and CI, distinct role-bound IDs/digests, exact allowlist coverage, and at most 32 grants. No enabled flag, directory, token, user, or request-derived fields accepted in JSON.

artifactBaseUrl must be explicitly reviewed by the operator: canonical public-DNS HTTPS origin plus /internal/prepare-worker/artifacts, no credentials, IP, alternate port, query or fragment. Shared transport validation is authoritative. This loader does not fetch the URL or perform DNS resolution. Directory is always /var/lib/canina/prepare-artifacts.

Descriptor-relative Linux /proc/self/fd traversal refuses symlink directories/files, nonregular files, hardlinks, files over 16 KiB, group/world writable files/directories, and foreign-owned files (root/runtime UID only). Reads are bounded even on concurrent growth. Configuration is frozen recursively and transport takes its own frozen snapshot. Trusted operator owns mounted configuration; edits require restart and review.

compose.prepare-worker.fragment.yml is an extension fragment, not a deployable compose file. Parent must merge its x-prepare-worker-backend into the correct reviewed Stage backend service and merge secrets. Compose bind-backed secrets may ignore mode/UID declarations: provision actual host grants file as root/runtime-owned mode 0400 and artifact directory runtime-owned mode 0700 first. No mounts or live configuration are created by this change.

Tests deliberately use the fixed /run/secrets path. Run ONLY in a fresh disposable container with source and donor dependencies read-only, private dependency copy, and private prisma generate; never on a live service. Tests need a disposable Linux root filesystem and do not require DB credentials. Registration test uses a real Nest HTTP listener to prove disabled routes are absent. Existing DB-backed transport tracer remains separately gated by WORKER_TRANSPORT_DB=1.