47 lines
3.4 KiB
Markdown
47 lines
3.4 KiB
Markdown
# Run Artifact Contract
|
|
|
|
Artifacts move files and large payloads between platform and run without blocking current live logs or control.
|
|
|
|
## Implemented Routes
|
|
|
|
- `POST /api/v1/run/artifacts/open`: opens a run-to-platform upload transfer and returns resume state.
|
|
- `POST /api/v1/run/artifacts/chunks`: uploads one bounded octet-stream chunk with byte range and checksum metadata in headers.
|
|
- `POST /api/v1/run/artifacts/status`: queries received chunks and the next missing chunk index.
|
|
- `POST /api/v1/run/artifacts/complete`: verifies all chunks and final checksum before marking the artifact available.
|
|
|
|
Browser-facing artifact downloads are implemented through platform-owned routes after a run upload completes:
|
|
|
|
- `POST /api/v1/artifacts/{id}/download`: returns safe download metadata and a platform content route.
|
|
- `GET /api/v1/artifacts/{id}/content`: returns bounded byte ranges for authorized browser or plugin-page reads.
|
|
|
|
## Payloads
|
|
|
|
- `ArtifactTransferOpenRequest`: run ID, session token, artifact ID, upload direction, owner scope, size, chunk size, checksum, and idempotency key.
|
|
- `ArtifactTransferOpenResponse`: transfer ID, artifact metadata, total chunks, received chunk indexes, next missing chunk index, duplicate flag, and server time.
|
|
- `ArtifactChunkUploadRequest`: transfer ID, artifact ID, chunk index, byte offset, size, checksum, and an in-memory octet-stream payload buffer that is not JSON encoded.
|
|
- `ArtifactChunkUploadResponse`: accepted chunk index, received chunk indexes, next missing chunk index, duplicate flag, and server time.
|
|
- `ArtifactTransferStatusRequest`: run ID, session token, transfer ID, and artifact ID.
|
|
- `ArtifactTransferStatusResponse`: transfer direction, total chunks, received chunk indexes, next missing chunk index, completion flag, and server time.
|
|
- `ArtifactTransferCompleteRequest`: transfer ID, artifact ID, final checksum, and final size.
|
|
- `ArtifactTransferCompleteResponse`: completed artifact metadata and server time.
|
|
|
|
## Local Queue
|
|
|
|
Run stores unacknowledged artifact chunk metadata as JSON and raw chunk bytes as sidecar files in the local artifact queue. A queued chunk may be removed only after the platform acknowledges the same transfer ID, artifact ID, and chunk index. The queue must not store or expose raw host paths.
|
|
|
|
## Rules
|
|
|
|
- Transfers must be resumable.
|
|
- Transfers must be checksummed.
|
|
- Artifact concurrency must be limited.
|
|
- Artifact transfer must not block control heartbeat, job ack/result, or current live log relay.
|
|
- Artifact transfer is lower priority than control, job lifecycle metadata, and current live log relay.
|
|
- Slow or retrying artifact chunks must not delay live log relay or terminal job result submission.
|
|
- Control, job, and log routes must reject artifact chunk payloads or transport details rather than accepting them through lightweight channel payloads.
|
|
|
|
Run artifact queues use owner-only atomic JSON entries and retain chunks until an exact transfer/artifact/index acknowledgement covers them. A low-priority uploader retries pending chunks independently of control, jobs, and logs.
|
|
|
|
## Deferred Channels
|
|
|
|
Platform-to-run Run self-update range reads are implemented through the signed `/api/v1/run/jobs/update-input` and `/api/v1/run/jobs/update-chunk` contract. Browser artifact upload, external object storage, presigned URLs, production mirrors/signing, and production throttling policies remain separate future work.
|