reqon-dsl 0.2.0 → 0.4.0

package/docusaurus/docs/error-handling/dead-letter-queues.md

@@ -1,399 +0,0 @@
----
-sidebar_position: 3
----
-
-# Dead Letter Queues
-
-Dead letter queues (DLQ) store failed items for later processing. They prevent data loss when errors occur and allow for manual or automated retry.
-
-## Basic Usage
-
-```vague
-mission DataSync {
-  store data: file("data")
-  store dlq: file("dead-letter-queue")
-
-  action FetchData {
-    get "/items"
-
-    for item in response.items {
-      get concat("/items/", item.id, "/details")
-
-      match response {
-        { error: e } -> queue dlq {
-          item: {
-            itemId: item.id,
-            error: e,
-            timestamp: now()
-          }
-        },
-        _ -> store response -> data { key: item.id }
-      }
-    }
-  }
-
-  run FetchData
-}
-```
-
-## Queue Directive Syntax
-
-```vague
-queue storeName {
-  item: objectToStore,
-  key: optionalKey
-}
-```
-
-### With Key
-
-```vague
-queue dlq {
-  item: { error: "failed" },
-  key: concat("error-", item.id)
-}
-```
-
-### Without Key (Auto-Generated)
-
-```vague
-queue dlq {
-  item: { error: "failed" }
-}
-```
-
-## What to Include
-
-### Minimum Information
-
-```vague
-queue dlq {
-  item: {
-    id: item.id,
-    error: response.error,
-    timestamp: now()
-  }
-}
-```
-
-### Full Context
-
-```vague
-queue dlq {
-  item: {
-    // Identifiers
-    id: item.id,
-    batchId: batchId,
-
-    // Original data
-    originalItem: item,
-
-    // Error details
-    error: response.error,
-    errorCode: response.code,
-    errorDetails: response.details,
-
-    // Context
-    action: "FetchDetails",
-    source: "ExternalAPI",
-
-    // Timing
-    timestamp: now(),
-    attemptCount: 1,
-
-    // For retry
-    retryable: response.code >= 500
-  }
-}
-```
-
-## DLQ Patterns
-
-### Simple Error Queue
-
-```vague
-mission Simple {
-  store dlq: file("errors")
-
-  action Process {
-    for item in items {
-      get concat("/api/", item.id)
-
-      match response {
-        { error: _ } -> queue dlq { item: { id: item.id, response: response } },
-        _ -> continue
-      }
-    }
-  }
-}
-```
-
-### Categorized Queues
-
-```vague
-mission Categorized {
-  store retryable: file("retryable-errors")
-  store permanent: file("permanent-errors")
-  store validation: file("validation-errors")
-
-  action Process {
-    for item in items {
-      get concat("/api/", item.id)
-
-      match response {
-        // Retryable errors
-        { code: 429 } -> queue retryable { item: { id: item.id, reason: "rate_limit" } },
-        { code: 500 } -> queue retryable { item: { id: item.id, reason: "server_error" } },
-        { code: 503 } -> queue retryable { item: { id: item.id, reason: "unavailable" } },
-
-        // Permanent errors
-        { code: 401 } -> queue permanent { item: { id: item.id, reason: "auth" } },
-        { code: 403 } -> queue permanent { item: { id: item.id, reason: "forbidden" } },
-        { code: 404 } -> queue permanent { item: { id: item.id, reason: "not_found" } },
-
-        // Validation errors
-        { code: 400 } -> queue validation { item: { id: item.id, details: response } },
-
-        // Success
-        _ -> continue
-      }
-    }
-  }
-}
-```
-
-### DLQ with Retry Counter
-
-```vague
-for item in items {
-  get concat("/api/", item.id)
-
-  match response {
-    { error: _ } where item.retryCount >= 3 -> {
-      // Max retries exceeded
-      queue permanentFailures {
-        item: { ...item, finalError: response.error }
-      }
-      skip
-    },
-    { error: _ } -> {
-      // Queue for retry
-      queue retryQueue {
-        item: {
-          ...item,
-          retryCount: (item.retryCount or 0) + 1,
-          lastError: response.error
-        }
-      }
-      skip
-    },
-    _ -> continue
-  }
-}
-```
-
-## Processing DLQ
-
-### Manual Review
-
-Export and review:
-
-```bash
-reqon mission.vague --output ./exports/
-# Review exports/dead-letter-queue.json
-```
-
-### Automated Retry
-
-Create a retry mission:
-
-```vague
-mission RetryFailed {
-  store dlq: file("dead-letter-queue")
-  store data: file("data")
-  store permanentFailed: file("permanent-failures")
-
-  action RetryItems {
-    for item in dlq where .retryable == true {
-      get concat("/api/", item.originalItem.id)
-
-      match response {
-        { error: _ } where item.attemptCount >= 5 -> {
-          // Give up after 5 attempts
-          store {
-            ...item,
-            finalError: response.error
-          } -> permanentFailed { key: item.id }
-          delete dlq[item.id]
-        },
-        { error: _ } -> {
-          // Update retry count
-          store {
-            ...item,
-            attemptCount: item.attemptCount + 1,
-            lastAttempt: now(),
-            lastError: response.error
-          } -> dlq { key: item.id }
-        },
-        _ -> {
-          // Success! Remove from DLQ
-          store response -> data { key: item.originalItem.id }
-          delete dlq[item.id]
-        }
-      }
-    }
-  }
-
-  run RetryItems
-}
-```
-
-### Scheduled Retry
-
-```vague
-mission ScheduledRetry {
-  schedule: every 1 hour
-
-  store dlq: file("dead-letter-queue")
-
-  action RetryEligible {
-    for item in dlq where .lastAttempt < addHours(now(), -1) {
-      // Retry items not attempted in the last hour
-      // ... retry logic
-    }
-  }
-
-  run RetryEligible
-}
-```
-
-## DLQ with Notifications
-
-```vague
-action NotifyOnFailure {
-  for item in items {
-    get concat("/api/", item.id)
-
-    match response {
-      { error: e } -> {
-        // Queue for retry
-        queue dlq { item: { id: item.id, error: e } }
-
-        // Check if threshold exceeded
-        match dlq {
-          _ where length(dlq) > 100 -> {
-            // Too many failures - alert
-            post NotificationAPI "/alerts" {
-              body: {
-                message: "DLQ threshold exceeded",
-                count: length(dlq),
-                timestamp: now()
-              }
-            }
-          },
-          _ -> continue
-        }
-      },
-      _ -> continue
-    }
-  }
-}
-```
-
-## Best Practices
-
-### Include Enough Context
-
-```vague
-queue dlq {
-  item: {
-    // What failed
-    id: item.id,
-    originalData: item,
-
-    // Why it failed
-    error: response.error,
-    errorCode: response.code,
-
-    // When it failed
-    timestamp: now(),
-
-    // Can we retry?
-    retryable: response.code >= 500,
-
-    // How many times have we tried?
-    attemptCount: 1
-  }
-}
-```
-
-### Separate Retryable vs Permanent
-
-```vague
-// Retryable: server errors, rate limits
-queue retryQueue { item: { ... } }
-
-// Permanent: validation errors, not found
-queue permanentQueue { item: { ... } }
-```
-
-### Set Retention Policies
-
-Periodically clean old entries:
-
-```vague
-action CleanOldEntries {
-  for item in dlq where .timestamp < addDays(now(), -30) {
-    // Archive or delete items older than 30 days
-    delete dlq[item.id]
-  }
-}
-```
-
-### Monitor Queue Size
-
-```vague
-action MonitorDLQ {
-  match dlq {
-    _ where length(dlq) > 1000 -> {
-      // Alert on large queue
-      store {
-        alert: "DLQ size exceeded 1000",
-        size: length(dlq),
-        timestamp: now()
-      } -> alerts
-    },
-    _ -> continue
-  }
-}
-```
-
-## Troubleshooting
-
-### Queue Growing Too Fast
-
-1. Check for systemic issues
-2. Review error patterns
-3. Fix root cause before retrying
-
-### Items Never Succeed
-
-Mark as permanent failure:
-
-```vague
-match item {
-  _ where item.attemptCount > 10 -> {
-    store item -> permanentFailures { key: item.id }
-    delete dlq[item.id]
-  },
-  _ -> continue
-}
-```
-
-### Duplicate Processing
-
-Use idempotent operations:
-
-```vague
-store response -> data { key: item.id, upsert: true }
-```

package/docusaurus/docs/error-handling/flow-control.md

@@ -1,337 +0,0 @@
----
-sidebar_position: 1
----
-
-# Flow Control Directives
-
-Flow control directives determine what happens after pattern matching. They provide fine-grained control over error handling and execution flow.
-
-## Available Directives
-
-| Directive | Description |
-|-----------|-------------|
-| `continue` | Proceed to next step |
-| `skip` | Skip remaining steps in current iteration |
-| `abort` | Stop mission with error |
-| `retry` | Retry previous request with backoff |
-| `queue` | Send to dead letter queue |
-| `jump...then` | Execute action, then continue |
-
-## Continue
-
-Proceed to the next step normally:
-
-```vague
-match response {
-  { data: _ } -> continue,
-  _ -> abort "No data"
-}
-
-// Execution continues here
-store response.data -> data { key: .id }
-```
-
-Use `continue` when:
-- Pattern matches expected success case
-- You want explicit confirmation of flow
-
-## Skip
-
-Skip remaining steps in the current loop iteration:
-
-```vague
-for item in items {
-  match item {
-    { status: "inactive" } -> skip,
-    { status: "deleted" } -> skip,
-    _ -> continue
-  }
-
-  // Only runs for active, non-deleted items
-  store item -> activeItems { key: .id }
-}
-```
-
-Use `skip` when:
-- Item should be ignored but processing should continue
-- Filtering within a loop
-- Handling non-critical errors
-
-## Abort
-
-Stop mission execution immediately:
-
-```vague
-match response {
-  { error: msg } -> abort msg,
-  { error: _ } -> abort "Unknown error occurred",
-  _ -> continue
-}
-```
-
-With custom message:
-
-```vague
-match response {
-  { code: 401 } -> abort "Authentication failed - check credentials",
-  { code: 403 } -> abort "Permission denied - check API permissions",
-  { code: 404 } -> abort "Resource not found",
-  { code: 500 } -> abort "Server error - try again later",
-  _ -> continue
-}
-```
-
-Use `abort` when:
-- Unrecoverable error occurs
-- Critical validation fails
-- Continuing would cause data corruption
-
-## Retry
-
-Retry the previous HTTP request:
-
-```vague
-match response {
-  { error: _, code: 429 } -> retry {
-    maxAttempts: 5,
-    backoff: exponential,
-    initialDelay: 1000,
-    maxDelay: 60000
-  },
-  _ -> continue
-}
-```
-
-### Retry Options
-
-| Option | Description | Default |
-|--------|-------------|---------|
-| `maxAttempts` | Maximum retry attempts | 3 |
-| `backoff` | Strategy: `exponential`, `linear`, `constant` | `exponential` |
-| `initialDelay` | First retry delay (ms) | 1000 |
-| `maxDelay` | Maximum delay (ms) | 30000 |
-| `delay` | Fixed delay (overrides backoff) | - |
-
-### Simple Retry
-
-```vague
-match response {
-  { code: 503 } -> retry,  // Uses defaults
-  _ -> continue
-}
-```
-
-### Fixed Delay
-
-```vague
-match response {
-  { code: 429, headers: h } -> retry {
-    delay: h["Retry-After"] * 1000
-  },
-  _ -> continue
-}
-```
-
-## Queue
-
-Send failed items to a dead letter queue:
-
-```vague
-match response {
-  { error: e } -> queue dlq {
-    item: {
-      request: currentRequest,
-      error: e,
-      timestamp: now()
-    }
-  },
-  _ -> continue
-}
-```
-
-### Queue Options
-
-```vague
-queue queueName {
-  item: itemToStore,
-  key: optionalKey
-}
-```
-
-Store the queue as a regular store:
-
-```vague
-mission ErrorHandling {
-  store dlq: file("dead-letter-queue")
-
-  action Process {
-    get "/data"
-
-    match response {
-      { error: e } -> queue dlq { item: { error: e } },
-      _ -> continue
-    }
-  }
-}
-```
-
-## Jump Then
-
-Execute another action, then continue or retry:
-
-```vague
-match response {
-  { code: 401 } -> jump RefreshToken then retry,
-  _ -> continue
-}
-
-action RefreshToken {
-  post "/auth/refresh" {
-    body: { refreshToken: env("REFRESH_TOKEN") }
-  }
-}
-```
-
-### Jump Then Retry
-
-Common pattern for token refresh:
-
-```vague
-action FetchData {
-  get "/protected-resource"
-
-  match response {
-    { code: 401 } -> jump RefreshToken then retry,
-    _ -> store response -> data { key: .id }
-  }
-}
-
-action RefreshToken {
-  post "/oauth/token" {
-    body: {
-      grant_type: "refresh_token",
-      refresh_token: env("REFRESH_TOKEN")
-    }
-  }
-  // New token is automatically used
-}
-```
-
-### Jump Then Continue
-
-```vague
-match response {
-  { needsSetup: true } -> jump SetupResource then continue,
-  _ -> continue
-}
-```
-
-## Combining Directives
-
-### Layered Error Handling
-
-```vague
-match response {
-  // Retry transient errors
-  { code: 429 } -> retry { maxAttempts: 5 },
-  { code: 503 } -> retry { maxAttempts: 3 },
-  { code: 504 } -> retry { maxAttempts: 3 },
-
-  // Handle auth separately
-  { code: 401 } -> jump RefreshToken then retry,
-
-  // Queue unrecoverable errors
-  { code: 400, error: e } -> queue dlq { item: { error: e } },
-
-  // Abort on critical errors
-  { code: 500, error: e } -> abort e,
-
-  // Skip missing resources
-  { code: 404 } -> skip,
-
-  // Continue on success
-  _ -> continue
-}
-```
-
-### Per-Item Error Handling
-
-```vague
-for item in items {
-  get concat("/items/", item.id)
-
-  match response {
-    { error: _, code: 404 } -> {
-      // Log and skip
-      store { id: item.id, status: "not_found" } -> missing
-      skip
-    },
-    { error: e } -> {
-      // Queue for retry
-      queue failed { item: { id: item.id, error: e } }
-      skip
-    },
-    _ -> continue
-  }
-
-  store response -> processedItems { key: .id }
-}
-```
-
-## Best Practices
-
-### Be Specific
-
-```vague
-// Good: specific error handling
-match response {
-  { code: 401 } -> jump RefreshToken then retry,
-  { code: 403 } -> abort "Permission denied",
-  { code: 429 } -> retry { delay: 60000 },
-  { code: 404 } -> skip,
-  { error: e } -> abort e,
-  _ -> continue
-}
-
-// Avoid: too generic
-match response {
-  { error: _ } -> retry,
-  _ -> continue
-}
-```
-
-### Always Have a Default
-
-```vague
-match response {
-  { status: "ok" } -> continue,
-  { status: "error" } -> abort "Error",
-  _ -> abort "Unexpected response"  // Always have catch-all
-}
-```
-
-### Log Before Abort
-
-```vague
-match response {
-  { error: e } -> {
-    store { error: e, timestamp: now() } -> errorLog
-    abort e
-  },
-  _ -> continue
-}
-```
-
-### Use Queue for Later Processing
-
-```vague
-match response {
-  { error: "rate_limit" } -> queue retryQueue {
-    item: {
-      request: currentRequest,
-      retryAfter: response.retryAfter
-    }
-  },
-  _ -> continue
-}
-```