@sequenceholdings/managed-functions 0.1.1

package/dist/tracing.js

@@ -0,0 +1,363 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FUNCTION_EGRESS_SUMMARY = void 0;
+exports.installFunctionTracing = installFunctionTracing;
+exports.runWithFunctionTracing = runWithFunctionTracing;
+const http_tracing_1 = require("./http-tracing");
+const node_async_hooks_1 = require("node:async_hooks");
+const promises_1 = require("node:timers/promises");
+const api_1 = require("@opentelemetry/api");
+const sdk_trace_base_1 = require("@opentelemetry/sdk-trace-base");
+const invocation = new node_async_hooks_1.AsyncLocalStorage();
+const provider = new sdk_trace_base_1.BasicTracerProvider();
+const tracer = provider.getTracer('com.seqholdings.managed-functions', '1.0.0');
+let originalFetch;
+const MAX_BATCHES = 10;
+const MAX_SPANS = 100;
+const BATCH_DELAY_MS = 50;
+const EXPORT_TIMEOUT_MS = 500;
+const nanos = (ms) => (BigInt(ms) * 1000000n).toString();
+function installFunctionTracing() {
+    if (originalFetch)
+        return;
+    originalFetch = globalThis.fetch.bind(globalThis);
+    const send = originalFetch;
+    globalThis.fetch = async (input, init) => {
+        const current = invocation.getStore();
+        if (!current || current.stopped)
+            return send(input, init);
+        const url = new URL(input instanceof Request ? input.url : input.toString());
+        const headers = new Headers(init?.headers ?? (input instanceof Request ? input.headers : undefined));
+        const method = (init?.method ?? (input instanceof Request ? input.method : 'GET')).toUpperCase();
+        const atlasRequest = url.origin === current.origin &&
+            (url.pathname.startsWith('/api/') || url.pathname.startsWith('/_data/'));
+        if (url.origin === current.origin &&
+            (url.pathname.startsWith('/api/') || url.pathname.startsWith('/_data/'))) {
+            for (const [key, value] of Object.entries(current.headers))
+                headers.set(key, value);
+            init = { ...init, headers, redirect: 'manual' };
+            if (!(0, http_tracing_1.shouldReportAtlasHttp)(url.pathname, method))
+                return send(input, init);
+        }
+        const operation = /^(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)$/.test(method)
+            ? method
+            : 'HTTP';
+        const span = tracer.startSpan(operation, { kind: api_1.SpanKind.CLIENT }, api_1.trace.setSpanContext(api_1.ROOT_CONTEXT, {
+            ...current.parent,
+            traceFlags: 1,
+            isRemote: true,
+        }));
+        const started = Date.now();
+        let status = 0;
+        try {
+            const response = await send(input, init);
+            status = response.status;
+            span.setStatus({
+                code: status >= 400 ? api_1.SpanStatusCode.ERROR : api_1.SpanStatusCode.UNSET,
+            });
+            return response;
+        }
+        finally {
+            span.end();
+            if (!current.stopped &&
+                !current.finishing &&
+                current.captured < MAX_SPANS) {
+                current.captured++;
+                current.spans.push({
+                    traceId: span.spanContext().traceId,
+                    spanId: span.spanContext().spanId,
+                    parentSpanId: current.parent.spanId,
+                    name: operation,
+                    kind: 3,
+                    startTimeUnixNano: nanos(started),
+                    endTimeUnixNano: nanos(Date.now()),
+                    attributes: [
+                        ...(atlasRequest
+                            ? [
+                                {
+                                    key: 'url.path',
+                                    value: {
+                                        stringValue: url.pathname.length <= 512
+                                            ? url.pathname
+                                            : '/api/[unmatched]',
+                                    },
+                                },
+                                {
+                                    key: 'com.seqholdings.atlas_api',
+                                    value: { stringValue: 'true' },
+                                },
+                            ]
+                            : []),
+                        { key: 'server.address', value: { stringValue: url.hostname } },
+                        {
+                            key: 'http.request.method',
+                            value: {
+                                stringValue: operation === 'HTTP' ? '_OTHER' : operation,
+                            },
+                        },
+                        {
+                            key: 'url.scheme',
+                            value: { stringValue: url.protocol.slice(0, -1) },
+                        },
+                        ...(status
+                            ? [
+                                {
+                                    key: 'http.response.status_code',
+                                    value: { intValue: String(status) },
+                                },
+                            ]
+                            : []),
+                    ],
+                    status: { code: status === 0 || status >= 400 ? 2 : 0 },
+                });
+                scheduleExport(current);
+            }
+            else if (!current.stopped)
+                current.dropped++;
+        }
+    };
+}
+async function runWithFunctionTracing(request, run, response) {
+    installFunctionTracing();
+    const read = (key) => {
+        const value = request.headers?.[key];
+        return typeof value === 'string' ? value : undefined;
+    };
+    const sequenceParent = read('x-sequence-traceparent');
+    const traceparent = sequenceParent ?? read('traceparent');
+    const match = traceparent?.match(/^00-([0-9a-f]{32})-([0-9a-f]{16})-01$/);
+    const attestation = read('x-sequence-trace-attestation');
+    const origin = read('x-sequence-trace-origin');
+    const principal = read('x-sequence-trace-principal');
+    if (!match || !traceparent || !attestation || !origin || !principal)
+        return run();
+    const current = {
+        parent: { traceId: match[1], spanId: match[2] },
+        headers: {
+            traceparent,
+            ...(sequenceParent === undefined
+                ? {}
+                : { 'x-sequence-traceparent': sequenceParent }),
+            'x-sequence-trace-attestation': attestation,
+        },
+        origin,
+        principal,
+        spans: [],
+        dropped: 0,
+        captured: 0,
+        acknowledged: 0,
+        rejected: 0,
+        abandoned: 0,
+        timedOut: false,
+        batches: 0,
+        stopped: false,
+        abort: new AbortController(),
+    };
+    if (response) {
+        const end = response.end;
+        const onClose = () => {
+            stopExport(current);
+            void finishExport(current);
+        };
+        response.once('close', onClose);
+        response.end = function (...args) {
+            response.off('close', onClose);
+            response.end = end;
+            void finishExport(current);
+            if (!response.destroyed)
+                Reflect.apply(end, response, args);
+            return this;
+        };
+    }
+    try {
+        return await invocation.run(current, run);
+    }
+    catch (error) {
+        void finishExport(current);
+        throw error;
+    }
+    finally {
+        if (!response || current.finishing || response.destroyed)
+            void finishExport(current);
+    }
+}
+function scheduleExport(current) {
+    if (current.stopped ||
+        current.finishing ||
+        current.timer ||
+        current.inFlight ||
+        current.batches >= MAX_BATCHES - 1 ||
+        !current.spans.length)
+        return;
+    current.timer = setTimeout(() => {
+        current.timer = undefined;
+        startExport(current);
+    }, BATCH_DELAY_MS);
+}
+function startExport(current) {
+    if (current.inFlight)
+        return current.inFlight;
+    if (current.stopped || !current.spans.length)
+        return Promise.resolve();
+    const spans = current.spans.splice(0);
+    current.batches++;
+    const sending = exportEgress(current, spans).finally(() => {
+        current.inFlight = undefined;
+        scheduleExport(current);
+    });
+    current.inFlight = sending;
+    return sending;
+}
+function stopExport(current) {
+    current.stopped = true;
+    clearTimeout(current.timer);
+    current.timer = undefined;
+    current.abort.abort();
+    current.abandoned += current.spans.length;
+    current.spans.length = 0;
+}
+function finishExport(current) {
+    if (current.finishing)
+        return current.finishing;
+    clearTimeout(current.timer);
+    current.timer = undefined;
+    const started = Date.now();
+    const remaining = current.spans.splice(0);
+    current.finishing = Promise.all([
+        current.inFlight,
+        remaining.length ? exportEgress(current, remaining) : undefined,
+    ])
+        .catch(() => undefined)
+        .then(() => {
+        stopExport(current);
+        reportEgressDelivery({ current, finalExportMs: Date.now() - started });
+    });
+    return current.finishing;
+}
+exports.FUNCTION_EGRESS_SUMMARY = 'traces.function_egress.summary';
+function reportEgressDelivery({ current, finalExportMs, }) {
+    if (!current.captured)
+        return;
+    try {
+        const unacknowledged = Math.max(0, current.captured -
+            current.acknowledged -
+            current.rejected -
+            current.abandoned);
+        const line = JSON.stringify({
+            message: exports.FUNCTION_EGRESS_SUMMARY,
+            metric: exports.FUNCTION_EGRESS_SUMMARY,
+            captured: current.captured,
+            acknowledged: current.acknowledged,
+            unacknowledged,
+            rejected: current.rejected,
+            abandoned: current.abandoned,
+            dropped: current.dropped,
+            exportTimedOut: current.timedOut,
+            finalExportMs,
+        });
+        if (current.rejected || current.abandoned || current.dropped)
+            console.warn(line);
+        else
+            console.info(line);
+    }
+    catch {
+    }
+}
+async function exportEgress(current, spans) {
+    if (!spans.length || !originalFetch || current.stopped)
+        return;
+    const body = JSON.stringify({
+        resourceSpans: [
+            {
+                resource: {
+                    attributes: [
+                        {
+                            key: 'service.name',
+                            value: { stringValue: 'managed-function' },
+                        },
+                    ],
+                },
+                scopeSpans: [
+                    {
+                        scope: {
+                            name: 'com.seqholdings.managed-functions',
+                            version: '1.0.0',
+                        },
+                        spans,
+                    },
+                ],
+            },
+        ],
+    });
+    const timeout = new AbortController();
+    const timer = setTimeout(() => timeout.abort(), EXPORT_TIMEOUT_MS);
+    const signal = AbortSignal.any([current.abort.signal, timeout.signal]);
+    const send = originalFetch;
+    let onAbort;
+    const aborted = new Promise((resolve) => {
+        onAbort = resolve;
+    });
+    signal.addEventListener('abort', onAbort, { once: true });
+    const attempts = async () => {
+        let uncertain = false;
+        for (let attempt = 0; attempt < 2 && !signal.aborted; attempt++) {
+            try {
+                const response = await send(`${current.origin}/api/runtime-traces/v1/traces`, {
+                    method: 'POST',
+                    headers: {
+                        ...current.headers,
+                        'x-sequence-trace-principal': current.principal,
+                        'Content-Type': 'application/json',
+                    },
+                    body,
+                    redirect: 'error',
+                    signal,
+                });
+                if (response.ok) {
+                    const result = (await response.json().catch(() => ({})));
+                    if (signal.aborted)
+                        return;
+                    const reported = Number(result.partialSuccess?.rejectedSpans ?? 0);
+                    if (Number.isInteger(reported) && reported >= 0) {
+                        const rejected = Math.min(reported, spans.length);
+                        if (!uncertain)
+                            current.rejected += rejected;
+                        current.acknowledged += spans.length - rejected;
+                    }
+                    if (result.partialSuccess?.rejectedSpans)
+                        console.warn('[traces] Egress spans outside capture scope', {
+                            rejected: result.partialSuccess.rejectedSpans,
+                        });
+                    break;
+                }
+                await response.body?.cancel();
+                if (response.status !== 429 && response.status < 500) {
+                    if (!uncertain)
+                        current.rejected += spans.length;
+                    break;
+                }
+                uncertain = true;
+            }
+            catch {
+                uncertain = true;
+            }
+            if (attempt === 0) {
+                try {
+                    await (0, promises_1.setTimeout)(50, undefined, { signal });
+                }
+                catch {
+                    break;
+                }
+            }
+        }
+    };
+    try {
+        await Promise.race([attempts(), aborted]);
+    }
+    finally {
+        if (timeout.signal.aborted)
+            current.timedOut = true;
+        signal.removeEventListener('abort', onAbort);
+        clearTimeout(timer);
+    }
+}

package/dist/valkey.d.ts

@@ -0,0 +1,41 @@
+import { checkServerIdentity } from 'node:tls';
+import { type CacheStore } from './cache';
+export interface ValkeyConnection {
+    host: string;
+    port: number;
+    serverIdentity: string;
+    caCertificates: string[];
+    keyPrefix: string;
+}
+export declare function valkeyTlsOptions(connection: ValkeyConnection): {
+    ca: string[];
+    servername: string | undefined;
+    rejectUnauthorized: boolean;
+    minVersion: "TLSv1.2";
+    checkServerIdentity: (_hostname: string, cert: Parameters<typeof checkServerIdentity>[1]) => Error | undefined;
+};
+export declare class ValkeyStore implements CacheStore {
+    private readonly connection;
+    private client;
+    private connecting;
+    private epoch;
+    private active;
+    private failures;
+    private openUntil;
+    private telemetry;
+    private readonly telemetryTimer;
+    private readonly auth;
+    constructor(connection: ValkeyConnection, local?: boolean);
+    private connect;
+    close(): void;
+    private resetConnection;
+    private execute;
+    get(key: string): Promise<string | null>;
+    set({ key, value, ttlSeconds, onlyIfAbsent, }: {
+        key: string;
+        value: string;
+        ttlSeconds: number;
+        onlyIfAbsent: boolean;
+    }): Promise<boolean>;
+    delete(key: string): Promise<boolean>;
+}

package/dist/valkey.js

@@ -0,0 +1,175 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValkeyStore = void 0;
+exports.valkeyTlsOptions = valkeyTlsOptions;
+const node_net_1 = require("node:net");
+const node_tls_1 = require("node:tls");
+const google_auth_library_1 = require("google-auth-library");
+const ioredis_1 = require("ioredis");
+const cache_1 = require("./cache");
+const COMMAND_TIMEOUT_MS = 150;
+const CONNECT_TIMEOUT_MS = 1500;
+const BREAKER_RESET_MS = 5000;
+const MAX_PENDING = 128;
+function valkeyTlsOptions(connection) {
+    return {
+        ca: connection.caCertificates,
+        servername: (0, node_net_1.isIP)(connection.serverIdentity)
+            ? undefined
+            : connection.serverIdentity,
+        rejectUnauthorized: true,
+        minVersion: 'TLSv1.2',
+        checkServerIdentity: (_hostname, cert) => (0, node_tls_1.checkServerIdentity)(connection.serverIdentity, cert),
+    };
+}
+class ValkeyStore {
+    connection;
+    client;
+    connecting;
+    epoch = 0;
+    active = 0;
+    failures = 0;
+    openUntil = 0;
+    telemetry = {
+        operations: 0,
+        errors: 0,
+        latencyTotalMs: 0,
+        latencyMaxMs: 0,
+    };
+    telemetryTimer;
+    auth;
+    constructor(connection, local = false) {
+        this.connection = connection;
+        if (!local && process.env.K_SERVICE) {
+            this.telemetryTimer = setInterval(() => {
+                if (this.telemetry.operations > 0)
+                    console.info(JSON.stringify({
+                        severity: 'INFO',
+                        event: 'managed_function.cache',
+                        ...this.telemetry,
+                    }));
+                this.telemetry = {
+                    operations: 0,
+                    errors: 0,
+                    latencyTotalMs: 0,
+                    latencyMaxMs: 0,
+                };
+            }, 30000);
+            this.telemetryTimer.unref();
+        }
+        this.auth = local
+            ? new google_auth_library_1.GoogleAuth({
+                scopes: ['https://www.googleapis.com/auth/cloud-platform'],
+            })
+            : new google_auth_library_1.Compute({
+                scopes: ['https://www.googleapis.com/auth/cloud-platform'],
+            });
+    }
+    async connect() {
+        if (this.client?.status === 'ready')
+            return this.client;
+        if (this.connecting)
+            return this.connecting;
+        const epoch = this.epoch;
+        const connection = (async () => {
+            const access = await this.auth.getAccessToken();
+            const token = typeof access === 'string' ? access : access?.token;
+            if (!token || epoch !== this.epoch)
+                throw new cache_1.CacheError('UNAVAILABLE');
+            const client = new ioredis_1.Redis({
+                host: this.connection.host,
+                port: this.connection.port,
+                username: 'default',
+                password: token,
+                tls: valkeyTlsOptions(this.connection),
+                keyPrefix: this.connection.keyPrefix,
+                lazyConnect: true,
+                connectTimeout: CONNECT_TIMEOUT_MS,
+                commandTimeout: COMMAND_TIMEOUT_MS,
+                enableOfflineQueue: false,
+                enableReadyCheck: false,
+                retryStrategy: () => null,
+                maxRetriesPerRequest: 0,
+                autoResendUnfulfilledCommands: false,
+                autoResubscribe: false,
+            });
+            client.on('error', () => {
+            });
+            this.client = client;
+            await client.connect();
+            if (epoch !== this.epoch) {
+                client.disconnect();
+                throw new cache_1.CacheError('UNAVAILABLE');
+            }
+            return client;
+        })();
+        this.connecting = connection;
+        try {
+            return await connection;
+        }
+        finally {
+            if (this.connecting === connection)
+                this.connecting = undefined;
+        }
+    }
+    close() {
+        clearInterval(this.telemetryTimer);
+        this.resetConnection();
+    }
+    resetConnection() {
+        this.epoch++;
+        this.client?.disconnect();
+        this.client = undefined;
+        this.connecting = undefined;
+    }
+    async execute(mutation, command) {
+        if (Date.now() < this.openUntil || this.active >= MAX_PENDING)
+            throw new cache_1.CacheError('UNAVAILABLE');
+        this.active++;
+        const started = performance.now();
+        let sent = false;
+        let timer;
+        const deadline = this.client?.status === 'ready' ? COMMAND_TIMEOUT_MS : CONNECT_TIMEOUT_MS;
+        try {
+            const result = await Promise.race([
+                (async () => {
+                    const client = await this.connect();
+                    sent = true;
+                    return command(client);
+                })(),
+                new Promise((_, reject) => {
+                    timer = setTimeout(() => reject(new cache_1.CacheError('UNAVAILABLE')), deadline);
+                }),
+            ]);
+            this.failures = 0;
+            return result;
+        }
+        catch {
+            this.telemetry.errors++;
+            this.resetConnection();
+            if (++this.failures >= 3)
+                this.openUntil = Date.now() + BREAKER_RESET_MS;
+            throw new cache_1.CacheError(mutation && sent ? 'UNKNOWN_OUTCOME' : 'UNAVAILABLE');
+        }
+        finally {
+            clearTimeout(timer);
+            this.active--;
+            const elapsed = performance.now() - started;
+            this.telemetry.operations++;
+            this.telemetry.latencyTotalMs += elapsed;
+            this.telemetry.latencyMaxMs = Math.max(this.telemetry.latencyMaxMs, elapsed);
+        }
+    }
+    get(key) {
+        return this.execute(false, (client) => client.get(key));
+    }
+    async set({ key, value, ttlSeconds, onlyIfAbsent, }) {
+        return this.execute(true, async (client) => (onlyIfAbsent
+            ? await client.set(key, value, 'EX', ttlSeconds, 'NX')
+            : await client.set(key, value, 'EX', ttlSeconds)) === 'OK');
+    }
+    delete(key) {
+        return this.execute(true, async (client) => (await client.del(key)) > 0);
+    }
+}
+exports.ValkeyStore = ValkeyStore;

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@sequenceholdings/managed-functions",
+  "version": "0.1.1",
+  "description": "Managed Function context and opt-in cache runtime",
+  "license": "UNLICENSED",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "default": "./dist/config.js"
+    },
+    "./runtime": "./dist/runtime.cjs"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "google-auth-library": "^10.5.0",
+    "ioredis": "^5.10.0",
+    "zod": "^4.1.13",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/sdk-trace-base": "^2.5.1",
+    "@sequenceholdings/storage": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.11",
+    "esbuild": "^0.25.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/bundle-runtime.mjs",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}