reqon-dsl 0.2.0 → 0.3.0

package/docusaurus/docs/http/requests.md

@@ -1,328 +0,0 @@
----
-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

@@ -1,402 +0,0 @@
----
-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
-}
-```