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.

Execution & Rollbacks

This guide explains how features execute, handle failures, and perform automatic rollbacks.

Executing a Feature​

Start a feature using ductape.features.execute():

const result = await ductape.features.execute({
  tag: 'order-fulfillment',
  input: {
    orderId: 'ORD-12345',
    customerId: 'cust-001',
    amount: 99.99,
    items: ['SKU-001', 'SKU-002'],
  },
});

Execution Options​

const result = await ductape.features.execute({
  tag: 'order-fulfillment',
  input: { orderId: 'ORD-12345' },

  // Optional settings
  feature_id: 'custom-id-123',      // Custom execution ID
  idempotency_key: 'order-12345',   // Prevent duplicate executions
  timeout: 300000,                   // Overall timeout (ms)
  context: {                         // Additional context
    source: 'api',
    requestId: 'req-abc',
  },
});

Execution Result​

interface FeatureResult {
  feature_id: string;            // Execution ID
  status: 'completed' | 'failed' | 'rolled_back' | 'running';
  output?: unknown;               // Return value from handler
  error?: {                       // Error details (if failed)
    message: string;
    step?: string;
    code?: string;
  };
  completed_steps: string[];      // Successfully completed steps
  failed_step?: string;           // Step that caused failure
  execution_time: number;         // Duration in milliseconds
  rollback_result?: {             // Rollback details (if rolled back)
    rolled_back_steps: string[];
    failed_steps?: Array<{ tag: string; error: string }>;
  };
}

Example: Handling Results​

const result = await ductape.features.execute({
  tag: 'order-fulfillment',
  input: { orderId: 'ORD-12345' },
});

switch (result.status) {
  case 'completed':
    console.log('Order processed:', result.output);
    console.log('Steps completed:', result.completed_steps);
    break;

  case 'failed':
    console.error('Feature failed at step:', result.failed_step);
    console.error('Error:', result.error?.message);
    break;

  case 'rolled_back':
    console.log('Feature rolled back');
    console.log('Rolled back steps:', result.rollback_result?.rolled_back_steps);
    break;
}

Feature Lifecycle​

┌─────────────────────────────────────────────────────────────────┐
│                        FEATURE EXECUTION                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│   Start                                                         │
│     │                                                           │
│     ▼                                                           │
│   ┌───────────┐   ┌───────────┐   ┌───────────┐                │
│   │  Step A   │ → │  Step B   │ → │  Step C   │ → Complete     │
│   └───────────┘   └───────────┘   └───────────┘                │
│        │               │               │                        │
│        ▼               ▼               ▼                        │
│   [Rollback A]   [Rollback B]   [Rollback C]                   │
│                                                                 │
│   If Step C fails: Rollback C → Rollback B → Rollback A        │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Step States​

Each step transitions through these states:

StateDescription
pendingStep not yet started
runningStep currently executing
completedStep finished successfully
failedStep failed
skippedStep skipped (due to allow_fail)
rolled_backStep's rollback handler executed

Rollback Strategies​

Configure how failures trigger rollbacks:

await ductape.features.define({
  tag: 'my-feature',
  options: {
    rollback_strategy: 'reverse_all',  // Default
  },
  handler: async (ctx) => { /* ... */ },
});

Available Strategies​

StrategyDescription
reverse_allRoll back all completed steps in reverse order
critical_onlyOnly roll back steps marked as critical: true
to_checkpointRoll back to the most recent checkpoint
noneNo automatic rollback

reverse_all (Default)​

Rolls back every completed step that has a rollback handler:

await ductape.features.define({
  options: { rollback_strategy: 'reverse_all' },
  handler: async (ctx) => {
    await ctx.step('step-a', handler, rollbackA);  // Will rollback
    await ctx.step('step-b', handler, rollbackB);  // Will rollback
    await ctx.step('step-c', handler);             // Fails - no rollback
    // If step-c fails: rollbackB() → rollbackA()
  },
});

critical_only​

Only rolls back steps marked as critical:

await ductape.features.define({
  options: { rollback_strategy: 'critical_only' },
  handler: async (ctx) => {
    // Payment is critical - always rollback on failure
    await ctx.step('payment', chargeHandler, refundHandler, { critical: true });

    // Analytics is not critical - won't rollback
    await ctx.step('analytics', trackHandler, rollbackAnalytics, { critical: false });

    // Inventory reservation fails
    await ctx.step('inventory', reserveHandler);

    // Only 'payment' is rolled back
  },
});

to_checkpoint​

Rolls back only to the most recent checkpoint:

await ductape.features.define({
  options: { rollback_strategy: 'to_checkpoint' },
  handler: async (ctx) => {
    await ctx.step('create-user', createHandler, deleteUser);

    await ctx.checkpoint('user-created');  // Checkpoint here

    await ctx.step('payment', chargeHandler, refundHandler);
    await ctx.step('inventory', reserveHandler, releaseHandler);

    // If inventory fails: only payment is rolled back
    // create-user is NOT rolled back (before checkpoint)
  },
});

none​

Disable automatic rollbacks entirely:

await ductape.features.define({
  options: { rollback_strategy: 'none' },
  handler: async (ctx) => {
    // No automatic rollbacks - handle failures manually
    try {
      await ctx.step('risky-operation', handler);
    } catch (error) {
      // Manual cleanup
      await ctx.triggerRollback('Manual rollback triggered');
    }
  },
});

Step Options for Failure Handling​

allow_fail​

Continue feature execution even if the step fails:

await ctx.step(
  'send-notification',
  async () => {
    await ctx.notification.email({ /* ... */ });
  },
  null,
  { allow_fail: true }  // Feature continues if this fails
);

retries and retry_delay​

Automatically retry failed steps:

await ctx.step(
  'external-api-call',
  async () => {
    return ctx.api.run({
      app: 'external-service',
      event: 'fetch-data',
      input: {},
    });
  },
  null,
  {
    retries: 3,           // Retry up to 3 times
    retry_delay: 2000,    // Wait 2 seconds between retries
  }
);

timeout​

Set a maximum duration for step execution:

await ctx.step(
  'slow-operation',
  async () => {
    return ctx.api.run({
      app: 'slow-service',
      event: 'process',
      input: {},
    });
  },
  null,
  { timeout: 30000 }  // 30 second timeout
);

critical​

Mark a step as always requiring rollback:

// With 'critical_only' strategy, only critical steps roll back
await ctx.step(
  'payment',
  async () => ctx.api.run({ app: 'stripe', event: 'charge', input: {} }),
  async (result) => ctx.api.run({ app: 'stripe', event: 'refund', input: { body: { id: result.id } } }),
  { critical: true }
);

Manual Rollback​

Trigger rollback programmatically using ctx.triggerRollback():

handler: async (ctx) => {
  const payment = await ctx.step('payment', chargeHandler, refundHandler);

  // Check for fraud
  const fraudCheck = await ctx.step('fraud-check', async () => {
    return ctx.api.run({
      app: 'fraud-detection',
      event: 'analyze',
      input: { body: { transactionId: payment.id } },
    });
  });

  if (fraudCheck.riskScore > 0.8) {
    // Manually trigger rollback
    const result = await ctx.triggerRollback('High fraud risk detected');

    return {
      success: false,
      reason: 'fraud_detected',
      rolledBackSteps: result.rolled_back_steps,
    };
  }

  // Continue with order...
}

Rollback Result​

interface RollbackResult {
  success: boolean;
  rolled_back_steps: string[];
  failed_steps?: Array<{
    tag: string;
    error: string;
  }>;
  reason: string;
}

Checkpoints​

Create checkpoints to save progress and control rollback scope:

handler: async (ctx) => {
  // Phase 1: User setup
  await ctx.step('create-user', createUser, deleteUser);
  await ctx.step('verify-email', sendVerification);

  // Checkpoint after user is fully created
  await ctx.checkpoint('user-setup-complete', {
    userId: ctx.steps['create-user'].id,
  });

  // Phase 2: Payment processing
  await ctx.step('payment', chargeCard, refundCard);

  // Checkpoint after payment
  await ctx.checkpoint('payment-complete', {
    chargeId: ctx.steps['payment'].id,
  });

  // Phase 3: Fulfillment
  await ctx.step('ship-order', shipOrder, cancelShipment);

  // If shipping fails with 'to_checkpoint' strategy:
  // - Only 'ship-order' is rolled back
  // - User and payment remain intact
}

Accessing Checkpoints​

// In your handler
const lastCheckpoint = ctx.checkpoint_name;  // e.g., 'payment-complete'
const checkpointData = ctx.checkpoint_data;  // { chargeId: '...' }

Signals​

Wait for external events during feature execution:

Waiting for Signals​

handler: async (ctx) => {
  // Create order
  const order = await ctx.step('create-order', createOrder);

  // Wait for manual approval
  const approval = await ctx.waitForSignal('order-approved', {
    timeout: '24h',
  });

  console.log('Approved by:', approval.approvedBy);
  console.log('Comments:', approval.comments);

  // Continue with fulfillment
  await ctx.step('fulfill', fulfillOrder);
}

Sending Signals​

From outside the feature, send a signal to continue execution:

await ductape.features.signal({
  feature_id: 'wf-abc123',
  signal: 'order-approved',
  payload: {
    approvedBy: 'manager@company.com',
    comments: 'Approved for processing',
    timestamp: Date.now(),
  },
});

Multiple Signals​

Wait for any of multiple possible signals:

const result = await ctx.waitForSignal(['approved', 'rejected', 'escalated'], {
  timeout: '48h',
});

// Check which signal was received
if (result._signal === 'approved') {
  await ctx.step('process', processOrder);
} else if (result._signal === 'rejected') {
  await ctx.triggerRollback('Order rejected');
} else if (result._signal === 'escalated') {
  await ctx.step('notify-manager', notifyManager);
}

Querying Feature Status​

Check the status of running or completed features:

// Get feature status
const status = await ductape.features.status({
  feature_id: 'wf-abc123',
});

console.log('Status:', status.status);
console.log('Current step:', status.current_step);
console.log('Completed steps:', status.completed_steps);
console.log('State:', status.state);

Query Handlers​

Define queries in your feature definition:

await ductape.features.define({
  tag: 'order-feature',

  queries: {
    'getProgress': {
      handler: (ctx) => ({
        completedSteps: ctx.completed_steps.length,
        totalSteps: 5,
        currentStep: ctx.current_step,
        percentComplete: (ctx.completed_steps.length / 5) * 100,
      }),
    },
    'getOrderDetails': {
      handler: (ctx) => ({
        orderId: ctx.input.orderId,
        status: ctx.state.orderStatus,
        paymentId: ctx.steps['payment']?.id,
      }),
    },
  },

  handler: async (ctx) => { /* ... */ },
});

// Query from outside
const progress = await ductape.features.query({
  feature_id: 'wf-abc123',
  query: 'getProgress',
});

Cancelling Features​

Cancel a running feature:

const result = await ductape.features.cancel({
  feature_id: 'wf-abc123',
  reason: 'User requested cancellation',
});

console.log('Cancelled:', result.cancelled);
console.log('Rolled back steps:', result.rolled_back_steps);

Dispatching Features​

Dispatch features to run on a schedule or at a specific time:

Schedule for Later​

// Run feature in 1 hour
const result = await ductape.features.dispatch({
  feature: 'order-fulfillment',
  input: { orderId: 'ORD-123' },
  schedule: {
    start_at: Date.now() + 3600000, // 1 hour from now
  },
});

console.log('Scheduled job ID:', result.job_id);
console.log('Scheduled for:', result.scheduled_at);

Cron Schedule​

// Run daily at midnight
const result = await ductape.features.dispatch({
  feature: 'daily-report',
  input: { reportType: 'sales' },
  schedule: {
    cron: '0 0 * * *', // Every day at midnight
  },
});

Recurring Dispatch​

// Run every hour with retry options
const result = await ductape.features.dispatch({
  feature: 'sync-inventory',
  input: { source: 'warehouse-a' },
  schedule: {
    cron: '0 * * * *', // Every hour
    timezone: 'America/New_York',
  },
  options: {
    retries: 3,
    timeout: 300000,
  },
});

Replay, Restart & Resume​

Ductape Features track execution state persistently, enabling powerful recovery capabilities:

OperationDescriptionInputState
ReplayRe-execute with same inputOriginalFresh
RestartRe-execute with new/modified inputNew/ModifiedFresh
ResumeContinue from last stateOriginalPreserved

Replay Feature​

Re-execute a feature using the same input from a previous execution:

// Replay a failed feature
const replayResult = await ductape.features.replay({
  feature_id: 'wf-abc123',
  reason: 'Debugging payment failure',
});

console.log(replayResult.feature_id);     // New feature ID
console.log(replayResult.replayed_from);  // Original: 'wf-abc123'

Replay with Options​

const replayResult = await ductape.features.replay({
  feature_id: 'wf-abc123',
  options: {
    retries: 5,
    timeout: 120000,
    debug: true,
  },
  reason: 'Debugging payment failure',
  idempotency_key: 'replay-wf-abc123-attempt-2',
});

Detecting Replay in Handler​

handler: async (ctx) => {
  if (ctx.is_replay) {
    ctx.log.info('Replaying feature', {
      original_id: ctx.replayed_from,
      reason: ctx.replay_reason,
    });
  }

  // Normal feature logic...
}

Restart Feature​

Reset and re-execute with new or modified input:

// Restart with corrected input
const restartResult = await ductape.features.restart({
  feature_id: 'wf-abc123',
  input: {
    orderId: 'ORD-123',
    email: 'corrected@email.com', // Fixed email
  },
  reason: 'Customer email was incorrect',
});

Partial Input Override​

// Only override specific fields, merge with original
const restartResult = await ductape.features.restart({
  feature_id: 'wf-abc123',
  input_override: {
    email: 'corrected@email.com',
  },
  merge_input: true,
});

Resume Feature​

Continue a feature from where it stopped (paused, failed, or crashed):

// Resume a paused feature
const resumeResult = await ductape.features.resume({
  feature_id: 'wf-abc123',
});

Resume from Checkpoint​

// Resume from a specific checkpoint
const resumeResult = await ductape.features.resume({
  feature_id: 'wf-abc123',
  from_checkpoint: 'payment-complete',
  input: {
    retry_payment: false,
  },
});

Resume from Failed Step​

// Resume from the step that failed
const resumeResult = await ductape.features.resume({
  feature_id: 'wf-abc123',
  from_step: 'create-shipment',
  skip_steps: ['send-confirmation'], // Skip problematic step
});

Handling Resume in Handler​

handler: async (ctx) => {
  if (ctx.is_restored) {
    ctx.log.info('Resuming feature', {
      from_checkpoint: ctx.restored_checkpoint?.name,
      completed_steps: ctx.completed_steps,
    });
  }

  // Check if step already completed before running
  if (!ctx.completed_steps.includes('validate-order')) {
    await ctx.step('validate-order', async () => {
      // Validation logic...
    });
  }

  await ctx.checkpoint('validation-complete');

  if (!ctx.completed_steps.includes('process-payment')) {
    await ctx.step('process-payment', async () => {
      // Payment logic...
    });
  }

  // Continue with remaining steps...
}

Replay from Step​

Re-execute starting from a specific step, using state from the original execution:

const result = await ductape.features.replayFromStep({
  feature_id: 'wf-abc123',
  from_step: 'create-shipment',
});

Step Replay with State Override​

// Replay from step with corrected previous step outputs
const result = await ductape.features.replayFromStep({
  feature_id: 'wf-abc123',
  from_step: 'process-payment',
  step_outputs: {
    'validate-order': {
      valid: true,
      total: 150.00, // Corrected total
    },
  },
});

Feature History​

Get detailed execution history for debugging and auditing:

Get Execution History​

const history = await ductape.features.history({
  feature_id: 'wf-abc123',
});

console.log(history.events);
// [
//   { type: 'feature_started', timestamp: 1701936000000, data: { input: {...} } },
//   { type: 'step_started', timestamp: 1701936001000, data: { step: 'validate-order' } },
//   { type: 'step_completed', timestamp: 1701936002000, data: { step: 'validate-order', output: {...} } },
//   { type: 'checkpoint_created', timestamp: 1701936003000, data: { name: 'validation-complete' } },
//   { type: 'step_started', timestamp: 1701936004000, data: { step: 'process-payment' } },
//   { type: 'step_failed', timestamp: 1701936005000, data: { step: 'process-payment', error: {...} } },
//   { type: 'rollback_started', timestamp: 1701936006000, data: {} },
//   { type: 'feature_rolled_back', timestamp: 1701936008000, data: {} },
// ]

Get Step Details​

const stepDetail = await ductape.features.stepDetail({
  feature_id: 'wf-abc123',
  step_tag: 'process-payment',
});

console.log(stepDetail);
// {
//   tag: 'process-payment',
//   status: 'failed',
//   input: { body: { amount: 100, customer_id: 'CUST-123' } },
//   output: null,
//   error: { message: 'Card declined', code: 'card_declined' },
//   attempts: 3,
//   duration: 1000,
//   rollback_status: 'completed',
// }

Find all replays, restarts, and resumes of a feature:

const related = await ductape.features.relatedExecutions({
  feature_id: 'wf-abc123',
});

console.log(related.executions);
// [
//   { feature_id: 'wf-abc123', type: 'original', status: 'failed' },
//   { feature_id: 'wf-def456', type: 'replay', status: 'failed', replayed_from: 'wf-abc123' },
//   { feature_id: 'wf-ghi789', type: 'restart', status: 'completed', restarted_from: 'wf-abc123' },
// ]

Compare Executions​

Compare two executions to see what changed:

const comparison = await ductape.features.compare({
  feature_ids: ['wf-abc123', 'wf-ghi789'],
});

console.log(comparison.input_diff);
// { email: ['wrong@email.com', 'correct@email.com'] }

console.log(comparison.step_diffs);
// [
//   {
//     step: 'process-payment',
//     'wf-abc123': { status: 'failed', error: 'Card declined' },
//     'wf-ghi789': { status: 'completed', output: { charge_id: 'ch_123' } },
//   },
// ]

Child Features​

Run features as children of other features:

handler: async (ctx) => {
  // Run payment as a child feature
  const paymentResult = await ctx.feature(
    'payment-' + ctx.input.orderId,   // Child feature ID
    'payment-processing',              // Feature tag
    {                                  // Input
      amount: ctx.input.amount,
      customerId: ctx.input.customerId,
    },
    {
      timeout: '5m',
      retries: 2,
      parent_close_policy: 'terminate',  // Cancel child if parent fails
    }
  );

  ctx.log.info('Payment completed', { chargeId: paymentResult.chargeId });
}

Parent Close Policies​

PolicyDescription
terminateCancel child feature when parent completes/fails
abandonLet child feature continue independently
request_cancelRequest cancellation but don't force it

Error Handling​

Try-Catch in Steps​

await ctx.step('risky-operation', async () => {
  try {
    return await ctx.api.run({
      app: 'unreliable-service',
      event: 'fetch',
      input: {},
    });
  } catch (error) {
    ctx.log.warn('Primary service failed, using fallback', { error: error.message });

    return await ctx.api.run({
      app: 'fallback-service',
      event: 'fetch',
      input: {},
    });
  }
});

Fallback Component​

Use the fallback component for structured failure handling:

const result = await ctx.fallback.execute({
  fallback: 'payment-fallback',
  input: {
    amount: ctx.input.amount,
    method: ctx.input.paymentMethod,
  },
  timeout: 30000,
});

Best Practices​

1. Always Define Rollback Handlers for Critical Operations​

// Good: Payment has rollback
await ctx.step('payment', chargeCard, refundCard);

// Bad: No way to undo if later steps fail
await ctx.step('payment', chargeCard);

2. Use Checkpoints for Long Features​

// Break long features into phases with checkpoints
await ctx.checkpoint('phase-1-complete');
// ...later steps won't roll back phase 1

3. Mark Non-Critical Steps with allow_fail​

// Email failures shouldn't stop order processing
await ctx.step('send-email', sendEmail, null, { allow_fail: true });

4. Use Idempotency Keys for Retries​

await ctx.api.run({
  app: 'stripe',
  event: 'charge',
  input: {
    body: { amount: 1000 },
    headers: { 'Idempotency-Key': `${ctx.feature_id}-payment` },
  },
});

5. Log Important State Changes​

ctx.log.info('Order status changed', {
  orderId: order.id,
  from: 'pending',
  to: 'processing',
});

Next Steps​