|
|
|
|
@@ -1,43 +1,13 @@
|
|
|
|
|
/**
|
|
|
|
|
* The timing-and-classification half of a timeout — a zero-dependency library
|
|
|
|
|
* of pure functions shared by every capability that clamps a caller's timeout
|
|
|
|
|
* hint, arms a deadline, and later has to tell "timed out" apart from
|
|
|
|
|
* "cancelled". It owns NO termination: the returned {@link deadline} signal only
|
|
|
|
|
* NOTIFIES; actually stopping the work (SIGKILL a process group, tear down a
|
|
|
|
|
* fetch socket, …) stays in each capability's implementation, because that
|
|
|
|
|
* mechanism differs per capability and no shared layer can own all of them.
|
|
|
|
|
*
|
|
|
|
|
* This is deliberately a library, not a cordis service or plugin: it takes no
|
|
|
|
|
* `ctx`, registers nothing, holds no cross-call state, and emits no events. A
|
|
|
|
|
* "timeout service" would have to understand how to stop every capability's
|
|
|
|
|
* work — exactly the knowledge a microkernel keeps out of shared layers.
|
|
|
|
|
*
|
|
|
|
|
* The four exports and their division of labor:
|
|
|
|
|
* - {@link clampTimeout} — validate a caller's optional positive hint, fill the
|
|
|
|
|
* backend default, cap at the backend max (pure arithmetic + the shared
|
|
|
|
|
* positive-finite request contract).
|
|
|
|
|
* - {@link deadline} — fuse upstream cancellation with a timeout into one
|
|
|
|
|
* `AbortSignal`, the timeout carrying an identifiable {@link TimeoutReason};
|
|
|
|
|
* `[Symbol.dispose]` clears the timer.
|
|
|
|
|
* - {@link timeoutOf} — classify an aborted signal (or error): a
|
|
|
|
|
* {@link TimeoutReason} means the timeout fired, anything else (or nothing)
|
|
|
|
|
* means it did not.
|
|
|
|
|
* - {@link TimeoutReason} — the internal classification reason; providers
|
|
|
|
|
* translate it into their own public error/result shape before returning.
|
|
|
|
|
*
|
|
|
|
|
* Shared timeout arithmetic, signal fusion, and classification. The library
|
|
|
|
|
* only notifies through abort signals; each capability still owns the mechanism
|
|
|
|
|
* that stops its work and translates timeout reasons into public outcomes.
|
|
|
|
|
* @module @deepseek-ai/dsh-timeout
|
|
|
|
|
*/
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* The internal reason attached to a timeout abort so consumers can classify it
|
|
|
|
|
* after the fact. It carries the failing `code` (each capability's own string —
|
|
|
|
|
* `BASH_TIMEOUT`, `WEB_FETCH_TIMEOUT`, …) and the `timeoutMs` that elapsed.
|
|
|
|
|
*
|
|
|
|
|
* It is an INTERNAL classification reason, not a public error: providers
|
|
|
|
|
* translate it into their seam-specific error code or result field (via
|
|
|
|
|
* {@link timeoutOf}) before returning to callers. Native `AbortSignal.timeout()`
|
|
|
|
|
* yields a fixed `TimeoutError` indistinguishable across timeout kinds; this
|
|
|
|
|
* type is identifiable and carries the code/duration.
|
|
|
|
|
* Internal abort reason carrying a capability-owned code and elapsed deadline.
|
|
|
|
|
* Providers translate it through {@link timeoutOf} before returning to callers.
|
|
|
|
|
*/
|
|
|
|
|
export class TimeoutReason extends Error {
|
|
|
|
|
override name = 'TimeoutReason'
|
|
|
|
|
@@ -52,16 +22,15 @@ export class TimeoutReason extends Error {
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Validate a caller's optional timeout hint, fill it from the backend default,
|
|
|
|
|
* then cap at the backend max. The shared positive-finite request contract:
|
|
|
|
|
* a supplied `requested` must be a positive finite number or this throws —
|
|
|
|
|
* `0` is NOT a caller-facing "disable timeout" value (that sentinel is internal
|
|
|
|
|
* to {@link deadline}). A missing `requested` falls back to `def`.
|
|
|
|
|
* Validate a caller's optional timeout hint, use the backend default, then cap
|
|
|
|
|
* it. Supplied values must be positive and finite; zero is not a public
|
|
|
|
|
* disable-timeout sentinel.
|
|
|
|
|
*
|
|
|
|
|
* @param requested The caller's optional hint; validated when present.
|
|
|
|
|
* @param def The backend default applied when `requested` is absent.
|
|
|
|
|
* @param max The backend upper bound the result is capped to.
|
|
|
|
|
* @param name Field name used in the thrown message (so the caller sees which input was bad).
|
|
|
|
|
* @param name Field name used in the thrown message (so the caller sees which input was
|
|
|
|
|
* bad).
|
|
|
|
|
* @returns The effective timeout in milliseconds: `min(requested ?? def, max)`.
|
|
|
|
|
*/
|
|
|
|
|
export function clampTimeout(
|
|
|
|
|
@@ -85,23 +54,9 @@ export interface Deadline {
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Build a deadline signal that aborts on upstream cancellation OR on timeout,
|
|
|
|
|
* with the timeout carrying an identifiable {@link TimeoutReason} (unlike
|
|
|
|
|
* native `AbortSignal.timeout()`, whose fixed `TimeoutError` is opaque). It is
|
|
|
|
|
* `AbortSignal.any([upstream, <timeout>])` — the single primitive that fuses
|
|
|
|
|
* two abort sources — with the reason and a disposable timer added on top.
|
|
|
|
|
*
|
|
|
|
|
* `timeoutMs <= 0` is the INTERNAL "no timeout" sentinel for backend-owned
|
|
|
|
|
* background work: arm no timer and forward only the upstream signal; with no
|
|
|
|
|
* upstream either, return a never-aborting signal so callers keep one call
|
|
|
|
|
* shape. External request hints validate as positive finite via
|
|
|
|
|
* {@link clampTimeout} before reaching here, so `0` never arrives from a model
|
|
|
|
|
* or plugin.
|
|
|
|
|
*
|
|
|
|
|
* The returned object's `[Symbol.dispose]` clears the timer — use `using` for a
|
|
|
|
|
* scope-lifetime consumer, or call it manually for an event-lifetime one. The
|
|
|
|
|
* signal only NOTIFIES; the caller must attach its own termination (kill the
|
|
|
|
|
* process group, abort the fetch, …).
|
|
|
|
|
* Fuse upstream cancellation with an identifiable timeout. `timeoutMs <= 0` is
|
|
|
|
|
* the internal no-timer sentinel; the returned disposer clears an armed timer.
|
|
|
|
|
* The signal only notifies, so callers must stop their own work.
|
|
|
|
|
*
|
|
|
|
|
* @param upstream The caller's cancellation signal, if any, fused into the result.
|
|
|
|
|
* @param timeoutMs Deadline in milliseconds; `<= 0` means "no timeout" (arm no timer).
|
|
|
|
|
@@ -114,9 +69,8 @@ export function deadline(
|
|
|
|
|
code: string,
|
|
|
|
|
): Deadline {
|
|
|
|
|
if (timeoutMs <= 0) {
|
|
|
|
|
// No timeout (background work): forward only the upstream signal, or a
|
|
|
|
|
// never-aborting one when there is no upstream. No timer, so dispose is a
|
|
|
|
|
// no-op — the empty method keeps the one call shape for every caller.
|
|
|
|
|
// No timeout (background work): forward only the upstream signal, or a never-aborting one
|
|
|
|
|
// when there is no upstream.
|
|
|
|
|
return { signal: upstream ?? new AbortController().signal, [Symbol.dispose]() {} }
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
@@ -132,22 +86,9 @@ export function deadline(
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
/**
|
|
|
|
|
* Recover the {@link TimeoutReason} from an aborted signal (or any object with a
|
|
|
|
|
* `reason`), else `undefined`. This is the classification half: a provider
|
|
|
|
|
* calls it on the deadline signal after an abort to decide whether the cause
|
|
|
|
|
* was its timeout (translate to the capability's timeout error/field) or an
|
|
|
|
|
* ordinary upstream cancellation (`undefined` → the cancel path).
|
|
|
|
|
*
|
|
|
|
|
* Pass `code` to scope the match to THIS deadline's timer. It matters under
|
|
|
|
|
* nesting: when the `upstream` handed to {@link deadline} is itself a deadline
|
|
|
|
|
* signal (e.g. a future `tools/execute` middleware arming a per-call deadline),
|
|
|
|
|
* `AbortSignal.any` preserves the OUTER `TimeoutReason` if the outer timer fires
|
|
|
|
|
* first. Without `code`, the inner capability would misclassify that outer
|
|
|
|
|
* timeout as its own (`timedOut:true` / `WEB_FETCH_TIMEOUT`) though its local
|
|
|
|
|
* timer never expired; with `code`, a foreign timeout reads as `undefined` and
|
|
|
|
|
* falls through to the upstream-cancel path, which is the correct classification
|
|
|
|
|
* from the inner capability's view. Omit `code` only to ask "was this ANY
|
|
|
|
|
* timeout" (a generic middleware that owns no single code).
|
|
|
|
|
* Recover a timeout reason from a reason-bearing object. Supplying `code`
|
|
|
|
|
* distinguishes this deadline from a nested upstream deadline; a foreign code
|
|
|
|
|
* follows the ordinary cancellation path.
|
|
|
|
|
*
|
|
|
|
|
* @param x An {@link AbortSignal} or any `{ reason }` carrier (e.g. a caught abort error).
|
|
|
|
|
* @param code When provided, only a {@link TimeoutReason} with this exact `code` matches.
|
|
|
|
|
|
Dudu-0223