dotdo 0.0.1 → 0.1.0

package/dist/workflows/context/correlation-capability.js

@@ -0,0 +1,266 @@
+/**
+ * Correlation Capability for WorkflowContext
+ *
+ * Provides distributed tracing capabilities via $.correlation:
+ * - $.correlation.id - Get current correlation ID
+ * - $.correlation.spanId - Get current span ID
+ * - $.correlation.context - Get full correlation context
+ * - $.correlation.span(name) - Create a child span for sub-operations
+ * - $.correlation.create() - Create a new correlation context
+ * - $.correlation.setContext(ctx) - Set the correlation context
+ * - $.correlation.setAttribute(key, value) - Add attribute to current span
+ * - $.correlation.addEvent(name, attrs) - Add event to current span
+ *
+ * Integrates with cross-DO RPC for automatic context propagation.
+ *
+ * @module workflows/context/correlation-capability
+ */
+import { generateCorrelationId, generateRequestId, } from './correlation';
+// ============================================================================
+// ID GENERATION
+// ============================================================================
+/**
+ * Generates a unique span ID
+ */
+function generateSpanId() {
+    const random = crypto.getRandomValues(new Uint8Array(4));
+    return `span-${Array.from(random).map(b => b.toString(16).padStart(2, '0')).join('')}`;
+}
+// ============================================================================
+// SPAN BUILDER IMPLEMENTATION
+// ============================================================================
+/**
+ * Creates a SpanBuilder for managing a span
+ */
+function createSpanBuilder(store, span) {
+    const parentSpanId = store.currentSpanId;
+    const builder = {
+        setAttribute(key, value) {
+            span.attributes[key] = value;
+            return builder;
+        },
+        addEvent(name, attributes) {
+            span.events.push({
+                name,
+                timestamp: new Date(),
+                attributes,
+            });
+            return builder;
+        },
+        async run(fn) {
+            // Set this span as current
+            const previousSpanId = store.currentSpanId;
+            store.currentSpanId = span.id;
+            store.spans.set(span.id, span);
+            try {
+                const result = await Promise.resolve(fn());
+                builder.end('completed');
+                return result;
+            }
+            catch (error) {
+                builder.end('failed');
+                throw error;
+            }
+            finally {
+                // Restore previous span
+                store.currentSpanId = previousSpanId;
+            }
+        },
+        end(status = 'completed') {
+            // Only end if not already ended
+            if (span.status === 'active') {
+                span.status = status;
+                span.endedAt = new Date();
+                span.durationMs = span.endedAt.getTime() - span.startedAt.getTime();
+            }
+        },
+        getSpan() {
+            return span;
+        },
+    };
+    return builder;
+}
+// ============================================================================
+// CORRELATION CAPABILITY IMPLEMENTATION
+// ============================================================================
+/**
+ * Creates a CorrelationCapability instance
+ *
+ * @param store - The storage for correlation state
+ * @returns A CorrelationCapability object
+ *
+ * @example
+ * ```typescript
+ * const store: CorrelationStore = {
+ *   context: null,
+ *   spans: new Map(),
+ *   currentSpanId: undefined,
+ * }
+ *
+ * const correlation = createCorrelationCapability(store)
+ *
+ * // Create new context
+ * const ctx = correlation.create()
+ * correlation.setContext(ctx)
+ *
+ * // Create and run a span
+ * const result = await correlation.span('process-order')
+ *   .setAttribute('order.id', '12345')
+ *   .run(async () => {
+ *     // ... process order
+ *     return { success: true }
+ *   })
+ * ```
+ */
+export function createCorrelationCapability(store) {
+    return {
+        get id() {
+            if (!store.context) {
+                throw new Error('No correlation context set');
+            }
+            return store.context.correlationId;
+        },
+        get spanId() {
+            return store.currentSpanId ?? store.context?.spanId;
+        },
+        get context() {
+            if (!store.context) {
+                throw new Error('No correlation context set');
+            }
+            return store.context;
+        },
+        span(name) {
+            if (!store.context) {
+                throw new Error('No correlation context set');
+            }
+            const span = {
+                id: generateSpanId(),
+                name,
+                parentId: store.currentSpanId,
+                correlationId: store.context.correlationId,
+                startedAt: new Date(),
+                status: 'active',
+                attributes: {},
+                events: [],
+            };
+            store.spans.set(span.id, span);
+            return createSpanBuilder(store, span);
+        },
+        setAttribute(key, value) {
+            if (!store.currentSpanId) {
+                // Silently ignore if no current span
+                return;
+            }
+            const span = store.spans.get(store.currentSpanId);
+            if (span) {
+                span.attributes[key] = value;
+            }
+        },
+        addEvent(name, attributes) {
+            if (!store.currentSpanId) {
+                // Silently ignore if no current span
+                return;
+            }
+            const span = store.spans.get(store.currentSpanId);
+            if (span) {
+                span.events.push({
+                    name,
+                    timestamp: new Date(),
+                    attributes,
+                });
+            }
+        },
+        create() {
+            return {
+                correlationId: generateCorrelationId(),
+                requestId: generateRequestId(),
+                timestamp: Date.now(),
+                sequence: 1,
+                spanId: generateSpanId(),
+            };
+        },
+        setContext(ctx) {
+            store.context = ctx;
+            // If the context has a spanId, use it as the current span reference
+            // (but don't create a span object for it - it's just a reference)
+        },
+    };
+}
+// ============================================================================
+// FACTORY FOR WORKFLOW CONTEXT
+// ============================================================================
+/**
+ * Creates a correlation capability for a workflow context.
+ * This factory creates the store and capability together.
+ *
+ * @returns An object containing the capability and its store
+ */
+export function createCorrelationContext() {
+    const store = {
+        context: null,
+        spans: new Map(),
+        currentSpanId: undefined,
+    };
+    const correlation = createCorrelationCapability(store);
+    return { correlation, store };
+}
+// ============================================================================
+// UTILITY FUNCTIONS FOR DO INTEGRATION
+// ============================================================================
+/**
+ * Creates a child correlation context for cross-DO calls.
+ * Preserves the correlation ID but creates new request/span IDs.
+ *
+ * @param parent - The parent correlation context
+ * @returns A new child correlation context
+ */
+export function createChildContext(parent) {
+    return {
+        correlationId: parent.correlationId,
+        requestId: generateRequestId(),
+        timestamp: Date.now(),
+        sequence: parent.sequence + 1,
+        spanId: generateSpanId(),
+        parentSpanId: parent.spanId,
+    };
+}
+/**
+ * Wraps an action with correlation tracking.
+ * Use this in $.do() implementation to automatically create spans.
+ *
+ * @param correlation - The correlation capability
+ * @param actionName - Name of the action being executed
+ * @param options - Additional options for the span
+ * @returns A function that wraps the action with span tracking
+ *
+ * @example
+ * ```typescript
+ * const result = await wrapWithCorrelation(
+ *   this.$.correlation,
+ *   'send.email',
+ *   { stepId: 'step-123', durability: 'durable' }
+ * )(async () => {
+ *   return await sendEmail(to, subject, body)
+ * })
+ * ```
+ */
+export function wrapWithCorrelation(correlation, actionName, options) {
+    return async (fn) => {
+        const spanBuilder = correlation.span(`do:${actionName}`)
+            .setAttribute('action.name', actionName);
+        if (options?.durability) {
+            spanBuilder.setAttribute('action.durability', options.durability);
+        }
+        if (options?.stepId) {
+            spanBuilder.setAttribute('action.stepId', options.stepId);
+        }
+        if (options?.retries !== undefined) {
+            spanBuilder.setAttribute('action.retries', options.retries);
+        }
+        if (options?.maxAttempts !== undefined) {
+            spanBuilder.setAttribute('action.maxAttempts', options.maxAttempts);
+        }
+        return spanBuilder.run(fn);
+    };
+}
+//# sourceMappingURL=correlation-capability.js.map

package/dist/workflows/context/correlation-capability.js.map

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