devstack 0.1.0

package/vendor/skills/skills/centrifugo/references/configuration.md

@@ -0,0 +1,201 @@
+# Centrifugo Configuration Reference
+
+## Configuration Sources (Priority Order)
+
+1. **Command-line flags** (highest)
+2. **Environment variables** (medium — override config file)
+3. **Configuration file** (lowest — JSON, YAML, or TOML)
+
+## Starting Centrifugo
+
+```bash
+# Generate config
+centrifugo genconfig              # Creates config.json
+
+# Start with config
+centrifugo -c config.json
+centrifugo --config=config.yaml
+centrifugo --config=config.toml
+
+# Docker
+docker run -p 8000:8000 centrifugo/centrifugo:v6 centrifugo
+docker run -p 8000:8000 -v $(pwd)/config.json:/centrifugo/config.json centrifugo/centrifugo:v6 centrifugo -c config.json
+```
+
+## Minimal Configuration
+
+```json
+{
+  "client": {
+    "token": {
+      "hmac_secret_key": "<SECRET>"
+    },
+    "allowed_origins": ["http://localhost:3000"]
+  },
+  "http_api": {
+    "key": "<API_KEY>"
+  }
+}
+```
+
+## Environment Variables
+
+All config options map to env vars. Use `CENTRIFUGO_` prefix with `_` separator for nesting:
+
+| Config Path                    | Environment Variable                                  |
+| ------------------------------ | ----------------------------------------------------- |
+| `client.token.hmac_secret_key` | `CENTRIFUGO_CLIENT_TOKEN_HMAC_SECRET_KEY`             |
+| `http_api.key`                 | `CENTRIFUGO_HTTP_API_KEY`                             |
+| `client.allowed_origins`       | `CENTRIFUGO_CLIENT_ALLOWED_ORIGINS` (comma-separated) |
+| `engine.type`                  | `CENTRIFUGO_ENGINE_TYPE`                              |
+| `engine.redis.address`         | `CENTRIFUGO_ENGINE_REDIS_ADDRESS`                     |
+
+Use `centrifugo defaultenv` to see all available env vars.
+
+## Core Configuration Sections
+
+### `client` — Client Connection Settings
+
+```json
+{
+  "client": {
+    "allowed_origins": ["http://localhost:3000"],
+    "token": {
+      "hmac_secret_key": "<SECRET>",
+      "rsa_public_key": "",
+      "ecdsa_public_key": "",
+      "audience": "",
+      "issuer": ""
+    },
+    "insecure": false,
+    "proxy": { ... }
+  }
+}
+```
+
+**`allowed_origins`**: Required for browser connections. Validates the Origin header. Use `["*"]` only in development.
+
+**`insecure`**: Skip client authentication (development only).
+
+### `http_api` — Server API Settings
+
+```json
+{
+  "http_api": {
+    "key": "<API_KEY>",
+    "insecure": false
+  }
+}
+```
+
+### `channel` — Channel & Namespace Settings
+
+See `references/channels.md` for full details.
+
+### `engine` — Engine Configuration
+
+See `references/engines.md` for Memory, Redis, and NATS setup.
+
+### `admin` — Admin Web UI
+
+```json
+{
+  "admin": {
+    "enabled": true,
+    "password": "<ADMIN_PASSWORD>",
+    "secret": "<ADMIN_SECRET>",
+    "insecure": false
+  }
+}
+```
+
+Access at `http://localhost:8000/` when enabled.
+
+### `tls` — TLS/HTTPS
+
+```json
+{
+  "tls": {
+    "enabled": true,
+    "cert_file": "/path/to/cert.pem",
+    "key_file": "/path/to/key.pem"
+  }
+}
+```
+
+With TLS, use `wss://` for WebSocket and `https://` for API.
+
+### `prometheus` — Metrics
+
+```json
+{
+  "prometheus": {
+    "enabled": true
+  }
+}
+```
+
+Metrics exposed at `/metrics` endpoint.
+
+### `health` — Health Check
+
+```json
+{
+  "health": {
+    "enabled": true
+  }
+}
+```
+
+Health endpoint at `/health`.
+
+### `log_level` — Logging
+
+```json
+{
+  "log_level": "info"
+}
+```
+
+Values: `trace`, `debug`, `info`, `warn`, `error`, `fatal`, `panic`.
+
+## Transport Endpoints
+
+Default endpoints (all on port 8000):
+
+| Endpoint                      | Transport      | Description                  |
+| ----------------------------- | -------------- | ---------------------------- |
+| `/connection/websocket`       | WebSocket      | Bidirectional real-time      |
+| `/connection/http_stream`     | HTTP Streaming | Bidirectional emulation      |
+| `/connection/sse`             | SSE            | Bidirectional emulation      |
+| `/connection/webtransport`    | WebTransport   | Bidirectional (experimental) |
+| `/connection/uni_websocket`   | WebSocket      | Unidirectional               |
+| `/connection/uni_http_stream` | HTTP Streaming | Unidirectional               |
+| `/connection/uni_sse`         | SSE            | Unidirectional               |
+| `/api`                        | HTTP           | Server API                   |
+| `/api/grpc`                   | GRPC           | Server GRPC API              |
+| `/metrics`                    | HTTP           | Prometheus metrics           |
+| `/health`                     | HTTP           | Health check                 |
+| `/`                           | HTTP           | Admin web UI                 |
+
+## Server Port
+
+```json
+{
+  "port": 8000
+}
+```
+
+Or via env: `CENTRIFUGO_PORT=8000`.
+
+## Helper CLI Commands
+
+```bash
+centrifugo genconfig            # Generate config file
+centrifugo gentoken -u <user>   # Generate test JWT
+centrifugo defaultconfig        # Show all config options with defaults
+centrifugo defaultenv           # Show all env var mappings
+centrifugo configdoc            # Show config documentation
+centrifugo checkconfig          # Validate config file
+centrifugo serve --port 3000    # Serve static files (development)
+```

package/vendor/skills/skills/centrifugo/references/engines.md

@@ -0,0 +1,203 @@
+# Centrifugo Engines & Scalability Reference
+
+## Engine Overview
+
+The Engine handles:
+
+- PUB/SUB between Centrifugo nodes
+- Publication history storage
+- Online presence management
+
+Engine = Broker (PUB/SUB + history) + Presence Manager.
+
+## Memory Engine (Default)
+
+Single node only. All data in process memory. Lost on restart.
+
+```json
+{
+  "engine": {
+    "type": "memory"
+  }
+}
+```
+
+**Use for**: Development, small deployments, isolated connection scenarios.
+
+## Redis Engine
+
+Multi-node scaling. Data persists across Centrifugo restarts.
+
+### Standalone Redis
+
+```json
+{
+  "engine": {
+    "type": "redis",
+    "redis": {
+      "address": "redis://user:password@127.0.0.1:6379/0"
+    }
+  }
+}
+```
+
+TLS: Use `rediss://` scheme.
+
+### Redis Sentinel
+
+```json
+{
+  "engine": {
+    "type": "redis",
+    "redis": {
+      "address": "redis+sentinel://user:password@host1:26379,host2:26379,host3:26379/mymaster/0"
+    }
+  }
+}
+```
+
+Format: `redis+sentinel://[user:pass@]host1:port,host2:port/master-name/db`
+
+### Redis Cluster
+
+```json
+{
+  "engine": {
+    "type": "redis",
+    "redis": {
+      "address": "redis+cluster://user:password@host1:7000,host2:7001,host3:7002"
+    }
+  }
+}
+```
+
+### Redis Sharding (Client-Side)
+
+Distribute load across multiple Redis instances:
+
+```json
+{
+  "engine": {
+    "type": "redis",
+    "redis": {
+      "address": ["redis://redis1:6379", "redis://redis2:6379", "redis://redis3:6379"]
+    }
+  }
+}
+```
+
+Uses consistent hashing. Can shard across Redis Clusters too.
+
+### Redis Options
+
+| Option            | Type            | Default          | Description          |
+| ----------------- | --------------- | ---------------- | -------------------- |
+| `address`         | string/string[] | "127.0.0.1:6379" | Redis address(es)    |
+| `prefix`          | string          | "centrifugo"     | Key prefix in Redis  |
+| `force_resp2`     | bool            | false            | Force RESP2 protocol |
+| `connect_timeout` | duration        | "1s"             | Connection timeout   |
+| `io_timeout`      | duration        | "4s"             | Read/write timeout   |
+| `tls`             | object          | null             | TLS configuration    |
+
+### Redis TLS
+
+```json
+{
+  "engine": {
+    "type": "redis",
+    "redis": {
+      "address": "rediss://localhost:6380",
+      "tls": {
+        "enabled": true,
+        "cert_file": "/path/to/cert.pem",
+        "key_file": "/path/to/key.pem",
+        "root_ca_file": "/path/to/ca.pem",
+        "insecure_skip_verify": false,
+        "server_name": "redis.example.com"
+      }
+    }
+  }
+}
+```
+
+### Redis-Compatible Storages
+
+Tested and supported:
+
+- **AWS ElastiCache** (Redis mode)
+- **Google Memorystore**
+- **Valkey**
+- **DragonflyDB** (set `force_resp2: true`)
+- **KeyDB**
+
+## NATS Broker
+
+NATS for PUB/SUB only (no history or presence). Combine with Redis for full features.
+
+```json
+{
+  "broker": {
+    "type": "nats",
+    "nats": {
+      "url": "nats://localhost:4222"
+    }
+  },
+  "presence_manager": {
+    "type": "redis",
+    "redis": {
+      "address": "redis://localhost:6379"
+    }
+  }
+}
+```
+
+### NATS Options
+
+| Option          | Type     | Default                 | Description        |
+| --------------- | -------- | ----------------------- | ------------------ |
+| `url`           | string   | "nats://localhost:4222" | NATS server URL    |
+| `prefix`        | string   | "centrifugo"            | Subject prefix     |
+| `dial_timeout`  | duration | "1s"                    | Connection timeout |
+| `write_timeout` | duration | "1s"                    | Write timeout      |
+
+## Separate Broker and Presence Manager
+
+For fine-grained control, configure broker and presence manager independently:
+
+```json
+{
+  "broker": {
+    "type": "redis",
+    "redis": {
+      "address": "redis://broker-redis:6379"
+    }
+  },
+  "presence_manager": {
+    "type": "redis",
+    "redis": {
+      "address": "redis://presence-redis:6379"
+    }
+  }
+}
+```
+
+## Scaling Architecture
+
+```
+                    Load Balancer
+                   /     |      \
+            Node 1    Node 2    Node 3
+                   \     |      /
+                    Redis Cluster
+                   /            \
+              Shard 1        Shard 2
+```
+
+- Each Centrifugo node handles a subset of client connections.
+- Any node can accept publish API calls — Redis broadcasts to all nodes.
+- Add nodes to scale connections; add Redis shards to scale throughput.
+- All data is ephemeral with TTLs — resharding is mostly automatic.
+
+## Minimum Redis Version
+
+**Redis 6.2.0 or later** is required.

package/vendor/skills/skills/centrifugo/references/proxy.md

@@ -0,0 +1,301 @@
+# Centrifugo Event Proxy Reference
+
+## Overview
+
+Centrifugo proxies client events to the application backend via HTTP or GRPC. This allows the backend to authenticate connections, authorize subscriptions, validate publications, and handle RPC calls.
+
+## Proxy Protocols
+
+- **HTTP**: Use `http://` or `https://` endpoint. Sends JSON POST requests.
+- **GRPC**: Use `grpc://` endpoint. Uses Protobuf-defined service.
+
+Both share the same schema: `github.com/centrifugal/centrifugo/internal/proxyproto/proxy.proto`
+
+## Client-Wide Proxy Events
+
+### Connect Proxy
+
+Authenticate connections without JWT.
+
+```json
+{
+  "client": {
+    "proxy": {
+      "connect": {
+        "enabled": true,
+        "endpoint": "http://backend:3000/centrifugo/connect",
+        "timeout": "3s",
+        "http_headers": ["Cookie", "Authorization"]
+      }
+    }
+  }
+}
+```
+
+**Backend receives**:
+
+```json
+{
+  "client": "client-id",
+  "transport": "websocket",
+  "protocol": "json",
+  "encoding": "json",
+  "data": {}, // Custom data from client
+  "b64data": "", // Binary data (base64)
+  "name": "js", // SDK name
+  "version": "5.x.x", // SDK version
+  "channels": [] // Channels client wants to subscribe to
+}
+```
+
+**Backend responds**:
+
+```json
+{
+  "result": {
+    "user": "42",
+    "expire_at": 1700000000,
+    "info": { "name": "Alice" },
+    "b64info": "",
+    "data": {},
+    "channels": ["notifications:user#42"],
+    "subs": {
+      "chat:room-1": {
+        "data": {},
+        "info": {}
+      }
+    },
+    "meta": {}
+  }
+}
+```
+
+To reject: return `{"error": {"code": 1000, "message": "unauthorized"}}` or use `{"disconnect": {"code": 4501, "reason": "unauthorized"}}`.
+
+### Refresh Proxy
+
+Extend sessions or perform periodic liveness checks.
+
+```json
+{
+  "client": {
+    "proxy": {
+      "refresh": {
+        "enabled": true,
+        "endpoint": "http://backend:3000/centrifugo/refresh"
+      }
+    }
+  }
+}
+```
+
+**Backend receives**: `{ client, transport, protocol, encoding, user, meta }`
+
+**Backend responds**:
+
+```json
+{
+  "result": {
+    "expire_at": 1700003600,
+    "info": {},
+    "expired": false
+  }
+}
+```
+
+## Channel Proxy Events
+
+Configured per-namespace:
+
+```json
+{
+  "channel": {
+    "namespaces": [
+      {
+        "name": "chat",
+        "proxy": {
+          "subscribe": {
+            "enabled": true,
+            "endpoint": "http://backend:3000/centrifugo/subscribe"
+          },
+          "publish": {
+            "enabled": true,
+            "endpoint": "http://backend:3000/centrifugo/publish"
+          },
+          "sub_refresh": {
+            "enabled": true,
+            "endpoint": "http://backend:3000/centrifugo/sub_refresh"
+          }
+        }
+      }
+    ]
+  }
+}
+```
+
+### Subscribe Proxy
+
+Validate channel access.
+
+**Backend receives**:
+
+```json
+{
+  "client": "client-id",
+  "transport": "websocket",
+  "protocol": "json",
+  "encoding": "json",
+  "user": "42",
+  "channel": "chat:room-1",
+  "token": "",
+  "meta": {},
+  "data": {}
+}
+```
+
+**Backend responds** (allow):
+
+```json
+{
+  "result": {
+    "info": { "role": "admin" },
+    "data": { "last_read": 100 },
+    "override": {
+      "presence": { "value": true },
+      "join_leave": { "value": true }
+    }
+  }
+}
+```
+
+**Backend responds** (deny):
+
+```json
+{
+  "error": {
+    "code": 403,
+    "message": "not allowed"
+  }
+}
+```
+
+### Publish Proxy
+
+Validate and optionally transform client publications.
+
+**Backend receives**:
+
+```json
+{
+  "client": "client-id",
+  "transport": "websocket",
+  "user": "42",
+  "channel": "chat:room-1",
+  "data": { "text": "hello" },
+  "meta": {}
+}
+```
+
+**Backend responds** (allow, optionally modify):
+
+```json
+{
+  "result": {
+    "data": { "text": "hello", "author": "Alice", "timestamp": 1700000000 },
+    "skip_history": false
+  }
+}
+```
+
+**Backend responds** (reject):
+
+```json
+{
+  "error": {
+    "code": 400,
+    "message": "message too long"
+  }
+}
+```
+
+### Sub Refresh Proxy
+
+Extend subscription expiration.
+
+**Backend receives**: `{ client, transport, user, channel, meta }`
+
+**Backend responds**: `{ result: { expire_at, expired, info } }`
+
+## RPC Proxy
+
+Handle custom client-to-server calls.
+
+```json
+{
+  "client": {
+    "proxy": {
+      "rpc": {
+        "enabled": true,
+        "endpoint": "http://backend:3000/centrifugo/rpc"
+      }
+    }
+  }
+}
+```
+
+**Backend receives**:
+
+```json
+{
+  "client": "client-id",
+  "transport": "websocket",
+  "user": "42",
+  "method": "get_user_profile",
+  "data": { "user_id": "123" },
+  "meta": {}
+}
+```
+
+**Backend responds**:
+
+```json
+{
+  "result": {
+    "data": { "name": "Bob", "avatar": "url" }
+  }
+}
+```
+
+## Proxy Configuration Options
+
+Each proxy event supports:
+
+| Option                    | Type     | Description                              |
+| ------------------------- | -------- | ---------------------------------------- |
+| `enabled`                 | bool     | Enable this proxy                        |
+| `endpoint`                | string   | Backend URL (http://, https://, grpc://) |
+| `timeout`                 | duration | Request timeout (default: "1s")          |
+| `http_headers`            | string[] | HTTP headers to forward from client      |
+| `grpc_metadata`           | string[] | GRPC metadata keys to forward            |
+| `binary_encoding`         | bool     | Use base64 for data fields               |
+| `include_connection_meta` | bool     | Include connection meta in request       |
+| `grpc_cert_file`          | string   | TLS cert for GRPC                        |
+| `grpc_credentials_key`    | string   | GRPC auth key                            |
+
+## HTTP Headers Forwarding
+
+By default, Centrifugo forwards no headers. Configure which client headers to proxy:
+
+```json
+{
+  "client": {
+    "proxy": {
+      "connect": {
+        "enabled": true,
+        "endpoint": "http://backend/connect",
+        "http_headers": ["Cookie", "Authorization", "X-Forwarded-For"]
+      }
+    }
+  }
+}
+```