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.
- package/dist/cli-bridge-extension.d.ts +51 -0
- package/dist/cli-bridge-extension.d.ts.map +1 -0
- package/dist/cli-bridge-extension.js +100 -0
- package/dist/cli-bridge-extension.js.map +1 -0
- package/dist/index.js +372 -33
- package/dist/index.js.map +1 -1
- package/dist/protocol.d.ts +22 -0
- package/dist/protocol.d.ts.map +1 -1
- package/dist/server-process-marker.d.ts +28 -0
- package/dist/server-process-marker.d.ts.map +1 -0
- package/dist/server-process-marker.js +30 -0
- package/dist/server-process-marker.js.map +1 -0
- package/dist/session-pool.d.ts +25 -0
- package/dist/session-pool.d.ts.map +1 -1
- package/dist/session-pool.js +52 -1
- package/dist/session-pool.js.map +1 -1
- package/dist/upload-gate.d.ts +96 -0
- package/dist/upload-gate.d.ts.map +1 -0
- package/dist/upload-gate.js +109 -0
- package/dist/upload-gate.js.map +1 -0
- package/dist/upload-staging.d.ts +172 -0
- package/dist/upload-staging.d.ts.map +1 -0
- package/dist/upload-staging.js +368 -0
- package/dist/upload-staging.js.map +1 -0
- package/package.json +1 -1
- package/public/_app/immutable/assets/{0.BnOlDJL_.css → 0.Cb5vRzMp.css} +1 -1
- package/public/_app/immutable/chunks/{pzF36qD8.js → BdyEwvKM.js} +2 -2
- package/public/_app/immutable/chunks/{pzF36qD8.js.map → BdyEwvKM.js.map} +1 -1
- package/public/_app/immutable/chunks/{CxeW4bFU.js → BgfVtPUY.js} +2 -2
- package/public/_app/immutable/chunks/{CxeW4bFU.js.map → BgfVtPUY.js.map} +1 -1
- package/public/_app/immutable/chunks/CO_n26iD.js +2 -0
- package/public/_app/immutable/chunks/{BDyT5Iv7.js.map → CO_n26iD.js.map} +1 -1
- package/public/_app/immutable/entry/{app.fmRrIlrx.js → app.Cd34rZl-.js} +3 -3
- package/public/_app/immutable/entry/{app.fmRrIlrx.js.map → app.Cd34rZl-.js.map} +1 -1
- package/public/_app/immutable/entry/start.Cs0K02Bg.js +2 -0
- package/public/_app/immutable/entry/start.Cs0K02Bg.js.map +1 -0
- package/public/_app/immutable/nodes/{0.y9mNw2ua.js → 0.CbsSRnKE.js} +2 -2
- package/public/_app/immutable/nodes/{0.y9mNw2ua.js.map → 0.CbsSRnKE.js.map} +1 -1
- package/public/_app/immutable/nodes/{1.D0t3PhYs.js → 1.FIugR_jQ.js} +2 -2
- package/public/_app/immutable/nodes/{1.D0t3PhYs.js.map → 1.FIugR_jQ.js.map} +1 -1
- package/public/_app/immutable/nodes/2.B8lR6Ytl.js +120 -0
- package/public/_app/immutable/nodes/2.B8lR6Ytl.js.map +1 -0
- package/public/_app/version.json +1 -1
- package/public/index.html +11 -11
- package/public/service-worker.js +1 -1
- package/public/_app/immutable/chunks/BDyT5Iv7.js +0 -2
- package/public/_app/immutable/entry/start.CR5sFyDq.js +0 -2
- package/public/_app/immutable/entry/start.CR5sFyDq.js.map +0 -1
- package/public/_app/immutable/nodes/2.hfqxCQJf.js +0 -120
- 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":"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"}
|