@basein/runner 0.2.12 → 0.3.1

package/dist/control/recorder-keeper.d.ts

@@ -0,0 +1,229 @@
+/**
+ * recorder-keeper — the background recorder's sign-in, kept current without
+ * ever standing between Claude Code and a hook.
+ *
+ * WHAT WAS WRONG. `bir-hooks` used to settle its sign-in *before* it listened:
+ * a `GET /health` to check the address, then — whenever the access token had
+ * expired, which is every first session of the day — a `POST /auth/refresh`,
+ * neither with a timeout. A service that was slow, blackholed, or behind a
+ * proxy that accepts and never answers held the port closed for 10-300 s, and
+ * every hook of every session in that window was refused (Claude Code shows
+ * each as a hook error). Worse, a refresh that failed for *any* reason — the
+ * Wi-Fi not up yet after a wake — was read as "not signed in": the recorder
+ * built a `NullRecorder`, logged "run `bir login`", and recorded nothing for
+ * the rest of its life, which is days. Following that advice changed nothing.
+ *
+ * WHAT IT DOES NOW. The recorder is decided from disk alone — the stored
+ * address and credentials.json — so it exists before the port is bound, with
+ * no network at all. An expired access token is not a reason to stop: the
+ * `RemoteRecorder` refreshes on its first 401 and adopts a sibling's refresh.
+ * Then, in the background and bounded by timeouts, this keeper:
+ *
+ *   - refreshes the token a little before it expires (and right away when it
+ *     already has), so the first prompt of the day does not pay for it;
+ *   - notices a sign-in appearing, changing or being removed on disk — `bir
+ *     login`, `bir setup`, `bir logout`, a sibling's refresh — and swaps the
+ *     backend of the {@link SwitchableRecorder} the control server holds. No
+ *     restart. A signed-out recorder checks again the moment a prompt arrives,
+ *     so the prompt after `bir login` is already recorded;
+ *   - tells a *rejected* sign-in (the API answered 400/401/403 with its own
+ *     JSON error) from a *missing* service (no answer, a timeout, 5xx, 429, or
+ *     a page that is not the API — a WAF's or a captive portal's HTML 403 is
+ *     not a verdict on the sign-in). Only the first stops recording and says
+ *     "run `bir login`", and even then the refusal is asked once more half an
+ *     hour later before it is final; the second keeps the saved sign-in,
+ *     retries with backoff, and says so.
+ *
+ * NOTHING HERE IS ON A HOT PATH. Every network call is in a timer or behind a
+ * hook's answer, has a timeout, and reports to `serviceHealth`, so a hook that
+ * *does* wait for the service (a prompt match) knows not to while it is down.
+ * While the runner is switched off (`bir off`) the keeper makes no calls.
+ */
+import { type AuthSession } from "../auth/client.js";
+import { type Recorder } from "../record/recorder.js";
+import { SwitchableRecorder } from "../record/switchable-recorder.js";
+/** Why the recorder is (or is not) recording right now. */
+export type KeeperState = 
+/** A session and an address: steps go to the service. */
+"recording"
+/** A session, and a plain-http address still being checked for an https redirect. */
+ | "settling"
+/** No service address at all. */
+ | "no_address"
+/** No credentials.json. */
+ | "signed_out"
+/** Credentials issued by another service than the configured one. */
+ | "other_service"
+/** The service refused the saved refresh token. */
+ | "rejected";
+interface Decision {
+    state: KeeperState;
+    baseUrl?: string;
+    session?: AuthSession;
+    /** For `other_service`: the address the saved sign-in belongs to. */
+    issuer?: string;
+}
+/**
+ * True for a plain-http address that is not this machine. Such an address may
+ * sit behind a TLS proxy that answers `308 → https`, and following that drops
+ * the bearer token (auth/client.ts, normalizeAuthUrl) — so nothing is sent to
+ * it until that has been checked. https needs no check, and a loopback address
+ * is neither redirected by a TLS front nor readable on the network.
+ */
+export declare function needsSettling(url: string): boolean;
+/**
+ * What the files on disk say the recorder should be. No network.
+ *
+ * `settled` maps a configured plain-http address to what its check found.
+ */
+export declare function decideFromDisk(settled?: ReadonlyMap<string, string>): Decision;
+export type RefreshOutcome = {
+    kind: "ok";
+    session: AuthSession;
+}
+/** The API answered and refused this refresh token. */
+ | {
+    kind: "rejected";
+    status: number;
+}
+/** No usable answer: network, timeout, 5xx, 429, or something that is not the API. */
+ | {
+    kind: "unreachable";
+    reason: string;
+};
+/**
+ * One `POST /auth/refresh`, bounded, reported to `serviceHealth`.
+ *
+ * `authenticate()` answers "no session" for every failure alike, which is what
+ * turned a network blip into "run `bir login`". This one says which it was.
+ */
+export declare function refreshSession(baseUrl: string, session: AuthSession, fetchImpl?: typeof fetch, timeoutMs?: number, now?: () => number): Promise<RefreshOutcome>;
+export interface RecorderKeeperOptions {
+    /** The project directory: decides the per-project off switch. */
+    cwd: string;
+    /** Injected by tests; defaults to the global fetch. */
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    /** How often the background check runs. Default 60 s. */
+    tickMs?: number;
+    /** When the first check runs after {@link RecorderKeeper.start}. Default 250 ms. */
+    firstTickMs?: number;
+    /** Refresh this long before the access token expires. Default 10 min. */
+    refreshAheadMs?: number;
+    /**
+     * Do not refresh an already-expired token this soon after a run started: the
+     * backend's own 401-refresh is likely in flight, and two refreshes of one
+     * rotating token lose one of them. Default 20 s.
+     */
+    quietMs?: number;
+    /** After a rejected refresh, how long to wait before re-reading the file. Default 1 s. */
+    rejectRecheckMs?: number;
+    /**
+     * After a rejected refresh, when to try it once more before the refusal is
+     * final. Default 30 min. Something that is not the API can still answer in
+     * its place with JSON; this bounds what such an answer costs.
+     */
+    rejectRetryMs?: number;
+    /** Builds the backend for a session. Injected by tests. */
+    makeRemote?: (baseUrl: string, session: AuthSession) => Recorder;
+}
+export declare class RecorderKeeper {
+    readonly recorder: SwitchableRecorder;
+    /**
+     * The one backend used whenever nothing is recorded. One per process, not
+     * one per sign-out: a `NullRecorder` numbers its runs itself, and a fresh
+     * one after every logout or settle handed out `run_local_1` again — two
+     * runs under one id in the journal `bir investigate` reads.
+     */
+    private readonly idle;
+    private readonly opts;
+    private readonly now;
+    private readonly fetchImpl;
+    private stateNow;
+    /** The address and session the current backend was built from (when recording). */
+    private baseUrl?;
+    private session?;
+    /** The decision waiting for its plain-http address to be checked. */
+    private pending?;
+    /** configured http address → what the check found. */
+    private readonly settled;
+    private settling?;
+    private diskStamp;
+    /** A refresh token the service refused; a file still holding it is not a sign-in. */
+    private rejectedRefreshToken?;
+    /** The refusal waiting for its one more try (see {@link RecorderKeeperOptions.rejectRetryMs}). */
+    private refused?;
+    private nextRefreshAt;
+    private refreshFailures;
+    private lastRunStartedAt;
+    private ticking;
+    private timers;
+    constructor(opts: RecorderKeeperOptions);
+    /** Why the recorder is or is not recording. */
+    get state(): KeeperState;
+    /**
+     * What `/health` reports as `recording`. True while a plain-http address is
+     * being checked too: there is a sign-in, and recording starts the moment the
+     * address answers — a "no session" there would send people to `bir login`
+     * for nothing.
+     */
+    get recording(): boolean;
+    /** The account recordings land in, for `/health`. */
+    get account(): string | undefined;
+    /** The service address replay should call, while there is a session for it. */
+    get authUrl(): string | undefined;
+    /** The live access token (C5): read on every use, never kept. */
+    currentAccessToken(): string | undefined;
+    /** Start the background checks. Timers are unref'd: they never keep the process up. */
+    start(): void;
+    stop(): void;
+    /**
+     * One background pass: look at the files, check a plain-http address,
+     * refresh a token that is due. Never throws; never overlaps itself.
+     */
+    tick(): Promise<void>;
+    /**
+     * Re-read the sign-in and the address if either file changed. Local and
+     * cheap: two `stat`s, and a read only when one of them moved.
+     */
+    checkDisk(): void;
+    private stamp;
+    private makeRemote;
+    /** Act on a decision: swap the backend when it changes what is recorded where. */
+    private apply;
+    private install;
+    private goIdle;
+    private explain;
+    /**
+     * Check a plain-http address for an https redirect, once it answers. Until
+     * then nothing is sent to it: a token sent before the check could go out in
+     * the clear to a host that would have redirected it.
+     */
+    private settle;
+    /** Refresh the access token when it is due, telling a refusal from an outage. */
+    private maybeRefresh;
+    /**
+     * Save a rotated session whatever happened meanwhile — the service has spent
+     * the refresh token on disk — unless the file no longer holds the one spent
+     * (a logout removed it, or a new sign-in replaced it), which is not ours to
+     * overwrite.
+     */
+    private saveRefreshed;
+    /**
+     * Decide from the files as they are now, whatever the last stamp said: after
+     * a logout this goes idle, after a sign-in as someone else it records to
+     * them, and after a sibling's refresh of the same sign-in it adopts the
+     * sibling's token (the `same` branch of {@link apply}).
+     */
+    private decideFromDiskNow;
+    /**
+     * A refusal is asked once more, {@link REJECT_RETRY_MS} later, before it is
+     * final: whatever stands in front of the API can answer for it in JSON too,
+     * and a sign-in that was never really refused should not cost more than
+     * that half hour. A second refusal is final until the file changes (`bir
+     * login`); no answer at all is asked again after another interval.
+     */
+    private maybeRetryRefused;
+}
+export {};
+//# sourceMappingURL=recorder-keeper.d.ts.map