devcontainer-builder (0.1.0)

400 always means the request itself was unusable - nothing was ever attempted, or a required piece of configuration to even attempt it (a registry, a host key pin) was missing:

• {"error": "invalid JSON body"} - the request body isn't valid JSON at all.
• {"error": "missing or invalid fields: repository (required); branch, image.{registry,name,tag}, gitCredentials.{username,token}, registryCredentials.{registry,username,password}, platforms, buildOptions.{noCache,cacheFrom,cacheTo,mode} (all optional)"} - the parsed body isn't a JSON object, or fails the shape check.
• {"error": "unable to parse git repository URL: <repository>"} - repository doesn't match any accepted URL form.
• {"error": "repository URL scheme \"<scheme>://\" is not allowed: ..."} - repository uses a scheme other than https:///ssh:///SCP-style (git:///http:// need the server's allowInsecureGitProtocols).
• {"error": "repository URL must not contain credentials (user:token@...) - pass them in gitCredentials instead"}.
• {"error": "buildOptions.cacheTo: cache type \"<type>\" is not allowed (allowed: registry, gha, inline)"} - likewise for cacheFrom.
• {"error": "unable to derive an image name from repository path ...: provide image.name"}.
• {"error": "no registry resolved for repository <repository>: provide image.registry or configure a matching registry mapping rule"} - no image.registry given and no registry mapping rule matched.
• {"error": "SSH host key policy is \"pinned\" but no pinned key configured for host <host>"} - the resolved SSH credential has no pinnedHostKey under sshHostKeyPolicy: pinned.

429 means the instance is already running build.maxConcurrent builds; retry after Retry-After seconds.

500 always means a real external command was actually run and failed - the request was well-formed, but cloning or building it didn't work: {"error": "<command> <args...> exited with code <n>", "logId": "<id>"}. The body is the real command and exit code, not the real error text (a registry's real 401 body, git's real "Permission denied") - fetch that via GET /logs/{logId} (also returned on success, as gitCloneLogId/imageBuildLogId).

Checks whether a previously-built image still exists in its registry, by talking to the registry's own HTTP API V2 directly (bearer-token challenge/exchange, then a manifest lookup).

Best-effort deletion of a previously-built image's manifest. Not all registries support this via the standard API (Docker Hub notably doesn't) - see 0008 for why that's treated as a normal outcome, not an error.

Reads a built image's devcontainer.metadata label straight from its registry (no pull, no Docker daemon) and returns it merged the way the Dev Containers CLI merges it, plus ready-to-run lifecycle scripts and merged VS Code customizations - what a Coder template needs to run postCreateCommand & co. and pre-install extensions. Pass registry/name/tag exactly as POST /build returned them. See 0011.

Kubernetes startupProbe. Always 200 {"status":"started"} once the process is listening - checks nothing beyond that. A distinct route from GET /health/live even though the check is identical today (this service has no separate async startup phase), so a startupProbe (a generous total budget, to tolerate slow pod scheduling/image pulls) can be tuned independently of livenessProbe (tight, once actually started).

Liveness probe. Always 200 {"status":"ok"} once the process is listening - checks nothing beyond that.

Readiness probe. 200 when BUILDKIT_ENDPOINT is configured, 503 when it isn't.

Prometheus text-format metrics (Content-Type: text/plain), for a ServiceMonitor/node-exporter-style scrape. Node.js process/runtime defaults (prom-client's collectDefaultMetrics) plus:

• devcontainer_builder_builds_total (counter, label status: success|failure|invalid_request|busy) - every POST /build attempt.
• devcontainer_builder_build_duration_seconds (histogram, label status) - real build wall-clock time, bucketed toward minutes (not the sub-second defaults), since a build is a clone + image build + push.
• devcontainer_builder_image_checks_total (counter, label result: exists|absent|error) - every GET /image call.
• devcontainer_builder_image_deletes_total (counter, label result: deleted|unsupported|error) - every DELETE /image call.
• devcontainer_builder_devcontainer_lookups_total (counter, label result: found|absent|no_metadata|error) - every GET /devcontainer call.

Full captured stdout+stderr of one git clone or one devcontainer build --push (including remote builder setup) - the id comes from POST /build's response (gitCloneLogId/imageBuildLogId on success, logId on a 500).

Not persisted beyond this pod's own lifetime (backed by the same ephemeral scratch space as an in-progress build, not a volume) and rotated: only the most recent commandLogRetention (default 10) files are kept per kind (git/docker) - an id from an old build may already be gone.

Deletes one captured command-output log ahead of its normal rotation. Idempotent - deleting an already-gone id also 404s.