@uploadfilm/sdk 0.0.0-stage → 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 (267) hide show
  1. package/LICENSE +4 -0
  2. package/README.md +529 -2
  3. package/dist/ai/embed.d.ts +58 -0
  4. package/dist/ai/fake.d.ts +41 -0
  5. package/dist/ai/http.d.ts +17 -0
  6. package/dist/ai/index.d.ts +27 -0
  7. package/dist/ai/languages.d.ts +2 -0
  8. package/dist/ai/ollama.d.ts +23 -0
  9. package/dist/ai/openaiCompatible.d.ts +54 -0
  10. package/dist/ai/passages.d.ts +28 -0
  11. package/dist/ai/transcribe.d.ts +84 -0
  12. package/dist/ai/types.d.ts +141 -0
  13. package/dist/ai/usage.d.ts +66 -0
  14. package/dist/ai/whisperJson.d.ts +15 -0
  15. package/dist/ai/workersAi.d.ts +56 -0
  16. package/dist/ai.js +1 -0
  17. package/dist/ai.mjs +1 -0
  18. package/dist/cards/files.d.ts +91 -0
  19. package/dist/cards/index.d.ts +15 -0
  20. package/dist/cards/layouts.d.ts +121 -0
  21. package/dist/cards/probe.d.ts +69 -0
  22. package/dist/cards/proxies.d.ts +70 -0
  23. package/dist/cards/select.d.ts +68 -0
  24. package/dist/cards/volumes.d.ts +170 -0
  25. package/dist/cards/xml.d.ts +80 -0
  26. package/dist/cards.js +1 -0
  27. package/dist/cards.mjs +1 -0
  28. package/dist/copy/checksums.d.ts +66 -0
  29. package/dist/copy/engine.d.ts +24 -0
  30. package/dist/copy/errors.d.ts +109 -0
  31. package/dist/copy/index.d.ts +15 -0
  32. package/dist/copy/steps.d.ts +28 -0
  33. package/dist/copy/sweep.d.ts +24 -0
  34. package/dist/copy/types.d.ts +363 -0
  35. package/dist/embed/player.js +2 -0
  36. package/dist/host/adapters.d.ts +107 -0
  37. package/dist/host/detect.d.ts +68 -0
  38. package/dist/host/encoders.d.ts +34 -0
  39. package/dist/host/environment.d.ts +53 -0
  40. package/dist/host/index.d.ts +20 -0
  41. package/dist/host/linux.d.ts +94 -0
  42. package/dist/host/mac.d.ts +47 -0
  43. package/dist/host/network.d.ts +54 -0
  44. package/dist/host/node.d.ts +13 -0
  45. package/dist/host/policy.d.ts +101 -0
  46. package/dist/host/tuner.d.ts +48 -0
  47. package/dist/host/types.d.ts +118 -0
  48. package/dist/host-node.js +1 -0
  49. package/dist/host-node.mjs +1 -0
  50. package/dist/host.js +1 -0
  51. package/dist/host.mjs +1 -0
  52. package/dist/images/index.d.ts +11 -0
  53. package/dist/images/settings.d.ts +43 -0
  54. package/dist/images/types.d.ts +83 -0
  55. package/dist/images/url.d.ts +65 -0
  56. package/dist/index.d.ts +16 -0
  57. package/dist/index.js +1 -0
  58. package/dist/index.mjs +1 -0
  59. package/dist/player/adapters/hlsjs.d.ts +28 -0
  60. package/dist/player/bandwidthMemory.d.ts +28 -0
  61. package/dist/player/captions/index.d.ts +55 -0
  62. package/dist/player/embed/code.d.ts +195 -0
  63. package/dist/player/embed/constants.d.ts +4 -0
  64. package/dist/player/embed/controller.d.ts +62 -0
  65. package/dist/player/embed/element.d.ts +32 -0
  66. package/dist/player/embed/frame.d.ts +65 -0
  67. package/dist/player/embed/global.d.ts +14 -0
  68. package/dist/player/embed/index.d.ts +15 -0
  69. package/dist/player/embed/loader.d.ts +1 -0
  70. package/dist/player/embed/oembed.d.ts +74 -0
  71. package/dist/player/embed/protocol.d.ts +64 -0
  72. package/dist/player/engine.d.ts +215 -0
  73. package/dist/player/index.d.ts +18 -0
  74. package/dist/player/start.d.ts +62 -0
  75. package/dist/player/store.d.ts +10 -0
  76. package/dist/player/storyboard/index.d.ts +161 -0
  77. package/dist/player/stream.d.ts +206 -0
  78. package/dist/player/tracks.d.ts +41 -0
  79. package/dist/player.js +1 -0
  80. package/dist/player.mjs +1 -0
  81. package/dist/proxies/args.d.ts +19 -0
  82. package/dist/proxies/budget.d.ts +57 -0
  83. package/dist/proxies/camera.d.ts +104 -0
  84. package/dist/proxies/formats.d.ts +36 -0
  85. package/dist/proxies/index.d.ts +18 -0
  86. package/dist/proxies/jobs.d.ts +98 -0
  87. package/dist/proxies/node.d.ts +32 -0
  88. package/dist/proxies/plan.d.ts +89 -0
  89. package/dist/proxies/probe.d.ts +39 -0
  90. package/dist/proxies/render.d.ts +104 -0
  91. package/dist/proxies/safety.d.ts +45 -0
  92. package/dist/proxies/types.d.ts +83 -0
  93. package/dist/proxies/upload.d.ts +14 -0
  94. package/dist/react/BigPlay.d.ts +26 -0
  95. package/dist/react/Player.d.ts +58 -0
  96. package/dist/react/embed/index.d.ts +45 -0
  97. package/dist/react/examples/CustomControls.d.ts +8 -0
  98. package/dist/react/images/Image.d.ts +16 -0
  99. package/dist/react/images/index.d.ts +4 -0
  100. package/dist/react/images/useImage.d.ts +47 -0
  101. package/dist/react/index.d.ts +17 -0
  102. package/dist/react/storyboard/index.d.ts +58 -0
  103. package/dist/react/theme.d.ts +37 -0
  104. package/dist/react/useAdapterErrors.d.ts +8 -0
  105. package/dist/react/usePlaybackStart.d.ts +18 -0
  106. package/dist/react/usePlayer.d.ts +28 -0
  107. package/dist/react/useReducedMotion.d.ts +2 -0
  108. package/dist/react/useTimedTrack.d.ts +22 -0
  109. package/dist/react.js +1 -0
  110. package/dist/react.mjs +1 -0
  111. package/dist/server/auth/apiKeys.d.ts +30 -0
  112. package/dist/server/auth/cache.d.ts +21 -0
  113. package/dist/server/auth/deviceTokens.d.ts +38 -0
  114. package/dist/server/auth/envelope.d.ts +15 -0
  115. package/dist/server/auth/grants.d.ts +76 -0
  116. package/dist/server/auth/index.d.ts +19 -0
  117. package/dist/server/auth/jwt.d.ts +65 -0
  118. package/dist/server/auth/keyring.d.ts +31 -0
  119. package/dist/server/auth/kv.d.ts +12 -0
  120. package/dist/server/auth/repository.d.ts +45 -0
  121. package/dist/server/auth/revocations.d.ts +21 -0
  122. package/dist/server/auth/scope.d.ts +4 -0
  123. package/dist/server/auth/serviceAuth.d.ts +24 -0
  124. package/dist/server/auth/signedUrls.d.ts +28 -0
  125. package/dist/server/embed/index.d.ts +36 -0
  126. package/dist/server/embed/lifecycle.d.ts +53 -0
  127. package/dist/server/embed/playerScript.d.ts +4 -0
  128. package/dist/server/images/index.d.ts +15 -0
  129. package/dist/server/images/job.d.ts +80 -0
  130. package/dist/server/images/layout.d.ts +24 -0
  131. package/dist/server/images/params.d.ts +90 -0
  132. package/dist/server/images/route.d.ts +101 -0
  133. package/dist/server/images/sign.d.ts +55 -0
  134. package/dist/server/index.d.ts +42 -0
  135. package/dist/server/media/client.d.ts +99 -0
  136. package/dist/server/media/frameCheck.d.ts +62 -0
  137. package/dist/server/media/index.d.ts +10 -0
  138. package/dist/server/media/protocol.d.ts +556 -0
  139. package/dist/server/media/storyboard.d.ts +144 -0
  140. package/dist/server/media/transcript.d.ts +143 -0
  141. package/dist/server/pipeline/index.d.ts +12 -0
  142. package/dist/server/pipeline/match.d.ts +10 -0
  143. package/dist/server/pipeline/pipeline.d.ts +182 -0
  144. package/dist/server/pipeline/queues.d.ts +108 -0
  145. package/dist/server/pipeline/sources.d.ts +54 -0
  146. package/dist/server/r2/client.d.ts +164 -0
  147. package/dist/server/r2/crc32.d.ts +24 -0
  148. package/dist/server/r2/encoding.d.ts +35 -0
  149. package/dist/server/r2/errors.d.ts +9 -0
  150. package/dist/server/r2/integrity.d.ts +25 -0
  151. package/dist/server/r2/parts.d.ts +46 -0
  152. package/dist/server/r2/sign.d.ts +47 -0
  153. package/dist/server/redis/index.d.ts +39 -0
  154. package/dist/server/state/memory.d.ts +18 -0
  155. package/dist/server/state/r2.d.ts +73 -0
  156. package/dist/server/state/types.d.ts +57 -0
  157. package/dist/server/storage/chunked.d.ts +25 -0
  158. package/dist/server/storage/index.d.ts +12 -0
  159. package/dist/server/storage/r2.d.ts +96 -0
  160. package/dist/server/storage/s3.d.ts +144 -0
  161. package/dist/server/testing/fake-r2.d.ts +410 -0
  162. package/dist/server/testing/index.d.ts +10 -0
  163. package/dist/server/testing/kv-contract.d.ts +14 -0
  164. package/dist/server/transfer/handler.d.ts +217 -0
  165. package/dist/server/transfer/keys.d.ts +45 -0
  166. package/dist/server/transfer/protocol.d.ts +190 -0
  167. package/dist/server/zip/client.d.ts +32 -0
  168. package/dist/server/zip/generations.d.ts +83 -0
  169. package/dist/server/zip/index.d.ts +12 -0
  170. package/dist/server/zip/planner.d.ts +94 -0
  171. package/dist/server/zip/sign.d.ts +22 -0
  172. package/dist/server-media.js +1 -0
  173. package/dist/server-media.mjs +1 -0
  174. package/dist/server-redis.js +1 -0
  175. package/dist/server-redis.mjs +1 -0
  176. package/dist/server-testing.js +1 -0
  177. package/dist/server-testing.mjs +1 -0
  178. package/dist/server.js +1 -0
  179. package/dist/server.mjs +1 -0
  180. package/dist/storage/browserFile.d.ts +19 -0
  181. package/dist/storage/index.d.ts +12 -0
  182. package/dist/storage/local.d.ts +9 -0
  183. package/dist/storage/presigned.d.ts +22 -0
  184. package/dist/sync/ffmpeg.d.ts +44 -0
  185. package/dist/sync/index.d.ts +17 -0
  186. package/dist/sync/match.d.ts +28 -0
  187. package/dist/sync/probe.d.ts +30 -0
  188. package/dist/sync/timecode.d.ts +50 -0
  189. package/dist/sync/transcript.d.ts +35 -0
  190. package/dist/sync/types.d.ts +172 -0
  191. package/dist/sync/waveform.d.ts +89 -0
  192. package/dist/sync.js +1 -0
  193. package/dist/sync.mjs +1 -0
  194. package/dist/transfer/claims.d.ts +41 -0
  195. package/dist/transfer/client.d.ts +267 -0
  196. package/dist/transfer/download.d.ts +192 -0
  197. package/dist/transfer/engine.d.ts +402 -0
  198. package/dist/transfer/errors.d.ts +50 -0
  199. package/dist/transfer/growing/bytes.d.ts +17 -0
  200. package/dist/transfer/growing/index.d.ts +12 -0
  201. package/dist/transfer/growing/parts.d.ts +157 -0
  202. package/dist/transfer/growing/retry.d.ts +38 -0
  203. package/dist/transfer/growing/store.d.ts +66 -0
  204. package/dist/transfer/growing/upload.d.ts +126 -0
  205. package/dist/transfer/index.d.ts +40 -0
  206. package/dist/transfer/integrity.d.ts +93 -0
  207. package/dist/transfer/limits.d.ts +34 -0
  208. package/dist/transfer/node.d.ts +63 -0
  209. package/dist/transfer/pool.d.ts +83 -0
  210. package/dist/transfer/protocol.d.ts +172 -0
  211. package/dist/transfer/signer.d.ts +29 -0
  212. package/dist/transfer/storage.d.ts +135 -0
  213. package/dist/transfer/timing.d.ts +132 -0
  214. package/dist/transfer/transports/electronNet.d.ts +62 -0
  215. package/dist/transfer/transports/fetch.d.ts +15 -0
  216. package/dist/transfer/transports/retryAfter.d.ts +12 -0
  217. package/dist/transfer/transports/undici.d.ts +72 -0
  218. package/dist/transfer/tuner.d.ts +56 -0
  219. package/dist/workers/cli.mjs +115 -0
  220. package/dist/workers/media/config.mjs +53 -0
  221. package/dist/workers/media/container/Dockerfile +19 -0
  222. package/dist/workers/media/container/FFMPEG.md +129 -0
  223. package/dist/workers/media/container/runner.mjs +2690 -0
  224. package/dist/workers/media/index.mjs +1011 -0
  225. package/dist/workers/media/init/config.ts +52 -0
  226. package/dist/workers/media/init/worker.ts +8 -0
  227. package/dist/workers/media/init/wrangler.toml +44 -0
  228. package/dist/workers/media/runner.mjs +2656 -0
  229. package/dist/workers/media/types/build/entry/config.d.mts +6 -0
  230. package/dist/workers/media/types/build/entry/index.d.mts +43 -0
  231. package/dist/workers/media/types/build/entry/program.d.mts +13 -0
  232. package/dist/workers/media/types/build/entry/runner.d.mts +12 -0
  233. package/dist/workers/media/types/build/entry/settings.d.mts +40 -0
  234. package/dist/workers/media/types/src/config.d.mts +135 -0
  235. package/dist/workers/media/types/src/jobs.d.mts +73 -0
  236. package/dist/workers/media/types/src/runner/container.d.mts +32 -0
  237. package/dist/workers/media/types/src/runner/ffmpeg.d.mts +227 -0
  238. package/dist/workers/media/types/src/runner/job.d.mts +107 -0
  239. package/dist/workers/media/types/src/runner/node.d.mts +71 -0
  240. package/dist/workers/media/types/src/runner/plugins.d.mts +45 -0
  241. package/dist/workers/media/types/src/serve.d.mts +107 -0
  242. package/dist/workers/media/types/src/steps/audio.d.mts +33 -0
  243. package/dist/workers/media/types/src/steps/edit.d.mts +62 -0
  244. package/dist/workers/media/types/src/steps/frameCheck.d.mts +44 -0
  245. package/dist/workers/media/types/src/steps/gate.d.mts +18 -0
  246. package/dist/workers/media/types/src/steps/paths.d.mts +1 -0
  247. package/dist/workers/media/types/src/steps/prep.d.mts +60 -0
  248. package/dist/workers/media/types/src/steps/render.d.mts +40 -0
  249. package/dist/workers/media/types/src/steps/runner.d.mts +30 -0
  250. package/dist/workers/media/types/src/steps/transcribe.d.mts +89 -0
  251. package/dist/workers/media/types/src/storyboard/index.d.mts +61 -0
  252. package/dist/workers/media/types/src/transcoder.d.mts +30 -0
  253. package/dist/workers/media/types/src/worker.d.mts +30 -0
  254. package/dist/workers/zip/index.mjs +589 -0
  255. package/dist/workers/zip/init/config.ts +22 -0
  256. package/dist/workers/zip/init/worker.ts +5 -0
  257. package/dist/workers/zip/init/wrangler.toml +25 -0
  258. package/dist/workers/zip/types/build/entry/index.d.mts +5 -0
  259. package/dist/workers/zip/types/src/config.d.mts +35 -0
  260. package/dist/workers/zip/types/src/serve.d.mts +86 -0
  261. package/dist/workers/zip/types/src/worker.d.mts +12 -0
  262. package/dist/zip/index.d.ts +13 -0
  263. package/dist/zip/layout.d.ts +129 -0
  264. package/dist/zip/names.d.ts +34 -0
  265. package/dist/zip/plan.d.ts +115 -0
  266. package/dist/zip/sw.d.ts +7 -0
  267. package/package.json +313 -4
@@ -0,0 +1,172 @@
1
+ /**
2
+ * The four swap-in points of the client engine (RFC §2.1), as interfaces. A product passes implementations in; the
3
+ * engine imports none of them, so the core stays free of Electron, DOM and network stacks.
4
+ *
5
+ * - Signer: asks the product's server to sign one storage operation (the SDK's transfer protocol,
6
+ * `@uploadfilm/sdk/server` createSignHandler speaks it). The client never holds storage credentials.
7
+ * - Transport: sends one PUT body to a presigned URL with live progress (Electron net, undici, fetch).
8
+ * - Hasher: md5 and crc32 of part bodies (node:crypto + zlib by default).
9
+ * - Saved state: the multipart records the engine keeps per item (the product's store, or a ResumeStore).
10
+ */
11
+ import type { TransferOp, TransferResult } from "../server/transfer/protocol";
12
+ export type { TransferOp, TransferResult };
13
+ /**
14
+ * Signs one op for a scope (UploadFilm: a project id) and answers with the op's TransferResult. Errors that mean
15
+ * "the server couldn't be reached / refused the request as a whole" are thrown (any error class: the engine's
16
+ * ErrorAdapter turns them into StorageErrors); per-op refusals come back as `{ ok: false, … }`.
17
+ */
18
+ export interface Signer {
19
+ sign(scope: string, op: TransferOp): Promise<TransferResult>;
20
+ }
21
+ /** Lets the engine take back a PUT that has not sent a byte yet (a borrower lane yielding to the primary lane). */
22
+ export interface Yieldable {
23
+ cancelIfQueued?: () => boolean;
24
+ /**
25
+ * The caller gave up on this PUT (a growing upload aborted or failed): stop it, sending no more. Honoured by the
26
+ * fetch transport; the undici and Electron transports ignore it (the PUT runs to its end, its answer unused).
27
+ */
28
+ signal?: AbortSignal;
29
+ }
30
+ /**
31
+ * What storage answered to a PUT that worked: its ETag (quotes stripped, may be "") and the checksum headers it sent
32
+ * back, as received. A header storage sent more than once is joined with ", " (so it never passes as one valid value);
33
+ * one it didn't send is absent.
34
+ */
35
+ export interface PutReceipt {
36
+ etag: string;
37
+ checksums: {
38
+ /** `x-amz-checksum-sha256` (base64 of the 32-byte digest, as S3/R2 send it). */
39
+ sha256?: string;
40
+ /** `x-amz-checksum-crc32` (base64). */
41
+ crc32?: string;
42
+ };
43
+ }
44
+ /** The receipt of an answer's headers (any casing; arrays = the header was repeated). */
45
+ export declare function receiptOf(etag: string, header: (name: string) => string | string[] | null | undefined): PutReceipt;
46
+ /** A header from a Node/Electron-style record (names in any case; undefined when absent). */
47
+ export declare function headerOf(h: Record<string, string | string[] | undefined> | undefined, name: string): string | string[] | undefined;
48
+ /**
49
+ * Sends one PUT. `put` resolves with the response ETag (quotes stripped, may be ""); `send` (same arguments) with the
50
+ * whole receipt: the ETag plus the checksum headers storage answered with. Both reject with a StorageError (status 0
51
+ * for no answer). `onProgress(sent)` reports body bytes the stack accepted, only ever growing. `timeoutMs`: from when
52
+ * the request really starts, the point after which a part is judged on its recent speed.
53
+ *
54
+ * `send` is optional so transports written for an older SDK keep working in the default MD5 mode; SHA-256 mode needs
55
+ * it and refuses (fails closed) on a transport without it. The SDK's three transports have both.
56
+ */
57
+ export interface Transport {
58
+ put(url: string, headers: Record<string, string>, body: Uint8Array, onProgress: (sent: number) => void, timeoutMs: number, y?: Yieldable): Promise<string>;
59
+ send?(url: string, headers: Record<string, string>, body: Uint8Array, onProgress: (sent: number) => void, timeoutMs: number, y?: Yieldable): Promise<PutReceipt>;
60
+ /**
61
+ * Connections the stack opens per host at most (Electron's net: 6). Requests beyond it wait inside the stack, so
62
+ * the engine's lanes split this many, not its own target. Infinity (undici, fetch in Node) = no cap.
63
+ */
64
+ readonly socketsPerHost: number;
65
+ /** Short name for logs and race tables ("electron-net", "undici", "fetch"). */
66
+ readonly name: string;
67
+ }
68
+ /** md5 (16 bytes) and zlib's crc32 of a buffer; crc32 continues from `prev` when given. */
69
+ export interface Hasher {
70
+ md5(b: Uint8Array): Uint8Array;
71
+ crc32(b: Uint8Array, prev?: number): number;
72
+ /** SHA-256 (32 bytes). Needed for `integrity: "sha256"` (nodeHasher has it). */
73
+ sha256?(b: Uint8Array): Uint8Array;
74
+ /** An incremental SHA-256 (for hashing a whole source in chunks). */
75
+ sha256Stream?(): {
76
+ update(b: Uint8Array): unknown;
77
+ digest(): Uint8Array;
78
+ };
79
+ /**
80
+ * A part's MD5 and CRC-32 off the caller's thread (createWorkerHasher: a worker thread). Preferred by the engine for
81
+ * multipart parts when present (small objects still use md5/crc32). The answer must be md5(b), crc32(b), and `body`:
82
+ * the same bytes, which the engine then sends. `transfer: true`: `b` is the engine's own buffer and may be handed off
83
+ * (detached) to the worker and back; otherwise `b` must be left intact (copy it). A rejection is not an error of the
84
+ * part: the engine reads the part again and hashes it with md5/crc32.
85
+ */
86
+ digestPart?(b: Uint8Array, o?: {
87
+ transfer?: boolean;
88
+ }): Promise<{
89
+ md5: Uint8Array;
90
+ crc: number;
91
+ body: Uint8Array;
92
+ }>;
93
+ /** Release what the hasher holds (worker threads). The engine's stop() calls it; the hasher works again after. */
94
+ close?(): Promise<void> | void;
95
+ }
96
+ /**
97
+ * What a source is right now, for "is it still the same bytes?". Files: device, inode, size, mtime (`Stamp`, from
98
+ * node.ts). Anything else: an `id` that changes when the content does (a content digest, a blob version, an object's
99
+ * ETag) and the size. Two stamps are the same source only if they are the same kind and every field matches.
100
+ */
101
+ export type SourceStamp = {
102
+ dev: number;
103
+ ino: number;
104
+ size: number;
105
+ mtimeMs: number;
106
+ ctimeMs?: number;
107
+ birthtimeMs?: number;
108
+ } | {
109
+ id: string;
110
+ size: number;
111
+ mtimeMs?: number;
112
+ };
113
+ /**
114
+ * Bytes to upload that aren't (only) a local path: a buffer, a browser File, a private partial file, a remote object.
115
+ *
116
+ * - `size`: the length the upload is cut from.
117
+ * - `read(offset, length)`: exactly `length` bytes at `offset`. Fewer is a failure (IntegrityError: never sent). The
118
+ * bytes answered must not change afterwards (a fresh buffer, or one the source no longer writes): the engine hashes
119
+ * what it got and sends it, and reads of other parts run in parallel, so a reader that refills one buffer for every
120
+ * read could have one part's bytes stored as another's.
121
+ * - `identity()`: see SourceStamp. Without it the engine can't tell whether a source is still the one a saved
122
+ * multipart came from: resuming such a multipart is "unknown" (never "match"); within one session the same
123
+ * ByteSource object counts as the same source.
124
+ */
125
+ export interface ByteSource {
126
+ readonly size: number;
127
+ read(offset: number, length: number, signal?: AbortSignal): Promise<Uint8Array>;
128
+ identity?(): Promise<SourceStamp | null>;
129
+ /** For messages ("<name>: …"); never shown with URLs. */
130
+ readonly name?: string;
131
+ }
132
+ /**
133
+ * Where a download goes when it isn't a path (gap 1): positional writes, reads (for the whole-object check), and the
134
+ * publication. `commit(size)` runs only after the bytes were verified; `discard()` after a mismatch or a give-up.
135
+ */
136
+ export interface Sink {
137
+ /** Stable across runs (the saved ranges are keyed by it). */
138
+ readonly id: string;
139
+ write(offset: number, bytes: Uint8Array): Promise<void>;
140
+ read(offset: number, length: number): Promise<Uint8Array>;
141
+ commit(size: number): Promise<void>;
142
+ discard(): Promise<void>;
143
+ }
144
+ /**
145
+ * Who uploads a key right now, shared by every engine that may upload the same content (several processes, runners,
146
+ * machines): a lease with an expiry. The product supplies it (memoryClaims for one process, kvClaims over its
147
+ * KeyValueStore/Redis, or its own server's create answers).
148
+ *
149
+ * - `acquire`: take the claim if it's free or expired → "acquired" with a token (a takeover of an expired claim also
150
+ * returns what the previous holder recorded: its upload id and part size, so proven parts can be kept); held by
151
+ * someone else and not expired → "held" with its expiry.
152
+ * - `renew`: extend our claim; false = it isn't ours any more (expired and taken over): stop sending.
153
+ * - `record`: note the multipart the holder created (for a later takeover).
154
+ * - `release`: give it up (finished, failed, cancelled). Only the token's holder can.
155
+ */
156
+ export interface ClaimStore {
157
+ acquire(key: string, ttlMs: number): Promise<{
158
+ status: "acquired";
159
+ token: string;
160
+ previous?: ClaimRecord;
161
+ } | {
162
+ status: "held";
163
+ expiresAt: number;
164
+ }>;
165
+ renew(key: string, token: string, ttlMs: number): Promise<boolean>;
166
+ record(key: string, token: string, rec: ClaimRecord): Promise<void>;
167
+ release(key: string, token: string): Promise<void>;
168
+ }
169
+ export interface ClaimRecord {
170
+ uploadId?: string;
171
+ partSize?: number;
172
+ }
@@ -0,0 +1,29 @@
1
+ /**
2
+ * A Signer over HTTP: batches the engine's ops per scope into one POST `{ ops }` → `{ results }` (the SDK's transfer
3
+ * protocol; `@uploadfilm/sdk/server` createSignHandler answers it). UploadFilm's app keeps its own signer (platform.ts,
4
+ * same wire format plus its device token and NotClaimed handling); other products use this one.
5
+ */
6
+ import type { Signer } from "./protocol";
7
+ import { type Clock } from "./timing";
8
+ /** The route answered the batch as a whole with an error (or couldn't be reached: status 0). */
9
+ export declare class SignerError extends Error {
10
+ status: number;
11
+ code?: string | undefined;
12
+ retryable: boolean;
13
+ constructor(message: string, status: number, code?: string | undefined, retryable?: boolean);
14
+ }
15
+ export interface HttpSignerOptions {
16
+ /** The route for a scope, e.g. (scope) => `/api/projects/${scope}/sign`. */
17
+ url: string | ((scope: string) => string);
18
+ /** Auth headers per request (a bearer token…). */
19
+ headers?: () => Record<string, string> | Promise<Record<string, string>>;
20
+ /** Ops issued within this window go in one request (default 40 ms). */
21
+ batchMs?: number;
22
+ /** Most ops per request (default 64, the handler's default limit). */
23
+ maxOps?: number;
24
+ /** Per-request deadline (default 60 s). */
25
+ timeoutMs?: number;
26
+ fetch?: typeof fetch;
27
+ clock?: () => Clock;
28
+ }
29
+ export declare function createHttpSigner(o: HttpSignerOptions): Signer;
@@ -0,0 +1,135 @@
1
+ /**
2
+ * Storage operations for the engine, all brokered by the product's server through a Signer: control calls
3
+ * (create/complete/abort/head/listParts) run server-side; bodies go straight to presigned URLs through the Transport.
4
+ *
5
+ * Moved from UploadFilm's app/src/main/storage.ts (the transport half lives in transports/).
6
+ */
7
+ import { type ErrorAdapter } from "./errors";
8
+ import type { PutReceipt, Signer, Transport, TransferResult, Yieldable } from "./protocol";
9
+ import type { TransferTiming } from "./timing";
10
+ /** `weak`: storage marked the ETag weak (W/"…"). Cloudflare does that when it would gzip the HEAD response
11
+ * (text-like content over ~1 KB); the value is still the object's MD5, but Content-Length may be missing. */
12
+ export type Stat = {
13
+ size: number | null;
14
+ etag: string | null;
15
+ weak?: boolean;
16
+ };
17
+ export declare const stat: (r: {
18
+ size: number | null;
19
+ etag?: string | null;
20
+ }) => Stat;
21
+ /** The server found the same content already stored and copied it to the key: nothing to upload. */
22
+ export type Deduped = {
23
+ deduped: true;
24
+ size: number | null;
25
+ etag: string | null;
26
+ };
27
+ /**
28
+ * What the optional modes add to the transfer protocol (fields a server that doesn't know them ignores; the SDK's
29
+ * createSignHandler implements the SHA-256 ones, see its `checksums` option and docs/platform/TRANSFER-GAPS.md):
30
+ * - create: `checksumAlgorithm: "SHA256"` (the multipart is created with SHA-256 COMPOSITE checksums), `partSize`
31
+ * (the client's proposal), `resumeUploadId` (a multipart this client may continue: its own, or a dead holder's).
32
+ * - part/put: `checksumSha256` (base64): the server signs `x-amz-checksum-sha256` with it.
33
+ * - complete: `parts[].checksumSha256` (base64), sent as each part's ChecksumSHA256.
34
+ * Answers may add: create `partSize` (the server's; wins over the proposal), `resumed: true` (the upload id is an
35
+ * existing multipart, e.g. an expired holder's: its parts are proven and adopted) or `inProgress: { claimExpiresAt }`
36
+ * (someone else uploads this content: wait); complete/head `checksumSha256` (base64, "<b64>-<parts>" for a
37
+ * multipart); listParts `parts[].checksumSha256`.
38
+ */
39
+ export type CreateAnswer = {
40
+ uploadId: string;
41
+ partSize?: number;
42
+ resumed?: boolean;
43
+ } | Deduped | {
44
+ inProgress: {
45
+ claimExpiresAt: number;
46
+ };
47
+ };
48
+ export type CheckedStat = Stat & {
49
+ checksumSha256?: string;
50
+ };
51
+ export type ListedPart = {
52
+ etag: string;
53
+ size?: number;
54
+ checksumSha256?: string;
55
+ };
56
+ export interface StorageOptions {
57
+ signer: Signer;
58
+ transport: Transport;
59
+ timing: TransferTiming;
60
+ /** Turns the signer's own errors into StorageErrors (default: duck-typed status/code/retryable). */
61
+ errors?: ErrorAdapter;
62
+ /** The GETs of `readBack` (default: the runtime's fetch). */
63
+ fetch?: typeof fetch;
64
+ }
65
+ /** What `readBack` read: the stored object's size, ETag (the version it was pinned to) and digests of its bytes. */
66
+ export type ReadBack = {
67
+ size: number;
68
+ etag: string | null;
69
+ sha256: string;
70
+ crc32: number;
71
+ };
72
+ export type Storage = ReturnType<typeof createStorage>;
73
+ /**
74
+ * `proveByReadBack`: an "Exists" / 412 is never settled here by MD5 (ours412); it goes to the engine, which proves the
75
+ * copy by reading it back (EngineCoreOptions.readBack). Without it (other callers), checked by MD5 as before.
76
+ */
77
+ export type WriteMark = {
78
+ proveByReadBack: boolean;
79
+ };
80
+ /** Unwrap a TransferResult or throw a StorageError the engine knows how to retry. */
81
+ export declare function unwrap<R extends TransferResult>(r: TransferResult): Extract<R, {
82
+ ok: true;
83
+ }>;
84
+ export declare function createStorage(o: StorageOptions): {
85
+ createMultipart: (scope: string, key: string, contentType: string, size?: number, counts?: boolean) => Promise<string>;
86
+ createOrDedupe: (scope: string, key: string, contentType: string, size?: number, counts?: boolean, sha256?: string) => Promise<Deduped | {
87
+ uploadId: string;
88
+ }>;
89
+ completeMultipart: (scope: string, key: string, uploadId: string, parts: {
90
+ n: number;
91
+ etag: string;
92
+ }[]) => Promise<{
93
+ recovered?: true | undefined;
94
+ size: number | null;
95
+ etag: string | null;
96
+ weak?: boolean;
97
+ }>;
98
+ abortMultipart: (scope: string, key: string, uploadId: string) => Promise<void | undefined>;
99
+ head: (scope: string, key: string) => Promise<Stat>;
100
+ listParts: (scope: string, key: string, uploadId: string) => Promise<Map<number, string>>;
101
+ listUploads: (scope: string, key: string) => Promise<{
102
+ uploadId: string;
103
+ initiated?: string;
104
+ }[]>;
105
+ uploadPart: (scope: string, key: string, uploadId: string, partNumber: number, body: Uint8Array, contentMd5: string, onProgress: (sent: number) => void, timeoutMs: number, y?: Yieldable) => Promise<string>;
106
+ putObject: (scope: string, key: string, body: Uint8Array, contentType: string, onProgress?: (sent: number) => void, timeoutMs?: number, contentMd5?: string, counts?: boolean, y?: Yieldable, sha256?: string, w?: WriteMark) => Promise<string>;
107
+ transport: Transport;
108
+ createSession: (scope: string, key: string, contentType: string, size: number, counts: boolean, x: {
109
+ sha256?: string;
110
+ checksumAlgorithm?: "SHA256";
111
+ partSize?: number;
112
+ resumeUploadId?: string;
113
+ }) => Promise<CreateAnswer>;
114
+ uploadPartChecked: (scope: string, key: string, uploadId: string, partNumber: number, body: Uint8Array, contentMd5: string, checksumSha256: string, onProgress: (sent: number) => void, timeoutMs: number, y?: Yieldable) => Promise<PutReceipt>;
115
+ putObjectChecked: (scope: string, key: string, body: Uint8Array, contentType: string, onProgress: (sent: number) => void, timeoutMs: number, contentMd5: string, checksumSha256: string, counts: boolean, y?: Yieldable, sha256?: string) => Promise<{
116
+ receipt: PutReceipt;
117
+ } | {
118
+ deduped: Deduped;
119
+ } | {
120
+ exists: CheckedStat;
121
+ }>;
122
+ listPartsChecked: (scope: string, key: string, uploadId: string) => Promise<Map<number, ListedPart>>;
123
+ completeChecked: (scope: string, key: string, uploadId: string, parts: {
124
+ n: number;
125
+ etag: string;
126
+ checksumSha256: string;
127
+ }[]) => Promise<CheckedStat>;
128
+ headWithChecksum: (scope: string, key: string) => Promise<CheckedStat>;
129
+ readBack: (scope: string, key: string, want: number, sha256Stream: () => {
130
+ update(b: Uint8Array): unknown;
131
+ digest(): Uint8Array;
132
+ }, crc32: (b: Uint8Array, prev?: number) => number) => Promise<ReadBack | null>;
133
+ };
134
+ /** Base64 → hex without Buffer (works in any runtime). */
135
+ export declare function b64ToHex(b64: string): string;
@@ -0,0 +1,132 @@
1
+ /**
2
+ * Every timing constant the transfer engine and its transports read, and the clock they read time from.
3
+ *
4
+ * The engine never copies a value into a module constant: it reads `timing.T.NAME` at the moment it needs it, so a
5
+ * product (or a test) may change values after the engine was created. A product that already keeps its own timing
6
+ * table with these names (UploadFilm's app/src/main/timing.ts) passes that very object, so one `configureTiming()`
7
+ * compresses the product and the engine together.
8
+ *
9
+ * Moved from UploadFilm's app/src/main/timing.ts (the transfer half; the product's own loops stay there).
10
+ */
11
+ export declare const TRANSFER_TIMING_DEFAULTS: {
12
+ /** backoff(): base and cap of the exponential retry delay (± 25 % jitter). */
13
+ readonly RETRY_BASE_MS: 1000;
14
+ readonly RETRY_CAP_MS: 60000;
15
+ /** backoff(): exponent cap (2^6 × 1 s = 64 s, so the 60 s cap wins). Count, not scaled. */
16
+ readonly RETRY_MAX_EXP: 6;
17
+ /** Small objects: non-transient failures before the item fails (`a > 25`). Count. */
18
+ readonly SMALL_MAX_ATTEMPTS: 25;
19
+ /** Parts: non-transient failures of one part before the item fails (`a > 40`). Count. */
20
+ readonly PART_MAX_ATTEMPTS: 40;
21
+ /**
22
+ * Reset-fast (perf-lab finding 1, docs/platform/TRANSFER-PERF.md): a part cut by a network-class failure (status 0:
23
+ * reset, refused, timeout, stall) while some other request succeeded within RESET_RETRY_WINDOW_MS (the link is up) is
24
+ * retried after RESET_RETRY_MS ± 50 % instead of the exponential backoff, at most RESET_FAST_RETRIES times in a row;
25
+ * then the backoff as before. Storage answers (4xx/5xx/429), other units and a link that is really down are unchanged.
26
+ */
27
+ readonly RESET_RETRY_MS: 1000;
28
+ readonly RESET_RETRY_WINDOW_MS: 10000;
29
+ /** Count, not scaled. */
30
+ readonly RESET_FAST_RETRIES: 12;
31
+ /** Single PUT (small objects) total timeout. */
32
+ readonly SMALL_PUT_TIMEOUT_MS: 600000;
33
+ /** Part PUT timeout = max(PART_TIMEOUT_MIN_MS, bytes / PART_TIMEOUT_FLOOR_BPS s). */
34
+ readonly PART_TIMEOUT_MIN_MS: 300000;
35
+ /** Bytes/s floor used to size a part's timeout. A rate, not scaled (the computed time is). */
36
+ readonly PART_TIMEOUT_FLOOR_BPS: 16000;
37
+ readonly ENGINE_TICK_MS: 1000;
38
+ readonly TUNE_INTERVAL_MS: 5000;
39
+ readonly RATE_WINDOW_MS: 8000;
40
+ readonly TUNE_SETTLE_AFTER_ERROR_MS: 20000;
41
+ readonly ERROR_BURST_WINDOW_MS: 10000;
42
+ /** looksOffline(): every request failing with a network-class error for this long. */
43
+ readonly OFFLINE_NO_BYTES_MS: 60000;
44
+ /** An item refused for quota looks again after this long. */
45
+ readonly QUOTA_REFRESH_MS: number;
46
+ /** A PUT that has sent nothing new for this long is aborted ("stalled"). */
47
+ readonly STALL_MS: 90000;
48
+ readonly STALL_POLL_MS: 400;
49
+ /** A PUT queued inside a capped pool (Electron's 6 per host) is given up only if nothing on the host moved for this long. */
50
+ readonly PUT_QUEUE_MAX_MS: number;
51
+ /** Body handed off, no response for this long plus the drain allowance → abort, retry. */
52
+ readonly PUT_RESPONSE_TIMEOUT_MS: 120000;
53
+ /** Upper bound on bytes reported sent that may still be in send buffers. Bytes, not scaled. */
54
+ readonly PUT_SEND_BUFFER_BYTES: number;
55
+ /** A PUT past its size-based timeout is aborted only if it moved slower than this (bytes/s) over its last window. */
56
+ readonly PUT_MIN_AVG_BPS: 1000;
57
+ /** Window over which that speed is measured. */
58
+ readonly PUT_SPEED_WINDOW_MS: number;
59
+ /** Slowest whole uplink (bytes/s) at which PUTs are never cut while their buffered tail drains. */
60
+ readonly PUT_FLOOR_LINK_BPS: 8000;
61
+ /** undici transport: TCP/TLS connect bound. */
62
+ readonly PUT_CONNECT_TIMEOUT_MS: 30000;
63
+ readonly DL_FETCH_TIMEOUT_MS: 30000;
64
+ readonly DL_STALL_MS: 30000;
65
+ readonly DL_RETRY_BASE_MS: 1000;
66
+ readonly DL_RETRY_CAP_MS: 60000;
67
+ /** Non-network failures before a download fails. Count, not scaled. */
68
+ readonly DL_MAX_TRIES: 8;
69
+ };
70
+ export type TransferTimingName = keyof typeof TRANSFER_TIMING_DEFAULTS;
71
+ /** The values the engine reads. A product's table may hold more names (it is passed as is). */
72
+ /** Names a product's own table may lack (added later): read with tv(), which falls back to the default (scaled). */
73
+ type LaterName = "PUT_CONNECT_TIMEOUT_MS" | "RESET_RETRY_MS" | "RESET_RETRY_WINDOW_MS" | "RESET_FAST_RETRIES";
74
+ export type TransferTimingValues = {
75
+ [K in Exclude<TransferTimingName, LaterName>]: number;
76
+ } & {
77
+ [K in LaterName]?: number;
78
+ };
79
+ export type TimerHandle = unknown;
80
+ export interface Clock {
81
+ /** Wall-clock milliseconds (records, claims, expiry). */
82
+ now(): number;
83
+ /**
84
+ * Monotonic milliseconds for elapsed-time checks (stall watchdogs, deadlines): never jumps when the wall clock does
85
+ * (wake from sleep, NTP step). Optional: a clock without it (a test's fake clock) is read through `now()` instead,
86
+ * so a fake clock drives the watchdogs exactly as before (RC-T7).
87
+ */
88
+ mono?(): number;
89
+ setTimeout(fn: () => void, ms: number): TimerHandle;
90
+ clearTimeout(h: TimerHandle): void;
91
+ setInterval(fn: () => void, ms: number): TimerHandle;
92
+ clearInterval(h: TimerHandle): void;
93
+ /** An AbortSignal that fires after `ms` (for fetch). */
94
+ timeoutSignal(ms: number): AbortSignal;
95
+ }
96
+ /** The real clock. Looks the globals up on every call. */
97
+ export declare const realClock: Clock;
98
+ /**
99
+ * What the engine and transports read time and limits from. `T` is read live; `scale()` is the duration multiplier
100
+ * (rates are divided by it so a compressed test sees proportionally fast links); `clock()` is looked up per call.
101
+ */
102
+ export interface TransferTiming {
103
+ T: TransferTimingValues;
104
+ scale(): number;
105
+ clock(): Clock;
106
+ }
107
+ /**
108
+ * A timing table with the defaults, `scale` applied to every duration (`*_MS`), then `overrides` set exactly.
109
+ * Products with their own table pass `{ T: theirTable, scale, clock }` instead.
110
+ */
111
+ export declare function createTiming(opts?: {
112
+ scale?: number;
113
+ overrides?: Partial<TransferTimingValues>;
114
+ clock?: Clock;
115
+ }): TransferTiming;
116
+ /** Read a value that an older product table may lack (added after it was written): its default then. */
117
+ export declare const tv: (t: TransferTiming, name: TransferTimingName) => number;
118
+ /** A clock's monotonic time: mono() when it has one, else now() (the same override point for fake clocks). */
119
+ export declare const monoOf: (c: Clock) => number;
120
+ /** Clock helpers over a TransferTiming (each looks the clock up per call, as the product's helpers do). */
121
+ export declare const clockOf: (t: TransferTiming) => {
122
+ now: () => number;
123
+ /** Monotonic time for elapsed-time checks: the clock's mono(), or its now() when it has none (fake clocks). */
124
+ mono: () => number;
125
+ every: (fn: () => void, ms: number) => unknown;
126
+ clearEvery: (h: TimerHandle) => void;
127
+ setTimer: (fn: () => void, ms: number) => unknown;
128
+ clearTimer: (h: TimerHandle) => void;
129
+ sleep: (ms: number) => Promise<void>;
130
+ timeoutSignal: (ms: number) => AbortSignal;
131
+ };
132
+ export {};
@@ -0,0 +1,62 @@
1
+ import { type Transport } from "../protocol";
2
+ import { type TransferTiming } from "../timing";
3
+ /** The parts of Electron's ClientRequest this transport uses. */
4
+ export interface NetRequestLike {
5
+ setHeader(k: string, v: string): void;
6
+ getUploadProgress(): {
7
+ active: boolean;
8
+ started: boolean;
9
+ current: number;
10
+ total?: number;
11
+ };
12
+ abort(): void;
13
+ end(body?: Uint8Array): void;
14
+ on(ev: "response", fn: (res: NetResponseLike) => void): unknown;
15
+ on(ev: "error", fn: (e: Error) => void): unknown;
16
+ }
17
+ export interface NetResponseLike {
18
+ statusCode: number;
19
+ headers: Record<string, string | string[] | undefined>;
20
+ on(ev: "data", fn: (c: Uint8Array) => void): unknown;
21
+ on(ev: "end", fn: () => void): unknown;
22
+ on(ev: "error", fn: (e: Error) => void): unknown;
23
+ }
24
+ export interface NetLike {
25
+ request(o: {
26
+ method: string;
27
+ url: string;
28
+ cache?: string;
29
+ useSessionCookies?: boolean;
30
+ }): NetRequestLike;
31
+ }
32
+ /**
33
+ * Electron's net (Chromium) opens at most 6 connections per host, and all our PUTs go to one host
34
+ * (R2 is HTTP/1.1 only). When the engine runs more parts than that, the rest wait inside Chromium,
35
+ * with getUploadProgress() = { active: false, started: false, current: 0 } and no events. So the stall
36
+ * and overall clocks of a request only start once it is really sending: Chromium says the upload
37
+ * started, bytes move, or fewer than POOL_PER_HOST of our older requests to that host are still open
38
+ * (sockets are handed out in order, so it has one, even if it is still connecting: a connect that hangs
39
+ * is still caught by the stall timeout). Until then it is "queued", bounded separately by
40
+ * PUT_QUEUE_MAX_MS. (Measured on Electron 45: 20 concurrent requests to one host → 6 sockets, 4 waves,
41
+ * audit RESEARCH-CLAIMS.md 1b; queued requests report started=false, current=0 until a socket frees.)
42
+ */
43
+ export declare const POOL_PER_HOST = 6;
44
+ export interface ElectronNetTransport extends Transport {
45
+ /** The supervised PUT (exported for tests: same signature as the transport's put). */
46
+ putTo: Transport["put"];
47
+ send: NonNullable<Transport["send"]>;
48
+ }
49
+ export declare function createElectronNetTransport(net: NetLike, timing: TransferTiming): ElectronNetTransport;
50
+ /** UTF-8 of response chunks (Buffers in Electron/Node, Uint8Arrays anywhere). */
51
+ export declare function utf8(chunks: Uint8Array[]): string;
52
+ /** The part of Electron's `powerSaveBlocker` the keep-awake helper uses. */
53
+ export interface PowerSaveBlockerLike {
54
+ start(type: "prevent-app-suspension" | "prevent-display-sleep"): number;
55
+ stop(id: number): void;
56
+ }
57
+ /**
58
+ * Host power hook (RC-T7 "host-power"): an `onBusyChange` for createTransferEngine that holds a power assertion
59
+ * ("prevent-app-suspension": the system stays awake, the display may sleep) while the engine has work, and releases
60
+ * it when it has none. `createTransferEngine({ …, onBusyChange: electronKeepAwake(powerSaveBlocker) })`.
61
+ */
62
+ export declare function electronKeepAwake(psb: PowerSaveBlockerLike, type?: "prevent-app-suspension" | "prevent-display-sleep"): (busy: boolean) => void;
@@ -0,0 +1,15 @@
1
+ import { type Transport } from "../protocol";
2
+ import { type TransferTiming } from "../timing";
3
+ export interface FetchTransportOptions {
4
+ fetch?: typeof fetch;
5
+ allowedOrigins?: string[];
6
+ /**
7
+ * Stream the body (supervised, live progress) instead of sending one buffer. Default: on where the runtime is Node
8
+ * (its fetch streams a fixed-length body), off elsewhere. Only force it on for a fetch that sends a ReadableStream
9
+ * body with the given Content-Length (never chunked).
10
+ */
11
+ streamBody?: boolean;
12
+ }
13
+ export declare function createFetchTransport(timing: TransferTiming, opts?: FetchTransportOptions): Transport & {
14
+ send: NonNullable<Transport["send"]>;
15
+ };
@@ -0,0 +1,12 @@
1
+ /**
2
+ * Retry-After on a storage answer (RC-T4): 429 SlowDown and 503 come with "Retry-After: <seconds>" or an HTTP date.
3
+ * The transports attach it to the PUT's StorageError as `retryAfterMs`, so the engine can wait at least that long
4
+ * before the next attempt instead of its own (shorter) backoff.
5
+ */
6
+ import type { StorageError } from "../errors";
7
+ /** Milliseconds to wait, or undefined when there is no usable header. Capped at `capMs` (a bogus far date). */
8
+ export declare function parseRetryAfter(v: string | string[] | null | undefined, capMs?: number, nowMs?: number): number | undefined;
9
+ /** The StorageError with `retryAfterMs` set when the answer had a usable Retry-After (only for 429/503 answers). */
10
+ export declare function withRetryAfter<E extends StorageError>(e: E, status: number, header: string | string[] | null | undefined): E & {
11
+ retryAfterMs?: number;
12
+ };
@@ -0,0 +1,72 @@
1
+ import { type Transport } from "../protocol";
2
+ import { type TransferTiming } from "../timing";
3
+ /**
4
+ * The parts of undici this transport uses (structural, so any undici ≥ 6 fits). The real module goes in as it is
5
+ * (`createUndiciTransport(undici, timing)`, no cast). `O` is the module's own request-options type, inferred from
6
+ * the module passed in: undici's typings are narrower than what it accepts at run time (its `body` type has no async
7
+ * iterable, which undici documents and this transport sends), so the transport builds UndiciRequestOptions and hands
8
+ * them over as `O` rather than making callers cast the module.
9
+ */
10
+ export interface UndiciLike<O = UndiciRequestOptions> {
11
+ Agent: new (o: Record<string, unknown>) => unknown;
12
+ /**
13
+ * undici's connector factory (every undici ≥ 6 exports it): wrapped so a socket option that throws can't kill us.
14
+ * A method (bivariant), so the real module's narrower connector types fit without a cast.
15
+ */
16
+ buildConnector?(o: {
17
+ timeout?: number;
18
+ }): (o: never, cb: (e: Error | null, s: unknown) => void) => void;
19
+ request(url: string, o: O): Promise<UndiciResponse>;
20
+ }
21
+ /** What the transport passes to `undici.request`. */
22
+ export interface UndiciRequestOptions {
23
+ method: "PUT";
24
+ headers: Record<string, string>;
25
+ /** The whole body, or a one-shot async iterable of CHUNK slices (progress follows the socket). */
26
+ body: Uint8Array | AsyncIterable<Uint8Array>;
27
+ signal: AbortSignal;
28
+ /** The keep-alive Agent, or the override from UndiciTransportOptions.dispatcher / setDispatcher. */
29
+ dispatcher: unknown;
30
+ }
31
+ /** The parts of undici's response the transport reads. */
32
+ export interface UndiciResponse {
33
+ statusCode: number;
34
+ headers: Record<string, string | string[] | undefined>;
35
+ body: {
36
+ text(): Promise<string>;
37
+ destroy(): unknown;
38
+ };
39
+ }
40
+ /**
41
+ * `unknown` when the module's own options type `O` takes the options the transport sends (dispatcher aside, typed by
42
+ * each module its own way), `never` otherwise: a `request(url, o: string)` is refused at compile time.
43
+ */
44
+ export type UndiciOptionsAccepted<O> = {
45
+ method: "PUT";
46
+ headers: Record<string, string>;
47
+ body: Uint8Array;
48
+ signal: AbortSignal;
49
+ } extends OmitEach<NonNullable<O>, "dispatcher"> ? unknown : never;
50
+ /** Omit applied to each member of a union (plain Omit merges a union's members into one type, review round 2). */
51
+ type OmitEach<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never;
52
+ /** Each PUT's life, for observers (tests' net logs, race reports). "sending" = its first body byte goes out. */
53
+ export type PutEvent = {
54
+ id: symbol;
55
+ url: string;
56
+ kind: "start" | "sending" | "aborted" | "response" | "error";
57
+ status?: number;
58
+ reason?: string;
59
+ };
60
+ export interface UndiciTransportOptions {
61
+ /** Send through another dispatcher (a test's virtual link, a recording wrapper). Default: one keep-alive Agent. */
62
+ dispatcher?: unknown;
63
+ /** Only these origins may be PUT to (scheme://host[:port]); anything else is refused before a byte is sent. */
64
+ allowedOrigins?: string[];
65
+ }
66
+ export interface UndiciTransport extends Transport {
67
+ send: NonNullable<Transport["send"]>;
68
+ watchers: Set<(e: PutEvent) => void>;
69
+ setDispatcher(d: unknown | null): void;
70
+ }
71
+ export declare function createUndiciTransport<O = UndiciRequestOptions>(undici: UndiciLike<O> & UndiciOptionsAccepted<O>, timing: TransferTiming, opts?: UndiciTransportOptions): UndiciTransport;
72
+ export {};