@voxgig/sdkgen 1.5.0 → 2.0.0

package/project/.sdk/tm/go/feature/paging_feature.go

@@ -3,6 +3,8 @@ package feature
 import (
 	"regexp"
 
+	vs "github.com/voxgig/struct"
+
 	"GOMODULE/core"
 )
 
@@ -64,6 +66,14 @@ func (f *PagingFeature) PreRequest(ctx *core.Context) {
 		paging = ctx.Ctrl.Paging
 	}
 
+	// GraphQL paginates through operation VARIABLES, not the query string.
+	// This hook runs after makeSpec, so spec.Body already holds the
+	// { query, variables } envelope, and before makeFetchDef serialises it.
+	if kind, _ := vs.GetProp(ctx.Point, "kind").(string); kind == "graphql" {
+		f.graphqlPreRequest(ctx, paging)
+		return
+	}
+
 	if cursor, has := paging["cursor"]; has && cursor != nil {
 		spec.Query[cursorParam] = cursor
 	} else if spec.Query[pageParam] == nil {
@@ -79,6 +89,43 @@ func (f *PagingFeature) PreRequest(ctx *core.Context) {
 	}
 }
 
+// Relay pagination: the cursor is the `after` variable (or whatever the
+// model named it), and the page size is `first`.
+func (f *PagingFeature) graphqlPreRequest(ctx *core.Context, paging map[string]any) {
+	body, ok := ctx.Spec.Body.(map[string]any)
+	if !ok {
+		return
+	}
+
+	vars, ok := body["variables"].(map[string]any)
+	if !ok {
+		vars = map[string]any{}
+		body["variables"] = vars
+	}
+
+	afterVar := foptStr(f.options, "afterVar", "after")
+	firstVar := foptStr(f.options, "firstVar", "first")
+
+	// Only bind variables the operation actually declares, or the server
+	// rejects the document.
+	declared := map[string]bool{}
+	if varlist, ok := vs.GetPath([]any{"graphql", "vars"}, ctx.Point).([]any); ok {
+		for _, v := range varlist {
+			if name, ok := vs.GetProp(v, "name").(string); ok {
+				declared[name] = true
+			}
+		}
+	}
+
+	if cursor, has := paging["cursor"]; has && cursor != nil && declared[afterVar] {
+		vars[afterVar] = cursor
+	}
+
+	if f.options["limit"] != nil && vars[firstVar] == nil && declared[firstVar] {
+		vars[firstVar] = foptInt(f.options, "limit", 0)
+	}
+}
+
 func (f *PagingFeature) PreResult(ctx *core.Context) {
 	if !f.Active || !f.isList(ctx) {
 		return
@@ -107,6 +154,39 @@ func (f *PagingFeature) PreResult(ctx *core.Context) {
 		}
 	}
 
+	// Set when the response states hasMore outright, rather than leaving it
+	// to be inferred from the presence of a cursor.
+	explicitMore := false
+
+	// Relay connections carry the cursor in pageInfo, at the path the model
+	// recorded for this op.
+	page := vs.GetPath([]any{"graphql", "page"}, ctx.Point)
+	if pm, ok := page.(map[string]any); ok {
+		if _, isMap := body.(map[string]any); isMap {
+			// `connpath` locates the connection object inside the response
+			// envelope (data.<field>); the cursor/more paths are relative
+			// to it.
+			conn := body
+			if cp, ok := pm["connpath"].(string); ok && cp != "" {
+				if sub := vs.GetPath(cp, body); sub != nil {
+					conn = sub
+				}
+			}
+
+			if cp, ok := pm["cursor"].(string); ok && cp != "" {
+				if cursor := vs.GetPath(cp, conn); cursor != nil {
+					paging["cursor"] = cursor
+				}
+			}
+			if mp, ok := pm["more"].(string); ok && mp != "" {
+				if more, ok := vs.GetPath(mp, conn).(bool); ok {
+					paging["hasMore"] = more
+					explicitMore = true
+				}
+			}
+		}
+	}
+
 	// Body-level cursors.
 	if bm, ok := body.(map[string]any); ok {
 		if bm["next"] != nil && paging["next"] == nil {
@@ -120,10 +200,16 @@ func (f *PagingFeature) PreResult(ctx *core.Context) {
 		}
 		if hasMore, ok := bm["hasMore"].(bool); ok {
 			paging["hasMore"] = hasMore
+			explicitMore = true
 		}
 	}
 
-	if paging["hasMore"] != 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 !explicitMore && paging["hasMore"] != true &&
 		(paging["next"] != nil || paging["cursor"] != nil || paging["nextPage"] != nil) {
 		paging["hasMore"] = true
 	}

package/project/.sdk/tm/go/utility/graphql.go

@@ -0,0 +1,168 @@
+package utility
+
+import (
+	"strconv"
+	"strings"
+
+	vs "github.com/voxgig/struct"
+
+	"GOMODULE/core"
+)
+
+// 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:
+//
+//	GraphqlBody   — build { query, variables } for a point, binding the
+//	                op's arguments to the document's declared variables.
+//
+//	GraphqlErrors — 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 resultBasic
+//	                never sees them.
+
+// Content type every GraphQL-over-HTTP request uses.
+const GraphqlContentType = "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`.
+func graphqlErrorCodeUtil(gqlerr any) string {
+	ext, _ := vs.GetProp(gqlerr, "extensions").(map[string]any)
+
+	raw, _ := vs.GetProp(ext, "code").(string)
+	if raw == "" {
+		raw, _ = vs.GetProp(ext, "type").(string)
+	}
+	raw = strings.ToUpper(raw)
+
+	if strings.Contains(raw, "AUTH") || strings.Contains(raw, "FORBIDDEN") ||
+		strings.Contains(raw, "UNAUTHENTICATED") {
+		return "request_auth"
+	}
+	if strings.Contains(raw, "RATELIMIT") || strings.Contains(raw, "RATE_LIMIT") ||
+		strings.Contains(raw, "TOO_MANY") {
+		return "request_ratelimit"
+	}
+	if strings.Contains(raw, "BAD_USER_INPUT") || strings.Contains(raw, "VALIDATION") ||
+		strings.Contains(raw, "INVALID") {
+		return "request_invalid"
+	}
+
+	return "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.
+func graphqlBodyUtil(ctx *core.Context) any {
+	gql, _ := vs.GetProp(ctx.Point, "graphql").(map[string]any)
+	if gql == nil {
+		return nil
+	}
+
+	// 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.
+	reqsrc, datasrc := ctx.Reqmatch, ctx.Match
+	if ctx.Op != nil && ctx.Op.Input == "data" {
+		reqsrc, datasrc = ctx.Reqdata, ctx.Data
+	}
+	if reqsrc == nil {
+		reqsrc = map[string]any{}
+	}
+	if datasrc == nil {
+		datasrc = map[string]any{}
+	}
+
+	variables := map[string]any{}
+
+	varlist, _ := vs.GetProp(gql, "vars").([]any)
+	for _, v := range varlist {
+		spec, _ := v.(map[string]any)
+		if spec == nil {
+			continue
+		}
+
+		name, _ := vs.GetProp(spec, "name").(string)
+		from, _ := vs.GetProp(spec, "from").(string)
+
+		if from == "" {
+			// The input object IS the request body. Strip the action
+			// selector, which is an SDK-side point discriminator, not an
+			// API field.
+			body := map[string]any{}
+			for k, val := range reqsrc {
+				if k != "$action" {
+					body[k] = val
+				}
+			}
+			variables[name] = body
+			continue
+		}
+
+		// Only send variables the caller actually supplied: sending an
+		// explicit null would clear a field on many APIs.
+		val := vs.GetProp(reqsrc, from)
+		if val == nil {
+			val = vs.GetProp(datasrc, from)
+		}
+		if val != nil {
+			variables[name] = val
+		}
+	}
+
+	doc, _ := vs.GetProp(gql, "doc").(string)
+
+	return map[string]any{
+		"query":     doc,
+		"variables": variables,
+	}
+}
+
+// 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.
+func graphqlErrorsUtil(ctx *core.Context) bool {
+	if ctx.Result == nil || ctx.Point == nil {
+		return false
+	}
+
+	kind, _ := vs.GetProp(ctx.Point, "kind").(string)
+	if kind != "graphql" {
+		return false
+	}
+
+	errlist, _ := vs.GetProp(ctx.Result.Body, "errors").([]any)
+	if len(errlist) == 0 {
+		return false
+	}
+
+	first := errlist[0]
+	msg, _ := vs.GetProp(first, "message").(string)
+	if msg == "" {
+		msg = "graphql error"
+	}
+	if len(errlist) > 1 {
+		msg = msg + " (+" + strconv.Itoa(len(errlist)-1) + " more)"
+	}
+
+	ctx.Result.Err = ctx.MakeError(graphqlErrorCodeUtil(first), "graphql: "+msg)
+	ctx.Result.Ok = false
+
+	return true
+}
+

package/project/.sdk/tm/go/utility/make_options.go

@@ -86,7 +86,7 @@ func makeOptionsUtil(ctx *core.Context) map[string]any {
 		},
 		"allow": map[string]any{
 			"method": "GET,PUT,POST,PATCH,DELETE,OPTIONS",
-			"op":     "create,update,load,list,remove,command,direct",
+			"op":     "create,update,load,list,remove,command,direct,graphql",
 		},
 		"entity": map[string]any{
 			"`$CHILD`": map[string]any{

package/project/.sdk/tm/go/utility/make_response.go

@@ -32,6 +32,12 @@ func makeResponseUtil(ctx *core.Context) (*core.Response, error) {
 	utility.ResultBasic(ctx)
 	utility.ResultHeaders(ctx)
 	utility.ResultBody(ctx)
+
+	// GraphQL reports failures as a top-level `errors` array under HTTP
+	// 200, so ResultBasic's status check never sees them. Lift them here,
+	// before the response transform tries to unwrap data that is not there.
+	utility.GraphqlErrors(ctx)
+
 	utility.TransformResponse(ctx)
 
 	if result.Err == nil {

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

@@ -51,8 +51,25 @@ func makeSpecUtil(ctx *core.Context) (*core.Spec, error) {
 	ctx.Spec.Params = utility.PrepareParams(ctx)
 	ctx.Spec.Query = utility.PrepareQuery(ctx)
 	ctx.Spec.Headers = utility.PrepareHeaders(ctx)
-	ctx.Spec.Body = utility.PrepareBody(ctx)
-	ctx.Spec.Path = utility.PreparePath(ctx)
+
+	kind, _ := vs.GetProp(point, "kind").(string)
+
+	if kind == "graphql" {
+		// GraphQL addresses one endpoint: no path parts, no query string,
+		// and the body carries the operation. PrepareBody 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.GraphqlBody(ctx)
+		ctx.Spec.Path = ""
+		// PrepareQuery 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 = map[string]any{}
+		ctx.Spec.Headers["content-type"] = GraphqlContentType
+	} else {
+		ctx.Spec.Body = utility.PrepareBody(ctx)
+		ctx.Spec.Path = utility.PreparePath(ctx)
+	}
 
 	if ctx.Ctrl.Explain != nil {
 		ctx.Ctrl.Explain["spec"] = ctx.Spec

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

@@ -31,6 +31,8 @@ func registerAll(u *core.Utility) {
 	u.PrepareParams = prepareParamsUtil
 	u.PreparePath = preparePathUtil
 	u.PrepareQuery = prepareQueryUtil
+	u.GraphqlBody = graphqlBodyUtil
+	u.GraphqlErrors = graphqlErrorsUtil
 	u.ResultBasic = resultBasicUtil
 	u.ResultBody = resultBodyUtil
 	u.ResultHeaders = resultHeadersUtil

package/project/.sdk/tm/haskell/src/SdkFeatures.hs

@@ -672,8 +672,14 @@ pagingFeature = do
                 opts <- readIORef options
                 pageParam <- optStr opts "pageParam" "page"; limitParam <- optStr opts "limitParam" "limit"; cursorParam <- optStr opts "cursorParam" "cursor"
                 ctrl <- readIORef (cCtrl ctx); pgv <- getp ctrl "paging"; let paging = case pgv of { VMap _ -> pgv; _ -> VNoval }
+                -- GraphQL paginates through operation VARIABLES, not the
+                -- query string. This hook runs after makeSpec, so spec.body
+                -- already holds the { query, variables } envelope, and before
+                -- makeFetchDef serialises it.
+                point <- readIORef (cPoint ctx)
+                kind <- getStrD point "kind" ""
                 cur <- case paging of VMap _ -> getp paging "cursor"; _ -> pure VNoval
-                case cur of
+                if kind == "graphql" then graphqlPreRequest opts specV point paging else case cur of
                   VNoval -> do
                     pv <- getp q pageParam
                     case pv of
@@ -688,8 +694,9 @@ pagingFeature = do
                       VNoval -> do sp <- getp opts "startPage"; setp q pageParam (case sp of VNum n -> VNum n; _ -> VNum 1)
                       _ -> pure ()
                   c -> setp q cursorParam c
-                lim <- getp opts "limit"
-                case lim of VNoval -> pure (); VNull -> pure (); _ -> do lv <- getp q limitParam; case lv of VNoval -> setp q limitParam lim; _ -> pure ()
+                when (kind /= "graphql") $ do
+                  lim <- getp opts "limit"
+                  case lim of VNoval -> pure (); VNull -> pure (); _ -> do lv <- getp q limitParam; case lv of VNoval -> setp q limitParam lim; _ -> pure ()
               _ -> pure ()
           "PreResult" -> do
             rv <- readIORef (cResult ctx)
@@ -704,16 +711,49 @@ pagingFeature = do
                 paging <- jo [("page", xpage), ("totalCount", xtot), ("nextPage", xnext), ("next", VNoval), ("cursor", VNoval), ("hasMore", VBool False)]
                 lnk <- headerCI headersM "link"
                 case lnk of VNoval -> pure (); VNull -> pure (); _ -> case extractNext (vstring lnk) of Just nx -> setp paging "next" (VStr nx); Nothing -> pure ()
-                case body of
+                -- Relay connections carry the cursor in pageInfo, at the
+                -- path the model recorded for this op. `explicitMore` is set
+                -- when the server states hasMore outright, rather than
+                -- leaving it to be inferred from the presence of a cursor.
+                point <- readIORef (cPoint ctx)
+                gqlpage <- getpathS point "graphql.page"
+                relayMore <- case (gqlpage, body) of
+                  (VMap _, VMap _) -> do
+                    -- `connpath` locates the connection object inside the
+                    -- response envelope (data.<field>); the cursor/more paths
+                    -- are relative to it.
+                    connpath <- getStrD gqlpage "connpath" ""
+                    conn <- if null connpath then pure body else do
+                      sub <- getpathS body connpath
+                      pure (if isNullish sub then body else sub)
+                    cursorpath <- getStrD gqlpage "cursor" ""
+                    when (not (null cursorpath)) $ do
+                      c <- getpathS conn cursorpath
+                      when (not (isNullish c)) (setp paging "cursor" c)
+                    morepath <- getStrD gqlpage "more" ""
+                    if null morepath then pure False else do
+                      mv <- getpathS conn morepath
+                      case mv of
+                        VBool mb -> do setp paging "hasMore" (VBool mb); pure True
+                        _ -> pure False
+                  _ -> pure False
+                bodyMore <- case body of
                   VMap _ -> do
                     bn <- getp body "next"; case bn of VNoval -> pure (); VNull -> pure (); _ -> do cn <- getp paging "next"; when (isNullish cn) (setp paging "next" bn)
                     bc <- getp body "cursor"; case bc of VNoval -> pure (); VNull -> pure (); _ -> setp paging "cursor" bc
                     bnc <- getp body "nextCursor"; case bnc of VNoval -> pure (); VNull -> pure (); _ -> setp paging "cursor" bnc
-                    bhm <- getp body "hasMore"; case bhm of VBool bb -> setp paging "hasMore" (VBool bb); _ -> pure ()
-                  _ -> pure ()
+                    bhm <- getp body "hasMore"; case bhm of { VBool bb -> do { setp paging "hasMore" (VBool bb); pure True }; _ -> pure False }
+                  _ -> pure False
+                -- 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.
+                let explicitMore = relayMore || bodyMore
                 hmV <- getp paging "hasMore"; nx <- getp paging "next"; cu2 <- getp paging "cursor"; np <- getp paging "nextPage"
                 let hm = isTrueV hmV || not (isNullish nx) || not (isNullish cu2) || not (isNullish np)
-                setp paging "hasMore" (VBool hm)
+                when (not explicitMore) (setp paging "hasMore" (VBool hm))
                 setp rv "paging" paging
                 cl <- cc ctx; lastM <- jo [("last", paging)]; trackSet cl "paging" lastM
               _ -> pure ()
@@ -721,6 +761,37 @@ pagingFeature = do
       initFn _ opts = do om <- toOptsMap opts; writeIORef options om; a <- optActive opts; writeIORef active a
   pure Feature { fName = "paging", fVersion = "0.0.1", fActive = active, fOptions = fopts, fInit = initFn, fHook = hookFn }
 
+-- Relay pagination: the cursor is the `after` variable (or whatever the model
+-- named it), and the page size is `first`.
+graphqlPreRequest :: Value -> Value -> Value -> Value -> IO ()
+graphqlPreRequest opts specV point paging = do
+  body <- getp specV "body"
+  case body of
+    VMap _ -> do
+      vv <- getp body "variables"
+      variables <- case vv of
+        VMap _ -> pure vv
+        _ -> do m <- emptyMap; setp body "variables" m; pure m
+
+      afterVar <- optStr opts "afterVar" "after"
+      firstVar <- optStr opts "firstVar" "first"
+
+      -- Only bind variables the operation actually declares, or the server
+      -- rejects the document.
+      vl <- getpathS point "graphql.vars"
+      varlist <- case vl of VList _ -> listItems vl; _ -> pure []
+      declared <- mapM (\v -> getStrD v "name" "") varlist
+
+      cur <- case paging of VMap _ -> getp paging "cursor"; _ -> pure VNoval
+      when (not (isNullish cur) && afterVar `elem` declared) $
+        setp variables afterVar cur
+
+      lim <- getp opts "limit"
+      existing <- getp variables firstVar
+      when (not (isNullish lim) && isNullish existing && firstVar `elem` declared) $
+        setp variables firstVar lim
+    _ -> pure ()
+
 elemIndex :: Eq a => a -> [a] -> Maybe Int
 elemIndex x = go 0 where go _ [] = Nothing; go i (y : ys) = if x == y then Just i else go (i + 1) ys
 
@@ -1074,8 +1145,76 @@ prepare client fetchargs = do
   (fd, merr2) <- makeFetchDefUtil ctx
   case merr2 of Just e -> throwIO (SdkException e); Nothing -> pure fd
 
+-- Is this raw-access op permitted by the SDK's allow.op option?
+opAllowed :: Client -> String -> IO Bool
+opAllowed client op = do
+  opts <- readIORef (clOptions client)
+  allow <- getpathS opts "allow.op"
+  pure (case allow of VStr s -> substrContains s op; _ -> False)
+
+opDenied :: Client -> String -> IO Value
+opDenied client op = do
+  opts <- readIORef (clOptions client)
+  allow <- getpathS opts "allow.op"
+  let a = case allow of VStr s -> s; _ -> ""
+  jo [ ("ok", VBool False)
+     , ("err", VStr ("ProjectNameSDK: " ++ op ++ ": operation not allowed by"
+                     ++ " SDK option allow.op value: \"" ++ a ++ "\"")) ]
+
+-- 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.
 direct :: Client -> Value -> IO Value
 direct client fetchargs = do
+  allowed <- opAllowed client "direct"
+  if not allowed then opDenied client "direct" else rawRequest 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.
+graphql :: Client -> String -> Value -> Value -> IO Value
+graphql client query variables ctrl = do
+  allowed <- opAllowed client "graphql"
+  if not allowed then opDenied client "graphql" else do
+    vars <- case variables of VMap _ -> pure variables; _ -> emptyMap
+    ctl <- case ctrl of VMap _ -> pure ctrl; _ -> emptyMap
+    headers <- jo [("content-type", VStr "application/json")]
+    body <- jo [("query", VStr query), ("variables", vars)]
+    fa <- jo [ ("method", VStr "POST"), ("headers", headers)
+             , ("body", body), ("ctrl", ctl) ]
+    res <- rawRequest client fa
+
+    -- 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.
+    ev <- getpathS res "data.errors"
+    errors <- case ev of VList _ -> listItems ev; _ -> pure []
+    case errors of
+      [] -> pure res
+      (firsterr : _) -> do
+        m0 <- getStrD firsterr "message" ""
+        let msg = if null m0 then "graphql error" else m0
+        setp res "ok" (VBool False)
+        setp res "err" (VStr ("ProjectNameSDK: graphql: " ++ msg))
+        setp res "graphql" ev
+        pure res
+
+-- 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.
+rawRequest :: Client -> Value -> IO Value
+rawRequest client fetchargs = do
   let u = clUtility client
   fa <- case fetchargs of VNoval -> emptyMap; _ -> pure fetchargs
   res <- try (prepare client fa) :: IO (Either SdkException Value)