@uploadfilm/sdk 0.1.0 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/README.md +26 -6
  2. package/dist/copy/types.d.ts +29 -2
  3. package/dist/index.js +1 -1
  4. package/dist/index.mjs +1 -1
  5. package/dist/player.js +1 -1
  6. package/dist/player.mjs +1 -1
  7. package/dist/server/media/client.d.ts +34 -1
  8. package/dist/server/media/protocol.d.ts +242 -4
  9. package/dist/server/r2/client.d.ts +18 -4
  10. package/dist/server/storage/chunked.d.ts +6 -2
  11. package/dist/server/storage/s3.d.ts +51 -0
  12. package/dist/server/testing/fake-r2.d.ts +22 -2
  13. package/dist/server/transfer/handler.d.ts +50 -0
  14. package/dist/server/transfer/protocol.d.ts +53 -4
  15. package/dist/server-media.js +1 -1
  16. package/dist/server-media.mjs +1 -1
  17. package/dist/server-testing.js +1 -1
  18. package/dist/server-testing.mjs +1 -1
  19. package/dist/server.js +1 -1
  20. package/dist/server.mjs +1 -1
  21. package/dist/transfer/client.d.ts +13 -2
  22. package/dist/transfer/engine.d.ts +22 -2
  23. package/dist/transfer/growing/bytes.d.ts +17 -0
  24. package/dist/transfer/growing/index.d.ts +12 -0
  25. package/dist/transfer/growing/parts.d.ts +157 -0
  26. package/dist/transfer/growing/retry.d.ts +38 -0
  27. package/dist/transfer/growing/store.d.ts +66 -0
  28. package/dist/transfer/growing/upload.d.ts +126 -0
  29. package/dist/transfer/index.d.ts +1 -0
  30. package/dist/transfer/protocol.d.ts +5 -0
  31. package/dist/transfer/storage.d.ts +28 -3
  32. package/dist/workers/cli.mjs +115 -0
  33. package/dist/workers/media/config.mjs +53 -0
  34. package/dist/workers/media/container/Dockerfile +19 -0
  35. package/dist/workers/media/container/FFMPEG.md +129 -0
  36. package/dist/workers/media/container/runner.mjs +2690 -0
  37. package/dist/workers/media/index.mjs +1011 -0
  38. package/dist/workers/media/init/config.ts +52 -0
  39. package/dist/workers/media/init/worker.ts +8 -0
  40. package/dist/workers/media/init/wrangler.toml +44 -0
  41. package/dist/workers/media/runner.mjs +2656 -0
  42. package/dist/workers/media/types/build/entry/config.d.mts +6 -0
  43. package/dist/workers/media/types/build/entry/index.d.mts +43 -0
  44. package/dist/workers/media/types/build/entry/program.d.mts +13 -0
  45. package/dist/workers/media/types/build/entry/runner.d.mts +12 -0
  46. package/dist/workers/media/types/build/entry/settings.d.mts +40 -0
  47. package/dist/workers/media/types/src/config.d.mts +135 -0
  48. package/dist/workers/media/types/src/jobs.d.mts +73 -0
  49. package/dist/workers/media/types/src/runner/container.d.mts +32 -0
  50. package/dist/workers/media/types/src/runner/ffmpeg.d.mts +227 -0
  51. package/dist/workers/media/types/src/runner/job.d.mts +107 -0
  52. package/dist/workers/media/types/src/runner/node.d.mts +71 -0
  53. package/dist/workers/media/types/src/runner/plugins.d.mts +45 -0
  54. package/dist/workers/media/types/src/serve.d.mts +107 -0
  55. package/dist/workers/media/types/src/steps/audio.d.mts +33 -0
  56. package/dist/workers/media/types/src/steps/edit.d.mts +62 -0
  57. package/dist/workers/media/types/src/steps/frameCheck.d.mts +44 -0
  58. package/dist/workers/media/types/src/steps/gate.d.mts +18 -0
  59. package/dist/workers/media/types/src/steps/paths.d.mts +1 -0
  60. package/dist/workers/media/types/src/steps/prep.d.mts +60 -0
  61. package/dist/workers/media/types/src/steps/render.d.mts +40 -0
  62. package/dist/workers/media/types/src/steps/runner.d.mts +30 -0
  63. package/dist/workers/media/types/src/steps/transcribe.d.mts +89 -0
  64. package/dist/workers/media/types/src/storyboard/index.d.mts +61 -0
  65. package/dist/workers/media/types/src/transcoder.d.mts +30 -0
  66. package/dist/workers/media/types/src/worker.d.mts +30 -0
  67. package/dist/workers/zip/index.mjs +589 -0
  68. package/dist/workers/zip/init/config.ts +22 -0
  69. package/dist/workers/zip/init/worker.ts +5 -0
  70. package/dist/workers/zip/init/wrangler.toml +25 -0
  71. package/dist/workers/zip/types/build/entry/index.d.mts +5 -0
  72. package/dist/workers/zip/types/src/config.d.mts +35 -0
  73. package/dist/workers/zip/types/src/serve.d.mts +86 -0
  74. package/dist/workers/zip/types/src/worker.d.mts +12 -0
  75. package/package.json +51 -3
@@ -81,8 +81,22 @@ export declare function rungsFor(rungs: readonly Rung[], width: number, height:
81
81
  * storyboard/storyboard.vtt and storyboard/storyboard.json (./storyboard.ts), from the same decode
82
82
  * faststart faststart.mp4: the source remuxed with its index first (no re-encode, no decode)
83
83
  */
84
- export type Step = "ladder" | "poster" | "storyboard" | "faststart" | "audio" | "transcript" | "frame-check";
84
+ export type Step = "ladder" | "poster" | "storyboard" | "faststart" | "audio" | "transcript" | "frame-check" | "prep" | "render";
85
+ /** The steps a job may name unless a product allows more (`prep` and `render` are allowed only by name: EDIT_STEPS). */
85
86
  export declare const STEPS: readonly Step[];
87
+ /**
88
+ * The editor's steps (docs/platform/MEDIA-STEPS.md). Each is a job of its own (never named with another step) and is
89
+ * off unless a product names it in `steps.allowed`:
90
+ * prep an edit-ready source: edit/media.mp4 (fragmented MP4, H.264/AAC within a resolution cap; only when the
91
+ * source isn't one already), filmstrip sheets edit/sb-NNN.jpg, waveform peaks edit/peaks.bin, and
92
+ * edit/prep.json (PrepResult) written last. One decode.
93
+ * render an edit list (EditList: parts of several sources, JobRequest.render) baked into render/video.mp4
94
+ * (fragmented MP4, moov first, H.264 + AAC 48 kHz stereo), render/poster.jpg and render/result.json
95
+ * (RenderResult) written last.
96
+ */
97
+ export declare const EDIT_STEPS: readonly Step[];
98
+ /** Every step, in canonical order. */
99
+ export declare const ALL_STEPS: readonly Step[];
86
100
  /**
87
101
  * Optional steps, off unless a product allows them (its config's `steps.allowed`) and a job asks for them:
88
102
  * audio audio/a-NNN.ogg (Opus, mono, 16 kHz, chunks of StepSettings.audio.chunkS) + audio/audio.json (the chunks
@@ -97,6 +111,8 @@ export declare const STEPS: readonly Step[];
97
111
  export declare const EXTRA_STEPS: readonly Step[];
98
112
  /** Does this job run any optional step? */
99
113
  export declare const hasExtraSteps: (steps: readonly Step[]) => boolean;
114
+ /** Is this a prep or render job? (Those run alone: parseSteps refuses them with any other step.) */
115
+ export declare const isEditJob: (steps: readonly Step[]) => boolean;
100
116
  /** Does the container write audio chunks for this job? (`transcript` needs them.) */
101
117
  export declare const wantsAudio: (steps: readonly Step[]) => boolean;
102
118
  /**
@@ -149,6 +165,10 @@ export interface StepSettings {
149
165
  maxSheetBytes?: number;
150
166
  maxBytes?: number;
151
167
  };
168
+ /** The `prep` step (an edit-ready source). Any field left out takes DEFAULT_PREP's. */
169
+ prep?: Partial<PrepSettings>;
170
+ /** The `render` step (an edit list baked into one file). Any field left out takes DEFAULT_RENDER's. */
171
+ render?: Partial<RenderSettings>;
152
172
  }
153
173
  /** The default optional-step settings with the given version (and any overrides, merged per group). */
154
174
  export declare function stepSettings(version: string, over?: {
@@ -170,11 +190,14 @@ export declare const TRANSCRIPT_VTT = "transcript.vtt";
170
190
  export declare const TRANSCRIPT_JSON = "transcript.json";
171
191
  export declare const FRAME_CHECK_FILE = "frame-check.json";
172
192
  export declare const audioChunkName: (i: number) => string;
173
- /** Steps in their canonical order, deduplicated; null when anything isn't a known step or the list is empty. */
193
+ /**
194
+ * Steps in their canonical order, deduplicated; null when anything isn't a known step or the list is empty, or when
195
+ * `prep` or `render` is named with any other step (each is a job of its own).
196
+ */
174
197
  export declare function parseSteps(x: unknown, allowed?: readonly Step[]): Step[] | null;
175
198
  /** Is `rel` a name the transcoder writes inside a ladder (and the Worker serves)? `seg`: the segment names in use. */
176
199
  export declare function ladderFile(rel: string, seg: readonly string[]): "playlist" | "init" | "segment" | null;
177
- export type OutputKind = "playlist" | "init" | "segment" | "poster" | "storyboard" | "storyboard-index" | "faststart" | "audio" | "audio-index" | "transcript" | "transcript-json" | "frame-check";
200
+ export type OutputKind = "playlist" | "init" | "segment" | "poster" | "storyboard" | "storyboard-index" | "faststart" | "audio" | "audio-index" | "transcript" | "transcript-json" | "frame-check" | "edit-media" | "edit-filmstrip" | "edit-peaks" | "edit-result" | "render-video" | "render-poster" | "render-result";
178
201
  /** Is `rel` a file one of these steps writes? (The gatekeeper refuses anything else.) */
179
202
  export declare function outputFile(rel: string, steps: readonly Step[], seg: readonly string[]): OutputKind | null;
180
203
  /**
@@ -182,7 +205,7 @@ export declare function outputFile(rel: string, steps: readonly Step[], seg: rea
182
205
  * playlist for a ladder; else the last step's own file. A transcript is written after it (by the Worker).
183
206
  */
184
207
  export declare function completionFile(steps: readonly Step[]): string;
185
- export declare const contentTypeOf: (rel: string) => "application/json" | "image/webp" | "image/jpeg" | "audio/ogg" | "video/mp4" | "application/vnd.apple.mpegurl" | "video/iso.segment" | "text/vtt; charset=utf-8";
208
+ export declare const contentTypeOf: (rel: string) => "application/json" | "application/octet-stream" | "image/webp" | "image/jpeg" | "audio/ogg" | "video/mp4" | "application/vnd.apple.mpegurl" | "video/iso.segment" | "text/vtt; charset=utf-8";
186
209
  /**
187
210
  * The hash a job's outputs are named by: SHA-256 (hex) of `<sourceKey>#<sourceEtag>[#<variant>]`. A new version of the
188
211
  * source (another ETag) or another variant (other settings) gets other outputs; the same ones always the same name.
@@ -223,6 +246,12 @@ export interface JobRequest {
223
246
  * MediaRecorder WebM). Absent: only the header's duration is checked, as before (the body is byte for byte the same).
224
247
  */
225
248
  expectDurationS?: number;
249
+ /**
250
+ * A `render` job's sources and edit list (and only a render job's). The job's `src`, `etag` and `bytes` are its
251
+ * first source's; the body may be up to MAX_RENDER_BODY. Absent on every other job (its body is byte for byte what
252
+ * it always was).
253
+ */
254
+ render?: RenderJob;
226
255
  }
227
256
  /** The longest expected length a job may carry (a week of footage: anything longer is a mistake, not a video). */
228
257
  export declare const MAX_EXPECT_DURATION_S: number;
@@ -316,3 +345,212 @@ export interface RunnerStatus {
316
345
  export declare const EXPECT_HEADER = "x-media-expect-duration";
317
346
  /** Header the runner sends its settings version in, on every output it writes (the gatekeeper refuses another). */
318
347
  export declare const VERSION_HEADER = "x-media-version";
348
+ /** prep's files, under the job's prefix. */
349
+ export declare const PREP_MEDIA = "edit/media.mp4";
350
+ export declare const PREP_PEAKS = "edit/peaks.bin";
351
+ /** Written last: while it is missing the prep doesn't exist for anyone. */
352
+ export declare const PREP_RESULT = "edit/prep.json";
353
+ export declare const prepSheetName: (i: number) => string;
354
+ /** render's files, under the job's prefix. */
355
+ export declare const RENDER_VIDEO = "render/video.mp4";
356
+ export declare const RENDER_POSTER = "render/poster.jpg";
357
+ /** Written last. */
358
+ export declare const RENDER_RESULT = "render/result.json";
359
+ /** The JSON results' format (PrepResult.format, RenderResult.format). */
360
+ export declare const EDIT_RESULT_FORMAT = 1;
361
+ /** What decides prep's outputs (StepSettings.prep; the step settings' version names them). */
362
+ export interface PrepSettings {
363
+ /** The edit-ready file's short side at most this (a job's own `maxShort`, one of the product's caps, lowers it). */
364
+ maxShort: number;
365
+ /** A longer source is refused. */
366
+ maxSeconds: number;
367
+ /** x264 preset and CRF of a converted source; AAC kbps of its sound (48 kHz stereo). */
368
+ preset: string;
369
+ crf: number;
370
+ audioKbps: number;
371
+ /** Filmstrip sheets (the storyboard layout): columns × rows thumbnails, each `tileLongSide` px on its long side. */
372
+ columns: number;
373
+ rows: number;
374
+ tileLongSide: number;
375
+ /** A thumbnail every this many seconds at least, longer so the filmstrip stays within `maxFrames`. */
376
+ minIntervalS: number;
377
+ maxFrames: number;
378
+ /** JPEG quality (FFmpeg's -q:v, 2 best … 31). */
379
+ jpegQ: number;
380
+ /** Waveform buckets per second (peaks.bin: [min, max] signed 8-bit per bucket, mono). */
381
+ peaksRate: number;
382
+ /** One FFmpeg run's limit (the job's own limit is the Worker's jobTimeoutMs). */
383
+ processTimeoutS: number;
384
+ }
385
+ export declare const DEFAULT_PREP: PrepSettings;
386
+ /** What decides render's outputs (StepSettings.render). */
387
+ export interface RenderSettings {
388
+ /** The output's short side at most this (an edit list's own `output.maxShort` lowers it). */
389
+ maxShort: number;
390
+ /** Limits on an edit list (each within RENDER_LIMITS). */
391
+ maxParts: number;
392
+ maxSources: number;
393
+ maxSeconds: number;
394
+ /** A shorter part is refused. */
395
+ minPartMs: number;
396
+ preset: string;
397
+ crf: number;
398
+ audioKbps: number;
399
+ /** The poster's width at most this. */
400
+ posterWidth: number;
401
+ /** One part's encode limit (and the join's). */
402
+ partTimeoutS: number;
403
+ }
404
+ export declare const DEFAULT_RENDER: RenderSettings;
405
+ /** Hard limits whatever the settings say (an edit list is hostile input until checked). */
406
+ export declare const RENDER_LIMITS: {
407
+ readonly parts: 500;
408
+ readonly sources: 100;
409
+ readonly seconds: number;
410
+ readonly frame: 8192;
411
+ readonly fps: 120;
412
+ };
413
+ /** A render job's body may be this long (any other job's: MAX_BODY). */
414
+ export declare const MAX_RENDER_BODY: number;
415
+ /** prep's settings with every default filled in, each bounded to what the runner can make. */
416
+ export declare function prepSettingsOf(ss: Pick<StepSettings, "prep"> | undefined): PrepSettings;
417
+ /** render's settings with every default filled in, each within RENDER_LIMITS. */
418
+ export declare function renderSettingsOf(ss: Pick<StepSettings, "render"> | undefined): RenderSettings;
419
+ /** The filmstrip's thumbnail interval (seconds) for a source this long: at least minIntervalS, at most maxFrames. */
420
+ export declare const filmstripInterval: (seconds: number, s: Pick<PrepSettings, "minIntervalS" | "maxFrames">) => number;
421
+ /** peaks.bin's size for a source this long: two signed bytes per bucket. */
422
+ export declare const peaksBytes: (seconds: number, rate: number) => number;
423
+ /** edit/prep.json. */
424
+ export interface PrepResult {
425
+ format: typeof EDIT_RESULT_FORMAT;
426
+ /** true: the edit-ready file is edit/media.mp4; false: the source already was one (use it as it is). */
427
+ converted: boolean;
428
+ media: typeof PREP_MEDIA | null;
429
+ durationMs: number;
430
+ /** The edit-ready picture's size (as displayed) and nominal rate. */
431
+ width: number;
432
+ height: number;
433
+ fps: number;
434
+ hasAudio: boolean;
435
+ /** The edit-ready file's size: edit/media.mp4's, or the source's. */
436
+ bytes: number;
437
+ filmstrip: {
438
+ interval: number;
439
+ count: number;
440
+ columns: number;
441
+ rows: number;
442
+ tileWidth: number;
443
+ tileHeight: number;
444
+ sheets: string[];
445
+ };
446
+ /** Waveform: signed 8-bit [min, max] per bucket, `rate` buckets a second, mono. null: no sound. */
447
+ peaks: {
448
+ file: typeof PREP_PEAKS;
449
+ rate: number;
450
+ buckets: number;
451
+ } | null;
452
+ }
453
+ /**
454
+ * Is this a prep.json these settings could have made, for this job (its source's size, its cap)? The reason it isn't,
455
+ * or null. (The gatekeeper's check.)
456
+ */
457
+ export declare function prepResultProblem(r: unknown, s: PrepSettings, job?: {
458
+ bytes: number;
459
+ maxShort?: number;
460
+ }): string | null;
461
+ /** A rectangle in pixels. */
462
+ export interface EditRect {
463
+ x: number;
464
+ y: number;
465
+ width: number;
466
+ height: number;
467
+ }
468
+ /** One part: [inMs, outMs) of a source (its index in RenderJob.sources), as displayed (a phone clip turned upright). */
469
+ export interface EditPart {
470
+ source: number;
471
+ inMs: number;
472
+ outMs: number;
473
+ /** Silence instead of the part's sound. */
474
+ muted?: true;
475
+ /** A crop of the part's picture (in its source's displayed pixels), before it is fitted into the output frame. */
476
+ crop?: EditRect;
477
+ }
478
+ /**
479
+ * An edit list, version 1. Every part is fitted inside the output frame (black bars, never stretched), then the
480
+ * whole-video `crop` (in output-frame pixels) is applied, then the resolution cap (the short side at most
481
+ * `maxShort`, and at most the product's RenderSettings.maxShort). The output runs at `fps`; frame k is at k / fps, so
482
+ * the total is within one frame of the parts' summed length.
483
+ */
484
+ export interface EditList {
485
+ version: 1;
486
+ output: {
487
+ width: number;
488
+ height: number;
489
+ fps: number;
490
+ crop?: EditRect;
491
+ maxShort?: number;
492
+ };
493
+ parts: EditPart[];
494
+ }
495
+ export declare const EDIT_LIST_VERSION = 1;
496
+ /** One source of a render: its key, the ETag it is pinned to (a source replaced meanwhile is refused) and its size. */
497
+ export interface RenderSource {
498
+ src: string;
499
+ etag: string;
500
+ bytes: number;
501
+ }
502
+ export interface RenderJob {
503
+ sources: RenderSource[];
504
+ editList: EditList;
505
+ }
506
+ /** A render job's fields in a fixed order (the signature is over these bytes). */
507
+ export declare function renderBody(r: RenderJob): RenderJob;
508
+ /**
509
+ * Check a render job (hostile until checked): its shape (no unknown fields), the edit list's version and limits, every
510
+ * part's source and times, every crop. The site checks before it signs; the Worker and the container check again.
511
+ */
512
+ export declare function parseRenderJob(x: unknown, s?: RenderSettings): {
513
+ job: RenderJob;
514
+ } | {
515
+ error: string;
516
+ };
517
+ /** The edit list's length (ms): the parts' summed length. */
518
+ export declare const editListMs: (e: Pick<EditList, "parts">) => number;
519
+ /**
520
+ * Frames each part gets on the output clock: frame k is at k / fps, a part owns the frames whose time falls in its
521
+ * span (at least one), so the total is within one frame of the edit list.
522
+ */
523
+ export declare function renderFrames(e: Pick<EditList, "parts" | "output">): number[];
524
+ /** The sound's rate: 48 kHz. */
525
+ export declare const RENDER_SAMPLE_RATE = 48000;
526
+ /** 48 kHz samples each part's sound gets, rounded cumulatively so the total is exact. */
527
+ export declare function renderSamples(e: Pick<EditList, "parts">): number[];
528
+ /** The output's size: the output frame (or its crop) with the short side at most the cap; even sides. */
529
+ export declare function renderFrame(e: Pick<EditList, "output">, s?: Pick<RenderSettings, "maxShort">): {
530
+ width: number;
531
+ height: number;
532
+ };
533
+ /** render/result.json. */
534
+ export interface RenderResult {
535
+ format: typeof EDIT_RESULT_FORMAT;
536
+ /** The picture's length: frames / fps (within one frame of the edit list). */
537
+ durationMs: number;
538
+ frames: number;
539
+ fps: number;
540
+ /** The sound's length in 48 kHz samples (exactly the edit list's). */
541
+ samples: number;
542
+ width: number;
543
+ height: number;
544
+ /** render/video.mp4's size. */
545
+ bytes: number;
546
+ parts: number;
547
+ }
548
+ /** Is this a result.json of this very edit list? The reason it isn't, or null. (The gatekeeper's check.) */
549
+ export declare function renderResultProblem(r: unknown, e: EditList, s: RenderSettings): string | null;
550
+ /** A render's identity: SHA-256 (hex) of its body. Two renders of the same sources and edit list are the same job. */
551
+ export declare function renderHash(r: RenderJob): Promise<string>;
552
+ /**
553
+ * A render's fingerprint, synchronously (FNV-1a, 64 bits, hex, of its body): part of the Worker's job key, so a new
554
+ * edit list for the same prefix is a new job. Not a security boundary (every request is signed); renderHash names things.
555
+ */
556
+ export declare function renderKey(r: RenderJob): string;
@@ -24,6 +24,12 @@ export interface PresignPutOptions {
24
24
  contentMd5?: string;
25
25
  contentLength?: number;
26
26
  ifNoneMatch?: boolean;
27
+ /**
28
+ * Base64 SHA-256 of the body, signed as `x-amz-checksum-sha256`: storage checks the body against it (400 BadDigest)
29
+ * and keeps it (echoed on the PUT, reported on HEAD). R2 checks it on a single PUT only: a part PUT that carries it
30
+ * is refused with 501 NotImplemented (measured on a real bucket, 2026-11-16).
31
+ */
32
+ checksumSha256?: string;
27
33
  }
28
34
  export interface PresignGetOptions {
29
35
  expiresIn?: number;
@@ -70,16 +76,20 @@ export type R2Client = ReturnType<typeof createR2Client>;
70
76
  export declare function createR2Client(config: R2Config): {
71
77
  bucket: string;
72
78
  signedFetch: (method: string, key: string, { headers, body, query, bucketLevel, signal }?: SignedFetchOptions) => Promise<Response>;
73
- createMultipart: (key: string, contentType: string, { signal }?: {
79
+ createMultipart: (key: string, contentType: string, { signal, checksumAlgorithm }?: {
74
80
  signal?: AbortSignal;
81
+ checksumAlgorithm?: "SHA256";
75
82
  }) => Promise<string>;
76
83
  completeMultipart: (key: string, uploadId: string, parts: {
77
84
  n: number;
78
85
  etag: string;
86
+ checksumSha256?: string;
79
87
  }[], { ifNoneMatch, signal }?: {
80
88
  ifNoneMatch?: boolean;
81
89
  signal?: AbortSignal;
82
- }) => Promise<void>;
90
+ }) => Promise<{
91
+ checksumSha256?: string;
92
+ }>;
83
93
  abortMultipart: (key: string, uploadId: string, { signal }?: {
84
94
  signal?: AbortSignal;
85
95
  }) => Promise<boolean>;
@@ -87,10 +97,14 @@ export declare function createR2Client(config: R2Config): {
87
97
  n: number;
88
98
  etag: string;
89
99
  size: number;
100
+ checksumSha256?: string;
90
101
  }[]>;
91
- headInfo: (key: string) => Promise<{
102
+ headInfo: (key: string, o?: {
103
+ checksums?: boolean;
104
+ }) => Promise<{
92
105
  size: number | null;
93
106
  etag: string | null;
107
+ checksumSha256?: string;
94
108
  }>;
95
109
  headObject: (key: string) => Promise<{
96
110
  etag: string;
@@ -137,7 +151,7 @@ export declare function createR2Client(config: R2Config): {
137
151
  } | null>;
138
152
  getBytes: (key: string, maxBytes: number) => Promise<Uint8Array | null>;
139
153
  getJson: <T>(key: string) => Promise<T | null>;
140
- presignPut: (key: string, { expiresIn, query, contentType, contentMd5, contentLength, ifNoneMatch }?: PresignPutOptions) => Promise<string>;
154
+ presignPut: (key: string, { expiresIn, query, contentType, contentMd5, contentLength, ifNoneMatch, checksumSha256 }?: PresignPutOptions) => Promise<string>;
141
155
  presignGet: (key: string, { expiresIn, download, inline, contentType }?: PresignGetOptions) => Promise<string>;
142
156
  };
143
157
  /**
@@ -17,5 +17,9 @@ export declare const CHUNK: number;
17
17
  export declare const TRAILER = "x-amz-checksum-crc32";
18
18
  /** Bytes on the wire for a `size`-byte payload. */
19
19
  export declare function encodedLength(size: number): number;
20
- /** Raw bytes in, aws-chunked bytes out; `onCrc` gets the payload's CRC-32 once it all passed. */
21
- export declare function awsChunked(size: number, hasher: Pick<CopyHasher, "crc32">, onCrc?: (crc: number) => void): TransformStream<Uint8Array, Uint8Array>;
20
+ /**
21
+ * Raw bytes in, aws-chunked bytes out; `onCrc` gets the payload's CRC-32 once it all passed. `trailerCrc`: send this
22
+ * CRC-32 in the trailer instead of the one computed (the CRC the bytes are known to have from elsewhere): S3 then
23
+ * refuses the request (BadDigest) if the bytes that arrived are other bytes, and stores nothing.
24
+ */
25
+ export declare function awsChunked(size: number, hasher: Pick<CopyHasher, "crc32">, onCrc?: (crc: number) => void, trailerCrc?: number): TransformStream<Uint8Array, Uint8Array>;
@@ -22,6 +22,8 @@ export declare const ARCHIVE_CLASSES: readonly string[];
22
22
  * `no_global_navigator` flag has no navigator) the globals only the Workers runtime has.
23
23
  */
24
24
  export declare const inWorker: () => boolean;
25
+ /** The fetch `cache` modes both Node and Cloudflare Workers accept. */
26
+ export type FetchCacheMode = "no-store" | "no-cache";
25
27
  export interface S3Credentials {
26
28
  accessKeyId: string;
27
29
  secretAccessKey: string;
@@ -70,6 +72,27 @@ export interface S3Options {
70
72
  partTimeoutMs?: (size: number) => number;
71
73
  /** Part size for an object of `size` (default 64 MiB, grown to stay under `maxParts`). */
72
74
  partSize?: (size: number) => number;
75
+ /**
76
+ * Send a Content-Type on CreateMultipartUpload and PutObject (default true: the copy's, else
77
+ * application/octet-stream). false: none, so S3 stores its default (binary/octet-stream), as a product whose existing
78
+ * copies were written that way needs (the backup Worker's originals).
79
+ */
80
+ sendContentType?: boolean;
81
+ /**
82
+ * A part (or single PUT) answered without the CRC-32 echo of the trailer sent is refused (StorageError, retried)
83
+ * instead of taken with no checksum (default false: some S3-compatible stores never echo). AWS S3 always echoes.
84
+ */
85
+ requireChecksumEcho?: boolean;
86
+ /**
87
+ * The fetch `cache` mode of every request (default "no-store": never through Cloudflare's cache, which can turn a
88
+ * HEAD into a GET and so break its signature). null: none sent (a Worker whose compatibility date predates
89
+ * 2024-11-11 without the cache_option_enabled flag refuses the field).
90
+ */
91
+ fetchCache?: FetchCacheMode | null;
92
+ /** HeadObject tries per call when S3 answers a body-less 403 that isn't a credentials problem (default 1). */
93
+ headTries?: number;
94
+ /** The wait before the second such try (ms, default 200), doubled each time. */
95
+ headRetryMs?: number;
73
96
  /** Object ETags are MD5s (default true; false with SSE-KMS / SSE-C). */
74
97
  md5Etags?: boolean;
75
98
  /** Follow a wrong-region answer once (default true). */
@@ -87,7 +110,35 @@ export type S3Module = CopySource & CopyDestination & {
87
110
  readonly stats: Record<string, number>;
88
111
  abort(key: string, uploadId: string): Promise<void>;
89
112
  listUploads(prefix: string): Promise<UploadInfo[]>;
113
+ /** One page of ListObjectsV2 (keys in UTF-8 binary order). */
114
+ list(o: S3ListOptions): Promise<S3ListPage>;
115
+ /** A small object's bytes as text (a report, a JSON document); null when there is no such object. */
116
+ getText(key: string): Promise<string | null>;
90
117
  };
118
+ export interface S3ListOptions {
119
+ prefix: string;
120
+ /** List keys after this one (ignored with a continuation token). */
121
+ startAfter?: string;
122
+ continuationToken?: string;
123
+ /** Keys per page (default and S3's most 1000). */
124
+ maxKeys?: number;
125
+ }
126
+ export interface S3Listed {
127
+ key: string;
128
+ size: number;
129
+ /** ms since epoch. */
130
+ lastModified?: number;
131
+ /** Bare. */
132
+ etag: string;
133
+ storageClass?: string;
134
+ checksumAlgorithm?: string;
135
+ checksumType?: string;
136
+ }
137
+ export interface S3ListPage {
138
+ objects: S3Listed[];
139
+ /** Set while there is more. */
140
+ nextToken?: string;
141
+ }
91
142
  export declare function s3(o: S3Options): S3Module;
92
143
  /** The query string S3 requests carry (exported for the fake's tests). */
93
144
  export declare const s3Query: (query: Query) => string;
@@ -14,7 +14,16 @@
14
14
  * - multipart ETag = md5(concat(binary part md5s)) + "-" + N
15
15
  * - PUT with If-None-Match: * onto an existing key → 412 PreconditionFailed (also CompleteMultipartUpload)
16
16
  * - Content-MD5 mismatch → 400 BadDigest; so is a wrong x-amz-checksum-crc32 / -crc32c / -sha1 / -sha256. A right one
17
- * is kept and HEAD/GET with `x-amz-checksum-mode: ENABLED` answer it
17
+ * is kept, answered back on the PUT, reported on every HEAD (with or without `x-amz-checksum-mode`) and on a whole
18
+ * GET with `x-amz-checksum-mode: ENABLED`
19
+ * - Content-MD5 together with x-amz-checksum-sha256 → 400 InvalidRequest ("You can only specify one non-default
20
+ * checksum at a time", 2026-11-16); either one alone is checked
21
+ * - SHA-256 on multipart uploads isn't implemented (measured 2026-11-16): create with x-amz-checksum-algorithm SHA256
22
+ * is accepted and ignored; a part PUT with x-amz-checksum-sha256 → 501 NotImplemented; a complete's
23
+ * <ChecksumSHA256> values are ignored (even wrong ones) and no composite checksum is answered or kept; ListParts
24
+ * reports no checksums. `s3Checksums = true` models S3 instead (see there). Not modelled: the x-amz-checksum-crc64nvme
25
+ * receipt R2 adds on its own to part PUTs, completes and multipart HEADs (nothing in the SDK reads it)
26
+ * - a presigned PUT with an x-amz-checksum-* header it wasn't signed with → 403 SignatureDoesNotMatch
18
27
  * - part numbers outside 1..10,000 → 400 InvalidArgument
19
28
  * - part PUT / complete for an unknown (aborted, completed, expired) uploadId → 404 NoSuchUpload
20
29
  * - complete: stale part ETag, unequal non-final part sizes or a last part bigger than the others → 400 InvalidPart; a
@@ -122,6 +131,8 @@ export interface StoredObject {
122
131
  export interface Upload {
123
132
  key: string;
124
133
  contentType?: string;
134
+ /** x-amz-checksum-algorithm of the create (kept only with `s3Checksums`). */
135
+ checksumAlgorithm?: string;
125
136
  parts: Map<number, {
126
137
  body: Buffer;
127
138
  etag: string;
@@ -232,6 +243,14 @@ export declare class FakeR2 {
232
243
  expiryAfterBody: boolean;
233
244
  /** Lifecycle: a multipart upload older than this many ms (on `now()`) is gone (NoSuchUpload). 0 = never (default). */
234
245
  uploadMaxAgeMs: number;
246
+ /**
247
+ * Model S3's SHA-256 checksums instead of R2's (off: R2, the default). On: a create with x-amz-checksum-algorithm
248
+ * SHA256 makes an upload whose parts carry x-amz-checksum-sha256 (checked, kept, reported by ListParts), whose
249
+ * complete needs every part's right <ChecksumSHA256> (else 400 InvalidPart) and answers the COMPOSITE checksum
250
+ * (base64 sha256 of the part digests + "-N"), which HEAD/GET then report with `x-amz-checksum-mode: ENABLED` only.
251
+ * For servers meant for S3-compatible stores that do support it; R2 doesn't.
252
+ */
253
+ s3Checksums: boolean;
235
254
  /** Uploads aborted through the S3 API (id → key): aborting one again answers 204, as R2 does. */
236
255
  protected aborted: Map<string, string>;
237
256
  readonly s3?: FakeS3Config;
@@ -332,7 +351,7 @@ export declare class FakeR2 {
332
351
  /** An S3 API PUT (If-Match and x-amz-meta-* honoured); token PUTs keep the platform fake's original rules. */
333
352
  s3?: boolean;
334
353
  }): Promise<undefined>;
335
- createUpload(key: string, contentType?: string): string;
354
+ createUpload(key: string, contentType?: string, checksumAlgorithm?: string): string;
336
355
  /**
337
356
  * CompleteMultipartUpload as R2 does it. → the stored object, or the S3 error code. `truncate`: the storage bug
338
357
  * fault (one byte short). The upload is consumed on success.
@@ -340,6 +359,7 @@ export declare class FakeR2 {
340
359
  completeUpload(key: string, uploadId: string, parts: {
341
360
  n: number;
342
361
  etag: string;
362
+ checksumSha256?: string;
343
363
  }[], o?: {
344
364
  truncate?: boolean;
345
365
  ifNoneMatch?: boolean;
@@ -2,6 +2,8 @@ import type { R2Client } from "../r2/client";
2
2
  import type { TransferOp, TransferResult } from "./protocol";
3
3
  /** Base64 of a 16-byte MD5: 22 chars + "==". */
4
4
  export declare const MD5_B64: RegExp;
5
+ /** Base64 of a 32-byte SHA-256, as `x-amz-checksum-sha256` carries it: 43 chars + "=". */
6
+ export declare const SHA256_B64: RegExp;
5
7
  /** "ok" lets the write through; anything else refuses it (unknown answers too: fail closed). */
6
8
  export type ReserveOutcome = "ok" | "quota" | "exists" | "deleted" | {
7
9
  refuse: TransferResult;
@@ -39,6 +41,12 @@ export interface SignHandlerOptions<Kind extends string, Ctx> {
39
41
  classify: (key: unknown, ctx: Ctx) => Kind | null;
40
42
  /** Kinds written once and counted (UploadFilm: originals). Default: none. */
41
43
  immutable?: (kind: Kind) => boolean;
44
+ /**
45
+ * Kinds this caller may read with the `get` op (a presigned GET, pinned by the client with If-Match). Default: none,
46
+ * every `get` is refused (`ReadRefused`, not retryable). A client engine uses it to prove by SHA-256 that an object
47
+ * which was at the key before its first write is the file (otherwise it can't adopt it: `Unverified`).
48
+ */
49
+ readable?: (kind: Kind, ctx: Ctx) => boolean | Promise<boolean>;
42
50
  limits?: {
43
51
  /** Ops per call (default 64). */
44
52
  maxOps?: number;
@@ -142,11 +150,53 @@ export interface SignHandlerOptions<Kind extends string, Ctx> {
142
150
  contentType: string;
143
151
  sha256: string;
144
152
  }) => Promise<DedupeSource> | DedupeSource;
153
+ /**
154
+ * The budget of a multipart whose size nobody knows until it ends (growing uploads), ported from ClipMe's
155
+ * presign-part and complete routes (its AUDIT F-02): a client holding a scope's credentials must not park unlimited
156
+ * bytes under one key. Called for every "part" op before it is signed (`phase: "part"`) and for every "complete"
157
+ * (`phase: "complete"`), of every kind, with storage's own count (ListParts), never the client's word:
158
+ * - part: `stored` = the bytes storage holds for this upload's OTHER parts (a part sent again replaces itself, so
159
+ * its earlier bytes don't count twice), `size` = the part's declared length (null when the client didn't say:
160
+ * a part signed ahead; refuse that if you require sizes), `total` = stored + (size ?? 0). A declared size is
161
+ * always signed into the URL as Content-Length, so storage refuses a bigger body;
162
+ * - complete: `stored` = `total` = the bytes of the parts being completed; a refusal aborts the upload, so a
163
+ * too-large object never comes into existence;
164
+ * - put (a single PUT, which would otherwise go round the budget): `size` = `total` = its declared size, signed as
165
+ * Content-Length. A put with no size is refused (SizeRequired) while this hook is set.
166
+ * "ok" lets it through; anything else refuses (same outcomes as `reserve`; unknown answers fail closed). Parts in
167
+ * flight together are each judged against what is stored, so a burst can pass by up to the parts in flight: the
168
+ * complete check is the one that holds. Costs one ListParts per part signed: set it only where it is wanted (the
169
+ * hook gets the kind). An upload storage no longer has answers NoSuchUpload.
170
+ */
171
+ signParts?: (ctx: Ctx, w: {
172
+ key: string;
173
+ kind: Kind;
174
+ uploadId: string;
175
+ phase: "part" | "complete" | "put";
176
+ partNumber: number | null;
177
+ size: number | null;
178
+ stored: number;
179
+ total: number;
180
+ }) => Promise<ReserveOutcome> | ReserveOutcome;
145
181
  /** Storage/internal failures turned into generic results (default: console.error, as UploadFilm logs them). */
146
182
  onError?: (e: unknown, retryable: boolean) => void;
147
183
  };
148
184
  /** The product's own keyless ops, by name. */
149
185
  ops?: Record<string, CustomOp<Ctx>>;
186
+ /**
187
+ * SHA-256 checksums (a client with integrity "sha256"). Single PUTs are always signed with the `x-amz-checksum-sha256`
188
+ * a client sends (storage checks the body against it and reports it on HEAD).
189
+ *
190
+ * `multipart` (default true): multipart uploads with SHA-256 too: create with ChecksumAlgorithm SHA256, every part
191
+ * signed with its checksum, complete with each part's ChecksumSHA256, and the composite checksum on the answers. Set
192
+ * it to false where storage can't do that: on **R2** a part PUT with `x-amz-checksum-sha256` is refused (501
193
+ * NotImplemented) and a complete's part checksums are ignored (measured 2026-11-16). Then a create, part or complete
194
+ * that asks for SHA-256 is refused with `ChecksumUnsupported` (not retryable): the client learns at once that it can't
195
+ * upload that file with SHA-256 here, instead of sending it all and ending `Unverified`.
196
+ */
197
+ checksums?: {
198
+ multipart?: boolean;
199
+ };
150
200
  }
151
201
  export type GuardOutcome = {
152
202
  refuse: {