@voltro/cli 0.30.1 → 0.31.0

package/templates/agent-docs/plugins/posthog.md

@@ -0,0 +1,91 @@
+# PostHog
+
+> Track-only AnalyticsSink that forwards events to PostHog's /capture endpoint — compose it with a second sink that owns reads.
+
+
+
+---
+
+<!-- source: en/plugins/posthog.md -->
+## PostHog
+
+_Track-only AnalyticsSink that forwards events to PostHog's /capture endpoint — compose it with a second sink that owns reads._
+
+`@voltro/plugin-posthog` is a **track-only** `AnalyticsSink` — it forwards every
+`track()` to PostHog's `/capture` endpoint so your events show up in PostHog's
+product-analytics UI (funnels, cohorts, sessions, feature flags). PostHog's
+query model is too PostHog-specific to fit the cross-provider contract, so
+`aggregate` / `timeseries` / `topN` return `AnalyticsCapabilityNotSupported`.
+The intended wiring is therefore `composeAnalytics([...])`: a primary sink owns
+the typed reads, PostHog additionally mirrors every event. For the shared
+`AnalyticsSink` API and the `useAnalytics()` read methods, see
+[Analytics & warehouse sinks](/docs/plugins/analytics).
+
+## Install
+
+```
+pnpm add @voltro/plugin-posthog
+```
+
+## Wiring — compose with a read-capable sink
+
+PostHog can't serve reads, so pair it with a primary sink via `composeAnalytics`
+(`track()` fans out to both; reads route to the first sink that supports them):
+
+```ts
+// app.config.ts
+import { composeAnalytics } from '@voltro/runtime'
+import { postgresAnalytics } from '@voltro/plugin-analytics-postgres'
+import { posthogAnalytics }  from '@voltro/plugin-posthog'
+
+export default {
+  type:      'api' as const,
+  name:      'myApi',
+  store:     'postgres' as const,
+  analytics: composeAnalytics([
+    postgresAnalytics(),                                     // primary — handles reads
+    posthogAnalytics({ apiKey: process.env.POSTHOG_KEY! }), // also forwards every track()
+  ]),
+}
+```
+
+## Options
+
+`posthogAnalytics(options)`:
+
+| Option | Type | Default | Notes |
+|---|---|---|---|
+| `apiKey` | `string` | — (**required**) | PostHog project API key. |
+| `host` | `string` | `'https://app.posthog.com'` | Use `'https://eu.posthog.com'` for EU cloud, or your self-hosted URL. |
+| `batch` | `{ maxSize?, flushIntervalMs? }` | unset (immediate mode) | Opt into client-side batching to PostHog's `/batch/` endpoint. |
+| `batch.maxSize` | `number` | `20` | Flush once the buffer reaches this many events. |
+| `batch.flushIntervalMs` | `number` | `5000` | Flush a non-empty buffer this many ms after the first event lands. |
+
+> **Connection details come from `options`, not env.** The plugin reads no
+> `POSTHOG_*` variables itself — the example wires `process.env` into the
+> options. Use `@voltro/env`'s `defineEnv` to declare the key as a secret.
+
+## Delivery semantics
+
+- **Immediate (default, `batch` unset):** every `track()` is one `/capture/`
+  POST, so a successful `track()` means the event was delivered.
+- **Batched (`batch: {...}`):** events buffer and flush by size, on a timer,
+  and on graceful shutdown (the `dispose` hook). A successful `track()` then
+  means "buffered" — far fewer round-trips under load, but a flush failure is
+  logged + the batch dropped (best-effort; `/batch/` carries no idempotency
+  key). A hard crash loses whatever is still buffered. Leave `batch` unset when
+  you need per-event delivery confirmation.
+
+## Capability limits
+
+`aggregate`, `timeseries`, and `topN` always return
+`AnalyticsCapabilityNotSupported` (provider `posthog`) — catch it with
+`Effect.catchTag` for graceful fallback, or rely on `composeAnalytics` routing
+reads to a read-capable sink. For PostHog-specific endpoints (capture batches,
+decide, person properties) import the `PostHog` Tag and use the raw HTTP API.
+
+## See also
+
+- [Analytics & warehouse sinks](/docs/plugins/analytics) — the shared
+  `AnalyticsSink` contract, the `useAnalytics()` read API, `composeAnalytics`,
+  and capability-not-supported error handling.

package/templates/agent-docs/plugins/presence.md

@@ -0,0 +1,115 @@
+# Presence
+
+> Ephemeral realtime presence — who's online in a channel, with heartbeat, live roster, and per-member metadata (status, cursor). Works cross-instance.
+
+
+
+---
+
+<!-- source: en/plugins/presence.md -->
+## Presence
+
+_Ephemeral realtime presence — who's online in a channel, with heartbeat, live roster, and per-member metadata (status, cursor). Works cross-instance._
+
+`@voltro/plugin-presence` answers "who's here right now". A client heartbeats into a channel; the roster lists everyone whose heartbeat is fresh. Held **in memory**, owner-partitioned: every member belongs to exactly the replica holding its WebSocket, so concurrent writes to one key are impossible by construction and there is no table, no CRDT and no coordinator.
+
+<Callout type="warn">
+Cross-instance presence needs a broker. With [`@voltro/plugin-broadcast`](/docs/plugins/broadcast) every replica sees the whole room; **without one, each replica sees only the clients connected to it** — a correct roster of a fraction of the room. Nothing errors, and a single-replica staging box looks perfect, so the boot logs a warning rather than leaving you to discover it in production.
+</Callout>
+
+## Wiring
+
+```ts
+// app.config.ts
+import { presencePlugin } from '@voltro/plugin-presence'
+
+export default {
+  type: 'api' as const, name: 'api',
+  plugins: [presencePlugin({ timeoutMs: 30_000 })],   // online window after the last heartbeat
+}
+```
+
+Contributes three routes: `presence.heartbeat`, `presence.list`, `presence.leave`. No table — a member is held by the replica that owns its connection.
+
+A client that vanishes without calling `leave` (a closed laptop, a dropped network, a crashed tab) is removed by a sweep after `timeoutMs`, and the removal is broadcast so every other replica drops it too. Each replica sweeps only its OWN members: another owner's timestamps are on another clock, and a replica that has gone is dropped whole by instance membership rather than guessed at. The sweep runs at a third of the timeout, so a vanished member is gone within roughly 1.3× the window.
+
+## Client hook
+
+```tsx
+import { usePresence } from '@voltro/plugin-presence/web'
+
+const Room = ({ channel }: { channel: string }) => {
+  // Heartbeats while mounted, leaves on unmount, returns the live roster.
+  const members = usePresence(channel, { meta: { status: 'typing' } })
+  return <div>{members.length} online: {members.map((m) => m.key).join(', ')}</div>
+}
+```
+
+`usePresence(channel, opts)` heartbeats on an interval (`heartbeatMs`, default 15s) and publishes per-member `meta` (status, cursor position, …). The roster is **push-driven** — `presence.list` is a reactive plugin query (`source: '_voltro_presence'`), so the framework pushes a fresh roster over the subscription transport on every roster change (heartbeat / leave / sweep / a peer departing) with NO client polling. `key` defaults to the subject id; pass an explicit `key` for anonymous members.
+
+## Typing indicator
+
+`useTyping` is a typing indicator built on the SAME presence primitive — no new transport. While `isTyping`, the client heartbeats into a short-TTL lane `typing:<channel>`; `stop()` / unmount leaves it, so a typer drops off within the heartbeat window.
+
+```tsx
+import { useTyping } from '@voltro/plugin-presence/web'
+
+const Composer = ({ channel, myKey }: { channel: string; myKey: string }) => {
+  const typing = useTyping(channel, { selfKey: myKey })
+  return (
+    <>
+      <textarea onFocus={typing.start} onBlur={typing.stop} />
+      {typing.active.length > 0 && <em>{typing.active.length} typing…</em>}
+    </>
+  )
+}
+```
+
+`useTyping(channel, opts)` → `{ active, isTyping, start, stop }`: `active` is the other members currently typing (self excluded via `selfKey`), `start()`/`stop()` toggle broadcasting. A shorter heartbeat than the roster (`heartbeatMs` default 3s) so a typer clears quickly; the lane roster is push-driven like `usePresence` (no poll). `activeTypers(members, selfKey)` is the pure self-exclusion helper it uses.
+
+## Cost
+
+Measured on the in-memory tracker:
+
+| | |
+| --- | --- |
+| a heartbeat (`track`), 1k members in the room | 0.10 µs |
+| `roster`, 1k members | 27 µs |
+| `roster`, 10k members | 283 µs |
+| a full sweep, 10k members | 77 µs |
+
+A heartbeat is a map write and costs nothing; reading the roster is linear in
+the room and is the number to watch. 10k in one channel is 283 µs per read —
+fine for a roster panel, wrong for a per-frame cursor overlay, which belongs in
+an event declared `delivery: 'latest'` rather than in presence metadata.
+
+## Notes
+
+- The roster is push-driven: `presence.list` is a reactive plugin query (`source: '_voltro_presence'`), so the framework re-runs it and pushes deltas over the subscription transport on every roster change — no client polling. There is no such TABLE any more; the name survives purely as the reactivity key the framework routes on, which is why the roster push needed no second mechanism when presence moved into memory. Any plugin query route that names a `source` table becomes push-driven the same way.
+- A member counts as online for `timeoutMs` after its last heartbeat. The sweep runs every `timeoutMs / 3`, so a vanished member is gone within roughly 1.3× the window.
+- The sweep needs **no cluster coordination**, and that follows from the design rather than being a shortcut: every member is owned by exactly one replica and nobody else may touch it, so each replica sweeps its own and there is nothing to contend over. (The table version *did* need coordination — its rows were shared.)
+
+## `timeoutMs` and `heartbeatMs` are one contract
+
+```ts
+presencePlugin({ timeoutMs: 30_000 })          // server: online for 30s after a beat
+usePresence(channel, { heartbeatMs: 15_000 })  // client: beats every 15s
+```
+
+A member counts as online for `timeoutMs` after its last heartbeat, and the
+client decides how often that heartbeat is. **The server value must comfortably
+outlast the client's** — the shipped default pair is 30s / 15s, a factor of two.
+
+Set it below the heartbeat and every member expires between beats: the roster
+flaps empty, and nothing reports it, because an empty roster is also what
+"nobody is here" looks like. A value under a second is refused at declaration
+for that reason; there is no "never expire" spelling, so omit `timeoutMs` for
+the default.
+
+A long window is fine — a signage terminal beating once a minute is a real
+deployment. The rule is a floor, not a range.
+
+
+## Permissions
+
+None for the roster itself — presence is in memory, so a heartbeat writes no rows.

package/templates/agent-docs/plugins/prometheus.md

@@ -0,0 +1,124 @@
+# Prometheus
+
+> Prometheus exporter — scrapes the unified Metrics-API at GET /metrics in text exposition format.
+
+
+
+---
+
+<!-- source: en/plugins/prometheus.md -->
+## Prometheus
+
+_Prometheus exporter — scrapes the unified Metrics-API at GET /metrics in text exposition format._
+
+`@voltro/plugin-prometheus` exposes the framework's metrics to Prometheus / Grafana at a scrape endpoint. It only READS — the framework emits the metrics automatically; the plugin formats them.
+
+## The Metrics-API (single source of truth)
+
+The framework records metrics into Effect's global `MetricRegistry`. One snapshot sees everything:
+
+- **Core RPC** — `voltro_rpc_requests_total{tag,status}`, `voltro_rpc_errors_total{tag}`, `voltro_rpc_duration_seconds{tag}` (histogram). Emitted at the mutation / action handler boundary.
+- **HTTP routes** — `voltro_http_requests_total{route,status}`, `voltro_http_duration_seconds{route}`.
+- **Plugin interceptors** — `voltro_plugin_hook_duration_seconds{hook}`, `voltro_plugin_hook_errors_total{hook}`.
+- **Subscriptions** — `voltro_subscriptions_active{tag}` (gauge of currently-open subscriptions), `voltro_subscription_deliveries_total{tag,kind}` + `voltro_subscription_delivery_seconds{tag,kind}` (per-delivery produce→push latency; `kind` = `snapshot` | `delta`).
+- **Schedules (crons)** — `voltro_schedule_runs_total{schedule,status}` (firings by name + outcome — `status` = `succeeded` | `failed`), `voltro_schedule_duration_seconds{schedule}` (histogram), and `voltro_schedule_last_success_timestamp_seconds{schedule}` (a **gauge holding the UNIX time of the last SUCCESS**). Emitted by the framework scheduler, so every cron gets them with no per-handler wiring. A cron fires unattended — the failure mode is silent — so this is the series to alert on: `time() - voltro_schedule_last_success_timestamp_seconds{schedule="…"} > <interval × N>` fires when a job stops succeeding (a failure counter alone can't catch a job that stopped firing at all, but the last-success gauge going stale does). A failure moves the counter but deliberately NOT the gauge.
+- **Workflows (durable execution)** — `voltro_workflow_runs_total{workflow,status}` (terminal outcomes — `status` = `succeeded` | `failed`), `voltro_workflow_duration_seconds{workflow}` (histogram), and `voltro_workflow_last_success_timestamp_seconds{workflow}` (last-success gauge). Emitted by the workflow run-recording seam. Because the framework applies no retry of its own, a `failed` run is **terminal** — it is the dead-letter state — so `voltro_workflow_runs_total{status="failed"}` **is** the dead-letter rate, and the last-success gauge going stale is the "this workflow stopped completing" alert (same shape as the schedule alert). A failure moves the counter but not the gauge.
+- **`@voltro/cache`** counters, Effect's own `effect_fiber_*` runtime metrics, and **any custom metric** you or another plugin defines.
+
+Two consumers read the SAME snapshot, so they never disagree:
+
+- **`GET /metrics`** (this plugin) → Prometheus text exposition format, consumed by Prometheus / Grafana.
+- **`GET /_voltro/inspect/metrics`** → JSON `MetricSample[]`, consumed by the dashboard's Metrics panel (quantiles derived from the histogram buckets, `histogram_quantile`-style).
+
+### Custom metrics
+
+Define your own counter / gauge / histogram and it shows up in both consumers automatically:
+
+```ts
+import { counter, gauge, histogramMetric } from '@voltro/runtime'
+import { Effect, Metric } from 'effect'
+
+const signups = counter('app_signups_total', 'User sign-ups.')
+
+export default (input, _ctx) =>
+  Effect.gen(function* () {
+    // … create the user …
+    yield* Metric.increment(signups)
+    return { ok: true }
+  })
+```
+
+## Wiring
+
+```ts
+// app.config.ts
+import { prometheusPlugin } from '@voltro/plugin-prometheus'
+
+export default {
+  type: 'api' as const,
+  name: 'api',
+  plugins: [prometheusPlugin()],
+}
+```
+
+Scrape config — one target **per replica**, never a single load-balanced hostname:
+
+```yaml
+scrape_configs:
+  - job_name: voltro
+    metrics_path: /metrics
+    static_configs:
+      # one target per replica — NOT one LB-fronted hostname
+      - targets: ['api-0.internal:4000', 'api-1.internal:4000']
+```
+
+### Multi-replica scraping
+
+The registry is **per-process**: each replica serves its own counters, and Prometheus keeps the series apart via the per-target `instance` label — exactly the pull model. But that only works when every replica is scraped **directly**. Behind a load-balancer, successive scrapes hit different processes and the per-process counters interleave into one incoherent series. On Kubernetes, use pod-level discovery so every pod becomes its own target:
+
+```yaml
+scrape_configs:
+  - job_name: voltro
+    kubernetes_sd_configs:
+      - role: pod
+    relabel_configs:
+      - source_labels: [__meta_kubernetes_pod_annotation_prometheus_io_scrape]
+        action: keep
+        regex: 'true'
+```
+
+The plugin's `name` option disambiguates multiple plugin instances **within one process** (it suffixes the plugin name) — it does not identify replicas; replica identity is the scrape target's `instance` label.
+
+## Options
+
+```ts
+prometheusPlugin({
+  path: '/metrics',          // scrape path (default /metrics)
+  token: process.env.PROMETHEUS_TOKEN,  // require `Authorization: Bearer <token>`
+  processMetrics: true,      // include node process_* metrics (default true)
+  version: '1.4.2',          // sets voltro_build_info{version} = 1
+})
+```
+
+- **`token`** — defaults to the `PROMETHEUS_TOKEN` env. Unset → the endpoint is open; gate it at the network layer (Prometheus uses `bearer_token` to send it).
+- **`processMetrics`** — emits `process_resident_memory_bytes`, `process_heap_bytes`, `process_cpu_seconds_total`.
+- The response is `text/plain; version=0.0.4; charset=utf-8` with `cache-control: no-store`.
+
+## Output shape
+
+Counters / gauges render as `name{labels} value`. Histograms render as cumulative `name_bucket{labels,le="…"}` series plus `name_sum` + `name_count` + the `+Inf` bucket — exactly what `histogram_quantile()` expects in Grafana.
+
+```
+# HELP voltro_rpc_requests_total Total RPC handler invocations.
+# TYPE voltro_rpc_requests_total counter
+voltro_rpc_requests_total{status="ok",tag="mutation.todos.create"} 42
+# TYPE voltro_rpc_duration_seconds histogram
+voltro_rpc_duration_seconds_bucket{tag="mutation.todos.create",le="0.001"} 3
+voltro_rpc_duration_seconds_bucket{tag="mutation.todos.create",le="+Inf"} 42
+voltro_rpc_duration_seconds_sum{tag="mutation.todos.create"} 0.21
+voltro_rpc_duration_seconds_count{tag="mutation.todos.create"} 42
+```
+
+## Scope
+
+Mutation / action / HTTP / plugin metrics, subscription metrics (active gauge + per-delivery latency histogram, split snapshot vs delta), schedule/cron metrics AND workflow metrics (run counter + duration + last-success gauge each) are all covered. OTLP metrics export reads the same registry: the `OTEL_EXPORTER_OTLP_ENDPOINT` that enables trace export also exports metrics (`@effect/opentelemetry` bridges the registry into the OTel MeterProvider) — that is the path for the Datadog Agent / any OTLP collector; agentless Datadog is `@voltro/plugin-datadog`. This plugin is specifically the Prometheus **pull** (scrape) surface.

package/templates/agent-docs/plugins/ratelimit.md

@@ -0,0 +1,274 @@
+# Rate limiting
+
+> Per-endpoint, per-subject and per-tenant request limits via the rpc interceptors. Sliding-window / fixed-window / token-bucket, memory / postgres / redis stores.
+
+
+
+---
+
+<!-- source: en/plugins/ratelimit.md -->
+## Rate limiting
+
+_Per-endpoint, per-subject and per-tenant request limits via the rpc interceptors. Sliding-window / fixed-window / token-bucket, memory / postgres / redis stores._
+
+`@voltro/plugin-ratelimit` enforces request limits at the **rpc interceptor**
+level — per endpoint, per subject, per tenant. Highly configurable: ordered
+rules, three algorithms, composite keying, static + dynamic per-tenant
+overrides, and an optional coarse pre-auth IP shield.
+
+Why the rpc interceptors and not an HTTP middleware: rpc traffic rides one
+long-lived WebSocket, so an HTTP-level limiter only ever sees the single
+upgrade — never the individual calls. The Effect-native rpc interceptors are
+the only surface that sees each call **and** the resolved subject (needed for
+per-tenant limits).
+
+Live — `demo.limited` is capped at 5/min per visitor; the 6th call within a
+minute fails with the typed `RateLimited` error (carrying `retryAfterMs`):
+
+```tsx
+const call = useAction('app', 'demo.limited')   // 5/min → typed RateLimited
+```
+
+## Quick start
+
+```ts
+// app.config.ts
+import { rateLimitPlugin } from '@voltro/plugin-ratelimit'
+
+export default {
+  type: 'api' as const,
+  name: 'myApi',
+  plugins: [
+    rateLimitPlugin({
+      // global fallback: 100 calls / minute / subject
+      default: { limit: 100, window: '1m' },
+      rules: [
+        // tighter, per-endpoint, token-bucket with burst
+        { match: 'todos.create', limit: 10, window: '1m', algorithm: 'token-bucket', burst: 15 },
+        // every admin.* mutation, one shared bucket per tenant
+        { match: /^admin\./, kind: 'mutation', limit: 1000, window: '1h', by: 'tenant', scope: 'rule' },
+      ],
+      // per-tenant limits from the subject's plan claim
+      resolve: (ctx) =>
+        ctx.subject.type !== 'anonymous' && ctx.subject.metadata?.plan === 'enterprise'
+          ? { limit: 10_000, window: '1m' }
+          : undefined,
+      store: 'memory', // 'memory' (default) | 'postgres' | 'redis' (any RESP server)
+    }),
+  ],
+}
+```
+
+## Rules — per endpoint
+
+Rules are evaluated top-to-bottom; the **first** whose `match` + `kind` accept
+the call wins. If none match, `default` applies; if there's no `default`, the
+call is unlimited.
+
+```ts
+rules: [
+  { match: 'todos.create', limit: 10, window: '1m' },          // exact rpc tag
+  { match: ['posts.create', 'posts.update'], limit: 30, window: '1m' }, // tag list
+  { match: /^admin\./, limit: 1000, window: '1h' },            // RegExp over tags
+]
+```
+
+| Field | Meaning |
+|---|---|
+| `match` | `string` (exact tag) · `string[]` (any of) · `RegExp` (pattern). Omitted → every tag. |
+| `kind` | `'mutation' \| 'query' \| 'action'` or an array. Omitted → all kinds. Limit writes but not reads. |
+| `limit` | allowance per window. `number`, or `(ctx) => number` for dynamic per-tenant/plan logic. |
+| `window` | `'1m'`, `'10s'`, `'500ms'`, `'2h'`, `'1d'`, or raw milliseconds. Static or `(ctx) => …`. |
+| `algorithm` | `'sliding-window'` (default), `'fixed-window'`, `'token-bucket'`. |
+| `burst` | token-bucket capacity; defaults to `limit`. Ignored by the window algorithms. |
+| `by` | keying dimension(s) — see below. Default `'subject'`. |
+| `scope` | `'tag'` (default: a bucket per endpoint) vs `'rule'` (one bucket across all tags the rule matches). |
+| `tenants` | static per-tenant overrides — see below. |
+
+`default` is the same shape minus `match` (it covers whatever no rule matched).
+
+## Algorithms
+
+- **`sliding-window`** (default) — weighted-counter approximation; smooth, no
+  edge bursts, two integers of state per key.
+- **`fixed-window`** — cheapest; can allow up to 2× at window edges.
+- **`token-bucket`** — smooth refill with a configurable `burst` capacity.
+  Good for "N steady-state, but allow a batch of `burst` now and then".
+
+## Keying — who shares a bucket
+
+`by` controls what the bucket is keyed on. Composite arrays join into one key.
+
+| `by` | Bucket scope |
+|---|---|
+| `'subject'` *(default)* | per authenticated principal (already tenant-scoped) |
+| `'tenant'` | one shared bucket for the whole tenant |
+| `'apiKey'` | per api key (falls back to subject for non-apiKey subjects) |
+| `'global'` | one bucket for the rule across everything |
+| `['tenant','subject']` | composite — one bucket per (tenant, user) |
+| `(ctx) => string` | custom key |
+
+`scope` is orthogonal: `'tag'` (default) gives each matched endpoint its own
+bucket; `'rule'` shares one bucket across every tag the rule matches (e.g.
+"200 writes/min total across all mutations").
+
+## Per-tenant limits
+
+Two ways, and they compose — static first, then the dynamic hook wins:
+
+**Static `tenants` override** on a rule — different limit (or exemption) per tenant id:
+
+```ts
+{
+  match: 'ai.chat', limit: 50, window: '1m',
+  tenants: {
+    free: { limit: 10 },
+    ent:  { limit: 5_000 },
+    internal: { disabled: true },   // exempt this tenant entirely
+  },
+}
+```
+
+**Dynamic `resolve` hook** — fully programmatic, sync / Promise / Effect.
+Runs after a rule + its static tenant override resolve; whatever it returns
+wins. Return a limit override, `'exempt'`, or `undefined` to keep the rule's:
+
+```ts
+resolve: (ctx) =>
+  ctx.subject.type !== 'anonymous' && ctx.subject.metadata?.plan === 'enterprise'
+    ? { limit: 10_000, window: '1m' }
+    : undefined,
+```
+
+The `ctx` is `{ tag, kind, subject, tenantId, traceId }`.
+
+## Master gate — `enabled`
+
+`false` disables all limiting; a function gates per-call (e.g. exempt a tenant
+or a maintenance bypass). Returning `false` means "no limit for this call".
+
+```ts
+rateLimitPlugin({
+  default: { limit: 100, window: '1m' },
+  enabled: (ctx) => ctx.tenantId !== 'vip',   // VIP tenant is never limited
+})
+```
+
+## Coarse pre-auth IP shield — `http`
+
+Optional front-door guard keyed by remote IP, **before** any subject is
+resolved. It fires on every HTTP request — inspect, webhooks, AND the rpc
+WebSocket upgrade. Use as a cheap DoS shield in addition to the per-subject
+rpc rules. Adds the `http:intercept` permission automatically.
+
+```ts
+rateLimitPlugin({
+  default: { limit: 100, window: '1m' },
+  http: { limit: 1000, window: '1m' },   // 1000 connections/min/IP at the door
+})
+```
+
+When the shield trips it returns `429` with a `Retry-After` header plus the IETF draft `RateLimit-Limit` / `RateLimit-Remaining` / `RateLimit-Reset` headers (`RateLimit-Reset` is seconds-until-reset), so the caller can read its quota position.
+
+## Rejected calls — the `RateLimited` error
+
+When a call exceeds its limit the interceptor fails with a typed error on the
+rpc error channel. The plugin merges `RateLimited` into **every** procedure's
+wire error union (server group + generated client group stay in lockstep), so
+the client decodes it **typed** — not as an opaque defect:
+
+```ts
+class RateLimited extends Schema.TaggedError('RateLimited')({
+  tag:          Schema.String,   // the rpc tag that was limited
+  limit:        Schema.Number,   // the effective limit hit
+  windowMs:     Schema.Number,   // the window it applies over
+  retryAfterMs: Schema.Number,   // suggested wait before retry
+  resetAtMs:    Schema.Number,   // epoch-ms when the bucket replenishes
+})
+```
+
+Client narrows on `_tag` and shows a retry timer:
+
+```tsx
+const result = await create.mutate(input).catch((e) => e)
+if (result?._tag === 'RateLimited') {
+  toast.error(`Slow down — retry in ${Math.ceil(result.retryAfterMs / 1000)}s`)
+}
+```
+
+For observability, pass `onLimited(info)` — a best-effort callback (swallowed
+on throw) fired on every rejection with `{ tag, kind, key, tenantId, limit, windowMs, retryAfterMs }`.
+
+## Storage backends
+
+A rate limiter needs an **atomic** counter (an increment that can't lose
+updates under concurrency), so it can't reuse a plain get/set cache. Three
+stores ship, all fail OPEN on backend errors (degrade to no-limit, never to 500s):
+
+- **Memory** *(default)* — single-process, zero-config. Perfect for dev and
+  single-instance deploys; not shared across replicas.
+- **Postgres** — multi-node correct. Runs on the framework's **already-open
+  `SqlClient`** — the same connection pool the app itself uses — so it reads no
+  `DB_*`/`PG_*` env of its own and never opens a second pool. The plugin binds
+  that client for you when `store: 'postgres'` is selected. It mutates counter
+  state under a `SELECT … FOR UPDATE` row lock plus a transaction-scoped
+  advisory lock (cold-key safe). The pg driver (`@effect/sql`) is loaded lazily,
+  only on this path — a memory- or redis-only app never bundles it.
+- **Redis (RESP family)** — multi-node, fastest. Runs the whole decision in
+  one atomic Lua script. Works against **any RESP-compatible server, not just
+  Redis itself**:
+
+  | Server | Notes |
+  |---|---|
+  | **Redis** | the reference RESP server |
+  | **Valkey** | the Linux-Foundation fork of Redis 7.2 |
+  | **KeyDB** | multithreaded, Redis-compatible |
+  | **Dragonfly** | modern multi-core drop-in |
+  | **Upstash** | serverless Redis over REST (HTTP driver) |
+
+`'redis'` is the umbrella for the **whole RESP family** — the server brand
+(Valkey, KeyDB, Dragonfly, …) is just the url; you never pick a per-server
+type. The one real choice is the **driver**, mirroring `@voltro/cache`:
+
+- `'resp'` *(default)* — `ioredis` over TCP. Covers Redis, Valkey, KeyDB,
+  Dragonfly, and Upstash's TCP endpoint.
+- `'http'` — `@upstash/redis` over REST, for serverless/edge where TCP isn't
+  available.
+
+Both are optional dependencies, loaded only when the redis store is used.
+
+```ts
+rateLimitPlugin({
+  default: { limit: 100, window: '1m' },
+  store: 'redis',   // 'memory' (default) | 'postgres' | 'redis' (any RESP server)
+})
+```
+
+`store: 'redis'` reads the same env as the cache plugin — `CACHE_REDIS_URL`
+(falling back to `REDIS_URL`), `CACHE_REDIS_DRIVER` (`resp` default | `http`),
+and `CACHE_REDIS_TOKEN` / `UPSTASH_REDIS_REST_TOKEN` for the http driver. An app
+already pointed at Valkey/Upstash for caching gets rate-limiting on the same
+backend for free.
+
+For a custom client/url/driver — or to share an existing connection — use the factory:
+
+```ts
+import { redisStore } from '@voltro/plugin-ratelimit/redis'
+
+// Valkey / KeyDB / Dragonfly / Redis over TCP — just the url:
+store: redisStore({ url: 'rediss://valkey.internal:6379' })
+
+// Upstash over REST (serverless/edge):
+store: redisStore({ driver: 'http', url: process.env.UPSTASH_REDIS_REST_URL!, token: process.env.UPSTASH_REDIS_REST_TOKEN! })
+
+// or share an existing client (ioredis or @upstash/redis):
+store: redisStore({ client: myClient })
+```
+
+Bring your own backend entirely by passing any object that satisfies the
+`RateLimitStore` interface to `store:`.
+
+## See also
+
+- [Mutations](/docs/data/mutations) — the interceptor chain rate limiting hooks into
+- [Multi-tenancy](/docs/multi-tenancy) — where `subject.tenantId` comes from