@private.me/xbind 3.0.1 → 3.0.2

package/dist-standalone/trace-spans.js

@@ -1 +1,488 @@
-import{TraceContext,generateSpanId}from"./trace-context.js";export var SpanStatusCode;!function(t){t[t.OK=0]="OK",t[t.ERROR=1]="ERROR",t[t.UNSET=2]="UNSET"}(SpanStatusCode||(SpanStatusCode={}));export var SpanKind;!function(t){t[t.INTERNAL=0]="INTERNAL",t[t.SERVER=1]="SERVER",t[t.CLIENT=2]="CLIENT",t[t.PRODUCER=3]="PRODUCER",t[t.CONSUMER=4]="CONSUMER"}(SpanKind||(SpanKind={}));export class TraceSpan{spanId;traceContext;name;kind;parentSpanId;startTime;endTime;status;attributes;events;ended;constructor(t,e,n={}){this.spanId=generateSpanId(),this.traceContext=e,this.name=t,this.kind=n.kind??SpanKind.INTERNAL,this.parentSpanId=n.parentSpanId,this.startTime=Date.now(),this.status={code:SpanStatusCode.UNSET},this.attributes=n.attributes??{},this.events=[],this.ended=!1}setAttribute(t,e){if(this.ended)throw new Error("Cannot set attribute on ended span");return this.attributes[t]=e,this}setAttributes(t){if(this.ended)throw new Error("Cannot set attributes on ended span");return Object.assign(this.attributes,t),this}addEvent(t,e){if(this.ended)throw new Error("Cannot add event to ended span");return this.events.push({name:t,timestamp:Date.now(),attributes:e}),this}setStatus(t,e){if(this.ended)throw new Error("Cannot set status on ended span");return this.status={code:t,message:e},this}recordException(t){if(this.ended)throw new Error("Cannot record exception on ended span");this.setStatus(SpanStatusCode.ERROR);const e={};return t instanceof Error?(e["exception.type"]=t.name,e["exception.message"]=t.message,t.stack&&(e["exception.stacktrace"]=t.stack)):e["exception.message"]=String(t),this.addEvent("exception",e),this}end(t){this.ended||(this.endTime=t??Date.now(),this.ended=!0,this.status.code===SpanStatusCode.UNSET&&(this.status={code:SpanStatusCode.OK}))}isEnded(){return this.ended}getDuration(){return this.ended&&this.endTime?this.endTime-this.startTime:null}toData(){if(!this.ended||!this.endTime)throw new Error("Cannot export data from active span. Call end() first.");return{spanId:this.spanId,traceId:this.traceContext.traceId,parentSpanId:this.parentSpanId,name:this.name,kind:this.kind,startTime:this.startTime,endTime:this.endTime,duration:this.endTime-this.startTime,status:{...this.status},attributes:{...this.attributes},events:this.events.map(t=>({name:t.name,timestamp:t.timestamp,attributes:t.attributes?{...t.attributes}:void 0}))}}createChild(t,e={}){return new TraceSpan(t,this.traceContext,{...e,parentSpanId:this.spanId})}}export class SpanRecorder{activeSpans;completedSpans;maxSpans;rootContext;constructor(t={}){this.activeSpans=new Map,this.completedSpans=[],this.maxSpans=t.maxSpans??1e3,this.rootContext=t.traceContext}startSpan(t,e={}){const n=e.traceContext??e.parentSpan?.traceContext??this.rootContext??TraceContext.create(),a=new TraceSpan(t,n,{kind:e.kind,attributes:e.attributes,parentSpanId:e.parentSpan?.spanId});this.activeSpans.set(a.spanId,a);const s=setTimeout(()=>{a.isEnded()||(a.setStatus(SpanStatusCode.ERROR,"Span not ended (auto-ended by recorder)"),this.endSpan(a))},6e4),r=a.end.bind(a);return a.end=t=>{clearTimeout(s),r(t),this.endSpan(a)},a}endSpan(t){t.isEnded()||t.end(),this.activeSpans.delete(t.spanId);const e=t.toData();this.completedSpans.push(e),this.completedSpans.length>this.maxSpans&&this.completedSpans.shift()}getCompletedSpans(){return[...this.completedSpans]}getActiveSpans(){return Array.from(this.activeSpans.values())}clearCompletedSpans(){this.completedSpans=[]}getSpanCount(){return{active:this.activeSpans.size,completed:this.completedSpans.length}}findSpansByTraceId(t){return this.completedSpans.filter(e=>e.traceId===t)}buildTraceTree(t){const e=this.findSpansByTraceId(t);if(0===e.length)return null;const n=e.find(t=>!t.parentSpanId);return n?buildSpanTreeNode(n,e):null}}function buildSpanTreeNode(t,e){const n=e.filter(e=>e.parentSpanId===t.spanId).map(t=>buildSpanTreeNode(t,e));return{span:t,children:n}}export async function measureAsync(t,e,n,a){const s=t.startSpan(e,a);try{const t=await n();return s.setStatus(SpanStatusCode.OK),t}catch(t){throw s.recordException(t),t}finally{s.end()}}export function measureSync(t,e,n,a){const s=t.startSpan(e,a);try{const t=n();return s.setStatus(SpanStatusCode.OK),t}catch(t){throw s.recordException(t),t}finally{s.end()}}
+/**
+ * @module trace-spans
+ * Distributed tracing spans with parent-child relationships
+ *
+ * Provides span tracking for distributed tracing with automatic timing,
+ * attribute collection, and integration with W3C Trace Context.
+ *
+ * Performance target: <1ms overhead per operation
+ *
+ * Usage:
+ * ```typescript
+ * import { TraceSpan, SpanRecorder } from '@private.me/xbind';
+ *
+ * // Create a span recorder
+ * const recorder = new SpanRecorder();
+ *
+ * // Start a span
+ * const span = recorder.startSpan('operation-name', { attr: 'value' });
+ *
+ * // Do work...
+ *
+ * // End the span
+ * span.end();
+ *
+ * // Get completed spans
+ * const spans = recorder.getCompletedSpans();
+ * ```
+ */
+import { TraceContext, generateSpanId } from './trace-context.js';
+/**
+ * Span status codes (aligned with OpenTelemetry)
+ */
+export var SpanStatusCode;
+(function (SpanStatusCode) {
+    /** Operation completed successfully */
+    SpanStatusCode[SpanStatusCode["OK"] = 0] = "OK";
+    /** Operation encountered an error */
+    SpanStatusCode[SpanStatusCode["ERROR"] = 1] = "ERROR";
+    /** Status is unset (default) */
+    SpanStatusCode[SpanStatusCode["UNSET"] = 2] = "UNSET";
+})(SpanStatusCode || (SpanStatusCode = {}));
+/**
+ * Span kind (aligned with OpenTelemetry)
+ */
+export var SpanKind;
+(function (SpanKind) {
+    /** Internal span (default) */
+    SpanKind[SpanKind["INTERNAL"] = 0] = "INTERNAL";
+    /** Server span (handling incoming request) */
+    SpanKind[SpanKind["SERVER"] = 1] = "SERVER";
+    /** Client span (outgoing request) */
+    SpanKind[SpanKind["CLIENT"] = 2] = "CLIENT";
+    /** Producer span (message queue producer) */
+    SpanKind[SpanKind["PRODUCER"] = 3] = "PRODUCER";
+    /** Consumer span (message queue consumer) */
+    SpanKind[SpanKind["CONSUMER"] = 4] = "CONSUMER";
+})(SpanKind || (SpanKind = {}));
+/**
+ * Trace span for distributed tracing
+ *
+ * Represents a single unit of work in a distributed trace with automatic timing.
+ */
+export class TraceSpan {
+    /** Span ID (unique within trace) */
+    spanId;
+    /** Trace context */
+    traceContext;
+    /** Span name */
+    name;
+    /** Span kind */
+    kind;
+    /** Parent span ID */
+    parentSpanId;
+    /** Start timestamp (milliseconds since epoch) */
+    startTime;
+    /** End timestamp (milliseconds since epoch, undefined if not ended) */
+    endTime;
+    /** Span status */
+    status;
+    /** Span attributes */
+    attributes;
+    /** Span events */
+    events;
+    /** Whether span has ended */
+    ended;
+    /**
+     * Create a trace span
+     *
+     * @param name - Span name
+     * @param traceContext - Trace context
+     * @param options - Span options
+     */
+    constructor(name, traceContext, options = {}) {
+        this.spanId = generateSpanId();
+        this.traceContext = traceContext;
+        this.name = name;
+        this.kind = options.kind ?? SpanKind.INTERNAL;
+        this.parentSpanId = options.parentSpanId;
+        this.startTime = Date.now();
+        this.status = { code: SpanStatusCode.UNSET };
+        this.attributes = options.attributes ?? {};
+        this.events = [];
+        this.ended = false;
+    }
+    /**
+     * Set span attribute
+     *
+     * @param key - Attribute key
+     * @param value - Attribute value
+     * @returns This span (for chaining)
+     */
+    setAttribute(key, value) {
+        if (this.ended) {
+            throw new Error('Cannot set attribute on ended span');
+        }
+        this.attributes[key] = value;
+        return this;
+    }
+    /**
+     * Set multiple span attributes
+     *
+     * @param attributes - Attributes to set
+     * @returns This span (for chaining)
+     */
+    setAttributes(attributes) {
+        if (this.ended) {
+            throw new Error('Cannot set attributes on ended span');
+        }
+        Object.assign(this.attributes, attributes);
+        return this;
+    }
+    /**
+     * Add an event to the span
+     *
+     * Events are timestamped log entries within a span.
+     *
+     * @param name - Event name
+     * @param attributes - Optional event attributes
+     * @returns This span (for chaining)
+     */
+    addEvent(name, attributes) {
+        if (this.ended) {
+            throw new Error('Cannot add event to ended span');
+        }
+        this.events.push({
+            name,
+            timestamp: Date.now(),
+            attributes,
+        });
+        return this;
+    }
+    /**
+     * Set span status
+     *
+     * @param code - Status code
+     * @param message - Optional status message
+     * @returns This span (for chaining)
+     */
+    setStatus(code, message) {
+        if (this.ended) {
+            throw new Error('Cannot set status on ended span');
+        }
+        this.status = { code, message };
+        return this;
+    }
+    /**
+     * Record an exception in the span
+     *
+     * Automatically sets status to ERROR and adds exception event.
+     *
+     * @param error - Error to record
+     * @returns This span (for chaining)
+     */
+    recordException(error) {
+        if (this.ended) {
+            throw new Error('Cannot record exception on ended span');
+        }
+        this.setStatus(SpanStatusCode.ERROR);
+        const attributes = {};
+        if (error instanceof Error) {
+            attributes['exception.type'] = error.name;
+            attributes['exception.message'] = error.message;
+            if (error.stack) {
+                attributes['exception.stacktrace'] = error.stack;
+            }
+        }
+        else {
+            attributes['exception.message'] = String(error);
+        }
+        this.addEvent('exception', attributes);
+        return this;
+    }
+    /**
+     * End the span
+     *
+     * Records the end timestamp and marks the span as complete.
+     * If status is UNSET, automatically sets to OK.
+     *
+     * @param endTime - Optional end timestamp (defaults to now)
+     */
+    end(endTime) {
+        if (this.ended) {
+            return; // Idempotent
+        }
+        this.endTime = endTime ?? Date.now();
+        this.ended = true;
+        // Auto-set status to OK if unset
+        if (this.status.code === SpanStatusCode.UNSET) {
+            this.status = { code: SpanStatusCode.OK };
+        }
+    }
+    /**
+     * Check if span has ended
+     *
+     * @returns True if ended
+     */
+    isEnded() {
+        return this.ended;
+    }
+    /**
+     * Get span duration in milliseconds
+     *
+     * @returns Duration or null if not ended
+     */
+    getDuration() {
+        if (!this.ended || !this.endTime)
+            return null;
+        return this.endTime - this.startTime;
+    }
+    /**
+     * Export span data
+     *
+     * @returns Span data (throws if span not ended)
+     */
+    toData() {
+        if (!this.ended || !this.endTime) {
+            throw new Error('Cannot export data from active span. Call end() first.');
+        }
+        return {
+            spanId: this.spanId,
+            traceId: this.traceContext.traceId,
+            parentSpanId: this.parentSpanId,
+            name: this.name,
+            kind: this.kind,
+            startTime: this.startTime,
+            endTime: this.endTime,
+            duration: this.endTime - this.startTime,
+            status: { ...this.status },
+            attributes: { ...this.attributes },
+            events: this.events.map((e) => ({
+                name: e.name,
+                timestamp: e.timestamp,
+                attributes: e.attributes ? { ...e.attributes } : undefined,
+            })),
+        };
+    }
+    /**
+     * Create a child span
+     *
+     * The child span will have the same trace ID but a new span ID.
+     *
+     * @param name - Child span name
+     * @param options - Span options
+     * @returns New child span
+     */
+    createChild(name, options = {}) {
+        return new TraceSpan(name, this.traceContext, {
+            ...options,
+            parentSpanId: this.spanId,
+        });
+    }
+}
+/**
+ * Span recorder for collecting completed spans
+ *
+ * Manages span lifecycle and provides access to completed span data.
+ */
+export class SpanRecorder {
+    /** Active spans (not yet ended) */
+    activeSpans;
+    /** Completed spans */
+    completedSpans;
+    /** Maximum number of completed spans to keep (prevent memory leak) */
+    maxSpans;
+    /** Trace context for root spans */
+    rootContext;
+    /**
+     * Create a span recorder
+     *
+     * @param options - Recorder options
+     */
+    constructor(options = {}) {
+        this.activeSpans = new Map();
+        this.completedSpans = [];
+        this.maxSpans = options.maxSpans ?? 1000;
+        this.rootContext = options.traceContext;
+    }
+    /**
+     * Start a new span
+     *
+     * @param name - Span name
+     * @param options - Span options
+     * @returns New span
+     */
+    startSpan(name, options = {}) {
+        const context = options.traceContext ??
+            options.parentSpan?.traceContext ??
+            this.rootContext ??
+            TraceContext.create();
+        const span = new TraceSpan(name, context, {
+            kind: options.kind,
+            attributes: options.attributes,
+            parentSpanId: options.parentSpan?.spanId,
+        });
+        this.activeSpans.set(span.spanId, span);
+        // Auto-end on next tick if forgotten (safety measure)
+        // This prevents memory leaks from forgotten spans
+        const timeout = setTimeout(() => {
+            if (!span.isEnded()) {
+                span.setStatus(SpanStatusCode.ERROR, 'Span not ended (auto-ended by recorder)');
+                this.endSpan(span);
+            }
+        }, 60000); // 60 second timeout
+        // Clear timeout if span ends normally
+        const originalEnd = span.end.bind(span);
+        span.end = (endTime) => {
+            clearTimeout(timeout);
+            originalEnd(endTime);
+            this.endSpan(span);
+        };
+        return span;
+    }
+    /**
+     * End a span and record its data
+     *
+     * @param span - Span to end
+     */
+    endSpan(span) {
+        if (!span.isEnded()) {
+            span.end();
+        }
+        // Remove from active spans
+        this.activeSpans.delete(span.spanId);
+        // Add to completed spans
+        const data = span.toData();
+        this.completedSpans.push(data);
+        // Enforce max spans limit (FIFO)
+        if (this.completedSpans.length > this.maxSpans) {
+            this.completedSpans.shift();
+        }
+    }
+    /**
+     * Get all completed spans
+     *
+     * @returns Array of completed span data
+     */
+    getCompletedSpans() {
+        return [...this.completedSpans];
+    }
+    /**
+     * Get active spans
+     *
+     * @returns Array of active spans
+     */
+    getActiveSpans() {
+        return Array.from(this.activeSpans.values());
+    }
+    /**
+     * Clear all completed spans
+     */
+    clearCompletedSpans() {
+        this.completedSpans = [];
+    }
+    /**
+     * Get span count
+     *
+     * @returns Object with active and completed span counts
+     */
+    getSpanCount() {
+        return {
+            active: this.activeSpans.size,
+            completed: this.completedSpans.length,
+        };
+    }
+    /**
+     * Find completed spans by trace ID
+     *
+     * @param traceId - Trace ID to search for
+     * @returns Array of matching spans
+     */
+    findSpansByTraceId(traceId) {
+        return this.completedSpans.filter((span) => span.traceId === traceId);
+    }
+    /**
+     * Build trace tree from completed spans
+     *
+     * Groups spans by trace ID and builds parent-child relationships.
+     *
+     * @param traceId - Trace ID to build tree for
+     * @returns Tree structure
+     */
+    buildTraceTree(traceId) {
+        const spans = this.findSpansByTraceId(traceId);
+        if (spans.length === 0)
+            return null;
+        // Find root span (no parent)
+        const root = spans.find((s) => !s.parentSpanId);
+        if (!root)
+            return null;
+        // Build tree recursively
+        return buildSpanTreeNode(root, spans);
+    }
+}
+/**
+ * Build span tree node recursively
+ *
+ * @param span - Current span
+ * @param allSpans - All spans in trace
+ * @returns Tree node
+ */
+function buildSpanTreeNode(span, allSpans) {
+    const children = allSpans
+        .filter((s) => s.parentSpanId === span.spanId)
+        .map((child) => buildSpanTreeNode(child, allSpans));
+    return { span, children };
+}
+/**
+ * Helper function to measure async operation with automatic span tracking
+ *
+ * @param recorder - Span recorder
+ * @param name - Span name
+ * @param fn - Async function to measure
+ * @param options - Span options
+ * @returns Result of async function
+ *
+ * @example
+ * ```typescript
+ * const result = await measureAsync(recorder, 'database-query', async () => {
+ *   return await db.query('SELECT * FROM users');
+ * });
+ * ```
+ */
+export async function measureAsync(recorder, name, fn, options) {
+    const span = recorder.startSpan(name, options);
+    try {
+        const result = await fn();
+        span.setStatus(SpanStatusCode.OK);
+        return result;
+    }
+    catch (error) {
+        span.recordException(error);
+        throw error;
+    }
+    finally {
+        span.end();
+    }
+}
+/**
+ * Helper function to measure sync operation with automatic span tracking
+ *
+ * @param recorder - Span recorder
+ * @param name - Span name
+ * @param fn - Sync function to measure
+ * @param options - Span options
+ * @returns Result of sync function
+ *
+ * @example
+ * ```typescript
+ * const result = measureSync(recorder, 'encryption', () => {
+ *   return encrypt(data, key);
+ * });
+ * ```
+ */
+export function measureSync(recorder, name, fn, options) {
+    const span = recorder.startSpan(name, options);
+    try {
+        const result = fn();
+        span.setStatus(SpanStatusCode.OK);
+        return result;
+    }
+    catch (error) {
+        span.recordException(error);
+        throw error;
+    }
+    finally {
+        span.end();
+    }
+}

package/dist-standalone/transport.js

@@ -1 +1,59 @@
-import{ok,err}from"./_deps/shared/index.js";export class HttpsTransportAdapter{baseUrl;timeoutMs;fetchFn;handlers=[];constructor(t){this.baseUrl=t.baseUrl.replace(/\/$/,""),this.timeoutMs=t.timeoutMs??1e4,this.fetchFn=t.fetch??globalThis.fetch.bind(globalThis)}async send(t,e){const s=`${this.baseUrl}/deliver/${encodeURIComponent(e)}`;try{const e=new AbortController,r=setTimeout(()=>e.abort(),this.timeoutMs),o=await this.fetchFn(s,{method:"POST",headers:{"Content-Type":"application/json"},body:JSON.stringify(t),signal:e.signal});return clearTimeout(r),o.ok?ok(void 0):err(404===o.status?"RECIPIENT_UNREACHABLE":"SEND_FAILED")}catch(t){return t instanceof DOMException&&"AbortError"===t.name?err("TIMEOUT"):err("NETWORK_ERROR")}}onReceive(t){this.handlers.push(t)}dispatch(t){for(const e of this.handlers)e(t)}dispose(){this.handlers=[]}}
+import { ok, err } from"./_deps/shared/index.js";
+/**
+ * HTTPS transport adapter — sends envelopes as JSON POST requests.
+ *
+ * Recipient URL resolved as: baseUrl/deliver/{recipientDid}
+ * This is the SDK's default transport for server-to-server delivery.
+ */
+export class HttpsTransportAdapter {
+    baseUrl;
+    timeoutMs;
+    fetchFn;
+    handlers = [];
+    constructor(opts) {
+        this.baseUrl = opts.baseUrl.replace(/\/$/, '');
+        this.timeoutMs = opts.timeoutMs ?? 10_000;
+        this.fetchFn = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    }
+    async send(envelope, recipientDid) {
+        const url = `${this.baseUrl}/deliver/${encodeURIComponent(recipientDid)}`;
+        try {
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+            const response = await this.fetchFn(url, {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify(envelope),
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            if (!response.ok) {
+                return err(response.status === 404
+                    ? 'RECIPIENT_UNREACHABLE'
+                    : 'SEND_FAILED');
+            }
+            return ok(undefined);
+        }
+        catch (e) {
+            if (e instanceof DOMException && e.name === 'AbortError') {
+                return err('TIMEOUT');
+            }
+            return err('NETWORK_ERROR');
+        }
+    }
+    onReceive(handler) {
+        this.handlers.push(handler);
+    }
+    /**
+     * Dispatch a received envelope to all handlers.
+     * Called by the server when an incoming POST is received.
+     */
+    dispatch(envelope) {
+        for (const handler of this.handlers) {
+            handler(envelope);
+        }
+    }
+    dispose() {
+        this.handlers = [];
+    }
+}