@maci0/dsh-quota-check 0.12.2

package/lib/index.js

@@ -0,0 +1,469 @@
+/**
+ * dsh-quota-check: one statusbar figure for the provider the current session
+ * is using: the remaining balance on a pure API-billing route, or the plan
+ * quota on a subscription route.
+ *
+ * Two halves, one endpoint:
+ *
+ * - this host half owns the provider credential and the outbound request, and
+ *   serves one JSON reply from `GET /quota-check?provider=<id>`. That is the
+ *   only way a browser half can reach a provider key: the key stays in this
+ *   process, and the browser only ever sees the formatted figure.
+ * - `lib/client.js` registers the chip in `conversation.composer.dock` (the
+ *   statusbar row directly under the composer and its model selector) and
+ *   asks this route for the provider the session's model selection names.
+ *
+ * Which endpoints answer is `probes.ts`; the credential and the reading are
+ * resolved once per provider and cached for {@link DEFAULT_CACHE_SECONDS}, so
+ * a rerender, a session switch, or a second tab never multiplies provider
+ * traffic.
+ *
+ * @module dsh-quota-check
+ */
+import Schema from '@deepseek-ai/schemastery';
+import { localRequests } from './local-usage.js';
+import { resolveProbe } from './probes.js';
+import { record } from './util.js';
+/** Plugin name as it appears in the loader. */
+export const name = 'quota-check';
+/**
+ * The route carrier, and the trust fence the route checks first: without
+ * `connection` nothing would refuse a cross-origin or unauthenticated caller,
+ * so the plugin waits for it rather than serving unfenced.
+ */
+export const inject = ['webServer', 'connection'];
+/** The route the browser half reads. */
+export const ROUTE = '/quota-check';
+/** Seconds one provider's reading is served without re-asking the provider. */
+export const DEFAULT_CACHE_SECONDS = 60;
+/** Per-request ceiling for a provider call, in milliseconds. */
+export const DEFAULT_TIMEOUT_MS = 10_000;
+/** Seconds the browser half waits between re-reads, unless configured otherwise. */
+export const DEFAULT_REFRESH_SECONDS = 300;
+/** Live report entries one host keeps before it starts evicting. */
+const MAX_REPORTS = 512;
+/** Longest provider route id the route accepts. */
+const MAX_PROVIDER_ID_LENGTH = 128;
+/**
+ * Shape of a provider route id. The harness's built-in routes are lowercase
+ * and hyphenated (`deepseek-official`, `zai-coding-cn`); a profile's own route
+ * keys are user-chosen, so `_`, `.` and capitals are admitted too (the z.ai
+ * probe already recognizes `z_ai`).
+ */
+const PROVIDER_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+/**
+ * Field defaults and bounds with no volatility wrapper. {@link resolveRow}
+ * parses a plain row through this schema, so its output is plain values; the
+ * loader-facing {@link Config} below is the same shape with every field made
+ * `volatile()`. The pair is asserted equal in the suite.
+ */
+const ValueSchema = Schema.object({
+    cacheSeconds: Schema.number().min(0).max(3_600).default(DEFAULT_CACHE_SECONDS),
+    timeoutMs: Schema.number().min(1).max(60_000).default(DEFAULT_TIMEOUT_MS),
+    refreshSeconds: Schema.number().min(10).max(3_600).default(DEFAULT_REFRESH_SECONDS),
+});
+/**
+ * Row schema as Cordis resolves it: what this plugin's `config` is validated
+ * against, and where each default lives. Every value here is a deployment
+ * choice (the cadences and the deadline vary by machine), so none is a
+ * constant only this plugin could change, and all three are editable from the
+ * Plugins page.
+ */
+export const Config = Schema.object({
+    cacheSeconds: Schema.number().min(0).max(3_600).default(DEFAULT_CACHE_SECONDS).volatile(),
+    timeoutMs: Schema.number().min(1).max(60_000).default(DEFAULT_TIMEOUT_MS).volatile(),
+    refreshSeconds: Schema.number().min(10).max(3_600).default(DEFAULT_REFRESH_SECONDS).volatile(),
+});
+/**
+ * Read one configured field as a plain value.
+ *
+ * The loader hands a `volatile()` field a live reference; a direct caller (a
+ * test, another plugin composing this one) hands the value itself. Both are
+ * accepted, so one read path serves both.
+ * @param value - the configured value, live or plain.
+ * @returns the current plain value, or `undefined` when a reference holds none.
+ */
+function readLive(value) {
+    if (value !== null && typeof value === 'object' && typeof value.get === 'function') {
+        // A scalar snapshot is the value; the generic cannot narrow that itself.
+        return value.get();
+    }
+    return value;
+}
+/**
+ * Turn a row (live references or plain values) into validated plain options.
+ * @param row - the configured row.
+ * @returns the resolved options, defaults filled by the schema.
+ */
+export function resolveRow(row = {}) {
+    return ValueSchema({
+        cacheSeconds: readLive(row.cacheSeconds),
+        timeoutMs: readLive(row.timeoutMs),
+        refreshSeconds: readLive(row.refreshSeconds),
+    });
+}
+/**
+ * What a provider route's base URL must start with: an http(s) scheme and a
+ * host. A scheme-less `box:20128` parses as a URL whose origin is "null".
+ */
+const BASE_URL_PATTERN = /^https?:\/\/[^\s/?#]+/iu;
+/** Whether a configured base URL is an absolute http(s) URL. */
+function isHttpUrl(baseURL) {
+    return BASE_URL_PATTERN.test(baseURL) && URL.canParse(baseURL);
+}
+/** Write a JSON reply whose body is already serialized. */
+function sendBody(res, status, body) {
+    res.statusCode = status;
+    res.setHeader('content-type', 'application/json; charset=utf-8');
+    res.setHeader('cache-control', 'no-store');
+    res.end(body);
+}
+/** Write a JSON reply; readings are live facts and are never cached by the browser. */
+function sendJson(res, status, payload) {
+    sendBody(res, status, JSON.stringify(payload));
+}
+/**
+ * Query parameters of a request target.
+ *
+ * Only the query matters here, so only the query is parsed: building a `URL`
+ * for every read pays for an origin the route never looks at.
+ * @param url - request target, path and query.
+ * @returns the decoded parameters.
+ */
+function searchParamsOf(url) {
+    // The fragment is not part of the request target a `URL` would parse either,
+    // and a target whose `#` precedes its `?` must not have the fragment read as
+    // query text.
+    const hash = url.indexOf('#');
+    const target = hash < 0 ? url : url.slice(0, hash);
+    const start = target.indexOf('?');
+    if (start < 0)
+        return new URLSearchParams();
+    return new URLSearchParams(target.slice(start + 1));
+}
+/**
+ * Resolve one provider route's profile: the settings namespace the LLM registry
+ * points at, drilled to the route's own path.
+ * @param ctx - host context.
+ * @param providerId - route id.
+ * @returns the fields this plugin reads, empty when nothing resolves.
+ */
+function providerConfigOf(ctx, providerId) {
+    const llm = ctx.get('llm');
+    let entry;
+    try {
+        entry = llm?.listConfigurableProviders().find(candidate => candidate.provider === providerId);
+    }
+    catch (error) {
+        ctx.logger.warn(`quota-check: could not read the provider directory (${String(error)})`);
+    }
+    if (entry === undefined)
+        return {};
+    const settings = ctx.get('settings');
+    const descriptor = settings?.describe().find(candidate => candidate.ns === entry.settingsNs);
+    let section = descriptor?.value;
+    for (const segment of entry.settingsPath)
+        section = record(section)?.[segment];
+    const fields = record(section) ?? {};
+    return {
+        ...entry.displayName === undefined ? {} : { displayName: entry.displayName },
+        ...typeof fields['baseURL'] === 'string' ? { baseURL: fields['baseURL'] } : {},
+        ...typeof fields['apiKeyEnv'] === 'string' ? { apiKeyEnv: fields['apiKeyEnv'] } : {},
+    };
+}
+/**
+ * Resolve the provider credential: the configured reference first, then the
+ * references the probe itself names.
+ * @param ctx - host context.
+ * @param config - the route's resolved profile.
+ * @param envNames - fallback references the probe names.
+ * @returns the key, or `undefined` when none is configured.
+ */
+async function apiKeyOf(ctx, config, envNames) {
+    const credentials = ctx.get('credentials');
+    for (const ref of [config.apiKeyEnv, ...envNames]) {
+        if (ref === undefined || ref.length === 0)
+            continue;
+        const resolved = await credentials?.resolve(ref);
+        const stored = resolved?.value;
+        if (stored !== undefined && stored.length > 0)
+            return stored;
+        const ambient = process.env[ref];
+        if (ambient !== undefined && ambient.length > 0)
+            return ambient;
+    }
+    return undefined;
+}
+/**
+ * Build one provider's reading.
+ * @param ctx - host context.
+ * @param providerId - route id the browser half asked about.
+ * @param timeoutMs - per-request provider deadline.
+ * @param refreshMs - re-read cadence the browser half is told to use.
+ * @returns the report, never throwing: a failure is an `error` report.
+ */
+async function buildReport(ctx, providerId, timeoutMs, refreshMs) {
+    let displayName = providerId;
+    try {
+        // Resolved per miss, not cached: the miss is network-bound, and a profile
+        // cache would hide a settings edit (baseURL, displayName) for its whole TTL.
+        const config = providerConfigOf(ctx, providerId);
+        displayName = config.displayName ?? providerId;
+        const base = { provider: providerId, displayName, fetchedAt: Date.now(), refreshMs };
+        // The route's baseURL belongs to another plugin's row, so it is checked
+        // here, at first use: no origin is guessed for a malformed one, and no
+        // credential is resolved or sent.
+        if (config.baseURL !== undefined && !isHttpUrl(config.baseURL)) {
+            return {
+                ...base,
+                status: 'error',
+                message: 'this route\'s baseURL is not an absolute http(s) URL; fix the provider row',
+            };
+        }
+        const probe = resolveProbe(providerId, config.baseURL);
+        if (probe === undefined) {
+            return {
+                ...base,
+                status: 'unsupported',
+                message: 'no balance or quota endpoint is known for this provider',
+            };
+        }
+        const envNames = probe.envNames ?? [];
+        const local = probe.local;
+        let requests;
+        if (local === undefined) {
+            const key = await apiKeyOf(ctx, config, envNames);
+            if (key === undefined) {
+                // A missing credential is a broken setup on a route that names its
+                // vendor; on a guessed route it only means the host is not that product.
+                return probe.tentative === true
+                    ? {
+                        ...base,
+                        status: 'unsupported',
+                        message: 'no balance or quota endpoint this plugin recognizes, and no credential to read for it',
+                    }
+                    : {
+                        ...base,
+                        status: 'error',
+                        message: `no credential is configured for this route (${config.apiKeyEnv ?? envNames.join(' / ')})`,
+                    };
+            }
+            if (probe.requests !== undefined) {
+                // The endpoint names ids only the provider knows: read its listing
+                // first, then ask each one it offers.
+                requests = await probe.requests({ key, timeoutMs });
+            }
+            else if (probe.url === undefined) {
+                return { ...base, status: 'error', message: 'this probe declares neither an endpoint nor a listing' };
+            }
+            else {
+                requests = [{ url: probe.url, headers: { authorization: `Bearer ${key}`, accept: 'application/json' } }];
+            }
+            if (requests.length === 0) {
+                return {
+                    ...base,
+                    status: 'error',
+                    message: `${config.baseURL ?? providerId} listed no endpoint to ask`,
+                };
+            }
+        }
+        else {
+            requests = await localRequests(local, { timeoutMs });
+            if (requests.length === 0) {
+                return {
+                    ...base,
+                    status: 'error',
+                    message: `no usable ${local} CLI credential is on this machine`,
+                };
+            }
+        }
+        let outcome = await fetchAll(requests, timeoutMs);
+        // A live-looking token can still be refused: rotate once and retry, which is
+        // what the CLI's own fetcher does. Cursor has no refresh path, so a retry
+        // there would only repeat the same refused request.
+        if (local !== undefined && local !== 'cursor' && !outcome.ok && outcome.refused) {
+            const retried = await localRequests(local, { forceRefresh: true, timeoutMs });
+            if (retried.length > 0)
+                outcome = await fetchAll(retried, timeoutMs);
+        }
+        if (!outcome.ok) {
+            // A 404 on a probe that only guessed the endpoint means the host does not
+            // publish it: absent data, not a reading that failed.
+            if (probe.tentative === true && outcome.status === 404) {
+                return {
+                    ...base,
+                    status: 'unsupported',
+                    message: `${requests[0]?.url ?? providerId} is not on this host`,
+                };
+            }
+            return {
+                ...base,
+                status: 'error',
+                message: `${requests[0]?.url ?? providerId} answered HTTP ${String(outcome.status)}`,
+            };
+        }
+        const reading = probe.parse(outcome.payloads);
+        if (reading === null) {
+            return { ...base, status: 'error', message: 'the provider response carried no balance or quota figure' };
+        }
+        return {
+            ...base,
+            status: 'ok',
+            kind: probe.kind,
+            text: reading.text,
+            ...reading.remaining === undefined ? {} : { remaining: reading.remaining },
+            lines: reading.lines,
+        };
+    }
+    catch (error) {
+        // Another service's exception text (credentials, settings, a parser) may
+        // name host paths or internals, so it stays in the host log.
+        ctx.logger.warn(`quota-check: the ${providerId} reading failed (${String(error)})`);
+        return {
+            provider: providerId,
+            displayName,
+            fetchedAt: Date.now(),
+            refreshMs,
+            status: 'error',
+            message: 'the reading failed; the host log names the cause',
+        };
+    }
+}
+/**
+ * Run every request of one probe in order, tolerating a partial answer: Grok
+ * reports two meters and one of them may be unavailable, so only a round where
+ * nothing answered is a failure.
+ * @param requests - requests built from the provider's credential.
+ * @param timeoutMs - per-request deadline.
+ * @returns the decoded bodies, the last status, and the refusal flag.
+ */
+async function fetchAll(requests, timeoutMs) {
+    const payloads = [];
+    let status = 0;
+    let refused = false;
+    for (const request of requests) {
+        try {
+            const response = await fetch(request.url, {
+                headers: request.headers,
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            status = response.status;
+            if (response.status === 401 || response.status === 403)
+                refused = true;
+            payloads.push(response.ok ? await response.json().catch(() => undefined) : undefined);
+        }
+        catch {
+            payloads.push(undefined);
+        }
+    }
+    return { ok: payloads.some(payload => payload !== undefined), status, refused, payloads };
+}
+/**
+ * Mount the host half.
+ * @param ctx - host context carrying the route carrier.
+ * @param config - this plugin's row configuration.
+ */
+export function apply(ctx, row = {}) {
+    // Read the row at every use: each field is volatile, so a save from the
+    // Plugins card has to reach the next reading rather than a mount-time copy.
+    const live = () => resolveRow(row);
+    live();
+    const cache = new Map();
+    const inflight = new Map();
+    // Bumped by a settings write. A read that started before one belongs to the
+    // old row (its deadline and the `refreshMs` it reports), so it must not fill
+    // the cache the write just emptied.
+    let generation = 0;
+    /**
+     * Keep the report map at its cap: once it holds `MAX_REPORTS`, the oldest key
+     * goes before the next insert. `Map` iterates in insertion order, so the first
+     * key is the one inserted longest ago; an entry whose lifetime has passed is
+     * already a miss on read, so it needs no sweep here.
+     */
+    const pruneReports = () => {
+        if (cache.size < MAX_REPORTS)
+            return;
+        const oldest = cache.keys().next().value;
+        if (oldest !== undefined)
+            cache.delete(oldest);
+    };
+    /**
+     * Serve one provider's serialized reading: the cached body, or a fresh one.
+     *
+     * The body is serialized once, when the reading is taken, so a hit answers
+     * with the bytes written then instead of serializing the same report again on
+     * every poll.
+     */
+    const reportFor = (providerId, refresh) => {
+        const { cacheSeconds, timeoutMs, refreshSeconds } = live();
+        const hit = cache.get(providerId);
+        if (!refresh && hit !== undefined && Date.now() - hit.at < cacheSeconds * 1_000) {
+            return Promise.resolve(hit.body);
+        }
+        const running = inflight.get(providerId);
+        if (running !== undefined)
+            return running;
+        const started = generation;
+        const pending = buildReport(ctx, providerId, timeoutMs, refreshSeconds * 1_000).then((report) => {
+            const body = JSON.stringify(report);
+            // A write that landed mid-read emptied the cache; this body belongs to
+            // the row before it, so it is answered but not kept.
+            if (started === generation) {
+                pruneReports();
+                cache.set(providerId, { at: Date.now(), body });
+            }
+            return body;
+        }).finally(() => {
+            // Only this read's own entry: after a write, a later poll may have
+            // installed its own read under the same key.
+            if (inflight.get(providerId) === pending)
+                inflight.delete(providerId);
+        });
+        inflight.set(providerId, pending);
+        return pending;
+    };
+    const handler = async (req, res) => {
+        const rejection = ctx.connection.requestRejection(req);
+        if (rejection !== undefined) {
+            res.statusCode = rejection;
+            res.end();
+            return;
+        }
+        if ((req.method ?? 'GET').toUpperCase() !== 'GET') {
+            res.setHeader('allow', 'GET');
+            sendJson(res, 405, { status: 'error', message: 'this route answers GET only' });
+            return;
+        }
+        const params = searchParamsOf(String(req.url ?? ROUTE));
+        const providerId = params.get('provider') ?? '';
+        if (providerId.length === 0) {
+            sendJson(res, 400, { status: 'error', message: 'a provider query parameter is required' });
+            return;
+        }
+        // Checked before the id keys the cache or reaches any lookup.
+        if (providerId.length > MAX_PROVIDER_ID_LENGTH || !PROVIDER_ID_PATTERN.test(providerId)) {
+            sendJson(res, 400, {
+                status: 'error',
+                message: `the provider query parameter must be a route id: letters, digits, ".", "_" or "-", at most ${String(MAX_PROVIDER_ID_LENGTH)} characters`,
+            });
+            return;
+        }
+        const body = await reportFor(providerId, params.get('refresh') === '1');
+        sendBody(res, 200, body);
+    };
+    ctx.effect(() => ctx.webServer.register({ kind: 'exact', path: ROUTE, handler }), `quota-check: GET ${ROUTE}`);
+    // A settings write moves the live references in place. Dropping the served
+    // readings makes the next poll show the effect of the edit instead of a body
+    // cached under the previous window, and the log line records what it became.
+    ctx.on('loader/volatile-update', () => {
+        cache.clear();
+        // A poll that starts after the write must read with the new row, so the
+        // reads the old row started stop being handed out. Their callers still get
+        // an answer.
+        inflight.clear();
+        generation += 1;
+        const { cacheSeconds, timeoutMs, refreshSeconds } = live();
+        ctx.logger.warn(`quota-check: configuration updated: ${cacheSeconds}s cache, ${timeoutMs}ms deadline,`
+            + ` ${refreshSeconds}s browser refresh`);
+    });
+}