@xano/developer-mcp 1.0.19 → 1.0.21

package/dist/xanoscript_docs/middleware.md

@@ -0,0 +1,321 @@
+---
+applyTo: "middleware/**/*.xs"
+---
+
+# Middleware
+
+Middleware intercepts and processes requests before and after your functions, queries, tasks, and tools execute.
+
+## Quick Reference
+
+```xs
+middleware "<name>" {
+  description = "What this middleware does"
+  exception_policy = "silent" | "rethrow" | "critical"
+  response_strategy = "merge" | "replace"
+  input { ... }
+  stack { ... }
+  response = $result
+}
+```
+
+### Required Blocks
+| Block | Purpose |
+|-------|---------|
+| `input` | Define parameters passed to middleware |
+| `stack` | Processing logic |
+| `response` | Output returned to caller |
+
+### Optional Attributes
+| Attribute | Values | Default | Description |
+|-----------|--------|---------|-------------|
+| `description` | text | - | Documents middleware purpose |
+| `exception_policy` | `silent`, `rethrow`, `critical` | `rethrow` | How to handle errors |
+| `response_strategy` | `merge`, `replace` | `merge` | How response combines with original |
+
+---
+
+## Basic Structure
+
+```xs
+middleware "log_request" {
+  description = "Logs all incoming requests"
+
+  input {
+    json request_data
+  }
+
+  stack {
+    debug.log {
+      value = {
+        timestamp: now,
+        data: $input.request_data
+      }
+    }
+  }
+
+  response = null
+}
+```
+
+---
+
+## Exception Policies
+
+Control how middleware handles errors:
+
+### silent
+Errors are caught and ignored. Execution continues normally.
+
+```xs
+middleware "optional_enrichment" {
+  exception_policy = "silent"
+
+  input {
+    int user_id
+  }
+
+  stack {
+    // If this fails, request continues without enrichment
+    api.call "external_service" {
+      url = "https://api.example.com/enrich/" ~ $input.user_id
+    } as $enriched
+  }
+
+  response = $enriched
+}
+```
+
+### rethrow (default)
+Errors are passed through to the caller. Standard error handling applies.
+
+```xs
+middleware "validate_token" {
+  exception_policy = "rethrow"
+
+  input {
+    text token
+  }
+
+  stack {
+    precondition ($input.token|strlen > 0) {
+      error_type = "accessdenied"
+      error = "Token required"
+    }
+  }
+
+  response = { valid: true }
+}
+```
+
+### critical
+Errors are treated as critical failures. Request is immediately terminated.
+
+```xs
+middleware "security_check" {
+  exception_policy = "critical"
+
+  input {
+    text ip_address
+  }
+
+  stack {
+    db.query "blocked_ips" {
+      where = $db.blocked_ips.ip == $input.ip_address
+      return = { type: "exists" }
+    } as $is_blocked
+
+    precondition (!$is_blocked) {
+      error_type = "accessdenied"
+      error = "Access denied"
+    }
+  }
+
+  response = { allowed: true }
+}
+```
+
+---
+
+## Response Strategies
+
+Control how middleware response combines with the original response:
+
+### merge (default)
+Middleware response is merged with original response.
+
+```xs
+middleware "add_metadata" {
+  response_strategy = "merge"
+
+  input {
+  }
+
+  stack {
+    var $meta {
+      value = {
+        server_time: now,
+        version: "1.0.0"
+      }
+    }
+  }
+
+  response = { _meta: $meta }
+}
+// Original: { data: [...] }
+// Result: { data: [...], _meta: { server_time: ..., version: "1.0.0" } }
+```
+
+### replace
+Middleware response completely replaces original response.
+
+```xs
+middleware "transform_response" {
+  response_strategy = "replace"
+
+  input {
+    json original_response
+  }
+
+  stack {
+    var $transformed {
+      value = {
+        success: true,
+        payload: $input.original_response
+      }
+    }
+  }
+
+  response = $transformed
+}
+```
+
+---
+
+## Common Patterns
+
+### Request Logging
+
+```xs
+middleware "audit_log" {
+  description = "Logs all API requests for audit trail"
+  exception_policy = "silent"
+
+  input {
+    text endpoint
+    text method
+    json request_body?
+    int user_id?
+  }
+
+  stack {
+    db.add "audit_log" {
+      data = {
+        endpoint: $input.endpoint,
+        method: $input.method,
+        request_body: $input.request_body,
+        user_id: $input.user_id,
+        ip_address: $env.$remote_ip,
+        created_at: now
+      }
+    }
+  }
+
+  response = null
+}
+```
+
+### Rate Limiting
+
+```xs
+middleware "rate_limit" {
+  description = "Enforces rate limits per user"
+  exception_policy = "rethrow"
+
+  input {
+    int user_id
+    int max_requests?=100
+    int window_seconds?=60
+  }
+
+  stack {
+    var $key { value = "ratelimit:" ~ $input.user_id }
+
+    redis.incr {
+      key = $key
+    } as $count
+
+    conditional {
+      if ($count == 1) {
+        redis.expire {
+          key = $key
+          seconds = $input.window_seconds
+        }
+      }
+    }
+
+    precondition ($count <= $input.max_requests) {
+      error_type = "standard"
+      error = "Rate limit exceeded"
+    }
+  }
+
+  response = { remaining: $input.max_requests - $count }
+}
+```
+
+### Response Caching
+
+```xs
+middleware "cache_response" {
+  description = "Caches responses in Redis"
+  exception_policy = "silent"
+
+  input {
+    text cache_key
+    int ttl_seconds?=300
+    json response_data
+  }
+
+  stack {
+    redis.set {
+      key = $input.cache_key
+      value = $input.response_data|json_encode
+      expire = $input.ttl_seconds
+    }
+  }
+
+  response = null
+}
+```
+
+---
+
+## Applying Middleware
+
+Middleware is configured at the branch level. See `xanoscript_docs({ topic: "branch" })` for configuration details.
+
+```xs
+branch "production" {
+  middleware = {
+    query: {
+      pre: ["validate_token", "rate_limit"],
+      post: ["audit_log", "cache_response"]
+    },
+    function: {
+      pre: ["validate_token"],
+      post: ["audit_log"]
+    }
+  }
+}
+```
+
+---
+
+## Best Practices
+
+1. **Keep middleware focused** - Each middleware should do one thing well
+2. **Use appropriate exception policies** - Critical for security, silent for optional enrichment
+3. **Consider performance** - Middleware runs on every request
+4. **Log failures** - Even silent failures should be logged for debugging
+5. **Test independently** - Middleware should be testable in isolation

package/dist/xanoscript_docs/realtime.md

@@ -42,11 +42,123 @@ api.realtime_event {
 
 ---
 
+## Realtime Channel Configuration
+
+Define channel settings at the workspace level using `realtime_channel`.
+
+```xs
+realtime_channel "<channel_pattern>" {
+  description = "Channel description"
+  active = true
+
+  public_messaging = {
+    active: true,
+    auth: false
+  }
+
+  private_messaging = {
+    active: true,
+    auth: true
+  }
+
+  settings = {
+    anonymous_clients: false,
+    nested_channels: true,
+    message_history: 100,
+    auth_channel: true,
+    presence: true
+  }
+}
+```
+
+### Channel Configuration Options
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `description` | text | Human-readable channel description |
+| `active` | boolean | Enable/disable the channel |
+
+### Messaging Options
+
+| Setting | Type | Description |
+|---------|------|-------------|
+| `public_messaging.active` | boolean | Allow public messages |
+| `public_messaging.auth` | boolean | Require authentication for public messages |
+| `private_messaging.active` | boolean | Allow private messages |
+| `private_messaging.auth` | boolean | Require authentication for private messages |
+
+### Settings Options
+
+| Setting | Type | Values | Description |
+|---------|------|--------|-------------|
+| `anonymous_clients` | boolean | true/false | Allow unauthenticated clients |
+| `nested_channels` | boolean | true/false | Allow sub-channel patterns |
+| `message_history` | number | 0, 25, 50, 100, 250, 1000 | Messages to retain |
+| `auth_channel` | boolean | true/false | Require channel-level auth |
+| `presence` | boolean | true/false | Track client presence |
+
+### Example Configurations
+
+```xs
+// Chat room channel with presence
+realtime_channel "room:*" {
+  description = "Chat room channels"
+  active = true
+
+  public_messaging = { active: true, auth: true }
+  private_messaging = { active: true, auth: true }
+
+  settings = {
+    anonymous_clients: false,
+    nested_channels: false,
+    message_history: 100,
+    auth_channel: true,
+    presence: true
+  }
+}
+
+// Global announcements (read-only for clients)
+realtime_channel "announcements" {
+  description = "System-wide announcements"
+  active = true
+
+  public_messaging = { active: true, auth: false }
+  private_messaging = { active: false, auth: false }
+
+  settings = {
+    anonymous_clients: true,
+    nested_channels: false,
+    message_history: 25,
+    auth_channel: false,
+    presence: false
+  }
+}
+
+// User-specific notifications
+realtime_channel "user:*" {
+  description = "User notification channels"
+  active = true
+
+  public_messaging = { active: false, auth: false }
+  private_messaging = { active: true, auth: true }
+
+  settings = {
+    anonymous_clients: false,
+    nested_channels: false,
+    message_history: 50,
+    auth_channel: true,
+    presence: false
+  }
+}
+```
+
+---
+
 ## Channel Patterns
 
 ### Public Channels
 
-Available to all authenticated clients.
+Accessible to all authenticated clients. When you send to a public channel, all clients currently subscribed to that channel receive the message.
 
 ```xs
 // Global announcements

package/dist/xanoscript_docs/tools.md

@@ -62,7 +62,7 @@ tool "get_user_by_email" {
 
 ## Input Block
 
-For complete type reference, use `xanoscript_docs({ keyword: "input" })`. For tools, input `description` fields are sent to the AI, so write them clearly:
+For complete type reference, use `xanoscript_docs({ topic: "types" })`. For tools, input `description` fields are sent to the AI, so write them clearly:
 
 ```xs
 input {

package/dist/xanoscript_docs/types.md

@@ -62,7 +62,13 @@ input {
 
 ### Empty Input Blocks
 
-**CRITICAL:** When an input block has no parameters, the braces MUST be on separate lines. This is a strict syntax requirement - `input {}` on a single line will cause parsing errors.
+**SYNTAX REQUIREMENT:** When an input block has no parameters, the braces MUST be on separate lines.
+
+**Why:** The XanoScript parser requires whitespace between braces to distinguish empty input blocks from inline objects.
+
+**Impact:** Using `input {}` on a single line will cause:
+- Syntax error during compilation
+- Function/API/tool will fail to deploy
 
 ```xs
 // CORRECT - braces on separate lines
@@ -109,6 +115,21 @@ email contact filters=trim|lower {
 password secret filters=min:8          // Minimum 8 characters
 ```
 
+#### Password Complexity Filters
+| Filter | Description | Example |
+|--------|-------------|---------|
+| `min:<n>` | Minimum total length | `password pwd filters=min:8` |
+| `minAlpha:<n>` | Minimum letters (a-zA-Z) | `password pwd filters=minAlpha:2` |
+| `minLowerAlpha:<n>` | Minimum lowercase letters | `password pwd filters=minLowerAlpha:1` |
+| `minUpperAlpha:<n>` | Minimum uppercase letters | `password pwd filters=minUpperAlpha:1` |
+| `minDigit:<n>` | Minimum digits (0-9) | `password pwd filters=minDigit:1` |
+| `minSymbol:<n>` | Minimum special characters | `password pwd filters=minSymbol:1` |
+
+```xs
+// Strong password: 8+ chars, 1 upper, 1 lower, 1 digit, 1 symbol
+password strong_pwd filters=min:8|minUpperAlpha:1|minLowerAlpha:1|minDigit:1|minSymbol:1
+```
+
 ### timestamp / date
 ```xs
 timestamp created_at?=now              // Defaults to current time
@@ -199,10 +220,8 @@ Filters validate and transform input values. Chain with `|`.
 | `ok:<chars>` | Allow only specified characters | `text hex filters=ok:0123456789abcdef` |
 | `prevent:<str>` | Block specific substrings | `text name filters=prevent:admin` |
 | `startsWith:<prefix>` | Require prefix | `text sku filters=startsWith:SKU-` |
-| `endsWith:<suffix>` | Require suffix | `text file filters=endsWith:.pdf` |
 | `alphaOk` | Allow only letters (a-zA-Z) | `text name filters=alphaOk` |
 | `digitOk` | Allow only digits (0-9) | `text code filters=digitOk` |
-| `alphaNumOk` | Allow letters and digits | `text username filters=alphaNumOk` |
 | `pattern:<regex>` | Match regex pattern | `text phone filters=pattern:^\+?[0-9]+$` |
 
 ### Numeric Filters
@@ -210,14 +229,12 @@ Filters validate and transform input values. Chain with `|`.
 |--------|-------------|---------|
 | `min:<n>` | Minimum value | `int age filters=min:0` |
 | `max:<n>` | Maximum value | `int age filters=max:150` |
-| `between:<a>:<b>` | Value between a and b | `int score filters=between:0:100` |
 
 ### Array Filters
 | Filter | Description | Example |
 |--------|-------------|---------|
 | `min:<n>` | Minimum array length | `text[] tags filters=min:1` |
 | `max:<n>` | Maximum array length | `text[] tags filters=max:10` |
-| `unique` | Remove duplicates | `int[] ids filters=unique` |
 
 ### Character Set Filters
 
@@ -255,11 +272,11 @@ input {
 ### Combined Examples
 ```xs
 input {
-  text username filters=trim|lower|min:3|max:20|alphaNumOk
+  text username filters=trim|lower|min:3|max:20|ok:abcdefghijklmnopqrstuvwxyz0123456789_
   email contact filters=trim|lower
   int age filters=min:0|max:150
   text hex_code filters=ok:abcdef0123456789|min:6|max:6
-  text[] tags filters=trim|lower|max:50|unique
+  text[] tags filters=trim|lower|max:50
   text phone filters=trim|pattern:^\+?[0-9\s-]+$
   int quantity filters=min:1|max:100
 }
@@ -326,7 +343,7 @@ input {
 
 ## Validation with Preconditions
 
-For complex validation beyond filters, use preconditions. For complete error handling reference, use `xanoscript_docs({ keyword: "syntax" })`.
+For complex validation beyond filters, use preconditions. For complete error handling reference, use `xanoscript_docs({ topic: "syntax" })`.
 
 ```xs
 precondition ($input.start_date < $input.end_date) {