@voxgig/sdkgen 1.5.1 → 2.0.0

package/project/.sdk/tm/rust/feature/paging.rs

@@ -9,10 +9,12 @@
 // `cursorParam`), the page size (`limit`) and the start page (`startPage`,
 // default 1) are configurable.
 
+use std::cell::RefCell;
 use std::rc::Rc;
 
 use crate::core::context::Context;
-use crate::core::helpers::{get_bool, getp, setp};
+use crate::core::spec::Spec;
+use crate::core::helpers::{get_bool, getp, getpath, setp};
 use crate::core::types::Feature;
 use crate::feature::support::*;
 use crate::utility::voxgigstruct::Value;
@@ -27,6 +29,13 @@ pub struct PagingFeature {
     pub last: Value,
 }
 
+// The model records connection/cursor/more as dot paths; core::getpath takes
+// pre-split segments.
+fn getpath_dotted(path: &str, store: &Value) -> Value {
+    let segs: Vec<&str> = path.split('.').collect();
+    getpath(&segs, store)
+}
+
 impl PagingFeature {
     pub fn new() -> PagingFeature {
         PagingFeature {
@@ -38,6 +47,64 @@ impl PagingFeature {
         }
     }
 
+    // Relay pagination: the cursor is the `after` variable (or whatever the
+    // model named it), and the page size is `first`.
+    fn graphql_pre_request(
+        &self, spec: &Rc<RefCell<Spec>>, point: &Value, paging: &Value,
+    ) {
+        let body = spec.borrow().body.clone();
+        if !matches!(body, Value::Map(_)) {
+            return;
+        }
+
+        let variables = {
+            let v = getp(&body, "variables");
+            if matches!(v, Value::Map(_)) {
+                v
+            } else {
+                let nv = Value::empty_map();
+                setp(&body, "variables", nv.clone());
+                nv
+            }
+        };
+
+        let after_var = fopt_str(&self.options, "afterVar", "after");
+        let first_var = fopt_str(&self.options, "firstVar", "first");
+
+        // Only bind variables the operation actually declares, or the server
+        // rejects the document.
+        let mut declared: Vec<String> = Vec::new();
+        if let Value::List(varlist) = getpath(&["graphql", "vars"], point) {
+            for v in varlist.borrow().iter() {
+                if let Some(name) = getp(v, "name").as_str() {
+                    declared.push(name.to_string());
+                }
+            }
+        }
+
+        let cursor = getp(paging, "cursor");
+        if !cursor.is_noval() && !cursor.is_null()
+            && declared.iter().any(|d| *d == after_var)
+        {
+            setp(&variables, &after_var, cursor);
+        }
+
+        // `limit: null` reads as unset, matching the reference's `null !=
+        // limit`: fopt_int would otherwise coerce it to 0 and bind `first: 0`,
+        // which relay servers reject or answer with an empty page.
+        let limit = getp(&self.options, "limit");
+        if !limit.is_noval() && !limit.is_null()
+            && getp(&variables, &first_var).is_noval()
+            && declared.iter().any(|d| *d == first_var)
+        {
+            setp(
+                &variables,
+                &first_var,
+                Value::Num(fopt_int(&self.options, "limit", 0) as f64),
+            );
+        }
+    }
+
     fn is_list(&self, ctx: &Rc<Context>) -> bool {
         let opname = ctx.op.borrow().name.clone();
         let ops =
@@ -122,6 +189,16 @@ impl Feature for PagingFeature {
         // A per-call cursor/page from ctrl takes priority (auto-iteration).
         let paging = ctx.ctrl.borrow().borrow().paging.clone();
 
+        // GraphQL paginates through operation VARIABLES, not the query
+        // string. This hook runs after make_spec, so spec.body already holds
+        // the { query, variables } envelope, and before make_fetch_def
+        // serialises it.
+        let point = ctx.point.borrow().clone();
+        if Some("graphql") == getp(&point, "kind").as_str() {
+            self.graphql_pre_request(&spec, &point, &paging);
+            return;
+        }
+
         let cursor = getp(&paging, "cursor");
         if !cursor.is_noval() && !cursor.is_null() {
             setp(&query, &cursor_param, cursor);
@@ -176,6 +253,44 @@ impl Feature for PagingFeature {
             }
         }
 
+        // Set when the response states hasMore outright, rather than leaving
+        // it to be inferred from the presence of a cursor.
+        let mut explicit_more = false;
+
+        // Relay connections carry the cursor in pageInfo, at the path the
+        // model recorded for this op.
+        let point = ctx.point.borrow().clone();
+        let page = getpath(&["graphql", "page"], &point);
+        if matches!(page, Value::Map(_)) && matches!(body, Value::Map(_)) {
+            // `connpath` locates the connection object inside the response
+            // envelope (data.<field>); the cursor/more paths are relative
+            // to it.
+            let connpath = getp(&page, "connpath").as_str().unwrap_or("").to_string();
+            let mut conn = body.clone();
+            if !connpath.is_empty() {
+                let sub = getpath_dotted(&connpath, &body);
+                if !sub.is_noval() && !sub.is_null() {
+                    conn = sub;
+                }
+            }
+
+            let cursorpath = getp(&page, "cursor").as_str().unwrap_or("").to_string();
+            if !cursorpath.is_empty() {
+                let cursor = getpath_dotted(&cursorpath, &conn);
+                if !cursor.is_noval() && !cursor.is_null() {
+                    setp(&paging, "cursor", cursor);
+                }
+            }
+
+            let morepath = getp(&page, "more").as_str().unwrap_or("").to_string();
+            if !morepath.is_empty() {
+                if let Value::Bool(more) = getpath_dotted(&morepath, &conn) {
+                    setp(&paging, "hasMore", Value::Bool(more));
+                    explicit_more = true;
+                }
+            }
+        }
+
         // Body-level cursors.
         if let Value::Map(_) = body {
             let next = getp(&body, "next");
@@ -192,10 +307,17 @@ impl Feature for PagingFeature {
             }
             if let Some(has_more) = get_bool(&body, "hasMore") {
                 setp(&paging, "hasMore", Value::Bool(has_more));
+                explicit_more = true;
             }
         }
 
-        if get_bool(&paging, "hasMore") != Some(true)
+        // Cursor presence only INFERS another page. When the server stated
+        // the answer outright — relay's `hasNextPage: false`, or a body
+        // `hasMore` — that wins: a final page normally carries both an end
+        // cursor and hasNextPage false, and inferring from the cursor there
+        // would send the caller back for a page that does not exist, forever.
+        if !explicit_more
+            && get_bool(&paging, "hasMore") != Some(true)
             && (!getp(&paging, "next").is_noval()
                 || !getp(&paging, "cursor").is_noval()
                 || !getp(&paging, "nextPage").is_noval())

package/project/.sdk/tm/rust/utility/graphql.rs

@@ -0,0 +1,193 @@
+use std::rc::Rc;
+
+use crate::core::context::Context;
+use crate::core::helpers::{getp, setp};
+use crate::utility::voxgigstruct::Value;
+
+// GraphQL transport. API-INDEPENDENT: every GraphQL SDK this generator
+// produces uses this file unchanged. The API-specific part — which
+// operations exist and what each one's document is — is model data,
+// computed once by apidef and emitted into Config.
+//
+// Two jobs:
+//
+//   graphql_body_util   — build { query, variables } for a point, binding
+//                         the op's arguments to the document's declared
+//                         variables.
+//
+//   graphql_errors_util — lift a GraphQL failure into an SDK error.
+//                         GraphQL reports failures as a top-level `errors`
+//                         array under HTTP 200, so the status-driven path
+//                         in result_basic never sees them.
+
+/// Content type every GraphQL-over-HTTP request uses.
+pub const GRAPHQL_CONTENT_TYPE: &str = "application/json";
+
+fn as_str(v: &Value) -> String {
+    match v {
+        Value::Str(s) => s.clone(),
+        _ => String::new(),
+    }
+}
+
+/// Map a GraphQL error to the same error codes the HTTP path produces, so
+/// a caller handles auth or rate limiting identically on both transports.
+/// Servers put the machine-readable code in `extensions.code`;
+/// Linear-style APIs use `extensions.type`.
+pub fn graphql_error_code(gqlerr: &Value) -> &'static str {
+    let ext = getp(gqlerr, "extensions");
+
+    let mut raw = as_str(&getp(&ext, "code"));
+    if raw.is_empty() {
+        raw = as_str(&getp(&ext, "type"));
+    }
+    let raw = raw.to_uppercase();
+
+    if raw.contains("AUTH") || raw.contains("FORBIDDEN")
+        || raw.contains("UNAUTHENTICATED")
+    {
+        return "request_auth";
+    }
+    if raw.contains("RATELIMIT") || raw.contains("RATE_LIMIT")
+        || raw.contains("TOO_MANY")
+    {
+        return "request_ratelimit";
+    }
+    if raw.contains("BAD_USER_INPUT") || raw.contains("VALIDATION")
+        || raw.contains("INVALID")
+    {
+        return "request_invalid";
+    }
+
+    "request_graphql"
+}
+
+/// Build the request body for a GraphQL point.
+///
+/// Variables come from the op's own arguments: a named variable binds to
+/// the like-named argument (`from`), and the input-object variable (empty
+/// `from`) takes the request data as a whole — which is what makes a
+/// generated create/update call look exactly like its REST equivalent.
+pub fn graphql_body_util(ctx: &Rc<Context>) -> Value {
+    let point = ctx.point.borrow().clone();
+    let gql = getp(&point, "graphql");
+
+    if !matches!(gql, Value::Map(_)) {
+        return Value::Noval;
+    }
+
+    // reqmatch/reqdata hold the caller's arguments for THIS call; data/match
+    // hold the entity's current state. Which pair depends on whether the op
+    // takes match or data input. A named variable falls back to the current
+    // state, so updating a loaded entity with just {title} still binds the
+    // stored id the mutation requires.
+    let op = ctx.op.borrow().clone();
+    let (reqsrc, datasrc) = if op.input == "data" {
+        (ctx.reqdata.borrow().clone(), ctx.data.borrow().clone())
+    } else {
+        (ctx.reqmatch.borrow().clone(), ctx.mtch.borrow().clone())
+    };
+    let reqsrc = match reqsrc {
+        Value::Map(m) => Value::Map(m),
+        _ => Value::empty_map(),
+    };
+    let datasrc = match datasrc {
+        Value::Map(m) => Value::Map(m),
+        _ => Value::empty_map(),
+    };
+
+    let variables = Value::empty_map();
+
+    if let Value::List(varlist) = getp(&gql, "vars") {
+        let specs: Vec<Value> = varlist.borrow().iter().cloned().collect();
+
+        for spec in specs {
+            let name = as_str(&getp(&spec, "name"));
+            let from = as_str(&getp(&spec, "from"));
+
+            if from.is_empty() {
+                // The input object IS the request body. Strip the action
+                // selector, which is an SDK-side point discriminator, not
+                // an API field.
+                let body = Value::empty_map();
+                if let Value::Map(src) = &reqsrc {
+                    let entries: Vec<(String, Value)> = src
+                        .borrow()
+                        .iter()
+                        .map(|(k, v)| (k.clone(), v.clone()))
+                        .collect();
+                    for (k, v) in entries {
+                        if "$action" != k {
+                            setp(&body, &k, v);
+                        }
+                    }
+                }
+                setp(&variables, &name, body);
+                continue;
+            }
+
+            // Only send variables the caller actually supplied: sending an
+            // explicit null would clear a field on many APIs.
+            let mut val = getp(&reqsrc, &from);
+            if val.is_noval() || val.is_null() {
+                val = getp(&datasrc, &from);
+            }
+            if !val.is_noval() && !val.is_null() {
+                setp(&variables, &name, val);
+            }
+        }
+    }
+
+    let out = Value::empty_map();
+    setp(&out, "query", getp(&gql, "doc"));
+    setp(&out, "variables", variables);
+
+    out
+}
+
+/// Inspect a decoded GraphQL response body and record a failure when the
+/// server reported one. Returns true when an error was recorded.
+///
+/// Partial data (`data` alongside `errors`) is treated as failure: the
+/// REST surface has no partial-success concept, and silently returning
+/// half an object would be worse than failing. The raw envelope stays
+/// available on the result for callers that need it.
+pub fn graphql_errors_util(ctx: &Rc<Context>) -> bool {
+    let point = ctx.point.borrow().clone();
+
+    if as_str(&getp(&point, "kind")) != "graphql" {
+        return false;
+    }
+
+    let result = match ctx.result.borrow().clone() {
+        Some(r) => r,
+        None => return false,
+    };
+
+    let body = result.borrow().body.clone();
+    let errors: Vec<Value> = match getp(&body, "errors") {
+        Value::List(l) => l.borrow().iter().cloned().collect(),
+        _ => return false,
+    };
+
+    if errors.is_empty() {
+        return false;
+    }
+
+    let first = errors[0].clone();
+    let mut msg = as_str(&getp(&first, "message"));
+    if msg.is_empty() {
+        msg = "graphql error".to_string();
+    }
+    if 1 < errors.len() {
+        msg = format!("{} (+{} more)", msg, errors.len() - 1);
+    }
+
+    let err = ctx.make_error(graphql_error_code(&first), &format!("graphql: {}", msg));
+
+    let mut r = result.borrow_mut();
+    r.err = Some(err);
+    r.ok = false;
+
+    true
+}

package/project/.sdk/tm/rust/utility/make_options.rs

@@ -64,7 +64,7 @@ pub fn make_options_util(ctx: &Rc<Context>) -> Value {
             "allow",
             jo(vec![
                 ("method", Value::str("GET,PUT,POST,PATCH,DELETE,OPTIONS")),
-                ("op", Value::str("create,update,load,list,remove,command,direct")),
+                ("op", Value::str("create,update,load,list,remove,command,direct,graphql")),
             ]),
         ),
         (

package/project/.sdk/tm/rust/utility/make_response.rs

@@ -35,6 +35,12 @@ pub fn make_response_util(
     crate::utility::result_basic::result_basic_util(ctx);
     crate::utility::result_headers::result_headers_util(ctx);
     crate::utility::result_body::result_body_util(ctx);
+
+    // GraphQL reports failures as a top-level `errors` array under HTTP
+    // 200, so result_basic's status check never sees them. Lift them here,
+    // before the response transform tries to unwrap data that is not there.
+    crate::utility::graphql::graphql_errors_util(ctx);
+
     crate::utility::transform_response::transform_response_util(ctx);
 
     {

package/project/.sdk/tm/rust/utility/make_spec.rs

@@ -50,10 +50,38 @@ pub fn make_spec_util(ctx: &Rc<Context>) -> Result<Rc<RefCell<Spec>>, ProjectNam
     spec.borrow_mut().query = query;
     let headers = crate::utility::prepare_headers::prepare_headers_util(ctx);
     spec.borrow_mut().headers = headers;
-    let body = crate::utility::prepare_body::prepare_body_util(ctx);
-    spec.borrow_mut().body = body;
-    let path = crate::utility::prepare_path::prepare_path_util(ctx);
-    spec.borrow_mut().path = path;
+
+    let point = ctx.point.borrow().clone();
+    let kind = match getp(&point, "kind") {
+        Value::Str(s) => s,
+        _ => String::new(),
+    };
+
+    if "graphql" == kind {
+        // GraphQL addresses one endpoint: no path parts, no query string,
+        // and the body carries the operation. prepare_body is skipped
+        // deliberately — it only emits a body for data-input ops, whereas
+        // every GraphQL op posts one, including load/list/remove.
+        let body = crate::utility::graphql::graphql_body_util(ctx);
+        spec.borrow_mut().body = body;
+        spec.borrow_mut().path = String::new();
+        // prepare_query already copied the op's match arguments into the
+        // query string. Those same values are bound as operation
+        // variables, so leaving them would send /graphql?id=i1.
+        spec.borrow_mut().query = Value::empty_map();
+        let headers = spec.borrow().headers.clone();
+        setp(
+            &headers,
+            "content-type",
+            Value::Str(crate::utility::graphql::GRAPHQL_CONTENT_TYPE.to_string()),
+        );
+        spec.borrow_mut().headers = headers;
+    } else {
+        let body = crate::utility::prepare_body::prepare_body_util(ctx);
+        spec.borrow_mut().body = body;
+        let path = crate::utility::prepare_path::prepare_path_util(ctx);
+        spec.borrow_mut().path = path;
+    }
 
     {
         let ctrl = ctx.ctrl.borrow().clone();

package/project/.sdk/tm/rust/utility/mod.rs

@@ -28,6 +28,7 @@ pub mod prepare_headers;
 pub mod prepare_method;
 pub mod prepare_params;
 pub mod prepare_path;
+pub mod graphql;
 pub mod prepare_query;
 pub mod result_basic;
 pub mod result_body;

package/project/.sdk/tm/scala/core/SdkClient.scala

@@ -133,7 +133,97 @@ abstract class SdkClient(options0: JMap[String, Object]) {
     utility.makeFetchDef(ctx)
   }
 
+  // Raw endpoint access is operator-controllable, like every entity op.
+  // Blocking it means denying BOTH the 'direct' and 'graphql' tokens, since
+  // either one reaches the same endpoint.
   def direct(fetchargs0: JMap[String, Object]): JMap[String, Object] = {
+    if (!opAllowed("direct")) opDenied("direct")
+    else rawRequest(fetchargs0)
+  }
+
+  // Is this raw-access op permitted by the SDK's allow.op option?
+  private def opAllowed(op: String): Boolean =
+    Struct.getpath(this.options, java.util.List.of("allow", "op")) match {
+      case s: String => s.contains(op)
+      case _ => false
+    }
+
+  private def opDenied(op: String): JMap[String, Object] = {
+    val allow = Struct.getpath(this.options, java.util.List.of("allow", "op")) match {
+      case s: String => s
+      case _ => ""
+    }
+    val out = new LinkedHashMap[String, Object]()
+    out.put("ok", java.lang.Boolean.FALSE)
+    out.put("err", new SdkError(op + "_allow",
+      "ProjectNameSDK: " + op + ": operation not allowed by" +
+        " SDK option allow.op value: \"" + allow + "\"", null))
+    out
+  }
+
+  // Raw GraphQL access: the pressure valve that makes the generated surface's
+  // deliberate omissions (per-call selection sets, typed filter builders,
+  // batching, subscriptions) livable — the whole schema stays reachable.
+  //
+  // Thin wrapper over the same prepare/fetch path direct uses, with the one
+  // thing raw direct cannot do for GraphQL: a GraphQL failure rides HTTP 200
+  // as a top-level `errors` array, so status alone would report a failed
+  // query as ok.
+  //
+  // NOTE: like direct, this bypasses the feature pipeline — no retry,
+  // ratelimit or paging features apply.
+  def graphql(
+    query: String,
+    variables: JMap[String, Object] = null,
+    ctrl: JMap[String, Object] = null,
+  ): JMap[String, Object] = {
+    if (!opAllowed("graphql")) opDenied("graphql")
+    else {
+      val headers = new LinkedHashMap[String, Object]()
+      headers.put("content-type", "application/json")
+
+      val body = new LinkedHashMap[String, Object]()
+      body.put("query", query)
+      body.put("variables",
+        if (variables == null) new LinkedHashMap[String, Object]() else variables)
+
+      val fetchargs = new LinkedHashMap[String, Object]()
+      fetchargs.put("method", "POST")
+      fetchargs.put("headers", headers)
+      fetchargs.put("body", body)
+      fetchargs.put("ctrl",
+        if (ctrl == null) new LinkedHashMap[String, Object]() else ctrl)
+
+      val res = rawRequest(fetchargs)
+
+      // Errors are read BEFORE any status check: a GraphQL parse or
+      // validation failure comes back as HTTP 400 carrying the standard
+      // { errors: [...] } body, and the raw path represents a non-2xx as
+      // ok:false with no err — so returning early on status would discard
+      // the server's own diagnostics, which are the only useful part of that
+      // response.
+      Struct.getpath(res, java.util.List.of("data", "errors")) match {
+        case errors: JList[_] if !errors.isEmpty =>
+          val msg = Struct.getprop(errors.get(0), "message") match {
+            case m: String if m.nonEmpty => m
+            case _ => "graphql error"
+          }
+          res.put("ok", java.lang.Boolean.FALSE)
+          res.put("err", new SdkError("graphql_error",
+            "ProjectNameSDK: graphql: " + msg, null))
+          res.put("graphql", errors.asInstanceOf[Object])
+        case _ =>
+      }
+
+      res
+    }
+  }
+
+  // Ungated request path shared by direct and graphql, each of which checks
+  // its own allow.op token first. Private, rather than a flag on fetchargs: a
+  // caller-supplied marker would let anyone opt straight back out of the gate
+  // by passing it.
+  private def rawRequest(fetchargs0: JMap[String, Object]): JMap[String, Object] = {
     val utility = this.utility
     val fetchargs = if (fetchargs0 == null) new LinkedHashMap[String, Object]() else fetchargs0
 

package/project/.sdk/tm/scala/core/Utility.scala

@@ -31,6 +31,8 @@ class Utility private (noregister: Boolean) {
   var prepareParams: CtxFn[JMap[String, Object]] = null
   var preparePath: CtxFn[String] = null
   var prepareQuery: CtxFn[JMap[String, Object]] = null
+  var graphqlBody: CtxFn[Object] = null
+  var graphqlErrors: CtxFn[java.lang.Boolean] = null
   var resultBasic: CtxFn[Result] = null
   var resultBody: CtxFn[Result] = null
   var resultHeaders: CtxFn[Result] = null
@@ -74,6 +76,8 @@ class Utility private (noregister: Boolean) {
     u.prepareParams = this.prepareParams
     u.preparePath = this.preparePath
     u.prepareQuery = this.prepareQuery
+    u.graphqlBody = this.graphqlBody
+    u.graphqlErrors = this.graphqlErrors
     u.resultBasic = this.resultBasic
     u.resultBody = this.resultBody
     u.resultHeaders = this.resultHeaders