Skip to main content
Preview
Preview Feature — This feature is currently in preview and under active development. APIs and functionality may change. We recommend testing thoroughly before using in production.

Overview

Build resilient integrations with healthchecks, quotas (load distribution), and fallbacks (automatic failover).

What is Resilience?​

Resilience in Ductape helps you build fault-tolerant integrations by:

  • Healthchecks: Monitor provider availability and detect failures
  • Quotas: Distribute load across multiple providers based on weights
  • Fallbacks: Automatically failover to backup providers when primary fails

Quick Start​

import Ductape from '@ductape/sdk';

const ductape = new Ductape({
  accessKey: 'your-access-key',
});

Code-First API​

Define resilience configurations using a fluent, type-safe API:


const { resilience } = ductape;

// Define a healthcheck
const healthcheck = await resilience.healthcheck.define({
  product: 'my-product',
  tag: 'stripe-health',
  handler: async (ctx) => {
    ctx.probe().app('stripe-app').action('health');
    ctx.interval(30000); // Check every 30 seconds
    ctx.retries(2);
    ctx.env('prd');
  },
});

// Define a quota for load distribution
const quota = await resilience.quota.define({
  product: 'my-product',
  tag: 'sms-quota',
  input: {
    phone: { type: 'string' },
    message: { type: 'string' },
  },
  handler: async (ctx) => {
    ctx.provider('twilio')
      .weight(70)
      .healthcheck('twilio-health')
      .app('twilio-app')
      .action('send-sms')
      .retries(2);

    ctx.provider('nexmo')
      .weight(30)
      .healthcheck('nexmo-health')
      .app('nexmo-app')
      .action('send-sms')
      .retries(2);
  },
});

// Define a fallback for automatic failover
const fallback = await resilience.fallback.define({
  product: 'my-product',
  tag: 'payment-fallback',
  input: {
    amount: { type: 'number' },
  },
  handler: async (ctx) => {
    ctx.primary('stripe')
      .healthcheck('stripe-health')
      .app('stripe-app')
      .action('charge')
      .retries(2);

    ctx.fallback('paypal')
      .healthcheck('paypal-health')
      .app('paypal-app')
      .action('payment')
      .retries(2);
  },
});

Running Resilience Operations​

Run a Healthcheck​

Manually trigger a healthcheck and cache the result:

const result = await ductape.health.run({
  product: 'my-product',
  env: 'prd',
  tag: 'stripe-health',
});

console.log(result.status); // 'available' or 'unavailable'

Check Health Status​

Get the current cached status of a healthcheck:

const status = await ductape.health.status({
  product: 'my-product',
  env: 'prd',
  tag: 'stripe-health',
});

Run a Quota​

const result = await ductape.quota.run({
  product: 'my-product',
  env: 'prd',
  tag: 'sms-quota',
  input: { phone: '+1234567890', message: 'Hello!' },
});

Run a Fallback​

const paymentResult = await ductape.fallback.run({
  product: 'my-product',
  env: 'prd',
  tag: 'payment-fallback',
  input: { amount: 1000 },
});

Key Concepts​

Providers​

Providers represent different services or APIs that can perform the same operation. For example, Twilio and Nexmo are both SMS providers.

Health-Aware Routing​

Resilience automatically routes traffic away from unhealthy providers based on healthcheck results.

Weighted Distribution​

Quotas distribute load across providers based on configured weights. A provider with weight 70 receives 70% of traffic.

Sequential Failover​

Fallbacks try providers in order until one succeeds. If the primary fails, it automatically tries the fallback.

Next Steps​