@weft-js/start 0.1.1 → 0.1.2

package/crate/src/ctx.rs

@@ -0,0 +1,186 @@
+//! What a handler knows about its call. There are three, and the generated trait picks one per function from its
+//! declaration, so what TS guarantees is a compile error in Rust rather than a convention:
+//!
+//! - [`Ctx`]: `ctx.user()` is an `Option`, as `ctx.user` is nullable in TS.
+//! - [`UserCtx`] (`auth: 'user'`): `ctx.user()` is the user; TS refused the call otherwise.
+//! - [`SharedCtx`] (`cache: { life }`): there is no `user()` at all, because the value is shared by every user.
+//!
+//! ```compile_fail
+//! fn leaks(ctx: weft::SharedCtx) { let _ = ctx.user(); }
+//! ```
+
+use std::ops::Deref;
+use std::sync::{Arc, Mutex};
+use std::time::Duration;
+
+use serde::Deserialize;
+
+/// The claims TS sends: never the session, and only what `remote({ claims })` chose to send.
+#[derive(Debug, Clone, Deserialize)]
+pub struct User {
+    pub id: String,
+    #[serde(default)]
+    pub roles: Vec<String>,
+    #[serde(default)]
+    pub tenant: Option<String>,
+    /// Anything else a `claims` function returned.
+    #[serde(flatten)]
+    pub extra: serde_json::Map<String, serde_json::Value>,
+}
+
+impl User {
+    pub fn has_role(&self, role: &str) -> bool {
+        self.roles.iter().any(|r| r == role)
+    }
+}
+
+/// What TS tells a sidecar or an addon about the call. Claims only: never a cookie or a session token.
+#[derive(Debug, Clone, Deserialize)]
+#[serde(rename_all = "camelCase")]
+pub struct Envelope {
+    pub user: Option<User>,
+    pub request_id: String,
+    pub deadline_ms: u64,
+    pub traceparent: Option<String>,
+    /// Milliseconds since the epoch when TS signed it. Nothing signs an in-process call.
+    #[serde(default)]
+    pub iat: u64,
+}
+
+/// A monotonic clock. `Instant::now()` panics on wasm32-unknown-unknown, so there the host tells the time.
+#[cfg(not(target_family = "wasm"))]
+fn clock() -> Duration {
+    static START: std::sync::OnceLock<std::time::Instant> = std::sync::OnceLock::new();
+    START.get_or_init(std::time::Instant::now).elapsed()
+}
+
+#[cfg(target_family = "wasm")]
+fn clock() -> Duration {
+    Duration::from_secs_f64(crate::native::now_ms() / 1000.0)
+}
+
+#[derive(Debug)]
+struct Inner {
+    function: String,
+    user: Option<User>,
+    request_id: String,
+    traceparent: Option<String>,
+    deadline: Duration,
+    tags: Mutex<Vec<String>>,
+    touched: Mutex<Vec<String>>,
+}
+
+/// What every context has: the deadline, the ids and the two reports back to TS.
+#[derive(Debug, Clone)]
+pub struct Base(Arc<Inner>);
+
+impl Base {
+    pub(crate) fn new(function: &str, envelope: Envelope) -> Self {
+        Base(Arc::new(Inner {
+            function: function.to_string(),
+            user: envelope.user,
+            request_id: envelope.request_id,
+            traceparent: envelope.traceparent,
+            deadline: clock() + Duration::from_millis(envelope.deadline_ms),
+            tags: Mutex::default(),
+            touched: Mutex::default(),
+        }))
+    }
+
+    /// Report a table this call read (a query) or wrote (a mutation). `weft dev` checks it against the function's tags
+    /// (Q011), as it does for a TS `run`; it can't see into Rust any other way.
+    pub fn touch(&self, table: impl Into<String>) {
+        self.0.touched.lock().expect("touched").push(table.into());
+    }
+
+    /// Add a cache tag to this call's result, or, in a mutation, a tag to invalidate. Declared tags stay in TS: Rust can
+    /// add to them and never remove one.
+    pub fn tag(&self, tag: impl Into<String>) {
+        self.0.tags.lock().expect("tags").push(tag.into());
+    }
+
+    /// The function's id, as the contract spells it.
+    pub fn function(&self) -> &str {
+        &self.0.function
+    }
+
+    /// The id TS gave this request. Log it: the client sees it on an `Internal` failure.
+    pub fn request_id(&self) -> &str {
+        &self.0.request_id
+    }
+
+    pub fn traceparent(&self) -> Option<&str> {
+        self.0.traceparent.as_deref()
+    }
+
+    /// What's left of the deadline. weft stops waiting at zero; long CPU loops should check [`Base::cancelled`].
+    pub fn remaining(&self) -> Duration {
+        self.0.deadline.saturating_sub(clock())
+    }
+
+    /// The deadline passed, so no one is waiting for this answer.
+    pub fn cancelled(&self) -> bool {
+        self.remaining().is_zero()
+    }
+
+    pub(crate) fn tags(&self) -> Vec<String> {
+        self.0.tags.lock().expect("tags").clone()
+    }
+
+    pub(crate) fn touched(&self) -> Vec<String> {
+        self.0.touched.lock().expect("touched").clone()
+    }
+
+    pub(crate) fn user(&self) -> Option<&User> {
+        self.0.user.as_ref()
+    }
+}
+
+/// How the generated code turns the common [`Base`] into the context a function's declaration calls for. `None` means
+/// the claims don't fit, which only a wrong signer can cause.
+pub trait FromBase: Sized {
+    fn from_base(base: Base) -> Option<Self>;
+}
+
+/// A public function: `user()` is an `Option`.
+#[derive(Debug, Clone)]
+pub struct Ctx(Base);
+
+impl Ctx {
+    pub fn user(&self) -> Option<&User> {
+        self.0.user()
+    }
+}
+
+/// `auth: 'user'`: TS refused the call unless someone is signed in.
+#[derive(Debug, Clone)]
+pub struct UserCtx(Base);
+
+impl UserCtx {
+    pub fn user(&self) -> &User {
+        self.0.user().expect("from_base checked it")
+    }
+}
+
+/// `cache: { life }`: one value for every user, so no user. Take what the value depends on as input.
+#[derive(Debug, Clone)]
+pub struct SharedCtx(Base);
+
+macro_rules! context {
+    ($($name:ident: $check:expr),*) => {$(
+        impl Deref for $name {
+            type Target = Base;
+            fn deref(&self) -> &Base {
+                &self.0
+            }
+        }
+        impl FromBase for $name {
+            fn from_base(base: Base) -> Option<Self> {
+                let fits: fn(&Base) -> bool = $check;
+                fits(&base).then_some(Self(base))
+            }
+        }
+    )*};
+}
+
+context!(Ctx: |_| true, UserCtx: |b| b.user().is_some(), SharedCtx: |b| b.user().is_none());

package/crate/src/envelope.rs

@@ -0,0 +1,163 @@
+//! One crossing per server function (PLAN §4.3). The request is `POST /_weft/fn/:id` with the JSON body `{ "input": … }`:
+//!
+//! ```text
+//! weft-ctx: base64url(JSON of the Envelope)
+//! weft-sig: hex(HMAC-SHA256(secret, "weft1\n" + id + "\n" + weft-ctx + "\n" + body))
+//! ```
+//!
+//! The signature covers the function 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.
+
+use std::fmt::Write as _;
+
+use base64::Engine;
+use base64::engine::general_purpose::URL_SAFE_NO_PAD;
+use hmac::{Hmac, KeyInit, Mac};
+use sha2::Sha256;
+
+pub use crate::ctx::Envelope;
+
+/// How far `iat` may be from this machine's clock.
+pub const MAX_SKEW_MS: u64 = 60_000;
+
+/// Why a call was refused before any handler ran.
+#[derive(Debug, PartialEq, Eq)]
+pub enum Refused {
+    /// No `weft-ctx`/`weft-sig`, or they don't decode.
+    Malformed,
+    /// The signature doesn't match: a wrong secret, or a changed call.
+    BadSignature,
+    /// `iat` is too far from now.
+    Stale,
+}
+
+impl std::fmt::Display for Refused {
+    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        f.write_str(match self {
+            Refused::Malformed => "no readable weft-ctx and weft-sig headers",
+            Refused::BadSignature => {
+                "the signature doesn't match: is WEFT_RUST_SECRET the same on both sides?"
+            }
+            Refused::Stale => "the call was signed too long ago (or a clock is off)",
+        })
+    }
+}
+
+fn keyed(secret: &[u8], id: &str, ctx: &str, body: &[u8]) -> Hmac<Sha256> {
+    let mut mac = Hmac::<Sha256>::new_from_slice(secret).expect("HMAC takes a key of any length");
+    mac.update(b"weft1\n");
+    mac.update(id.as_bytes());
+    mac.update(b"\n");
+    mac.update(ctx.as_bytes());
+    mac.update(b"\n");
+    mac.update(body);
+    mac
+}
+
+fn hex_decode(s: &str) -> Option<Vec<u8>> {
+    if !s.len().is_multiple_of(2) {
+        return None;
+    }
+    (0..s.len())
+        .step_by(2)
+        .map(|i| u8::from_str_radix(s.get(i..i + 2)?, 16).ok())
+        .collect()
+}
+
+/// The `weft-sig` for a call. TS is the signer; this is here for tests and hand-written callers.
+pub fn sign(secret: &[u8], id: &str, ctx: &str, body: &[u8]) -> String {
+    let mut hex = String::with_capacity(64);
+    for b in keyed(secret, id, ctx, body).finalize().into_bytes() {
+        let _ = write!(hex, "{b:02x}");
+    }
+    hex
+}
+
+/// Check the signature (in constant time), then decode the envelope and check its age against `now_ms`.
+pub fn verify(
+    secret: &[u8],
+    id: &str,
+    ctx: &str,
+    sig: &str,
+    body: &[u8],
+    now_ms: u64,
+) -> Result<Envelope, Refused> {
+    let sig = hex_decode(sig).ok_or(Refused::Malformed)?;
+    keyed(secret, id, ctx, body)
+        .verify_slice(&sig)
+        .map_err(|_| Refused::BadSignature)?;
+    let json = URL_SAFE_NO_PAD
+        .decode(ctx)
+        .map_err(|_| Refused::Malformed)?;
+    let envelope: Envelope = serde_json::from_slice(&json).map_err(|_| Refused::Malformed)?;
+    if envelope.iat.abs_diff(now_ms) > MAX_SKEW_MS {
+        return Err(Refused::Stale);
+    }
+    Ok(envelope)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    const CTX: &str = "eyJ1c2VyIjp7ImlkIjoidTEiLCJyb2xlcyI6WyJhZG1pbiJdfSwicmVxdWVzdElkIjoicjEiLCJkZWFkbGluZU1zIjoxMDAwLCJ0cmFjZXBhcmVudCI6bnVsbCwiaWF0IjoxMDAwMDAwfQ";
+
+    #[test]
+    fn the_signature_covers_the_function_the_claims_and_the_body() {
+        let sig = sign(b"s3cret", "f.abc", CTX, b"{}");
+        let ok = verify(b"s3cret", "f.abc", CTX, &sig, b"{}", 1_000_000).unwrap();
+        assert_eq!(ok.user.unwrap().id, "u1");
+        assert_eq!(ok.deadline_ms, 1000);
+        assert_eq!(
+            verify(b"other", "f.abc", CTX, &sig, b"{}", 1_000_000).unwrap_err(),
+            Refused::BadSignature
+        );
+        assert_eq!(
+            verify(b"s3cret", "g.abc", CTX, &sig, b"{}", 1_000_000).unwrap_err(),
+            Refused::BadSignature
+        );
+        assert_eq!(
+            verify(b"s3cret", "f.abc", CTX, &sig, b"[]", 1_000_000).unwrap_err(),
+            Refused::BadSignature
+        );
+        assert_eq!(
+            verify(b"s3cret", "f.abc", "e30", &sig, b"{}", 1_000_000).unwrap_err(),
+            Refused::BadSignature
+        );
+    }
+
+    #[test]
+    fn an_old_call_is_refused_even_with_a_good_signature() {
+        let sig = sign(b"k", "f", CTX, b"{}");
+        assert!(verify(b"k", "f", CTX, &sig, b"{}", 1_000_000 + MAX_SKEW_MS).is_ok());
+        assert_eq!(
+            verify(b"k", "f", CTX, &sig, b"{}", 1_000_000 + MAX_SKEW_MS + 1).unwrap_err(),
+            Refused::Stale
+        );
+    }
+
+    #[test]
+    fn junk_headers_are_malformed_not_a_panic() {
+        assert_eq!(
+            verify(b"k", "f", CTX, "zz", b"{}", 0).unwrap_err(),
+            Refused::Malformed
+        );
+        assert_eq!(
+            verify(b"k", "f", CTX, "abc", b"{}", 0).unwrap_err(),
+            Refused::Malformed
+        );
+        assert_eq!(
+            verify(b"k", "f", CTX, "é", b"{}", 0).unwrap_err(),
+            Refused::Malformed
+        );
+    }
+
+    /// The same vector `packages/start/test/rust.test.mjs` signs in JS: the two sides agree byte for byte.
+    #[test]
+    fn matches_the_typescript_signer() {
+        assert_eq!(
+            sign(b"s3cret", "f.abc", CTX, b"{\"input\":{\"q\":\"x\"}}"),
+            "1a4c89d125bdeda4db5f2dd02045bc1044ff4ecfacff00c7f42f602ceef3ad08"
+        );
+    }
+}

package/crate/src/functions.rs

@@ -0,0 +1,173 @@
+//! A service's functions by contract id, and what a call comes to on any transport: `weft::router` puts them behind
+//! HTTP, `weft::native!` behind Node-API or a WASM export. The body of a reply is the same on all of them:
+//!
+//! ```text
+//! { "ok": true, "value": …, "tags": […], "touched": […] }
+//! { "ok": false, "error": { "code": "NotFound", "data": … } }
+//! ```
+
+use std::collections::HashMap;
+use std::future::Future;
+use std::pin::Pin;
+use std::sync::Arc;
+
+use serde::Serialize;
+use serde::de::DeserializeOwned;
+use serde_json::{Value, json};
+
+use crate::ctx::{Base, FromBase};
+
+pub(crate) type Boxed = Pin<Box<dyn Future<Output = Answer> + Send>>;
+pub(crate) type Handler = Arc<dyn Fn(Base, Vec<u8>) -> Boxed + Send + Sync>;
+
+/// How a call ended, before the reports are added.
+pub(crate) enum Answer {
+    /// The value, already JSON: nothing reads it on this side.
+    Value(String),
+    Failed(Failed),
+    /// serde refused what TS sent: the two sides were built from different contracts.
+    Drift(String),
+}
+
+/// What a function's error becomes on the wire.
+pub enum Failed {
+    /// A declared error: `{ "code": …, "data": … }`, which TS checks against the declaration.
+    Typed(Value),
+    /// Anything else. The detail stays in this log: the client gets a request id.
+    Internal(String),
+}
+
+/// An error type a function can return. Generated for each function that declares `errors`.
+pub trait Failure {
+    fn failed(self) -> Failed;
+}
+
+/// The error of a function that declares none. Any `std::error::Error` converts into it, so `?` works.
+#[derive(Debug)]
+pub struct Error(pub String);
+
+impl Error {
+    pub fn msg(message: impl Into<String>) -> Self {
+        Error(message.into())
+    }
+}
+
+impl<E: std::error::Error> From<E> for Error {
+    fn from(e: E) -> Self {
+        Error(e.to_string())
+    }
+}
+
+impl Failure for Error {
+    fn failed(self) -> Failed {
+        Failed::Internal(self.0)
+    }
+}
+
+/// A service's functions, by contract id. `contract::functions(service)` builds it; [`crate::router`] serves it.
+pub struct Functions {
+    service: &'static str,
+    hash: &'static str,
+    table: HashMap<&'static str, Handler>,
+}
+
+impl Functions {
+    pub fn new(service: &'static str, hash: &'static str) -> Self {
+        Functions {
+            service,
+            hash,
+            table: HashMap::new(),
+        }
+    }
+
+    /// One function. Called by generated code.
+    #[must_use]
+    pub fn add<C, I, O, E, F, Fut>(mut self, id: &'static str, f: F) -> Self
+    where
+        C: FromBase + Send + 'static,
+        I: DeserializeOwned + Send + 'static,
+        O: Serialize,
+        E: Failure,
+        F: Fn(C, I) -> Fut + Send + Sync + 'static,
+        Fut: Future<Output = Result<O, E>> + Send + 'static,
+    {
+        #[derive(serde::Deserialize)]
+        struct Body<I> {
+            input: I,
+        }
+        let f = Arc::new(f);
+        let handler: Handler = Arc::new(move |base, body| {
+            let f = f.clone();
+            Box::pin(async move {
+                let input = match serde_json::from_slice::<Body<I>>(&body) {
+                    Ok(b) => b.input,
+                    Err(e) => return Answer::Drift(e.to_string()),
+                };
+                drop(body);
+                let Some(ctx) = C::from_base(base) else {
+                    return Answer::Drift(
+                        "the claims don't fit this function's declaration".into(),
+                    );
+                };
+                match f(ctx, input).await {
+                    Ok(v) => match serde_json::to_string(&v) {
+                        Ok(v) => Answer::Value(v),
+                        Err(e) => Answer::Failed(Failed::Internal(format!(
+                            "the result didn't serialize: {e}"
+                        ))),
+                    },
+                    Err(e) => Answer::Failed(e.failed()),
+                }
+            })
+        });
+        self.table.insert(id, handler);
+        self
+    }
+
+    pub(crate) fn service(&self) -> &'static str {
+        self.service
+    }
+
+    pub(crate) fn hash(&self) -> &'static str {
+        self.hash
+    }
+
+    pub(crate) fn ids(&self) -> Vec<&'static str> {
+        let mut ids: Vec<_> = self.table.keys().copied().collect();
+        ids.sort_unstable();
+        ids
+    }
+
+    pub(crate) fn handler(&self, id: &str) -> Option<Handler> {
+        self.table.get(id).cloned()
+    }
+}
+
+pub(crate) fn ok_body(value: &str, base: &Base) -> String {
+    let list = |l: Vec<String>| serde_json::to_string(&l).expect("strings serialize");
+    format!(
+        r#"{{"ok":true,"value":{value},"tags":{},"touched":{}}}"#,
+        list(base.tags()),
+        list(base.touched())
+    )
+}
+
+/// `detail` crosses only inside this process: TS logs it, and a client never sees it.
+pub(crate) fn internal_body(base: &Base, detail: Option<&str>) -> Value {
+    let mut error = json!({ "code": "Internal", "requestId": base.request_id() });
+    if let Some(d) = detail {
+        error["detail"] = json!(d);
+    }
+    json!({ "ok": false, "error": error })
+}
+
+pub(crate) fn drift_body(detail: &str) -> Value {
+    json!({ "ok": false, "error": { "code": "Drift", "message": detail } })
+}
+
+pub(crate) fn panic_text(p: &(dyn std::any::Any + Send)) -> String {
+    p.downcast_ref::<&str>()
+        .map(std::string::ToString::to_string)
+        .or_else(|| p.downcast_ref::<String>().cloned())
+        .unwrap_or_else(|| "no message".into())
+}

package/crate/src/lib.rs

@@ -0,0 +1,118 @@
+//! The Rust side of weft's `remote()` and `native()` (PLAN §4.3, research 36 and 39). A sidecar or an addon implements
+//! server functions declared in TypeScript: Zod stays the source of truth, `.weft/contract.json` carries it, and `weft::build::generate` turns it into
+//! serde types, a typed error enum per function and one `Service` trait, so a change on the TS side stops `cargo` exactly
+//! where the Rust no longer matches.
+//!
+//! ```ignore
+//! // build.rs: fn main() { weft::build::generate("search") }
+//! 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
+//! }
+//! ```
+//!
+//! An addon is the same `impl Service` in a `cdylib`, with one line in place of `main`:
+//!
+//! ```ignore
+//! weft::native!(contract::functions(Media));
+//! ```
+//!
+//! TS 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.
+
+#[cfg(feature = "build")]
+pub mod build;
+
+#[cfg(feature = "core")]
+#[cfg_attr(
+    not(any(feature = "server", feature = "native")),
+    allow(
+        dead_code,
+        reason = "`core` alone is what generated code names; the rest is for `server` and `native`"
+    )
+)]
+mod ctx;
+#[cfg(feature = "server")]
+mod envelope;
+#[cfg(feature = "core")]
+#[cfg_attr(
+    not(any(feature = "server", feature = "native")),
+    allow(
+        dead_code,
+        reason = "`core` alone is what generated code names; the rest is for `server` and `native`"
+    )
+)]
+mod functions;
+#[cfg(feature = "native")]
+#[doc(hidden)]
+#[cfg_attr(
+    test,
+    allow(dead_code, reason = "Node-API registers exports outside test builds")
+)]
+pub mod native;
+#[cfg(feature = "otel")]
+mod otel;
+#[cfg(feature = "server")]
+mod server;
+
+#[cfg(feature = "core")]
+pub use ctx::{Base, Ctx, Envelope, FromBase, SharedCtx, User, UserCtx};
+#[cfg(feature = "server")]
+pub use envelope::{Refused, sign, verify};
+#[cfg(feature = "core")]
+pub use functions::{Error, Failed, Failure, Functions};
+#[cfg(feature = "server")]
+pub use server::{router, router_with, serve};
+
+/// The generated contract, as `pub mod contract`: the types, the `Service` trait and `functions()`.
+#[macro_export]
+macro_rules! contract {
+    () => {
+        #[allow(dead_code, unused, clippy::all)]
+        pub mod contract {
+            include!(concat!(env!("OUT_DIR"), "/weft_contract.rs"));
+        }
+    };
+}
+
+/// This crate's functions as a Node-API addon, or a `.wasm` on that target: a `native()` crate's one line of glue.
+#[cfg(feature = "native")]
+#[macro_export]
+macro_rules! native {
+    ($functions:expr) => {
+        #[cfg(not(target_family = "wasm"))]
+        ::weft::__rt::napi::ctor::declarative::ctor! {
+            #[ctor(unsafe)]
+            fn __weft_native() {
+                ::weft::native::install(|| $functions)
+            }
+        }
+        #[cfg(target_family = "wasm")]
+        #[unsafe(no_mangle)]
+        pub extern "C" fn weft_init() {
+            ::weft::native::install(|| $functions)
+        }
+    };
+}
+
+/// What generated code names, so an app doesn't have to depend on what its schemas happen to use.
+#[cfg(feature = "core")]
+#[doc(hidden)]
+pub mod __rt {
+    pub use chrono;
+    #[cfg(all(feature = "native", not(target_family = "wasm")))]
+    pub use napi;
+    pub use regress;
+    pub use uuid;
+}