@uploadfilm/sdk 0.0.0-stage → 0.1.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 (218) hide show
  1. package/LICENSE +4 -0
  2. package/README.md +509 -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 +336 -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 +66 -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 +318 -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 +150 -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 +21 -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 +93 -0
  161. package/dist/server/testing/fake-r2.d.ts +390 -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 +167 -0
  165. package/dist/server/transfer/keys.d.ts +45 -0
  166. package/dist/server/transfer/protocol.d.ts +141 -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 +256 -0
  196. package/dist/transfer/download.d.ts +192 -0
  197. package/dist/transfer/engine.d.ts +382 -0
  198. package/dist/transfer/errors.d.ts +50 -0
  199. package/dist/transfer/index.d.ts +39 -0
  200. package/dist/transfer/integrity.d.ts +93 -0
  201. package/dist/transfer/limits.d.ts +34 -0
  202. package/dist/transfer/node.d.ts +63 -0
  203. package/dist/transfer/pool.d.ts +83 -0
  204. package/dist/transfer/protocol.d.ts +167 -0
  205. package/dist/transfer/signer.d.ts +29 -0
  206. package/dist/transfer/storage.d.ts +110 -0
  207. package/dist/transfer/timing.d.ts +132 -0
  208. package/dist/transfer/transports/electronNet.d.ts +62 -0
  209. package/dist/transfer/transports/fetch.d.ts +15 -0
  210. package/dist/transfer/transports/retryAfter.d.ts +12 -0
  211. package/dist/transfer/transports/undici.d.ts +72 -0
  212. package/dist/transfer/tuner.d.ts +56 -0
  213. package/dist/zip/index.d.ts +13 -0
  214. package/dist/zip/layout.d.ts +129 -0
  215. package/dist/zip/names.d.ts +34 -0
  216. package/dist/zip/plan.d.ts +115 -0
  217. package/dist/zip/sw.d.ts +7 -0
  218. package/package.json +265 -4
@@ -0,0 +1,63 @@
1
+ import { Worker } from "node:worker_threads";
2
+ import type { Md5Stream } from "./integrity";
3
+ import type { ByteSource, Hasher, SourceStamp } from "./protocol";
4
+ export declare const nodeHasher: Hasher;
5
+ export declare const nodeMd5: () => Md5Stream;
6
+ export interface WorkerHasherOptions {
7
+ /** Worker threads (default 2: perf-lab's measured setting). */
8
+ workers?: number;
9
+ /** Called with each worker thread started (diagnostics and tests: a test kills one to prove the failover). */
10
+ onSpawn?(w: Worker): void;
11
+ }
12
+ /**
13
+ * nodeHasher with parts' MD5 + CRC-32 in worker threads (perf-lab finding 2, docs/platform/TRANSFER-PERF.md): the
14
+ * engine's main thread (Electron's main process in a Mac app) no longer spends ~1.1 s per GB in 25 ms blocks hashing.
15
+ * Same digests as nodeHasher (property-tested). Workers start on the first part and are unref'd (they never keep a
16
+ * process alive); `close()` terminates them (the engine's stop() calls it) and the next part starts them again. A
17
+ * worker that errors or exits fails its parts' digests (the engine then hashes those on its own thread) and is
18
+ * replaced on the next part; after 3 such losses the hasher stays on the main thread (`degraded`).
19
+ */
20
+ export declare function createWorkerHasher(o?: WorkerHasherOptions): Hasher & {
21
+ readonly degraded: boolean;
22
+ close(): Promise<void>;
23
+ };
24
+ export declare const nodeSha256Hex: (b: Uint8Array) => string;
25
+ /**
26
+ * The file as it is now: device, inode, size, mtime. Two stamps of the same file are equal (sameStamp); a card pulled
27
+ * and another mounted at the same path (same name, size, even mtime) is a different device/inode.
28
+ */
29
+ export type Stamp = {
30
+ dev: number;
31
+ ino: number;
32
+ size: number;
33
+ mtimeMs: number;
34
+ ctimeMs?: number;
35
+ birthtimeMs?: number;
36
+ };
37
+ export declare function stampOf(src: string): Stamp | null;
38
+ /**
39
+ * Same file (device, inode, size, mtime, and birth time when both stamps have one: another card with the same names,
40
+ * size and mtime in the same reader can get the same device number and inode, but not the same birth time). Takes any
41
+ * SourceStamp (hosts get them in callbacks); only files ever match. A chmod or an xattr doesn't make it another file.
42
+ */
43
+ export declare const sameStamp: (a: SourceStamp | null | undefined, b: SourceStamp | null | undefined) => boolean;
44
+ /**
45
+ * sameStamp and the same ctime (when both have one): the engine's check that the bytes it read are still the file's
46
+ * (RL-2: a rewrite that put the mtime back keeps dev/inode/size/mtime, not ctime). A metadata-only change (chmod,
47
+ * xattr) fails it too; the engine then proves the content again rather than trusting it.
48
+ */
49
+ export declare const sameContentStamp: (a: SourceStamp | null | undefined, b: SourceStamp | null | undefined) => boolean;
50
+ /** fs/promises `open`, looked up per call (so a test or product may wrap it). */
51
+ export declare const openFile: (path: string, flags?: string) => Promise<import("node:fs/promises").FileHandle>;
52
+ /** Two source stamps describe the same source: files by device/inode/size/mtime, other sources by id/size(/mtime). */
53
+ export declare function sameSource(a: SourceStamp | null | undefined, b: SourceStamp | null | undefined): boolean;
54
+ /**
55
+ * A local file as a ByteSource (identity = device/inode/size/mtime). The engine reads plain paths itself (the same
56
+ * calls as before ByteSource existed); this is for code that wants a ByteSource for a file, e.g. to mix files and
57
+ * buffers behind one interface. `size` is the file's size when it was opened.
58
+ */
59
+ export declare function fileSource(path: string): ByteSource;
60
+ /** Bytes in memory as a ByteSource (tests, generated objects). `id` defaults to the bytes' SHA-256. */
61
+ export declare function bufferSource(bytes: Uint8Array, id?: string): ByteSource;
62
+ /** sameSource with sameContentStamp for files (the engine's content checks: a rewrite with its mtime put back fails). */
63
+ export declare function sameContentSource(a: SourceStamp | null | undefined, b: SourceStamp | null | undefined): boolean;
@@ -0,0 +1,83 @@
1
+ /**
2
+ * The part pool as a standalone API (gap 5): one pool of connections shared by every transfer of a process, split
3
+ * between lanes, sized by a tuner. Jobs are functions; the pool only decides when each one starts.
4
+ *
5
+ * const pool = createPartPool({
6
+ * lanes: [{ name: "poster", first: true }, { name: "original", minShare: 2 / 3 }, { name: "proxy", yieldable: true }],
7
+ * connections: { min: 4, start: 8, max: 32 },
8
+ * socketsPerHost: transport.socketsPerHost,
9
+ * });
10
+ * await pool.run("original", signal, (y) => transport.put(url, headers, body, onProgress, timeoutMs, y));
11
+ * pool.sample(bytes); // feed the tuner
12
+ *
13
+ * Lane rules (the same as the engine core's, through the same laneShare()):
14
+ * - `first` lanes start before anything else;
15
+ * - the primary lane (`minShare`) keeps at least ⌈minShare × sockets⌉ of the connections while it has jobs queued
16
+ * (AGENTS.md: originals keep ⌈2/3⌉);
17
+ * - borrower lanes run in what the primary leaves; while it has nothing queued but jobs running, at most
18
+ * ⌊running × (1 − minShare) / minShare⌋ (laneShare: half as many as the primary's at 2/3), and every idle connection
19
+ * once it has neither;
20
+ * `yieldable` borrowers hand their place back: a job that passed the Yieldable it was given to its transport is
21
+ * cancelled while still queued in the stack (`cancelIfQueued`), rejects with YIELDED, and is queued again by the pool;
22
+ * - `maxActive`: at most this many jobs of the lane at once.
23
+ * Or strict priorities (cloud-transfer's CONTEXT > SMALL > ATTACHMENT): lanes with `priority` (lower first) start in
24
+ * that order, nothing reserved.
25
+ *
26
+ * A queued job consumes nothing: its function isn't called (no request timeout or retry budget runs) until it starts.
27
+ * Aborting a queued job removes it from the queue at once (rejects with an AbortError-like `Cancelled`).
28
+ *
29
+ * Tuners (policy): "uploadfilm" (createTuner: slow start then ±2 hill climbing every TUNE_INTERVAL_MS, ×0.7 on error
30
+ * bursts) or "halve-on-error" (createHalvingTuner: ±1 every tuneIntervalMs while work is queued, halve on every
31
+ * retryable error). `fail()` reports an error to the tuner; `sample(bytes)` reports throughput.
32
+ */
33
+ import { StorageError } from "./errors";
34
+ import { type LaneSpec } from "./engine";
35
+ import type { Yieldable } from "./protocol";
36
+ import { type TransferTiming } from "./timing";
37
+ export interface PoolLane extends LaneSpec {
38
+ /** Strict order: lanes with a priority start lowest first (and reserve nothing). */
39
+ priority?: number;
40
+ }
41
+ export interface PartPoolOptions {
42
+ lanes: PoolLane[];
43
+ connections?: {
44
+ min?: number;
45
+ start?: number;
46
+ max?: number;
47
+ };
48
+ /** The transport's cap per host (Electron's net: 6): the pool never runs more than this at once. */
49
+ socketsPerHost?: number;
50
+ policy?: "uploadfilm" | "halve-on-error";
51
+ /** halve-on-error: how often the tuner moves (default 2 s) and how long an error holds it (default 5 s). */
52
+ tuneIntervalMs?: number;
53
+ errorCooldownMs?: number;
54
+ /** uploadfilm policy: its timing table and clock (default createTiming()). */
55
+ timing?: TransferTiming;
56
+ }
57
+ export declare class PoolCancelled extends Error {
58
+ readonly code = "Cancelled";
59
+ constructor();
60
+ }
61
+ export declare function createPartPool(o: PartPoolOptions): {
62
+ /** Run `job` in `lane` when the pool has room for it. `job` gets a Yieldable to pass to its transport. */
63
+ run<T>(lane: string, signal: AbortSignal | undefined, job: (y: Yieldable) => Promise<T>): Promise<T>;
64
+ /** `bytes` more went out (feeds the tuner). */
65
+ sample(bytes: number, at?: number): void;
66
+ /** A job failed with a retryable error. */
67
+ fail(): void;
68
+ /** uploadfilm policy: measure the rate (every ENGINE_TICK_MS) and tune (every TUNE_INTERVAL_MS). */
69
+ start(): void;
70
+ stop(): void;
71
+ /** The tuner's target (before the per-host cap). */
72
+ readonly connections: number;
73
+ readonly active: number;
74
+ readonly queued: number;
75
+ activeIn: (name: string) => number;
76
+ /** Jobs of a lane waiting to start. */
77
+ queuedIn: (name: string) => number;
78
+ /** Hold the target (tests; uploadfilm policy only). */
79
+ pin(n: number | null): void;
80
+ };
81
+ export type PartPool = ReturnType<typeof createPartPool>;
82
+ /** A job's transport answered "gave its place back" (re-exported for job authors). */
83
+ export declare const yielded: () => StorageError;
@@ -0,0 +1,167 @@
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
+ /**
26
+ * What storage answered to a PUT that worked: its ETag (quotes stripped, may be "") and the checksum headers it sent
27
+ * back, as received. A header storage sent more than once is joined with ", " (so it never passes as one valid value);
28
+ * one it didn't send is absent.
29
+ */
30
+ export interface PutReceipt {
31
+ etag: string;
32
+ checksums: {
33
+ /** `x-amz-checksum-sha256` (base64 of the 32-byte digest, as S3/R2 send it). */
34
+ sha256?: string;
35
+ /** `x-amz-checksum-crc32` (base64). */
36
+ crc32?: string;
37
+ };
38
+ }
39
+ /** The receipt of an answer's headers (any casing; arrays = the header was repeated). */
40
+ export declare function receiptOf(etag: string, header: (name: string) => string | string[] | null | undefined): PutReceipt;
41
+ /** A header from a Node/Electron-style record (names in any case; undefined when absent). */
42
+ export declare function headerOf(h: Record<string, string | string[] | undefined> | undefined, name: string): string | string[] | undefined;
43
+ /**
44
+ * Sends one PUT. `put` resolves with the response ETag (quotes stripped, may be ""); `send` (same arguments) with the
45
+ * whole receipt: the ETag plus the checksum headers storage answered with. Both reject with a StorageError (status 0
46
+ * for no answer). `onProgress(sent)` reports body bytes the stack accepted, only ever growing. `timeoutMs`: from when
47
+ * the request really starts, the point after which a part is judged on its recent speed.
48
+ *
49
+ * `send` is optional so transports written for an older SDK keep working in the default MD5 mode; SHA-256 mode needs
50
+ * it and refuses (fails closed) on a transport without it. The SDK's three transports have both.
51
+ */
52
+ export interface Transport {
53
+ put(url: string, headers: Record<string, string>, body: Uint8Array, onProgress: (sent: number) => void, timeoutMs: number, y?: Yieldable): Promise<string>;
54
+ send?(url: string, headers: Record<string, string>, body: Uint8Array, onProgress: (sent: number) => void, timeoutMs: number, y?: Yieldable): Promise<PutReceipt>;
55
+ /**
56
+ * Connections the stack opens per host at most (Electron's net: 6). Requests beyond it wait inside the stack, so
57
+ * the engine's lanes split this many, not its own target. Infinity (undici, fetch in Node) = no cap.
58
+ */
59
+ readonly socketsPerHost: number;
60
+ /** Short name for logs and race tables ("electron-net", "undici", "fetch"). */
61
+ readonly name: string;
62
+ }
63
+ /** md5 (16 bytes) and zlib's crc32 of a buffer; crc32 continues from `prev` when given. */
64
+ export interface Hasher {
65
+ md5(b: Uint8Array): Uint8Array;
66
+ crc32(b: Uint8Array, prev?: number): number;
67
+ /** SHA-256 (32 bytes). Needed for `integrity: "sha256"` (nodeHasher has it). */
68
+ sha256?(b: Uint8Array): Uint8Array;
69
+ /** An incremental SHA-256 (for hashing a whole source in chunks). */
70
+ sha256Stream?(): {
71
+ update(b: Uint8Array): unknown;
72
+ digest(): Uint8Array;
73
+ };
74
+ /**
75
+ * A part's MD5 and CRC-32 off the caller's thread (createWorkerHasher: a worker thread). Preferred by the engine for
76
+ * multipart parts when present (small objects still use md5/crc32). The answer must be md5(b), crc32(b), and `body`:
77
+ * the same bytes, which the engine then sends. `transfer: true`: `b` is the engine's own buffer and may be handed off
78
+ * (detached) to the worker and back; otherwise `b` must be left intact (copy it). A rejection is not an error of the
79
+ * part: the engine reads the part again and hashes it with md5/crc32.
80
+ */
81
+ digestPart?(b: Uint8Array, o?: {
82
+ transfer?: boolean;
83
+ }): Promise<{
84
+ md5: Uint8Array;
85
+ crc: number;
86
+ body: Uint8Array;
87
+ }>;
88
+ /** Release what the hasher holds (worker threads). The engine's stop() calls it; the hasher works again after. */
89
+ close?(): Promise<void> | void;
90
+ }
91
+ /**
92
+ * What a source is right now, for "is it still the same bytes?". Files: device, inode, size, mtime (`Stamp`, from
93
+ * node.ts). Anything else: an `id` that changes when the content does (a content digest, a blob version, an object's
94
+ * ETag) and the size. Two stamps are the same source only if they are the same kind and every field matches.
95
+ */
96
+ export type SourceStamp = {
97
+ dev: number;
98
+ ino: number;
99
+ size: number;
100
+ mtimeMs: number;
101
+ ctimeMs?: number;
102
+ birthtimeMs?: number;
103
+ } | {
104
+ id: string;
105
+ size: number;
106
+ mtimeMs?: number;
107
+ };
108
+ /**
109
+ * Bytes to upload that aren't (only) a local path: a buffer, a browser File, a private partial file, a remote object.
110
+ *
111
+ * - `size`: the length the upload is cut from.
112
+ * - `read(offset, length)`: exactly `length` bytes at `offset`. Fewer is a failure (IntegrityError: never sent). The
113
+ * bytes answered must not change afterwards (a fresh buffer, or one the source no longer writes): the engine hashes
114
+ * what it got and sends it, and reads of other parts run in parallel, so a reader that refills one buffer for every
115
+ * read could have one part's bytes stored as another's.
116
+ * - `identity()`: see SourceStamp. Without it the engine can't tell whether a source is still the one a saved
117
+ * multipart came from: resuming such a multipart is "unknown" (never "match"); within one session the same
118
+ * ByteSource object counts as the same source.
119
+ */
120
+ export interface ByteSource {
121
+ readonly size: number;
122
+ read(offset: number, length: number, signal?: AbortSignal): Promise<Uint8Array>;
123
+ identity?(): Promise<SourceStamp | null>;
124
+ /** For messages ("<name>: …"); never shown with URLs. */
125
+ readonly name?: string;
126
+ }
127
+ /**
128
+ * Where a download goes when it isn't a path (gap 1): positional writes, reads (for the whole-object check), and the
129
+ * publication. `commit(size)` runs only after the bytes were verified; `discard()` after a mismatch or a give-up.
130
+ */
131
+ export interface Sink {
132
+ /** Stable across runs (the saved ranges are keyed by it). */
133
+ readonly id: string;
134
+ write(offset: number, bytes: Uint8Array): Promise<void>;
135
+ read(offset: number, length: number): Promise<Uint8Array>;
136
+ commit(size: number): Promise<void>;
137
+ discard(): Promise<void>;
138
+ }
139
+ /**
140
+ * Who uploads a key right now, shared by every engine that may upload the same content (several processes, runners,
141
+ * machines): a lease with an expiry. The product supplies it (memoryClaims for one process, kvClaims over its
142
+ * KeyValueStore/Redis, or its own server's create answers).
143
+ *
144
+ * - `acquire`: take the claim if it's free or expired → "acquired" with a token (a takeover of an expired claim also
145
+ * returns what the previous holder recorded: its upload id and part size, so proven parts can be kept); held by
146
+ * someone else and not expired → "held" with its expiry.
147
+ * - `renew`: extend our claim; false = it isn't ours any more (expired and taken over): stop sending.
148
+ * - `record`: note the multipart the holder created (for a later takeover).
149
+ * - `release`: give it up (finished, failed, cancelled). Only the token's holder can.
150
+ */
151
+ export interface ClaimStore {
152
+ acquire(key: string, ttlMs: number): Promise<{
153
+ status: "acquired";
154
+ token: string;
155
+ previous?: ClaimRecord;
156
+ } | {
157
+ status: "held";
158
+ expiresAt: number;
159
+ }>;
160
+ renew(key: string, token: string, ttlMs: number): Promise<boolean>;
161
+ record(key: string, token: string, rec: ClaimRecord): Promise<void>;
162
+ release(key: string, token: string): Promise<void>;
163
+ }
164
+ export interface ClaimRecord {
165
+ uploadId?: string;
166
+ partSize?: number;
167
+ }
@@ -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,110 @@
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 ignores them today, see 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
+ }
63
+ export type Storage = ReturnType<typeof createStorage>;
64
+ /** Unwrap a TransferResult or throw a StorageError the engine knows how to retry. */
65
+ export declare function unwrap<R extends TransferResult>(r: TransferResult): Extract<R, {
66
+ ok: true;
67
+ }>;
68
+ export declare function createStorage(o: StorageOptions): {
69
+ createMultipart: (scope: string, key: string, contentType: string, size?: number, counts?: boolean) => Promise<string>;
70
+ createOrDedupe: (scope: string, key: string, contentType: string, size?: number, counts?: boolean, sha256?: string) => Promise<Deduped | {
71
+ uploadId: string;
72
+ }>;
73
+ completeMultipart: (scope: string, key: string, uploadId: string, parts: {
74
+ n: number;
75
+ etag: string;
76
+ }[]) => Promise<Stat>;
77
+ abortMultipart: (scope: string, key: string, uploadId: string) => Promise<void | undefined>;
78
+ head: (scope: string, key: string) => Promise<Stat>;
79
+ listParts: (scope: string, key: string, uploadId: string) => Promise<Map<number, string>>;
80
+ listUploads: (scope: string, key: string) => Promise<{
81
+ uploadId: string;
82
+ initiated?: string;
83
+ }[]>;
84
+ uploadPart: (scope: string, key: string, uploadId: string, partNumber: number, body: Uint8Array, contentMd5: string, onProgress: (sent: number) => void, timeoutMs: number, y?: Yieldable) => Promise<string>;
85
+ putObject: (scope: string, key: string, body: Uint8Array, contentType: string, onProgress?: (sent: number) => void, timeoutMs?: number, contentMd5?: string, counts?: boolean, y?: Yieldable, sha256?: string) => Promise<string>;
86
+ transport: Transport;
87
+ createSession: (scope: string, key: string, contentType: string, size: number, counts: boolean, x: {
88
+ sha256?: string;
89
+ checksumAlgorithm?: "SHA256";
90
+ partSize?: number;
91
+ resumeUploadId?: string;
92
+ }) => Promise<CreateAnswer>;
93
+ 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>;
94
+ 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<{
95
+ receipt: PutReceipt;
96
+ } | {
97
+ deduped: Deduped;
98
+ } | {
99
+ exists: CheckedStat;
100
+ }>;
101
+ listPartsChecked: (scope: string, key: string, uploadId: string) => Promise<Map<number, ListedPart>>;
102
+ completeChecked: (scope: string, key: string, uploadId: string, parts: {
103
+ n: number;
104
+ etag: string;
105
+ checksumSha256: string;
106
+ }[]) => Promise<CheckedStat>;
107
+ headWithChecksum: (scope: string, key: string) => Promise<CheckedStat>;
108
+ };
109
+ /** Base64 → hex without Buffer (works in any runtime). */
110
+ 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;