@av-pi-studio/server 0.0.118 → 0.0.120

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/README.md CHANGED
@@ -41,7 +41,7 @@ A single daemon process owns all runtime state and mediates every operation:
41
41
  manages worktrees, and integrates with the GitHub API for PRs/issues.
42
42
  - **Orchestration** — chat rooms with `@mentions`, cron/interval **schedules** that fire agent
43
43
  prompts, and iterative worker+verifier **loops**.
44
- - **Files** — directory listing, text/binary file preview, and token-based chunked file download.
44
+ - **Files** — directory listing, text/binary file preview, and chunked file download by path (byte ranges, resume with `ifUnchanged`, cancel).
45
45
  - **Service proxy** — an HTTP reverse proxy that routes to localhost services started by agents.
46
46
 
47
47
  The daemon is **provider-agnostic**: the rest of the code only ever touches the `AgentClient` /
@@ -259,7 +259,8 @@ All communication rides a **single WebSocket connection** per client.
259
259
  ### Text frames — JSON envelopes discriminated by `type`
260
260
 
261
261
  - `hello` (Client→Server, first frame) — handshake with `clientId`, `clientType`
262
- (`mobile`/`browser`/`cli`/`mcp`), `protocolVersion`, optional `capabilities`.
262
+ (`mobile`/`browser`/`cli`/`mcp`), `protocolVersion`, optional `capabilities`, `platform` and `agentStreams`
263
+ (`"all"` default, or `"none"` to receive no `agent_stream` frames).
263
264
  - `status` (Server→Client) — `server_info` payload sent right after a successful hello.
264
265
  - `ping` / `pong` — **JSON** liveness (not RFC 6455 ping, which browsers/RN can't send).
265
266
  - `session` — the envelope wrapping every RPC request/response/broadcast (`{ type: "session",
@@ -274,9 +275,10 @@ are accepted via aliases but never generated.
274
275
 
275
276
  Layout: `[1-byte opcode][1-byte slot][payload]`. The `slot` (0–255) demultiplexes multiple
276
277
  terminals over the one connection. Codecs use `Uint8Array` (not Node `Buffer`) so they run
277
- unchanged in browsers and React Native. **File downloads** also ride binary frames: a client
278
- requests a token via the `file_download_token_request` RPC, then streams `Begin → Chunk* → End`
279
- frames via `file_download_request`; uploads consume the same frame format.
278
+ unchanged in browsers and React Native. **File downloads** also ride binary frames: a client sends
279
+ `file_download_request { path, offset?, length?, ifUnchanged? }`, gets a `file_download_response` (with the file's
280
+ size) first, then `Begin → Chunk* → End`; `file_download_cancel_request { stream }` stops one
281
+ (`Error` `cancelled`). Advertised as `fileDownloadRanges`. Uploads consume the same frame format.
280
282
 
281
283
  ### HTTP surface
282
284
 
@@ -388,7 +390,7 @@ src/
388
390
  terminal/ TerminalManager (PTY lifecycle, slot mux, snapshot, binary broadcast).
389
391
  projects/ Workspaces, projects, git ops, worktrees, GitHub, reconciliation.
390
392
  orchestration/ ChatService, ScheduleService, LoopService, cron.
391
- files/ File explorer + chunked download token store.
393
+ files/ File explorer + chunked download/upload transfer.
392
394
  proxy/ ServiceProxy + port registry for agent-started services.
393
395
  logging/ Pino logger factory.
394
396
  util/ Concurrency helpers.
@@ -1,6 +1,6 @@
1
1
  import type { AgentStreamEvent } from "@av-pi-studio/protocol";
2
2
  import type { Logger } from "../logging/logger.js";
3
- import type { Session } from "../ws/session.js";
3
+ import { type Session } from "../ws/session.js";
4
4
  import type { HandlerRegistry } from "../ws/router.js";
5
5
  import { AgentManager } from "./agent-manager.js";
6
6
  import type { AgentClient, AgentSession, RunOptions } from "./provider-contract.js";
@@ -1,4 +1,5 @@
1
1
  import { randomUUID } from "node:crypto";
2
+ import { agentStreamRecipients } from "../ws/session.js";
2
3
  import { AgentManager } from "./agent-manager.js";
3
4
  import { AgentTimelineStore } from "./timeline-store.js";
4
5
  import { composeSystemPrompt } from "./compose-system-prompt.js";
@@ -51,14 +52,14 @@ export function resetTimeline(agentId, rows) {
51
52
  */
52
53
  export function appendStreamEvent(agentId, event, broadcast, sessions) {
53
54
  if ((event.kind === "tool_call" && event.partial) || event.kind === "queue_update") {
54
- broadcast(sessions, {
55
+ broadcast(agentStreamRecipients(sessions), {
55
56
  type: "session",
56
57
  message: { type: "agent_stream", agentId, timestamp: new Date().toISOString(), event },
57
58
  });
58
59
  return;
59
60
  }
60
61
  const row = getOrCreateTimeline(agentId).append(event);
61
- broadcast(sessions, {
62
+ broadcast(agentStreamRecipients(sessions), {
62
63
  type: "session",
63
64
  message: {
64
65
  type: "agent_stream",
@@ -283,7 +284,7 @@ export class AgentService {
283
284
  text: prompt,
284
285
  images: opts.images,
285
286
  });
286
- this.broadcastAll(getSessions(), {
287
+ this.broadcastAll(agentStreamRecipients(getSessions()), {
287
288
  type: "session",
288
289
  message: {
289
290
  type: "agent_stream",
@@ -309,7 +310,7 @@ export class AgentService {
309
310
  text: prompt,
310
311
  images: opts.images,
311
312
  });
312
- this.broadcastAll(getSessions(), {
313
+ this.broadcastAll(agentStreamRecipients(getSessions()), {
313
314
  type: "session",
314
315
  message: {
315
316
  type: "agent_stream",
@@ -1,4 +1,4 @@
1
- import type { Session } from "../ws/session.js";
1
+ import { type Session } from "../ws/session.js";
2
2
  import type { HandlerRegistry } from "../ws/router.js";
3
3
  import type { AgentManager } from "./agent-manager.js";
4
4
  import type { AgentClient } from "./provider-contract.js";
@@ -1,4 +1,5 @@
1
1
  import { randomUUID } from "node:crypto";
2
+ import { agentStreamRecipients } from "../ws/session.js";
2
3
  import { getTimeline, spawnOrResumeSession } from "./agent-service.js";
3
4
  export class SessionOperationsService {
4
5
  deps;
@@ -72,7 +73,7 @@ export class SessionOperationsService {
72
73
  if (timeline) {
73
74
  const messageId = msg.clientMessageId ?? randomUUID();
74
75
  const row = timeline.append({ kind: "user_message", messageId, text: message, images });
75
- this.broadcastAll(getSessions(), {
76
+ this.broadcastAll(agentStreamRecipients(getSessions()), {
76
77
  type: "session",
77
78
  message: {
78
79
  type: "agent_stream",
@@ -459,9 +459,9 @@ export function startDaemon(opts) {
459
459
  broadcast,
460
460
  getActiveSessions,
461
461
  }).registerHandlers(registry, getActiveSessions);
462
- // ── Files: explorer (with download tokens) + transfer + filesystem watch ──────
462
+ // ── Files: explorer + transfer + filesystem watch ──────
463
463
  const fileTransfer = new FileTransferService();
464
- new FileExplorerService({ issueDownloadToken: fileTransfer.issueDownloadToken }).registerHandlers(registry);
464
+ new FileExplorerService().registerHandlers(registry);
465
465
  fileTransfer.registerHandlers(registry);
466
466
  const fileTransferBinary = fileTransfer.binaryHandler();
467
467
  const fileWatchService = new FileWatchService({ logger });
@@ -719,6 +719,7 @@ export function startDaemon(opts) {
719
719
  clientId: hello.data.clientId,
720
720
  clientType: hello.data.clientType,
721
721
  platform: hello.data.platform,
722
+ agentStreams: hello.data.agentStreams,
722
723
  capabilities,
723
724
  appVersion: hello.data.appVersion,
724
725
  transport: "relay",
@@ -267,11 +267,10 @@ export function startDevDaemon(opts) {
267
267
  // (features/file-explorer-transfer.md). Lets the workspace Explorer + file
268
268
  // preview panes show actual files.
269
269
  //
270
- // Same wiring as production `bootstrap.ts`: the explorer issues download tokens through the
271
- // transfer service, which also owns the token / download / upload RPCs and the upload binary
272
- // handler.
270
+ // Same wiring as production `bootstrap.ts`: the transfer service owns the download / upload RPCs
271
+ // and the upload binary handler.
273
272
  const fileTransfer = new FileTransferService();
274
- new FileExplorerService({ issueDownloadToken: fileTransfer.issueDownloadToken }).registerHandlers(registry);
273
+ new FileExplorerService().registerHandlers(registry);
275
274
  fileTransfer.registerHandlers(registry);
276
275
  const fileTransferBinary = fileTransfer.binaryHandler();
277
276
  // ── Terminals: manager + control RPCs + binary stream (same wiring as production) ──────────
@@ -30,14 +30,11 @@ export type FileExplorerResult = {
30
30
  mtimeMs: number;
31
31
  mimeHint: string;
32
32
  };
33
- transferToken: string;
34
33
  } | {
35
34
  ok: false;
36
35
  error: string;
37
36
  };
38
37
  export interface FileExplorerDeps {
39
- /** Issue a download token for a binary file (task-005 supplies the real store). */
40
- issueDownloadToken?: (resolvedPath: string) => string;
41
38
  previewBytes?: number;
42
39
  }
43
40
  export declare class FileExplorerService {
@@ -341,14 +341,12 @@ export class FileExplorerService {
341
341
  if (sniffLen > 0)
342
342
  await handle.read(sniff, 0, sniffLen, 0);
343
343
  if (isBinary(sniff)) {
344
- const transferToken = this.deps.issueDownloadToken?.(resolvedPath) ?? randomUUID();
345
344
  return {
346
345
  ok: true,
347
346
  kind: "binary",
348
347
  path: inputPath,
349
348
  resolvedPath,
350
349
  metadata: { size, mtimeMs, mimeHint: mimeHintForFile(resolvedPath) },
351
- transferToken,
352
350
  };
353
351
  }
354
352
  const readLen = Math.min(size, previewBytes);
@@ -1,6 +1,5 @@
1
1
  import type { Session } from "../ws/session.js";
2
2
  import type { BinaryHandler, HandlerRegistry } from "../ws/router.js";
3
- import { DownloadTokenStore } from "./download-token-store.js";
4
3
  /**
5
4
  * A download stops reading from disk while this many bytes are queued on the session's socket (32
6
5
  * default chunks) and resumes below the low mark. Chosen, not measured: big enough that the read
@@ -10,7 +9,6 @@ import { DownloadTokenStore } from "./download-token-store.js";
10
9
  export declare const DOWNLOAD_HIGH_WATER_BYTES: number;
11
10
  export declare const DOWNLOAD_LOW_WATER_BYTES: number;
12
11
  export interface FileTransferDeps {
13
- tokenStore?: DownloadTokenStore;
14
12
  chunkBytes?: number;
15
13
  highWaterBytes?: number;
16
14
  lowWaterBytes?: number;
@@ -25,7 +23,6 @@ export interface DownloadPacing {
25
23
  isOpen(): boolean;
26
24
  }
27
25
  export declare class FileTransferService {
28
- readonly tokenStore: DownloadTokenStore;
29
26
  private readonly chunkBytes;
30
27
  private readonly highWaterBytes;
31
28
  private readonly lowWaterBytes;
@@ -34,29 +31,56 @@ export declare class FileTransferService {
34
31
  private readonly uploads;
35
32
  /** Rotating hand-out point in the one-byte stream id space (see `nextFreeSlot`). */
36
33
  private streamCursor;
34
+ /** Accepted downloads by session id, then stream id: download ids are scoped to the session. */
35
+ private readonly downloads;
36
+ /** Rotating hand-out point for a download the client did not number itself. */
37
+ private downloadCursor;
37
38
  constructor(deps?: FileTransferDeps);
38
- /** Issue a download token for a resolved path (also used by the file explorer for binary files). */
39
- issueDownloadToken: (resolvedPath: string) => string;
39
+ /**
40
+ * Answer a `file_download_request` from session `sessionId`. `response` is the
41
+ * `file_download_response` to send; `run` is present only when the download was accepted, and
42
+ * streams the file once called (after the response has gone out). The caller must call `run`
43
+ * exactly once: it owns the open file.
44
+ */
45
+ beginDownload(sessionId: string, message: Record<string, unknown>): Promise<{
46
+ response: Record<string, unknown>;
47
+ run?: (sink: (frame: Uint8Array) => void, pacing: DownloadPacing) => Promise<void>;
48
+ }>;
49
+ /**
50
+ * Stop `sessionId`'s download on `stream`: it sends `Error` `cancelled` and reads no further.
51
+ * False when that session has no download on `stream` (never started, or already finished).
52
+ */
53
+ cancelDownload(sessionId: string, stream: number): boolean;
40
54
  registerHandlers(registry: HandlerRegistry): void;
41
- /** Hand out the next stream id for a transfer this service does not track (a download the
42
- * client didn't number itself). Rotates through the one-byte space instead of counting past
43
- * 255, which `encodeFileTransferFrame` rejects outright. */
44
- private takeStream;
45
55
  /**
46
- * Validate + consume the token, then stream the file as `Begin → Chunk* → End` binary frames.
56
+ * Validate a download request, reserve its stream id on the session and open its file. Nothing is
57
+ * sent: the caller answers first and then calls `streamDownload`, which owns (and closes) the
58
+ * returned handle and releases the reservation.
47
59
  *
48
- * With `pacing`, the disk read pauses while the socket's queue is above the high-water mark, so a
49
- * client that reads slowly costs the daemon about that much memory, not the whole file. A read
50
- * error sends one `Error` frame and stops (no `End`); a socket that closed mid-transfer ends it
51
- * silently.
60
+ * `offset` defaults to 0 and `length` to "to the end of the file"; `length` is clamped to it. An
61
+ * `offset` equal to the size is a legal empty range, one beyond it is `range_not_satisfiable`.
62
+ * `ifUnchanged` that does not equal the file's current size and modification time (a malformed
63
+ * one never does) is `changed`.
64
+ */
65
+ private openDownload;
66
+ private openFile;
67
+ /** Forget a finished or rejected download. A no-op once the session's downloads were dropped. */
68
+ private release;
69
+ private releaseSession;
70
+ /**
71
+ * Stream an opened download as `Begin → Chunk* → End` binary frames, then close its file.
72
+ *
73
+ * The disk read pauses while the socket's queue is above the high-water mark, so a client that
74
+ * reads slowly costs the daemon about that much memory, not the whole file. A read error, or a
75
+ * file that ended before the announced length, sends one `Error` frame and no `End`; a socket
76
+ * that closed mid-transfer ends it silently. Never rejects: it runs detached from the request.
77
+ */
78
+ private streamDownload;
79
+ private pipeRange;
80
+ /**
81
+ * Resolves `true` once the socket's queue is at or below the low-water mark; `false` if it closed
82
+ * or the download ended (`ended`) while waiting.
52
83
  */
53
- startDownload(token: string, stream: number, sink: (frame: Uint8Array) => void, pacing?: DownloadPacing): Promise<{
54
- ok: boolean;
55
- error?: string;
56
- transferId?: string;
57
- }>;
58
- private pipeFile;
59
- /** Resolves `true` once the socket's queue is at or below the low-water mark; `false` if it closed. */
60
84
  private waitForDrain;
61
85
  /** Binary frame handler for upload streams (Begin → Chunk* → End). Frames are serialized per
62
86
  * stream so an in-flight `Begin` (open) completes before any `Chunk` writes. A frame is applied
@@ -64,7 +88,8 @@ export declare class FileTransferService {
64
88
  binaryHandler(): BinaryHandler;
65
89
  /**
66
90
  * Release everything a session left open: its pending uploads lose their stream id and their file
67
- * handle is closed once frames already in flight finish. Nothing is sent (the session is gone).
91
+ * handle is closed once frames already in flight finish; its downloads stop reading and lose
92
+ * their stream id and file handle. Nothing is sent (the session is gone).
68
93
  */
69
94
  disposeSession(session: Session): void;
70
95
  private handleUploadFrame;
@@ -1,14 +1,14 @@
1
- import { createReadStream } from "node:fs";
2
- import { mkdir, open, realpath } from "node:fs/promises";
1
+ import { mkdir, open, realpath, stat } from "node:fs/promises";
3
2
  import { basename, dirname } from "node:path";
4
3
  import { encodeFileTransferFrame, nextFreeSlot, SLOT_SPACE, tryDecodeFileTransferFrame, } from "@av-pi-studio/protocol";
5
- import { DownloadTokenStore } from "./download-token-store.js";
6
4
  import { mimeHintForFile } from "./file-explorer.js";
7
5
  import { expandHome } from "./resolve-path.js";
8
6
  /**
9
- * Chunked file download (token-authorized) + upload over the file-transfer binary frame format
10
- * (features/file-explorer-transfer.md § Binary transfer frames, § Behavior). Downloads stream
7
+ * Chunked file download (by path, optionally a byte range) + upload over the file-transfer binary
8
+ * frame format (features/file-explorer-transfer.md § Binary transfer frames, § Behavior). A
9
+ * download is answered first (`file_download_response`, with the file's size) and then streams
11
10
  * `Begin → Chunk* → End`; uploads consume the same frames and write to the target path.
11
+ * Range, response ordering and errors: features/desktop-client-protocol-followups-2.md § 1.
12
12
  * Flow control, completion and stream ownership: features/desktop-client-protocol-followups.md § 2.
13
13
  */
14
14
  const DEFAULT_CHUNK_BYTES = 32 * 1024;
@@ -21,13 +21,28 @@ const DEFAULT_CHUNK_BYTES = 32 * 1024;
21
21
  export const DOWNLOAD_HIGH_WATER_BYTES = 1024 * 1024;
22
22
  export const DOWNLOAD_LOW_WATER_BYTES = 256 * 1024;
23
23
  const DEFAULT_DRAIN_POLL_MS = 10;
24
+ /** Absent → `undefined`; a safe integer ≥ `min` → itself; anything else → `null` (invalid). */
25
+ function parseCount(value, min) {
26
+ if (value === undefined)
27
+ return undefined;
28
+ return typeof value === "number" && Number.isSafeInteger(value) && value >= min ? value : null;
29
+ }
30
+ function isMissing(err) {
31
+ return err?.code === "ENOENT";
32
+ }
33
+ /** `ifUnchanged` equals the file as it is now. Anything but `{ size, mtimeMs }` never does. */
34
+ function matchesFile(ifUnchanged, size, mtimeMs) {
35
+ if (typeof ifUnchanged !== "object" || ifUnchanged === null)
36
+ return false;
37
+ const expected = ifUnchanged;
38
+ return expected.size === size && expected.mtimeMs === mtimeMs;
39
+ }
24
40
  /** `open_failed (EACCES)`-style text: a stage plus the errno code, never a path or a stack. */
25
41
  function failureText(stage, err) {
26
42
  const code = err?.code;
27
43
  return typeof code === "string" ? `${stage}_failed (${code})` : `${stage}_failed`;
28
44
  }
29
45
  export class FileTransferService {
30
- tokenStore;
31
46
  chunkBytes;
32
47
  highWaterBytes;
33
48
  lowWaterBytes;
@@ -36,42 +51,81 @@ export class FileTransferService {
36
51
  uploads = new Map();
37
52
  /** Rotating hand-out point in the one-byte stream id space (see `nextFreeSlot`). */
38
53
  streamCursor = 1;
54
+ /** Accepted downloads by session id, then stream id: download ids are scoped to the session. */
55
+ downloads = new Map();
56
+ /** Rotating hand-out point for a download the client did not number itself. */
57
+ downloadCursor = 1;
39
58
  constructor(deps = {}) {
40
- this.tokenStore = deps.tokenStore ?? new DownloadTokenStore();
41
59
  this.chunkBytes = deps.chunkBytes ?? DEFAULT_CHUNK_BYTES;
42
60
  this.highWaterBytes = deps.highWaterBytes ?? DOWNLOAD_HIGH_WATER_BYTES;
43
61
  this.lowWaterBytes = deps.lowWaterBytes ?? DOWNLOAD_LOW_WATER_BYTES;
44
62
  this.drainPollMs = deps.drainPollMs ?? DEFAULT_DRAIN_POLL_MS;
45
63
  }
46
- /** Issue a download token for a resolved path (also used by the file explorer for binary files). */
47
- issueDownloadToken = (resolvedPath) => this.tokenStore.issue(resolvedPath).token;
64
+ /**
65
+ * Answer a `file_download_request` from session `sessionId`. `response` is the
66
+ * `file_download_response` to send; `run` is present only when the download was accepted, and
67
+ * streams the file once called (after the response has gone out). The caller must call `run`
68
+ * exactly once: it owns the open file.
69
+ */
70
+ async beginDownload(sessionId, message) {
71
+ const opened = await this.openDownload(sessionId, message);
72
+ if (!opened.ok) {
73
+ return {
74
+ response: {
75
+ type: "file_download_response",
76
+ ok: false,
77
+ error: opened.error,
78
+ ...(opened.stream === undefined ? {} : { stream: opened.stream }),
79
+ ...opened.current,
80
+ },
81
+ };
82
+ }
83
+ const d = opened.download;
84
+ return {
85
+ response: {
86
+ type: "file_download_response",
87
+ ok: true,
88
+ stream: d.stream,
89
+ transferId: d.transferId,
90
+ totalBytes: d.totalBytes,
91
+ mtimeMs: d.mtimeMs,
92
+ offset: d.offset,
93
+ length: d.length,
94
+ },
95
+ run: (sink, pacing) => this.streamDownload(d, sink, pacing),
96
+ };
97
+ }
98
+ /**
99
+ * Stop `sessionId`'s download on `stream`: it sends `Error` `cancelled` and reads no further.
100
+ * False when that session has no download on `stream` (never started, or already finished).
101
+ */
102
+ cancelDownload(sessionId, stream) {
103
+ const active = this.downloads.get(sessionId)?.get(stream);
104
+ if (!active)
105
+ return false;
106
+ active.stop ??= "cancelled";
107
+ active.wake?.();
108
+ return true;
109
+ }
48
110
  registerHandlers(registry) {
49
- registry.register("file_download_token_request", async (ctx) => {
50
- const path = String(ctx.message.path ?? "");
51
- let resolved;
52
- try {
53
- resolved = await realpath(expandHome(path));
54
- }
55
- catch {
56
- return { type: "file_download_token_response", ok: false, error: "not_found" };
57
- }
58
- const { token, expiresAt } = this.tokenStore.issue(resolved);
59
- return { type: "file_download_token_response", ok: true, token, expiresAt };
60
- });
61
111
  registry.register("file_download_request", async (ctx) => {
62
- const token = String(ctx.message.token ?? "");
63
- const stream = ctx.message.stream === undefined ? this.takeStream() : Number(ctx.message.stream);
64
- // Range-checked BEFORE the token is consumed: an out-of-range stream used to burn the
65
- // single-use token and only then throw out of `encodeFileTransferFrame`, leaving the
66
- // client's retry nothing to redeem.
67
- if (!Number.isInteger(stream) || stream < 0 || stream >= SLOT_SPACE) {
68
- return { type: "file_download_response", stream, ok: false, error: "invalid_stream" };
112
+ const { response, run } = await this.beginDownload(ctx.session.id, ctx.message);
113
+ // The router sends the reply first and the stream starts after it, so a client always learns
114
+ // the size and range before the first frame and a long transfer never holds the request open.
115
+ if (run) {
116
+ ctx.afterReply(() => void run((frame) => ctx.session.sendBinary(frame), {
117
+ bufferedAmount: () => ctx.session.bufferedAmount,
118
+ isOpen: () => ctx.session.isOpen,
119
+ }));
69
120
  }
70
- const result = await this.startDownload(token, stream, (frame) => ctx.session.sendBinary(frame), {
71
- bufferedAmount: () => ctx.session.bufferedAmount,
72
- isOpen: () => ctx.session.isOpen,
73
- });
74
- return { type: "file_download_response", stream, ...result };
121
+ return response;
122
+ });
123
+ registry.register("file_download_cancel_request", (ctx) => {
124
+ const stream = ctx.message.stream;
125
+ const cancelled = typeof stream === "number" && this.cancelDownload(ctx.session.id, stream);
126
+ return cancelled
127
+ ? { type: "file_download_cancel_response", ok: true }
128
+ : { type: "file_download_cancel_response", ok: false, error: "not_found" };
75
129
  });
76
130
  registry.register("file_upload_request", (ctx) => {
77
131
  const targetPath = String(ctx.message.path ?? "");
@@ -97,64 +151,221 @@ export class FileTransferService {
97
151
  return { type: "file_upload_response", ok: true, stream };
98
152
  });
99
153
  }
100
- /** Hand out the next stream id for a transfer this service does not track (a download the
101
- * client didn't number itself). Rotates through the one-byte space instead of counting past
102
- * 255, which `encodeFileTransferFrame` rejects outright. */
103
- takeStream() {
104
- const stream = this.streamCursor;
105
- this.streamCursor = (stream + 1) % SLOT_SPACE;
106
- return stream;
154
+ /**
155
+ * Validate a download request, reserve its stream id on the session and open its file. Nothing is
156
+ * sent: the caller answers first and then calls `streamDownload`, which owns (and closes) the
157
+ * returned handle and releases the reservation.
158
+ *
159
+ * `offset` defaults to 0 and `length` to "to the end of the file"; `length` is clamped to it. An
160
+ * `offset` equal to the size is a legal empty range, one beyond it is `range_not_satisfiable`.
161
+ * `ifUnchanged` that does not equal the file's current size and modification time (a malformed
162
+ * one never does) is `changed`.
163
+ */
164
+ async openDownload(sessionId, message) {
165
+ const path = message.path;
166
+ if (typeof path !== "string" || path === "")
167
+ return { ok: false, error: "missing_path" };
168
+ const requestedStream = message.stream;
169
+ if (requestedStream !== undefined &&
170
+ !(typeof requestedStream === "number" &&
171
+ Number.isInteger(requestedStream) &&
172
+ requestedStream >= 0 &&
173
+ requestedStream < SLOT_SPACE)) {
174
+ return { ok: false, error: "invalid_stream" };
175
+ }
176
+ const offset = parseCount(message.offset, 0);
177
+ const requestedLength = parseCount(message.length, 1);
178
+ if (offset === null || requestedLength === null)
179
+ return { ok: false, error: "invalid_range" };
180
+ // Check and reserve with no await in between: two requests for one id cannot both pass.
181
+ let mine = this.downloads.get(sessionId);
182
+ if (!mine)
183
+ this.downloads.set(sessionId, (mine = new Map()));
184
+ const stream = requestedStream ?? nextFreeSlot(mine, this.downloadCursor);
185
+ if (stream === null) {
186
+ this.releaseSession(sessionId, mine);
187
+ return { ok: false, error: "no_free_stream" };
188
+ }
189
+ if (mine.has(stream))
190
+ return { ok: false, error: "stream_in_use", stream };
191
+ if (requestedStream === undefined)
192
+ this.downloadCursor = (stream + 1) % SLOT_SPACE;
193
+ const active = { stop: null };
194
+ mine.set(stream, active);
195
+ const result = await this.openFile(sessionId, active, stream, path, {
196
+ offset: offset ?? 0,
197
+ requestedLength,
198
+ ifUnchanged: message.ifUnchanged,
199
+ });
200
+ if (!result.ok)
201
+ this.release(sessionId, stream, active);
202
+ return result;
203
+ }
204
+ async openFile(sessionId, active, stream, path, range) {
205
+ let resolved;
206
+ try {
207
+ resolved = await realpath(expandHome(path));
208
+ }
209
+ catch {
210
+ return { ok: false, error: "not_found", stream };
211
+ }
212
+ let handle;
213
+ try {
214
+ // Checked before opening: opening a FIFO or device for reading can block.
215
+ if (!(await stat(resolved)).isFile())
216
+ return { ok: false, error: "not_a_file", stream };
217
+ handle = await open(resolved, "r");
218
+ }
219
+ catch (err) {
220
+ return { ok: false, error: isMissing(err) ? "not_found" : "unreadable", stream };
221
+ }
222
+ let handedOver = false;
223
+ try {
224
+ active.handle = handle;
225
+ const info = await handle.stat();
226
+ if (!info.isFile())
227
+ return { ok: false, error: "not_a_file", stream };
228
+ if (range.offset > info.size)
229
+ return { ok: false, error: "range_not_satisfiable", stream };
230
+ const mtimeMs = Math.trunc(info.mtimeMs);
231
+ if (range.ifUnchanged !== undefined && !matchesFile(range.ifUnchanged, info.size, mtimeMs)) {
232
+ return {
233
+ ok: false,
234
+ error: "changed",
235
+ stream,
236
+ current: { totalBytes: info.size, mtimeMs },
237
+ };
238
+ }
239
+ const available = info.size - range.offset;
240
+ const download = {
241
+ sessionId,
242
+ active,
243
+ stream,
244
+ transferId: `dl-${stream}-${Date.now()}`,
245
+ fileName: basename(resolved),
246
+ mimeType: mimeHintForFile(resolved),
247
+ totalBytes: info.size,
248
+ mtimeMs,
249
+ offset: range.offset,
250
+ length: Math.min(range.requestedLength ?? available, available),
251
+ handle,
252
+ };
253
+ handedOver = true;
254
+ return { ok: true, download };
255
+ }
256
+ catch {
257
+ return { ok: false, error: "unreadable", stream };
258
+ }
259
+ finally {
260
+ if (!handedOver)
261
+ await handle.close().catch(() => { });
262
+ }
263
+ }
264
+ /** Forget a finished or rejected download. A no-op once the session's downloads were dropped. */
265
+ release(sessionId, stream, active) {
266
+ const mine = this.downloads.get(sessionId);
267
+ if (!mine || mine.get(stream) !== active)
268
+ return;
269
+ mine.delete(stream);
270
+ this.releaseSession(sessionId, mine);
271
+ }
272
+ releaseSession(sessionId, mine) {
273
+ if (mine.size === 0 && this.downloads.get(sessionId) === mine)
274
+ this.downloads.delete(sessionId);
107
275
  }
108
276
  /**
109
- * Validate + consume the token, then stream the file as `Begin → Chunk* → End` binary frames.
277
+ * Stream an opened download as `Begin → Chunk* → End` binary frames, then close its file.
110
278
  *
111
- * With `pacing`, the disk read pauses while the socket's queue is above the high-water mark, so a
112
- * client that reads slowly costs the daemon about that much memory, not the whole file. A read
113
- * error sends one `Error` frame and stops (no `End`); a socket that closed mid-transfer ends it
114
- * silently.
279
+ * The disk read pauses while the socket's queue is above the high-water mark, so a client that
280
+ * reads slowly costs the daemon about that much memory, not the whole file. A read error, or a
281
+ * file that ended before the announced length, sends one `Error` frame and no `End`; a socket
282
+ * that closed mid-transfer ends it silently. Never rejects: it runs detached from the request.
115
283
  */
116
- async startDownload(token, stream, sink, pacing) {
117
- const path = this.tokenStore.consume(token);
118
- if (!path)
119
- return { ok: false, error: "invalid_or_expired_token" };
120
- const transferId = `dl-${stream}-${Date.now()}`;
121
- sink(encodeFileTransferFrame({
122
- opcode: "Begin",
123
- stream,
124
- meta: { transferId, fileName: basename(path), mimeType: mimeHintForFile(path) },
125
- }));
126
- const outcome = await this.pipeFile(path, stream, sink, pacing);
127
- if (outcome === "closed")
128
- return { ok: false, error: "connection_closed", transferId };
129
- if (outcome === "error") {
130
- sink(encodeFileTransferFrame({ opcode: "Error", stream, message: "read_failed" }));
131
- return { ok: false, error: "read_failed", transferId };
284
+ async streamDownload(d, sink, pacing) {
285
+ try {
286
+ if (d.active.stop === "closed" || !pacing.isOpen())
287
+ return;
288
+ if (d.active.stop === "cancelled") {
289
+ // Cancelled between the answer and the first frame: no `Begin` was promised yet.
290
+ sink(encodeFileTransferFrame({ opcode: "Error", stream: d.stream, message: "cancelled" }));
291
+ return;
292
+ }
293
+ sink(encodeFileTransferFrame({
294
+ opcode: "Begin",
295
+ stream: d.stream,
296
+ meta: {
297
+ transferId: d.transferId,
298
+ fileName: d.fileName,
299
+ mimeType: d.mimeType,
300
+ totalBytes: d.totalBytes,
301
+ mtimeMs: d.mtimeMs,
302
+ offset: d.offset,
303
+ length: d.length,
304
+ },
305
+ }));
306
+ const outcome = await this.pipeRange(d, sink, pacing);
307
+ if (outcome === "closed")
308
+ return;
309
+ sink(encodeFileTransferFrame(outcome === "end"
310
+ ? { opcode: "End", stream: d.stream, ok: true }
311
+ : { opcode: "Error", stream: d.stream, message: outcome }));
312
+ }
313
+ catch {
314
+ // A send to a socket that closed under us throws; there is nobody left to tell.
315
+ }
316
+ finally {
317
+ this.release(d.sessionId, d.stream, d.active);
318
+ await d.handle.close().catch(() => { });
132
319
  }
133
- sink(encodeFileTransferFrame({ opcode: "End", stream, ok: true }));
134
- return { ok: true, transferId };
135
320
  }
136
- pipeFile(path, stream, sink, pacing) {
321
+ pipeRange(d, sink, pacing) {
322
+ if (d.length === 0)
323
+ return Promise.resolve("end");
137
324
  const { promise, resolve } = Promise.withResolvers();
138
- const rs = createReadStream(path, { highWaterMark: this.chunkBytes });
325
+ const rs = d.handle.createReadStream({
326
+ start: d.offset,
327
+ end: d.offset + d.length - 1,
328
+ highWaterMark: this.chunkBytes,
329
+ autoClose: false,
330
+ });
331
+ let sent = 0;
139
332
  let settled = false;
333
+ const stopped = () => (d.active.stop === "cancelled" ? "cancelled" : "closed");
140
334
  const finish = (outcome) => {
141
335
  if (settled)
142
336
  return;
143
337
  settled = true;
338
+ d.active.wake = undefined;
144
339
  rs.destroy();
145
340
  resolve(outcome);
146
341
  };
342
+ d.active.wake = () => {
343
+ if (d.active.stop)
344
+ finish(stopped());
345
+ };
147
346
  rs.on("data", (chunk) => {
148
347
  if (settled)
149
348
  return;
150
- if (pacing && !pacing.isOpen())
349
+ if (d.active.stop)
350
+ return finish(stopped());
351
+ if (!pacing.isOpen())
151
352
  return finish("closed");
152
353
  const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
153
- sink(encodeFileTransferFrame({ opcode: "Chunk", stream, data: new Uint8Array(bytes) }));
154
- const queued = pacing?.bufferedAmount();
155
- if (pacing && queued !== undefined && queued > this.highWaterBytes) {
354
+ try {
355
+ sink(encodeFileTransferFrame({
356
+ opcode: "Chunk",
357
+ stream: d.stream,
358
+ data: new Uint8Array(bytes),
359
+ }));
360
+ }
361
+ catch {
362
+ return finish("closed");
363
+ }
364
+ sent += bytes.length;
365
+ const queued = pacing.bufferedAmount();
366
+ if (queued !== undefined && queued > this.highWaterBytes) {
156
367
  rs.pause();
157
- void this.waitForDrain(pacing).then((stillOpen) => {
368
+ void this.waitForDrain(pacing, () => settled).then((stillOpen) => {
158
369
  if (!stillOpen)
159
370
  finish("closed");
160
371
  else if (!settled)
@@ -162,14 +373,18 @@ export class FileTransferService {
162
373
  });
163
374
  }
164
375
  });
165
- rs.on("end", () => finish("end"));
166
- rs.on("error", () => finish("error"));
376
+ // The range is bounded, so a short read means the file shrank after the size was announced.
377
+ rs.on("end", () => finish(sent === d.length ? "end" : "changed"));
378
+ rs.on("error", () => finish("read_failed"));
167
379
  return promise;
168
380
  }
169
- /** Resolves `true` once the socket's queue is at or below the low-water mark; `false` if it closed. */
170
- async waitForDrain(pacing) {
381
+ /**
382
+ * Resolves `true` once the socket's queue is at or below the low-water mark; `false` if it closed
383
+ * or the download ended (`ended`) while waiting.
384
+ */
385
+ async waitForDrain(pacing, ended) {
171
386
  for (;;) {
172
- if (!pacing.isOpen())
387
+ if (ended() || !pacing.isOpen())
173
388
  return false;
174
389
  const queued = pacing.bufferedAmount();
175
390
  if (queued === undefined || queued <= this.lowWaterBytes)
@@ -197,7 +412,8 @@ export class FileTransferService {
197
412
  }
198
413
  /**
199
414
  * Release everything a session left open: its pending uploads lose their stream id and their file
200
- * handle is closed once frames already in flight finish. Nothing is sent (the session is gone).
415
+ * handle is closed once frames already in flight finish; its downloads stop reading and lose
416
+ * their stream id and file handle. Nothing is sent (the session is gone).
201
417
  */
202
418
  disposeSession(session) {
203
419
  for (const [stream, upload] of this.uploads) {
@@ -207,6 +423,15 @@ export class FileTransferService {
207
423
  upload.done = true;
208
424
  upload.chain = upload.chain.then(() => upload.handle?.close().catch(() => { }));
209
425
  }
426
+ const mine = this.downloads.get(session.id);
427
+ if (!mine)
428
+ return;
429
+ this.downloads.delete(session.id);
430
+ for (const active of mine.values()) {
431
+ active.stop = "closed";
432
+ active.wake?.();
433
+ void active.handle?.close().catch(() => { });
434
+ }
210
435
  }
211
436
  async handleUploadFrame(session, upload, frame) {
212
437
  if (upload.done)
@@ -1,5 +1,4 @@
1
1
  export * from "./file-explorer.js";
2
- export * from "./download-token-store.js";
3
2
  export * from "./file-transfer.js";
4
3
  export * from "./limits.js";
5
4
  //# sourceMappingURL=index.d.ts.map
@@ -1,6 +1,5 @@
1
1
  // File explorer (list/preview + path safety) and binary file transfer.
2
2
  export * from "./file-explorer.js";
3
- export * from "./download-token-store.js";
4
3
  export * from "./file-transfer.js";
5
4
  export * from "./limits.js";
6
5
  //# sourceMappingURL=index.js.map
@@ -20,6 +20,9 @@ function toClientInfo(session) {
20
20
  clientId: session.clientId,
21
21
  clientType: session.clientType,
22
22
  ...(session.platform !== undefined ? { platform: session.platform } : {}),
23
+ ...(session.agentStreams !== undefined && session.agentStreams !== "all"
24
+ ? { agentStreams: session.agentStreams }
25
+ : {}),
23
26
  ...(session.appVersion !== undefined ? { appVersion: session.appVersion } : {}),
24
27
  connectedAt: session.connectedAt,
25
28
  ...(session.remoteAddress !== undefined ? { remoteAddress: session.remoteAddress } : {}),
@@ -57,6 +57,8 @@ export function variantKey(frame) {
57
57
  const payload = m.payload;
58
58
  return payload.ok ? "agent_ui_respond_response.ok" : "agent_ui_respond_response.not_found";
59
59
  }
60
+ case "file_download_response":
61
+ return m.ok === true ? type : "file_download_response.rejected";
60
62
  case "pong":
61
63
  case "daemon_status_response":
62
64
  case "daemon_status_subscribe_response":
@@ -74,8 +76,7 @@ export function variantKey(frame) {
74
76
  case "interrupt_response":
75
77
  case "agent_ui_list_response":
76
78
  case "rpc_error":
77
- case "file_download_token_response":
78
- case "file_download_response":
79
+ case "file_download_cancel_response":
79
80
  case "file_upload_response":
80
81
  case "file_upload_complete":
81
82
  case "create_terminal_response":
@@ -116,16 +117,29 @@ function uploadFrames(stream, transferId) {
116
117
  ];
117
118
  }
118
119
  /**
119
- * File transfer, all inside a temp dir: token → download of a small file; upload with `ack: true`
120
- * driven as a client (Begin/Chunk/End), then the `file_upload_complete` push.
120
+ * File transfer, all inside a temp dir: a whole-file download, a guarded ranged one, a rejected
121
+ * one and a cancel for an idle stream; upload with `ack: true` driven as a client
122
+ * (Begin/Chunk/End), then the `file_upload_complete` push.
121
123
  */
122
124
  async function runFileTransferSteps(client) {
123
125
  const dir = await mkdtemp(join(tmpdir(), "pi-studio-fixture-"));
124
126
  try {
125
127
  const downloadPath = join(dir, "download.txt");
126
128
  await writeFile(downloadPath, SCENARIO_DOWNLOAD_TEXT);
127
- const tokenResponse = await client.rpc("file_download_token_request", { path: downloadPath });
128
- await client.rpc("file_download_request", { token: String(tokenResponse.token) });
129
+ const first = await client.rpc("file_download_request", { path: downloadPath });
130
+ // A guarded range over the file's real size and mtime, as a resuming client sends it.
131
+ const ranged = await client.rpc("file_download_request", {
132
+ path: downloadPath,
133
+ offset: 8,
134
+ length: 16,
135
+ ifUnchanged: { size: first.totalBytes, mtimeMs: first.mtimeMs },
136
+ });
137
+ if (ranged.ok !== true)
138
+ throw new Error(`ranged download was rejected: ${String(ranged.error)}`);
139
+ // A rejection (no such file) and a cancel for a stream nothing runs on (the cancel outcome
140
+ // that is the same every run; `ok: true` needs a download still in flight).
141
+ await client.rpc("file_download_request", { path: join(dir, "missing.txt") });
142
+ await client.rpc("file_download_cancel_request", { stream: 200 });
129
143
  const transferId = "scenario-upload";
130
144
  const uploadPath = join(dir, "upload.txt");
131
145
  const upload = await client.rpc("file_upload_request", {
@@ -14,6 +14,13 @@ export interface RpcHandlerContext {
14
14
  session: Session;
15
15
  message: Record<string, unknown>;
16
16
  requestId?: string;
17
+ /**
18
+ * Run `fn` once the router has sent this handler's reply. A handler that must put frames on the
19
+ * wire strictly after its answer (a download's binary stream) schedules them here instead of
20
+ * sending them from inside the awaited handler. Not run when the handler throws; a throwing `fn`
21
+ * is logged and never reaches the client as an `rpc_error`.
22
+ */
23
+ afterReply(fn: () => void): void;
17
24
  }
18
25
  /** A handler returns a response message (wrapped + correlated by the router) or `undefined`. */
19
26
  export type RpcHandler = (ctx: RpcHandlerContext) => unknown | Promise<unknown>;
package/dist/ws/router.js CHANGED
@@ -44,16 +44,35 @@ async function dispatchSessionMessage(session, message, registry) {
44
44
  }
45
45
  const startedAt = Date.now();
46
46
  try {
47
- const result = await handler({ session, message, requestId });
47
+ const afterReply = [];
48
+ const result = await handler({
49
+ session,
50
+ message,
51
+ requestId,
52
+ afterReply: (fn) => afterReply.push(fn),
53
+ });
48
54
  registry.logger?.debug({ type, requestId, clientId: session.clientId, durationMs: Date.now() - startedAt }, "rpc ok");
49
- if (result !== undefined) {
50
- const response = requestId &&
51
- typeof result === "object" &&
52
- result !== null &&
53
- result.requestId === undefined
54
- ? { ...result, requestId }
55
- : result;
56
- session.send({ type: "session", message: response });
55
+ try {
56
+ if (result !== undefined) {
57
+ const response = requestId &&
58
+ typeof result === "object" &&
59
+ result !== null &&
60
+ result.requestId === undefined
61
+ ? { ...result, requestId }
62
+ : result;
63
+ session.send({ type: "session", message: response });
64
+ }
65
+ }
66
+ finally {
67
+ // Hooks run even when the send threw (a closed socket) so they can release what they hold.
68
+ for (const fn of afterReply) {
69
+ try {
70
+ fn();
71
+ }
72
+ catch (error) {
73
+ registry.logger?.warn({ type, requestId, clientId: session.clientId, err: error?.message }, "rpc after-reply hook failed");
74
+ }
75
+ }
57
76
  }
58
77
  }
59
78
  catch (error) {
@@ -1,4 +1,11 @@
1
1
  import type { WebSocket } from "ws";
2
+ /** What a connection receives of `agent_stream` frames (`hello.agentStreams`). */
3
+ export type AgentStreamMode = "all" | "none";
4
+ /**
5
+ * The sessions that may receive an `agent_stream` frame: everyone except `"none"` sessions. Every
6
+ * place that sends one MUST pass its audience through here (an absent mode counts as `"all"`).
7
+ */
8
+ export declare function agentStreamRecipients(sessions: Iterable<Session>): Session[];
2
9
  /**
3
10
  * A per-connection session (architecture/websocket-protocol.md § Behavior). Holds the client
4
11
  * identity, the (rehydrated) capability set, and the socket. The wire boundary asks exactly one
@@ -10,6 +17,8 @@ export declare class Session {
10
17
  readonly clientType: string;
11
18
  /** The hello's `platform` (e.g. `"desktop"`), verbatim when the client sent one. Informational. */
12
19
  readonly platform: string | undefined;
20
+ /** The hello's `agentStreams` mode; fixed for the life of the connection. */
21
+ readonly agentStreams: AgentStreamMode;
13
22
  capabilities: Record<string, boolean>;
14
23
  /** Epoch ms of the handshake. A wall-clock fact for the connected-clients list. */
15
24
  readonly connectedAt: number;
@@ -24,6 +33,7 @@ export declare class Session {
24
33
  clientId: string;
25
34
  clientType: string;
26
35
  platform?: string;
36
+ agentStreams?: AgentStreamMode;
27
37
  capabilities: Record<string, boolean>;
28
38
  socket: WebSocket;
29
39
  connectedAt?: number;
@@ -1,6 +1,18 @@
1
1
  import { supports } from "@av-pi-studio/protocol";
2
2
  /** `WebSocket.OPEN` (the `ws` package's readyState for an open socket). */
3
3
  const WS_OPEN = 1;
4
+ /**
5
+ * The sessions that may receive an `agent_stream` frame: everyone except `"none"` sessions. Every
6
+ * place that sends one MUST pass its audience through here (an absent mode counts as `"all"`).
7
+ */
8
+ export function agentStreamRecipients(sessions) {
9
+ const out = [];
10
+ for (const session of sessions) {
11
+ if (session.agentStreams !== "none")
12
+ out.push(session);
13
+ }
14
+ return out;
15
+ }
4
16
  /**
5
17
  * A per-connection session (architecture/websocket-protocol.md § Behavior). Holds the client
6
18
  * identity, the (rehydrated) capability set, and the socket. The wire boundary asks exactly one
@@ -12,6 +24,8 @@ export class Session {
12
24
  clientType;
13
25
  /** The hello's `platform` (e.g. `"desktop"`), verbatim when the client sent one. Informational. */
14
26
  platform;
27
+ /** The hello's `agentStreams` mode; fixed for the life of the connection. */
28
+ agentStreams;
15
29
  capabilities;
16
30
  /** Epoch ms of the handshake. A wall-clock fact for the connected-clients list. */
17
31
  connectedAt;
@@ -26,6 +40,7 @@ export class Session {
26
40
  this.clientId = opts.clientId;
27
41
  this.clientType = opts.clientType;
28
42
  this.platform = opts.platform;
43
+ this.agentStreams = opts.agentStreams ?? "all";
29
44
  this.capabilities = opts.capabilities;
30
45
  this.connectedAt = opts.connectedAt ?? Date.now();
31
46
  this.appVersion = opts.appVersion;
@@ -72,6 +72,7 @@ export function createWebSocketServer(httpServer, deps) {
72
72
  clientId: hello.data.clientId,
73
73
  clientType: hello.data.clientType,
74
74
  platform: hello.data.platform,
75
+ agentStreams: hello.data.agentStreams,
75
76
  capabilities,
76
77
  socket: ws,
77
78
  appVersion: hello.data.appVersion,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@av-pi-studio/server",
3
- "version": "0.0.118",
3
+ "version": "0.0.120",
4
4
  "bin": {
5
5
  "pi-studio-daemon": "dist/daemon/main.js"
6
6
  },
@@ -24,8 +24,8 @@
24
24
  "clean": "rm -rf dist *.tsbuildinfo"
25
25
  },
26
26
  "dependencies": {
27
- "@av-pi-studio/protocol": "^0.0.118",
28
- "@av-pi-studio/relay": "^0.0.118",
27
+ "@av-pi-studio/protocol": "^0.0.120",
28
+ "@av-pi-studio/relay": "^0.0.120",
29
29
  "@earendil-works/pi-coding-agent": "^1.4.0",
30
30
  "@xterm/addon-serialize": "^0.14.0",
31
31
  "@xterm/headless": "^6.0.0",
@@ -1,14 +0,0 @@
1
- export declare class DownloadTokenStore {
2
- private readonly ttlMs;
3
- private readonly now;
4
- private readonly tokens;
5
- constructor(ttlMs?: number, now?: () => number, maxTokens?: number);
6
- /** Issue a single-use token for `path`. */
7
- issue(path: string): {
8
- token: string;
9
- expiresAt: number;
10
- };
11
- /** Validate + consume a token. Returns the path, or null if invalid/expired/already used. */
12
- consume(token: string): string | null;
13
- }
14
- //# sourceMappingURL=download-token-store.d.ts.map
@@ -1,33 +0,0 @@
1
- import { randomUUID } from "node:crypto";
2
- import { LRUCache } from "lru-cache";
3
- export class DownloadTokenStore {
4
- ttlMs;
5
- now;
6
- tokens;
7
- constructor(ttlMs = 10 * 60_000, now = () => Date.now(), maxTokens = 10_000) {
8
- this.ttlMs = ttlMs;
9
- this.now = now;
10
- this.tokens = new LRUCache({ max: maxTokens });
11
- }
12
- /** Issue a single-use token for `path`. */
13
- issue(path) {
14
- const token = randomUUID();
15
- const expiresAt = this.now() + this.ttlMs;
16
- this.tokens.set(token, { path, expiresAt, used: false });
17
- return { token, expiresAt };
18
- }
19
- /** Validate + consume a token. Returns the path, or null if invalid/expired/already used. */
20
- consume(token) {
21
- const entry = this.tokens.get(token);
22
- if (!entry)
23
- return null;
24
- if (entry.used || entry.expiresAt < this.now()) {
25
- this.tokens.delete(token);
26
- return null;
27
- }
28
- entry.used = true;
29
- this.tokens.delete(token); // single-use
30
- return entry.path;
31
- }
32
- }
33
- //# sourceMappingURL=download-token-store.js.map