tapimo 0.0.0 → 0.0.2

package/dist/internal/EdgeCache.js

@@ -0,0 +1,174 @@
+import { Base64 } from 'ox';
+// Per-request headers that must never be persisted in a shared cache entry.
+// `age`/`cf-cache-status` are CDN telemetry stamped by Cloudflare on Cache API
+// hits (e.g. the inner `Cache.response` layer); storing them would freeze a
+// stale `Age` into every copy served from this cache.
+const volatileHeaders = [
+    'age',
+    'cf-cache-status',
+    'content-encoding',
+    'content-length',
+    'server-timing',
+    'set-cookie',
+    'ratelimit-limit',
+    'ratelimit-remaining',
+    'ratelimit-reset',
+    'tempo-request-id',
+];
+/**
+ * Serves GET responses from the edge cache store BEFORE auth and rate-limiting
+ * run, so cache hits skip the per-request store round-trips that dominate
+ * latency — for every caller, authenticated or not. Place this ahead of the
+ * auth middleware.
+ *
+ * Only 2xx responses from routes that opted into caching (via `Cache.response`,
+ * which publishes the `edgeCache` policy) are stored, and the policy is only
+ * published for routes whose responses are public and URL-keyed (no per-principal
+ * data), so a single shared entry is safe to serve to all callers. The trade-off
+ * is that cache hits bypass origin metering: they are not counted against
+ * rate-limit quotas.
+ *
+ * The cache is a plain `Store.Store` — the same store the origin read cache uses
+ * — holding the response serialized to a string under a URL key. It is a no-op
+ * when no store is supplied.
+ *
+ * Standard request `Cache-Control` directives let a caller invalidate without an
+ * out-of-band purge: `no-cache` forces a refresh (skip the stored hit, re-fetch,
+ * overwrite the entry) and `no-store` bypasses the cache entirely. Both fall
+ * through to the origin and are metered normally. The store is colo-local, so a
+ * refresh only affects the data center serving that request.
+ */
+export function middleware(options = {}) {
+    return async (c, next) => {
+        const { store } = options;
+        const eligible = store !== undefined && c.req.method === 'GET' && !c.req.raw.headers.has('range');
+        const key = eligible ? cacheKey(c.req.url) : undefined;
+        // Honor the standard request `Cache-Control` directives so a caller can
+        // refresh a stale entry on the colo serving them without any out-of-band
+        // purge: `no-cache` skips the stored hit but still re-stores the fresh
+        // response (revalidate), and `no-store` bypasses the cache on both sides.
+        // `Pragma: no-cache` is the HTTP/1.0 fallback, honored only when
+        // `Cache-Control` is absent (RFC 9111 §5.4). A forced miss falls through
+        // to `next()` and is metered like any other origin request, so this is
+        // not an unmetered-access vector.
+        const directives = (c.req.header('cache-control') ?? c.req.header('pragma') ?? '').toLowerCase();
+        const noStore = directives.includes('no-store');
+        const noCache = noStore || directives.includes('no-cache');
+        if (store && key && !noCache) {
+            const hit = await store.get(key);
+            if (hit) {
+                // Mark the hit for the canonical request log line; routing never runs
+                // for hits, so this is the only signal that the cache answered.
+                c.set('edgeCacheStatus', 'hit');
+                return serveHit(c.req.header('if-none-match'), hit);
+            }
+        }
+        await next();
+        if (!store || !key || noStore)
+            return;
+        const policy = c.get('edgeCache');
+        if (!policy)
+            return;
+        if (c.res.status < 200 || c.res.status >= 300)
+            return;
+        if (c.res.headers.has('set-cookie'))
+            return;
+        if (c.res.headers.get('content-type')?.includes('text/event-stream'))
+            return;
+        // Store a public, sanitized copy; the client still receives the original
+        // (private, metered) response for this miss.
+        const value = await serialize(c.res, policy);
+        const put = store.put(key, value, { ttl: policy.maxAge * 1_000 });
+        const waitUntil = getWaitUntil(c);
+        if (waitUntil)
+            waitUntil(put);
+        else
+            await put.catch(() => { });
+        return;
+    };
+}
+async function serialize(response, policy) {
+    const headers = new Headers(response.headers);
+    for (const name of volatileHeaders)
+        headers.delete(name);
+    headers.set('Cache-Control', cacheControl(policy));
+    headers.set('Vary', 'Accept-Encoding');
+    // The store is text-only, so binary bodies (e.g. PNG token logos) must be
+    // base64-encoded or the round trip through `.text()` corrupts them. Text
+    // bodies (JSON, SVG, HTML) stay verbatim to avoid the 33% base64 overhead.
+    const textual = isTextual(headers.get('content-type'));
+    const stored = {
+        body: textual
+            ? await response.clone().text()
+            : Base64.fromBytes(new Uint8Array(await response.clone().arrayBuffer())),
+        ...(textual ? {} : { encoding: 'base64' }),
+        headers: [...headers],
+        status: response.status,
+    };
+    return JSON.stringify(stored);
+}
+function serveHit(ifNoneMatch, value) {
+    const { body, encoding, headers, status } = JSON.parse(value);
+    const responseHeaders = new Headers(headers);
+    const etag = responseHeaders.get('etag');
+    if (etag && ifNoneMatch && etagMatches(etag, ifNoneMatch)) {
+        const notModified = new Headers();
+        for (const name of ['Cache-Control', 'ETag', 'Vary']) {
+            const header = responseHeaders.get(name);
+            if (header)
+                notModified.set(name, header);
+        }
+        return new Response(null, { headers: notModified, status: 304, statusText: 'Not Modified' });
+    }
+    if (encoding === 'base64') {
+        // Copy the decoded bytes into an exact `ArrayBuffer`: `Base64.toBytes`
+        // returns a `Uint8Array` view, which this TS lib does not accept as a
+        // `BodyInit`.
+        const bytes = Base64.toBytes(body);
+        const buffer = new ArrayBuffer(bytes.byteLength);
+        new Uint8Array(buffer).set(bytes);
+        return new Response(buffer, { headers: responseHeaders, status });
+    }
+    return new Response(body, { headers: responseHeaders, status });
+}
+// A body is safe to store as verbatim text when its content type is textual;
+// everything else (images, octet-stream) is treated as binary and base64-coded.
+function isTextual(contentType) {
+    if (!contentType)
+        return false;
+    return /^(?:text\/|application\/(?:json|xml|javascript|[\w.-]+\+(?:json|xml))|image\/svg\+xml)/i.test(contentType);
+}
+// Sort query params so semantically identical URLs share one cache entry.
+function cacheKey(requestUrl) {
+    const url = new URL(requestUrl);
+    url.searchParams.sort();
+    return url.toString();
+}
+function getWaitUntil(c) {
+    // `c.executionCtx` throws on runtimes without one (e.g. Node), so probe it
+    // defensively and fall back to awaiting the write inline.
+    try {
+        const ctx = c.executionCtx;
+        return ctx ? ctx.waitUntil.bind(ctx) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function etagMatches(etag, ifNoneMatch) {
+    const strip = (tag) => tag.trim().replace(/^W\//, '');
+    return ifNoneMatch.split(',').some((tag) => strip(tag) === strip(etag));
+}
+/**
+ * Builds the shared-cache `Cache-Control` value for a stored copy: `public`
+ * with `max-age`/`s-maxage` bound to the policy plus an optional
+ * `stale-while-revalidate` window. Used for this layer's stored copies and by
+ * `Cache.response` to bound the inner response cache's entry lifetime.
+ */
+export function cacheControl(policy) {
+    const directives = ['public', `max-age=${policy.maxAge}`, `s-maxage=${policy.maxAge}`];
+    if (policy.staleWhileRevalidate)
+        directives.push(`stale-while-revalidate=${policy.staleWhileRevalidate}`);
+    return directives.join(', ');
+}
+//# sourceMappingURL=EdgeCache.js.map

package/dist/internal/EdgeCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EdgeCache.js","sourceRoot":"","sources":["../../src/internal/EdgeCache.ts"],"names":[],"mappings":"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"}

package/dist/internal/Log.d.ts

@@ -0,0 +1,104 @@
+import type { MiddlewareHandler } from 'hono';
+import type { RequestIdVariables } from 'hono/request-id';
+import * as ApiKey from '../ApiKey.js';
+import type * as Auth from './Auth.js';
+import type * as EdgeCache from './EdgeCache.js';
+import type * as Timing from './Timing.js';
+/** Hono variables read by the request logger and written by other layers. */
+export type Variables = {
+    /** Stable error code recorded by `Response.error` for the request log entry. */
+    errorCode?: string | undefined;
+};
+/** Hono environment shape used by the request logger. */
+export type Environment = {
+    Variables: Variables & EdgeCache.Variables & RequestIdVariables & Timing.Variables & {
+        /** Authenticated or anonymous caller, set by auth middleware. */
+        principal?: Auth.Principal | undefined;
+    };
+};
+/** Log level, derived from the response status. */
+export type Level = 'error' | 'info' | 'warn';
+/** One canonical request log entry. */
+export type Entry = {
+    /** `'hit'` when the edge response cache served the request without reaching the origin handlers. */
+    cache?: 'hit' | undefined;
+    /** Total request duration in milliseconds. */
+    duration: number;
+    /** Stable error code when the response is a JSON error envelope (e.g. `not_found`, `api_key_invalid`). */
+    errorCode?: string | undefined;
+    /** Log level derived from the response status: 5xx `error`, 4xx `warn`, else `info`. */
+    level: Level;
+    /** Request method. */
+    method: string;
+    /** Request pathname. */
+    path: string;
+    /** MPP payment reason when the request was paid per call. */
+    payment?: Auth.Payment['reason'] | undefined;
+    /** Caller identity. Raw API-key tokens are never logged. */
+    principal?: {
+        /** Key environment for API-key callers. */
+        environment?: ApiKey.ApiKey['environment'] | undefined;
+        /** Principal id: the API key id, or the public quota identity. */
+        id: string;
+        /** Owning organization id for API-key callers. */
+        orgId?: string | undefined;
+        /** Principal kind. */
+        type: 'api_key' | 'public';
+    } | undefined;
+    /** Raw query string (no leading `?`) with API-key tokens redacted, when present. */
+    query?: string | undefined;
+    /** Rate limit state from the `RateLimit-*` response headers, when enforced. */
+    rateLimit?: {
+        /** Quota for the current window. */
+        limit: number;
+        /** Requests remaining in the current window. */
+        remaining: number;
+        /** Reset timestamp in Unix seconds. */
+        reset?: number | undefined;
+        /** Quota bucket scope, when available. */
+        scope?: string | undefined;
+    } | undefined;
+    /** Request id, also echoed in the `tempo-request-id` response header. */
+    requestId: string;
+    /** Matched handler path (bounded cardinality), e.g. `/v1/tokens/:address`; `/*` when a middleware (e.g. an edge-cache hit) short-circuited routing. */
+    route: string;
+    /** Response status code. */
+    status: number;
+    /** Upstream operation durations in milliseconds, from the request's Server-Timing metrics (e.g. RPC and TIDX calls). */
+    timings?: Record<string, number> | undefined;
+};
+/** Sink receiving one {@link Entry} per request. */
+export type Emit = (entry: Entry) => Promise<void> | void;
+/**
+ * Emits one canonical structured log entry per request, after the response is
+ * written. Register after `requestId()` and before the timing and edge-cache
+ * layers so the entry covers edge-cache hits and includes the Server-Timing
+ * metrics collected inside the request.
+ *
+ * The entry derives everything from state other layers already produce —
+ * `requestId`, the auth principal, `RateLimit-*` headers, Server-Timing
+ * metrics, the `errorCode` recorded by `Response.error`, and the edge-cache
+ * hit marker — so handlers never log per-request lines themselves.
+ */
+export declare function middleware<environment extends Environment = Environment>(options?: middleware.Options): MiddlewareHandler<environment>;
+export declare namespace middleware {
+    /** Options for the request logger middleware. */
+    type Options = {
+        /** Log sink. Defaults to {@link emit}: the level-matched console method, passed the entry as a structured object. */
+        emit?: Emit | undefined;
+    };
+}
+/**
+ * Default log sink: writes the entry as a structured object through the
+ * console method matching its level. Passing the object (not a pre-serialized
+ * JSON string) lets Cloudflare Workers Logs index the fields for filtering
+ * and querying; Node prints the same object inline on stdout/stderr.
+ */
+export declare function emit(entry: Entry): void;
+/**
+ * An {@link Emit} that drops entries below `min` and otherwise delegates to
+ * {@link emit}. `'warn'` keeps warn/error (e.g. production, where the request
+ * metrics sink carries successful-request volume instead of one info log each).
+ */
+export declare function withMinLevel(min: Level): Emit;
+//# sourceMappingURL=Log.d.ts.map

package/dist/internal/Log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Log.d.ts","sourceRoot":"","sources":["../../src/internal/Log.ts"],"names":[],"mappings":"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"}

package/dist/internal/Log.js

@@ -0,0 +1,118 @@
+import * as ApiKey from '../ApiKey.js';
+/**
+ * Emits one canonical structured log entry per request, after the response is
+ * written. Register after `requestId()` and before the timing and edge-cache
+ * layers so the entry covers edge-cache hits and includes the Server-Timing
+ * metrics collected inside the request.
+ *
+ * The entry derives everything from state other layers already produce —
+ * `requestId`, the auth principal, `RateLimit-*` headers, Server-Timing
+ * metrics, the `errorCode` recorded by `Response.error`, and the edge-cache
+ * hit marker — so handlers never log per-request lines themselves.
+ */
+export function middleware(options = {}) {
+    const fn = options.emit ?? emit;
+    return async (c, next) => {
+        const start = performance.now();
+        await next();
+        const duration = performance.now() - start;
+        const url = new URL(c.req.url);
+        const status = c.res.status;
+        // Hono cannot resolve variable types through the generic `environment`,
+        // so shared-variable reads are cast from the environment contract above
+        // (the same pattern EdgeCache uses for its cross-layer reads).
+        const principal = c.get('principal');
+        const errorCode = c.get('errorCode');
+        // The `request` total metric duplicates `duration` (measured here, one
+        // layer further out), so only operation timings are kept.
+        const metrics = c.get('serverTiming')?.filter((metric) => metric.name !== 'request');
+        const timings = metrics?.length
+            ? Object.fromEntries(metrics.map((metric) => [metric.name, round(metric.duration)]))
+            : undefined;
+        const rateLimit = (() => {
+            const limit = c.res.headers.get('RateLimit-Limit');
+            const remaining = c.res.headers.get('RateLimit-Remaining');
+            const reset = c.res.headers.get('RateLimit-Reset');
+            const scope = c.res.headers.get('RateLimit-Scope');
+            if (limit === null || remaining === null)
+                return undefined;
+            return {
+                limit: Number(limit),
+                remaining: Number(remaining),
+                ...(reset === null ? {} : { reset: Number(reset) }),
+                ...(scope === null ? {} : { scope }),
+            };
+        })();
+        const result = fn({
+            ...(c.get('edgeCacheStatus') === 'hit' ? { cache: 'hit' } : {}),
+            duration: round(duration),
+            ...(errorCode === undefined ? {} : { errorCode }),
+            level: status >= 500 ? 'error' : status >= 400 ? 'warn' : 'info',
+            method: c.req.method,
+            path: url.pathname,
+            ...(principal?.payment === undefined ? {} : { payment: principal.payment.reason }),
+            ...(principal === undefined
+                ? {}
+                : {
+                    principal: {
+                        ...(principal.type === 'api_key' ? { environment: principal.environment } : {}),
+                        id: principal.id,
+                        ...(principal.type === 'api_key' ? { orgId: principal.orgId } : {}),
+                        type: principal.type,
+                    },
+                }),
+            // Keys belong in headers, but a confused client may pass one in the
+            // query string; redact defensively before it reaches a log store.
+            ...(url.search.length > 1 ? { query: ApiKey.redact(url.search.slice(1)) } : {}),
+            ...(rateLimit === undefined ? {} : { rateLimit }),
+            requestId: c.get('requestId'),
+            route: c.req.routePath,
+            status,
+            ...(timings === undefined ? {} : { timings }),
+        });
+        if (result instanceof Promise) {
+            const promise = result.catch((error) => console.error('request log sink failed', error));
+            // Unit tests and non-Worker runtimes do not always provide an execution
+            // context. In Workers, waitUntil keeps async sinks alive without holding
+            // the response open; elsewhere the promise is deliberately fire-and-forget.
+            try {
+                c.executionCtx.waitUntil(promise);
+            }
+            catch {
+                void promise;
+            }
+        }
+    };
+}
+/**
+ * Default log sink: writes the entry as a structured object through the
+ * console method matching its level. Passing the object (not a pre-serialized
+ * JSON string) lets Cloudflare Workers Logs index the fields for filtering
+ * and querying; Node prints the same object inline on stdout/stderr.
+ */
+export function emit(entry) {
+    if (entry.level === 'error')
+        console.error(entry);
+    else if (entry.level === 'warn')
+        console.warn(entry);
+    else
+        console.log(entry);
+}
+/** Severity ranking used to filter entries below a minimum level. */
+const severity = { error: 2, info: 0, warn: 1 };
+/**
+ * An {@link Emit} that drops entries below `min` and otherwise delegates to
+ * {@link emit}. `'warn'` keeps warn/error (e.g. production, where the request
+ * metrics sink carries successful-request volume instead of one info log each).
+ */
+export function withMinLevel(min) {
+    return (entry) => {
+        if (severity[entry.level] < severity[min])
+            return;
+        emit(entry);
+    };
+}
+function round(value) {
+    return Math.round(value * 10) / 10;
+}
+//# sourceMappingURL=Log.js.map

package/dist/internal/Log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Log.js","sourceRoot":"","sources":["../../src/internal/Log.ts"],"names":[],"mappings":"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"}

package/dist/internal/MetricSink.d.ts

@@ -0,0 +1,65 @@
+import type { Metrics } from '../Metrics.js';
+import type * as Webhooks from '../Webhooks.js';
+import type * as Log from './Log.js';
+/** Webhook event type, including the synthetic `ping` carried on test envelopes. */
+export type EventType = Webhooks.Envelope['type'];
+/** Where a delivery attempt originated. */
+export type Trigger = 'manual_retry' | 'ping' | 'queue';
+/** Context for one poller tick that the {@link Webhooks.createPoller.Result} omits. */
+export type TickMeta = {
+    /** Chain polled this tick; used when the tick errored before a result existed. */
+    chainId?: number | undefined;
+    /** Wall-clock duration of the tick in ms. */
+    durationMs: number;
+    /** Whether the tick completed. */
+    outcome: 'error' | 'ok';
+};
+/**
+ * A webhook metric event, recorded by the {@link webhooks} sink. The poller
+ * emits `webhook:tick`/`webhook:enqueue` and the delivery path emits
+ * `webhook:delivery`.
+ */
+export type WebhookEvent = {
+    meta: TickMeta;
+    result: Webhooks.createPoller.Result | undefined;
+    type: 'webhook:tick';
+} | {
+    chainId: number;
+    durationMs: number;
+    eventType: EventType;
+    ok: boolean;
+    type: 'webhook:enqueue';
+} | {
+    envelope: Webhooks.Envelope;
+    result: Webhooks.Result;
+    subscription: Webhooks.Subscription;
+    trigger: Trigger;
+    type: 'webhook:delivery';
+};
+/** Records request (HTTP) metrics for one request-log entry. Built by {@link requests}. */
+export type RequestSink = (entry: Log.Entry) => void;
+/** Records webhook reliability metrics. Built by {@link webhooks}. */
+export type WebhookSink = {
+    /** Ships buffered metrics (call once per poller tick / delivery). */
+    flush(): void;
+    /** Records one webhook event. */
+    record(event: WebhookEvent): void;
+};
+/**
+ * Builds a request (HTTP) metrics sink over `backend`: emits the bounded Worker
+ * metrics derived from one request-log entry, then flushes (one entry == one
+ * request).
+ *
+ * Metric tags deliberately exclude caller ids, organization ids, request ids,
+ * raw paths, and IP-derived identities — those belong in logs or analytics, not
+ * StatsD-style series.
+ */
+export declare function requests(backend: Metrics): RequestSink;
+/**
+ * Builds a webhook delivery-reliability sink over `backend`. Tags stay
+ * low-cardinality (`chain_id`, `event_type`, `destination_type`, `status_class`,
+ * `attempt_bucket`, `outcome`) — never subscription/org/event ids, which belong
+ * in logs or analytics, not StatsD-style series.
+ */
+export declare function webhooks(backend: Metrics): WebhookSink;
+//# sourceMappingURL=MetricSink.d.ts.map

package/dist/internal/MetricSink.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetricSink.d.ts","sourceRoot":"","sources":["../../src/internal/MetricSink.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAA;AAC5C,OAAO,KAAK,KAAK,QAAQ,MAAM,gBAAgB,CAAA;AAC/C,OAAO,KAAK,KAAK,GAAG,MAAM,UAAU,CAAA;AAEpC,oFAAoF;AACpF,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAA;AAEjD,2CAA2C;AAC3C,MAAM,MAAM,OAAO,GAAG,cAAc,GAAG,MAAM,GAAG,OAAO,CAAA;AAEvD,uFAAuF;AACvF,MAAM,MAAM,QAAQ,GAAG;IACrB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,6CAA6C;IAC7C,UAAU,EAAE,MAAM,CAAA;IAClB,kCAAkC;IAClC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAA;CACxB,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,YAAY,GACpB;IACE,IAAI,EAAE,QAAQ,CAAA;IACd,MAAM,EAAE,QAAQ,CAAC,YAAY,CAAC,MAAM,GAAG,SAAS,CAAA;IAChD,IAAI,EAAE,cAAc,CAAA;CACrB,GACD;IACE,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,SAAS,EAAE,SAAS,CAAA;IACpB,EAAE,EAAE,OAAO,CAAA;IACX,IAAI,EAAE,iBAAiB,CAAA;CACxB,GACD;IACE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,CAAA;IAC3B,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAA;IACvB,YAAY,EAAE,QAAQ,CAAC,YAAY,CAAA;IACnC,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,kBAAkB,CAAA;CACzB,CAAA;AAEL,2FAA2F;AAC3F,MAAM,MAAM,WAAW,GAAG,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,KAAK,IAAI,CAAA;AAEpD,sEAAsE;AACtE,MAAM,MAAM,WAAW,GAAG;IACxB,qEAAqE;IACrE,KAAK,IAAI,IAAI,CAAA;IACb,iCAAiC;IACjC,MAAM,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAA;CAClC,CAAA;AAWD;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAwBtD;AAqBD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,WAAW,CAqEtD"}

package/dist/internal/MetricSink.js

@@ -0,0 +1,146 @@
+/**
+ * Builds a request (HTTP) metrics sink over `backend`: emits the bounded Worker
+ * metrics derived from one request-log entry, then flushes (one entry == one
+ * request).
+ *
+ * Metric tags deliberately exclude caller ids, organization ids, request ids,
+ * raw paths, and IP-derived identities — those belong in logs or analytics, not
+ * StatsD-style series.
+ */
+export function requests(backend) {
+    return (entry) => {
+        const tags = routeTags(entry);
+        backend.count('http_response_count', 1, {
+            ...tags,
+            ...(entry.errorCode === undefined ? {} : { error_code: entry.errorCode }),
+            ...(entry.payment === undefined ? {} : { payment: entry.payment }),
+            status: entry.status,
+        });
+        backend.histogram('http_response_duration_ms', entry.duration, tags);
+        if (entry.status === 429 || entry.errorCode === 'rate_limit_exceeded')
+            backend.count('http_rate_limit_count', 1, {
+                ...tags,
+                rate_limit_scope: entry.rateLimit?.scope ?? 'unknown',
+                status: entry.status,
+            });
+        for (const [operation, duration] of Object.entries(entry.timings ?? {}))
+            backend.histogram('upstream_duration_ms', duration, { ...tags, operation });
+        backend.flush();
+    };
+}
+function routeTags(entry) {
+    return {
+        cache: entry.cache ?? 'miss',
+        method: entry.method,
+        principal_environment: entry.principal?.environment ?? 'none',
+        principal_type: entry.principal?.type ?? 'unknown',
+        route: entry.route,
+    };
+}
+/**
+ * Builds a webhook delivery-reliability sink over `backend`. Tags stay
+ * low-cardinality (`chain_id`, `event_type`, `destination_type`, `status_class`,
+ * `attempt_bucket`, `outcome`) — never subscription/org/event ids, which belong
+ * in logs or analytics, not StatsD-style series.
+ */
+export function webhooks(backend) {
+    return {
+        flush() {
+            backend.flush();
+        },
+        record(event) {
+            switch (event.type) {
+                case 'webhook:tick': {
+                    const { meta, result } = event;
+                    const chain_id = String(result?.chainId ?? meta.chainId ?? 'unknown');
+                    backend.count('webhook_poller_tick_count', 1, { chain_id, outcome: meta.outcome });
+                    backend.histogram('webhook_poller_tick_duration_ms', meta.durationMs, {
+                        chain_id,
+                        outcome: meta.outcome,
+                    });
+                    if (!result)
+                        return;
+                    backend.histogram('webhook_poller_subscription_count', result.subscriptions, { chain_id });
+                    backend.count('webhook_poller_scanned_count', result.scanned, { chain_id });
+                    backend.gauge('webhook_poller_safe_block', result.safeBlock, { chain_id });
+                    backend.count('webhook_poller_dispatch_count', result.dispatched, {
+                        chain_id,
+                        outcome: 'dispatched',
+                    });
+                    backend.count('webhook_poller_dispatch_count', result.failed, {
+                        chain_id,
+                        outcome: 'failed',
+                    });
+                    return;
+                }
+                case 'webhook:enqueue': {
+                    const tags = { chain_id: String(event.chainId), event_type: event.eventType };
+                    const outcome = event.ok ? 'ok' : 'error';
+                    backend.count('webhook_dispatch_enqueue_count', 1, { ...tags, outcome });
+                    backend.histogram('webhook_dispatch_enqueue_duration_ms', event.durationMs, {
+                        ...tags,
+                        outcome,
+                    });
+                    return;
+                }
+                case 'webhook:delivery': {
+                    const { envelope, result, subscription } = event;
+                    const tags = {
+                        chain_id: String(envelope.chainId),
+                        destination_type: subscription.destination.type,
+                        event_type: envelope.type,
+                    };
+                    const outcome = result.ok ? 'succeeded' : 'failed';
+                    backend.count('webhook_delivery_attempt_count', 1, {
+                        ...tags,
+                        attempt_bucket: attemptBucket(subscription.failureCount + 1),
+                        outcome,
+                        status_class: statusClass(result),
+                        trigger: event.trigger,
+                    });
+                    if (result.durationMs !== undefined)
+                        backend.histogram('webhook_delivery_duration_ms', result.durationMs, {
+                            ...tags,
+                            outcome,
+                        });
+                    backend.histogram('webhook_delivery_queue_latency_ms', Math.max(0, Date.now() - Date.parse(envelope.createdAt)), tags);
+                    return;
+                }
+            }
+        },
+    };
+}
+/** Buckets a 1-based attempt number into a bounded set of attempt labels. */
+function attemptBucket(attempt) {
+    if (attempt <= 1)
+        return '1';
+    if (attempt === 2)
+        return '2';
+    if (attempt <= 5)
+        return '3-5';
+    if (attempt <= 10)
+        return '6-10';
+    return 'gt10';
+}
+/** Maps a delivery result to a low-cardinality status class. */
+function statusClass(result) {
+    if (result.ok)
+        return '2xx';
+    const { error, status } = result;
+    if (status !== undefined) {
+        if (status >= 300 && status < 400)
+            return 'url_rejected';
+        if (status >= 400 && status < 500)
+            return '4xx';
+        if (status >= 500)
+            return '5xx';
+    }
+    if (error === undefined)
+        return 'unknown';
+    if (/redirect/i.test(error))
+        return 'url_rejected';
+    if (/timeout|abort/i.test(error))
+        return 'timeout';
+    return 'network';
+}
+//# sourceMappingURL=MetricSink.js.map

package/dist/internal/MetricSink.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"MetricSink.js","sourceRoot":"","sources":["../../src/internal/MetricSink.ts"],"names":[],"mappings":"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"}