npm package: @ku0/x-router-rs
Description: Rust x-router core bindings for high-performance new-api routing.
Latest version: 0.1.0

# x-router-rs

Rust x-router core + native HTTP service.

## Native Node Binding Build

```bash
pnpm --filter @ku0/x-router-rs build:rs
```

## Run Rust HTTP Service

```bash
pnpm --filter @ku0/x-router-rs serve:rs
```

Environment variables:

- `X_ROUTER_HOST` (default `0.0.0.0`)
- `X_ROUTER_PORT` (default `4317`)
- `X_ROUTER_BASE_PATH` (default `/v1/x-router`)
- `X_ROUTER_METRICS_PATH` (default `/metrics`)
- `X_ROUTER_REQUEST_TIMEOUT_MS` (default `5000`)
- `X_ROUTER_AUTH_MODE` (`disabled` | `optional` | `required`)
- `X_ROUTER_AUTH_STORE_MODE` (`in-memory` | `sqlite`)
- `X_ROUTER_AUTH_STORE_SQLITE_PATH` (default `.tmp/x-router-auth.db` when sqlite mode)
- `X_ROUTER_API_KEYS` (example: `tenant-a=key-a|key-b,tenant-b=key-c`)
- `X_ROUTER_DISTRIBUTED_LIMITER_MODE` (`disabled` | `shadow` | `enforce`)
- `X_ROUTER_DISTRIBUTED_LIMITER_REDIS_URL` (example: `redis://127.0.0.1:6379/0`)
- `X_ROUTER_DISTRIBUTED_LIMITER_KEY_PREFIX` (default `x-router`)
- `X_ROUTER_DISTRIBUTED_LIMITER_FAIL_OPEN` (default `true`)
- `X_ROUTER_DISTRIBUTED_LIMITER_TIMEOUT_MS` (default `150`)
- `X_ROUTER_DISTRIBUTED_LIMITER_REUSE_CONNECTION` (default `true`)
- `X_ROUTER_DISTRIBUTED_LIMITER_CONNECTION_POOL_SIZE` (default `8`)
- `X_ROUTER_UPSTREAM_MODE` (`disabled` | `prefer-upstream` | `upstream-only`)
- `X_ROUTER_UPSTREAMS` (example: `core-a@3=http://10.0.0.11:4317,core-b@1=http://10.0.0.12:4317`)
- `X_ROUTER_UPSTREAM_TIMEOUT_MS` (default `3000`)
- `X_ROUTER_UPSTREAM_COOLDOWN_MS` (default `15000`)
- `X_ROUTER_UPSTREAM_MAX_ATTEMPTS` (default `3`)
- `X_ROUTER_UPSTREAM_MAX_IN_FLIGHT` (default `256`)
- `X_ROUTER_UPSTREAM_CIRCUIT_FAILURE_THRESHOLD` (default `3`)
- `X_ROUTER_UPSTREAM_CIRCUIT_OPEN_MS` (default `20000`)
- `X_ROUTER_UPSTREAM_RETRY_BUDGET_MAX_TOKENS` (default `64`)
- `X_ROUTER_UPSTREAM_RETRY_BUDGET_REFILL_PER_SUCCESS` (default `0.25`)
- `X_ROUTER_UPSTREAM_EWMA_ALPHA` (default `0.2`)
- `X_ROUTER_UPSTREAM_SELECTION` (`latency-aware` | `round-robin` | `weighted-round-robin` | `least-loaded` | `tenant-affinity`)
- `X_ROUTER_UPSTREAM_HEALTH_PROBE_ENABLED` (default `false`)
- `X_ROUTER_UPSTREAM_HEALTH_PROBE_INTERVAL_MS` (default `15000`)
- `X_ROUTER_UPSTREAM_HEALTH_PROBE_AUTO_DISABLE` (default `true`)
- `X_ROUTER_UPSTREAM_HEALTH_PROBE_FAILURE_THRESHOLD` (default `3`)
- `X_ROUTER_UPSTREAM_HEALTH_PROBE_RECOVER_THRESHOLD` (default `2`)
- `X_ROUTER_TENANT_DEFAULT_RPM` (default `1200`)
- `X_ROUTER_TENANT_DEFAULT_BURST` (default `600`)
- `X_ROUTER_TENANT_DEFAULT_MAX_IN_FLIGHT` (default `64`)
- `X_ROUTER_TENANT_MAX_TRACKED` (default `10000`)
- `X_ROUTER_CONTROL_PLANE_IF_MATCH_REQUIRED` (default `false`)
- `X_ROUTER_CONTROL_PLANE_IF_MATCH_HEADER` (default `x-policy-if-match`)
- `X_ROUTER_STATE_PERSISTENCE_PATH` (optional; example `.tmp/x-router-rs-state.json`)
- `X_ROUTER_STATE_PERSISTENCE_AUTO_SAVE` (default `true`)
- `X_ROUTER_COMPAT_ENABLED` (default `false`)
- `X_ROUTER_COMPAT_WS_ENABLED` (default `true`)
- `X_ROUTER_COMPAT_NOT_IMPLEMENTED_MODE` (`strict` | `passthrough`, default `strict`)
- `X_ROUTER_COMPAT_MODEL_CACHE_TTL_MS` (default `15000`)
- `X_ROUTER_COMPAT_MODEL_REFRESH_TIMEOUT_MS` (default `2000`)
- `X_ROUTER_COMPAT_MODEL_STATIC_JSON` (optional JSON fallback model registry)
- `X_ROUTER_COMPAT_MODEL_RATE_LIMIT_MODE` (`disabled` | `shadow` | `enforce`, default `disabled`)
- `X_ROUTER_COMPAT_MODEL_RATE_LIMIT_RPM` (default `0`, disabled when `0`)
- `X_ROUTER_COMPAT_MODEL_RATE_LIMIT_REDIS_URL` (optional; defaults to distributed limiter Redis URL when unset)
- `X_ROUTER_COMPAT_MODEL_RATE_LIMIT_REDIS_KEY_PREFIX` (default `x-router:compat:model-rate`)
- `X_ROUTER_COMPAT_MODEL_RATE_LIMIT_REDIS_TIMEOUT_MS` (default `150`)
- `X_ROUTER_COMPAT_SYSTEM_GUARD_ENABLED` (default `true`)
- `X_ROUTER_COMPAT_SYSTEM_MAX_IN_FLIGHT` (default `2000`)
- `X_ROUTER_COMPAT_SYSTEM_MAX_BODY_BYTES` (default `10485760`)
- `X_ROUTER_COMPAT_DECOMPRESS_ENABLED` (default `true`)
- `X_ROUTER_COMPAT_WS_MAX_CONNECTIONS` (default `5000`)
- `X_ROUTER_COMPAT_WS_IDLE_TIMEOUT_MS` (default `60000`)
- `X_ROUTER_COMPAT_WS_PING_INTERVAL_MS` (default `15000`)
- `X_ROUTER_COMPAT_WS_UPSTREAM_CONNECT_TIMEOUT_MS` (default `5000`)

State loader is backward-compatible with legacy `snake_case` state documents.
Manual control endpoints:
- `POST /v1/x-router/state/save` forces snapshot save even when auto-save is disabled.
- `POST /v1/x-router/state/reload` reloads and replaces in-memory policy state from file.
Control-plane state concurrency:
- responses include `x-policy-state-hash`, `x-policy-state-revision`, `x-policy-state-updated-at-ms`.
- `GET /v1/x-router/state` returns current policy state metadata.
- mutating control-plane endpoints accept `x-policy-if-match: <hash>`.
- mismatch returns `409 XR_STATE_CONFLICT`.
- with `X_ROUTER_CONTROL_PLANE_IF_MATCH_REQUIRED=true`, missing precondition returns `428 XR_STATE_CONFLICT`.

## Endpoints

- `GET /health`
- `GET /ready`
- `GET /metrics`
- `GET /metrics/prometheus`
- `GET /v1/x-router/capabilities`
- `GET /v1/x-router/auth`
- `POST /v1/x-router/auth/reload`
- `PUT /v1/x-router/auth/keys/:tenantId`
- `DELETE /v1/x-router/auth/keys`
- `GET /v1/x-router/distributed-limiter`
- `GET /v1/x-router/openapi`
- `GET /v1/x-router/openapi/compat`
- `GET /v1/x-router/upstreams`
- `POST /v1/x-router/upstreams/probe`
- `PUT /v1/x-router/upstreams/nodes/:nodeId`
- `DELETE /v1/x-router/upstreams/nodes/:nodeId`
- `POST /v1/x-router/upstreams/nodes/:nodeId`
- `POST /v1/x-router/resolve-route`
- `POST /v1/x-router/resolve-route-batch`
- `POST /v1/x-router/select-channel`
- `POST /v1/x-router/affinity-key`
- `POST /v1/x-router/apply-overrides`
- `POST /v1/x-router/normalize-request`
- `POST /v1/x-router/simulate-billing`
- `GET /v1/x-router/tenants`
- `GET /v1/x-router/tenant-upstreams`
- `GET /v1/x-router/state`
- `POST /v1/x-router/state/reload`
- `POST /v1/x-router/state/save`
- `PUT /v1/x-router/tenants/:tenantId/policy`
- `DELETE /v1/x-router/tenants/:tenantId/policy`
- `PUT /v1/x-router/tenants/:tenantId/services/:serviceId/policy`
- `DELETE /v1/x-router/tenants/:tenantId/services/:serviceId/policy`
- `PUT /v1/x-router/tenants/:tenantId/upstreams`
- `DELETE /v1/x-router/tenants/:tenantId/upstreams`
- `PUT /v1/x-router/tenants/:tenantId/services/:serviceId/upstreams`
- `DELETE /v1/x-router/tenants/:tenantId/services/:serviceId/upstreams`

Compatibility relay surface (when `X_ROUTER_COMPAT_ENABLED=true`):
- `GET /v1/models`
- `GET /v1/models/:model`
- `POST /v1/models/*path`
- `GET /v1beta/models`
- `GET /v1beta/openai/models`
- `POST /v1beta/models/*path`
- `POST /pg/chat/completions`
- `GET /v1/realtime`
- `POST /v1/messages`
- `POST /v1/completions`
- `POST /v1/chat/completions`
- `POST /v1/responses`
- `POST /v1/responses/compact`
- `POST /v1/edits`
- `POST /v1/images/generations`
- `POST /v1/images/edits`
- `POST /v1/images/variations` (`XR_NOT_IMPLEMENTED` in strict mode)
- `POST /v1/embeddings`
- `POST /v1/audio/transcriptions`
- `POST /v1/audio/translations`
- `POST /v1/audio/speech`
- `POST /v1/rerank`
- `POST /v1/engines/:model/embeddings`
- `POST /v1/moderations`
- `POST /v1/video/generations`
- `GET /v1/video/generations/:taskId`
- `POST /v1/videos`
- `GET /v1/videos/:taskId`
- `GET /v1/videos/:taskId/content`
- `POST /v1/videos/:videoId/remix`
- `POST /kling/v1/videos/text2video`
- `GET /kling/v1/videos/text2video/:taskId`
- `POST /kling/v1/videos/image2video`
- `GET /kling/v1/videos/image2video/:taskId`
- `POST /jimeng`
- `/mj/*` and `/:mode/mj/*` (GET/POST)
- `POST /suno/submit/:action`
- `POST /suno/fetch`
- `GET /suno/fetch/:id`
- `/v1/files*`, `/v1/fine-tunes*` compatibility stubs in strict mode

Realtime compatibility details:
- `/v1/realtime` now performs Rust-native websocket relay to selected upstream nodes.
- The route keeps deterministic ingress errors (`426`, `503`, `504`) and exposes selected node via `x-compat-ws-node`.
- Before upgrade acceptance, the service performs upstream preflight dialing and returns `504 XR_UPSTREAM_UNAVAILABLE` on connect timeout.

Video compatibility details:
- `/v1/video/generations*` and `/v1/videos*` map to the Rust compat task pipeline.
- `/kling/v1/videos/*` and `/jimeng` are supported as compat task ingress paths.

Model compatibility provider precedence:
- `/v1beta/openai/models` is pinned to OpenAI semantics.
- `/v1beta/models` is pinned to Gemini semantics.
- `/v1/models/:model` defaults to OpenAI unless explicit Anthropic headers are present.
- `/v1/models` keeps header/query-based provider hints (`anthropic`/`gemini`/`openai`).

Model compatibility response semantics:
- OpenAI routes return `{"success":true,"object":"list","data":[...]}` for list and OpenAI model object for retrieve.
- Gemini list routes return `{"models":[...],"nextPageToken":null}`.
- Anthropic list routes return `{"data":[...],"first_id":"...","has_more":false,"last_id":"..."}`.

Tenant upstream policy payload (`PUT /v1/x-router/tenants/:tenantId/upstreams`):
- `allowedNodeIds`: non-empty upstream node id list.
- `mode`: `strict` (default) or `fallback`.
  - `strict`: only route to allowlisted nodes.
  - `fallback`: if allowlist has no enabled candidates, fallback to global enabled nodes.

Upstream node payload (`PUT /v1/x-router/upstreams/nodes/:nodeId`):
- `baseUrl`: required upstream URL.
- `enabled`: optional, defaults to `true`.
- `headers`: optional map of request headers forwarded to this upstream.
- `weight`: optional positive integer, defaults to `100` (used by `weighted-round-robin`).

Service namespace:
- Request header `x-service-id` (default `default`).
- Tenant governance and tenant upstream policy are scoped by `tenant + service`.

## Test

```bash
pnpm --filter @ku0/x-router-rs test:rs
pnpm --filter @ku0/x-router-rs verify:compat-routes
```

## Perf Smoke

```bash
pnpm --filter @ku0/x-router-rs perf:rs
pnpm --filter @ku0/x-router-rs perf:rs:realtime-local
pnpm --filter @ku0/x-router-rs perf:rs:realtime-kpi-local
```

Default profile is `compat-chat`. Runtime controls:
- `X_ROUTER_PERF_BASE_URL` (default `http://127.0.0.1:4317`)
- `X_ROUTER_PERF_PROFILE` (`compat-chat` | `compat-models` | `compat-video` | `compat-realtime` | `control-resolve`)
- `X_ROUTER_PERF_TOTAL_REQUESTS` (default `400`)
- `X_ROUTER_PERF_CONCURRENCY` (default `32`)
- `X_ROUTER_PERF_TIMEOUT_MS` (default `5000`)
- `X_ROUTER_PERF_WS_MESSAGES` (default `1`, applies to `compat-realtime`)
- `X_ROUTER_PERF_ASSERT_MAX_ERROR_RATE` (default `0.0`)
- `X_ROUTER_PERF_ASSERT_MAX_P95_MS` (default `0.0`, disabled when `0`)

`perf:rs:realtime-local` automatically starts:
- local upstream websocket echo fixture
- local x-router server with compat + upstream-only mode
- realtime perf profile run (`compat-realtime`) against that local stack

`perf:rs:realtime-kpi-local` runs two local realtime perf phases and enforces:
- `errorRate == 0` on low/high load
- `p95 <= X_ROUTER_PERF_KPI_MAX_P95_MS` (default `80`)
- `highThroughput / lowThroughput >= X_ROUTER_PERF_KPI_MIN_SCALE_FACTOR` (default `1.2`)