reqon-dsl 0.2.0

package/docusaurus/docs/http/requests.md

@@ -0,0 +1,328 @@
+---
+sidebar_position: 1
+---
+
+# HTTP Requests
+
+Reqon provides powerful HTTP request handling with built-in support for pagination, retries, rate limiting, and more.
+
+## Request Methods
+
+```vague
+// GET - Retrieve data
+get "/users"
+
+// POST - Create data
+post "/users" { body: { name: "John" } }
+
+// PUT - Replace data
+put "/users/123" { body: { name: "Jane" } }
+
+// PATCH - Partial update
+patch "/users/123" { body: { email: "jane@example.com" } }
+
+// DELETE - Remove data
+delete "/users/123"
+```
+
+## Request Options
+
+### Query Parameters
+
+Add query parameters to requests:
+
+```vague
+get "/users" {
+  params: {
+    limit: 100,
+    offset: 0,
+    status: "active",
+    sort: "created_at",
+    order: "desc"
+  }
+}
+```
+
+Generates: `GET /users?limit=100&offset=0&status=active&sort=created_at&order=desc`
+
+### Dynamic Parameters
+
+Use expressions in parameters:
+
+```vague
+get "/users" {
+  params: {
+    since: formatDate(lastSync, "YYYY-MM-DD"),
+    limit: env("PAGE_SIZE") or 100
+  }
+}
+```
+
+### Request Body
+
+Send JSON body with POST/PUT/PATCH:
+
+```vague
+post "/users" {
+  body: {
+    name: "John Doe",
+    email: "john@example.com",
+    metadata: {
+      source: "api",
+      importedAt: now()
+    }
+  }
+}
+```
+
+### Dynamic Body
+
+Build body from variables:
+
+```vague
+for user in usersToCreate {
+  post "/users" {
+    body: {
+      name: user.name,
+      email: user.email,
+      role: user.role or "user"
+    }
+  }
+}
+```
+
+### Custom Headers
+
+Override or add headers:
+
+```vague
+get "/data" {
+  headers: {
+    "Accept": "application/json",
+    "X-API-Version": "2.0",
+    "X-Request-ID": uuid()
+  }
+}
+```
+
+## Response Handling
+
+### Accessing Response Data
+
+The `response` variable contains the parsed JSON:
+
+```vague
+action FetchUsers {
+  get "/users"
+
+  // Access response data
+  for user in response.data {
+    store user -> users { key: .id }
+  }
+
+  // Access metadata
+  validate {
+    assume response.total > 0
+  }
+}
+```
+
+### Response Structure
+
+```vague
+// Common API response pattern
+{
+  "data": [...],
+  "meta": {
+    "total": 100,
+    "page": 1,
+    "perPage": 20
+  }
+}
+
+// Access in Reqon
+for item in response.data { }
+validate { assume response.meta.total > 0 }
+```
+
+## Working with Multiple Sources
+
+### Default Source
+
+The first defined source is the default:
+
+```vague
+mission Example {
+  source API { auth: bearer, base: "https://api.example.com" }
+
+  action Fetch {
+    get "/users"  // Uses API source
+  }
+}
+```
+
+### Named Source
+
+Specify source explicitly:
+
+```vague
+mission MultiSource {
+  source Primary { auth: bearer, base: "https://primary.api.com" }
+  source Backup { auth: bearer, base: "https://backup.api.com" }
+
+  action FetchFromBoth {
+    get Primary "/users"
+    store response -> primaryUsers { key: .id }
+
+    get Backup "/users"
+    store response -> backupUsers { key: .id }
+  }
+}
+```
+
+## Dynamic URLs
+
+Build URLs dynamically:
+
+```vague
+action FetchDetails {
+  for user in users {
+    // String concatenation
+    get concat("/users/", user.id)
+
+    // Nested resources
+    get concat("/users/", user.id, "/orders")
+
+    // Complex paths
+    get concat("/api/v", env("API_VERSION"), "/users/", user.id)
+  }
+}
+```
+
+## Request Timeouts
+
+Configure at source level:
+
+```vague
+source SlowAPI {
+  auth: bearer,
+  base: "https://slow.api.com",
+  timeout: 60000  // 60 seconds
+}
+```
+
+Or per-request (future feature):
+
+```vague
+get "/slow-endpoint" {
+  timeout: 120000  // 2 minutes
+}
+```
+
+## Error Handling
+
+Handle HTTP errors with match:
+
+```vague
+action SafeFetch {
+  get "/users"
+
+  match response {
+    { error: _, code: 401 } -> jump RefreshAuth then retry,
+    { error: _, code: 404 } -> skip,
+    { error: _, code: 429 } -> retry { delay: 60000 },
+    { error: e } -> abort e,
+    _ -> store response -> users { key: .id }
+  }
+}
+```
+
+## Request Chaining
+
+Chain requests with data from previous responses:
+
+```vague
+action FetchWithDetails {
+  // First request
+  get "/orders"
+
+  for order in response.orders {
+    // Use data from first request
+    get concat("/customers/", order.customerId)
+
+    map order -> EnrichedOrder {
+      ...order,
+      customer: response
+    }
+
+    store order -> enrichedOrders { key: .id }
+  }
+}
+```
+
+## Batching Requests
+
+For APIs that support batch operations:
+
+```vague
+action BatchFetch {
+  // Collect IDs
+  get "/items" { params: { status: "pending" } }
+
+  // Batch request
+  post "/items/batch" {
+    body: {
+      ids: response.items.map(.id)
+    }
+  }
+
+  store response -> batchResults
+}
+```
+
+## Best Practices
+
+### Use Descriptive Error Handling
+
+```vague
+match response {
+  { error: _, code: 400 } -> abort "Invalid request data",
+  { error: _, code: 401 } -> abort "Authentication failed",
+  { error: _, code: 403 } -> abort "Permission denied",
+  { error: _, code: 404 } -> abort "Resource not found",
+  { error: _, code: 429 } -> retry { delay: 60000 },
+  { error: _, code: 500 } -> retry { maxAttempts: 3 },
+  { error: e } -> abort e,
+  _ -> continue
+}
+```
+
+### Validate Before Processing
+
+```vague
+get "/data"
+
+validate response {
+  assume .data is array,
+  assume length(.data) > 0
+}
+
+for item in response.data { }
+```
+
+### Log Important Requests
+
+```vague
+get "/important-operation"
+
+match response {
+  { success: true } -> {
+    store { operation: "fetch", status: "success", timestamp: now() } -> logs
+    continue
+  },
+  _ -> {
+    store { operation: "fetch", status: "failed", response: response } -> logs
+    abort "Operation failed"
+  }
+}
+```

package/docusaurus/docs/http/retry.md

@@ -0,0 +1,402 @@
+---
+sidebar_position: 3
+---
+
+# Retry Strategies
+
+Reqon provides built-in retry handling for transient failures with configurable backoff strategies.
+
+## Basic Retry Configuration
+
+```vague
+get "/data" {
+  retry: {
+    maxAttempts: 3,
+    backoff: exponential,
+    initialDelay: 1000,
+    maxDelay: 30000
+  }
+}
+```
+
+## Retry Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `maxAttempts` | Maximum number of retry attempts | 3 |
+| `backoff` | Backoff strategy | `exponential` |
+| `initialDelay` | First retry delay (ms) | 1000 |
+| `maxDelay` | Maximum delay between retries (ms) | 30000 |
+
+## Backoff Strategies
+
+### Exponential Backoff
+
+Doubles the delay after each attempt:
+
+```vague
+get "/data" {
+  retry: {
+    maxAttempts: 5,
+    backoff: exponential,
+    initialDelay: 1000
+  }
+}
+```
+
+Timing:
+- Attempt 1: immediate
+- Attempt 2: wait 1000ms
+- Attempt 3: wait 2000ms
+- Attempt 4: wait 4000ms
+- Attempt 5: wait 8000ms
+
+### Linear Backoff
+
+Adds a fixed delay each time:
+
+```vague
+get "/data" {
+  retry: {
+    maxAttempts: 5,
+    backoff: linear,
+    initialDelay: 2000
+  }
+}
+```
+
+Timing:
+- Attempt 1: immediate
+- Attempt 2: wait 2000ms
+- Attempt 3: wait 4000ms
+- Attempt 4: wait 6000ms
+- Attempt 5: wait 8000ms
+
+### Constant Backoff
+
+Same delay every time:
+
+```vague
+get "/data" {
+  retry: {
+    maxAttempts: 5,
+    backoff: constant,
+    initialDelay: 5000
+  }
+}
+```
+
+Timing:
+- Attempt 1: immediate
+- Attempt 2: wait 5000ms
+- Attempt 3: wait 5000ms
+- Attempt 4: wait 5000ms
+- Attempt 5: wait 5000ms
+
+## Maximum Delay
+
+Cap the maximum delay:
+
+```vague
+get "/data" {
+  retry: {
+    maxAttempts: 10,
+    backoff: exponential,
+    initialDelay: 1000,
+    maxDelay: 30000  // Cap at 30 seconds
+  }
+}
+```
+
+Without maxDelay, exponential backoff would reach:
+- Attempt 8: 128 seconds
+- Attempt 9: 256 seconds
+- Attempt 10: 512 seconds
+
+With `maxDelay: 30000`, all delays are capped at 30 seconds.
+
+## Conditional Retry
+
+Use `match` for conditional retry logic:
+
+```vague
+action FetchWithConditionalRetry {
+  get "/data"
+
+  match response {
+    // Retry on rate limit
+    { error: _, code: 429 } -> retry {
+      maxAttempts: 5,
+      backoff: exponential,
+      initialDelay: 60000  // Start with 1 minute
+    },
+
+    // Retry on server errors
+    { error: _, code: 500 } -> retry {
+      maxAttempts: 3,
+      backoff: exponential,
+      initialDelay: 5000
+    },
+
+    // Retry on timeout
+    { error: "timeout" } -> retry {
+      maxAttempts: 3,
+      backoff: constant,
+      initialDelay: 10000
+    },
+
+    // Don't retry client errors
+    { error: _, code: 400 } -> abort "Bad request",
+    { error: _, code: 401 } -> abort "Unauthorized",
+    { error: _, code: 404 } -> skip,
+
+    // Success
+    _ -> continue
+  }
+}
+```
+
+## Retry After Header
+
+Reqon respects the `Retry-After` header when present:
+
+```vague
+get "/rate-limited-api" {
+  retry: {
+    maxAttempts: 5,
+    backoff: exponential,
+    initialDelay: 1000
+  }
+}
+```
+
+If the API returns:
+```http
+HTTP/1.1 429 Too Many Requests
+Retry-After: 60
+```
+
+Reqon will wait 60 seconds before retrying, regardless of backoff settings.
+
+## Combining with Other Features
+
+### With Pagination
+
+```vague
+get "/items" {
+  paginate: offset(offset, 100),
+  until: length(response) == 0,
+  retry: {
+    maxAttempts: 3,
+    backoff: exponential
+  }
+}
+```
+
+Each page request uses retry logic independently.
+
+### With Rate Limiting
+
+```vague
+source API {
+  auth: bearer,
+  base: "https://api.example.com",
+  rateLimit: {
+    requestsPerMinute: 60,
+    strategy: "pause"
+  }
+}
+
+action Fetch {
+  get "/items" {
+    retry: {
+      maxAttempts: 3,
+      backoff: exponential
+    }
+  }
+}
+```
+
+Rate limiting runs before retry; retry handles unexpected failures.
+
+## Jump and Retry
+
+For complex retry scenarios like token refresh:
+
+```vague
+action FetchData {
+  get "/protected-data"
+
+  match response {
+    { error: _, code: 401 } -> jump RefreshToken then retry,
+    _ -> store response -> data { key: .id }
+  }
+}
+
+action RefreshToken {
+  post "/auth/refresh" {
+    body: { refreshToken: env("REFRESH_TOKEN") }
+  }
+
+  // Token is automatically used in subsequent requests
+}
+```
+
+The `jump RefreshToken then retry` directive:
+1. Executes the `RefreshToken` action
+2. Retries the original request with the new token
+
+## Per-Source Retry Configuration
+
+Configure default retry at the source level:
+
+```vague
+source UnreliableAPI {
+  auth: bearer,
+  base: "https://flaky.api.com",
+  retry: {
+    maxAttempts: 5,
+    backoff: exponential,
+    initialDelay: 2000,
+    maxDelay: 60000
+  }
+}
+
+action Fetch {
+  // Uses source-level retry config
+  get "/data"
+}
+```
+
+Request-level config overrides source-level:
+
+```vague
+action FetchWithOverride {
+  get "/data" {
+    retry: {
+      maxAttempts: 10  // Override just maxAttempts
+    }
+  }
+}
+```
+
+## Best Practices
+
+### Use Exponential Backoff for APIs
+
+```vague
+get "/api/data" {
+  retry: {
+    maxAttempts: 5,
+    backoff: exponential,
+    initialDelay: 1000,
+    maxDelay: 30000
+  }
+}
+```
+
+### Handle Specific Error Codes
+
+```vague
+match response {
+  // Transient errors - retry
+  { code: 429 } -> retry { maxAttempts: 5 },
+  { code: 503 } -> retry { maxAttempts: 3 },
+  { code: 504 } -> retry { maxAttempts: 3 },
+
+  // Permanent errors - don't retry
+  { code: 400 } -> abort "Bad request",
+  { code: 401 } -> abort "Unauthorized",
+  { code: 403 } -> abort "Forbidden",
+  { code: 404 } -> skip,
+
+  _ -> continue
+}
+```
+
+### Set Reasonable Limits
+
+```vague
+// Good: reasonable limits
+retry: {
+  maxAttempts: 5,
+  maxDelay: 60000
+}
+
+// Risky: too aggressive
+retry: {
+  maxAttempts: 100,
+  maxDelay: 1000  // 1 second
+}
+
+// Risky: too long
+retry: {
+  maxAttempts: 20,
+  initialDelay: 60000  // 1 minute start
+}
+```
+
+### Log Retry Attempts
+
+Combine with match for observability:
+
+```vague
+action FetchWithLogging {
+  get "/data" {
+    retry: {
+      maxAttempts: 3,
+      backoff: exponential
+    }
+  }
+
+  match response {
+    { error: e } -> {
+      store {
+        endpoint: "/data",
+        error: e,
+        timestamp: now()
+      } -> retryLogs
+      abort e
+    },
+    _ -> continue
+  }
+}
+```
+
+## Troubleshooting
+
+### Retry Not Working
+
+Ensure the response matches retry conditions:
+
+```vague
+// Retry only triggers on match directive
+match response {
+  { error: _ } -> retry { maxAttempts: 3 },  // This triggers retry
+  _ -> continue
+}
+```
+
+### Too Many Retries
+
+Add a maximum delay:
+
+```vague
+retry: {
+  maxAttempts: 10,
+  backoff: exponential,
+  initialDelay: 1000,
+  maxDelay: 30000  // Cap delays
+}
+```
+
+### Retry After Token Refresh
+
+Use `jump then retry`:
+
+```vague
+match response {
+  { code: 401 } -> jump RefreshToken then retry,
+  _ -> continue
+}
+```