Uh oh!
There was an error while loading. Please reload this page.
Document get_deployment_payload / delete_deployment_payload response contracts - #600
Conversation
…contracts Companion to HarperFast/harper#1898 (which implements the two operations — they were documented but returned "Operation not found", harper#1893): raw-bytes response for get_deployment_payload, and the terminal-status requirement, idempotency, response shape, and audit event for delete_deployment_payload. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
There was a problem hiding this comment.
Code Review
This pull request updates the API documentation in reference/operations-api/operations.md to detail the response format for retrieving a deployment's raw tarball and to expand on the behavior, constraints, and response schema of the delete_deployment_payload endpoint. The review feedback suggests a minor formatting improvement to use an em-dash instead of a hyphen for consistency.
| } | ||
| ``` | ||
| 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`). |
There was a problem hiding this comment.
For consistency with the rest of the document, use an em-dash (—) instead of a hyphen (-) to separate the clauses.
| 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`). |
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL:https://preview.harper-documentation.harperfabric.com/pr-600 This preview will update automatically when you push new commits. |
Uh oh!
There was an error while loading. Please reload this page.
Ethan-Arrowood
left a comment
There was a problem hiding this comment.
LGTM — with harper#1898 merged, I verified the documented response contracts field-for-field against the handler source (field names, status values, error codes, the octet-stream/Content-Disposition contract, cluster-wide reclaim, idempotency, and the audit note) — all accurate.
One net-new nit to fold in: the idempotent-case message differs from the example shown, worth aligning. And cb1kenobi's point is real — get_deployment_payload self-enforces super_user (non-delegable) while delete_deployment_payload doesn't — worth documenting that asymmetry.
sent with Claude Opus 4.8
get_deployment_payload checks requireSuperUser() directly in the handler, unlike delete_deployment_payload and nearly every other super_user op, which can be granted to a non-super_user role via that role's operations allowlist. Document the asymmetry so admins don't hit an unexplained 403. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
🚀 Preview DeploymentYour preview deployment is ready! 🔗 Preview URL:https://preview.harper-documentation.harperfabric.com/pr-600 This preview will update automatically when you push new commits. |
Uh oh!
There was an error while loading. Please reload this page.
🧹 Preview CleanupThe preview deployment for this PR has been removed. |
Conflict in reference/operations-api/operations.md was additive: main added the `credentials` parameter plus its "Deploy credentials" section (#581) where this branch adds the two-phase parameters. Kept both — the parameter list now carries activate/deployment_id/revert_on_failure/ignore_replication_errors/ deployment_timeout/two_phase AND credentials, followed by main's credentials section. main's get_deployment_payload / delete_deployment_payload docs (#600) are untouched.
Companion to HarperFast/harper#1898 "Implement get_deployment_payload and delete_deployment_payload operations", which implements the two operations (documented since 5.1 but returning
Operation not found— harper#1893).Adds the previously-unspecified behavioral contracts:
get_deployment_payload— response is raw tarball bytes (octet-stream + download filename), never JSON/base64; 404 when the payload was reclaimed.delete_deployment_payload— cluster-wide reclaim note, terminal-status requirement (409 otherwise), idempotency (freed_bytes: 0), response shape, and thepayload_droppedaudit event.Hold merge until harper#1898 lands.
🤖 Generated with Claude Code (Opus 4.8)