[mismosmi]

Adds a Cargo workspace under rust/ that brings the Toapi concepts to Rust:

• define the API once on the server
• generate OpenAPI from it, and a typed client from that
• authorize each route method, like the TypeScript server
• cache responses on the server and in the client by tag
• keep client caches fresh through tag-based invalidation and the invalidation stream

The client runs natively and in the browser (wasm32-unknown-unknown).

users-server (axum handlers + toapi-server)
   │  api().openapi()
   ▼
openapi.json  (committed; a test fails when it is out of date)
   │  toapi_client::generate!("../users-server/openapi.json")  (or toapi-codegen in build.rs)
   ▼
users-client  (api.users.id(1).get() path tree + request types + toapi-client runtime)

// server
Api::new("Users", "1.0.0")
    .cache(Arc::new(InMemoryCache::new()))
    .route("/users", get(public, list_users).post(signed_in, create_user))
    .route("/users/{id}", get(public, get_user).put(signed_in, update_user))

// client
toapi_client::generate!("../users-server/openapi.json");

let api = Api::new("http://localhost:3000/api");
let user  = api.users.id(123).get().await?;                 // Arc<User>, shared with the cache
let users = api.users.get().limit(10).await?;               // Arc<Vec<User>>
let user  = api.users.id(123).put().name("Alicia").role(Role::Member).await?;  // User
let user  = api.users.id(123).put().body(new_user).await?;
let mut live = api.users.id(123).get().watch();             // Stream<Item = Result<Arc<User>, Error>>

Crates

• toapi-core: wire constants, the naming scheme and the server Cache trait (with CacheEntry, Lookup and Invalidation), so cache implementations don't depend on the server. For GET /users/{id} the naming scheme gives GetUsersByIdRequest, GetUsersByIdQuery, PutUsersByIdRequestBody, GetUsersByIdResponseBody, GetUsersByIdCall and UsersByIdRoute.
• toapi-server: an Api builder on top of axum, created with Api::new(title, version) for the OpenAPI document.
  • GET handlers must return Cached<T> and mutations Invalidates<T>; anything else is a compile error.
  • Authorization: every route method takes an authorize first, like a TypeScript handler's authorize:
    • It's an async function of extractors that don't read the body, returning Result<A, E>. On Err, the error is the response.
    • public lets every request through.
    • Handlers read A with the Auth<A> extractor. route panics when a handler's Auth<A> isn't what its authorize returns.
  • Extractors implement OperationInput, which feeds the OpenAPI 3.1 document.
  • route panics if the {placeholders} don't match the handler's Path<T>.
  • Server-side cache, like the TypeScript server's Cache:
    • A GET runs authorize, then looks up its URL in the cache, then runs the handler on a miss.
    • A successful Cached<T> that explicitly set tags or a TTL is stored for its TTL, or .default_ttl(..) (14 days, like TS). Responses without either are never stored.
    • Mutations delete the entries carrying their tags before their response goes out, then notify the invalidation streams.
    • A response computed while one of its tags was invalidated isn't stored (lookups return a token that set checks).
    • PubSub (the default) caches nothing. toapi_cache::InMemoryCache caches within one process. Both are set with .cache(Arc::new(..)), and callers keep a clone to invalidate from background jobs.
    • Handlers invalidate imperatively through the RequestCache extractor, attributed to the calling client like req.invalidate.
  • The invalidation stream supports throttling, keepalive, a per-request tag filter, the session cookie and tag hashing.
• toapi-cache: server cache implementations, currently InMemoryCache.
• toapi-codegen: generates the client code from the OpenAPI document:
  • Path tree rooted at Api: static segments are fields, parameters are typed methods, and HTTP methods return call builders.
  • Call builders have one setter per query parameter and body field. Optional ones can be left out. Required ones are tracked in the builder's type, so leaving one out is a compile error that names the field (PostUsersCall<Set, Unset<required::role>> is not a future).
  • Whole-struct setters: .query(GetUsersQuery { .. }) and .body(NewUser { .. }) set all fields of a query or body struct at once, including the required ones.
  • Request structs (GetUsersByIdRequest) implement Request, with type Kind = Query for GET and Mutation otherwise. They can be built with .into_request() or run directly with client.call(..).
  • Name collisions and conflicting parameter names fail the build with an error naming both paths.
• toapi-macros: generate!, which runs the codegen at compile time.
  • The path is relative to the crate's Cargo.toml.
  • The crate is rebuilt when the document changes.
  • Errors point at the path literal.
  • It's re-exported by toapi-client, so no build script is needed.
  • The build-script route (toapi_codegen::build) is still available.
• toapi-client:
  • One Client::call(request), whose return type comes from the request's Kind:
    • GET requests return a QueryCall, which can be awaited or watched as a stream.
    • Mutations return a MutationCall, which resolves after the affected watched queries were refetched.
  • A cache that works like the TypeScript client's:
    • Stored in a DashMap, so reads only take a read lock on one shard.
    • The first query for a URL is cached immediately, as a shared future backed by its own task. Concurrent queries for the URL share that request, and it completes even if nobody waits for it anymore.
    • Each response is parsed once and kept as Arc<dyn Any + Send + Sync>. Queries and watch streams resolve to an Arc<T> of it, downcast without copying, so two queries for the same URL get the same allocation. Mutations aren't cached and resolve to plain values.
    • Invalidation deletes the entries whose tags (a HashSet) intersect the invalidated ones, and publishes their URLs to a pub-sub of callbacks, like the TypeScript client's PubSub. Publishing awaits all callbacks.
    • Failed requests are dropped after min_ttl, and responses with a TTL once it's over plus up to max_overdue_ttl. Both are set on ClientBuilder and match the TypeScript client's minTTL and maxOverdueTTL (defaults 100ms and 1s).
  • Watch streams subscribe a callback as soon as watch() is called:
    • When the stream's URL is invalidated, the callback refetches it through the cache and pushes the result into a tokio::sync::watch channel that the stream reads from.
    • The channel keeps only the latest result, so a stream nobody polls neither blocks invalidations nor piles up responses.
    • Dropping the stream, polled or not, unsubscribes the callback.
  • An invalidation stream listener that reconnects with backoff and drops the cache on reconnect.
  • WebAssembly: a small platform module covers what differs in the browser:
    • spawning and sleeping: wasm_bindgen_futures and gloo-timers instead of tokio
    • the clock: js_sys::Date::now()
    • Send bounds: MaybeSend, also used by the generated code
    • cookies: requests include credentials, and the browser keeps the session cookie
    • expiry jitter: a SplitMix64 counter, the same on all targets

The wire protocol (X-TAPI-Tags, X-TAPI-Expires-At, /__tapi/invalidations, /__tapi/openapi.json, the __tapi-session cookie, tag hashing) matches the TypeScript packages. The tag hash is pinned to the value @toapi/server produces.

Releasing the crates is tracked in #537 (switching to knope); this PR adds no changeset.

Not covered yet

Also listed in rust/README.md:

• Redis/Postgres caches, for caching across server processes
• NDJSON responses, multipart bodies and array query parameters

Testing

• Unit tests for:

  • naming
  • the server caches: PubSub and RequestCache (in toapi-server), and InMemoryCache (in toapi-cache: storing, invalidating, expiry, skipping responses older than an invalidation)
  • the client cache
  • codegen, including the tree, the whole-struct setters and conflict errors
  • tag hashing, the clock and the jitter

• Server caching tests (crates/toapi-server/tests/caching.rs), driven through the router:

  • tagged responses are served from the cache, with their tags and content type, keyed by URL including the query
  • responses without tags or a TTL, and errors, are never cached
  • TTL expiry, with the original X-TAPI-Expires-At kept on cache hits
  • mutations invalidate cached responses
  • authorize runs before the cache, so a rejected request never sees a cached response
  • handlers read the authorize result through Auth<A>
  • a mismatched Auth<A> panics when the route is added

• Client cache integration tests (crates/toapi-client/tests/cache.rs) against a counting server:

  • five concurrent queries make one HTTP request and one parse
  • later queries don't parse again and return the same Arc (Arc::ptr_eq)
  • invalidation refetches
  • a watched refetch is shared with the next query and done when invalidate resolves
  • a watch stream nobody polls doesn't block an invalidation, and its callback still refetches
  • dropped watch streams unsubscribe, whether polled or not
  • failed requests are retried after min_ttl, and min_ttl is configurable

• Browser tests (crates/toapi-client/tests/wasm.rs): the client compiled for wasm32-unknown-unknown, run in Node through wasm-bindgen-test-runner against an HTTP server written in JavaScript:

  • concurrent queries share one request and value
  • invalidation refetches watch streams
  • failed requests are retried after min_ttl
  • a watch stream follows another client's mutation through the invalidation stream

• A test that fails when openapi.json is out of date.

• End-to-end tests (examples/users-client/tests/e2e.rs) against the real server, which uses InMemoryCache, with the client generated by generate!:

  • queries and mutations through the tree, with field setters and with whole query/body structs
  • the request structs run with client.call
  • into_request() builds the expected structs
  • an unauthorized mutation returns 401
  • watch() follows the client's own mutations, and another client's mutation through the invalidation stream

• compile_fail doctests in users-client for:

  • a missing required body field
  • a wrongly typed path parameter
  • a method the route doesn't have
  • watch() on a mutation, through the tree and through client.call

• Checked manually:

  • touching openapi.json marks users-client dirty
  • a wrong path gives could not read …/openapi.jsn, pointing at the macro argument

• CI (rust job in ci.yml) runs:

  • cargo fmt --check, cargo clippy -D warnings and cargo test --workspace
  • clippy for wasm32-unknown-unknown on the client and the example client
  • the browser tests

  All of these pass locally.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QC3KeukVBedvsgLE1jWoGb

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5d813be

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR