@voxgig/sdkgen 1.5.1 → 2.0.1

package/project/.sdk/tm/lua/utility/make_spec.lua

@@ -1,6 +1,7 @@
 -- ProjectName SDK utility: make_spec
 
 local vs = require("utility.struct.struct")
+local graphql = require("utility.graphql")
 local Spec = require("core.spec")
 
 local function make_spec_util(ctx)
@@ -53,8 +54,23 @@ local function make_spec_util(ctx)
   ctx.spec.params = utility.prepare_params(ctx)
   ctx.spec.query = utility.prepare_query(ctx)
   ctx.spec.headers = utility.prepare_headers(ctx)
-  ctx.spec.body = utility.prepare_body(ctx)
-  ctx.spec.path = utility.prepare_path(ctx)
+
+  if "graphql" == vs.getprop(ctx.point, "kind") then
+    -- 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.
+    ctx.spec.body = utility.graphql_body(ctx)
+    ctx.spec.path = ""
+    -- 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.
+    ctx.spec.query = {}
+    ctx.spec.headers["content-type"] = graphql.CONTENT_TYPE
+  else
+    ctx.spec.body = utility.prepare_body(ctx)
+    ctx.spec.path = utility.prepare_path(ctx)
+  end
 
   if ctx.ctrl.explain ~= nil then
     ctx.ctrl.explain["spec"] = ctx.spec

package/project/.sdk/tm/lua/utility/register.lua

@@ -26,6 +26,7 @@ local prepare_method = require("utility.prepare_method")
 local prepare_params = require("utility.prepare_params")
 local prepare_path = require("utility.prepare_path")
 local prepare_query = require("utility.prepare_query")
+local graphql = require("utility.graphql")
 local result_basic = require("utility.result_basic")
 local result_body = require("utility.result_body")
 local result_headers = require("utility.result_headers")
@@ -58,6 +59,8 @@ local function register_all(u)
   u.prepare_params = prepare_params
   u.prepare_path = prepare_path
   u.prepare_query = prepare_query
+  u.graphql_body = graphql.body
+  u.graphql_errors = graphql.errors
   u.result_basic = result_basic
   u.result_body = result_body
   u.result_headers = result_headers

package/project/.sdk/tm/ocaml/sdk_features.ml

@@ -643,6 +643,37 @@ let clienttrack_feature () : feature =
 (* paging                                                              *)
 (* ------------------------------------------------------------------ *)
 
+(* Relay pagination: the cursor is the `after` variable (or whatever the model
+ * named it), and the page size is `first`. *)
+let graphql_pre_request (options : value) (spec : spec) (point : value)
+    (paging : value) : unit =
+  match spec.sp_body with
+  | Map _ as body ->
+    let variables = match getp body "variables" with
+      | Map _ as m -> m
+      | _ -> let m = empty_map () in setp body "variables" m; m in
+
+    let after_var = opt_str options "afterVar" ~default:"after" in
+    let first_var = opt_str options "firstVar" ~default:"first" in
+
+    (* Only bind variables the operation actually declares, or the server
+     * rejects the document. *)
+    let declared = match getpath_s point "graphql.vars" with
+      | List r -> List.filter_map (fun v -> match getp v "name" with
+          | Str n -> Some n | _ -> None) !r
+      | _ -> [] in
+
+    (match getp paging "cursor" with
+     | Noval | Null -> ()
+     | c -> if List.mem after_var declared then setp variables after_var c);
+
+    (match getp options "limit" with
+     | Noval | Null -> ()
+     | lim ->
+       if List.mem first_var declared && is_nullish (getp variables first_var)
+       then setp variables first_var lim)
+  | _ -> ()
+
 let paging_feature () : feature =
   let options = ref (empty_map ()) in
   let f = { f_name = "paging"; f_version = "0.0.1"; f_active = true; f_options = Noval;
@@ -676,19 +707,27 @@ let paging_feature () : feature =
              let limit_param = opt_str !options "limitParam" ~default:"limit" in
              let cursor_param = opt_str !options "cursorParam" ~default:"cursor" in
              let paging = match ctx.c_ctrl.ctrl_paging with Map _ as m -> m | _ -> empty_map () in
-             (match getp paging "cursor" with
-              | Noval | Null ->
-                (match getp q page_param with
-                 | Noval ->
-                   let page = (match getp paging "page" with
-                       | Noval | Null -> (match getp !options "startPage" with Num n -> Num n | _ -> Num 1.)
-                       | p -> p) in
-                   setp q page_param page
-                 | _ -> ())
-              | c -> setp q cursor_param c);
-             (match getp !options "limit" with
-              | Noval | Null -> ()
-              | lim -> (match getp q limit_param with Noval -> setp q limit_param lim | _ -> ())))
+             (* GraphQL paginates through operation VARIABLES, not the query
+              * string. This hook runs after make_spec, so spec.sp_body already
+              * holds the { query, variables } envelope, and before
+              * make_fetch_def serialises it. *)
+             if get_str_d ctx.c_point "kind" "" = "graphql" then
+               graphql_pre_request !options spec ctx.c_point paging
+             else begin
+               (match getp paging "cursor" with
+                | Noval | Null ->
+                  (match getp q page_param with
+                   | Noval ->
+                     let page = (match getp paging "page" with
+                         | Noval | Null -> (match getp !options "startPage" with Num n -> Num n | _ -> Num 1.)
+                         | p -> p) in
+                     setp q page_param page
+                   | _ -> ())
+                | c -> setp q cursor_param c);
+               (match getp !options "limit" with
+                | Noval | Null -> ()
+                | lim -> (match getp q limit_param with Noval -> setp q limit_param lim | _ -> ()))
+             end)
         | "PreResult" ->
           (match ctx.c_result with
            | None -> ()
@@ -703,18 +742,56 @@ let paging_feature () : feature =
              (match header_ci headers "link" with
               | Noval | Null -> ()
               | l -> (match extract_next (vstr_of l) with Some n -> setp paging "next" (Str n) | None -> ()));
+             (* Relay connections carry the cursor in pageInfo, at the path
+              * the model recorded for this op. `explicit_more` is set when
+              * the server states hasMore outright, rather than leaving it to
+              * be inferred from the presence of a cursor. *)
+             let explicit_more = ref false in
+             let gqlpage = getpath_s ctx.c_point "graphql.page" in
+             (match gqlpage, body with
+              | Map _, Map _ ->
+                (* `connpath` locates the connection object inside the
+                 * response envelope (data.<field>); the cursor/more paths are
+                 * relative to it. *)
+                let connpath = get_str_d gqlpage "connpath" "" in
+                let conn =
+                  if connpath = "" then body
+                  else (match getpath_s body connpath with
+                        | Noval | Null -> body
+                        | sub -> sub) in
+                let cursorpath = get_str_d gqlpage "cursor" "" in
+                if cursorpath <> "" then
+                  (match getpath_s conn cursorpath with
+                   | Noval | Null -> ()
+                   | c -> setp paging "cursor" c);
+                let morepath = get_str_d gqlpage "more" "" in
+                if morepath <> "" then
+                  (match getpath_s conn morepath with
+                   | Bool b -> setp paging "hasMore" (Bool b); explicit_more := true
+                   | _ -> ())
+              | _ -> ());
              (match body with
               | Map _ ->
                 (match getp body "next" with Noval | Null -> () | n -> if is_nullish (getp paging "next") then setp paging "next" n);
                 (match getp body "cursor" with Noval | Null -> () | c -> setp paging "cursor" c);
                 (match getp body "nextCursor" with Noval | Null -> () | c -> setp paging "cursor" c);
-                (match getp body "hasMore" with Bool b -> setp paging "hasMore" (Bool b) | _ -> ())
+                (match getp body "hasMore" with
+                 | Bool b -> setp paging "hasMore" (Bool b); explicit_more := true
+                 | _ -> ())
               | _ -> ());
-             let hm = (getp paging "hasMore" = Bool true)
-                      || not (is_nullish (getp paging "next"))
-                      || not (is_nullish (getp paging "cursor"))
-                      || not (is_nullish (getp paging "nextPage")) in
-             setp paging "hasMore" (Bool hm);
+             (* 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 not !explicit_more then begin
+               let hm = (getp paging "hasMore" = Bool true)
+                        || not (is_nullish (getp paging "next"))
+                        || not (is_nullish (getp paging "cursor"))
+                        || not (is_nullish (getp paging "nextPage")) in
+               setp paging "hasMore" (Bool hm)
+             end;
              result.rt_paging <- paging;
              track_set (cc ctx) "paging" (jo [("last", paging)]))
         | _ -> ());
@@ -1090,7 +1167,24 @@ let prepare (client : sdk_client) (fetchargs : value) : value =
   (match u.u_prepare_auth ctx with (_, Some err) -> raise (Sdk_error_exc err) | _ -> ());
   (match u.u_make_fetch_def ctx with (_, Some err) -> raise (Sdk_error_exc err) | (fd, None) -> fd)
 
-let direct (client : sdk_client) (fetchargs : value) : value =
+(* Is this raw-access op permitted by the SDK's allow.op option? *)
+let op_allowed (client : sdk_client) (op : string) : bool =
+  match getpath_s client.cl_options "allow.op" with
+  | Str allow -> substr_contains allow op
+  | _ -> false
+
+let op_denied (client : sdk_client) (op : string) : value =
+  let allow = match getpath_s client.cl_options "allow.op" with
+    | Str s -> s | _ -> "" in
+  jo [("ok", Bool false);
+      ("err", Str ("ProjectNameSDK: " ^ op ^ ": operation not allowed by" ^
+                   " SDK option allow.op value: \"" ^ allow ^ "\""))]
+
+(* Ungated request path shared by direct and graphql, each of which checks its
+ * own allow.op token first. Separate, rather than a flag on fetchargs: a
+ * caller-supplied marker would let anyone opt straight back out of the gate
+ * by passing it. *)
+let raw_request (client : sdk_client) (fetchargs : value) : value =
   let u = client.cl_utility in
   let fetchargs = if is_noval fetchargs then empty_map () else fetchargs in
   match (try `Ok (prepare client fetchargs) with Sdk_error_exc e -> `Err e) with
@@ -1117,6 +1211,56 @@ let direct (client : sdk_client) (fetchargs : value) : value =
                ("headers", headers); ("data", json_data)]
          | _ -> jo [("ok", Bool false); ("err", err_to_value (ctx_make_error ctx "direct_invalid" "invalid response type"))]))
 
+(* 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. *)
+let direct (client : sdk_client) (fetchargs : value) : value =
+  if not (op_allowed client "direct") then op_denied client "direct"
+  else raw_request client fetchargs
+
+(* 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. *)
+let graphql (client : sdk_client) (query : string) (variables : value)
+    (ctrl : value) : value =
+  if not (op_allowed client "graphql") then op_denied client "graphql"
+  else begin
+    let vars = match variables with Map _ as m -> m | _ -> empty_map () in
+    let ctl = match ctrl with Map _ as m -> m | _ -> empty_map () in
+    let res = raw_request client (jo [
+      ("method", Str "POST");
+      ("headers", jo [("content-type", Str "application/json")]);
+      ("body", jo [("query", Str query); ("variables", vars)]);
+      ("ctrl", ctl)]) in
+
+    (* 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. *)
+    let errors = match getpath_s res "data.errors" with
+      | List r -> !r | _ -> [] in
+
+    (match errors with
+     | [] -> ()
+     | first :: _ ->
+       let msg = get_str_d first "message" "" in
+       let msg = if msg = "" then "graphql error" else msg in
+       setp res "ok" (Bool false);
+       setp res "err" (Str ("ProjectNameSDK: graphql: " ^ msg));
+       setp res "graphql" (lst errors));
+
+    res
+  end
+
 let sdk_test ~(config : value) ~(make_feature : string -> feature) (testopts : value) (sdkopts : value) : sdk_client =
   let sdkopts = match clone (if is_noval sdkopts then empty_map () else sdkopts) with Map _ as m -> m | _ -> empty_map () in
   let testopts = match clone (if is_noval testopts then empty_map () else testopts) with Map _ as m -> m | _ -> empty_map () in

package/project/.sdk/tm/ocaml/sdk_runtime.ml

@@ -416,6 +416,120 @@ let prepare_query_util (ctx : ctx) : value =
 let prepare_body_util (ctx : ctx) : value =
   if ctx.c_op.op_input = "data" then (cu ctx).u_transform_request ctx else Noval
 
+(* ---- graphql (transport) -------------------------------------------------
+ *
+ * GraphQL transport. API-INDEPENDENT: every GraphQL SDK this generator
+ * produces uses this code 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. *)
+let graphql_content_type = "application/json"
+
+(* 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`. *)
+let graphql_error_code (gqlerr : value) : string =
+  let ext = getp gqlerr "extensions" in
+  let code = get_str_d ext "code" "" in
+  let code = if code = "" then get_str_d ext "type" "" else code in
+  let raw = String.uppercase_ascii code in
+  if substr_contains raw "AUTH" || substr_contains raw "FORBIDDEN"
+     || substr_contains raw "UNAUTHENTICATED" then "request_auth"
+  else if substr_contains raw "RATELIMIT" || substr_contains raw "RATE_LIMIT"
+          || substr_contains raw "TOO_MANY" then "request_ratelimit"
+  else if substr_contains raw "BAD_USER_INPUT" || substr_contains raw "VALIDATION"
+          || substr_contains raw "INVALID" then "request_invalid"
+  else "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. *)
+let graphql_body_util (ctx : ctx) : value =
+  match getp ctx.c_point "graphql" with
+  | Map _ as gql ->
+    (* 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 datainput = ctx.c_op.op_input = "data" in
+    let reqsrc = if datainput then ctx.c_reqdata else ctx.c_reqmatch in
+    let datasrc = if datainput then ctx.c_data else ctx.c_match in
+    let reqsrc = match reqsrc with Map _ as m -> m | _ -> empty_map () in
+    let datasrc = match datasrc with Map _ as m -> m | _ -> empty_map () in
+    let variables = empty_map () in
+    let varlist = match getp gql "vars" with List r -> !r | _ -> [] in
+    List.iter (fun spec ->
+        match spec with
+        | Map _ ->
+          let name = get_str_d spec "name" "" in
+          let from = get_str_d spec "from" "" in
+          if name <> "" then begin
+            if from = "" then begin
+              (* The input object IS the request body. Strip the action
+               * selector, which is an SDK-side point discriminator, not an
+               * API field. *)
+              let body = empty_map () in
+              List.iter (fun k ->
+                  if k <> "$action" then setp body k (getp reqsrc k))
+                (keysof reqsrc);
+              setp variables name body
+            end
+            else
+              (* Only send variables the caller actually supplied: sending an
+               * explicit null would clear a field on many APIs. *)
+              let v = getp reqsrc from in
+              let v = if is_nullish v then getp datasrc from else v in
+              if not (is_nullish v) then setp variables name v
+          end
+        | _ -> ())
+      varlist;
+    jo [("query", getp gql "doc"); ("variables", variables)]
+  | _ -> Noval
+
+(* 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. *)
+let graphql_errors_util (ctx : ctx) : bool =
+  match ctx.c_result with
+  | None -> false
+  | Some result ->
+    if get_str_d ctx.c_point "kind" "" <> "graphql" then false
+    else
+      let errors = match getp result.rt_body "errors" with List r -> !r | _ -> [] in
+      let count = List.length errors in
+      if count = 0 then false
+      else begin
+        let first = List.hd errors in
+        let msg = get_str_d first "message" "" in
+        let msg = if msg = "" then "graphql error" else msg in
+        let msg =
+          if 1 < count then msg ^ " (+" ^ string_of_int (count - 1) ^ " more)"
+          else msg in
+        result.rt_err <-
+          Some (ctx_make_error ctx (graphql_error_code first) ("graphql: " ^ msg));
+        result.rt_ok <- false;
+        true
+      end
+
 let prepare_auth_util (ctx : ctx) : (spec option * sdk_error option) =
   match ctx.c_spec with
   | None -> (None, Some (ctx_make_error ctx "auth_no_spec" "Expected context spec property to be defined."))
@@ -584,8 +698,23 @@ let make_spec_util (ctx : ctx) : (spec option * sdk_error option) =
       sp.sp_params <- u.u_prepare_params ctx;
       sp.sp_query <- u.u_prepare_query ctx;
       sp.sp_headers <- u.u_prepare_headers ctx;
-      sp.sp_body <- u.u_prepare_body ctx;
-      sp.sp_path <- u.u_prepare_path ctx;
+      if get_str_d ctx.c_point "kind" "" = "graphql" then begin
+        (* 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. *)
+        sp.sp_body <- u.u_graphql_body ctx;
+        sp.sp_path <- "";
+        (* 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. *)
+        sp.sp_query <- empty_map ();
+        setp sp.sp_headers "content-type" (Str graphql_content_type)
+      end
+      else begin
+        sp.sp_body <- u.u_prepare_body ctx;
+        sp.sp_path <- u.u_prepare_path ctx
+      end;
       (match ctx.c_ctrl.ctrl_explain with Map _ -> setp ctx.c_ctrl.ctrl_explain "spec" (spec_to_value sp) | _ -> ());
       match u.u_prepare_auth ctx with
       | (_, Some err) -> (None, Some err)
@@ -687,7 +816,13 @@ let make_response_util (ctx : ctx) : (response option * sdk_error option) =
            | None -> (None, Some (ctx_make_error ctx "response_no_result" "Expected context result property to be defined."))
            | Some result ->
              spec.sp_step <- "response";
-             u.u_result_basic ctx; u.u_result_headers ctx; u.u_result_body ctx; ignore (u.u_transform_response ctx);
+             u.u_result_basic ctx; u.u_result_headers ctx; u.u_result_body 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. *)
+             ignore (u.u_graphql_errors ctx);
+             ignore (u.u_transform_response ctx);
              if result.rt_err = None then result.rt_ok <- true;
              (match ctx.c_ctrl.ctrl_explain with Map _ -> setp ctx.c_ctrl.ctrl_explain "result" (result_to_value result) | _ -> ());
              (Some response, None))))
@@ -763,7 +898,7 @@ let opt_spec_value () : value =
     ("auth", jo [("prefix", Str "")]);
     ("headers", jo [("`$CHILD`", Str "`$STRING`")]);
     ("allow", jo [("method", Str "GET,PUT,POST,PATCH,DELETE,OPTIONS");
-                  ("op", Str "create,update,load,list,remove,command,direct")]);
+                  ("op", Str "create,update,load,list,remove,command,direct,graphql")]);
     ("entity", jo [("`$CHILD`", jo [("`$OPEN`", Bool true); ("active", Bool false); ("alias", empty_map ())])]);
     ("feature", jo [("`$CHILD`", jo [("`$OPEN`", Bool true); ("active", Bool false)])]);
     ("utility", empty_map ());
@@ -898,6 +1033,8 @@ let new_utility () : utility =
     u_prepare_params = prepare_params_util;
     u_prepare_path = prepare_path_util;
     u_prepare_query = prepare_query_util;
+    u_graphql_body = graphql_body_util;
+    u_graphql_errors = graphql_errors_util;
     u_result_basic = result_basic_util;
     u_result_body = result_body_util;
     u_result_headers = result_headers_util;
@@ -932,6 +1069,8 @@ let register (u : utility) : unit =
   u.u_prepare_params <- prepare_params_util;
   u.u_prepare_path <- prepare_path_util;
   u.u_prepare_query <- prepare_query_util;
+  u.u_graphql_body <- graphql_body_util;
+  u.u_graphql_errors <- graphql_errors_util;
   u.u_result_basic <- result_basic_util;
   u.u_result_body <- result_body_util;
   u.u_result_headers <- result_headers_util;

package/project/.sdk/tm/ocaml/sdk_types.ml

@@ -152,6 +152,8 @@ and utility = {
   mutable u_prepare_params : ctx -> value;
   mutable u_prepare_path : ctx -> string;
   mutable u_prepare_query : ctx -> value;
+  mutable u_graphql_body : ctx -> value;
+  mutable u_graphql_errors : ctx -> bool;
   mutable u_result_basic : ctx -> unit;
   mutable u_result_body : ctx -> unit;
   mutable u_result_headers : ctx -> unit;

package/project/.sdk/tm/perl/feature/paging_feature.pm

@@ -64,6 +64,14 @@ sub PreRequest {
     $paging = $ctx->{ctrl}{paging};
   }
 
+  # 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.
+  if ('graphql' eq (ProjectNameHelpers::gp($ctx->{point}, 'kind') // '')) {
+    $self->_graphql_pre_request($ctx, $paging);
+    return;
+  }
+
   if (defined $paging->{cursor}) {
     $spec->{query}{$cursor_param} = $paging->{cursor};
   }
@@ -79,6 +87,45 @@ sub PreRequest {
   return;
 }
 
+# Relay pagination: the cursor is the `after` variable (or whatever the model
+# named it), and the page size is `first`.
+sub _graphql_pre_request {
+  my ($self, $ctx, $paging) = @_;
+
+  my $body = $ctx->{spec}{body};
+  return unless ref($body) eq 'HASH';
+
+  my $variables = $body->{variables};
+  unless (ref($variables) eq 'HASH') {
+    $variables = {};
+    $body->{variables} = $variables;
+  }
+
+  my $after_var = defined $self->{options}{afterVar} ? $self->{options}{afterVar} : 'after';
+  my $first_var = defined $self->{options}{firstVar} ? $self->{options}{firstVar} : 'first';
+
+  # Only bind variables the operation actually declares, or the server
+  # rejects the document.
+  my %declared;
+  my $varlist = ProjectNameHelpers::gpath($ctx->{point}, 'graphql.vars');
+  if (ref($varlist) eq 'ARRAY') {
+    for my $v (@$varlist) {
+      my $name = ProjectNameHelpers::gp($v, 'name');
+      $declared{$name} = 1 if defined $name;
+    }
+  }
+
+  if (defined $paging->{cursor} && $declared{$after_var}) {
+    $variables->{$after_var} = $paging->{cursor};
+  }
+
+  if (defined $self->{options}{limit} && !defined $variables->{$first_var}
+    && $declared{$first_var}) {
+    $variables->{$first_var} = $self->{options}{limit};
+  }
+  return;
+}
+
 sub PreResult {
   my ($self, $ctx) = @_;
   return unless $self->{active};
@@ -106,6 +153,39 @@ sub PreResult {
     }
   }
 
+  # Set when the response states hasMore outright, rather than leaving it to
+  # be inferred from the presence of a cursor.
+  my $explicit_more = 0;
+
+  # Relay connections carry the cursor in pageInfo, at the path the model
+  # recorded for this op.
+  my $page = ProjectNameHelpers::gpath($ctx->{point}, 'graphql.page');
+  if (ref($page) eq 'HASH' && Voxgig::Struct::ismap($body)) {
+    # `connpath` locates the connection object inside the response envelope
+    # (data.<field>); the cursor/more paths are relative to it.
+    my $conn = $body;
+    my $connpath = $page->{connpath};
+    if (defined $connpath && '' ne $connpath) {
+      my $sub = ProjectNameHelpers::gpath($body, $connpath);
+      $conn = $sub if defined $sub;
+    }
+
+    my $cursorpath = $page->{cursor};
+    if (defined $cursorpath && '' ne $cursorpath) {
+      my $cursor = ProjectNameHelpers::gpath($conn, $cursorpath);
+      $paging->{cursor} = $cursor if defined $cursor;
+    }
+
+    my $morepath = $page->{more};
+    if (defined $morepath && '' ne $morepath) {
+      my $more = ProjectNameHelpers::gpath($conn, $morepath);
+      if (ProjectNameHelpers::is_true($more) || ProjectNameHelpers::is_false($more)) {
+        $paging->{hasMore} = ProjectNameHelpers::is_true($more) ? 1 : 0;
+        $explicit_more = 1;
+      }
+    }
+  }
+
   # Body-level cursors.
   if (Voxgig::Struct::ismap($body)) {
     my $bnext = ProjectNameHelpers::gp($body, 'next');
@@ -118,12 +198,20 @@ sub PreResult {
     my $bhasmore = $body->{hasMore};
     if (ProjectNameHelpers::is_true($bhasmore) || ProjectNameHelpers::is_false($bhasmore)) {
       $paging->{hasMore} = ProjectNameHelpers::is_true($bhasmore) ? 1 : 0;
+      $explicit_more = 1;
     }
   }
 
-  $paging->{hasMore} = ($paging->{hasMore}
-    || defined $paging->{next} || defined $paging->{cursor}
-    || defined $paging->{nextPage}) ? 1 : 0;
+  # 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.
+  unless ($explicit_more) {
+    $paging->{hasMore} = ($paging->{hasMore}
+      || defined $paging->{next} || defined $paging->{cursor}
+      || defined $paging->{nextPage}) ? 1 : 0;
+  }
 
   $result->{paging} = $paging;