Files
kandev/apps/web/lib/api/domains/queue-api.ts
T
José Almeida 83abe6d743 fix(queue): propagate transfer error + tighten WSError narrowing
- `Service.TransferSession` now returns an error so callers can fail
  closed instead of silently leaving entries orphaned on the previous
  session. The two existing call sites pick the right policy:
  `switchSessionForStep` (reusing an existing session) propagates the
  error so the workflow switch aborts; the new-session path logs and
  continues, since the new session is already committed and rolling
  back here would leave a half-switched workflow.
- `asWSError` now also narrows on `message` / `details`, so WS payloads
  without a `code` field are still mapped to a meaningful `Error.message`
  via `rethrowQueueError` (instead of "[object Object]"). Native
  `Error` instances explicitly skip the WS-error branch so they pass
  through untouched, preserving the existing pass-through guarantee.
- `queue-api.test.ts`: `expect.assertions(N)` on the catch-only tests
  so a missing throw fails the test instead of silently passing.
2026-05-10 21:22:00 +01:00

163 lines
5.1 KiB
TypeScript

import type { QueueStatus, QueuedMessage } from "@/lib/state/slices/session/types";
import { getWebSocketClient } from "@/lib/ws/connection";
const WS_CLIENT_UNAVAILABLE = "WebSocket client not available";
/** Error thrown when the queue would exceed its per-session cap. */
export class QueueFullError extends Error {
readonly code = "queue_full";
readonly queueSize: number;
readonly max: number;
constructor(queueSize: number, max: number) {
super(`Queue is full (${queueSize}/${max} pending). Wait for the next turn to drain.`);
this.name = "QueueFullError";
this.queueSize = queueSize;
this.max = max;
}
}
/** Error thrown when the targeted entry was already drained or does not exist. */
export class QueueEntryNotFoundError extends Error {
readonly code = "entry_not_found";
constructor() {
super("Queue entry was already drained or no longer exists.");
this.name = "QueueEntryNotFoundError";
}
}
type WSError = {
code?: string;
message?: string;
details?: { queue_size?: number; max?: number; [k: string]: unknown };
};
function asWSError(err: unknown): WSError | undefined {
// Some WS error payloads omit `code` and only carry `message`/`details`;
// narrowing on `code` alone would drop those and stringify the whole object
// as the eventual Error message ("[object Object]"). Real Error instances
// are skipped so they pass through unchanged in `rethrowQueueError`.
if (typeof err !== "object" || err === null || err instanceof Error) {
return undefined;
}
if ("code" in err || "message" in err || "details" in err) {
return err as WSError;
}
return undefined;
}
export function rethrowQueueError(err: unknown): never {
const wsErr = asWSError(err);
if (wsErr?.code === "queue_full") {
const size = typeof wsErr.details?.queue_size === "number" ? wsErr.details.queue_size : 0;
const max = typeof wsErr.details?.max === "number" ? wsErr.details.max : 0;
throw new QueueFullError(size, max);
}
if (wsErr?.code === "entry_not_found") {
throw new QueueEntryNotFoundError();
}
if (wsErr?.message) {
throw new Error(wsErr.message);
}
throw err instanceof Error ? err : new Error(String(err));
}
export type QueueMessageParams = {
session_id: string;
task_id: string;
content: string;
model?: string;
plan_mode?: boolean;
attachments?: Array<{ type: string; data: string; mime_type: string }>;
user_id?: string;
};
/** Append a new entry to the session's FIFO queue. Throws QueueFullError on overflow. */
export async function queueMessage(params: QueueMessageParams): Promise<QueuedMessage> {
const client = getWebSocketClient();
if (!client) {
throw new Error(WS_CLIENT_UNAVAILABLE);
}
try {
return await client.request<QueuedMessage>("message.queue.add", params);
} catch (err) {
rethrowQueueError(err);
}
}
/** Clear every pending entry for the session. */
export async function clearQueue(sessionId: string): Promise<{ removed: number }> {
const client = getWebSocketClient();
if (!client) {
throw new Error(WS_CLIENT_UNAVAILABLE);
}
return client.request<{ removed: number }>("message.queue.cancel", { session_id: sessionId });
}
/** Fetch the full queue snapshot (entries + capacity). */
export async function getQueueStatus(sessionId: string): Promise<QueueStatus> {
const client = getWebSocketClient();
if (!client) {
throw new Error(WS_CLIENT_UNAVAILABLE);
}
return client.request<QueueStatus>("message.queue.get", { session_id: sessionId });
}
/** Append content onto the tail entry when the same caller authored it; otherwise insert a new entry. */
export async function appendToQueue(params: {
session_id: string;
task_id: string;
content: string;
model?: string;
plan_mode?: boolean;
user_id?: string;
}): Promise<{ entry_id: string; was_append: boolean }> {
const client = getWebSocketClient();
if (!client) {
throw new Error(WS_CLIENT_UNAVAILABLE);
}
try {
return await client.request<{ entry_id: string; was_append: boolean }>(
"message.queue.append",
params,
);
} catch (err) {
rethrowQueueError(err);
}
}
/** Replace the content/attachments of a queued entry. Throws QueueEntryNotFoundError if drained. */
export async function updateQueuedMessage(params: {
session_id: string;
entry_id: string;
content: string;
attachments?: Array<{ type: string; data: string; mime_type: string }>;
user_id?: string;
}): Promise<{ entry_id: string }> {
const client = getWebSocketClient();
if (!client) {
throw new Error(WS_CLIENT_UNAVAILABLE);
}
try {
return await client.request<{ entry_id: string }>("message.queue.update", params);
} catch (err) {
rethrowQueueError(err);
}
}
/** Remove a single queued entry by id. Throws QueueEntryNotFoundError if drained. */
export async function removeQueuedEntry(params: {
session_id: string;
entry_id: string;
}): Promise<{ entry_id: string }> {
const client = getWebSocketClient();
if (!client) {
throw new Error(WS_CLIENT_UNAVAILABLE);
}
try {
return await client.request<{ entry_id: string }>("message.queue.remove", params);
} catch (err) {
rethrowQueueError(err);
}
}