convex-rust 0.0.0-stage → 0.1.0

package/rust/convex_fn/src/dns.rs

@@ -0,0 +1,356 @@
+//! DNS lookups over HTTPS (RFC 8484 JSON API, as served by Cloudflare and
+//! Google). A wasm action has no sockets, so `dns.resolve*` goes through the
+//! host `fetch` instead.
+//!
+//! ```ignore
+//! let mx = convex_fn::dns::resolve("example.com", RecordType::Mx).await?;
+//! for a in mx {
+//!     if let Record::Mx { preference, exchange } = a.record { /* ... */ }
+//! }
+//! ```
+//!
+//! The default endpoint is `https://cloudflare-dns.com/dns-query`; use
+//! [`Resolver::new`] for another JSON endpoint (for example
+//! `https://dns.google/resolve`).
+
+use std::net::{Ipv4Addr, Ipv6Addr};
+
+use serde_json::Value;
+
+use crate::{Ctx, Error, FetchRequest, Result};
+
+/// Cloudflare's DNS-over-HTTPS JSON endpoint.
+pub const CLOUDFLARE: &str = "https://cloudflare-dns.com/dns-query";
+/// Google's DNS-over-HTTPS JSON endpoint.
+pub const GOOGLE: &str = "https://dns.google/resolve";
+
+/// Record types [`resolve`] understands.
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub enum RecordType {
+    A,
+    Ns,
+    Cname,
+    Mx,
+    Txt,
+    Aaaa,
+    Srv,
+}
+
+impl RecordType {
+    /// The IANA type number.
+    pub const fn number(self) -> u16 {
+        match self {
+            RecordType::A => 1,
+            RecordType::Ns => 2,
+            RecordType::Cname => 5,
+            RecordType::Mx => 15,
+            RecordType::Txt => 16,
+            RecordType::Aaaa => 28,
+            RecordType::Srv => 33,
+        }
+    }
+
+    pub const fn as_str(self) -> &'static str {
+        match self {
+            RecordType::A => "A",
+            RecordType::Ns => "NS",
+            RecordType::Cname => "CNAME",
+            RecordType::Mx => "MX",
+            RecordType::Txt => "TXT",
+            RecordType::Aaaa => "AAAA",
+            RecordType::Srv => "SRV",
+        }
+    }
+
+    /// Parses `"MX"`, `"txt"`, ... (ASCII case-insensitive).
+    pub fn parse(s: &str) -> Option<Self> {
+        [
+            RecordType::A,
+            RecordType::Ns,
+            RecordType::Cname,
+            RecordType::Mx,
+            RecordType::Txt,
+            RecordType::Aaaa,
+            RecordType::Srv,
+        ]
+        .into_iter()
+        .find(|t| t.as_str().eq_ignore_ascii_case(s))
+    }
+}
+
+/// A resolved record's data.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub enum Record {
+    A(Ipv4Addr),
+    Aaaa(Ipv6Addr),
+    /// Host name, without the trailing dot.
+    Ns(String),
+    Cname(String),
+    Mx {
+        preference: u16,
+        exchange: String,
+    },
+    /// The character-strings of the record concatenated, as Node's `resolveTxt(...).join("")`.
+    Txt(String),
+    Srv {
+        priority: u16,
+        weight: u16,
+        port: u16,
+        target: String,
+    },
+}
+
+/// One answer: the owner name, its TTL in seconds and the data.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub struct Answer {
+    pub name: String,
+    pub ttl: u32,
+    pub record: Record,
+}
+
+/// A DNS-over-HTTPS client.
+#[derive(Clone, Debug)]
+pub struct Resolver {
+    endpoint: String,
+}
+
+impl Default for Resolver {
+    fn default() -> Self {
+        Self::new(CLOUDFLARE)
+    }
+}
+
+impl Resolver {
+    /// A resolver using the given JSON DoH endpoint.
+    pub fn new(endpoint: impl Into<String>) -> Self {
+        Self {
+            endpoint: endpoint.into(),
+        }
+    }
+
+    /// Looks up `name`. A name that does not exist (NXDOMAIN) or has no
+    /// records of `rtype` gives an empty list; a server failure is an error.
+    pub async fn resolve(&self, name: &str, rtype: RecordType) -> Result<Vec<Answer>> {
+        let url = self.url(name, rtype);
+        let resp = Ctx::default()
+            .fetch(FetchRequest::get(url).header("accept", "application/dns-json"))
+            .await?;
+        if resp.status != 200 {
+            return Err(Error::msg(format!(
+                "dns: {} answered {} for {name} {}",
+                self.endpoint,
+                resp.status,
+                rtype.as_str()
+            )));
+        }
+        parse_response(&resp.body, rtype)
+    }
+
+    fn url(&self, name: &str, rtype: RecordType) -> String {
+        let sep = if self.endpoint.contains('?') {
+            '&'
+        } else {
+            '?'
+        };
+        format!(
+            "{}{sep}name={}&type={}",
+            self.endpoint,
+            percent_encode(name),
+            rtype.as_str()
+        )
+    }
+}
+
+/// [`Resolver::resolve`] with the default (Cloudflare) endpoint.
+pub async fn resolve(name: &str, rtype: RecordType) -> Result<Vec<Answer>> {
+    Resolver::default().resolve(name, rtype).await
+}
+
+fn percent_encode(s: &str) -> String {
+    let mut out = String::with_capacity(s.len());
+    for b in s.bytes() {
+        if b.is_ascii_alphanumeric() || matches!(b, b'-' | b'.' | b'_') {
+            out.push(b as char);
+        } else {
+            out.push_str(&format!("%{b:02X}"));
+        }
+    }
+    out
+}
+
+/// Parses a DoH JSON response, keeping the answers of type `rtype` (a CNAME
+/// chain in front of an A answer is dropped).
+pub fn parse_response(body: &[u8], rtype: RecordType) -> Result<Vec<Answer>> {
+    let v: Value = serde_json::from_slice(body)?;
+    // RCODE: 0 NOERROR, 3 NXDOMAIN (no such name: nothing to return).
+    match v.get("Status").and_then(Value::as_u64) {
+        Some(0) | Some(3) => {}
+        Some(code) => {
+            return Err(Error::msg(format!("dns: server failure (RCODE {code})")));
+        }
+        None => return Err(Error::msg("dns: response has no Status")),
+    }
+    let mut out = vec![];
+    for a in v
+        .get("Answer")
+        .and_then(Value::as_array)
+        .map_or(&[][..], Vec::as_slice)
+    {
+        if a.get("type").and_then(Value::as_u64) != Some(u64::from(rtype.number())) {
+            continue;
+        }
+        let data = a.get("data").and_then(Value::as_str).unwrap_or_default();
+        let Some(record) = parse_data(rtype, data) else {
+            return Err(Error::msg(format!(
+                "dns: cannot parse {} data {data:?}",
+                rtype.as_str()
+            )));
+        };
+        out.push(Answer {
+            name: trim_dot(a.get("name").and_then(Value::as_str).unwrap_or_default()),
+            ttl: a.get("TTL").and_then(Value::as_u64).unwrap_or(0) as u32,
+            record,
+        });
+    }
+    Ok(out)
+}
+
+fn trim_dot(s: &str) -> String {
+    s.strip_suffix('.').unwrap_or(s).to_string()
+}
+
+fn parse_data(rtype: RecordType, data: &str) -> Option<Record> {
+    let mut it = data.split_whitespace();
+    Some(match rtype {
+        RecordType::A => Record::A(data.trim().parse().ok()?),
+        RecordType::Aaaa => Record::Aaaa(data.trim().parse().ok()?),
+        RecordType::Ns => Record::Ns(trim_dot(data.trim())),
+        RecordType::Cname => Record::Cname(trim_dot(data.trim())),
+        RecordType::Mx => Record::Mx {
+            preference: it.next()?.parse().ok()?,
+            exchange: trim_dot(it.next()?),
+        },
+        RecordType::Srv => Record::Srv {
+            priority: it.next()?.parse().ok()?,
+            weight: it.next()?.parse().ok()?,
+            port: it.next()?.parse().ok()?,
+            target: trim_dot(it.next()?),
+        },
+        RecordType::Txt => Record::Txt(unquote_txt(data)),
+    })
+}
+
+/// `"a" "b"` -> `ab`; text without quotes is returned as is.
+fn unquote_txt(data: &str) -> String {
+    let t = data.trim();
+    if !t.starts_with('"') {
+        return t.to_string();
+    }
+    let mut out = String::new();
+    let mut chars = t.chars();
+    let mut in_str = false;
+    while let Some(c) = chars.next() {
+        match (in_str, c) {
+            (false, '"') => in_str = true,
+            (true, '"') => in_str = false,
+            (true, '\\') => match chars.next() {
+                Some(d) if d.is_ascii_digit() => {
+                    // \DDD decimal escape
+                    let mut n = d.to_digit(10).unwrap_or(0);
+                    for _ in 0..2 {
+                        if let Some(e) = chars.next() {
+                            n = n * 10 + e.to_digit(10).unwrap_or(0);
+                        }
+                    }
+                    out.push(char::from_u32(n).unwrap_or('?'));
+                }
+                Some(d) => out.push(d),
+                None => {}
+            },
+            (true, c) => out.push(c),
+            (false, _) => {}
+        }
+    }
+    out
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parses_mx_with_cname_chain_and_dots() {
+        let body = br#"{"Status":0,"Answer":[
+            {"name":"www.x.test.","type":5,"TTL":60,"data":"x.test."},
+            {"name":"x.test.","type":15,"TTL":300,"data":"10 mx1.x.test."},
+            {"name":"x.test.","type":15,"TTL":300,"data":"20 mx2.x.test."}]}"#;
+        let a = parse_response(body, RecordType::Mx).unwrap();
+        assert_eq!(a.len(), 2);
+        assert_eq!(a[0].name, "x.test");
+        assert_eq!(a[0].ttl, 300);
+        assert_eq!(
+            a[1].record,
+            Record::Mx {
+                preference: 20,
+                exchange: "mx2.x.test".into()
+            }
+        );
+    }
+
+    #[test]
+    fn parses_a_aaaa_srv_txt() {
+        let a = parse_response(
+            br#"{"Status":0,"Answer":[{"name":"h.","type":1,"TTL":1,"data":"1.2.3.4"}]}"#,
+            RecordType::A,
+        )
+        .unwrap();
+        assert_eq!(a[0].record, Record::A(Ipv4Addr::new(1, 2, 3, 4)));
+        let a = parse_response(
+            br#"{"Status":0,"Answer":[{"name":"h.","type":28,"TTL":1,"data":"2606:4700::1"}]}"#,
+            RecordType::Aaaa,
+        )
+        .unwrap();
+        assert_eq!(a[0].record, Record::Aaaa("2606:4700::1".parse().unwrap()));
+        let a = parse_response(
+            br#"{"Status":0,"Answer":[{"name":"_s._tcp.h.","type":33,"TTL":1,"data":"1 2 443 t.h."}]}"#,
+            RecordType::Srv,
+        )
+        .unwrap();
+        assert_eq!(
+            a[0].record,
+            Record::Srv {
+                priority: 1,
+                weight: 2,
+                port: 443,
+                target: "t.h".into()
+            }
+        );
+        let a = parse_response(
+            br#"{"Status":0,"Answer":[{"name":"h.","type":16,"TTL":1,"data":"\"v=spf1 \" \"a \\\"q\\\" -all\""}]}"#,
+            RecordType::Txt,
+        )
+        .unwrap();
+        assert_eq!(a[0].record, Record::Txt("v=spf1 a \"q\" -all".into()));
+    }
+
+    #[test]
+    fn nxdomain_is_empty_servfail_is_error() {
+        assert!(parse_response(br#"{"Status":3}"#, RecordType::A)
+            .unwrap()
+            .is_empty());
+        assert!(parse_response(br#"{"Status":2}"#, RecordType::A).is_err());
+        assert!(parse_response(br#"{"Answer":[]}"#, RecordType::A).is_err());
+    }
+
+    #[test]
+    fn url_encoding_and_types() {
+        let r = Resolver::new("https://dns.google/resolve");
+        assert_eq!(
+            r.url("exa mple.com", RecordType::Txt),
+            "https://dns.google/resolve?name=exa%20mple.com&type=TXT"
+        );
+        assert_eq!(RecordType::parse("mx"), Some(RecordType::Mx));
+        assert_eq!(RecordType::parse("zz"), None);
+        assert_eq!(RecordType::Srv.number(), 33);
+    }
+}

package/rust/convex_fn/src/error.rs

@@ -0,0 +1,179 @@
+use std::fmt;
+
+use serde_json::Value;
+
+pub type Result<T, E = Error> = std::result::Result<T, E>;
+
+/// An action error. Like `anyhow::Error`, any `std::error::Error` converts into
+/// it with `?`. `Error::Convex` reaches clients as a `ConvexError` with `data`.
+#[derive(Debug, Clone)]
+pub enum Error {
+    /// Application error with structured data (`throw new ConvexError(data)`).
+    Convex { message: String, data: Value },
+    /// Any other error; clients see "Server Error" plus the message in logs.
+    Message(String),
+}
+
+/// Constructor for application errors, mirroring the JS `ConvexError` class.
+pub struct ConvexError;
+
+impl ConvexError {
+    #[allow(clippy::new_ret_no_self)]
+    pub fn new(data: impl Into<Value>) -> Error {
+        Error::convex(data)
+    }
+}
+
+impl Error {
+    /// An application error with structured data (`throw new ConvexError(data)`).
+    pub fn convex(data: impl Into<Value>) -> Self {
+        let data = data.into();
+        let message = match &data {
+            Value::String(s) => s.clone(),
+            other => other.to_string(),
+        };
+        Error::Convex { message, data }
+    }
+
+    /// The `ConvexError` data, if this is an application error.
+    pub fn data(&self) -> Option<&Value> {
+        match self {
+            Error::Convex { data, .. } => Some(data),
+            Error::Message(_) => None,
+        }
+    }
+
+    pub fn msg(message: impl Into<String>) -> Self {
+        Error::Message(message.into())
+    }
+
+    pub fn message(&self) -> &str {
+        match self {
+            Error::Convex { message, .. } | Error::Message(message) => message,
+        }
+    }
+
+    pub(crate) fn to_json(&self) -> Value {
+        match self {
+            Error::Convex { message, data } => {
+                serde_json::json!({ "message": message, "data": data, "kind": "convex" })
+            }
+            Error::Message(message) => serde_json::json!({ "message": message, "kind": "user" }),
+        }
+    }
+
+    /// Parses `{"message": …, "data"?: …}` as returned in task events.
+    pub(crate) fn from_json(v: &Value) -> Self {
+        let message = v
+            .get("message")
+            .and_then(Value::as_str)
+            .unwrap_or("unknown error")
+            .to_string();
+        match v.get("data") {
+            // A present `data` (even null) is a ConvexError, like `new ConvexError(null)` in JS.
+            Some(data) => Error::Convex {
+                message,
+                data: data.clone(),
+            },
+            None => Error::Message(message),
+        }
+    }
+}
+
+impl fmt::Display for Error {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        f.write_str(self.message())
+    }
+}
+
+impl<E: std::error::Error> From<E> for Error {
+    fn from(e: E) -> Self {
+        Error::Message(e.to_string())
+    }
+}
+
+/// Formats the panic report: `Uncaught panic: <message> at <file:line:col>`.
+/// The host (`PANIC_LOG_PREFIX` in the fork's rust/core.rs) takes the last such
+/// level-3 log line as the error message when the abort trap follows.
+#[cfg_attr(
+    not(any(target_arch = "wasm32", convex_native, test)),
+    allow(dead_code)
+)]
+pub(crate) fn format_panic(message: &str, location: Option<(&str, u32, u32)>) -> String {
+    match location {
+        Some((file, line, col)) => format!("Uncaught panic: {message} at {file}:{line}:{col}"),
+        None => format!("Uncaught panic: {message}"),
+    }
+}
+
+/// Reports panics (message + location) as an error log line before the abort
+/// trap, so the host can surface them instead of "unreachable".
+#[cfg(any(target_arch = "wasm32", convex_native))]
+pub(crate) fn install_panic_hook() {
+    static ONCE: std::sync::Once = std::sync::Once::new();
+    ONCE.call_once(|| {
+        std::panic::set_hook(Box::new(|info| {
+            let payload = info.payload();
+            let message = payload
+                .downcast_ref::<&str>()
+                .map(|s| s.to_string())
+                .or_else(|| payload.downcast_ref::<String>().cloned())
+                .unwrap_or_else(|| "Box<dyn Any>".to_string());
+            let location = info.location().map(|l| (l.file(), l.line(), l.column()));
+            #[cfg(convex_native)]
+            crate::native::record_panic(match location {
+                Some((file, line, col)) => format!("{message} at {file}:{line}:{col}"),
+                None => message.clone(),
+            });
+            crate::sys::log_line(
+                crate::wire::LogLevel::Error,
+                &format_panic(&message, location),
+            );
+            // Distinguishes the real panic line from a user log line with the same prefix.
+            crate::sys::panic_marker();
+        }));
+    });
+}
+
+#[cfg(test)]
+mod tests {
+    use serde_json::json;
+
+    use super::{format_panic, ConvexError, Error};
+
+    #[test]
+    fn convex_error_json_round_trip() {
+        let e = Error::convex(json!({ "code": 7, "tags": ["a"] }));
+        assert_eq!(e.data(), Some(&json!({ "code": 7, "tags": ["a"] })));
+        let j = e.to_json();
+        assert_eq!(j["kind"], "convex");
+        let back = Error::from_json(&j);
+        assert_eq!(back.data(), e.data());
+        assert_eq!(back.message(), e.message());
+        // String data uses the string itself as message.
+        let s = ConvexError::new("nope");
+        assert_eq!(s.message(), "nope");
+        assert_eq!(Error::from_json(&s.to_json()).data(), Some(&json!("nope")));
+    }
+
+    #[test]
+    fn message_error_json_round_trip() {
+        let e = Error::msg("boom");
+        assert_eq!(e.data(), None);
+        let j = e.to_json();
+        assert_eq!(j, json!({ "message": "boom", "kind": "user" }));
+        let back = Error::from_json(&j);
+        assert_eq!(back.data(), None);
+        assert_eq!(back.message(), "boom");
+        // Missing message falls back.
+        assert_eq!(Error::from_json(&json!({})).message(), "unknown error");
+    }
+
+    #[test]
+    fn panic_line_has_message_and_location() {
+        assert_eq!(
+            format_panic("kaboom", Some(("src/spec.rs", 12, 5))),
+            "Uncaught panic: kaboom at src/spec.rs:12:5"
+        );
+    }
+}