tensor-wasm-api 0.3.8

HTTP serverless API gateway (axum).
Documentation

tensor-wasm-api

HTTP serverless API gateway for Craton TensorWasm, built on axum. Exposes REST endpoints for deploying modules, invoking instances synchronously and asynchronously, polling job status, scraping metrics, and health-checking the node. Wraps the routes in a Tower middleware stack covering request tracing, per-request timeouts, a process-wide concurrency cap, a 64 MiB body limit, bearer-token authentication, and tenant-header scoping. Ships the axum app builder and listener wiring that production deployments hook into.

Security surface

  • Body limit (64 MiB). Every inbound request is capped via axum::extract::DefaultBodyLimit::max. Larger bodies are rejected with 413 Payload Too Large before any handler runs.
  • CORS allowlist. Cross-origin browser callers are rejected by default; widen via TENSOR_WASM_API_CORS_ALLOWED_ORIGINS=https://app.example.com,https://admin.example.com. The layer admits GET/POST/DELETE and the standard Authorization, Content-Type, X-TensorWasm-Tenant, and Traceparent headers.
  • Bearer-token auth via TENSOR_WASM_API_TOKENS. A comma-separated allowlist of accepted tokens. Empty/unset puts the gateway in dev mode (warn-once on startup, requests pass through). When set, callers must send Authorization: Bearer <token>.
  • Tenant scoping via X-TensorWasm-Tenant header. The header is parsed as a u64 and threaded through to the executor. Absent header defaults to tenant 0; set TENSOR_WASM_API_REQUIRE_TENANT=1 to make the header mandatory.
  • Snapshot HMAC key via TENSOR_WASM_API_SNAPSHOT_HMAC_KEY (hex, 64 chars). Optional. When set, the upcoming /snapshot/save and /snapshot/restore routes will HMAC-SHA256 sign on save and verify on restore. Malformed-but-set is a hard startup error so a typo never silently degrades to the no-signing path. The routes themselves are not yet wired (v0.4); the env knob is parsed today so manifests can be staged ahead of time.
  • Snapshot strict-verify via TENSOR_WASM_API_SNAPSHOT_REQUIRE_SIGNATURE (true/false, default false). Optional. When true, snapshot restore refuses v2 (unsigned) blobs even when a signing key is configured.
  • XFCC trusted-proxy allowlist via TENSOR_WASM_API_TRUSTED_XFCC_PROXIES. Comma-separated list of IPv4/IPv6 addresses or CIDR ranges (e.g. 10.0.0.0/8,127.0.0.1,::1) whose X-Forwarded-Client-Cert headers the audit middleware will honour. Empty / unset = trust nobody (safe default — every inbound XFCC is dropped before reaching the audit record). Operators behind an mTLS-terminating reverse proxy should set this to the proxy's IP(s); deployments without such a proxy must leave it unset so attacker-supplied Subject values never enter the audit stream.

See API.md for the full wire-format reference.

What ships in 0.3.x

The W2.x hardening wave layers the following on top of the core deploy/invoke surface:

  • W1.4 Rate limiting. Per-token leaky bucket; over-limit callers receive 429 Too Many Requests with Retry-After.
  • W2.1 Scoped tokens. Per-tenant authorization; cross-tenant access surfaces as a 403 envelope.
  • W2.2 Audit log. Structured JSON records every authenticated request through a sink-pluggable writer.
  • W2.3 HTTP metrics. Prometheus exposition at /metrics covering request counts, duration histograms, and per-route labels.

Feature flags

This crate exposes no Cargo features; it compiles identically in every workspace configuration.

See docs/BUILD.md for the project-wide flag taxonomy.

Dependencies

External crates this crate depends on (pinned at workspace root):

  • tokio — async runtime hosting the HTTP server.
  • axum — web framework providing the router and extractors.
  • tower — middleware abstractions stacked onto the router.
  • tower-http — ready-made middleware (timeout, trace, CORS). Body-limit uses axum's native DefaultBodyLimit::max rather than the tower-http layer.
  • subtle — constant-time byte comparison used by bearer-token allowlist lookup.
  • hyper — underlying HTTP/1 and HTTP/2 transport.
  • thiserror — derive macro for API error variants.
  • tracing — structured spans/events for request handling.
  • tracing-opentelemetry — bridges tracing spans into OpenTelemetry contexts so the W3C traceparent header stitches traces across services.
  • opentelemetry — propagator API used by the trace layer to extract incoming traceparent headers.
  • serde — derive support for request/response DTOs.
  • serde_json — JSON encoding of API payloads.
  • wasmparser — full structural validation of inbound Wasm modules at deploy time.
  • base64 — decoding wasm_b64 deploy payloads.
  • dashmap — concurrent in-memory function and job registries.
  • uuid — server-assigned function and job identifiers.

Internal crate dependencies:

  • tensor-wasm-core — error envelope mapping, shared metrics, type primitives.
  • tensor-wasm-exec — drives TensorWasmExecutor for the synchronous and async invoke paths.