@toa.io/extensions.exposition 1.0.0-alpha.3 → 1.0.0-alpha.300

package/transpiled/directives/io/lib/throttle/Quotas.d.ts

@@ -0,0 +1,70 @@
+import { Keys } from './Keys.js';
+import type { Batch } from './Sync.js';
+import type { Configuration } from './Configuration.js';
+import type { Parameter } from '../../../../RTD/index.js';
+import type { Input as Context, Output } from '../../../../io.js';
+/**
+ * A quota per key, metered by GCRA, decided in this process and shared with the others.
+ *
+ * The state of a key is one theoretical arrival time: the moment the key would be back
+ * at zero if nothing more arrived. An admitted request pushes it `emission` further out,
+ * time drags it back, and a request is admitted while it stays within `capacity` of now.
+ * So `requests` is what a key may spend at once, and `requests / interval` what it earns
+ * back — no window to burst across the edge of, and no lockout to time out of.
+ *
+ * Deciding needs nothing but the local map, which is what keeps the request path free of
+ * I/O. What the other gateways have spent arrives on {@link Sync}'s tick, as a debt in
+ * milliseconds — a duration, so it carries across processes without their clocks having
+ * to agree, and additive, which is what lets each process report only its own increments.
+ */
+export declare class Quotas {
+    /** How often the debt is worth reconciling with the other gateways, in milliseconds. */
+    readonly period: number;
+    /** Milliseconds of debt an admitted request adds, `interval / requests`. */
+    private readonly emission;
+    /** Debt a key may carry before it is refused, `interval` — a burst of `requests`. */
+    private readonly capacity;
+    private readonly keys;
+    private readonly prefix;
+    private readonly conditional;
+    private readonly entries;
+    /**
+     * The key computed at precall, for settle to charge against.
+     *
+     * `segment` reads the route parameters, which settle is not given, and `identity`
+     * can be refreshed between the two — so recomputing there would key a request
+     * differently than it was checked, and throttling would quietly stop working.
+     */
+    private readonly keyed;
+    constructor(options: Options);
+    static create(configuration: Configuration, route?: string): Quotas;
+    /**
+     * Seconds to wait before the request would be admitted, or zero when it is.
+     *
+     * Charges here when nothing conditions the count, so that the request is metered by
+     * the same call that admits it; otherwise only the response can tell whether it counts,
+     * and {@link use} charges once it can.
+     */
+    check(context: Context, parameters: Parameter[]): number;
+    /** Charges what the condition accepts, once the response can be matched against it. */
+    use(input: Context, output: Output): void;
+    /**
+     * Adds what is worth reporting to the batch, and drops what has gone quiet.
+     *
+     * The debt is not cleared here but in {@link settled}, so a tick that fails to reach
+     * Redis leaves it to be reported by the next one instead of losing it.
+     */
+    flush(now: number, batch: Batch[]): void;
+    /** Takes the group's debt back, and clears what this process contributed to it. */
+    settled(reported: Batch, debt: number, now: number): void;
+    name(key: string): string;
+    private charge;
+}
+export interface Options {
+    keys: Keys;
+    requests: number;
+    interval: number;
+    conditional: boolean;
+    /** what the keys are reported under, in place of the budget they carry */
+    name?: string;
+}

package/transpiled/directives/io/lib/throttle/Quotas.js

@@ -0,0 +1,142 @@
+import { Keys } from './Keys.js';
+/**
+ * A quota per key, metered by GCRA, decided in this process and shared with the others.
+ *
+ * The state of a key is one theoretical arrival time: the moment the key would be back
+ * at zero if nothing more arrived. An admitted request pushes it `emission` further out,
+ * time drags it back, and a request is admitted while it stays within `capacity` of now.
+ * So `requests` is what a key may spend at once, and `requests / interval` what it earns
+ * back — no window to burst across the edge of, and no lockout to time out of.
+ *
+ * Deciding needs nothing but the local map, which is what keeps the request path free of
+ * I/O. What the other gateways have spent arrives on {@link Sync}'s tick, as a debt in
+ * milliseconds — a duration, so it carries across processes without their clocks having
+ * to agree, and additive, which is what lets each process report only its own increments.
+ */
+export class Quotas {
+    /** How often the debt is worth reconciling with the other gateways, in milliseconds. */
+    period;
+    /** Milliseconds of debt an admitted request adds, `interval / requests`. */
+    emission;
+    /** Debt a key may carry before it is refused, `interval` — a burst of `requests`. */
+    capacity;
+    keys;
+    prefix;
+    conditional;
+    entries = new Map();
+    /**
+     * The key computed at precall, for settle to charge against.
+     *
+     * `segment` reads the route parameters, which settle is not given, and `identity`
+     * can be refreshed between the two — so recomputing there would key a request
+     * differently than it was checked, and throttling would quietly stop working.
+     */
+    keyed = new WeakMap();
+    constructor(options) {
+        this.keys = options.keys;
+        this.conditional = options.conditional;
+        this.emission = options.interval / options.requests;
+        this.capacity = options.interval;
+        this.period = period(options.interval);
+        // a key means one budget, so quotas that do not share one must not share a key
+        this.prefix =
+            options.name === undefined
+                ? `t:${options.requests}:${options.interval}:`
+                : `${options.name}:`;
+    }
+    static create(configuration, route = '') {
+        const { requests, interval, condition } = configuration;
+        const keys = Keys.create(configuration.key, condition, route);
+        return new this({ keys, requests, interval, conditional: condition !== undefined });
+    }
+    /**
+     * Seconds to wait before the request would be admitted, or zero when it is.
+     *
+     * Charges here when nothing conditions the count, so that the request is metered by
+     * the same call that admits it; otherwise only the response can tell whether it counts,
+     * and {@link use} charges once it can.
+     */
+    check(context, parameters) {
+        const key = this.keys.get(context, parameters);
+        // a request that cannot be keyed is not metered
+        if (key === undefined)
+            return 0;
+        this.keyed.set(context, key);
+        const now = Date.now();
+        const entry = this.entries.get(key);
+        const tat = Math.max(entry?.tat ?? now, now);
+        const admit = tat + this.emission - this.capacity;
+        if (admit > now)
+            return Math.ceil((admit - now) / 1000);
+        if (!this.conditional)
+            this.charge(key, entry, tat);
+        return 0;
+    }
+    /** Charges what the condition accepts, once the response can be matched against it. */
+    use(input, output) {
+        if (!this.conditional || !this.keys.matches(input, output))
+            return;
+        // precall always runs first, and a request it refuses never reaches settle
+        const key = this.keyed.get(input) ?? this.keys.get(input);
+        if (key === undefined)
+            return;
+        const now = Date.now();
+        const entry = this.entries.get(key);
+        const tat = Math.max(entry?.tat ?? now, now);
+        this.charge(key, entry, tat);
+    }
+    /**
+     * Adds what is worth reporting to the batch, and drops what has gone quiet.
+     *
+     * The debt is not cleared here but in {@link settled}, so a tick that fails to reach
+     * Redis leaves it to be reported by the next one instead of losing it.
+     */
+    flush(now, batch) {
+        for (const [key, entry] of this.entries) {
+            const delta = Math.round(entry.debt);
+            if (delta > 0) {
+                batch.push({ quotas: this, key, delta });
+                continue;
+            }
+            // out of debt and with nothing left to report, a key says no more than an absent one
+            if (entry.tat <= now)
+                this.entries.delete(key);
+        }
+    }
+    /** Takes the group's debt back, and clears what this process contributed to it. */
+    settled(reported, debt, now) {
+        const entry = this.entries.get(reported.key);
+        if (entry === undefined) {
+            if (debt > 0)
+                this.entries.set(reported.key, { tat: now + debt, debt: 0 });
+            return;
+        }
+        entry.debt -= reported.delta;
+        // the group has spent at least what this process has, so its debt is the one to keep
+        entry.tat = Math.max(entry.tat, now + debt);
+    }
+    name(key) {
+        return this.prefix + key;
+    }
+    charge(key, entry, tat) {
+        if (entry === undefined)
+            this.entries.set(key, { tat: tat + this.emission, debt: this.emission });
+        else {
+            entry.tat = tat + this.emission;
+            entry.debt += this.emission;
+        }
+    }
+}
+/**
+ * How often to reconcile, in milliseconds.
+ *
+ * Reconciling is what bounds the overshoot — between two ticks a gateway is going on
+ * what it alone has spent — so it is worth doing an order of magnitude more often than
+ * the interval, within reason on either end.
+ */
+function period(interval) {
+    return Math.min(Math.max(interval / 10, MIN_PERIOD), MAX_PERIOD);
+}
+const MIN_PERIOD = 250;
+const MAX_PERIOD = 2000;
+//# sourceMappingURL=Quotas.js.map

package/transpiled/directives/io/lib/throttle/Quotas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Quotas.js","sourceRoot":"","sources":["../../../../../source/directives/io/lib/throttle/Quotas.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAMhC;;;;;;;;;;;;;GAaG;AACH,MAAM,OAAO,MAAM;IACjB,wFAAwF;IACxE,MAAM,CAAQ;IAE9B,4EAA4E;IAC3D,QAAQ,CAAQ;IAEjC,qFAAqF;IACpE,QAAQ,CAAQ;IAEhB,IAAI,CAAM;IACV,MAAM,CAAQ;IACd,WAAW,CAAS;IACpB,OAAO,GAAG,IAAI,GAAG,EAAiB,CAAA;IAEnD;;;;;;OAMG;IACc,KAAK,GAAG,IAAI,OAAO,EAAmB,CAAA;IAEvD,YAAmB,OAAgB;QACjC,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAA;QACxB,IAAI,CAAC,WAAW,GAAG,OAAO,CAAC,WAAW,CAAA;QACtC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAA;QACnD,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAA;QAChC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;QAEtC,+EAA+E;QAC/E,IAAI,CAAC,MAAM;YACT,OAAO,CAAC,IAAI,KAAK,SAAS;gBACxB,CAAC,CAAC,KAAK,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ,GAAG;gBAC9C,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,GAAG,CAAA;IAC1B,CAAC;IAEM,MAAM,CAAC,MAAM,CAAC,aAA4B,EAAE,KAAK,GAAW,EAAE;QACnE,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,aAAa,CAAA;QACvD,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,CAAA;QAE7D,OAAO,IAAI,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,WAAW,EAAE,SAAS,KAAK,SAAS,EAAE,CAAC,CAAA;IACrF,CAAC;IAED;;;;;;OAMG;IACI,KAAK,CAAC,OAAgB,EAAE,UAAuB;QACpD,MAAM,GAAG,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,EAAE,UAAU,CAAC,CAAA;QAE9C,gDAAgD;QAChD,IAAI,GAAG,KAAK,SAAS;YAAE,OAAO,CAAC,CAAA;QAE/B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,OAAO,EAAE,GAAG,CAAC,CAAA;QAE5B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,IAAI,GAAG,EAAE,GAAG,CAAC,CAAA;QAC5C,MAAM,KAAK,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAA;QAEjD,IAAI,KAAK,GAAG,GAAG;YAAE,OAAO,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,IAAI,CAAC,CAAA;QAEvD,IAAI,CAAC,IAAI,CAAC,WAAW;YAAE,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,CAAA;QAEnD,OAAO,CAAC,CAAA;IACV,CAAC;IAED,uFAAuF;IAChF,GAAG,CAAC,KAAc,EAAE,MAAc;QACvC,IAAI,CAAC,IAAI,CAAC,WAAW,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,MAAM,CAAC;YAAE,OAAM;QAElE,2EAA2E;QAC3E,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;QAEzD,IAAI,GAAG,KAAK,SAAS;YAAE,OAAM;QAE7B,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;QACnC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG,IAAI,GAAG,EAAE,GAAG,CAAC,CAAA;QAE5C,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,EAAE,GAAG,CAAC,CAAA;IAC9B,CAAC;IAED;;;;;OAKG;IACI,KAAK,CAAC,GAAW,EAAE,KAAc;QACtC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACxC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;YAEpC,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;gBACd,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAA;gBAExC,SAAQ;YACV,CAAC;YAED,qFAAqF;YACrF,IAAI,KAAK,CAAC,GAAG,IAAI,GAAG;gBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA;QAChD,CAAC;IACH,CAAC;IAED,mFAAmF;IAC5E,OAAO,CAAC,QAAe,EAAE,IAAY,EAAE,GAAW;QACvD,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAA;QAE5C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,IAAI,IAAI,GAAG,CAAC;gBAAE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,GAAG,GAAG,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAA;YAE1E,OAAM;QACR,CAAC;QAED,KAAK,CAAC,IAAI,IAAI,QAAQ,CAAC,KAAK,CAAA;QAE5B,qFAAqF;QACrF,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC,CAAA;IAC7C,CAAC;IAEM,IAAI,CAAC,GAAW;QACrB,OAAO,IAAI,CAAC,MAAM,GAAG,GAAG,CAAA;IAC1B,CAAC;IAEO,MAAM,CAAC,GAAW,EAAE,KAAwB,EAAE,GAAW;QAC/D,IAAI,KAAK,KAAK,SAAS;YACrB,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,GAAG,GAAG,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAA;aACrE,CAAC;YACJ,KAAK,CAAC,GAAG,GAAG,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAA;YAC/B,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAA;QAC7B,CAAC;IACH,CAAC;CACF;AAED;;;;;;GAMG;AACH,SAAS,MAAM,CAAC,QAAgB;IAC9B,OAAO,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,GAAG,EAAE,EAAE,UAAU,CAAC,EAAE,UAAU,CAAC,CAAA;AAClE,CAAC;AAED,MAAM,UAAU,GAAG,GAAG,CAAA;AACtB,MAAM,UAAU,GAAG,IAAI,CAAA"}

package/transpiled/directives/io/lib/throttle/Sync.d.ts

@@ -0,0 +1,29 @@
+import type { Quotas } from './Quotas.js';
+import type { atomicity } from '@toa.io/core/types';
+/**
+ * Reconciles every quota of the process with the other gateways, on one tick.
+ *
+ * Nothing here is on the request path. Each tick takes what the quotas have spent since
+ * the last one and sends all of it as a single call, so the cost of staying in step is
+ * one round trip a tick — not one per key, and not one per directive. What comes back is
+ * the debt the whole group has reached, which the quotas then decide on locally.
+ */
+export declare class Sync {
+    private readonly atom;
+    private readonly quotas;
+    private timer;
+    private period;
+    /** Ticks do not overlap: a slow round trip delays reconciling, it does not double it. */
+    private reconciling;
+    constructor(atom: atomicity.Atom);
+    register(quotas: Quotas): void;
+    dispose(): void;
+    private start;
+    private readonly tick;
+    private reconcile;
+}
+export interface Batch {
+    quotas: Quotas;
+    key: string;
+    delta: number;
+}

package/transpiled/directives/io/lib/throttle/Sync.js

@@ -0,0 +1,70 @@
+import { console } from 'openspan';
+/**
+ * Reconciles every quota of the process with the other gateways, on one tick.
+ *
+ * Nothing here is on the request path. Each tick takes what the quotas have spent since
+ * the last one and sends all of it as a single call, so the cost of staying in step is
+ * one round trip a tick — not one per key, and not one per directive. What comes back is
+ * the debt the whole group has reached, which the quotas then decide on locally.
+ */
+export class Sync {
+    atom;
+    quotas = [];
+    timer = null;
+    period = Infinity;
+    /** Ticks do not overlap: a slow round trip delays reconciling, it does not double it. */
+    reconciling = false;
+    constructor(atom) {
+        this.atom = atom;
+    }
+    register(quotas) {
+        this.quotas.push(quotas);
+        // the shortest interval sets the pace, and reconciling the others more often than
+        // they asked for only makes them more accurate — an idle quota contributes nothing
+        if (quotas.period < this.period) {
+            this.period = quotas.period;
+            this.start();
+        }
+    }
+    dispose() {
+        if (this.timer !== null) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    start() {
+        this.dispose();
+        this.timer = setInterval(this.tick, this.period);
+        this.timer.unref();
+    }
+    tick = () => {
+        if (this.reconciling)
+            return;
+        const now = Date.now();
+        const batch = [];
+        for (const quotas of this.quotas)
+            quotas.flush(now, batch);
+        if (batch.length === 0)
+            return;
+        this.reconciling = true;
+        void this.reconcile(batch).finally(() => {
+            this.reconciling = false;
+        });
+    };
+    async reconcile(batch) {
+        try {
+            const keys = batch.map((entry) => entry.quotas.name(entry.key));
+            const deltas = batch.map((entry) => entry.delta);
+            const debts = await this.atom.meter(keys, deltas);
+            const now = Date.now();
+            for (let i = 0; i < batch.length; i++)
+                batch[i].quotas.settled(batch[i], debts[i], now);
+        }
+        catch (error) {
+            // what was not reported stays to be reported by the next tick, and until then
+            // this gateway keeps throttling on what it alone has seen, and keeps serving
+            console.warn('Throttling could not reconcile with the group', error);
+        }
+    }
+}
+//# sourceMappingURL=Sync.js.map

package/transpiled/directives/io/lib/throttle/Sync.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sync.js","sourceRoot":"","sources":["../../../../../source/directives/io/lib/throttle/Sync.ts"],"names":[],"mappings":"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"}

package/transpiled/directives/io/lib/throttle/Warning.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A warning about a condition that holds for request after request, written once per
+ * `interval` rather than once per request.
+ */
+export declare class Warning {
+    private readonly message;
+    private readonly interval;
+    private last;
+    constructor(message: string, interval?: number);
+    emit(attributes?: Record<string, unknown>): void;
+}

package/transpiled/directives/io/lib/throttle/Warning.js

@@ -0,0 +1,24 @@
+import { console } from 'openspan';
+/**
+ * A warning about a condition that holds for request after request, written once per
+ * `interval` rather than once per request.
+ */
+export class Warning {
+    message;
+    interval;
+    last = -Infinity;
+    constructor(message, interval = INTERVAL) {
+        this.message = message;
+        this.interval = interval;
+    }
+    emit(attributes) {
+        const now = Date.now();
+        if (now - this.last < this.interval)
+            return;
+        this.last = now;
+        console.warn(this.message, attributes);
+    }
+}
+/** 100 seconds */
+const INTERVAL = 100_000;
+//# sourceMappingURL=Warning.js.map

package/transpiled/directives/io/lib/throttle/Warning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Warning.js","sourceRoot":"","sources":["../../../../../source/directives/io/lib/throttle/Warning.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAA;AAElC;;;GAGG;AACH,MAAM,OAAO,OAAO;IACD,OAAO,CAAQ;IACf,QAAQ,CAAQ;IACzB,IAAI,GAAG,CAAC,QAAQ,CAAA;IAExB,YAAmB,OAAe,EAAE,QAAQ,GAAW,QAAQ;QAC7D,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;QACtB,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAC1B,CAAC;IAEM,IAAI,CAAC,UAAoC;QAC9C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QAEtB,IAAI,GAAG,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,QAAQ;YAAE,OAAM;QAE3C,IAAI,CAAC,IAAI,GAAG,GAAG,CAAA;QAEf,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAA;IACxC,CAAC;CACF;AAED,kBAAkB;AAClB,MAAM,QAAQ,GAAG,OAAO,CAAA"}

package/transpiled/directives/io/lib/throttle/components/Component.d.ts

@@ -0,0 +1,6 @@
+import type { Parameter } from '../../../../../RTD/index.js';
+import type { Input as Context } from '../../../../../io.js';
+export interface Component {
+    /** what to key on, or nothing when the request cannot be keyed by this component */
+    get: (context: Context, parameters: Parameter[]) => string | undefined;
+}

package/transpiled/directives/io/lib/throttle/components/Component.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Component.js.map

package/transpiled/directives/io/lib/throttle/components/Component.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Component.js","sourceRoot":"","sources":["../../../../../../source/directives/io/lib/throttle/components/Component.ts"],"names":[],"mappings":""}

package/transpiled/directives/io/lib/throttle/components/IP.d.ts

@@ -0,0 +1,14 @@
+import type { Context } from '../../../../../HTTP/index.js';
+import type { Component } from './Component.js';
+/**
+ * The client address, as the request context resolved it; see `documentation/ip.md`.
+ *
+ * A request without one cannot be keyed, so it is let through, and whoever keys on the
+ * address says so — once in a while rather than on every request, because the cause is
+ * the deployment, not the request.
+ */
+export declare class IP implements Component {
+    private readonly warning;
+    constructor(options: unknown, route: string);
+    get(context: Context): string | undefined;
+}

package/transpiled/directives/io/lib/throttle/components/IP.js

@@ -0,0 +1,24 @@
+import { Warning } from '../Warning.js';
+/**
+ * The client address, as the request context resolved it; see `documentation/ip.md`.
+ *
+ * A request without one cannot be keyed, so it is let through, and whoever keys on the
+ * address says so — once in a while rather than on every request, because the cause is
+ * the deployment, not the request.
+ */
+export class IP {
+    warning;
+    constructor(options, route) {
+        const subject = typeof options === 'string' ? options : throttle(route);
+        this.warning = new Warning(`${subject} is not in effect: the request has no ip`);
+    }
+    get(context) {
+        if (context.ip === undefined)
+            this.warning.emit();
+        return context.ip;
+    }
+}
+function throttle(route) {
+    return route === '' ? 'Throttle' : `Throttle of ${route}`;
+}
+//# sourceMappingURL=IP.js.map

package/transpiled/directives/io/lib/throttle/components/IP.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"IP.js","sourceRoot":"","sources":["../../../../../../source/directives/io/lib/throttle/components/IP.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAIvC;;;;;;GAMG;AACH,MAAM,OAAO,EAAE;IACI,OAAO,CAAS;IAEjC,YAAmB,OAAgB,EAAE,KAAa;QAChD,MAAM,OAAO,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAA;QAEvE,IAAI,CAAC,OAAO,GAAG,IAAI,OAAO,CAAC,GAAG,OAAO,0CAA0C,CAAC,CAAA;IAClF,CAAC;IAEM,GAAG,CAAC,OAAgB;QACzB,IAAI,OAAO,CAAC,EAAE,KAAK,SAAS;YAAE,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAA;QAEjD,OAAO,OAAO,CAAC,EAAE,CAAA;IACnB,CAAC;CACF;AAED,SAAS,QAAQ,CAAC,KAAa;IAC7B,OAAO,KAAK,KAAK,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,eAAe,KAAK,EAAE,CAAA;AAC3D,CAAC"}

package/transpiled/directives/io/lib/throttle/components/Identity.d.ts

@@ -0,0 +1,11 @@
+import type { Input } from '../../../../../io.js';
+import type { Component } from './Component.js';
+/**
+ * The authenticated identity, or nothing when the request carries none.
+ *
+ * Anonymous requests therefore share one quota between them; `ip` is the component
+ * that tells them apart.
+ */
+export declare class Identity implements Component {
+    get(context: Input): string;
+}

package/transpiled/directives/io/lib/throttle/components/Identity.js

@@ -0,0 +1,12 @@
+/**
+ * The authenticated identity, or nothing when the request carries none.
+ *
+ * Anonymous requests therefore share one quota between them; `ip` is the component
+ * that tells them apart.
+ */
+export class Identity {
+    get(context) {
+        return context.identity?.id ?? '';
+    }
+}
+//# sourceMappingURL=Identity.js.map

package/transpiled/directives/io/lib/throttle/components/Identity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Identity.js","sourceRoot":"","sources":["../../../../../../source/directives/io/lib/throttle/components/Identity.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,OAAO,QAAQ;IACZ,GAAG,CAAC,OAAc;QACvB,OAAQ,OAAgC,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,CAAA;IAC7D,CAAC;CACF"}

package/transpiled/directives/io/lib/throttle/components/Path.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from '../../../../../HTTP/index.js';
+import type { Component } from './Component.js';
+export declare class Path implements Component {
+    get(context: Context): string;
+}

package/transpiled/directives/io/lib/throttle/components/Path.js

@@ -0,0 +1,6 @@
+export class Path {
+    get(context) {
+        return context.url.pathname;
+    }
+}
+//# sourceMappingURL=Path.js.map

package/transpiled/directives/io/lib/throttle/components/Path.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Path.js","sourceRoot":"","sources":["../../../../../../source/directives/io/lib/throttle/components/Path.ts"],"names":[],"mappings":"AAGA,MAAM,OAAO,IAAI;IACR,GAAG,CAAC,OAAgB;QACzB,OAAO,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAA;IAC7B,CAAC;CACF"}

package/transpiled/directives/io/lib/throttle/components/Route.d.ts

@@ -0,0 +1,12 @@
+import type { Component } from './Component.js';
+/**
+ * The route as declared — `/users/:id` — rather than the path a request came in on.
+ *
+ * A constant per method, resolved when the tree is built, so every request to one
+ * route shares a quota however many concrete paths match it.
+ */
+export declare class Route implements Component {
+    private readonly route;
+    constructor(_: unknown, route: string);
+    get(): string;
+}

package/transpiled/directives/io/lib/throttle/components/Route.js

@@ -0,0 +1,16 @@
+/**
+ * The route as declared — `/users/:id` — rather than the path a request came in on.
+ *
+ * A constant per method, resolved when the tree is built, so every request to one
+ * route shares a quota however many concrete paths match it.
+ */
+export class Route {
+    route;
+    constructor(_, route) {
+        this.route = route;
+    }
+    get() {
+        return this.route;
+    }
+}
+//# sourceMappingURL=Route.js.map

package/transpiled/directives/io/lib/throttle/components/Route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Route.js","sourceRoot":"","sources":["../../../../../../source/directives/io/lib/throttle/components/Route.ts"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,MAAM,OAAO,KAAK;IACC,KAAK,CAAQ;IAE9B,YAAmB,CAAU,EAAE,KAAa;QAC1C,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;IACpB,CAAC;IAEM,GAAG;QACR,OAAO,IAAI,CAAC,KAAK,CAAA;IACnB,CAAC;CACF"}

package/transpiled/directives/io/lib/throttle/components/Segment.d.ts

@@ -0,0 +1,9 @@
+import type { Parameter } from '../../../../../RTD/index.js';
+import type { Input as Context } from '../../../../../io.js';
+import type { Component } from './Component.js';
+/** The value a named route segment was bound to, or nothing when the route has none. */
+export declare class Segment implements Component {
+    private readonly name;
+    constructor(name: unknown);
+    get(_: Context, parameters: Parameter[]): string;
+}

package/transpiled/directives/io/lib/throttle/components/Segment.js

@@ -0,0 +1,13 @@
+/** The value a named route segment was bound to, or nothing when the route has none. */
+export class Segment {
+    name;
+    constructor(name) {
+        if (typeof name !== 'string')
+            throw new Error('Throttle segment must be a string');
+        this.name = name;
+    }
+    get(_, parameters) {
+        return parameters.find(({ name }) => name === this.name)?.value ?? '';
+    }
+}
+//# sourceMappingURL=Segment.js.map

package/transpiled/directives/io/lib/throttle/components/Segment.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Segment.js","sourceRoot":"","sources":["../../../../../../source/directives/io/lib/throttle/components/Segment.ts"],"names":[],"mappings":"AAIA,wFAAwF;AACxF,MAAM,OAAO,OAAO;IACD,IAAI,CAAQ;IAE7B,YAAmB,IAAa;QAC9B,IAAI,OAAO,IAAI,KAAK,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAA;QAElF,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;IAEM,GAAG,CAAC,CAAU,EAAE,UAAuB;QAC5C,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,KAAK,IAAI,CAAC,IAAI,CAAC,EAAE,KAAK,IAAI,EAAE,CAAA;IACvE,CAAC;CACF"}

package/transpiled/directives/io/lib/throttle/components/index.d.ts

@@ -0,0 +1,5 @@
+import type { KeyComponentMethod } from '../Configuration.js';
+import type { Component } from './Component.js';
+type Constructor<T> = new (options: unknown, route: string) => T;
+export declare const Components: Record<KeyComponentMethod, Constructor<Component>>;
+export type { Component };

package/transpiled/directives/io/lib/throttle/components/index.js

@@ -0,0 +1,13 @@
+import { Path } from './Path.js';
+import { IP } from './IP.js';
+import { Route } from './Route.js';
+import { Identity } from './Identity.js';
+import { Segment } from './Segment.js';
+export const Components = {
+    ip: IP,
+    path: Path,
+    route: Route,
+    identity: Identity,
+    segment: Segment
+};
+//# sourceMappingURL=index.js.map

package/transpiled/directives/io/lib/throttle/components/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../source/directives/io/lib/throttle/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAChC,OAAO,EAAE,EAAE,EAAE,MAAM,SAAS,CAAA;AAC5B,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAClC,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AACxC,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AAMtC,MAAM,CAAC,MAAM,UAAU,GAAuD;IAC5E,EAAE,EAAE,EAAE;IACN,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,KAAK;IACZ,QAAQ,EAAE,QAAQ;IAClB,OAAO,EAAE,OAAO;CACjB,CAAA"}

package/transpiled/directives/io/lib/throttle/conditions/Condition.d.ts

@@ -0,0 +1,4 @@
+import type { Input, Output } from '../../../../../io.js';
+export interface Condition {
+    match: (input: Input, output: Output) => boolean;
+}

package/transpiled/directives/io/lib/throttle/conditions/Condition.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=Condition.js.map

package/transpiled/directives/io/lib/throttle/conditions/Condition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Condition.js","sourceRoot":"","sources":["../../../../../../source/directives/io/lib/throttle/conditions/Condition.ts"],"names":[],"mappings":""}

package/transpiled/directives/io/lib/throttle/conditions/Status.d.ts

@@ -0,0 +1,7 @@
+import type { Input, Output } from '../../../../../io.js';
+import type { Condition } from './Condition.js';
+export declare class Status implements Condition {
+    private readonly status;
+    constructor(status: unknown);
+    match(input: Input, output: Output): boolean;
+}

package/transpiled/directives/io/lib/throttle/conditions/Status.js

@@ -0,0 +1,12 @@
+export class Status {
+    status;
+    constructor(status) {
+        if (typeof status !== 'number')
+            throw new Error('Status must be a number');
+        this.status = status;
+    }
+    match(input, output) {
+        return output?.status === this.status;
+    }
+}
+//# sourceMappingURL=Status.js.map

package/transpiled/directives/io/lib/throttle/conditions/Status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Status.js","sourceRoot":"","sources":["../../../../../../source/directives/io/lib/throttle/conditions/Status.ts"],"names":[],"mappings":"AAGA,MAAM,OAAO,MAAM;IACA,MAAM,CAAQ;IAE/B,YAAmB,MAAe;QAChC,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAA;QAE1E,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;IAEM,KAAK,CAAC,KAAY,EAAE,MAAc;QACvC,OAAO,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC,MAAM,CAAA;IACvC,CAAC;CACF"}

package/transpiled/directives/io/lib/throttle/conditions/index.d.ts

@@ -0,0 +1,5 @@
+import type { KeyConditionMethod } from '../Configuration.js';
+import type { Condition } from './Condition.js';
+type Constructor<T> = new (options: unknown) => T;
+export declare const Conditions: Record<KeyConditionMethod, Constructor<Condition>>;
+export type { Condition };

package/transpiled/directives/io/lib/throttle/conditions/index.js

@@ -0,0 +1,5 @@
+import { Status } from './Status.js';
+export const Conditions = {
+    status: Status
+};
+//# sourceMappingURL=index.js.map

package/transpiled/directives/io/lib/throttle/conditions/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../../source/directives/io/lib/throttle/conditions/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AAMpC,MAAM,CAAC,MAAM,UAAU,GAAuD;IAC5E,MAAM,EAAE,MAAM;CACf,CAAA"}

package/transpiled/directives/io/lib/throttle/index.d.ts

@@ -0,0 +1,4 @@
+export { Quotas } from './Quotas.js';
+export { Sync } from './Sync.js';
+export { Warning } from './Warning.js';
+export { parse, type Configuration, type Declaration } from './Configuration.js';