@parsrun/service 0.1.0

package/dist/server-DFE8n2Sx.d.ts

@@ -0,0 +1,106 @@
+import { Logger } from '@parsrun/core';
+import { b as ServiceDefinition, m as TraceContext, f as RpcRequest, g as RpcResponse } from './types-n4LLSPQU.js';
+
+/**
+ * @parsrun/service - RPC Server
+ * Server for handling RPC requests
+ */
+
+/**
+ * RPC handler context
+ */
+interface RpcHandlerContext {
+    /** Request ID */
+    requestId: string;
+    /** Service name */
+    service: string;
+    /** Method name */
+    method: string;
+    /** Method type */
+    type: "query" | "mutation";
+    /** Request metadata */
+    metadata: Record<string, unknown>;
+    /** Trace context */
+    traceContext?: TraceContext;
+    /** Logger */
+    logger: Logger;
+}
+/**
+ * RPC handler function
+ */
+type RpcHandler<TInput = unknown, TOutput = unknown> = (input: TInput, context: RpcHandlerContext) => Promise<TOutput>;
+/**
+ * RPC handlers record
+ */
+type RpcHandlers = {
+    queries?: Record<string, RpcHandler>;
+    mutations?: Record<string, RpcHandler>;
+};
+interface RpcServerOptions {
+    /** Service definition */
+    definition: ServiceDefinition;
+    /** RPC handlers */
+    handlers: RpcHandlers;
+    /** Logger */
+    logger?: Logger;
+    /** Default timeout in ms */
+    defaultTimeout?: number;
+    /** Middleware */
+    middleware?: RpcMiddleware[];
+}
+/**
+ * RPC middleware function
+ */
+type RpcMiddleware = (request: RpcRequest, context: RpcHandlerContext, next: () => Promise<unknown>) => Promise<unknown>;
+/**
+ * RPC Server for handling incoming requests
+ */
+declare class RpcServer {
+    private readonly definition;
+    private readonly handlers;
+    private readonly logger;
+    private readonly defaultTimeout;
+    private readonly middleware;
+    constructor(options: RpcServerOptions);
+    /**
+     * Handle an RPC request
+     */
+    handle<TInput, TOutput>(request: RpcRequest<TInput>): Promise<RpcResponse<TOutput>>;
+    /**
+     * Get handler for a method
+     */
+    private getHandler;
+    /**
+     * Build middleware chain
+     */
+    private buildMiddlewareChain;
+    /**
+     * Get service definition
+     */
+    getDefinition(): ServiceDefinition;
+    /**
+     * Get registered methods
+     */
+    getMethods(): {
+        queries: string[];
+        mutations: string[];
+    };
+}
+/**
+ * Create an RPC server
+ */
+declare function createRpcServer(options: RpcServerOptions): RpcServer;
+/**
+ * Logging middleware
+ */
+declare function loggingMiddleware(): RpcMiddleware;
+/**
+ * Validation middleware (placeholder - integrate with ArkType)
+ */
+declare function validationMiddleware(validators: Record<string, (input: unknown) => unknown>): RpcMiddleware;
+/**
+ * Tenant context middleware
+ */
+declare function tenantMiddleware(): RpcMiddleware;
+
+export { RpcServer as R, type RpcHandler as a, type RpcHandlers as b, createRpcServer as c, type RpcMiddleware as d, type RpcHandlerContext as e, loggingMiddleware as l, tenantMiddleware as t, validationMiddleware as v };

package/dist/tracing/index.d.ts

@@ -0,0 +1,406 @@
+import { m as TraceContext, o as SpanKind, q as SpanAttributeValue, n as Span, p as SpanStatus, T as TracingConfig } from '../types-n4LLSPQU.js';
+import { Logger } from '@parsrun/core';
+
+/**
+ * @parsrun/service - Trace Context
+ * W3C Trace Context implementation
+ */
+
+/**
+ * Generate a trace ID (32 hex characters)
+ */
+declare function generateTraceId(): string;
+/**
+ * Generate a span ID (16 hex characters)
+ */
+declare function generateSpanId(): string;
+/**
+ * Create a new trace context
+ */
+declare function createTraceContext(options?: {
+    traceId?: string;
+    spanId?: string;
+    traceFlags?: number;
+    traceState?: string;
+}): TraceContext;
+/**
+ * Create child trace context (new span in same trace)
+ */
+declare function createChildContext(parent: TraceContext): TraceContext;
+/**
+ * Format trace context as W3C traceparent header
+ *
+ * Format: {version}-{trace-id}-{span-id}-{trace-flags}
+ * Example: 00-0af7651916cd43dd8448eb211c80319c-b7ad6b7169203331-01
+ */
+declare function formatTraceparent(ctx: TraceContext): string;
+/**
+ * Parse W3C traceparent header
+ */
+declare function parseTraceparent(header: string): TraceContext | null;
+/**
+ * Format trace state as W3C tracestate header
+ *
+ * Format: key1=value1,key2=value2
+ */
+declare function formatTracestate(state: Record<string, string>): string;
+/**
+ * Parse W3C tracestate header
+ */
+declare function parseTracestate(header: string): Record<string, string>;
+/**
+ * Async-local-storage-like context manager for tracing
+ * Uses a simple stack for edge compatibility
+ */
+declare class TraceContextManager {
+    private readonly stack;
+    /**
+     * Get current trace context
+     */
+    current(): TraceContext | undefined;
+    /**
+     * Run a function with a trace context
+     */
+    run<T>(ctx: TraceContext, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Run a function with a new child context
+     */
+    runChild<T>(fn: () => Promise<T>): Promise<T>;
+    /**
+     * Create context from incoming request headers
+     */
+    fromHeaders(headers: Headers | Record<string, string>): TraceContext | undefined;
+    /**
+     * Add trace context to outgoing request headers
+     */
+    toHeaders(ctx: TraceContext): Record<string, string>;
+    /**
+     * Check if current context is sampled
+     */
+    isSampled(): boolean;
+    /**
+     * Clear all contexts (for testing)
+     */
+    clear(): void;
+}
+type Sampler = "always" | "never" | {
+    ratio: number;
+};
+/**
+ * Determine if a trace should be sampled
+ */
+declare function shouldSample(sampler: Sampler, traceId?: string): boolean;
+
+/**
+ * @parsrun/service - Spans
+ * Span creation and management
+ */
+
+interface SpanOptions {
+    /** Span name */
+    name: string;
+    /** Span kind */
+    kind?: SpanKind;
+    /** Parent trace context */
+    parent?: TraceContext;
+    /** Initial attributes */
+    attributes?: Record<string, SpanAttributeValue>;
+    /** Start time (default: now) */
+    startTime?: number;
+}
+/**
+ * Create a new span
+ */
+declare function createSpan(options: SpanOptions): Span;
+/**
+ * Span manager for creating and managing spans
+ */
+declare class SpanManager {
+    private readonly spans;
+    /**
+     * Start a new span
+     */
+    startSpan(options: SpanOptions): Span;
+    /**
+     * End a span
+     */
+    endSpan(span: Span, status?: SpanStatus): Span;
+    /**
+     * Set span attribute
+     */
+    setAttribute(span: Span, key: string, value: SpanAttributeValue): void;
+    /**
+     * Set multiple span attributes
+     */
+    setAttributes(span: Span, attributes: Record<string, SpanAttributeValue>): void;
+    /**
+     * Add span event
+     */
+    addEvent(span: Span, name: string, attributes?: Record<string, SpanAttributeValue>): void;
+    /**
+     * Set span status
+     */
+    setStatus(span: Span, status: SpanStatus): void;
+    /**
+     * Record exception on span
+     */
+    recordException(span: Span, error: Error): void;
+    /**
+     * Get span by ID
+     */
+    getSpan(spanId: string): Span | undefined;
+    /**
+     * Get all completed spans and clear
+     */
+    flush(): Span[];
+    /**
+     * Clear all spans
+     */
+    clear(): void;
+}
+/**
+ * Calculate span duration in milliseconds
+ */
+declare function getSpanDuration(span: Span): number | undefined;
+/**
+ * Check if span is completed
+ */
+declare function isSpanCompleted(span: Span): boolean;
+/**
+ * Get span as simplified object (for logging)
+ */
+declare function spanToLogObject(span: Span): Record<string, unknown>;
+/**
+ * Common span attribute keys (OpenTelemetry semantic conventions)
+ */
+declare const SpanAttributes: {
+    readonly HTTP_METHOD: "http.method";
+    readonly HTTP_URL: "http.url";
+    readonly HTTP_STATUS_CODE: "http.status_code";
+    readonly HTTP_REQUEST_CONTENT_LENGTH: "http.request_content_length";
+    readonly HTTP_RESPONSE_CONTENT_LENGTH: "http.response_content_length";
+    readonly RPC_SYSTEM: "rpc.system";
+    readonly RPC_SERVICE: "rpc.service";
+    readonly RPC_METHOD: "rpc.method";
+    readonly DB_SYSTEM: "db.system";
+    readonly DB_NAME: "db.name";
+    readonly DB_OPERATION: "db.operation";
+    readonly DB_STATEMENT: "db.statement";
+    readonly MESSAGING_SYSTEM: "messaging.system";
+    readonly MESSAGING_DESTINATION: "messaging.destination";
+    readonly MESSAGING_MESSAGE_ID: "messaging.message_id";
+    readonly SERVICE_NAME: "service.name";
+    readonly SERVICE_VERSION: "service.version";
+    readonly EXCEPTION_TYPE: "exception.type";
+    readonly EXCEPTION_MESSAGE: "exception.message";
+    readonly EXCEPTION_STACKTRACE: "exception.stacktrace";
+    readonly PARS_TENANT_ID: "pars.tenant_id";
+    readonly PARS_USER_ID: "pars.user_id";
+    readonly PARS_REQUEST_ID: "pars.request_id";
+};
+
+/**
+ * @parsrun/service - Trace Exporters
+ * Console and OTLP exporters for spans
+ */
+
+interface SpanExporter {
+    /** Exporter name */
+    readonly name: string;
+    /** Export spans */
+    export(spans: Span[]): Promise<void>;
+    /** Shutdown exporter */
+    shutdown(): Promise<void>;
+}
+interface ExporterOptions {
+    /** Logger */
+    logger?: Logger;
+}
+interface ConsoleExporterOptions extends ExporterOptions {
+    /** Pretty print (default: true in dev) */
+    pretty?: boolean;
+    /** Include attributes (default: true) */
+    includeAttributes?: boolean;
+    /** Include events (default: true) */
+    includeEvents?: boolean;
+}
+/**
+ * Console exporter for development/debugging
+ */
+declare class ConsoleExporter implements SpanExporter {
+    readonly name = "console";
+    private readonly logger;
+    private readonly pretty;
+    private readonly includeAttributes;
+    private readonly includeEvents;
+    constructor(options?: ConsoleExporterOptions);
+    export(spans: Span[]): Promise<void>;
+    shutdown(): Promise<void>;
+}
+/**
+ * Create a console exporter
+ */
+declare function createConsoleExporter(options?: ConsoleExporterOptions): ConsoleExporter;
+interface OtlpExporterOptions extends ExporterOptions {
+    /** OTLP endpoint URL */
+    endpoint: string;
+    /** Service name */
+    serviceName: string;
+    /** Service version */
+    serviceVersion?: string;
+    /** Custom headers */
+    headers?: Record<string, string>;
+    /** Timeout in ms */
+    timeout?: number;
+    /** Batch size */
+    batchSize?: number;
+    /** Flush interval in ms */
+    flushInterval?: number;
+}
+/**
+ * OTLP exporter for production tracing
+ */
+declare class OtlpExporter implements SpanExporter {
+    readonly name = "otlp";
+    private readonly endpoint;
+    private readonly serviceName;
+    private readonly serviceVersion;
+    private readonly headers;
+    private readonly timeout;
+    private readonly batchSize;
+    private readonly flushInterval;
+    private readonly logger;
+    private readonly buffer;
+    private flushTimer;
+    constructor(options: OtlpExporterOptions);
+    export(spans: Span[]): Promise<void>;
+    private flush;
+    private buildOtlpPayload;
+    private convertSpan;
+    private convertSpanKind;
+    private convertAttributeValue;
+    shutdown(): Promise<void>;
+}
+/**
+ * Create an OTLP exporter
+ */
+declare function createOtlpExporter(options: OtlpExporterOptions): OtlpExporter;
+
+/**
+ * @parsrun/service - Tracer
+ * High-level tracing API
+ */
+
+interface TracerOptions {
+    /** Service name */
+    serviceName: string;
+    /** Service version */
+    serviceVersion?: string;
+    /** Tracing config */
+    config?: TracingConfig;
+    /** Span exporter */
+    exporter?: SpanExporter;
+    /** Logger */
+    logger?: Logger;
+}
+/**
+ * Main tracer class for distributed tracing
+ */
+declare class Tracer {
+    private readonly serviceName;
+    private readonly serviceVersion;
+    private readonly sampler;
+    private readonly exporter;
+    private readonly logger;
+    private readonly contextManager;
+    private readonly spanManager;
+    private readonly enabled;
+    private flushTimer;
+    constructor(options: TracerOptions);
+    /**
+     * Start a new span
+     */
+    startSpan(name: string, options?: {
+        kind?: SpanKind;
+        parent?: TraceContext;
+        attributes?: Record<string, SpanAttributeValue>;
+    }): Span | null;
+    /**
+     * End a span
+     */
+    endSpan(span: Span | null, error?: Error): void;
+    /**
+     * Run a function with automatic span creation
+     */
+    trace<T>(name: string, fn: (span: Span | null) => Promise<T>, options?: {
+        kind?: SpanKind;
+        attributes?: Record<string, SpanAttributeValue>;
+    }): Promise<T>;
+    /**
+     * Add attribute to current span
+     */
+    setAttribute(key: string, value: SpanAttributeValue): void;
+    /**
+     * Add event to current span
+     */
+    addEvent(name: string, attributes?: Record<string, SpanAttributeValue>): void;
+    /**
+     * Get current trace context
+     */
+    currentContext(): TraceContext | undefined;
+    /**
+     * Get context manager for advanced use
+     */
+    getContextManager(): TraceContextManager;
+    /**
+     * Extract trace context from incoming request
+     */
+    extract(headers: Headers | Record<string, string>): TraceContext | undefined;
+    /**
+     * Inject trace context into outgoing request headers
+     */
+    inject(ctx?: TraceContext): Record<string, string>;
+    /**
+     * Flush completed spans to exporter
+     */
+    flush(): Promise<void>;
+    /**
+     * Shutdown tracer
+     */
+    shutdown(): Promise<void>;
+}
+/**
+ * Create a tracer
+ */
+declare function createTracer(options: TracerOptions): Tracer;
+/**
+ * Get the global tracer instance
+ */
+declare function getGlobalTracer(): Tracer | null;
+/**
+ * Set the global tracer instance
+ */
+declare function setGlobalTracer(tracer: Tracer): void;
+/**
+ * Reset the global tracer (for testing)
+ */
+declare function resetGlobalTracer(): void;
+/**
+ * Create HTTP server tracing middleware
+ */
+declare function createTracingMiddleware(tracer: Tracer): (request: Request, next: () => Promise<Response>) => Promise<Response>;
+/**
+ * Create RPC tracing helpers
+ */
+declare function createRpcTracing(tracer: Tracer): {
+    /**
+     * Trace an outgoing RPC call
+     */
+    traceCall<T>(service: string, method: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Trace an incoming RPC request
+     */
+    traceHandler<T>(service: string, method: string, fn: () => Promise<T>, parentCtx?: TraceContext): Promise<T>;
+};
+
+export { ConsoleExporter, type ConsoleExporterOptions, type ExporterOptions, OtlpExporter, type OtlpExporterOptions, type Sampler, SpanAttributes, type SpanExporter, SpanManager, type SpanOptions, TraceContextManager, Tracer, type TracerOptions, createChildContext, createConsoleExporter, createOtlpExporter, createRpcTracing, createSpan, createTraceContext, createTracer, createTracingMiddleware, formatTraceparent, formatTracestate, generateSpanId, generateTraceId, getGlobalTracer, getSpanDuration, isSpanCompleted, parseTraceparent, parseTracestate, resetGlobalTracer, setGlobalTracer, shouldSample, spanToLogObject };