@weft-js/start 0.1.1 → 0.1.3

package/crate/src/build.rs

@@ -0,0 +1,367 @@
+//! `weft::build::generate("search")` in a sidecar's or an addon's `build.rs`: `.weft/contract.json` → serde types (typify), a typed
+//! error enum per function, the `Service` trait and `functions()`. Rust never defines a schema (PLAN §4.3). A contract
+//! that changes reruns this, and cargo then stops exactly where the implementation no longer fits, which `weft dev`,
+//! `weft build` and `weft check` report as R103 with the function's id.
+
+mod emit;
+
+use std::collections::BTreeMap;
+use std::env;
+use std::fs;
+use std::path::{Path, PathBuf};
+
+use schemars::schema::{RootSchema, Schema};
+use serde_json::{Map, Value, json};
+use typify::{TypeSpace, TypeSpaceSettings};
+
+/// Generate the contract for `service` into `OUT_DIR/weft_contract.rs`, and a copy to read at `.weft/rust/<service>.rs`.
+///
+/// # Panics
+/// When there's no contract or `service` has no functions. A build script reports failure by panicking; the message is
+/// R103 with the fix.
+pub fn generate(service: &str) {
+    println!("cargo:rerun-if-env-changed=WEFT_CONTRACT");
+    let path = contract_path().unwrap_or_else(|| panic!("R103: no .weft/contract.json above this crate. Run `weft dev` or `weft check` in the app, or set WEFT_CONTRACT"));
+    println!("cargo:rerun-if-changed={}", path.display());
+    let text = fs::read_to_string(&path)
+        .unwrap_or_else(|e| panic!("R103: can't read {}: {e}", path.display()));
+    let contract: Value = serde_json::from_str(&text)
+        .unwrap_or_else(|e| panic!("R103: {} isn't JSON: {e}", path.display()));
+    let code = render(&contract, service).unwrap_or_else(|e| panic!("R103: {e}"));
+    // An addon's undefined `napi_*` symbols are the host's, which macOS's linker has to be told.
+    if contract["services"][service]["kind"] == "native"
+        && env::var("CARGO_CFG_TARGET_FAMILY").is_ok_and(|f| !f.contains("wasm"))
+    {
+        napi_build::setup();
+    }
+    let out =
+        PathBuf::from(env::var("OUT_DIR").expect("cargo sets OUT_DIR")).join("weft_contract.rs");
+    fs::write(&out, &code).expect("OUT_DIR is writable");
+    if let Some(dir) = path.parent().map(|p| p.join("rust")) {
+        let _ = fs::create_dir_all(&dir);
+        let _ = fs::write(dir.join(format!("{service}.rs")), &code); // to read: a build doesn't depend on it
+    }
+}
+
+/// `WEFT_CONTRACT`, or the nearest `.weft/contract.json` above the crate.
+fn contract_path() -> Option<PathBuf> {
+    if let Ok(p) = env::var("WEFT_CONTRACT") {
+        return Some(PathBuf::from(p));
+    }
+    let dir = PathBuf::from(env::var("CARGO_MANIFEST_DIR").ok()?);
+    dir.ancestors()
+        .map(|d: &Path| d.join(".weft/contract.json"))
+        .find(|p| p.exists())
+}
+
+/// `searchDocs` → `search_docs`, kept clear of what a method can't be called.
+fn snake(name: &str) -> String {
+    let mut out = String::new();
+    for (i, c) in name.chars().enumerate() {
+        if c.is_ascii_uppercase() {
+            if i > 0 {
+                out.push('_');
+            }
+            out.push(c.to_ascii_lowercase());
+        } else if c.is_alphanumeric() || c == '_' {
+            out.push(c);
+        }
+    }
+    if syn::parse_str::<syn::Ident>(&out).is_err() {
+        format!("{out}_")
+    } else {
+        out
+    }
+}
+
+/// `searchDocs` → `SearchDocs`.
+fn pascal(name: &str) -> String {
+    let clean: String = name
+        .chars()
+        .filter(|c| c.is_alphanumeric() || *c == '_')
+        .collect();
+    let mut chars = clean.chars();
+    chars
+        .next()
+        .map_or(String::new(), |c| c.to_uppercase().chain(chars).collect())
+}
+
+/// typify reads schemars 0.8 schemas, which spell a tuple `items: […]`. Zod's `$defs` are collected by the caller.
+fn normal(v: &Value, defs: &mut BTreeMap<String, Value>) -> Value {
+    match v {
+        Value::Object(m) => {
+            let mut out = Map::new();
+            for (k, x) in m {
+                match k.as_str() {
+                    "$schema" => {}
+                    "$defs" | "definitions" => {
+                        for (name, def) in x.as_object().into_iter().flatten() {
+                            let def = normal(def, defs);
+                            defs.insert(name.clone(), def);
+                        }
+                    }
+                    "prefixItems" => {
+                        out.insert("items".into(), normal(x, defs));
+                    }
+                    "$ref" => {
+                        out.insert(
+                            k.clone(),
+                            json!(
+                                x.as_str()
+                                    .unwrap_or("")
+                                    .replace("#/$defs/", "#/definitions/")
+                            ),
+                        );
+                    }
+                    _ => {
+                        out.insert(k.clone(), normal(x, defs));
+                    }
+                }
+            }
+            Value::Object(out)
+        }
+        Value::Array(a) => Value::Array(a.iter().map(|x| normal(x, defs)).collect()),
+        x => x.clone(),
+    }
+}
+
+struct Spec<'a> {
+    id: &'a str,
+    method: String,
+    type_name: String,
+    ctx: &'static str,
+    input: Option<Value>,
+    output: Value,
+    errors: Vec<(String, Value)>,
+}
+
+fn specs<'a>(functions: &[&'a Value], defs: &mut BTreeMap<String, Value>) -> Vec<Spec<'a>> {
+    let mut seen = BTreeMap::<String, usize>::new();
+    for f in functions {
+        *seen
+            .entry(f["name"].as_str().unwrap_or("").to_string())
+            .or_default() += 1;
+    }
+    functions
+        .iter()
+        .map(|f| {
+            let id = f["id"].as_str().unwrap_or("");
+            let name = f["name"].as_str().unwrap_or(id);
+            // Two files can export one name: the id's hash keeps them apart.
+            let unique = if seen[name] > 1 {
+                id.replace('.', "_")
+            } else {
+                name.to_string()
+            };
+            let imp = &f["impl"];
+            Spec {
+                id,
+                method: snake(&unique),
+                type_name: pascal(&unique),
+                ctx: match imp["ctx"].as_str() {
+                    Some("shared") => "SharedCtx",
+                    Some("user") => "UserCtx",
+                    _ => "Ctx",
+                },
+                input: (!f["input"].is_null()).then(|| normal(&f["input"], defs)),
+                output: normal(&imp["output"], defs),
+                errors: imp["errors"]
+                    .as_object()
+                    .into_iter()
+                    .flatten()
+                    .map(|(k, v)| (k.clone(), normal(v, defs)))
+                    .collect(),
+            }
+        })
+        .collect()
+}
+
+fn add(space: &mut TypeSpace, schema: &Value, name: &str) -> Result<String, String> {
+    let root: RootSchema = serde_json::from_value(schema.clone())
+        .map_err(|e| format!("`{name}` isn't a schema typify reads: {e}"))?;
+    let id = space
+        .add_type_with_name(&Schema::Object(root.schema), Some(name.to_string()))
+        .map_err(|e| format!("`{name}`: {e}"))?;
+    Ok(space
+        .get_type(&id)
+        .map_err(|e| e.to_string())?
+        .ident()
+        .to_string())
+}
+
+/// `pub type X = …` unless typify already named the type `X`.
+fn alias(name: &str, ident: &str) -> String {
+    if ident.replace(' ', "") == name {
+        String::new()
+    } else {
+        format!("pub type {name} = {ident};\n")
+    }
+}
+
+/// The Rust for `service`'s functions.
+pub(crate) fn render(contract: &Value, service: &str) -> Result<String, String> {
+    let all = contract["functions"]
+        .as_array()
+        .ok_or("the contract has no `functions`")?;
+    let functions: Vec<&Value> = all
+        .iter()
+        .filter(|f| f["impl"]["service"] == service)
+        .collect();
+    if functions.is_empty() {
+        return Err(format!(
+            "no function in the contract has `impl: remote('rust://{service}')` or `impl: native('{service}')`. Point one at it, or rename the service in build.rs"
+        ));
+    }
+    let hash = contract["services"][service]["hash"].as_str().unwrap_or("");
+
+    let mut defs = BTreeMap::new();
+    let specs = specs(&functions, &mut defs);
+    let mut settings = TypeSpaceSettings::default();
+    settings.with_struct_builder(false);
+    let mut space = TypeSpace::new(&settings);
+    let mut extra = String::new();
+    let mut body = String::new();
+
+    let refs = defs
+        .into_iter()
+        .map(|(k, v)| {
+            serde_json::from_value::<Schema>(v)
+                .map(|s| (k.clone(), s))
+                .map_err(|e| format!("`$defs/{k}`: {e}"))
+        })
+        .collect::<Result<Vec<_>, _>>()?;
+    space
+        .add_ref_types(refs)
+        .map_err(|e| format!("named schemas: {e}"))?;
+
+    let mut methods = String::new();
+    let mut table = String::new();
+    for s in &specs {
+        emit::function(
+            s,
+            &mut space,
+            &mut extra,
+            &mut body,
+            &mut methods,
+            &mut table,
+        )?;
+    }
+
+    let text = format!(
+        r"{types}
+{extra}
+{body}
+/// The contract's hash: `GET /_weft/health` reports it, and neither side runs a binary built from another one.
+pub const CONTRACT_HASH: &str = {hash:?};
+
+/// Every function `{service}` implements. Written by `weft::build`: edit the TypeScript, not this.
+pub trait Service: Send + Sync + 'static {{
+    {methods}
+}}
+
+/// What `weft::router` serves, or `weft::native!` exports.
+pub fn functions<S: Service>(service: S) -> ::weft::Functions {{
+    let service = ::std::sync::Arc::new(service);
+    ::weft::Functions::new({service:?}, CONTRACT_HASH)
+    {table}
+}}
+",
+        types = space.to_stream(),
+    );
+    let file = syn::parse_file(&text).map_err(|e| format!("generated code didn't parse: {e}"))?;
+    let pretty = prettyplease::unparse(&file);
+    Ok(pretty
+        .replace("::chrono::", "::weft::__rt::chrono::")
+        .replace("::uuid::", "::weft::__rt::uuid::")
+        .replace("::regress::", "::weft::__rt::regress::"))
+}
+
+#[cfg(test)]
+#[allow(
+    clippy::needless_pass_by_value,
+    reason = "fixtures take `json!` literals"
+)]
+mod tests {
+    use super::*;
+
+    fn contract(functions: Value) -> Value {
+        json!({ "functions": functions, "services": { "search": { "hash": "h1" } } })
+    }
+
+    fn function(name: &str, input: Value, output: Value, ctx: &str, errors: Value) -> Value {
+        json!({ "id": format!("{name}.abc123"), "name": name, "input": input, "impl": { "service": "search", "ctx": ctx, "output": output, "errors": errors } })
+    }
+
+    #[test]
+    fn names_follow_the_function() {
+        assert_eq!(snake("searchDocs"), "search_docs");
+        assert_eq!(snake("match"), "match_");
+        assert_eq!(pascal("searchDocs"), "SearchDocs");
+    }
+
+    #[test]
+    fn one_method_a_function_with_its_context_and_errors() {
+        let code = render(
+            &contract(json!([
+                function("searchDocs", json!({ "type": "object", "properties": { "q": { "type": "string" } }, "required": ["q"] }), json!({ "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"] } }), "shared", json!({})),
+                function("saveDoc", Value::Null, json!({ "type": "null" }), "user", json!({ "NotFound": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"] } })),
+                function("other", Value::Null, json!({ "type": "string" }), "ctx", json!({})),
+            ])),
+            "search",
+        )
+        .unwrap();
+        assert!(code.contains("fn search_docs("), "{code}");
+        assert!(code.contains("ctx: ::weft::SharedCtx"));
+        assert!(code.contains("input: SearchDocsInput"));
+        assert!(code.contains("pub type SearchDocsOutput ="));
+        assert!(code.contains("ctx: ::weft::UserCtx"));
+        assert!(!code.contains("SaveDocInput"), "no input, no parameter");
+        assert!(code.contains("pub enum SaveDocError"));
+        assert!(code.contains("NotFound(SaveDocNotFound)"));
+        assert!(code.contains("\"h1\""));
+    }
+
+    #[test]
+    fn a_service_with_no_functions_says_how_to_fix_it() {
+        let e = render(&contract(json!([])), "search").unwrap_err();
+        assert!(e.contains("rust://search"), "{e}");
+    }
+
+    #[test]
+    fn a_tuple_and_a_named_schema_from_zod() {
+        let output = json!({ "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "array", "items": { "$ref": "#/$defs/Hit" }, "$defs": { "Hit": { "type": "object", "properties": { "id": { "type": "string" } }, "required": ["id"] } } });
+        let tuple = json!({ "type": "array", "prefixItems": [{ "type": "string" }, { "type": "number" }], "minItems": 2, "maxItems": 2 });
+        let code = render(
+            &contract(json!([function("hits", tuple, output, "ctx", json!({}))])),
+            "search",
+        )
+        .unwrap();
+        assert!(code.contains("pub struct Hit"), "{code}");
+        assert!(
+            code.contains("pub type HitsOutput = ::std::vec::Vec<Hit>"),
+            "{code}"
+        );
+        assert!(
+            code.contains("pub type HitsInput = (::std::string::String, f64)"),
+            "{code}"
+        );
+    }
+
+    #[test]
+    fn dates_and_uuids_need_no_dependency_of_the_app() {
+        let input = json!({ "type": "object", "properties": { "at": { "type": "string", "format": "date-time" }, "id": { "type": "string", "format": "uuid" } }, "required": ["at", "id"] });
+        let code = render(
+            &contract(json!([function(
+                "f",
+                input,
+                json!({ "type": "null" }),
+                "ctx",
+                json!({})
+            )])),
+            "search",
+        )
+        .unwrap();
+        assert!(code.contains("::weft::__rt::chrono::"), "{code}");
+        assert!(code.contains("::weft::__rt::uuid::"), "{code}");
+    }
+}

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());