Skip to content

Document get_deployment_payload / delete_deployment_payload response contracts #600

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kriszyp wants to merge 1 commit into
base: main
Choose a base branch
from
+15 −1
Open

Document get_deployment_payload / delete_deployment_payload response contracts #600

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 15 additions & 1 deletion reference/operations-api/operations.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -697,9 +697,11 @@ Returns the raw tarball for a deployment. Useful for inspecting or re-deploying
}
```

The response is the raw tarball bytes (`Content-Type: application/octet-stream`, with a `Content-Disposition` download filename) - not JSON and not base64-encoded, so payloads of any size stream without inflation. Returns `404` if the deployment does not exist or its payload has already been reclaimed (by payload retention or `delete_deployment_payload`).

@gemini-code-assist gemini-code-assist Bot Jul 22, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For consistency with the rest of the document, use an em-dash (—) instead of a hyphen (-) to separate the clauses.

Suggested change
The response is the raw tarball bytes (`Content-Type: application/octet-stream`, with a `Content-Disposition` download filename) - not JSON and not base64-encoded, so payloads of any size stream without inflation. Returns `404` if the deployment does not exist or its payload has already been reclaimed (by payload retention or `delete_deployment_payload`).
The response is the raw tarball bytes (`Content-Type: application/octet-stream`, with a `Content-Disposition` download filename) — not JSON and not base64-encoded, so payloads of any size stream without inflation. Returns `404` if the deployment does not exist or its payload has already been reclaimed (by payload retention or `delete_deployment_payload`).

@cb1kenobi cb1kenobi Jul 23, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Medium: get_deployment_payload's super_user requirement is stricter than delete_deployment_payload's, but the doc doesn't say so

Both ops are registered with requires_su: true in operation_authorization.ts, and that map has a Gate-2 bypass: an op that is SU-only by default can still be granted to a non-super_user role via that role's operations allowlist. delete_deployment_payload (and nearly every other super_user op in this table) goes through that path unmodified. get_deployment_payload is the exception — harper#1898 adds a requireSuperUser() check directly inside handleGetDeploymentPayload, so it 403s even for a role that explicitly lists it in operations (matching the secrets-store ops, per that PR's own comment). An admin who grants get_deployment_payload the same way they successfully granted delete_deployment_payload will hit an unexplained 403.

This PR's stated goal is documenting "previously-unspecified behavioral contracts" for these two ops, so this asymmetry belongs here rather than staying implicit in the super_user table label both ops share.

Suggested fix: append a sentence to this paragraph, e.g. "Unlike most other super_user operations, this check is enforced directly in the handler and cannot be satisfied by granting the operation through a role's operations allowlist — only an actual super_user role can call it."

—
Generated by Barber AI


### `delete_deployment_payload`

Removes the tarball blob from a deployment record. The deployment record itself is retained; only the binary payload is deleted. Use this to reclaim storage after confirming a deployment is stable.
Removes the tarball blob from a deployment record. The deployment record itself is retained; only the binary payload is deleted. Use this to reclaim storage after confirming a deployment is stable. The deletion replicates, so one call frees the payload's storage on every node in the cluster.

```json
{
Expand All @@ -708,6 +710,18 @@ Removes the tarball blob from a deployment record. The deployment record itself
}
```

Response:

```json
{
"message": "Deleted payload for deployment 'a3f8c2d1...'",
"deployment_id": "a3f8c2d1...",
"freed_bytes": 52428800
}
```

The deployment must be in a terminal status (`success`, `failed`, or `rolled_back`); deleting the payload of an in-progress deployment fails with `409`, since its payload may still be replicating to peers. Deleting an already-reclaimed payload succeeds with `freed_bytes: 0` (the operation is idempotent). A `payload_dropped` entry recording the deleting user is appended to the deployment's `event_log`.

### `add_ssh_key`

Adds an SSH key (must be ed25519) for authenticating deployments from private repositories.
Expand Down