wherever-dev 0.18.3 → 0.18.5

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 (50) hide show
  1. package/dist/cli-bridge-extension.d.ts +51 -0
  2. package/dist/cli-bridge-extension.d.ts.map +1 -0
  3. package/dist/cli-bridge-extension.js +100 -0
  4. package/dist/cli-bridge-extension.js.map +1 -0
  5. package/dist/index.js +372 -33
  6. package/dist/index.js.map +1 -1
  7. package/dist/protocol.d.ts +22 -0
  8. package/dist/protocol.d.ts.map +1 -1
  9. package/dist/server-process-marker.d.ts +28 -0
  10. package/dist/server-process-marker.d.ts.map +1 -0
  11. package/dist/server-process-marker.js +30 -0
  12. package/dist/server-process-marker.js.map +1 -0
  13. package/dist/session-pool.d.ts +25 -0
  14. package/dist/session-pool.d.ts.map +1 -1
  15. package/dist/session-pool.js +52 -1
  16. package/dist/session-pool.js.map +1 -1
  17. package/dist/upload-gate.d.ts +96 -0
  18. package/dist/upload-gate.d.ts.map +1 -0
  19. package/dist/upload-gate.js +109 -0
  20. package/dist/upload-gate.js.map +1 -0
  21. package/dist/upload-staging.d.ts +172 -0
  22. package/dist/upload-staging.d.ts.map +1 -0
  23. package/dist/upload-staging.js +368 -0
  24. package/dist/upload-staging.js.map +1 -0
  25. package/package.json +1 -1
  26. package/public/_app/immutable/assets/{0.BnOlDJL_.css → 0.Cb5vRzMp.css} +1 -1
  27. package/public/_app/immutable/chunks/{pzF36qD8.js → BdyEwvKM.js} +2 -2
  28. package/public/_app/immutable/chunks/{pzF36qD8.js.map → BdyEwvKM.js.map} +1 -1
  29. package/public/_app/immutable/chunks/{CxeW4bFU.js → BgfVtPUY.js} +2 -2
  30. package/public/_app/immutable/chunks/{CxeW4bFU.js.map → BgfVtPUY.js.map} +1 -1
  31. package/public/_app/immutable/chunks/CO_n26iD.js +2 -0
  32. package/public/_app/immutable/chunks/{BDyT5Iv7.js.map → CO_n26iD.js.map} +1 -1
  33. package/public/_app/immutable/entry/{app.fmRrIlrx.js → app.Cd34rZl-.js} +3 -3
  34. package/public/_app/immutable/entry/{app.fmRrIlrx.js.map → app.Cd34rZl-.js.map} +1 -1
  35. package/public/_app/immutable/entry/start.Cs0K02Bg.js +2 -0
  36. package/public/_app/immutable/entry/start.Cs0K02Bg.js.map +1 -0
  37. package/public/_app/immutable/nodes/{0.y9mNw2ua.js → 0.CbsSRnKE.js} +2 -2
  38. package/public/_app/immutable/nodes/{0.y9mNw2ua.js.map → 0.CbsSRnKE.js.map} +1 -1
  39. package/public/_app/immutable/nodes/{1.D0t3PhYs.js → 1.FIugR_jQ.js} +2 -2
  40. package/public/_app/immutable/nodes/{1.D0t3PhYs.js.map → 1.FIugR_jQ.js.map} +1 -1
  41. package/public/_app/immutable/nodes/2.B8lR6Ytl.js +120 -0
  42. package/public/_app/immutable/nodes/2.B8lR6Ytl.js.map +1 -0
  43. package/public/_app/version.json +1 -1
  44. package/public/index.html +11 -11
  45. package/public/service-worker.js +1 -1
  46. package/public/_app/immutable/chunks/BDyT5Iv7.js +0 -2
  47. package/public/_app/immutable/entry/start.CR5sFyDq.js +0 -2
  48. package/public/_app/immutable/entry/start.CR5sFyDq.js.map +0 -1
  49. package/public/_app/immutable/nodes/2.hfqxCQJf.js +0 -120
  50. package/public/_app/immutable/nodes/2.hfqxCQJf.js.map +0 -1
@@ -0,0 +1,96 @@
1
+ /**
2
+ * The upload WRITE GATE: one decision, shared by every path that writes an
3
+ * uploaded file over the WebSocket (the legacy base64 `file_upload` frame and
4
+ * the chunked protocol). `POST /session/upload` has no socket, so it uses
5
+ * `gateUploadFolder` below, which shares the reasons and the size limit.
6
+ *
7
+ * An upload WRITES a file to disk, so it is a write capability and sits behind
8
+ * the same verdict as a send. It is bound to the session this socket PAINTED
9
+ * (`session_created` of its last `session_load` / `session_new`), not only to
10
+ * the one it is attached to: with fast-first loading a cold session is painted
11
+ * seconds before the socket is attached, and that window is exactly when a
12
+ * resumed upload arrives (docs/adr/0012).
13
+ *
14
+ * Decision (recorded here, the choice site): when a session is painted, ONLY
15
+ * that session is accepted. The attached session is the fallback only while
16
+ * nothing is painted (the start of a `session_load`, before its cheap read
17
+ * returns, when `readOnly` still describes the attached session). Accepting
18
+ * "painted OR attached" at all times was considered and rejected: between a
19
+ * cold load's paint of B and its attach, the socket is still attached to the
20
+ * previous session A while `client.readOnly` already holds B's verdict, so an
21
+ * upload for A would be judged by B's verdict, which is the very cross-session
22
+ * bug this gate exists to close.
23
+ */
24
+ import type { WhereverConfig } from './session-pool.js';
25
+ /** Default for `uploads.maxBytes`: 1 GiB. Phone videos easily exceed the 100 MiB download cap. */
26
+ export declare const DEFAULT_UPLOAD_MAX_BYTES: number;
27
+ /** The parts of a WS client the gate reads. */
28
+ export interface UploadGateClient {
29
+ /** The ATTACHED session file, or null. */
30
+ sessionId: string | null;
31
+ readOnly: boolean;
32
+ paintedSessionFile?: string;
33
+ paintedSessionId?: string;
34
+ paintedCwd?: string;
35
+ }
36
+ /** The parts of the session pool the gate reads. */
37
+ export interface UploadGatePool {
38
+ getSession(sessionFileOrId: string): {
39
+ sessionFile: string;
40
+ cwd: string;
41
+ } | null;
42
+ }
43
+ export type UploadGateVerdict = {
44
+ ok: true;
45
+ cwd: string;
46
+ } | {
47
+ ok: false;
48
+ reason: string;
49
+ };
50
+ /**
51
+ * May this client write an upload for `sessionId` (a session id or file)?
52
+ * On success, returns the cwd of the session the file belongs to: the PAINTED
53
+ * cwd, never `pool.getSession()` of a cold session, which is null while its
54
+ * agent builds and used to send the file to tmp.
55
+ */
56
+ export declare function gateUploadWrite(client: UploadGateClient, pool: UploadGatePool, sessionId: string): UploadGateVerdict;
57
+ /** A session folder's verdicts, as `POST /session/upload` resolves them without a socket. */
58
+ export interface UploadFolderVerdicts {
59
+ cwd: string;
60
+ /** The cwd matches a `sessions.readOnly` glob. */
61
+ readOnly: boolean;
62
+ /** The cwd does not exist (or is not a directory) on this machine. */
63
+ folderMissing: boolean;
64
+ /** A restore job is materialising the cwd right now. */
65
+ restoring: boolean;
66
+ }
67
+ /**
68
+ * The write gate for an upload that has NO socket (`POST /session/upload`).
69
+ *
70
+ * It applies the HARD read-only reasons of the WebSocket verdict (see
71
+ * `hasHardReadOnly` in index.ts, plus a running restore, which `session_load`
72
+ * folds into folder-missing): a `sessions.readOnly` folder, a missing folder,
73
+ * and a folder a restore job is cloning into. It cannot apply the per-viewer
74
+ * folder-conflict observe-only lock, because that state belongs to a socket and
75
+ * a POST has none (an accepted, documented limitation, docs/adr/0012). It does
76
+ * not require the session to be loaded: the composer is editable while a cold
77
+ * agent builds, so the cwd comes from the pool or the session file's header.
78
+ *
79
+ * Decisions (recorded here, the choice site):
80
+ * - The HTTP statuses: a refusal by this gate is `403`, an unresolvable session
81
+ * `404`, an oversized body `413` (matching `/session/download`'s `413`). One
82
+ * `403` for all three folder reasons, told apart by the `error` text the
83
+ * client shows, rather than e.g. `409` for a restore in progress: the client
84
+ * only needs the reason, and the WebSocket paths have no codes either.
85
+ * - A running restore is checked BEFORE folder-missing, so a folder that is
86
+ * both missing and being cloned says "being restored", the more useful truth.
87
+ * - A header-only read (`SessionPool.readSessionFolderMeta`) rather than
88
+ * `readSessionMeta` with a tiny history limit: a cold `readSessionMeta`
89
+ * streams the whole transcript to find the window, which a write never needs.
90
+ */
91
+ export declare function gateUploadFolder(v: UploadFolderVerdicts): UploadGateVerdict;
92
+ /** The configured `uploads.maxBytes`, or the 1 GiB default when unset or not a positive number. */
93
+ export declare function uploadMaxBytes(config: WhereverConfig): number;
94
+ /** Refusal reason when `bytes` exceeds the limit, else null. */
95
+ export declare function uploadTooLarge(bytes: number, maxBytes: number): string | null;
96
+ //# sourceMappingURL=upload-gate.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"upload-gate.d.ts","sourceRoot":"","sources":["../src/upload-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAExD,kGAAkG;AAClG,eAAO,MAAM,wBAAwB,QAAqB,CAAC;AAE3D,+CAA+C;AAC/C,MAAM,WAAW,gBAAgB;IAC/B,0CAA0C;IAC1C,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,UAAU,CAAC,eAAe,EAAE,MAAM,GAAG;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAClF;AAED,MAAM,MAAM,iBAAiB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE1F;;;;;GAKG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,cAAc,EACpB,SAAS,EAAE,MAAM,GAChB,iBAAiB,CAuBnB;AAED,6FAA6F;AAC7F,MAAM,WAAW,oBAAoB;IACnC,GAAG,EAAE,MAAM,CAAC;IACZ,kDAAkD;IAClD,QAAQ,EAAE,OAAO,CAAC;IAClB,sEAAsE;IACtE,aAAa,EAAE,OAAO,CAAC;IACvB,wDAAwD;IACxD,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,oBAAoB,GAAG,iBAAiB,CAiB3E;AAED,mGAAmG;AACnG,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,CAG7D;AAED,gEAAgE;AAChE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAI7E"}
@@ -0,0 +1,109 @@
1
+ /**
2
+ * The upload WRITE GATE: one decision, shared by every path that writes an
3
+ * uploaded file over the WebSocket (the legacy base64 `file_upload` frame and
4
+ * the chunked protocol). `POST /session/upload` has no socket, so it uses
5
+ * `gateUploadFolder` below, which shares the reasons and the size limit.
6
+ *
7
+ * An upload WRITES a file to disk, so it is a write capability and sits behind
8
+ * the same verdict as a send. It is bound to the session this socket PAINTED
9
+ * (`session_created` of its last `session_load` / `session_new`), not only to
10
+ * the one it is attached to: with fast-first loading a cold session is painted
11
+ * seconds before the socket is attached, and that window is exactly when a
12
+ * resumed upload arrives (docs/adr/0012).
13
+ *
14
+ * Decision (recorded here, the choice site): when a session is painted, ONLY
15
+ * that session is accepted. The attached session is the fallback only while
16
+ * nothing is painted (the start of a `session_load`, before its cheap read
17
+ * returns, when `readOnly` still describes the attached session). Accepting
18
+ * "painted OR attached" at all times was considered and rejected: between a
19
+ * cold load's paint of B and its attach, the socket is still attached to the
20
+ * previous session A while `client.readOnly` already holds B's verdict, so an
21
+ * upload for A would be judged by B's verdict, which is the very cross-session
22
+ * bug this gate exists to close.
23
+ */
24
+ /** Default for `uploads.maxBytes`: 1 GiB. Phone videos easily exceed the 100 MiB download cap. */
25
+ export const DEFAULT_UPLOAD_MAX_BYTES = 1024 * 1024 * 1024;
26
+ /**
27
+ * May this client write an upload for `sessionId` (a session id or file)?
28
+ * On success, returns the cwd of the session the file belongs to: the PAINTED
29
+ * cwd, never `pool.getSession()` of a cold session, which is null while its
30
+ * agent builds and used to send the file to tmp.
31
+ */
32
+ export function gateUploadWrite(client, pool, sessionId) {
33
+ let cwd;
34
+ if (client.paintedSessionFile) {
35
+ if (client.paintedCwd &&
36
+ (sessionId === client.paintedSessionId || sessionId === client.paintedSessionFile)) {
37
+ cwd = client.paintedCwd;
38
+ }
39
+ }
40
+ else if (client.sessionId) {
41
+ const tracked = pool.getSession(sessionId);
42
+ if (tracked && tracked.sessionFile === client.sessionId)
43
+ cwd = tracked.cwd;
44
+ }
45
+ if (cwd === undefined) {
46
+ return {
47
+ ok: false,
48
+ reason: 'This upload is not for the session this connection is on, so the file was not uploaded.',
49
+ };
50
+ }
51
+ if (client.readOnly) {
52
+ return { ok: false, reason: 'This session is read-only from here, so the file was not uploaded.' };
53
+ }
54
+ return { ok: true, cwd };
55
+ }
56
+ /**
57
+ * The write gate for an upload that has NO socket (`POST /session/upload`).
58
+ *
59
+ * It applies the HARD read-only reasons of the WebSocket verdict (see
60
+ * `hasHardReadOnly` in index.ts, plus a running restore, which `session_load`
61
+ * folds into folder-missing): a `sessions.readOnly` folder, a missing folder,
62
+ * and a folder a restore job is cloning into. It cannot apply the per-viewer
63
+ * folder-conflict observe-only lock, because that state belongs to a socket and
64
+ * a POST has none (an accepted, documented limitation, docs/adr/0012). It does
65
+ * not require the session to be loaded: the composer is editable while a cold
66
+ * agent builds, so the cwd comes from the pool or the session file's header.
67
+ *
68
+ * Decisions (recorded here, the choice site):
69
+ * - The HTTP statuses: a refusal by this gate is `403`, an unresolvable session
70
+ * `404`, an oversized body `413` (matching `/session/download`'s `413`). One
71
+ * `403` for all three folder reasons, told apart by the `error` text the
72
+ * client shows, rather than e.g. `409` for a restore in progress: the client
73
+ * only needs the reason, and the WebSocket paths have no codes either.
74
+ * - A running restore is checked BEFORE folder-missing, so a folder that is
75
+ * both missing and being cloned says "being restored", the more useful truth.
76
+ * - A header-only read (`SessionPool.readSessionFolderMeta`) rather than
77
+ * `readSessionMeta` with a tiny history limit: a cold `readSessionMeta`
78
+ * streams the whole transcript to find the window, which a write never needs.
79
+ */
80
+ export function gateUploadFolder(v) {
81
+ if (v.readOnly) {
82
+ return { ok: false, reason: 'This session is read-only from here, so the file was not uploaded.' };
83
+ }
84
+ if (v.restoring) {
85
+ return {
86
+ ok: false,
87
+ reason: "This session's folder is still being restored, so the file was not uploaded.",
88
+ };
89
+ }
90
+ if (v.folderMissing) {
91
+ return {
92
+ ok: false,
93
+ reason: "This session's folder is missing on this machine, so the file was not uploaded.",
94
+ };
95
+ }
96
+ return { ok: true, cwd: v.cwd };
97
+ }
98
+ /** The configured `uploads.maxBytes`, or the 1 GiB default when unset or not a positive number. */
99
+ export function uploadMaxBytes(config) {
100
+ const v = config.uploads?.maxBytes;
101
+ return typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : DEFAULT_UPLOAD_MAX_BYTES;
102
+ }
103
+ /** Refusal reason when `bytes` exceeds the limit, else null. */
104
+ export function uploadTooLarge(bytes, maxBytes) {
105
+ return bytes > maxBytes
106
+ ? `File too large (${bytes} bytes, the limit is ${maxBytes} bytes), so it was not uploaded.`
107
+ : null;
108
+ }
109
+ //# sourceMappingURL=upload-gate.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"upload-gate.js","sourceRoot":"","sources":["../src/upload-gate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,kGAAkG;AAClG,MAAM,CAAC,MAAM,wBAAwB,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAmB3D;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAwB,EACxB,IAAoB,EACpB,SAAiB;IAEjB,IAAI,GAAuB,CAAC;IAC5B,IAAI,MAAM,CAAC,kBAAkB,EAAE,CAAC;QAC9B,IACE,MAAM,CAAC,UAAU;YACjB,CAAC,SAAS,KAAK,MAAM,CAAC,gBAAgB,IAAI,SAAS,KAAK,MAAM,CAAC,kBAAkB,CAAC,EAClF,CAAC;YACD,GAAG,GAAG,MAAM,CAAC,UAAU,CAAC;QAC1B,CAAC;IACH,CAAC;SAAM,IAAI,MAAM,CAAC,SAAS,EAAE,CAAC;QAC5B,MAAM,OAAO,GAAG,IAAI,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;QAC3C,IAAI,OAAO,IAAI,OAAO,CAAC,WAAW,KAAK,MAAM,CAAC,SAAS;YAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAC7E,CAAC;IACD,IAAI,GAAG,KAAK,SAAS,EAAE,CAAC;QACtB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,yFAAyF;SAClG,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,EAAE,CAAC;QACpB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,oEAAoE,EAAE,CAAC;IACrG,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC;AAC3B,CAAC;AAaD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,MAAM,UAAU,gBAAgB,CAAC,CAAuB;IACtD,IAAI,CAAC,CAAC,QAAQ,EAAE,CAAC;QACf,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,oEAAoE,EAAE,CAAC;IACrG,CAAC;IACD,IAAI,CAAC,CAAC,SAAS,EAAE,CAAC;QAChB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,8EAA8E;SACvF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,CAAC,aAAa,EAAE,CAAC;QACpB,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,iFAAiF;SAC1F,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,CAAC;AAClC,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,cAAc,CAAC,MAAsB;IACnD,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,EAAE,QAAQ,CAAC;IACnC,OAAO,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,wBAAwB,CAAC;AAC7F,CAAC;AAED,gEAAgE;AAChE,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,QAAgB;IAC5D,OAAO,KAAK,GAAG,QAAQ;QACrB,CAAC,CAAC,mBAAmB,KAAK,wBAAwB,QAAQ,kCAAkC;QAC5F,CAAC,CAAC,IAAI,CAAC;AACX,CAAC"}
@@ -0,0 +1,172 @@
1
+ /**
2
+ * Server-side staging for RESUMABLE, CHUNKED uploads (docs/adr/0012).
3
+ *
4
+ * One server-owned directory, `getWhereverStateDir()/upload-staging/`, holds every
5
+ * in-flight upload as two entries keyed by the client-generated `uploadId`:
6
+ *
7
+ * - `<uploadId>` the partial file; its SIZE is the acknowledged offset;
8
+ * - `<uploadId>.json` the sidecar (`UploadSidecar`), the durable record of what
9
+ * the upload is (`sessionId`, `filename`, `size`), where it
10
+ * goes (`targetDir`, resolved ONCE at begin) and, once
11
+ * finished, where it went (`done`, `savedPath`).
12
+ *
13
+ * The sidecar is what makes completion idempotent across a lost reply or a server
14
+ * restart: a repeated begin or finish of a finished id answers with the recorded
15
+ * `savedPath` instead of writing a second copy.
16
+ *
17
+ * Every operation on one `uploadId` runs through a per-id SERIAL QUEUE, and the
18
+ * `offset === currentOffset` check of a chunk runs INSIDE it, so two sockets
19
+ * racing chunks for the same id (a resumed upload whose old socket is still
20
+ * flushing) can never interleave writes or both be accepted for one offset.
21
+ *
22
+ * This module knows nothing about WebSockets, sessions or the write gate: the
23
+ * caller passes an `authorize(sidecar)` callback that runs inside the queue, so a
24
+ * gate verdict is taken against the sidecar the write will actually use.
25
+ */
26
+ /** Wire capability advertised in `connected.capabilities`. */
27
+ export declare const UPLOAD_CAPABILITY = "upload.v1";
28
+ /** Hard cap on one chunk's payload. Small enough that heartbeat frames interleave. */
29
+ export declare const UPLOAD_CHUNK_MAX_BYTES: number;
30
+ /** Staging entries untouched for this long are garbage-collected. */
31
+ export declare const UPLOAD_STAGING_MAX_AGE_MS: number;
32
+ /** First byte of a binary chunk frame. */
33
+ export declare const CHUNK_FRAME_KIND = 1;
34
+ /** Second byte of a binary chunk frame. */
35
+ export declare const CHUNK_FRAME_VERSION = 1;
36
+ /** A client-generated upload id: URL-safe, 22..64 chars (>= 128 random bits base64url). */
37
+ export declare function isValidUploadId(id: unknown): id is string;
38
+ export interface UploadSidecar {
39
+ uploadId: string;
40
+ sessionId: string;
41
+ filename: string;
42
+ size: number;
43
+ mime?: string;
44
+ /** Absolute target folder, resolved once at begin from the painted cwd. */
45
+ targetDir: string;
46
+ createdAt: number;
47
+ /** True once the file has been moved to `savedPath`. */
48
+ done?: boolean;
49
+ /**
50
+ * The final path. Written BEFORE the move (with `done` unset), so a crash
51
+ * between the move and recording `done` is completed by the next finish rather
52
+ * than producing a second, differently-named copy.
53
+ */
54
+ savedPath?: string;
55
+ }
56
+ export type ParsedChunkFrame = {
57
+ ok: true;
58
+ uploadId: string;
59
+ offset: number;
60
+ payload: Buffer;
61
+ } | {
62
+ ok: false;
63
+ uploadId: string;
64
+ error: string;
65
+ };
66
+ /**
67
+ * Parse `[u8 kind=1][u8 version=1][u8 idLen][uploadId ascii][u64 offset BE][payload]`.
68
+ * `uploadId` is returned whenever it could be read, so the refusal can be routed.
69
+ */
70
+ export declare function parseChunkFrame(buf: Buffer): ParsedChunkFrame;
71
+ /** Build a chunk frame (used by tests and as the reference encoder). */
72
+ export declare function encodeChunkFrame(uploadId: string, offset: number, payload: Uint8Array): Buffer;
73
+ /** Answer of begin / chunk: the server's offset. */
74
+ export type OffsetResult = {
75
+ ok: true;
76
+ offset: number;
77
+ size: number;
78
+ sessionId: string;
79
+ done?: boolean;
80
+ savedPath?: string;
81
+ accepted?: boolean;
82
+ } | {
83
+ ok: false;
84
+ error: string;
85
+ sessionId: string;
86
+ };
87
+ export type FinishResult = {
88
+ ok: true;
89
+ savedPath: string;
90
+ filename: string;
91
+ sessionId: string;
92
+ } | {
93
+ ok: false;
94
+ error: string;
95
+ sessionId: string;
96
+ };
97
+ /** Returns a refusal reason, or null when the operation may proceed. */
98
+ export type Authorize = (sidecar: UploadSidecar) => string | null;
99
+ export interface UploadStagingOptions {
100
+ /** The staging directory (`<state dir>/upload-staging`). Created lazily. */
101
+ dir: string;
102
+ /** Injectable for the EXDEV test. Defaults to `fs.promises.rename`. */
103
+ rename?: (from: string, to: string) => Promise<void>;
104
+ /** Injectable clock. */
105
+ now?: () => number;
106
+ maxAgeMs?: number;
107
+ }
108
+ export interface BeginRequest {
109
+ uploadId: string;
110
+ sessionId: string;
111
+ filename: string;
112
+ size: number;
113
+ mime?: string;
114
+ /** Resolved only for a NEW id; a known id keeps its recorded target. */
115
+ targetDir: () => string;
116
+ }
117
+ export declare class UploadStaging {
118
+ readonly dir: string;
119
+ private readonly renameFn;
120
+ private readonly now;
121
+ private readonly maxAgeMs;
122
+ private readonly queues;
123
+ constructor(opts: UploadStagingOptions);
124
+ partialPath(uploadId: string): string;
125
+ sidecarPath(uploadId: string): string;
126
+ /** Run `fn` after every earlier operation on `uploadId` has settled. */
127
+ private enqueue;
128
+ readSidecar(uploadId: string): Promise<UploadSidecar | null>;
129
+ private writeSidecar;
130
+ private partialSize;
131
+ /**
132
+ * Start or resume an upload. Idempotent: a known id must match the sidecar's
133
+ * `sessionId`, `size` and `filename`, and answers with the bytes already
134
+ * staged; a finished id answers `{ offset: size, done: true, savedPath }`.
135
+ */
136
+ begin(req: BeginRequest, authorize?: Authorize): Promise<OffsetResult>;
137
+ /**
138
+ * Write one chunk at `offset`. Accepted only when `offset` equals the bytes
139
+ * already staged (checked inside the serial queue); otherwise answers with the
140
+ * true offset and `accepted: false`, which is how a client realigns.
141
+ */
142
+ writeChunk(uploadId: string, offset: number, payload: Buffer, authorize?: Authorize): Promise<OffsetResult>;
143
+ /**
144
+ * Move a complete upload into its target dir and record it. Repeated finishes
145
+ * (lost reply, restart) return the same `savedPath`.
146
+ *
147
+ * Decision (recorded at the choice site): a finish before every byte is staged
148
+ * is a refusal (`ok: false` with the staged/declared counts), not an
149
+ * `upload_offset` realign. A conforming client only finishes after its last
150
+ * ack reached `size`, so this is a client bug, and answering with an offset
151
+ * would let a buggy client loop silently. The alternative (reply with the true
152
+ * offset so the client resends) was considered and rejected for that reason.
153
+ */
154
+ finish(uploadId: string, sessionId: string, authorize?: Authorize, nameFor?: (filename: string) => string): Promise<FinishResult>;
155
+ /** Rename, falling back to copy + unlink across filesystems (`EXDEV`). */
156
+ private move;
157
+ /**
158
+ * Delete an unfinished upload's partial and sidecar. A finished id is left
159
+ * alone (its sidecar keeps completion idempotent; the saved file is the
160
+ * user's). Returns a refusal reason or null.
161
+ */
162
+ abort(uploadId: string, sessionId: string): Promise<string | null>;
163
+ /**
164
+ * Remove every staging entry (partial, sidecar, leftover `.tmp`) whose newest
165
+ * mtime is older than `maxAgeMs`, skipping ids with a queued operation.
166
+ * Returns the number of upload ids removed.
167
+ */
168
+ gc(): Promise<number>;
169
+ /** Is `p` (already resolved) the staging dir or inside it? Lexical and realpath. */
170
+ contains(p: string): boolean;
171
+ }
172
+ //# sourceMappingURL=upload-staging.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"upload-staging.d.ts","sourceRoot":"","sources":["../src/upload-staging.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,8DAA8D;AAC9D,eAAO,MAAM,iBAAiB,cAAc,CAAC;AAE7C,sFAAsF;AACtF,eAAO,MAAM,sBAAsB,QAAc,CAAC;AAElD,qEAAqE;AACrE,eAAO,MAAM,yBAAyB,QAAsB,CAAC;AAE7D,0CAA0C;AAC1C,eAAO,MAAM,gBAAgB,IAAI,CAAC;AAClC,2CAA2C;AAC3C,eAAO,MAAM,mBAAmB,IAAI,CAAC;AAIrC,2FAA2F;AAC3F,wBAAgB,eAAe,CAAC,EAAE,EAAE,OAAO,GAAG,EAAE,IAAI,MAAM,CAEzD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,wDAAwD;IACxD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,MAAM,gBAAgB,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAC/D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,gBAAgB,CAsB7D;AAED,wEAAwE;AACxE,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,GAAG,MAAM,CAS9F;AAED,oDAAoD;AACpD,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAAE,GACrH;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD,MAAM,MAAM,YAAY,GACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACpE;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD,wEAAwE;AACxE,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,EAAE,aAAa,KAAK,MAAM,GAAG,IAAI,CAAC;AAElE,MAAM,WAAW,oBAAoB;IACnC,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;IACZ,uEAAuE;IACvE,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,wBAAwB;IACxB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,SAAS,EAAE,MAAM,MAAM,CAAC;CACzB;AAED,qBAAa,aAAa;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8C;IACvE,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAuC;gBAElD,IAAI,EAAE,oBAAoB;IAOtC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAIrC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAIrC,wEAAwE;IACxE,OAAO,CAAC,OAAO;IAWT,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC;YAUpD,YAAY;YAOZ,WAAW;IAQzB;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,YAAY,EAAE,SAAS,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC;IA6CtE;;;;OAIG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC;IA+B3G;;;;;;;;;;OAUG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAsCjI,0EAA0E;YAC5D,IAAI;IAUlB;;;;OAIG;IACH,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAelE;;;;OAIG;IACG,EAAE,IAAI,OAAO,CAAC,MAAM,CAAC;IAgC3B,oFAAoF;IACpF,QAAQ,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO;CAW7B"}