@apifuse/provider-sdk 2.2.0-beta.61 → 2.2.0-beta.62

package/dist/runtime/handle.js

@@ -3,13 +3,15 @@
  *
  * Storage layout: one state namespace per kind, `handle.<kind>`, scoped by the
  * kind's access (bound → connection scope via `state.forConnection`, public →
- * provider scope). The state key is the canonical handle string. Records hold
+ * provider scope; both cursors and drafts may be either). The state key is the
+ * canonical handle string. Records hold
  * the validated data plus status/timestamps; the handle string itself carries
  * no payload and no signature.
  */
 import { randomInt, randomUUID } from "node:crypto";
 import { isProviderError } from "../errors.js";
 import { HandleError, handleRecoverySentence, isDraftKind, } from "../handle.js";
+import { formatHandleIssuers } from "../handle-meta.js";
 import { BOUND_HANDLE_WORD_COUNT, findHandleWordWithinDistance, HIGH_PUBLIC_HANDLE_WORD_COUNT, ISSUABLE_HANDLE_WORDS, PUBLIC_HANDLE_WORD_COUNT, } from "./handle-wordlist.js";
 import { createMemoryProviderRuntimeState } from "./state.js";
 const RECORD_VERSION = 1;
@@ -151,14 +153,13 @@ export function formatNormalizationClasses(classes) {
 // Errors (spec §5)
 // ---------------------------------------------------------------------------
 function publicCollapsedMessage(kind) {
-    const again = kind.issuedBy
-        ? `Call \`${kind.issuedBy}\` again to get a new one.`
-        : "Request a new one.";
+    const issuers = formatHandleIssuers(kind.issuedBy);
+    const again = issuers ? `Call ${issuers} again to get a new one.` : "Request a new one.";
     return `\`${kind.fieldName}\` is not valid or has expired. ${again}`;
 }
 function normalizationError(kind, failure) {
     if (failure.reason === "kind_mismatch") {
-        return new HandleError("HANDLE_KIND_MISMATCH", `\`${kind.fieldName}\` must be a \`${kind.name}_...\` handle as returned by ${kind.issuedBy ? `\`${kind.issuedBy}\`` : "the issuing operation"}. ${handleRecoverySentence(kind)}`, { kind: kind.name, details: { field: kind.fieldName } });
+        return new HandleError("HANDLE_KIND_MISMATCH", `\`${kind.fieldName}\` must be a \`${kind.name}_...\` handle as returned by ${formatHandleIssuers(kind.issuedBy) ?? "the issuing operation"}. ${handleRecoverySentence(kind)}`, { kind: kind.name, details: { field: kind.fieldName } });
     }
     if (kind.access === "public") {
         return new HandleError("HANDLE_INVALID", publicCollapsedMessage(kind), {
@@ -217,7 +218,7 @@ function committedError(kind) {
     return new HandleError("HANDLE_COMMITTED", `\`${kind.fieldName}\` has already been committed and can no longer be changed. ${handleRecoverySentence(kind)}`, { kind: kind.name, details: { field: kind.fieldName } });
 }
 function connectionRequiredError(kind, operation) {
-    return new HandleError("HANDLE_CONNECTION_REQUIRED", `Handle kind "${kind.name}" is bound to a connection, but request.connectionId is missing for ${operation}. Bound handles require a connection-scoped request; use access: "public" for connection-less cursors.`, { kind: kind.name });
+    return new HandleError("HANDLE_CONNECTION_REQUIRED", `Handle kind "${kind.name}" is bound to a connection, but request.connectionId is missing for ${operation}. Bound handles require a connection-scoped request; use access: "public" for connection-less kinds.`, { kind: kind.name });
 }
 function storageUnavailableError(kind, reason, cause) {
     return new HandleError("HANDLE_STORAGE_UNAVAILABLE", `Handle storage for kind "${kind.name}" is not available: ${reason}.`, { kind: kind.name, cause, details: { reason } });
@@ -526,7 +527,7 @@ export function createHandleContext(options) {
             record: value,
         };
     }
-    async function create(kind, data) {
+    async function createRecord(kind, data) {
         return await instrumented(kind, "create", async (report) => {
             const validated = validateData(kind, "create", data);
             const namespace = resolveNamespace(kind, "create");
@@ -551,12 +552,16 @@ export function createHandleContext(options) {
             for (let attempt = 0; attempt < CREATE_ATTEMPTS; attempt += 1) {
                 const canonical = `${kind.name}_${generateWords(kind.wordCount).join("-")}`;
                 const result = await storage(kind, () => namespace.compareAndSet(canonical, 0, record, { ttl: msDuration(writeTtlMs) }));
-                if (result.ok)
-                    return { value: canonical, outcome: "success" };
+                if (result.ok) {
+                    return { value: toHandleRecord(kind, canonical, record), outcome: "success" };
+                }
             }
             throw storageUnavailableError(kind, `could not allocate a unique handle after ${CREATE_ATTEMPTS} attempts`);
         });
     }
+    async function create(kind, data) {
+        return (await createRecord(kind, data)).handle;
+    }
     async function read(kind, handle) {
         return await instrumented(kind, "read", async (report) => {
             const loaded = await load(kind, "read", handle, report);
@@ -876,7 +881,7 @@ export function createHandleContext(options) {
             throw busyError(kind);
         });
     }
-    return { create, read, update, commit, discard };
+    return { create, createRecord, read, update, commit, discard };
 }
 /**
  * Handle context for unit tests: memory state, a fixed connection, and an

package/dist/runtime/http-telemetry-binding.d.ts

@@ -0,0 +1,10 @@
+import type { HttpClient } from "../types.js";
+import { type HttpTelemetrySink } from "./http-telemetry.js";
+/** Return whether a host binding has at least one callable declared HTTP method. */
+export declare function isSupportedHttpBinding(value: unknown): value is HttpClient;
+/** Emit the unsupported-shape warning once for the process. */
+export declare function warnUnsupportedHttpBinding(): void;
+/** Route SDK transports inside a host binding through the same attempt collector. */
+export declare function scopedHttpTelemetry(existing: HttpTelemetrySink | undefined): HttpTelemetrySink | undefined;
+/** Observe opaque host calls without changing their arguments, receiver or returned promise. */
+export declare function bindHttpTelemetry(client: HttpClient, sink: HttpTelemetrySink): HttpClient;

package/dist/runtime/http-telemetry-binding.js

@@ -0,0 +1,152 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { httpTelemetryErrorCode } from "./http-telemetry.js";
+import { startHttpTelemetry } from "./http-telemetry-guard.js";
+import { proxyTransportRetryErrorCode, proxyTransportRetryErrorStatus, } from "./proxy-retry-policy.js";
+const scopes = new AsyncLocalStorage();
+const methods = new Set(["request", "get", "post", "put", "delete", "stream", "sse"]);
+const adapters = new WeakMap();
+let unsupportedShapeWarned = false;
+/** Return whether a host binding has at least one callable declared HTTP method. */
+export function isSupportedHttpBinding(value) {
+    if ((typeof value !== "object" && typeof value !== "function") || value === null)
+        return false;
+    for (const method of methods) {
+        try {
+            if (typeof Reflect.get(value, method) === "function")
+                return true;
+        }
+        catch {
+            // A hostile property getter is not a usable binding.
+        }
+    }
+    return false;
+}
+/** Emit the unsupported-shape warning once for the process. */
+export function warnUnsupportedHttpBinding() {
+    if (unsupportedShapeWarned)
+        return;
+    unsupportedShapeWarned = true;
+    try {
+        console.warn("[apifuse] http telemetry not attached; reason=unsupported_binding_shape");
+    }
+    catch {
+        // Warning output is diagnostic only and must not affect request handling.
+    }
+}
+/** Route SDK transports inside a host binding through the same attempt collector. */
+export function scopedHttpTelemetry(existing) {
+    const scope = scopes.getStore();
+    if (!scope)
+        return existing;
+    scope.nativeObserved = true;
+    if (!existing || existing === scope.sink)
+        return scope.sink;
+    return {
+        markTelemetryFailed: () => scope.sink.markTelemetryFailed?.(),
+        startRequest(options) {
+            const request = startHttpTelemetry(scope.sink, options.retryPreset);
+            const observer = startHttpTelemetry({
+                startRequest: (options) => existing.startRequest(options),
+                markTelemetryFailed() {
+                    scope.sink.markTelemetryFailed?.();
+                    existing.markTelemetryFailed?.();
+                },
+            }, options.retryPreset);
+            return {
+                recordAttempt(event) {
+                    request.recordAttempt(event);
+                    observer.recordAttempt(event);
+                },
+                finish(ms) {
+                    request.finish(ms);
+                    observer.finish(ms);
+                },
+                toTenantRetryPayload() {
+                    observer.toTenantRetryPayload();
+                    return request.toTenantRetryPayload();
+                },
+            };
+        },
+    };
+}
+/** Observe opaque host calls without changing their arguments, receiver or returned promise. */
+export function bindHttpTelemetry(client, sink) {
+    if ((typeof client === "object" && client !== null) || typeof client === "function") {
+        const existing = adapters.get(client);
+        if (existing) {
+            existing.sink = sink;
+            return existing.adapter;
+        }
+    }
+    const wrappers = new Map();
+    // An inheriting target also supports hosts whose own methods are frozen.
+    const adapter = new Proxy(Object.create(client), {
+        get(_target, property) {
+            const original = Reflect.get(client, property, client);
+            if (typeof property !== "string" || !methods.has(property) || typeof original !== "function")
+                return original;
+            const cached = wrappers.get(property);
+            if (cached?.original === original)
+                return cached.wrapped;
+            const wrapped = function (...args) {
+                // Direct calls keep the host receiver; explicit and unbound receivers pass through.
+                const receiver = this === adapter ? client : this;
+                const scope = { sink: state.sink, nativeObserved: false };
+                const started = performance.now();
+                const settled = (result, failed) => {
+                    if (scope.nativeObserved)
+                        return;
+                    const request = startHttpTelemetry(state.sink, undefined);
+                    request.observe(() => {
+                        const status = failed
+                            ? proxyTransportRetryErrorStatus(result)
+                            : result &&
+                                typeof result === "object" &&
+                                "status" in result &&
+                                typeof result.status === "number"
+                                ? result.status
+                                : undefined;
+                        request.recordAttempt({
+                            ms: performance.now() - started,
+                            proxyUsed: false,
+                            ...(status === undefined ? {} : { status }),
+                            ...(failed
+                                ? { e: httpTelemetryErrorCode(proxyTransportRetryErrorCode(result)) }
+                                : {}),
+                        });
+                    });
+                    request.finish(performance.now() - started);
+                };
+                return scopes.run(scope, () => {
+                    let result;
+                    try {
+                        result = Reflect.apply(original, receiver, args);
+                    }
+                    catch (error) {
+                        settled(error, true);
+                        throw error;
+                    }
+                    try {
+                        if (result instanceof Promise) {
+                            void Promise.prototype.then.call(result, (value) => settled(value, false), (error) => settled(error, true));
+                        }
+                        else
+                            settled(result, false);
+                    }
+                    catch (error) {
+                        // Promise subclasses may throw while a telemetry continuation is attached.
+                        startHttpTelemetry(state.sink, undefined).observe(() => {
+                            throw error;
+                        });
+                    }
+                    return result;
+                });
+            };
+            wrappers.set(property, { original, wrapped });
+            return wrapped;
+        },
+    });
+    const state = { sink, adapter };
+    adapters.set(adapter, state);
+    return adapter;
+}

package/dist/runtime/http-telemetry-guard.d.ts

@@ -0,0 +1,6 @@
+import type { HttpRetrySummary } from "../types.js";
+import { type HttpTelemetryRequestSink, type HttpTelemetrySink } from "./http-telemetry.js";
+/** Keep all public observers, including property access, outside transport failures. */
+export declare function startHttpTelemetry(sink: HttpTelemetrySink | undefined, retryPreset: HttpRetrySummary["preset"]): HttpTelemetryRequestSink & {
+    observe(callback: () => void): void;
+};

package/dist/runtime/http-telemetry-guard.js

@@ -0,0 +1,150 @@
+import { HttpTelemetryCollector, } from "./http-telemetry.js";
+const intrinsicPromiseThen = Promise.prototype.then;
+const ignoreObserverResult = () => { };
+/** Attach handlers only through the Promise intrinsic; never invoke a host thenable. */
+function absorbObserverPromise(value) {
+    let constructorDescriptor;
+    let shadowed = false;
+    try {
+        constructorDescriptor = Object.getOwnPropertyDescriptor(value, "constructor");
+        // Even the intrinsic `then` consults Symbol.species. An undefined constructor
+        // selects its intrinsic Promise without reading a subclass's species getter.
+        Object.defineProperty(value, "constructor", {
+            value: undefined,
+            configurable: constructorDescriptor?.configurable ?? true,
+        });
+        shadowed = true;
+    }
+    catch {
+        // Non-extensible ordinary promises can still accept intrinsic handlers.
+    }
+    try {
+        void intrinsicPromiseThen.call(value, ignoreObserverResult, ignoreObserverResult);
+    }
+    catch {
+        // A non-Promise thenable has no intrinsic rejection to absorb. Do not run it.
+    }
+    finally {
+        if (shadowed) {
+            try {
+                if (constructorDescriptor) {
+                    Object.defineProperty(value, "constructor", constructorDescriptor);
+                }
+                else {
+                    Reflect.deleteProperty(value, "constructor");
+                }
+            }
+            catch {
+                // Host object traps are also observer failures.
+            }
+        }
+    }
+}
+function isAsyncObserverReturn(value) {
+    if (!value || (typeof value !== "object" && typeof value !== "function"))
+        return false;
+    try {
+        if (!("then" in value) || typeof value.then !== "function")
+            return false;
+    }
+    catch {
+        // A rejected Promise can itself have a throwing `then` getter. Still absorb it.
+    }
+    absorbObserverPromise(value);
+    return true;
+}
+/** Keep all public observers, including property access, outside transport failures. */
+export function startHttpTelemetry(sink, retryPreset) {
+    let failed = false;
+    const fail = () => {
+        if (failed)
+            return;
+        failed = true;
+        try {
+            isAsyncObserverReturn(sink?.markTelemetryFailed?.());
+        }
+        catch {
+            // The failure reporter is itself an observer. Never recurse.
+        }
+    };
+    const observe = (callback) => {
+        try {
+            const result = callback();
+            if (isAsyncObserverReturn(result)) {
+                // The observer API is synchronous. Absorb invalid asynchronous returns too.
+                fail();
+                return undefined;
+            }
+            return result;
+        }
+        catch {
+            fail();
+            return undefined;
+        }
+    };
+    const result = observe(() => (sink ?? new HttpTelemetryCollector()).startRequest({ retryPreset }));
+    const request = observe(() => {
+        if (!result ||
+            typeof result.recordAttempt !== "function" ||
+            typeof result.finish !== "function" ||
+            typeof result.toTenantRetryPayload !== "function") {
+            fail();
+            return undefined;
+        }
+        return result;
+    });
+    return {
+        observe,
+        recordAttempt: (event) => {
+            observe(() => request?.recordAttempt(event));
+        },
+        finish: (ms) => {
+            observe(() => request?.finish(ms));
+        },
+        toTenantRetryPayload: () => {
+            if (failed)
+                return undefined;
+            return observe(() => {
+                const value = observe(() => request?.toTenantRetryPayload());
+                if (value === undefined)
+                    return undefined;
+                // Copy only validated primitive fields; never pass observer-owned objects on.
+                const { attempts, retries, preset, transport, lastErrorCode, lastStatus } = value;
+                if (!Number.isSafeInteger(attempts) ||
+                    attempts < 2 ||
+                    !Number.isSafeInteger(retries) ||
+                    (retries !== attempts - 1 &&
+                        !(attempts === Number.MAX_SAFE_INTEGER && retries === Number.MAX_SAFE_INTEGER)) ||
+                    transport !== "native" ||
+                    (preset !== undefined &&
+                        ![
+                            "off",
+                            "transport_transient",
+                            "safe_read",
+                            "aggressive_read",
+                            "rate_limit_aware",
+                        ].includes(preset)) ||
+                    (lastErrorCode !== undefined &&
+                        ![
+                            "transport_network_error",
+                            "transport_timeout",
+                            "transport_cancelled",
+                            "upstream_http_error",
+                            "other",
+                        ].includes(lastErrorCode)) ||
+                    (lastStatus !== undefined && (!Number.isSafeInteger(lastStatus) || lastStatus < 0))) {
+                    fail();
+                    return undefined;
+                }
+                return {
+                    attempts,
+                    retries,
+                    ...(preset === undefined ? {} : { preset }),
+                    transport,
+                    ...(lastErrorCode === undefined ? {} : { lastErrorCode }),
+                    ...(lastStatus === undefined ? {} : { lastStatus }),
+                };
+            });
+        },
+    };
+}

package/dist/runtime/http-telemetry.d.ts

@@ -0,0 +1,104 @@
+import type { HttpRetrySummary } from "../types.js";
+import { type ClosedEnum, type TelemetryContributor, type TenantNeutral } from "./request-telemetry.js";
+/** The same closed vocabulary used by tenant-visible meta.retry. */
+export type HttpTelemetryErrorCode = "transport_network_error" | "transport_timeout" | "transport_cancelled" | "upstream_http_error" | "other";
+export declare function httpTelemetryErrorCode(code: string | undefined): HttpTelemetryErrorCode;
+export type HttpTelemetryRetryPayload = {
+    attempts: number;
+    retries: number;
+    preset?: ClosedEnum<NonNullable<HttpRetrySummary["preset"]>>;
+    transport: ClosedEnum<HttpRetrySummary["transport"]>;
+    lastErrorCode?: ClosedEnum<HttpTelemetryErrorCode>;
+    /** Last failed attempt's status, preserving the existing meta.retry contract. */
+    lastStatus?: number;
+};
+export type HttpAttemptTelemetryEvent = {
+    ms: number;
+    proxyUsed: boolean;
+    status?: number;
+    e?: HttpTelemetryErrorCode;
+    /** A returned status-retry outcome, rather than a thrown transport error. */
+    statusRetry?: boolean;
+    /** Operator-only error text. Never projected into the header or tenant metadata. */
+    diagnostics?: {
+        name: string;
+        message: string;
+        cause?: {
+            name: string;
+            message: string;
+        };
+    };
+};
+export interface HttpTelemetryRequestSink {
+    recordAttempt(event: HttpAttemptTelemetryEvent): void;
+    /** Called once when the logical HTTP call settles; includes backoff time. */
+    finish(ms: number): void;
+    toTenantRetryPayload(): TenantNeutral<HttpTelemetryRetryPayload> | undefined;
+}
+export interface HttpTelemetrySink {
+    /** Optional, best-effort failure marker; called at most once per logical request. */
+    markTelemetryFailed?(): void;
+    /** Each call gets independent retry state, including concurrent calls. */
+    startRequest(options: {
+        retryPreset?: HttpRetrySummary["preset"];
+    }): HttpTelemetryRequestSink;
+}
+export type HttpAttemptSample = {
+    n: number;
+    ms: number;
+    status?: number;
+    e?: HttpTelemetryErrorCode;
+    diagnostics?: HttpAttemptTelemetryEvent["diagnostics"];
+};
+export type HttpTelemetryLogPayload = {
+    /** Observer failure; operator-only and never projected into the header. */
+    telemetryFailed?: true;
+    attempts: number;
+    retries: number;
+    timeouts: number;
+    proxyUsed: boolean;
+    /** Most recently completed attempt's status, including successful statuses. */
+    lastStatus?: number;
+    retryPreset?: HttpRetrySummary["preset"];
+    transport: HttpRetrySummary["transport"];
+    lastErrorCode?: HttpTelemetryErrorCode;
+    attemptSamples: HttpAttemptSample[];
+    dropped: number;
+    /** Sum of logical call durations, including retry delays. */
+    ms: number;
+    /** Most recent successful retried call; also the source of tenant meta.retry. */
+    retry?: HttpTelemetryRetryPayload;
+};
+export type HttpTelemetryHeaderPayload = {
+    attempts: number;
+    retries: number;
+    timeouts: number;
+    proxyUsed: boolean;
+    lastStatus?: number;
+    retryPreset?: ClosedEnum<NonNullable<HttpRetrySummary["preset"]>>;
+    transport: ClosedEnum<HttpRetrySummary["transport"]>;
+    lastErrorCode?: ClosedEnum<HttpTelemetryErrorCode>;
+    attemptSamples: {
+        n: number;
+        ms: number;
+        status?: number;
+        e?: ClosedEnum<HttpTelemetryErrorCode>;
+    }[];
+    dropped: number;
+    ms: number;
+    retry?: HttpTelemetryRetryPayload;
+};
+export declare class HttpTelemetryCollector implements HttpTelemetrySink, TelemetryContributor<HttpTelemetryLogPayload, HttpTelemetryHeaderPayload> {
+    #private;
+    readonly key: "http";
+    constructor(options?: {
+        redact?: (text: string) => string;
+    });
+    markTelemetryFailed(): void;
+    startRequest(options: {
+        retryPreset?: HttpRetrySummary["preset"];
+    }): HttpTelemetryRequestSink;
+    toTenantRetryPayload(): TenantNeutral<HttpTelemetryRetryPayload> | undefined;
+    toLogPayload(): HttpTelemetryLogPayload | undefined;
+    toHeaderPayload(log: HttpTelemetryLogPayload): HttpTelemetryHeaderPayload;
+}