admin343/browser
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

first commit

Browse Source
This commit is contained in:
npc0-hue
2026-07-11 14:56:10 +08:00
commit 7e05d0a4e7
660 changed files with 78119 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
run/protocol/artifact.md
+44
View File
@@ -0,0 +1,44 @@
# Run Artifact Contract
Artifacts move files and large payloads between platform and run without blocking 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 chunk with byte range and checksum metadata.
- `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 JSON byte payload.
- `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 `ArtifactChunkUploadRequest` payloads 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 log upload.
- Artifact transfer is lower priority than control, job lifecycle metadata, and durable log ingest.
- Slow or retrying artifact chunks must not prevent log spool acknowledgement cleanup 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.
## Deferred Channels
Platform-to-run download, browser artifact upload, external object storage, presigned URLs, and production throttling policies remain separate future work.