Restspace v2 — User Manual

Comprehensive documentation for building on the Restspace v2 (RS2) runtime.

Who this is for. Anyone comfortable with HTTP, JSON, and a little JavaScript — roughly a mid-range front-end developer — who wants to stand up a backend out of composable services without writing a traditional server. No Rust or systems-programming background is assumed. Each part builds on the one before, so a first read works front-to-back; later it doubles as a reference.

Table of Contents

Part 1 — Orientation

• 1.1 What Restspace v2 is (services as functions on HTTP messages)
• 1.2 The mental model: tenants, mounts, services, pipelines
• 1.3 What you can build with it (and what it deliberately leaves out)
• 1.4 How this manual is organized & prerequisites

Part 2 — Getting Started

• 2.1 Installing the runtime and the rs2 CLI
• 2.2 Running your first node (serverConfig.json)
• 2.3 Writing a minimal tenant config
• 2.4 Making your first request (and reading the response)
• 2.5 Health checks and the developer loop

Part 3 — Core Concepts

• 3.1 Messages and bodies (bytes vs. streams, media types, provenance)
• 3.2 Tenants and mounts (longest-prefix routing, path safety)
• 3.3 The store pattern: one client codepath for every store
• 3.4 Patterns vs. facets (feature-detection over special-casing)
• 3.5 Capabilities and the sandbox (default-deny)
• 3.6 The instruction plane: what fully describes a tenant

Part 4 — Storing Files and Data

• 4.1 The file service: streamed reads and writes
• 4.2 Ranges, ETags, conditional GETs, and HEAD
• 4.3 Static-site & SPA hosting from a file mount
• 4.4 The data service: schema-validated JSON records
• 4.5 Schemas, validation errors, and JSON merge PATCH
• 4.6 Listings, pagination, and the ?confirm= delete guard
• 4.7 Choosing a storage backend and isolating mounts

Part 5 — Authentication & Access Control

• 5.0 The RS2 security model (the three tiers, the authority invariant)
• 5.1 The auth service: login, refresh, logout, current user
• 5.2 Users, password hashes, and roles
• 5.3 Tokens: JWTs, cookies, and bearer headers
• 5.4 Role specs on mounts (read/write/delete/invoke, path-scoped grants, per-spec access)
• 5.5 CORS, trusted vs. allowed origins, and the CSRF guard

Part 6 — Querying and Rendering Data

• 6.1 The query service: stored queries authored like files
• 6.2 Parameters: URL segments, query strings, and request bodies
• 6.3 JSON templates (structural, injection-safe substitution)
• 6.4 String/SQL templates and bind parameters
• 6.5 Param schemas, defaults, and validation
• 6.6 Rendering HTML with the template service

Part 7 — Composing with Pipelines

• 7.1 The pipeline service: authored like files, run on any verb
• 7.2 The typed spec and the string DSL (two inputs, one stored form)
• 7.3 Step kinds: call, transform, pipeline, split
• 7.4 Modes: serial, parallel, conditional, tee/teeWait
• 7.5 Conditions, ${...} interpolation, and captured variables
• 7.6 Transforms with JSONata
• 7.7 Retries, effect classes, and idempotency
• 7.8 Segments and the ?$plan introspection
• 7.9 Debugging a pipeline
• 7.10 Wrappers and response shaping
• 7.11 Webhooks, schedules, and polling connectors

Part 8 — Custom Services (Your Own Code)

• 8.1 When to reach for custom code (vs. a pipeline or query)
• 8.2 The JavaScript service contract (handle, msg, ctx)
• 8.3 The supported API surface (the npm-compat prelude)
• 8.4 The WebAssembly service contract (Rust components against the WIT world)
• 8.5 Capability grants: internal prefixes and outbound HTTP
• 8.6 Building, bundling, and deploying (rs2 deploy)
• 8.7 Versioning, rollback, and mounting code: refs
• 8.8 Limits inside the sandbox and diagnosing failures
• 8.9 Loadable storage adapters (bring your own backend)
• 8.10 The proxy and sms services
• 8.11 Discovery manifests and external catalogues

Part 9 — The HTTP API & Cross-Cutting Behavior

• 9.1 The discovery surface (/.well-known/rs2/*) and OpenAPI
• 9.2 Structured errors (application/problem+json) and error codes
• 9.3 Idempotency keys and replay
• 9.4 Caching: the universal caching config and conditional revalidation
• 9.5 Limits, containment, and the per-tenant circuit breaker
• 9.6 Tracing: X-Trace-Id and correlating to logs

Part 10 — Operating a Node

• 10.1 Server config in depth (listener, file root, tenants dir)
• 10.2 Single- vs. multi-tenant deployments (domain maps, subdomains)
• 10.3 Logging & observability (the log service, sinks, severities)
• 10.4 Editing config safely (PUT /services/raw, dry-build, hot-swap)
• 10.5 Deploying and rotating custom code on a running node
• 10.6 Secrets handling (write-only config fields)
• 10.7 Operator infras, first-admin bootstrap, and production boundaries

Part 11 — Migrating from v1 Restspace

• 11.1 What rs2 migrate carries over
• 11.2 What is warned, adjusted, or skipped
• 11.3 Post-migration checklist (secrets, users, pipelines, queries)

Appendices

• A. Glossary of terms
• B. Tenant config reference (every key)
• C. Error code reference
• D. Default limits and how to change them
• E. The rs2 CLI command reference
• F. Further reading (PRD, architecture notes, the operator skill)
• G. How the JavaScript (V8 isolate) engine works
• H. How the WebAssembly (Wasmtime) engine works