@ductape/sdk 0.1.8 → 0.1.10

package/dist/resilience/fallback.service.js

@@ -0,0 +1,771 @@
+"use strict";
+/**
+ * Fallback Service
+ *
+ * Code-first API for defining and managing fallbacks with sequential failover.
+ * Uses ProductBuilder for CRUD operations and ProcessorService for execution.
+ * Implements health-aware sequential failover with minimal latency.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FallbackService = exports.FallbackError = void 0;
+const types_1 = require("./types");
+const products_service_1 = __importDefault(require("../products/services/products.service"));
+const processor_service_1 = __importDefault(require("../processor/services/processor.service"));
+const runtime_defaults_1 = require("../runtime/runtime-defaults");
+/**
+ * Error class for fallback operations
+ */
+class FallbackError extends Error {
+    constructor(message, code, details) {
+        super(message);
+        this.code = code;
+        this.details = details;
+        this.name = 'FallbackError';
+    }
+}
+exports.FallbackError = FallbackError;
+/**
+ * Provider builder that records fallback provider configuration
+ */
+class RecordingFallbackProviderBuilder {
+    constructor(providerName, options) {
+        this.providerName = providerName;
+        this.options = options;
+        this._retries = 2;
+    }
+    weight(_value) {
+        // Fallback doesn't use weight, but we implement for interface compatibility
+        return this;
+    }
+    healthcheck(tag) {
+        this._healthcheck = tag;
+        return this;
+    }
+    app(tag) {
+        this._type = types_1.FeatureEventTypes.ACTION;
+        this._app = tag;
+        return new RecordingFallbackAppProviderBuilder(this, this._app);
+    }
+    /**
+     * @deprecated Features are deprecated - use workflow() instead
+     */
+    feature(tag) {
+        console.warn('feature() is deprecated. Use workflow() instead.');
+        this._type = types_1.FeatureEventTypes.ACTION;
+        this._event = tag;
+        this.finalize();
+        return this;
+    }
+    database(tag) {
+        this._type = types_1.FeatureEventTypes.ACTION;
+        this._app = tag;
+        return new RecordingFallbackDatabaseProviderBuilder(this, tag);
+    }
+    workflow(tag) {
+        this._type = types_1.FeatureEventTypes.ACTION;
+        this._event = tag;
+        return new RecordingFallbackWorkflowProviderBuilder(this, tag);
+    }
+    notification(tag) {
+        this._type = types_1.FeatureEventTypes.ACTION;
+        this._event = tag;
+        return new RecordingFallbackNotificationProviderBuilder(this, tag);
+    }
+    mapInput(mapper) {
+        this._inputMapper = mapper;
+        return this;
+    }
+    mapOutput(mapper) {
+        this._outputMapper = mapper;
+        return this;
+    }
+    retries(count) {
+        this._retries = count;
+        return this;
+    }
+    checkInterval(ms) {
+        this._checkInterval = ms;
+        return this;
+    }
+    /**
+     * Set event/action name (used by sub-builders)
+     */
+    setEvent(event) {
+        this._event = event;
+        this.finalize();
+    }
+    /**
+     * Set workflow input (used by workflow builder)
+     */
+    setWorkflowInput(input) {
+        this._workflowInput = input;
+        this.finalize();
+    }
+    /**
+     * Finalize and add provider to options
+     */
+    finalize() {
+        const inputSchema = this.generateInputSchema();
+        const outputSchema = this.generateOutputSchema();
+        const option = {
+            provider: this.providerName,
+            healthcheck: this._healthcheck,
+            type: this._type || types_1.FeatureEventTypes.ACTION,
+            app: this._app,
+            event: this._event || '',
+            input: this._workflowInput || inputSchema,
+            output: outputSchema,
+            retries: this._retries,
+            check_interval: this._checkInterval,
+        };
+        this.options.push(option);
+    }
+    /**
+     * Generate input schema from mapper function
+     */
+    generateInputSchema() {
+        if (!this._inputMapper) {
+            return {};
+        }
+        const proxyHandler = {
+            get: (_target, prop) => {
+                if (typeof prop === 'string') {
+                    return `$Input{${prop}}`;
+                }
+                return undefined;
+            },
+        };
+        try {
+            const proxy = new Proxy({}, proxyHandler);
+            return this._inputMapper(proxy);
+        }
+        catch (_a) {
+            return {};
+        }
+    }
+    /**
+     * Generate output schema from mapper function
+     */
+    generateOutputSchema() {
+        if (!this._outputMapper) {
+            return {};
+        }
+        const proxyHandler = {
+            get: (_target, prop) => {
+                if (typeof prop === 'string') {
+                    return `$Response{${prop}}`;
+                }
+                return undefined;
+            },
+        };
+        try {
+            const proxy = new Proxy({}, proxyHandler);
+            return this._outputMapper(proxy);
+        }
+        catch (_a) {
+            return {};
+        }
+    }
+}
+class RecordingFallbackAppProviderBuilder {
+    constructor(parent, appTag) {
+        this.parent = parent;
+        this.appTag = appTag;
+    }
+    action(event) {
+        this.parent.setEvent(event);
+        return this.parent;
+    }
+    weight(value) {
+        return this.parent.weight(value);
+    }
+    healthcheck(tag) {
+        return this.parent.healthcheck(tag);
+    }
+    app(tag) {
+        return this.parent.app(tag);
+    }
+    feature(tag) {
+        return this.parent.feature(tag);
+    }
+    database(tag) {
+        return this.parent.database(tag);
+    }
+    workflow(tag) {
+        return this.parent.workflow(tag);
+    }
+    notification(tag) {
+        return this.parent.notification(tag);
+    }
+    mapInput(mapper) {
+        return this.parent.mapInput(mapper);
+    }
+    mapOutput(mapper) {
+        return this.parent.mapOutput(mapper);
+    }
+    retries(count) {
+        return this.parent.retries(count);
+    }
+    checkInterval(ms) {
+        return this.parent.checkInterval(ms);
+    }
+}
+class RecordingFallbackDatabaseProviderBuilder {
+    constructor(parent, dbTag) {
+        this.parent = parent;
+        this.dbTag = dbTag;
+    }
+    action(event) {
+        this.parent.setEvent(event);
+        return this.parent;
+    }
+    weight(value) {
+        return this.parent.weight(value);
+    }
+    healthcheck(tag) {
+        return this.parent.healthcheck(tag);
+    }
+    app(tag) {
+        return this.parent.app(tag);
+    }
+    feature(tag) {
+        return this.parent.feature(tag);
+    }
+    database(tag) {
+        return this.parent.database(tag);
+    }
+    workflow(tag) {
+        return this.parent.workflow(tag);
+    }
+    notification(tag) {
+        return this.parent.notification(tag);
+    }
+    mapInput(mapper) {
+        return this.parent.mapInput(mapper);
+    }
+    mapOutput(mapper) {
+        return this.parent.mapOutput(mapper);
+    }
+    retries(count) {
+        return this.parent.retries(count);
+    }
+    checkInterval(ms) {
+        return this.parent.checkInterval(ms);
+    }
+}
+class RecordingFallbackWorkflowProviderBuilder {
+    constructor(parent, workflowTag) {
+        this.parent = parent;
+        this.workflowTag = workflowTag;
+    }
+    input(data) {
+        this.parent.setWorkflowInput(data);
+        return this.parent;
+    }
+    weight(value) {
+        return this.parent.weight(value);
+    }
+    healthcheck(tag) {
+        return this.parent.healthcheck(tag);
+    }
+    app(tag) {
+        return this.parent.app(tag);
+    }
+    feature(tag) {
+        return this.parent.feature(tag);
+    }
+    database(tag) {
+        return this.parent.database(tag);
+    }
+    workflow(tag) {
+        return this.parent.workflow(tag);
+    }
+    notification(tag) {
+        return this.parent.notification(tag);
+    }
+    mapInput(mapper) {
+        return this.parent.mapInput(mapper);
+    }
+    mapOutput(mapper) {
+        return this.parent.mapOutput(mapper);
+    }
+    retries(count) {
+        return this.parent.retries(count);
+    }
+    checkInterval(ms) {
+        return this.parent.checkInterval(ms);
+    }
+}
+class RecordingFallbackNotificationProviderBuilder {
+    constructor(parent, notificationTag) {
+        this.parent = parent;
+        this.notificationTag = notificationTag;
+    }
+    event(event) {
+        this.parent.setEvent(event);
+        return this.parent;
+    }
+    weight(value) {
+        return this.parent.weight(value);
+    }
+    healthcheck(tag) {
+        return this.parent.healthcheck(tag);
+    }
+    app(tag) {
+        return this.parent.app(tag);
+    }
+    feature(tag) {
+        return this.parent.feature(tag);
+    }
+    database(tag) {
+        return this.parent.database(tag);
+    }
+    workflow(tag) {
+        return this.parent.workflow(tag);
+    }
+    notification(tag) {
+        return this.parent.notification(tag);
+    }
+    mapInput(mapper) {
+        return this.parent.mapInput(mapper);
+    }
+    mapOutput(mapper) {
+        return this.parent.mapOutput(mapper);
+    }
+    retries(count) {
+        return this.parent.retries(count);
+    }
+    checkInterval(ms) {
+        return this.parent.checkInterval(ms);
+    }
+}
+/**
+ * Recording context that captures fallback configuration during handler execution
+ */
+class RecordingFallbackContext {
+    constructor(inputSchema) {
+        this._options = [];
+        this._input = inputSchema;
+    }
+    get input() {
+        const proxyHandler = {
+            get: (target, prop) => {
+                if (typeof prop === 'string') {
+                    return `$Input{${prop}}`;
+                }
+                return undefined;
+            },
+        };
+        return new Proxy({}, proxyHandler);
+    }
+    primary(name) {
+        return new RecordingFallbackProviderBuilder(name, this._options);
+    }
+    fallback(name) {
+        return new RecordingFallbackProviderBuilder(name, this._options);
+    }
+    auth(field) {
+        return `$Auth{${field}}`;
+    }
+    token(key) {
+        return `$Secret{${key}}`;
+    }
+    variable(app, key) {
+        return `$Variable{${app}}{${key}}`;
+    }
+    constant(app, key) {
+        return `$Constant{${app}}{${key}}`;
+    }
+    /**
+     * Build the fallback schema from recorded configuration
+     */
+    build(tag, name, description) {
+        if (this._options.length === 0) {
+            throw new FallbackError('At least one provider must be configured', 'NO_PROVIDERS_CONFIGURED');
+        }
+        return {
+            tag,
+            name,
+            description,
+            input: this._input,
+            options: this._options,
+        };
+    }
+    get options() {
+        return this._options;
+    }
+}
+/**
+ * Fallback Service
+ *
+ * Provides code-first API for defining, creating, and managing fallbacks.
+ * Uses ProductBuilder for CRUD operations and ProcessorService for execution.
+ * Implements health-aware sequential failover with minimal latency.
+ */
+class FallbackService {
+    constructor(config) {
+        this.productBuilders = new Map();
+        this.processorCache = new Map();
+        this.config = config;
+        this._privateKey = config.private_key;
+        this.productEnv = new runtime_defaults_1.ProductEnvResolver((0, runtime_defaults_1.runtimeDefaultsFromConfig)(config));
+    }
+    resolvePE(options) {
+        return this.productEnv.resolve(options);
+    }
+    /**
+     * Gets or creates a cached ProductBuilder
+     */
+    async getProductBuilder(productTag) {
+        let builder = this.productBuilders.get(productTag);
+        if (!builder) {
+            builder = new products_service_1.default({
+                workspace_id: this.config.workspace_id,
+                public_key: this.config.public_key,
+                user_id: this.config.user_id,
+                token: this.config.token,
+                env_type: this.config.env_type,
+                redis_client: this.config.redis_client,
+                queues: this.config.queues,
+                access_key: this.config.access_key,
+            });
+            await builder.initializeProductByTag(productTag);
+            this.productBuilders.set(productTag, builder);
+        }
+        return builder;
+    }
+    /**
+     * Gets or creates a cached ProcessorService for minimal latency
+     */
+    getProcessor(productTag) {
+        let processor = this.processorCache.get(productTag);
+        if (!processor) {
+            processor = new processor_service_1.default({
+                workspace_id: this.config.workspace_id,
+                public_key: this.config.public_key,
+                user_id: this.config.user_id,
+                token: this.config.token,
+                env_type: this.config.env_type,
+                redis_client: this.config.redis_client,
+                queues: this.config.queues,
+                private_key: this._privateKey,
+                access_key: this.config.access_key,
+            });
+            this.processorCache.set(productTag, processor);
+        }
+        return processor;
+    }
+    // ==================== Code-First API ====================
+    /**
+     * Define a fallback using code-first API
+     *
+     * @example
+     * ```ts
+     * const fallback = await fallbackService.define({
+     *   product: 'my-product',
+     *   tag: 'payment-fallback',
+     *   name: 'Payment Provider Fallback',
+     *   input: {
+     *     amount: { type: 'number', required: true },
+     *     currency: { type: 'string', required: true },
+     *   },
+     *   handler: async (ctx) => {
+     *     ctx.primary('stripe')
+     *       .healthcheck('stripe-health')
+     *       .app('stripe-app')
+     *       .action('charge')
+     *       .mapInput((input) => ({ body: { amount: input.amount } }))
+     *       .mapOutput((res) => ({ chargeId: res.id }))
+     *       .retries(2);
+     *
+     *     ctx.fallback('paypal')
+     *       .healthcheck('paypal-health')
+     *       .app('paypal-app')
+     *       .action('payment')
+     *       .mapInput((input) => ({ body: { amount: input.amount } }))
+     *       .mapOutput((res) => ({ chargeId: res.id }))
+     *       .retries(2);
+     *   },
+     * });
+     * ```
+     */
+    async define(options) {
+        const ctx = new RecordingFallbackContext(options.input);
+        // Execute the handler to record the configuration
+        await options.handler(ctx);
+        // Build the schema
+        const schema = ctx.build(options.tag, options.name, options.description);
+        const definedFallback = {
+            tag: options.tag,
+            name: options.name,
+            description: options.description,
+            input: options.input,
+            compile: () => schema,
+        };
+        // If product is specified, register immediately
+        if (options.product) {
+            await this.create(options.product, definedFallback);
+        }
+        return definedFallback;
+    }
+    // ==================== CRUD via ProductBuilder ====================
+    /**
+     * Create a fallback from a defined fallback or schema
+     */
+    async create(product, fallback) {
+        const schema = 'compile' in fallback ? fallback.compile() : fallback;
+        const builder = await this.getProductBuilder(product);
+        const productFallback = {
+            tag: schema.tag,
+            name: schema.name || schema.tag,
+            description: schema.description || '',
+            input: schema.input,
+            options: schema.options.map((opt) => ({
+                app: opt.app,
+                type: types_1.FeatureEventTypes.ACTION,
+                event: opt.event,
+                input: opt.input || {},
+                output: opt.output || {},
+                retries: opt.retries || 2,
+                healthcheck: opt.healthcheck,
+                check_interval: opt.check_interval,
+            })),
+        };
+        await builder.createFallback(productFallback);
+        return (await builder.fetchFallback(schema.tag));
+    }
+    /**
+     * Fetch a fallback by tag
+     */
+    async fetch(product, tag) {
+        const builder = await this.getProductBuilder(product);
+        return builder.fetchFallback(tag);
+    }
+    /**
+     * Fetch all fallbacks for a product
+     */
+    async fetchAll(product) {
+        const builder = await this.getProductBuilder(product);
+        return builder.fetchFallbacks();
+    }
+    /**
+     * Update an existing fallback
+     */
+    async update(product, tag, fallback) {
+        const builder = await this.getProductBuilder(product);
+        if ('handler' in fallback && fallback.handler && fallback.input) {
+            const ctx = new RecordingFallbackContext(fallback.input);
+            await fallback.handler(ctx);
+            const schema = ctx.build(tag, fallback.name, fallback.description);
+            await builder.updateFallback(tag, {
+                name: schema.name,
+                description: schema.description,
+                input: schema.input,
+                options: schema.options.map((opt) => ({
+                    app: opt.app,
+                    type: types_1.FeatureEventTypes.ACTION,
+                    event: opt.event,
+                    input: opt.input || {},
+                    output: opt.output || {},
+                    retries: opt.retries || 2,
+                    healthcheck: opt.healthcheck,
+                    check_interval: opt.check_interval,
+                })),
+            });
+        }
+        else {
+            await builder.updateFallback(tag, fallback);
+        }
+    }
+    /**
+     * Delete a fallback
+     */
+    async delete(product, tag) {
+        const builder = await this.getProductBuilder(product);
+        await builder.deleteFallback(tag);
+    }
+    // ==================== Execution - Health-Aware Sequential Failover ====================
+    /**
+     * Run a fallback with health-aware sequential failover
+     *
+     * Optimization strategies:
+     * 1. Parallel health status lookups from Redis (O(1) per provider)
+     * 2. Skip unhealthy providers immediately
+     * 3. Cached processor instances to avoid re-initialization
+     * 4. Exponential backoff only on failures
+     * 5. Short-circuit on first success
+     */
+    async run(options) {
+        var _a;
+        const { product, env, tag, input } = this.resolvePE(options);
+        const startTime = Date.now();
+        const triedProviders = [];
+        // Fetch fallback config
+        const fallback = await this.fetch(product, tag);
+        if (!fallback) {
+            throw new FallbackError(`Fallback '${tag}' not found in product '${product}'`, 'FALLBACK_NOT_FOUND');
+        }
+        if (!((_a = fallback.options) === null || _a === void 0 ? void 0 : _a.length)) {
+            throw new FallbackError(`Fallback '${tag}' has no providers configured`, 'NO_PROVIDERS');
+        }
+        const processor = this.getProcessor(product);
+        // Parallel health status lookup - minimal latency
+        const healthStatuses = await this.getHealthStatusesParallel(processor, product, env, fallback.options);
+        // Order providers: healthy first, then unknown, then unhealthy
+        const orderedProviders = this.orderProvidersByHealth(fallback.options, healthStatuses);
+        // Sequential failover with health-aware skipping
+        let lastError = null;
+        let failoverCount = 0;
+        for (const provider of orderedProviders) {
+            const providerName = provider.app || provider.event;
+            triedProviders.push(providerName);
+            // Check if provider is unhealthy and we have healthier alternatives
+            const healthStatus = provider.healthcheck ? healthStatuses.get(provider.healthcheck) : null;
+            const isUnhealthy = (healthStatus === null || healthStatus === void 0 ? void 0 : healthStatus.status) === 'unavailable';
+            // Skip unhealthy providers if we haven't tried all healthy ones
+            if (isUnhealthy && failoverCount === 0) {
+                // Only skip if there are more providers to try
+                const remainingHealthy = orderedProviders.slice(triedProviders.length).some((p) => {
+                    const status = p.healthcheck ? healthStatuses.get(p.healthcheck) : null;
+                    return !status || status.status !== 'unavailable';
+                });
+                if (remainingHealthy) {
+                    failoverCount++;
+                    continue;
+                }
+            }
+            try {
+                const result = await this.executeWithRetries(processor, provider, env, product, input);
+                return {
+                    data: result.data,
+                    provider: providerName,
+                    latency: Date.now() - startTime,
+                    wasHealthy: !isUnhealthy,
+                    failoverCount,
+                    triedProviders,
+                };
+            }
+            catch (error) {
+                lastError = error;
+                failoverCount++;
+                // Continue to next provider
+            }
+        }
+        // All providers failed
+        throw new FallbackError(`All ${fallback.options.length} providers failed. Last error: ${lastError === null || lastError === void 0 ? void 0 : lastError.message}`, 'ALL_PROVIDERS_FAILED', { lastError, triedProviders, failoverCount });
+    }
+    /**
+     * Parallel health status lookup from Redis - O(n) with parallel I/O
+     */
+    async getHealthStatusesParallel(processor, product, env, options) {
+        const statuses = new Map();
+        // Collect healthcheck tags
+        const healthcheckTags = options.filter((opt) => opt.healthcheck).map((opt) => opt.healthcheck);
+        if (healthcheckTags.length === 0) {
+            return statuses;
+        }
+        // Parallel Redis lookups
+        const results = await Promise.allSettled(healthcheckTags.map(async (tag) => {
+            try {
+                const cached = await processor.getHealthcheckStatusFromCache(product, `${tag}:${env}`);
+                return { tag, status: (cached === null || cached === void 0 ? void 0 : cached.status) || 'unknown', latency: cached === null || cached === void 0 ? void 0 : cached.latency };
+            }
+            catch (_a) {
+                return { tag, status: 'unknown' };
+            }
+        }));
+        for (const result of results) {
+            if (result.status === 'fulfilled') {
+                statuses.set(result.value.tag, {
+                    status: result.value.status,
+                    lastLatency: result.value.latency,
+                });
+            }
+        }
+        return statuses;
+    }
+    /**
+     * Order providers by health status: healthy > unknown > unhealthy
+     * Maintains original order within each category (first provider = primary)
+     */
+    orderProvidersByHealth(options, healthStatuses) {
+        const healthy = [];
+        const unknown = [];
+        const unhealthy = [];
+        for (const opt of options) {
+            if (!opt.healthcheck) {
+                healthy.push(opt); // No healthcheck = assume healthy
+            }
+            else {
+                const status = healthStatuses.get(opt.healthcheck);
+                if (!status || status.status === 'unknown') {
+                    unknown.push(opt);
+                }
+                else if (status.status === 'available') {
+                    healthy.push(opt);
+                }
+                else {
+                    unhealthy.push(opt);
+                }
+            }
+        }
+        return [...healthy, ...unknown, ...unhealthy];
+    }
+    /**
+     * Execute provider action with exponential backoff retries
+     */
+    async executeWithRetries(processor, provider, env, product, input) {
+        const maxRetries = provider.retries || 2;
+        let lastError = null;
+        let retriesUsed = 0;
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                // Execute app action via processor
+                const result = await processor.processAction({
+                    env,
+                    product,
+                    app: provider.app,
+                    action: provider.event,
+                    input,
+                    retries: 0, // We handle retries ourselves
+                });
+                return { data: result, retriesUsed };
+            }
+            catch (error) {
+                lastError = error;
+                retriesUsed++;
+                if (attempt < maxRetries) {
+                    // Exponential backoff: 50ms, 100ms, 200ms (capped at 2s for low latency)
+                    await new Promise((r) => setTimeout(r, Math.min(50 * Math.pow(2, attempt), 2000)));
+                }
+            }
+        }
+        throw new FallbackError(`Provider ${provider.app || provider.event} failed after ${maxRetries + 1} attempts: ${lastError === null || lastError === void 0 ? void 0 : lastError.message}`, 'PROVIDER_FAILED', { lastError, retriesUsed });
+    }
+    /**
+     * Dispatch fallback for deferred execution via job queue
+     *
+     * Note: For immediate execution, use run() instead.
+     * Dispatch schedules the fallback for background processing.
+     */
+    async dispatch(options) {
+        const { product, tag } = options;
+        const jobId = `fallback_${tag}_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+        // For deferred execution, we run the fallback asynchronously
+        setImmediate(async () => {
+            try {
+                await this.run(options);
+            }
+            catch (error) {
+                console.error(`Deferred fallback execution failed for ${product}:${tag}:`, error);
+            }
+        });
+        return { jobId };
+    }
+}
+exports.FallbackService = FallbackService;
+exports.default = FallbackService;
+//# sourceMappingURL=fallback.service.js.map