eric/distributor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

Update documentation to clarity bundle_id and idempotency_key usage and distinctions

Browse Source
This commit is contained in:
Eric Rakestraw
2026-06-07 20:45:29 -05:00
parent 25fbfc4677
commit f98e528c90
6 changed files with 27 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/consumers/pkg-upload.md
View File

@@ -40,8 +40,8 @@ Use `UploadFiles` when the producer has generated output files but has not assem
```go
result, err := client.UploadFiles(ctx, upload.UploadFilesOptions{
ID: "weather.hourly.brentwood.2026-06-07T15",
IdempotencyKey: "weather.hourly.brentwood.2026-06-07T15",
ID: "weather.hourly.brentwood",
IdempotencyKey: "weather.hourly.brentwood.20260607T150000Z",
Files: []bundle.BundleFile{
{SourcePath: "/tmp/weather/report.md", Path: "report.md"},
{SourcePath: "/tmp/weather/summary.txt", Path: "summary.txt"},
@@ -62,7 +62,7 @@ Use `UploadBundle` when the producer already has a complete local bundle root co
```go
result, err := client.UploadBundle(ctx, upload.UploadBundleOptions{
Root: "/var/spool/weather/hourly-2026-06-07T15",
IdempotencyKey: "weather.hourly.brentwood.2026-06-07T15",
IdempotencyKey: "weather.hourly.brentwood.20260607T150000Z",
})
if err != nil {
return err
@@ -94,7 +94,9 @@ Status values are `accepted`, `queued`, `running`, `succeeded`, and `failed`. Co
Every upload request includes `Idempotency-Key`.
If `IdempotencyKey` is omitted, the client generates a random 128-bit lowercase hexadecimal key for that upload operation and reuses it for retries within the same call. For cross-process retry safety, producers should pass a stable key derived from the producer job or report id.
If `IdempotencyKey` is omitted, the client generates a random 128-bit lowercase hexadecimal key for that upload operation and reuses it for retries within the same call. For cross-process retry safety, producers should pass a key derived from the producer run, such as `<bundle-id>.<run-id>`.
Do not reuse the same idempotency key for multiple distinct report generations. Reuse it only when retrying the exact same run with the same source manifest. A repeated key with the same manifest returns the original accepted run instead of enqueueing another run; a repeated key with different content returns an idempotency conflict.
The client retries only safe cases: