@weft-js/start 0.1.1 → 0.1.3

package/crate/Cargo.toml

@@ -0,0 +1,72 @@
+[package]
+name = "weft"
+version = "0.0.1"
+edition = "2024"
+license = "MIT"
+description = "The Rust side of weft's remote() and native(): generated types from .weft/contract.json, Ctx, the signed envelope, an axum Router, a Node-API and WASM entry"
+
+[features]
+default = ["server"]
+# What generated code needs on any target.
+core = ["dep:chrono", "dep:regress", "dep:serde", "dep:serde_json", "dep:uuid"]
+# What a sidecar links.
+server = ["core", "dep:axum", "dep:base64", "dep:hmac", "dep:sha2", "dep:tokio", "dep:tracing", "dep:tracing-subscriber"]
+# What a `native()` crate links, with `default-features = false`: an addon, or a .wasm on that target. No server, no tokio.
+native = ["core", "dep:napi", "dep:napi-derive"]
+# `span.set_parent` from the envelope's traceparent, for an app that installs an OpenTelemetry layer.
+otel = ["server", "dep:opentelemetry", "dep:tracing-opentelemetry"]
+# What a sidecar's build.rs links, with `default-features = false`: nothing of the server.
+build = ["dep:napi-build", "dep:prettyplease", "dep:schemars", "dep:serde_json", "dep:syn", "dep:typify"]
+
+[dependencies]
+axum = { version = "0.8.9", default-features = false, features = ["http1", "json", "tokio"], optional = true }
+base64 = { version = "0.23", optional = true }
+chrono = { version = "0.4", default-features = false, features = ["clock", "serde", "std"], optional = true }
+hmac = { version = "0.13", optional = true }
+napi-build = { version = "2.4", optional = true }
+opentelemetry = { version = "0.33", optional = true }
+prettyplease = { version = "0.3", optional = true }
+regress = { version = "0.11", optional = true }
+schemars = { version = "0.8.22", optional = true } # the version typify reads
+serde = { version = "1", features = ["derive"], optional = true }
+serde_json = { version = "1", optional = true }
+sha2 = { version = "0.11", optional = true }
+syn = { version = "3", features = ["full"], optional = true }
+tokio = { version = "1.54", features = ["macros", "net", "rt-multi-thread", "signal", "time"], optional = true }
+tracing = { version = "0.1", optional = true }
+tracing-opentelemetry = { version = "0.34", optional = true }
+tracing-subscriber = { version = "0.3", default-features = false, features = ["ansi", "env-filter", "fmt"], optional = true }
+typify = { version = "0.8.0", optional = true }
+uuid = { version = "1", features = ["serde"], optional = true }
+
+# Not on wasm: there the crate exports a small ABI of its own (src/native.rs).
+[target.'cfg(not(target_family = "wasm"))'.dependencies]
+napi = { version = "3.12", default-features = false, features = ["dyn-symbols", "napi4"], optional = true }
+napi-derive = { version = "3.6", optional = true }
+
+[dev-dependencies]
+tower = { version = "0.5", features = ["util"] }
+
+[lib]
+doctest = true
+
+[lints.rust]
+unsafe_op_in_unsafe_fn = "deny"
+
+[lints.clippy]
+pedantic = { level = "deny", priority = -1 }
+unwrap_used = "deny"
+undocumented_unsafe_blocks = "deny"
+allow_attributes_without_reason = "deny"
+# Pedantic lints that cost more than they catch here. Byte offsets are u32 by Oxc's design; the rest are taste.
+cast_possible_truncation = "allow"
+cast_possible_wrap = "allow"
+cast_sign_loss = "allow"
+cast_precision_loss = "allow"
+module_name_repetitions = "allow"
+must_use_candidate = "allow"
+missing_errors_doc = "allow"
+missing_panics_doc = "allow"
+too_many_lines = "deny"
+similar_names = "allow"
+struct_excessive_bools = "allow"

package/crate/README.md

@@ -0,0 +1,322 @@
+<p align="center">
+  <a href="https://github.com/Ravonus/weft">
+    <img src="https://raw.githubusercontent.com/Ravonus/weft/main/site/public/logo.svg" width="88" height="88" alt="Weft">
+  </a>
+</p>
+
+<h1 align="center">weft (Rust crate)</h1>
+
+<p align="center">
+  <strong>The Rust side of Weft's <code>remote()</code> and <code>native()</code>: server functions declared in TypeScript, implemented in Rust.</strong><br>
+  Zod stays the source of truth. The crate generates the types, a <code>Service</code> trait and the transport, so a contract change stops <code>cargo</code> where the Rust no longer fits.
+</p>
+
+<p align="center">
+  <a href="../../LICENSE"><img src="https://img.shields.io/badge/license-MIT-145c3c" alt="MIT license"></a>
+  <img src="https://img.shields.io/badge/rust-1.99.1-145c3c" alt="Rust toolchain 1.99.1">
+  <img src="https://img.shields.io/badge/edition-2024-145c3c" alt="Rust edition 2024">
+</p>
+
+<p align="center">
+  <a href="#quick-start">Quick start</a> ·
+  <a href="../../site/content/learn/rust.md">Rust guide</a> ·
+  <a href="../../packages/cli/docs/rust.md">Rust reference</a> ·
+  <a href="../README.md">All crates</a>
+</p>
+
+> [!NOTE]
+> This crate is not on crates.io. `@weft-js/start` ships a copy of it in its package as `crate/` (written at `prepack`
+> by `packages/start/scripts/crate.mjs`, without `target/` and `tests/`), and an app's `Cargo.toml` points there by
+> path. That copy is always the version the installed TypeScript speaks. `weft add rust` writes the dependency for you.
+
+A Weft server function can have a Rust body instead of a TypeScript `run`. You declare it in TypeScript with Zod, as
+any other function, and give it `impl: <target>`. `weft check`, `weft dev` and `weft build` write the schemas to
+`.weft/contract.json`, and this crate's `build` feature turns that file into Rust: a struct per input and output, a
+typed error enum per function, and one `Service` trait. You implement the trait; the crate serves it as an HTTP sidecar
+(`remote()`) or exports it in-process as a Node-API addon or a `.wasm` (`native()`).
+
+TypeScript keeps the public edge: sessions, CSRF, the cache and validation on both sides of the call. Rust only sees
+input that already passed, and claims, never cookies.
+
+## Highlights
+
+- **No hand-written Rust types.** `weft::build::generate("<service>")` reads `.weft/contract.json` and writes the types
+  with typify, the error enums, the `Service` trait and `functions()` into `OUT_DIR`.
+- **Drift stops the build.** A contract that changes reruns the build script, and `cargo` fails exactly where the
+  implementation no longer fits. Weft reports it as `R103` with the function's id.
+- **The context matches the declaration.** A function gets `Ctx`, `UserCtx` (`auth: 'user'`) or `SharedCtx` (a shared
+  cache), and `SharedCtx` has no `user()` at all, so leaking per-user data into a shared result is a compile error.
+- **Signed calls.** A sidecar call carries `weft-ctx` and `weft-sig` headers: an HMAC-SHA256 over the function id, the
+  context and the body, with `iat` checked against a 60-second skew.
+- **One reply shape on every transport.** `{ "ok": true, "value", "tags", "touched" }` or
+  `{ "ok": false, "error": { "code", … } }`, from HTTP, Node-API and WASM alike.
+- **A panic is one failed call.** Each sidecar call runs in its own task with the deadline TypeScript sent; a panic or
+  an overrun answers that call and leaves the process serving.
+- **Feature-gated.** A `native()` addon links no server and no tokio; a build script links only the generator.
+
+## Contents
+
+- [Quick start](#quick-start)
+- [Features](#features)
+- [The generated contract](#the-generated-contract)
+- [Contexts](#contexts)
+- [`remote()`: the sidecar](#remote-the-sidecar)
+- [`native()`: in-process](#native-in-process)
+- [Errors](#errors)
+- [API reference](#api-reference)
+- [Troubleshooting](#troubleshooting)
+- [Build and test](#build-and-test)
+
+## Quick start
+
+In an app, let the CLI write the crate:
+
+```bash
+weft add rust media            # native(): an in-process addon
+weft add rust search --remote  # remote(): a sidecar
+```
+
+For `remote()`, the crate depends on `weft` twice: the default features for the sidecar, and only `build` for the build
+script. With the copy inside `@weft-js/start`, that looks like this:
+
+```toml
+[dependencies]
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+weft = { path = "../../node_modules/@weft-js/start/crate" }
+
+[build-dependencies]
+weft = { path = "../../node_modules/@weft-js/start/crate", default-features = false, features = ["build"] }
+```
+
+```rust
+// build.rs
+fn main() {
+    weft::build::generate("search");
+}
+```
+
+```rust
+// src/main.rs
+weft::contract!();
+use contract::*;
+
+struct Search;
+
+impl Service for Search {
+    async fn search_docs(
+        &self,
+        ctx: weft::SharedCtx,
+        input: SearchDocsInput,
+    ) -> Result<SearchDocsOutput, weft::Error> {
+        ctx.touch("docs");
+        Ok(vec![])
+    }
+}
+
+#[tokio::main]
+async fn main() -> std::io::Result<()> {
+    weft::serve(weft::router(contract::functions(Search))).await
+}
+```
+
+For `native()`, the crate is a `cdylib`, depends on `weft` with `default-features = false, features = ["native"]`, and
+replaces `main` with one line:
+
+```rust
+weft::native!(contract::functions(Media));
+```
+
+The [Rust guide](../../site/content/learn/rust.md) walks through both, including the TypeScript side.
+
+## Features
+
+| Feature | Default | Enables | Use it for |
+|---|---|---|---|
+| `core` | via `server` | `chrono`, `regress`, `serde`, `serde_json`, `uuid`; the `Ctx` types, `Functions`, `Error` | What generated code needs on any target |
+| `server` | yes | `core` plus `axum`, `tokio`, `hmac`, `sha2`, `base64`, `tracing`, `tracing-subscriber`; `router`, `router_with`, `serve`, `sign`, `verify` | A `remote()` sidecar |
+| `native` | no | `core` plus `napi`, `napi-derive` (not on wasm); `weft::native!` | A `native()` crate, as an addon or a `.wasm`. No server, no tokio |
+| `otel` | no | `server` plus `opentelemetry`, `tracing-opentelemetry` | Continue the trace TypeScript started, for an app that installs an OpenTelemetry layer |
+| `build` | no | `typify`, `schemars`, `syn`, `prettyplease`, `napi-build`, `serde_json`; `weft::build::generate` | A sidecar's or addon's `build.rs` |
+
+## The generated contract
+
+`weft::build::generate(service)` does this, in a build script:
+
+1. Finds the contract: `WEFT_CONTRACT` if set, else the nearest `.weft/contract.json` above the crate.
+2. Turns each function of `service` into Rust. Names convert from camelCase: `searchDocs` becomes the method
+   `search_docs` and the types `SearchDocsInput`, `SearchDocsOutput`. Two files that export the same name are kept
+   apart by the function id.
+3. Writes `OUT_DIR/weft_contract.rs`, and a copy to read at `.weft/rust/<service>.rs` (a build never depends on the
+   copy).
+4. For a `native` service on a non-wasm target, runs `napi_build::setup()` so the linker accepts the host's `napi_*`
+   symbols.
+
+`weft::contract!()` includes the generated file as `pub mod contract`, which holds:
+
+| Item | What it is |
+|---|---|
+| `<Name>Input`, `<Name>Output` | serde types for each function, from its Zod schemas |
+| `<Name>Error` | A typed error enum, for each function that declares `errors` |
+| `trait Service` | One `async fn` per function, each taking the context its declaration calls for |
+| `fn functions(service) -> weft::Functions` | The dispatch table that `weft::router` serves and `weft::native!` exports |
+| `const CONTRACT_HASH` | The contract's hash. The sidecar's health check reports it, and neither side runs a binary built from another one |
+
+## Contexts
+
+The generated trait picks one context per function, from its declaration in TypeScript:
+
+| Type | When | `user()` |
+|---|---|---|
+| `weft::Ctx` | default | `Option<&User>`, as `ctx.user` is nullable in TypeScript |
+| `weft::UserCtx` | `auth: 'user'` | `&User`: TypeScript refused the call otherwise |
+| `weft::SharedCtx` | a shared cache (`cache: { life }`) | none: the value is shared by every user |
+
+All three dereference to `weft::Base`, which has:
+
+| Method | What it does |
+|---|---|
+| `touch(table)` | Report a table this call read or wrote. `weft dev` checks it against the function's tags (Q011) |
+| `tag(tag)` | Add a cache tag to the result, or in a mutation a tag to invalidate. Rust can add tags, never remove declared ones |
+| `function()` | The function's id, as the contract spells it |
+| `request_id()` | The id TypeScript gave this request. The client sees it on an `Internal` failure, so log it |
+| `traceparent()` | The W3C `traceparent` TypeScript sent, if any |
+| `remaining()` | What's left of the deadline |
+| `cancelled()` | `true` once the deadline has passed, so long CPU loops can stop |
+
+`weft::User` carries `id`, `roles`, an optional `tenant`, and any other claims in `extra`; `has_role(role)` checks
+`roles`. These are only what `remote({ claims })` chose to send.
+
+## `remote()`: the sidecar
+
+`weft::router(functions)` returns an axum `Router`, so a sidecar can be one binary or part of a larger axum app:
+
+| Route | What it does |
+|---|---|
+| `POST /_weft/fn/{id}` | Verify the signature, deserialize `{ "input": … }`, run the function in its own task under the deadline, answer |
+| `GET /_weft/health` | `{ ok, service, contract, functions, pid }`, for the supervisor |
+
+`router` reads its key from `WEFT_RUST_SECRET` and panics with `R106` when it is unset, because a sidecar that took
+unsigned calls would trust any process that could reach it. `router_with(functions, secret)` takes the key directly.
+
+`weft::serve(router)` listens on `WEFT_LISTEN` (`127.0.0.1:0` when unset), prints `weft-listening <addr>` for the
+supervisor, logs to stderr by `RUST_LOG` (default `info`) unless the app installed a subscriber, and drains on SIGTERM
+or Ctrl-C.
+
+### The envelope
+
+Each call carries two headers:
+
+```text
+weft-ctx: base64url(JSON of the Envelope)
+weft-sig: hex(HMAC-SHA256(secret, "weft1\n" + id + "\n" + weft-ctx + "\n" + body))
+```
+
+The envelope is `{ user, requestId, deadlineMs, traceparent, iat }`. The signature covers the function id and the body
+as well as the claims, so a signed call can't be replayed against another function or with another input, and `iat`
+bounds how long it can be replayed at all (`MAX_SKEW_MS` is `60_000`). `weft::sign` and `weft::verify` are public, for
+tests and other hosts.
+
+### What a call answers
+
+| Outcome | Status | Body |
+|---|---|---|
+| Value | 200 | `{ "ok": true, "value": …, "tags": […], "touched": […] }` |
+| Declared error | 200 | `{ "ok": false, "error": { "code": …, "data": … } }` |
+| Panic, `weft::Error`, or a result that doesn't serialize | 500 | `{ "ok": false, "error": { "code": "Internal", "requestId": … } }`; the detail stays in the sidecar's log |
+| Input serde refuses, or claims that don't fit the context | 422 | `{ "ok": false, "error": { "code": "Drift", "message": … } }` |
+| Unknown function id | 404 | `Drift`, naming the id |
+| Missing, malformed or wrong signature, or stale `iat` | 401 | `Refused` |
+| Deadline passed | 504 | `Deadline` |
+
+When TypeScript hangs up, axum drops the handler's future and the crate aborts the task.
+
+### Tracing
+
+Each call runs in a `weft.fn` span with `function`, `request_id`, `trace_id` and `parent_id` fields, taken from the
+envelope's `traceparent`. With the `otel` feature, the span's parent is set from `traceparent`, so the call continues
+the trace TypeScript started.
+
+## `native()`: in-process
+
+`weft::native!(contract::functions(Svc))` exports the service from a `cdylib`. There is no HTTP and no signature,
+because nothing outside the process can reach it. The service is built on the first call, not while the library loads.
+
+| Target | Exports | How a call runs |
+|---|---|---|
+| Node-API addon | `call(id, ctx, body)` (async), `contract()` | On the host's worker pool, so a long call doesn't hold the event loop |
+| `wasm32` | `weft_init`, `weft_alloc`, `weft_free`, `weft_call`, `weft_contract`; imports `weft.now` and `weft.panicked` | On whatever thread calls it. Returns `pointer << 32 | length` |
+
+`contract()` returns `{ service, hash, functions }`, and TypeScript refuses a library built from another contract
+(R103).
+
+> [!WARNING]
+> `native()` brings no async runtime. It is for CPU work. A function that waits on IO belongs in `remote()`: on the
+> WASM build a method that doesn't complete without waiting panics.
+
+## Errors
+
+A function that declares no `errors` returns `weft::Error`. Any `std::error::Error` converts into it, so `?` works, and
+`weft::Error::msg("…")` makes one from text. It always becomes an `Internal` failure: the client gets the request id
+and the detail stays on the server.
+
+A function that declares `errors` returns its generated `<Name>Error` enum, which implements `weft::Failure` and
+serializes as `{ "code": …, "data": … }`. TypeScript checks it against the declaration, and the client catches
+`e.code` and `e.data`.
+
+## API reference
+
+| Item | Feature | Description |
+|---|---|---|
+| `weft::contract!()` | any | Include the generated contract as `pub mod contract` |
+| `weft::native!(functions)` | `native` | Export the functions as a Node-API addon, or as a `.wasm` on that target |
+| `weft::build::generate(service)` | `build` | Generate the contract in a build script. Panics with `R103` and a fix when it can't |
+| `weft::router(functions)` | `server` | An axum `Router` keyed by `WEFT_RUST_SECRET` |
+| `weft::router_with(functions, secret)` | `server` | The same, with the key in hand |
+| `weft::serve(router)` | `server` | Serve on `WEFT_LISTEN` and drain on SIGTERM or Ctrl-C |
+| `weft::sign(secret, id, ctx, body)` | `server` | The `weft-sig` value for a call |
+| `weft::verify(secret, id, ctx, sig, body, now_ms)` | `server` | Check a call and decode its `Envelope`, or say why it is `Refused` |
+| `weft::Refused` | `server` | `Malformed`, `BadSignature` or `Stale` |
+| `weft::Ctx`, `UserCtx`, `SharedCtx` | `core` | The three contexts |
+| `weft::Base`, `FromBase` | `core` | What every context has, and how generated code builds a context from it |
+| `weft::User`, `Envelope` | `core` | The claims, and what TypeScript sends about a call |
+| `weft::Functions` | `core` | A service's functions by contract id |
+| `weft::Error`, `Failure`, `Failed` | `core` | The default error, the trait an error type implements, and what it becomes on the wire |
+
+## Troubleshooting
+
+| Message | Cause and fix |
+|---|---|
+| `R103: no .weft/contract.json above this crate` | The build script found no contract. Run `weft dev` or `weft check` in the app, or set `WEFT_CONTRACT` |
+| `R103: …` with a function's name from `cargo` | The contract changed and the Rust no longer matches. Update the `impl Service` |
+| `R106: WEFT_RUST_SECRET is not set` | `weft dev` and `weft start` set it. A sidecar deployed on its own needs the same value as the server |
+| `Refused`: the signature doesn't match | `WEFT_RUST_SECRET` differs between the two sides |
+| `Refused`: signed too long ago | A clock is more than 60 seconds off |
+| `Drift` | The sidecar and TypeScript were built from different contracts. Rebuild the sidecar |
+
+The full list of Rust codes, R101 to R109, is in the [Rust reference](../../packages/cli/docs/rust.md).
+
+## Build and test
+
+The toolchain is pinned in `rust-toolchain.toml` to Rust `1.99.1` with `clippy` and `rustfmt`.
+
+```bash
+cd crates/weft
+cargo test                                 # default features: unit tests, tests/router.rs and doc tests
+cargo test --features build,otel           # also the generator's and the otel layer's unit tests
+cargo clippy --all-targets -- -D warnings
+```
+
+The `build` and `otel` modules exist only with their features, so their unit tests run only when those are on.
+
+`tests/router.rs` drives the router as TypeScript meets it: a signed POST and each way a call can end (a value with
+both reports, the declared context enforced at run time, a typed error, a panic, the deadline, drift, an unknown
+function, a bad signature, and the health check). `src/ctx.rs` holds a `compile_fail` doc test proving `SharedCtx` has
+no `user()`. `evals/gates/phase5a-exit.mjs` and `evals/gates/phase5b-exit.mjs` build real crates against this one.
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for the repository workflow.
+
+## License
+
+[MIT](../../LICENSE)

package/crate/rust-toolchain.toml

@@ -0,0 +1,3 @@
+[toolchain]
+channel = "1.99.1"
+components = ["clippy", "rustfmt"]

package/crate/src/build/emit.rs

@@ -0,0 +1,103 @@
+//! Emit each function's types, errors, trait method and dispatch entry.
+
+use std::fmt::Write as _;
+
+use typify::TypeSpace;
+
+use super::{Spec, add, alias};
+
+pub(super) fn function(
+    s: &Spec<'_>,
+    space: &mut TypeSpace,
+    extra: &mut String,
+    body: &mut String,
+    methods: &mut String,
+    table: &mut String,
+) -> Result<(), String> {
+    let name = &s.type_name;
+    let input = match &s.input {
+        Some(schema) => {
+            *extra += &alias(
+                &format!("{name}Input"),
+                &add(space, schema, &format!("{name}Input"))?,
+            );
+            format!(", input: {name}Input")
+        }
+        None => String::new(),
+    };
+    *extra += &alias(
+        &format!("{name}Output"),
+        &add(space, &s.output, &format!("{name}Output"))?,
+    );
+
+    let error = error(s, space, extra, body)?;
+
+    let _ = writeln!(
+        methods,
+        "/// `{id}`\nfn {method}(&self, ctx: ::weft::{ctx}{input}) -> impl ::std::future::Future<Output = ::std::result::Result<{name}Output, {error}>> + Send;",
+        id = s.id,
+        method = s.method,
+        ctx = s.ctx,
+    );
+    let (param, args) = if s.input.is_some() {
+        (format!("input: {name}Input"), "ctx, input")
+    } else {
+        ("_: ()".to_string(), "ctx")
+    };
+    let _ = writeln!(
+        table,
+        ".add({id:?}, {{ let s = service.clone(); move |ctx: ::weft::{ctx}, {param}| {{ let s = s.clone(); async move {{ s.{method}({args}).await }} }} }})",
+        id = s.id,
+        ctx = s.ctx,
+        method = s.method,
+    );
+    Ok(())
+}
+
+fn error(
+    s: &Spec<'_>,
+    space: &mut TypeSpace,
+    extra: &mut String,
+    body: &mut String,
+) -> Result<String, String> {
+    let name = &s.type_name;
+    Ok(if s.errors.is_empty() {
+        "::weft::Error".to_string()
+    } else {
+        let mut variants = String::new();
+        for (code, schema) in &s.errors {
+            let data = format!("{name}{code}");
+            *extra += &alias(&data, &add(space, schema, &data)?);
+            let _ = writeln!(variants, "{code}({data}),");
+        }
+        let _ = write!(
+            *body,
+            r#"
+/// `{id}`'s declared errors, and `Internal` for the rest: any `std::error::Error` converts, so `?` works.
+#[derive(Debug, ::serde::Serialize)]
+#[serde(tag = "code", content = "data")]
+pub enum {name}Error {{
+    {variants}
+    #[serde(skip)]
+    Internal(::std::string::String),
+}}
+impl<E: ::std::error::Error> ::std::convert::From<E> for {name}Error {{
+    fn from(e: E) -> Self {{ Self::Internal(e.to_string()) }}
+}}
+impl ::weft::Failure for {name}Error {{
+    fn failed(self) -> ::weft::Failed {{
+        match self {{
+            Self::Internal(detail) => ::weft::Failed::Internal(detail),
+            typed => match ::serde_json::to_value(typed) {{
+                Ok(v) => ::weft::Failed::Typed(v),
+                Err(e) => ::weft::Failed::Internal(e.to_string()),
+            }},
+        }}
+    }}
+}}
+"#,
+            id = s.id,
+        );
+        format!("{name}Error")
+    })
+}