convex-rust 0.0.0-stage → 0.1.0

package/rust/convex_fn/src/intl.rs

@@ -0,0 +1,75 @@
+//! Time zones and locale formatting through the host's `Intl` (`intl/*` sync ops, see
+//! contracts/ABI.md "Optional sync ops: intl/*").
+//!
+//! A wasm32 guest has no time zone database: `chrono::Local` and `std` know only UTC. Asking for a
+//! zone here never falls back to UTC; an unknown zone, or a host without these ops, is an error.
+//! (To stay self-contained instead, `jiff` with its bundled tzdb or `chrono-tz` work on wasm32 too, at
+//! roughly 0.4-0.5 MB of wasm per call, which the cloud pays at every cold call.)
+
+use serde_json::{json, Value};
+
+use crate::{Error, Result};
+
+fn call(op: &str, args: Value) -> Result<Value> {
+    let out = crate::sys::sync(op, args.to_string().as_bytes());
+    let v: Value = serde_json::from_slice(&out)?;
+    match v.get("error") {
+        Some(err) => {
+            let e = Error::from_json(err);
+            let msg = e.message().to_string();
+            if msg.contains("unknown sync op") {
+                Err(Error::msg(format!(
+                    "host lacks {op}: update convex-rust to >= {MIN_CONVEX_RUST} (V8 host); the wasmtime host has no intl ops, use jiff or chrono-tz with a bundled tzdb"
+                )))
+            } else {
+                Err(e)
+            }
+        }
+        None => Ok(v.get("ok").cloned().unwrap_or(Value::Null)),
+    }
+}
+
+/// First `convex-rust` release that serves the `intl/*` ops on V8 hosts.
+pub const MIN_CONVEX_RUST: &str = "0.2.0";
+
+/// Offset of the IANA zone `tz` from UTC at `epoch_ms`, in seconds (positive east of UTC), DST included.
+/// Errors on an unknown zone; never returns 0 as a stand-in.
+pub fn tz_offset_secs(tz: &str, epoch_ms: f64) -> Result<i32> {
+    let v = call("intl/tzOffset", json!({ "tz": tz, "epochMs": epoch_ms }))?;
+    v.as_i64()
+        .map(|n| n as i32)
+        .ok_or_else(|| Error::msg(format!("intl/tzOffset: unexpected reply {v}")))
+}
+
+/// Converts a wall-clock time in `tz` (milliseconds since the epoch as if the wall clock were UTC) to the real
+/// epoch milliseconds. In a DST gap or overlap (a wall-clock time that does not exist, or exists twice) the
+/// result is one of the two candidate instants.
+pub fn local_to_epoch_ms(tz: &str, local_ms: f64) -> Result<f64> {
+    let first = tz_offset_secs(tz, local_ms)? as f64 * 1000.0;
+    let guess = local_ms - first;
+    let second = tz_offset_secs(tz, guess)? as f64 * 1000.0;
+    Ok(if second == first { guess } else { local_ms - second })
+}
+
+/// `new Intl.DateTimeFormat(locale, options).format(epoch_ms)`. `options` is the Intl options object, for example
+/// `{"timeZone": "Europe/Lisbon", "dateStyle": "full", "timeStyle": "short"}`. An unknown `timeZone` or locale
+/// is an error.
+pub fn format_date(epoch_ms: f64, locale: &str, options: Value) -> Result<String> {
+    format("date", json!(epoch_ms), locale, options)
+}
+
+/// `new Intl.NumberFormat(locale, options).format(value)`, for example options
+/// `{"style": "currency", "currency": "EUR"}`.
+pub fn format_number(value: f64, locale: &str, options: Value) -> Result<String> {
+    format("number", json!(value), locale, options)
+}
+
+fn format(kind: &str, value: Value, locale: &str, options: Value) -> Result<String> {
+    let v = call(
+        "intl/format",
+        json!({ "kind": kind, "value": value, "locale": locale, "options": options }),
+    )?;
+    v.as_str()
+        .map(str::to_string)
+        .ok_or_else(|| Error::msg(format!("intl/format: unexpected reply {v}")))
+}

package/rust/convex_fn/src/lib.rs

@@ -0,0 +1,242 @@
+//! Write Convex actions in Rust (`"use rust"`).
+//!
+//! ```ignore
+//! use convex_fn::{action, Ctx, Result};
+//!
+//! #[action]
+//! async fn hello(ctx: &Ctx, args: serde_json::Value) -> Result<String> {
+//!     let msgs = ctx.run_query("messages:list", serde_json::json!({})).await?;
+//!     Ok(format!("{} messages", msgs.as_array().map_or(0, Vec::len)))
+//! }
+//! ```
+//!
+//! # Logging, clock, random, env
+//!
+//! - `println!` goes to WASI stdout and `eprintln!` to stderr; the host turns
+//!   each line into a function log line (stdout at log/info level, stderr at
+//!   error level). No setup needed.
+//! - Feature `log`: a `log::Log` implementation is installed by the `#[action]`
+//!   entry unless a logger is already set (`error`->3, `warn`->2, `info`->1,
+//!   `debug`/`trace`->0). Messages are written as-is (no target prefix).
+//! - Feature `tracing`: a minimal subscriber is installed the same way; events
+//!   are written as `span{fields}: message key=value`, at the mapped level.
+//! - `std::env::var`, `SystemTime::now`, `Instant` and `getrandom` (0.2 and 0.3,
+//!   hence `rand`) work through WASI.
+//! - With `tokio-rt`, blocking calls (`block_on`, `reqwest::blocking`) made
+//!   inside an action drive the host task directly; tokio tasks spawned on the
+//!   `LocalSet` do not progress until the blocking call returns.
+//!
+//! Host interface: `contracts/ABI.md`. Function metadata: `contracts/MANIFEST.md`.
+
+mod args;
+pub mod crypto;
+mod ctx;
+pub mod dns;
+mod error;
+mod executor;
+mod fanout;
+pub mod fs;
+pub mod intl;
+mod function_ref;
+mod http;
+mod logging;
+#[cfg(convex_native)]
+pub mod native;
+mod net;
+mod sys;
+pub mod values;
+#[doc(hidden)]
+pub mod wire;
+
+pub use args::{ConvexType, Field, Validator};
+pub use convex_fn_macros::{action, http_action, ConvexArgs, ConvexValue};
+pub use ctx::{
+    ChunkSource, Chunks, Ctx, FetchRequest, FetchResponse, FetchStream, Redirect, Scheduler,
+    Storage, StorageFile, StorageMetadata, VectorFilter, VectorHit, VectorSearchQuery,
+};
+pub use error::{ConvexError, Error, Result};
+pub use executor::{block_on, join_all, race, select, Either};
+pub use fanout::par_map;
+pub use function_ref::{
+    ComponentFunctionRef, FunctionAddress, FunctionHandle, FunctionRef, FunctionTarget,
+};
+pub use http::{BodyWriter, HttpRequest, HttpResponse};
+pub use serde;
+pub use serde_json::{json, Value};
+pub use values::{Bytes, Float64, Int64};
+
+/// Wire format shared with `convex_fn_test`; not public API.
+#[doc(hidden)]
+pub use wire as __wire;
+
+/// Write one line to the function log at the given level.
+pub mod log {
+    use crate::wire::LogLevel;
+
+    pub fn debug(msg: &str) {
+        crate::sys::log_line(LogLevel::Debug, msg)
+    }
+    pub fn info(msg: &str) {
+        crate::sys::log_line(LogLevel::Info, msg)
+    }
+    pub fn warn(msg: &str) {
+        crate::sys::log_line(LogLevel::Warn, msg)
+    }
+    pub fn error(msg: &str) {
+        crate::sys::log_line(LogLevel::Error, msg)
+    }
+}
+
+/// Hooks for running actions natively (used by `convex_fn_test`).
+#[cfg(all(not(target_arch = "wasm32"), not(convex_native)))]
+pub mod testing {
+    /// A host implementing contracts/ABI.md in-process. Byte payloads are the
+    /// same JSON the wasm host exchanges.
+    pub trait Host {
+        fn task_submit(&mut self, request: &[u8]) -> i64;
+        /// `None` means "nothing ready" (`block = false`) or "no outstanding
+        /// tasks" (`block = true`).
+        fn task_poll(&mut self, block: bool) -> Option<Vec<u8>>;
+        fn sync_syscall(&mut self, op: &str, args: &[u8]) -> Vec<u8>;
+        fn log(&mut self, level: i32, msg: &str);
+    }
+
+    /// Install `host` for the current thread, returning the previous one.
+    pub fn install_host(host: Box<dyn Host>) -> Option<Box<dyn Host>> {
+        crate::executor::reset();
+        crate::sys::install(host)
+    }
+
+    /// Remove and return the current thread's host.
+    pub fn uninstall_host() -> Option<Box<dyn Host>> {
+        crate::sys::uninstall()
+    }
+}
+
+/// Optional wasm export: frees the result buffer of a `convex_run:*` call once the host has read it
+/// (contracts/V8HOST.md). `ptr`/`len` are the two halves of the packed value the call returned; that
+/// buffer is an exactly sized boxed slice (see `run_export`). Hosts that do not know it just leak the buffer.
+#[cfg(target_arch = "wasm32")]
+#[no_mangle]
+pub extern "C" fn convex_free(ptr: *mut u8, len: usize) {
+    if len == 0 || ptr.is_null() {
+        return;
+    }
+    // SAFETY: `run_export` returned `Box<[u8]>::into_raw` parts (ptr, len); the host frees them once.
+    unsafe { drop(Box::from_raw(std::ptr::slice_from_raw_parts_mut(ptr, len))) };
+}
+
+#[doc(hidden)]
+pub mod __rt {
+    use std::future::Future;
+
+    use serde::{de::DeserializeOwned, Serialize};
+
+    use crate::{error::Error, Ctx};
+
+    /// A fresh `Ctx` for native test hosts (`convex_fn_test`).
+    #[cfg(all(not(target_arch = "wasm32"), not(convex_native)))]
+    pub fn test_ctx() -> Ctx {
+        Ctx::new()
+    }
+
+    pub use crate::http::adapter as http_adapter;
+
+    pub use crate::args::{manifest_bytes, manifest_len, manifest_string, NoValidator, Probe};
+
+    /// Stand-in return type with no validator.
+    pub struct NoReturnType;
+
+    pub const fn const_bytes<const N: usize>(s: &str) -> [u8; N] {
+        let b = s.as_bytes();
+        let mut out = [0u8; N];
+        let mut i = 0;
+        while i < N {
+            out[i] = b[i];
+            i += 1;
+        }
+        out
+    }
+
+    /// Installs the `log` / `tracing` bridges (features `log`, `tracing`) unless
+    /// the user already installed their own. No-op without those features.
+    pub fn install_logging() {
+        crate::logging::install();
+    }
+
+    /// Body of every `convex_run:*` export.
+    #[cfg(target_arch = "wasm32")]
+    pub fn run_export<A, R, F, Fut>(args_ptr: *mut u8, args_len: usize, f: F) -> i64
+    where
+        A: DeserializeOwned,
+        R: Serialize,
+        F: FnOnce(Ctx, A) -> Fut,
+        Fut: Future<Output = crate::Result<R>>,
+    {
+        crate::error::install_panic_hook();
+        // A reused instance must not see the previous call's tasks/streams (the host restarts ids at 0).
+        crate::executor::reset_state();
+        // SAFETY: the host wrote `args_len` bytes into a buffer from `convex_alloc`.
+        let args = unsafe { Vec::from_raw_parts(args_ptr, args_len, args_len.max(1)) };
+        let envelope = run_to_envelope(&args, f);
+        let out = std::mem::ManuallyDrop::new(envelope.into_bytes().into_boxed_slice());
+        ((out.as_ptr() as u64) << 32 | out.len() as u64) as i64
+    }
+
+    /// Body of every `convex_run:*` export in native (`--cfg convex_native`) builds.
+    #[cfg(convex_native)]
+    pub fn run_export<A, R, F, Fut>(args_ptr: *mut u8, args_len: usize, f: F) -> i64
+    where
+        A: DeserializeOwned,
+        R: Serialize,
+        F: FnOnce(Ctx, A) -> Fut,
+        Fut: Future<Output = crate::Result<R>>,
+    {
+        crate::native::run_export_native(args_ptr, args_len, f)
+    }
+
+    /// Plain native builds (`cargo test`) never call the exports.
+    #[cfg(all(not(target_arch = "wasm32"), not(convex_native)))]
+    pub fn run_export<A, R, F, Fut>(_args_ptr: *mut u8, _args_len: usize, _f: F) -> i64
+    where
+        A: DeserializeOwned,
+        R: Serialize,
+        F: FnOnce(Ctx, A) -> Fut,
+        Fut: Future<Output = crate::Result<R>>,
+    {
+        unreachable!("convex_run exports are only callable on wasm32 or with --cfg convex_native")
+    }
+
+    /// Body of every `#[http_action]` `convex_run:*` export: the call's args are the request head.
+    pub fn run_http_export<F, Fut>(args_ptr: *mut u8, args_len: usize, f: F) -> i64
+    where
+        F: FnOnce(Ctx, crate::HttpRequest) -> Fut + 'static,
+        Fut: Future<Output = crate::Result<crate::HttpResponse>> + 'static,
+    {
+        run_export(args_ptr, args_len, crate::http::adapter(f))
+    }
+
+    /// Runs an action on raw Convex-JSON args and returns the result envelope
+    /// (contracts/ABI.md "Result envelope").
+    pub fn run_to_envelope<A, R, F, Fut>(args: &[u8], f: F) -> String
+    where
+        A: DeserializeOwned,
+        R: Serialize,
+        F: FnOnce(Ctx, A) -> Fut,
+        Fut: Future<Output = crate::Result<R>>,
+    {
+        install_logging();
+        let result = serde_json::from_slice::<A>(args)
+            .map_err(|e| Error::msg(format!("invalid arguments: {e}")))
+            .and_then(|a| crate::executor::block_on(f(Ctx::new(), a)))
+            .and_then(|r| {
+                serde_json::to_value(r)
+                    .map_err(|e| Error::msg(format!("invalid return value: {e}")))
+            });
+        let envelope = match result {
+            Ok(v) => serde_json::json!({ "ok": v }),
+            Err(e) => serde_json::json!({ "error": e.to_json() }),
+        };
+        envelope.to_string()
+    }
+}

package/rust/convex_fn/src/logging.rs

@@ -0,0 +1,222 @@
+//! Optional bridges from the `log` and `tracing` ecosystems to the host `log`
+//! import (contracts/ABI.md levels: 0 debug, 1 info, 2 warn, 3 error).
+//!
+//! Both are installed automatically by the `#[action]` entry (and by
+//! `convex_fn_test`) when the corresponding cargo feature is on and the user has
+//! not installed a logger / default subscriber of their own.
+//!
+//! Plain `println!` / `eprintln!` need no feature: the WASI stdout / stderr
+//! file descriptors are turned into log lines by the host (stdout at info,
+//! stderr at error).
+
+#[cfg(feature = "log")]
+mod log_bridge {
+    use log_crate::{Level, LevelFilter, Log, Metadata, Record};
+
+    use crate::{sys, wire::LogLevel};
+
+    pub struct HostLogger;
+
+    pub fn level(l: Level) -> LogLevel {
+        match l {
+            Level::Trace | Level::Debug => LogLevel::Debug,
+            Level::Info => LogLevel::Info,
+            Level::Warn => LogLevel::Warn,
+            Level::Error => LogLevel::Error,
+        }
+    }
+
+    impl Log for HostLogger {
+        fn enabled(&self, _: &Metadata<'_>) -> bool {
+            true
+        }
+        fn log(&self, record: &Record<'_>) {
+            sys::log_line(level(record.level()), &record.args().to_string());
+        }
+        fn flush(&self) {}
+    }
+
+    static LOGGER: HostLogger = HostLogger;
+
+    pub fn install() {
+        if log_crate::set_logger(&LOGGER).is_ok() {
+            log_crate::set_max_level(LevelFilter::Trace);
+        }
+    }
+}
+
+#[cfg(feature = "tracing")]
+mod tracing_bridge {
+    use std::{
+        collections::HashMap,
+        fmt::Write as _,
+        sync::{
+            atomic::{AtomicU64, Ordering},
+            Mutex,
+        },
+    };
+
+    use tracing_core::{
+        field::{Field, Visit},
+        span, Event, Level, Metadata, Subscriber,
+    };
+
+    use crate::{sys, wire::LogLevel};
+
+    #[derive(Default)]
+    struct Fields {
+        message: String,
+        rest: String,
+    }
+
+    impl Fields {
+        fn kv(&mut self, name: &str, value: std::fmt::Arguments<'_>) {
+            if !self.rest.is_empty() {
+                self.rest.push(' ');
+            }
+            let _ = write!(self.rest, "{name}={value}");
+        }
+    }
+
+    impl Visit for Fields {
+        fn record_debug(&mut self, field: &Field, value: &dyn std::fmt::Debug) {
+            if field.name() == "message" {
+                let _ = write!(self.message, "{value:?}");
+            } else {
+                self.kv(field.name(), format_args!("{value:?}"));
+            }
+        }
+        fn record_str(&mut self, field: &Field, value: &str) {
+            if field.name() == "message" {
+                self.message.push_str(value);
+            } else {
+                self.kv(field.name(), format_args!("{value:?}"));
+            }
+        }
+    }
+
+    struct SpanData {
+        name: &'static str,
+        fields: String,
+        refs: usize,
+    }
+
+    /// Formats events as `span{fields}: message key=value ...` and writes them
+    /// to the host log.
+    #[derive(Default)]
+    pub struct HostSubscriber {
+        next_id: AtomicU64,
+        spans: Mutex<HashMap<u64, SpanData>>,
+        stack: Mutex<Vec<u64>>,
+    }
+
+    pub fn level(l: &Level) -> LogLevel {
+        match *l {
+            Level::TRACE | Level::DEBUG => LogLevel::Debug,
+            Level::INFO => LogLevel::Info,
+            Level::WARN => LogLevel::Warn,
+            Level::ERROR => LogLevel::Error,
+        }
+    }
+
+    impl Subscriber for HostSubscriber {
+        fn enabled(&self, _: &Metadata<'_>) -> bool {
+            true
+        }
+        fn new_span(&self, attrs: &span::Attributes<'_>) -> span::Id {
+            let mut f = Fields::default();
+            attrs.record(&mut f);
+            let id = self.next_id.fetch_add(1, Ordering::Relaxed) + 1;
+            self.spans.lock().unwrap().insert(
+                id,
+                SpanData {
+                    name: attrs.metadata().name(),
+                    fields: f.rest,
+                    refs: 1,
+                },
+            );
+            span::Id::from_u64(id)
+        }
+        fn record(&self, id: &span::Id, values: &span::Record<'_>) {
+            let mut f = Fields::default();
+            values.record(&mut f);
+            if let Some(s) = self.spans.lock().unwrap().get_mut(&id.into_u64()) {
+                if !s.fields.is_empty() && !f.rest.is_empty() {
+                    s.fields.push(' ');
+                }
+                s.fields.push_str(&f.rest);
+            }
+        }
+        fn record_follows_from(&self, _: &span::Id, _: &span::Id) {}
+        fn clone_span(&self, id: &span::Id) -> span::Id {
+            if let Some(s) = self.spans.lock().unwrap().get_mut(&id.into_u64()) {
+                s.refs += 1;
+            }
+            id.clone()
+        }
+        fn try_close(&self, id: span::Id) -> bool {
+            let mut spans = self.spans.lock().unwrap();
+            let k = id.into_u64();
+            if let Some(s) = spans.get_mut(&k) {
+                s.refs -= 1;
+                if s.refs == 0 {
+                    spans.remove(&k);
+                    return true;
+                }
+            }
+            false
+        }
+        fn enter(&self, id: &span::Id) {
+            self.stack.lock().unwrap().push(id.into_u64());
+        }
+        fn exit(&self, id: &span::Id) {
+            let mut st = self.stack.lock().unwrap();
+            if let Some(i) = st.iter().rposition(|x| *x == id.into_u64()) {
+                st.remove(i);
+            }
+        }
+        fn event(&self, event: &Event<'_>) {
+            let mut f = Fields::default();
+            event.record(&mut f);
+            let mut line = String::new();
+            {
+                let spans = self.spans.lock().unwrap();
+                for id in self.stack.lock().unwrap().iter() {
+                    if let Some(s) = spans.get(id) {
+                        line.push_str(s.name);
+                        if !s.fields.is_empty() {
+                            let _ = write!(line, "{{{}}}", s.fields);
+                        }
+                        line.push(':');
+                    }
+                }
+            }
+            if !line.is_empty() {
+                line.push(' ');
+            }
+            line.push_str(&f.message);
+            if !f.rest.is_empty() {
+                if !f.message.is_empty() {
+                    line.push(' ');
+                }
+                line.push_str(&f.rest);
+            }
+            sys::log_line(level(event.metadata().level()), &line);
+        }
+    }
+
+    pub fn install() {
+        // Fails (harmlessly) when a global default subscriber already exists.
+        let _ = tracing_core::dispatcher::set_global_default(tracing_core::Dispatch::new(
+            HostSubscriber::default(),
+        ));
+    }
+}
+
+/// Installs the enabled bridges unless the user already installed their own.
+pub(crate) fn install() {
+    #[cfg(feature = "log")]
+    log_bridge::install();
+    #[cfg(feature = "tracing")]
+    tracing_bridge::install();
+}