feat(clients): add Go, Rust, C# and Dart clients for ResolveSpec and FunctionSpec

clients/resolvespec-rs/.gitignore

@@ -0,0 +1,2 @@
+target/
+Cargo.lock

clients/resolvespec-rs/Cargo.toml

@@ -0,0 +1,18 @@
+[package]
+name = "resolvespec"
+version = "0.1.0"
+edition = "2021"
+rust-version = "1.80"
+description = "Client for ResolveSpec (JSON body) and FunctionSpec endpoints"
+license = "MIT"
+
+[dependencies]
+reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+base64 = "0.22"
+thiserror = "1"
+
+[dev-dependencies]
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+wiremock = "0.6"

clients/resolvespec-rs/README.md

@@ -0,0 +1,40 @@
+# resolvespec (Rust)
+
+Rust client for ResolveSpec (JSON body) and FunctionSpec. Async (`reqwest` + `tokio`). MSRV 1.80.
+
+## Clients
+
+| Type | Constructor | Methods |
+|---|---|---|
+| `ResolveSpecClient` | `new(base_url)` / `from_builder(ClientBuilder)` | `get_metadata` `read` `create` `update` `delete` |
+| `FuncSpecClient` | `new(base_url)` / `from_builder(ClientBuilder)` | `query` `query_list` `request` |
+
+`ClientBuilder::new(url).token().header().timeout().http_client()`. Precedence: Content-Type < custom headers < bearer token.
+
+## ResolveSpec
+
+- `RecordId`: `Int`/`Str` → URL, `Many(Vec<String>)` → body (`From` impls provided).
+- `Options` (`Default` + struct update), optional fields are `Option`/empty `Vec`.
+- Result: `Response{success, data: serde_json::Value, metadata}`; `resp.decode::<T>()`.
+
+## FunctionSpec
+
+- Routes are server-defined: pass the `path`.
+- `Params = BTreeMap<String, Param>` → query string (`Param::List` → repeated keys).
+- `FuncSpecOptions` → `X-*` headers: `filters`, `search_filters`, `custom_sql_where`, `custom_sql_or`, `sort`, `limit`, `offset`, `distinct`, `skip_count`, `skip_cache`, `response_format`.
+- `query_list` fills `metadata` from `Content-Range`; 206 is success.
+
+## Server quirks
+
+- `sort` is raw SQL in ORDER BY (client sends `col ASC|DESC`).
+- One search operator per column.
+- Values starting `ZIP_` / `__` are base64-decoded by the server.
+- Non-ASCII, control chars and edge spaces are auto-encoded (`ZIP_`).
+
+## Errors
+
+`Error::Api { status, message, error: ApiError{code, message, detail, sql} }`, `Error::Http`, `Error::Json`.
+
+## Test
+
+`cargo test`

clients/resolvespec-rs/src/client.rs

@@ -0,0 +1,90 @@
+use std::collections::HashMap;
+use std::time::Duration;
+
+use reqwest::header::{HeaderMap, HeaderName, HeaderValue, AUTHORIZATION, CONTENT_TYPE};
+
+use crate::error::Result;
+
+/// Shared HTTP configuration.
+#[derive(Clone)]
+pub(crate) struct Config {
+    pub base_url: String,
+    pub token: Option<String>,
+    pub headers: HashMap<String, String>,
+    pub http: reqwest::Client,
+}
+
+/// Builder options shared by both clients.
+#[derive(Default, Clone)]
+pub struct ClientBuilder {
+    base_url: String,
+    token: Option<String>,
+    headers: HashMap<String, String>,
+    timeout: Option<Duration>,
+    http: Option<reqwest::Client>,
+}
+
+impl ClientBuilder {
+    pub fn new(base_url: &str) -> Self {
+        Self { base_url: base_url.trim_end_matches('/').into(), timeout: Some(Duration::from_secs(30)), ..Default::default() }
+    }
+    pub fn token(mut self, token: &str) -> Self {
+        self.token = Some(token.into());
+        self
+    }
+    pub fn header(mut self, name: &str, value: &str) -> Self {
+        self.headers.insert(name.into(), value.into());
+        self
+    }
+    pub fn timeout(mut self, t: Duration) -> Self {
+        self.timeout = Some(t);
+        self
+    }
+    pub fn http_client(mut self, c: reqwest::Client) -> Self {
+        self.http = Some(c);
+        self
+    }
+    pub(crate) fn config(self) -> Result<Config> {
+        let http = match self.http {
+            Some(c) => c,
+            None => {
+                let mut b = reqwest::Client::builder();
+                if let Some(t) = self.timeout {
+                    b = b.timeout(t);
+                }
+                b.build()?
+            }
+        };
+        Ok(Config { base_url: self.base_url, token: self.token, headers: self.headers, http })
+    }
+}
+
+impl Config {
+    /// Content-Type < custom headers < extra (per-call) < bearer token.
+    pub fn headers(&self, extra: &HashMap<String, String>) -> HeaderMap {
+        let mut m = HeaderMap::new();
+        m.insert(CONTENT_TYPE, HeaderValue::from_static("application/json"));
+        for (k, v) in self.headers.iter().chain(extra.iter()) {
+            if let (Ok(n), Ok(v)) = (HeaderName::try_from(k.as_str()), HeaderValue::from_str(v)) {
+                m.insert(n, v);
+            }
+        }
+        if let Some(t) = &self.token {
+            if let Ok(v) = HeaderValue::from_str(&format!("Bearer {t}")) {
+                m.insert(AUTHORIZATION, v);
+            }
+        }
+        m
+    }
+}
+
+pub(crate) fn path_segment(s: &str) -> String {
+    let mut out = String::new();
+    for b in s.bytes() {
+        match b {
+            b'A'..=b'Z' | b'a'..=b'z' | b'0'..=b'9' | b'-' | b'.' | b'_' | b'~' => out.push(b as char),
+            _ => out.push_str(&format!("%{b:02X}")),
+        }
+    }
+    out
+}

clients/resolvespec-rs/src/error.rs

@@ -0,0 +1,34 @@
+use crate::types::ApiError;
+
+/// Returned on transport failure, a non-2xx response or an unsuccessful API result.
+#[derive(Debug, thiserror::Error)]
+pub enum Error {
+    #[error("{message}")]
+    Api { status: u16, message: String, error: ApiError },
+    #[error(transparent)]
+    Http(#[from] reqwest::Error),
+    #[error(transparent)]
+    Json(#[from] serde_json::Error),
+}
+
+pub type Result<T> = std::result::Result<T, Error>;
+
+pub(crate) fn error_from(status: u16, body: &str) -> Error {
+    let parsed: Option<serde_json::Value> = serde_json::from_str(body).ok();
+    let err: ApiError = parsed
+        .as_ref()
+        .and_then(|v| v.get("error"))
+        .and_then(|e| serde_json::from_value(e.clone()).ok())
+        .unwrap_or_default();
+    let message = if !err.message.is_empty() {
+        err.message.clone()
+    } else {
+        let text = if parsed.is_none() { body.trim().chars().take(200).collect::<String>() } else { String::new() };
+        if text.is_empty() {
+            format!("{} ({})", reqwest::StatusCode::from_u16(status).ok().and_then(|s| s.canonical_reason()).unwrap_or("Error"), status)
+        } else {
+            text
+        }
+    };
+    Error::Api { status, message, error: err }
+}

clients/resolvespec-rs/src/funcspec.rs

@@ -0,0 +1,263 @@
+use std::collections::{BTreeMap, HashMap};
+
+use base64::{engine::general_purpose::STANDARD, Engine};
+use reqwest::Method;
+use serde_json::Value;
+
+use crate::client::{ClientBuilder, Config};
+use crate::error::{error_from, Result};
+use crate::types::{FilterOption, Metadata, Response, SortOption};
+
+/// Options sent to funcspec endpoints as `X-*` headers.
+///
+/// Server behaviour (`pkg/funcspec`): `sort` is inserted raw into ORDER BY (so it is sent as SQL
+/// terms); only one search operator per column is kept; values starting with `ZIP_` or `__`
+/// are base64-decoded by the server, so such plaintext values cannot be sent faithfully.
+#[derive(Debug, Clone, Default)]
+pub struct FuncSpecOptions {
+    /// eq+AND -> X-FieldFilter; others X-SearchOp / X-SearchOr.
+    pub filters: Vec<FilterOption>,
+    /// X-SearchFilter-{col}: text ILIKE.
+    pub search_filters: BTreeMap<String, String>,
+    pub custom_sql_where: Option<String>,
+    pub custom_sql_or: Option<String>,
+    pub sort: Vec<SortOption>,
+    pub limit: Option<i64>,
+    pub offset: Option<i64>,
+    pub distinct: Option<bool>,
+    pub skip_count: Option<bool>,
+    pub skip_cache: Option<bool>,
+    /// simple | detail | syncfusion
+    pub response_format: Option<String>,
+}
+
+/// Query-string parameter value. `List` is sent as repeated keys (server: IN filter).
+#[derive(Debug, Clone)]
+pub enum Param {
+    Str(String),
+    Int(i64),
+    Bool(bool),
+    List(Vec<String>),
+}
+
+impl From<&str> for Param {
+    fn from(v: &str) -> Self {
+        Self::Str(v.into())
+    }
+}
+impl From<String> for Param {
+    fn from(v: String) -> Self {
+        Self::Str(v)
+    }
+}
+impl From<i64> for Param {
+    fn from(v: i64) -> Self {
+        Self::Int(v)
+    }
+}
+impl From<bool> for Param {
+    fn from(v: bool) -> Self {
+        Self::Bool(v)
+    }
+}
+impl From<Vec<String>> for Param {
+    fn from(v: Vec<String>) -> Self {
+        Self::List(v)
+    }
+}
+
+pub type Params = BTreeMap<String, Param>;
+
+fn operator(op: &str) -> &str {
+    match op {
+        "eq" => "equals",
+        "neq" => "notequals",
+        "gt" => "greaterthan",
+        "gte" => "greaterthanorequal",
+        "lt" => "lessthan",
+        "lte" => "lessthanorequal",
+        "like" | "ilike" | "contains" => "contains",
+        "startswith" => "beginswith",
+        "endswith" => "endswith",
+        "in" => "in",
+        "between" => "between",
+        "between_inclusive" => "betweeninclusive",
+        "is_null" => "empty",
+        "is_not_null" => "notempty",
+        other => other,
+    }
+}
+
+fn scalar(v: &Value) -> String {
+    match v {
+        Value::Null => String::new(),
+        Value::String(s) => s.clone(),
+        Value::Array(a) => a.iter().map(scalar).collect::<Vec<_>>().join(","),
+        other => other.to_string(),
+    }
+}
+
+/// Base64 (UTF-8) with the `ZIP_` prefix.
+pub fn encode_header_value(v: &str) -> String {
+    format!("ZIP_{}", STANDARD.encode(v.as_bytes()))
+}
+
+/// Decode a value that may carry a `ZIP_` or `__` prefix (nested allowed).
+pub fn decode_header_value(v: &str) -> String {
+    for p in ["ZIP_", "__"] {
+        if let Some(rest) = v.strip_prefix(p) {
+            let mut b64: String = rest.chars().filter(|c| !matches!(c, '\n' | '\r' | ' ')).collect();
+            while b64.len() % 4 != 0 {
+                b64.push('=');
+            }
+            return match STANDARD.decode(b64).ok().and_then(|b| String::from_utf8(b).ok()) {
+                Some(s) => decode_header_value(&s),
+                None => v.to_string(),
+            };
+        }
+    }
+    v.to_string()
+}
+
+/// Encode values that are unsafe as raw header/query text (non-ASCII, control chars, edge spaces).
+fn safe(v: &str) -> String {
+    if v != v.trim() || v.chars().any(|c| !c.is_ascii() || c.is_ascii_control()) {
+        encode_header_value(v)
+    } else {
+        v.to_string()
+    }
+}
+
+/// Build the `X-*` headers understood by `funcspec.ParseParameters`.
+pub fn build_headers(o: &FuncSpecOptions) -> BTreeMap<String, String> {
+    let mut h = BTreeMap::new();
+    for f in &o.filters {
+        let logic = f.logic_operator.as_deref().unwrap_or("AND");
+        let v = safe(&scalar(&f.value));
+        if f.operator == "eq" && logic == "AND" {
+            h.insert(format!("X-FieldFilter-{}", f.column), v);
+        } else {
+            let kind = if logic == "OR" { "X-SearchOr" } else { "X-SearchOp" };
+            h.insert(format!("{kind}-{}-{}", operator(&f.operator), f.column), v);
+        }
+    }
+    for (col, text) in &o.search_filters {
+        h.insert(format!("X-SearchFilter-{col}"), safe(text));
+    }
+    if let Some(v) = o.custom_sql_where.as_deref().filter(|s| !s.is_empty()) {
+        h.insert("X-Custom-SQL-W".into(), safe(v));
+    }
+    if let Some(v) = o.custom_sql_or.as_deref().filter(|s| !s.is_empty()) {
+        h.insert("X-Custom-SQL-Or".into(), safe(v));
+    }
+    if !o.sort.is_empty() {
+        let terms: Vec<String> = o
+            .sort
+            .iter()
+            .map(|s| format!("{} {}", s.column, if s.direction.eq_ignore_ascii_case("desc") { "DESC" } else { "ASC" }))
+            .collect();
+        h.insert("X-Sort".into(), safe(&terms.join(","))); // funcspec puts this verbatim into ORDER BY
+    }
+    if let Some(n) = o.limit {
+        h.insert("X-Limit".into(), n.to_string());
+    }
+    if let Some(n) = o.offset {
+        h.insert("X-Offset".into(), n.to_string());
+    }
+    for (name, v) in [("X-Distinct", o.distinct), ("X-SkipCount", o.skip_count), ("X-SkipCache", o.skip_cache)] {
+        if let Some(b) = v {
+            h.insert(name.into(), b.to_string());
+        }
+    }
+    match o.response_format.as_deref() {
+        Some("simple") => h.insert("X-SimpleApi".into(), "true".into()),
+        Some("detail") => h.insert("X-DetailApi".into(), "true".into()),
+        Some("syncfusion") => h.insert("X-Syncfusion".into(), "true".into()),
+        _ => None,
+    };
+    h
+}
+
+/// Build query-string pairs: bools -> true/false, lists -> repeated keys.
+pub fn build_query(p: &Params) -> Vec<(String, String)> {
+    let mut out = Vec::new();
+    for (k, v) in p {
+        match v {
+            Param::Str(s) => out.push((k.clone(), safe(s))),
+            Param::Int(n) => out.push((k.clone(), n.to_string())),
+            Param::Bool(b) => out.push((k.clone(), b.to_string())),
+            Param::List(l) => out.extend(l.iter().map(|s| (k.clone(), safe(s)))),
+        }
+    }
+    out
+}
+
+fn metadata(content_range: Option<&str>, limit: Option<i64>) -> Metadata {
+    let mut m = Metadata { limit: limit.unwrap_or(0), ..Default::default() };
+    if let Some(cr) = content_range {
+        // "items {start}-{end}/{total}"
+        let rest = cr.rsplit(' ').next().unwrap_or("");
+        if let Some((range, total)) = rest.split_once('/') {
+            if let (Some((s, e)), Ok(t)) = (range.split_once('-'), total.parse::<i64>()) {
+                if let (Ok(s), Ok(e)) = (s.parse::<i64>(), e.parse::<i64>()) {
+                    m.total = t;
+                    m.filtered = t;
+                    m.count = e - s;
+                    m.offset = s;
+                }
+            }
+        }
+    }
+    m
+}
+
+/// Client for user-defined SQL endpoints. Routes are defined by the server application.
+#[derive(Clone)]
+pub struct FuncSpecClient {
+    cfg: Config,
+}
+
+impl FuncSpecClient {
+    pub fn new(base_url: &str) -> Result<Self> {
+        Self::from_builder(ClientBuilder::new(base_url))
+    }
+
+    pub fn from_builder(b: ClientBuilder) -> Result<Self> {
+        Ok(Self { cfg: b.config()? })
+    }
+
+    async fn call(&self, method: Method, path: &str, params: &Params, options: Option<&FuncSpecOptions>, list: bool) -> Result<Response> {
+        let url = format!("{}/{}", self.cfg.base_url, path.trim_start_matches('/'));
+        let extra: HashMap<String, String> = options.map(|o| build_headers(o).into_iter().collect()).unwrap_or_default();
+        let resp = self.cfg.http.request(method, url).headers(self.cfg.headers(&extra)).query(&build_query(params)).send().await?;
+        let status = resp.status();
+        let cr = resp.headers().get("content-range").and_then(|v| v.to_str().ok()).map(str::to_owned);
+        let text = resp.text().await?;
+        if !status.is_success() {
+            // 206 Partial Content is success
+            return Err(error_from(status.as_u16(), &text));
+        }
+        let data = if text.trim().is_empty() { Value::Null } else { serde_json::from_str(&text)? };
+        Ok(Response {
+            success: true,
+            data,
+            metadata: list.then(|| metadata(cr.as_deref(), options.and_then(|o| o.limit))),
+            error: None,
+        })
+    }
+
+    /// Single-record endpoint (`SqlQuery`). `data` is the row object.
+    pub async fn query(&self, path: &str, params: &Params, options: Option<&FuncSpecOptions>) -> Result<Response> {
+        self.call(Method::GET, path, params, options, false).await
+    }
+
+    /// List endpoint (`SqlQueryList`). Metadata comes from Content-Range.
+    pub async fn query_list(&self, path: &str, params: &Params, options: Option<&FuncSpecOptions>) -> Result<Response> {
+        self.call(Method::GET, path, params, options, true).await
+    }
+
+    /// Like `query` / `query_list` with an explicit HTTP method (routes are app-defined).
+    pub async fn request(&self, method: Method, path: &str, params: &Params, options: Option<&FuncSpecOptions>, list: bool) -> Result<Response> {
+        self.call(method, path, params, options, list).await
+    }
+}

clients/resolvespec-rs/src/lib.rs

@@ -0,0 +1,12 @@
+//! Client for ResolveSpec (JSON body) and FunctionSpec endpoints.
+mod client;
+mod error;
+mod funcspec;
+mod resolvespec;
+pub mod types;
+
+pub use client::ClientBuilder;
+pub use error::{Error, Result};
+pub use funcspec::{build_headers, build_query, decode_header_value, encode_header_value, FuncSpecClient, FuncSpecOptions, Param, Params};
+pub use resolvespec::{RecordId, ResolveSpecClient};
+pub use types::*;

clients/resolvespec-rs/src/resolvespec.rs

@@ -0,0 +1,130 @@
+use std::collections::HashMap;
+
+use reqwest::Method;
+use serde::Serialize;
+use serde_json::Value;
+
+use crate::client::{path_segment, ClientBuilder, Config};
+use crate::error::{error_from, Error, Result};
+use crate::types::{Options, Response};
+
+/// A record id: a single value goes in the URL, a list goes in the body.
+#[derive(Debug, Clone)]
+pub enum RecordId {
+    Int(i64),
+    Str(String),
+    Many(Vec<String>),
+}
+
+impl From<i64> for RecordId {
+    fn from(v: i64) -> Self {
+        Self::Int(v)
+    }
+}
+impl From<&str> for RecordId {
+    fn from(v: &str) -> Self {
+        Self::Str(v.into())
+    }
+}
+impl From<Vec<String>> for RecordId {
+    fn from(v: Vec<String>) -> Self {
+        Self::Many(v)
+    }
+}
+
+fn url_id(id: &Option<RecordId>) -> Option<String> {
+    match id {
+        Some(RecordId::Int(n)) => Some(n.to_string()),
+        Some(RecordId::Str(s)) => Some(s.clone()),
+        _ => None,
+    }
+}
+
+#[derive(Serialize)]
+struct Request<'a> {
+    operation: &'a str,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    id: Option<Vec<String>>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    data: Option<Value>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    options: Option<&'a Options>,
+}
+
+/// Client for the ResolveSpec JSON body protocol.
+#[derive(Clone)]
+pub struct ResolveSpecClient {
+    cfg: Config,
+}
+
+impl ResolveSpecClient {
+    pub fn new(base_url: &str) -> Result<Self> {
+        Self::from_builder(ClientBuilder::new(base_url))
+    }
+
+    pub fn from_builder(b: ClientBuilder) -> Result<Self> {
+        Ok(Self { cfg: b.config()? })
+    }
+
+    fn url(&self, schema: &str, entity: &str, id: Option<String>) -> String {
+        let mut u = format!("{}/{}/{}", self.cfg.base_url, path_segment(schema), path_segment(entity));
+        if let Some(id) = id.filter(|i| !i.is_empty()) {
+            u.push('/');
+            u.push_str(&path_segment(&id));
+        }
+        u
+    }
+
+    async fn send(&self, method: Method, url: String, body: Option<Request<'_>>) -> Result<Response> {
+        let mut req = self.cfg.http.request(method, url).headers(self.cfg.headers(&HashMap::new()));
+        if let Some(b) = body {
+            req = req.body(serde_json::to_vec(&b)?);
+        }
+        let resp = req.send().await?;
+        let status = resp.status();
+        let text = resp.text().await?;
+        if !status.is_success() {
+            return Err(error_from(status.as_u16(), &text));
+        }
+        let out: Response = serde_json::from_str(&text)?;
+        if !out.success {
+            if let Some(e) = out.error.clone() {
+                return Err(Error::Api { status: status.as_u16(), message: e.message.clone(), error: e });
+            }
+        }
+        Ok(out)
+    }
+
+    /// GET /{schema}/{entity}
+    pub async fn get_metadata(&self, schema: &str, entity: &str) -> Result<Response> {
+        self.send(Method::GET, self.url(schema, entity, None), None).await
+    }
+
+    pub async fn read(&self, schema: &str, entity: &str, id: Option<RecordId>, options: Option<&Options>) -> Result<Response> {
+        let body = Request { operation: "read", id: many(&id), data: None, options };
+        self.send(Method::POST, self.url(schema, entity, url_id(&id)), Some(body)).await
+    }
+
+    pub async fn create(&self, schema: &str, entity: &str, data: Value, options: Option<&Options>) -> Result<Response> {
+        let body = Request { operation: "create", id: None, data: Some(data), options };
+        self.send(Method::POST, self.url(schema, entity, None), Some(body)).await
+    }
+
+    pub async fn update(&self, schema: &str, entity: &str, data: Value, id: Option<RecordId>, options: Option<&Options>) -> Result<Response> {
+        let body = Request { operation: "update", id: many(&id), data: Some(data), options };
+        self.send(Method::POST, self.url(schema, entity, url_id(&id)), Some(body)).await
+    }
+
+    pub async fn delete(&self, schema: &str, entity: &str, id: impl Into<RecordId>) -> Result<Response> {
+        let id = Some(id.into());
+        let body = Request { operation: "delete", id: None, data: None, options: None };
+        self.send(Method::POST, self.url(schema, entity, url_id(&id)), Some(body)).await
+    }
+}
+
+fn many(id: &Option<RecordId>) -> Option<Vec<String>> {
+    match id {
+        Some(RecordId::Many(v)) => Some(v.clone()),
+        _ => None,
+    }
+}

clients/resolvespec-rs/src/types.rs

@@ -0,0 +1,192 @@
+//! Types aligned with Go `pkg/common/types.go`. Field names are the wire names.
+use serde::{Deserialize, Serialize};
+use serde_json::Value;
+use std::collections::HashMap;
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct FilterOption {
+    pub column: String,
+    /// eq neq gt gte lt lte like ilike in contains startswith endswith between
+    /// between_inclusive is_null is_not_null
+    pub operator: String,
+    #[serde(default)]
+    pub value: Value,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub logic_operator: Option<String>, // AND | OR
+}
+
+impl FilterOption {
+    pub fn new(column: &str, operator: &str, value: impl Into<Value>) -> Self {
+        Self { column: column.into(), operator: operator.into(), value: value.into(), logic_operator: None }
+    }
+    pub fn or(mut self) -> Self {
+        self.logic_operator = Some("OR".into());
+        self
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct SortOption {
+    pub column: String,
+    pub direction: String, // asc | desc
+}
+
+impl SortOption {
+    pub fn new(column: &str, direction: &str) -> Self {
+        Self { column: column.into(), direction: direction.into() }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Parameter {
+    pub name: String,
+    pub value: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub sequence: Option<i32>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct CustomOperator {
+    pub name: String,
+    pub sql: String,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ComputedColumn {
+    pub name: String,
+    pub expression: String,
+}
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct PreloadOption {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub relation: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub table_name: Option<String>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub columns: Vec<String>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub omit_columns: Vec<String>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub sort: Vec<SortOption>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub filters: Vec<FilterOption>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub r#where: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub limit: Option<i64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub offset: Option<i64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub updateable: Option<bool>,
+    #[serde(skip_serializing_if = "HashMap::is_empty", default)]
+    pub computed_ql: HashMap<String, String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub recursive: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub primary_key: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub related_key: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub foreign_key: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub recursive_child_key: Option<String>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub sql_joins: Vec<String>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub join_aliases: Vec<String>,
+}
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct VectorSearchOption {
+    pub column: String,
+    pub vector: Vec<f64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub metric: Option<String>, // l2 (default) | cosine | ip
+    #[serde(rename = "as", skip_serializing_if = "Option::is_none")]
+    pub alias: Option<String>, // distance alias, default _distance
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub direction: Option<String>,
+}
+
+/// ResolveSpec request options object.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct Options {
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub preload: Vec<PreloadOption>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub columns: Vec<String>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub omit_columns: Vec<String>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub filters: Vec<FilterOption>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub sort: Vec<SortOption>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub limit: Option<i64>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub offset: Option<i64>,
+    #[serde(rename = "customOperators", skip_serializing_if = "Vec::is_empty", default)]
+    pub custom_operators: Vec<CustomOperator>,
+    #[serde(rename = "computedColumns", skip_serializing_if = "Vec::is_empty", default)]
+    pub computed_columns: Vec<ComputedColumn>,
+    #[serde(skip_serializing_if = "Vec::is_empty", default)]
+    pub parameters: Vec<Parameter>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub cursor_forward: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub cursor_backward: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub fetch_row_number: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub vector_search: Option<VectorSearchOption>,
+}
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
+pub struct Metadata {
+    #[serde(default)]
+    pub total: i64,
+    #[serde(default)]
+    pub count: i64,
+    #[serde(default)]
+    pub filtered: i64,
+    #[serde(default)]
+    pub limit: i64,
+    #[serde(default)]
+    pub offset: i64,
+}
+
+/// ResolveSpec envelope. `data` is left as JSON for the caller to decode.
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct Response {
+    #[serde(default)]
+    pub success: bool,
+    #[serde(default)]
+    pub data: Value,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub metadata: Option<Metadata>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub error: Option<ApiError>,
+}
+
+impl Response {
+    /// Decode `data` into `T`.
+    pub fn decode<T: serde::de::DeserializeOwned>(&self) -> Result<T, serde_json::Error> {
+        serde_json::from_value(self.data.clone())
+    }
+}
+
+#[derive(Debug, Clone, Default, Serialize, Deserialize)]
+pub struct ApiError {
+    #[serde(default)]
+    pub code: String,
+    #[serde(default)]
+    pub message: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub details: Option<Value>,
+    /// Server-side reason (funcspec / restheadspec).
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub detail: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub sql: Option<String>,
+}

clients/resolvespec-rs/tests/client.rs

@@ -0,0 +1,164 @@
+use resolvespec::*;
+use serde_json::json;
+use wiremock::matchers::{header, method, path, query_param};
+use wiremock::{Mock, MockServer, ResponseTemplate};
+
+#[tokio::test]
+async fn read_posts_body_with_headers() {
+    let srv = MockServer::start().await;
+    Mock::given(method("POST"))
+        .and(path("/public/users"))
+        .and(header("authorization", "Bearer tok"))
+        .and(header("x-tenant", "a"))
+        .respond_with(ResponseTemplate::new(200).set_body_json(json!({"success": true, "data": [{"id": 1}]})))
+        .expect(1)
+        .mount(&srv)
+        .await;
+    let c = ResolveSpecClient::from_builder(ClientBuilder::new(&format!("{}/", srv.uri())).token("tok").header("X-Tenant", "a")).unwrap();
+    let opts = Options { limit: Some(5), filters: vec![FilterOption::new("a", "eq", 1)], ..Default::default() };
+    let r = c.read("public", "users", None, Some(&opts)).await.unwrap();
+    let rows: Vec<serde_json::Value> = r.decode().unwrap();
+    assert_eq!(rows.len(), 1);
+    let body: serde_json::Value = serde_json::from_slice(&srv.received_requests().await.unwrap()[0].body).unwrap();
+    assert_eq!(body["operation"], "read");
+    assert_eq!(body["options"]["limit"], 5);
+    assert!(body.get("id").is_none());
+}
+
+#[tokio::test]
+async fn id_placement() {
+    let srv = MockServer::start().await;
+    Mock::given(method("POST")).respond_with(ResponseTemplate::new(200).set_body_json(json!({"success": true, "data": {}}))).mount(&srv).await;
+    let c = ResolveSpecClient::new(&srv.uri()).unwrap();
+    c.read("s", "e", Some(7.into()), None).await.unwrap();
+    c.update("s", "e", json!({"a": 1}), Some(vec!["1".to_string(), "2".to_string()].into()), None).await.unwrap();
+    c.delete("s", "e", "a/b").await.unwrap();
+    let reqs = srv.received_requests().await.unwrap();
+    assert_eq!(reqs[0].url.path(), "/s/e/7");
+    assert_eq!(reqs[1].url.path(), "/s/e");
+    let b: serde_json::Value = serde_json::from_slice(&reqs[1].body).unwrap();
+    assert_eq!(b["id"], json!(["1", "2"]));
+    assert_eq!(b["operation"], "update");
+    assert_eq!(reqs[2].url.path(), "/s/e/a%2Fb");
+}
+
+#[tokio::test]
+async fn errors() {
+    let srv = MockServer::start().await;
+    Mock::given(path("/s/a")).respond_with(ResponseTemplate::new(400).set_body_json(json!({"success": false, "error": {"code": "x", "message": "bad", "detail": "why"}}))).mount(&srv).await;
+    Mock::given(path("/s/b")).respond_with(ResponseTemplate::new(502).set_body_string("bad gateway")).mount(&srv).await;
+    Mock::given(path("/s/c")).respond_with(ResponseTemplate::new(200).set_body_json(json!({"success": false, "error": {"code": "c", "message": "nope"}}))).mount(&srv).await;
+    let c = ResolveSpecClient::new(&srv.uri()).unwrap();
+    match c.read("s", "a", None, None).await.unwrap_err() {
+        Error::Api { status, message, error } => {
+            assert_eq!((status, message.as_str(), error.code.as_str(), error.detail.as_deref()), (400, "bad", "x", Some("why")))
+        }
+        e => panic!("{e:?}"),
+    }
+    match c.read("s", "b", None, None).await.unwrap_err() {
+        Error::Api { status, message, .. } => assert_eq!((status, message.as_str()), (502, "bad gateway")),
+        e => panic!("{e:?}"),
+    }
+    assert_eq!(c.read("s", "c", None, None).await.unwrap_err().to_string(), "nope");
+}
+
+#[test]
+fn headers_filters() {
+    let o = FuncSpecOptions {
+        filters: vec![
+            FilterOption::new("status", "eq", "active"),
+            FilterOption::new("age", "gte", 18),
+            FilterOption::new("name", "contains", "x").or(),
+            FilterOption::new("deleted", "is_null", serde_json::Value::Null),
+            FilterOption::new("id", "in", json!([1, 2])),
+            FilterOption::new("p", "between_inclusive", json!([1, 5])),
+        ],
+        ..Default::default()
+    };
+    let h = build_headers(&o);
+    let want: std::collections::BTreeMap<String, String> = [
+        ("X-FieldFilter-status", "active"),
+        ("X-SearchOp-greaterthanorequal-age", "18"),
+        ("X-SearchOr-contains-name", "x"),
+        ("X-SearchOp-empty-deleted", ""),
+        ("X-SearchOp-in-id", "1,2"),
+        ("X-SearchOp-betweeninclusive-p", "1,5"),
+    ]
+    .into_iter()
+    .map(|(k, v)| (k.to_string(), v.to_string()))
+    .collect();
+    assert_eq!(h, want);
+}
+
+#[test]
+fn headers_misc_and_encoding() {
+    let o = FuncSpecOptions {
+        search_filters: [("name".to_string(), "bob".to_string())].into(),
+        custom_sql_where: Some("a = 1".into()),
+        custom_sql_or: Some("b = 2".into()),
+        sort: vec![SortOption::new("name", "asc"), SortOption::new("created_at", "DESC")],
+        limit: Some(5),
+        offset: Some(10),
+        distinct: Some(true),
+        skip_count: Some(true),
+        skip_cache: Some(false),
+        response_format: Some("syncfusion".into()),
+        ..Default::default()
+    };
+    let h = build_headers(&o);
+    assert_eq!(h["X-Sort"], "name ASC,created_at DESC");
+    assert_eq!(h["X-SearchFilter-name"], "bob");
+    assert_eq!(h["X-Custom-SQL-W"], "a = 1");
+    assert_eq!(h["X-Limit"], "5");
+    assert_eq!(h["X-SkipCache"], "false");
+    assert_eq!(h["X-Syncfusion"], "true");
+
+    let o = FuncSpecOptions { filters: vec![FilterOption::new("n", "eq", "héllo"), FilterOption::new("m", "eq", " pad")], ..Default::default() };
+    let h = build_headers(&o);
+    assert!(h["X-FieldFilter-n"].starts_with("ZIP_"));
+    assert_eq!(decode_header_value(&h["X-FieldFilter-n"]), "héllo");
+    assert_eq!(decode_header_value(&h["X-FieldFilter-m"]), " pad");
+}
+
+#[test]
+fn query_building() {
+    let mut p = Params::new();
+    p.insert("a".into(), true.into());
+    p.insert("b".into(), vec!["x".to_string(), "y".to_string()].into());
+    p.insert("d".into(), 3i64.into());
+    assert_eq!(build_query(&p), vec![("a".into(), "true".into()), ("b".into(), "x".into()), ("b".into(), "y".into()), ("d".into(), "3".into())]);
+}
+
+#[tokio::test]
+async fn query_list_metadata() {
+    let srv = MockServer::start().await;
+    Mock::given(method("GET"))
+        .and(path("/api/users"))
+        .and(query_param("org", "1"))
+        .and(header("x-limit", "2"))
+        .respond_with(ResponseTemplate::new(206).insert_header("Content-Range", "items 10-12/50").set_body_json(json!([{"id": 1}, {"id": 2}])))
+        .expect(1)
+        .mount(&srv)
+        .await;
+    let c = FuncSpecClient::from_builder(ClientBuilder::new(&srv.uri()).token("tok")).unwrap();
+    let mut p = Params::new();
+    p.insert("org".into(), 1i64.into());
+    let r = c.query_list("/api/users", &p, Some(&FuncSpecOptions { limit: Some(2), ..Default::default() })).await.unwrap();
+    assert_eq!(r.metadata.unwrap(), Metadata { total: 50, count: 2, filtered: 50, limit: 2, offset: 10 });
+    assert_eq!(r.data.as_array().unwrap().len(), 2);
+}
+
+#[tokio::test]
+async fn query_single_and_error() {
+    let srv = MockServer::start().await;
+    Mock::given(path("/api/ok")).respond_with(ResponseTemplate::new(200).set_body_json(json!({"id": 1}))).mount(&srv).await;
+    Mock::given(path("/api/bad")).respond_with(ResponseTemplate::new(400).set_body_json(json!({"success": false, "error": {"code": "hook_error", "message": "Hook execution failed", "detail": "authentication required"}}))).mount(&srv).await;
+    let c = FuncSpecClient::new(&srv.uri()).unwrap();
+    let r = c.query("api/ok", &Params::new(), None).await.unwrap();
+    assert!(r.metadata.is_none());
+    assert_eq!(r.data["id"], 1);
+    match c.query("api/bad", &Params::new(), None).await.unwrap_err() {
+        Error::Api { error, .. } => assert_eq!((error.code.as_str(), error.detail.as_deref()), ("hook_error", Some("authentication required"))),
+        e => panic!("{e:?}"),
+    }
+}