@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/src/cmp/c/TestEntity_c.ts

@@ -8,6 +8,8 @@ import {
   Content,
   File,
   cmp,
+  opReachable,
+  invalidRequest,
 } from '@voxgig/sdkgen'
 
 
@@ -41,10 +43,9 @@ int main(void) {
   CHECK_STR_EQ(e->vt->get_name(e), "${entity.name}", "entity get_name");
 `)
 
-    // The stream test drives the list op; only emit it when the entity has a
-    // list op — a create/load-only entity has no list endpoint, so
-    // stream("list") would error.
-    const hasList = null != (entity.op && (entity.op as any)?.list)
+    // The stream test drives the list op with no match; only emit it when a
+    // bare call can reach a list route (see helpers/opShape opReachable).
+    const hasList = opReachable((entity.op as any)?.list, [])
     if (hasList) {
       Content(`
   // stream(): runs the list op through the full pipeline and returns a List
@@ -79,6 +80,8 @@ int main(void) {
 `)
     }
 
+    Content(failureTests(ident, evar, entity, hasList))
+
     Content(`
   TEST_SUMMARY("${evar}_entity");
 }
@@ -87,6 +90,76 @@ int main(void) {
 })
 
 
+// A failed operation fails a stream as it fails the operation: a transport
+// failure, and a hook that rejects the call. The caller's ctrl stays its own,
+// and an invalid request fails with validate's own error. A C hook cannot throw.
+function failureTests(ident: string, evar: string, entity: ModelEntity, hasList: boolean): string {
+  const feature = (name: string) =>
+    `!v_is_noval(getp(getp(shared_config(), "feature"), "${name}"))`
+  let out = ''
+
+  if (hasList) {
+    out += `
+  {
+    voxgig_value* offline = cmap(1, "net", cmap(1, "offline", v_bool(true)));
+    PNError* ferr = NULL;
+    Entity* fe = ${ident}_${evar}(test_sdk(offline, NULL), NULL);
+    voxgig_value* fitems = ${evar}_stream(fe, "list", NULL, NULL, &ferr);
+    CHECK(NULL == fitems && NULL != ferr && NULL != strstr(ferr->msg, "offline"),
+      "stream: a failed operation fails the stream");
+
+    PNError* qerr = NULL;
+    Entity* qe = ${ident}_${evar}(test_sdk(offline, NULL), NULL);
+    ${evar}_stream(qe, "list", NULL, cmap(1, "ctrl", cmap(1, "throw", v_bool(false))), &qerr);
+    CHECK(NULL == qerr, "stream: under throw false a failed stream ends");
+
+    if (${feature('rbac')}) {
+      PNError* derr = NULL;
+      Entity* de = ${ident}_${evar}(test_sdk(NULL, cmap(1, "feature",
+        cmap(1, "rbac", cmap(2, "active", v_bool(true), "deny", v_bool(true))))), NULL);
+      ${evar}_stream(de, "list", NULL, NULL, &derr);
+      CHECK(NULL != derr && 0 == strcmp(derr->code, "rbac_denied"),
+        "stream: a denied operation fails the stream");
+    }
+  }
+
+  {
+    voxgig_value* explain = voxgig_new_map();
+    voxgig_value* ctrl = cmap(1, "explain", v_share(explain));
+    PNError* cerr = NULL;
+    Entity* ce = ${ident}_${evar}(test_sdk(NULL, NULL), NULL);
+    ${evar}_stream(ce, "list", NULL, cmap(1, "ctrl", v_share(ctrl)), &cerr);
+    CHECK(NULL == cerr && v_is_noval(getp(ctrl, "stream")),
+      "stream: the caller's ctrl gains no key");
+    CHECK(0 < voxgig_as_map(explain)->len, "stream: the caller's explain record is filled");
+  }
+`
+  }
+
+  const bad = invalidRequest(entity)
+  if (null != bad) {
+    const pairs = Object.entries(bad.args)
+    const args = pairs
+      .map(([k, v]) => JSON.stringify(k) + ', ' +
+        ('number' === typeof v ? 'v_num(' + v + ')' :
+          'boolean' === typeof v ? 'v_bool(' + v + ')' : 'v_str(' + JSON.stringify(v) + ')'))
+      .join(', ')
+    out += `
+  if (${feature('validate')}) {
+    PNError* verr = NULL;
+    Entity* ve = ${ident}_${evar}(test_sdk(NULL, cmap(1, "feature",
+      cmap(1, "validate", cmap(1, "active", v_bool(true))))), NULL);
+    ve->vt->${bad.op}(ve, cmap(${pairs.length}, ${args}), NULL, &verr);
+    CHECK(NULL != verr && 0 == strcmp(verr->code, "validate_failed"),
+      "an invalid request fails with validate_failed");
+  }
+`
+  }
+
+  return out
+}
+
+
 export {
   TestEntity
 }

package/project/.sdk/src/cmp/c/fragment/Entity.fragment.c

@@ -31,6 +31,7 @@ static Entity* entyvar_load(Entity* e, voxgig_value* reqmatch, voxgig_value* ctr
 static Entity** entyvar_list(Entity* e, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err);
 static Entity* entyvar_create(Entity* e, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err);
 static Entity* entyvar_update(Entity* e, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err);
+static Entity* entyvar_patch(Entity* e, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err);
 static Entity* entyvar_remove(Entity* e, voxgig_value* reqmatch, voxgig_value* ctrl, PNError** err);
 static void entyvar_mark_deleted(Entity* e);
 static bool entyvar_deleted(Entity* e);
@@ -116,13 +117,20 @@ static voxgig_value* entyvar_run_op(entyvar_entity* self, Context* ctx,
   return done_util(ctx, err);
 }
 
-// A step's error does not pass through make_error in stream, so it and the
-// explain record are cleaned on the way out.
-static voxgig_value* entyvar_stream_fail(Context* ctx, PNError* pe, PNError** err) {
-  clean_explain_util(ctx);
-  clean_error_util(ctx, pe);
-  *err = pe;
-  return NULL;
+// The items of what done or make_error hands back: NULL with *err set, or
+// under `throw: false` the data there is, as a List.
+static voxgig_value* entyvar_stream_items(voxgig_value* data, PNError** err) {
+  if (*err) return NULL;
+  voxgig_value* out = voxgig_new_list();
+  if (voxgig_is_list(data)) {
+    voxgig_list* l = voxgig_as_list(data);
+    for (size_t i = 0; i < l->len; i++) {
+      voxgig_list_push(voxgig_as_list(out), voxgig_retain(l->items[i]));
+    }
+  } else if (data && !v_is_noval(data) && !v_is_null(data)) {
+    voxgig_list_push(voxgig_as_list(out), voxgig_retain(data));
+  }
+  return out;
 }
 
 // Streaming operation. Runs `action` through the full pipeline and returns a
@@ -143,8 +151,15 @@ voxgig_value* entyvar_stream(Entity* e, const char* action, voxgig_value* args,
 
   voxgig_value* stream_opts = voxgig_is_map(callopts) ? callopts : voxgig_new_map();
 
-  voxgig_value* ctrl = to_map(getp(stream_opts, "ctrl"));
-  if (!voxgig_is_map(ctrl)) ctrl = voxgig_new_map();
+  // A copy: the caller's ctrl gains no key, and explain stays its own record.
+  voxgig_value* ctrl = voxgig_new_map();
+  voxgig_value* given = to_map(getp(stream_opts, "ctrl"));
+  if (voxgig_is_map(given)) {
+    voxgig_map* gm = voxgig_as_map(given);
+    for (size_t i = 0; i < gm->len; i++) {
+      setp(ctrl, gm->entries[i].key, voxgig_retain(gm->entries[i].value));
+    }
+  }
   setp(ctrl, "stream", v_share(stream_opts));
 
   voxgig_value* reqmatch = to_map(args);
@@ -171,27 +186,27 @@ voxgig_value* entyvar_stream(Entity* e, const char* action, voxgig_value* args,
 
   feature_hook_util(ctx, "PrePoint");
   voxgig_value* point = make_point_util(ctx, &pe);
-  if (pe) return entyvar_stream_fail(ctx, pe, err);
+  if (pe) return entyvar_stream_items(make_error_util(ctx, pe, err), err);
   ctx_out_set_point_val(ctx, point);
 
   feature_hook_util(ctx, "PreSpec");
   Spec* spec = make_spec_util(ctx, &pe);
-  if (pe) return entyvar_stream_fail(ctx, pe, err);
+  if (pe) return entyvar_stream_items(make_error_util(ctx, pe, err), err);
   ctx->out_spec = spec;
 
   feature_hook_util(ctx, "PreRequest");
   Response* resp = make_request_util(ctx, &pe);
-  if (pe) return entyvar_stream_fail(ctx, pe, err);
+  if (pe) return entyvar_stream_items(make_error_util(ctx, pe, err), err);
   ctx->out_request = resp;
 
   feature_hook_util(ctx, "PreResponse");
   Response* resp2 = make_response_util(ctx, &pe);
-  if (pe) return entyvar_stream_fail(ctx, pe, err);
+  if (pe) return entyvar_stream_items(make_error_util(ctx, pe, err), err);
   ctx->out_response = resp2;
 
   feature_hook_util(ctx, "PreResult");
   SdkResult* result = make_result_util(ctx, &pe);
-  if (pe) return entyvar_stream_fail(ctx, pe, err);
+  if (pe) return entyvar_stream_items(make_error_util(ctx, pe, err), err);
   ctx->out_result = result;
 
   feature_hook_util(ctx, "PreDone");
@@ -205,19 +220,7 @@ voxgig_value* entyvar_stream(Entity* e, const char* action, voxgig_value* args,
     return res->stream(res->stream_ud);
   }
 
-  voxgig_value* data = done_util(ctx, err);
-  if (*err) return NULL;
-
-  voxgig_value* out = voxgig_new_list();
-  if (voxgig_is_list(data)) {
-    voxgig_list* l = voxgig_as_list(data);
-    for (size_t i = 0; i < l->len; i++) {
-      voxgig_list_push(voxgig_as_list(out), voxgig_retain(l->items[i]));
-    }
-  } else if (!v_is_noval(data) && !v_is_null(data)) {
-    voxgig_list_push(voxgig_as_list(out), voxgig_retain(data));
-  }
-  return out;
+  return entyvar_stream_items(done_util(ctx, err), err);
 }
 
 static const char* entyvar_get_name(Entity* e) {
@@ -266,6 +269,8 @@ static voxgig_value* entyvar_matchv(Entity* e, voxgig_value* args) {
 
 // #UpdateOp
 
+// #PatchOp
+
 // #RemoveOp
 
 // `remove` resolves to the entity, marked. The instance KEEPS the data it
@@ -290,5 +295,6 @@ static const EntityVT entyvar_VT = {
   entyvar_list,
   entyvar_create,
   entyvar_update,
+  entyvar_patch,
   entyvar_remove,
 };

package/project/.sdk/src/cmp/c/fragment/EntityPatchOp.fragment.c

@@ -0,0 +1,36 @@
+// EJECT-START
+
+static void entyvar_patch_postdone(entyvar_entity* self, Context* ctx) {
+  SdkResult* result = ctx->result;
+  if (result) {
+    voxgig_value* resmatch = result->resmatch;
+    voxgig_value* resdata = result->resdata;
+    if (voxgig_is_map(resmatch)) self->mtch = resmatch;
+    if (!v_is_noval(resdata) && !v_is_null(resdata)) {
+      voxgig_value* m = to_map(voxgig_clone(resdata));
+      self->data = voxgig_is_map(m) ? m : voxgig_new_map();
+    }
+  }
+}
+
+static Entity* entyvar_patch(Entity* e, voxgig_value* reqdata, voxgig_value* ctrl, PNError** err) {
+  entyvar_entity* self = (entyvar_entity*)e;
+  CtxSpec cs;
+  memset(&cs, 0, sizeof(cs));
+  cs.opname = "patch";
+  cs.ctrl = ctrl;
+  cs.mtch = self->mtch;
+  cs.data = self->data;
+  cs.reqdata = reqdata;
+  Context* ctx = make_context_util(cs, entyvar_ent_ctx(self));
+  entyvar_run_op(self, ctx, entyvar_patch_postdone, err);
+  if (*err) return NULL;
+
+  // The operation resolves to THIS entity: run_op has just absorbed the
+  // result into it, and the caller reaches the record through vt->data.
+  // See AGENTS.md "Entity operations return ENTITIES".
+
+  return e;
+}
+
+// EJECT-END

package/project/.sdk/src/cmp/c/fragment/Main.fragment.c

@@ -2,6 +2,7 @@
 
 #include "api.h"
 
+#include <ctype.h>
 #include <stdio.h>   // snprintf
 #include <stdlib.h>
 #include <string.h>
@@ -99,8 +100,24 @@ voxgig_value* sdk_prepare(ProjectNameSDK* sdk, voxgig_value* fetchargs, PNError*
 
   const char* path = get_str(fetchargs, "path");
   path = path ? path : "";
-  const char* method = get_str(fetchargs, "method");
-  if (!method || method[0] == '\0') method = "GET";
+  const char* given = get_str(fetchargs, "method");
+  if (!given || given[0] == '\0') given = "GET";
+  size_t mlen = strlen(given);
+  char* upper = (char*)malloc(mlen + 1);
+  for (size_t i = 0; i <= mlen; i++) upper[i] = (char)toupper((unsigned char)given[i]);
+  voxgig_value* method_v = v_str(upper);
+  free(upper);
+  const char* method = voxgig_as_string(method_v);
+
+  voxgig_value* allow_method_v = getpath2(options, "allow", "method");
+  if (!allow_list_has(allow_method_v, method)) {
+    char buf[512];
+    snprintf(buf, sizeof(buf),
+      "Method \"%s\" not allowed by SDK option allow.method value: \"%s\"", method,
+      voxgig_is_string(allow_method_v) ? voxgig_as_string(allow_method_v) : "");
+    *err = context_make_error(ctx, "spec_method_allow", buf);
+    return NULL;
+  }
 
   voxgig_value* params = to_map(getp(fetchargs, "params"));
   if (!voxgig_is_map(params)) params = voxgig_new_map();
@@ -144,9 +161,7 @@ static voxgig_value* err_map(const char* msg) {
 
 // Is this raw-access op permitted by the SDK's allow.op option?
 static bool sdk_op_allowed(ProjectNameSDK* sdk, const char* op) {
-  voxgig_value* allow_op = getpath2(sdk->options, "allow", "op");
-  if (!voxgig_is_string(allow_op)) return false;
-  return NULL != strstr(voxgig_as_string(allow_op), op);
+  return allow_list_has(getpath2(sdk->options, "allow", "op"), op);
 }
 
 static voxgig_value* sdk_op_denied(ProjectNameSDK* sdk, const char* op) {
@@ -217,11 +232,29 @@ static voxgig_value* sdk_raw_request(
       json_data = voxgig_is_func(jf) ? call_json(jf) : voxgig_new_undef();
     }
 
-    return cmap(4,
-      "ok", v_bool(status >= 200 && status < 300),
+    PNError* body_err = NULL;
+    bool unreadable = false;
+    if (!no_body && get_bool(fetched, "unreadable", &unreadable) && unreadable) {
+      PNError* failed = NULL;
+      if (status < 200 || status >= 300) {
+        const char* st = get_str(fetched, "statusText");
+        char msg[160];
+        snprintf(msg, sizeof(msg), "request: %lld: %s", (long long)status, st ? st : "");
+        failed = context_make_error(ctx, "request_status", msg);
+      }
+      body_err = unreadable_body(ctx, status, headers, getp(fetched, "body"),
+        getp(fetchdef, "headers"), failed);
+    }
+
+    voxgig_value* out = cmap(4,
+      "ok", v_bool(NULL == body_err && status >= 200 && status < 300),
       "status", v_num((double)status),
       "headers", v_share(headers),
       "data", json_data);
+    if (body_err) {
+      setp(out, "err", v_str(clean_str(ctx, body_err->msg)));
+    }
+    return out;
   }
 
   return err_map("invalid response type");

package/project/.sdk/src/cmp/c/utility_c.ts

@@ -4,7 +4,7 @@ import {
   walk,
 } from '@voxgig/struct'
 
-import { sdkName } from '@voxgig/sdkgen'
+import { sdkName, canonScalarKey, requiredItems } from '@voxgig/sdkgen'
 
 
 // C reserved keywords illegal as identifiers.
@@ -123,6 +123,12 @@ function clean(o: any, dropDefaults?: boolean): any {
 
 
 
+// A C string literal.
+function cString(s: string): string {
+  return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"'
+}
+
+
 function cStringLiteral(json: string, chunkSize: number = 2000): string {
   const parts: string[] = []
   let i = 0
@@ -136,11 +142,24 @@ function cStringLiteral(json: string, chunkSize: number = 2000): string {
     i = end
   }
   return parts
-    .map((p) => '  "' + p.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"')
+    .map((p) => '  ' + cString(p))
     .join('\n')
 }
 
+// A list's required route and query parameters, as the match it is called with.
+function cListMatch(entity: any): string {
+  const lit = (type: any): string =>
+    (({ NULL: 'v_null()', INTEGER: 'v_num(1)', NUMBER: 'v_num(1)', BOOLEAN: 'v_bool(true)', ARRAY: 'v_list()', OBJECT: 'v_map()' }) as any)[canonScalarKey(type)] ?? 'v_str("example")'
+  const items = requiredItems(entity, 'list')
+  return 0 < items.length
+    ? `cmap(${items.length}, ${items.map((it: any) => `${cString(it.name)}, ${lit(it.type)}`).join(', ')})`
+    : 'NULL'
+}
+
+
 export {
+  cListMatch,
+  cString,
   cStringLiteral,
   clean,
   cIdent,

package/project/.sdk/src/cmp/clojure/Entity_clojure.ts

@@ -37,7 +37,7 @@ const Entity = cmp(function Entity(props: any) {
           // defined — callers of an unsupported op get an undefined-var error,
           // matching the dynamic-language donors).
           const opfrags =
-            (['load', 'list', 'create', 'update', 'remove']
+            (['load', 'list', 'create', 'update', 'patch', 'remove']
               .reduce((a: any, opname: string) =>
               (a['; #' + camelify(opname) + 'Op'] =
                 !opnames.includes(opname) ? '' : ({ indent }: any) => {

package/project/.sdk/src/cmp/clojure/Main_clojure.ts

@@ -2,6 +2,7 @@
 import {
   cmp, each,
   File, Content, Copy, Folder,
+  inactiveFeatureExcludes,
   pluginExcludes,
 } from '@voxgig/sdkgen'
 
@@ -50,7 +51,8 @@ const Main = cmp(async function Main(props: any) {
 
   Copy({
     from: 'tm/' + target.name,
-    exclude: [/src\/feature\//, ...containerExcludes, ...pluginExcludes(model)],
+    exclude: [/src\/feature\//, ...containerExcludes,
+      ...inactiveFeatureExcludes(props.ctx$, target), ...pluginExcludes(model)],
     replace: {
       ...props.ctx$.stdrep,
     }

package/project/.sdk/src/cmp/clojure/PrepareAuth_clojure.ts

@@ -78,7 +78,7 @@ function renderHeader(spec: AuthSpec, head: string): string {
 (def OPTION-APIKEY "apikey")
 ` + (spec.basic ? `(def OPTION-SECRET "secret")
 ` : '') + `(def NOT-FOUND "__NOTFOUND__")
-
+${authName('HEADER-AUTH', true)}
 (defn u-prepare-auth [ctx]
   (let [spec (oget ctx :spec)]
     (if (nil? spec) [nil (ctx-error ctx "auth_no_spec" "Expected context spec property to be defined.")]
@@ -87,7 +87,10 @@ function renderHeader(spec: AuthSpec, head: string): string {
           (if (nil? (vs/getprop options "auth"))
             ;; Public APIs that need no auth omit the options.auth block entirely.
             (do (vs/delprop headers HEADER-AUTH) [spec nil])
-            (let [apikey (vs/getprop options OPTION-APIKEY NOT-FOUND)]
+            (let [cred (prepare-auth-name options)
+                  apikey (vs/getprop options OPTION-APIKEY NOT-FOUND)]
+              ;; A credential left under the declared name would travel beside the renamed one.
+              (when (not= cred HEADER-AUTH) (vs/delprop headers HEADER-AUTH))
 ${spec.basic ? basicBlock() : headerPlace(14)}
               [spec nil]))))))
 `
@@ -97,10 +100,10 @@ ${spec.basic ? basicBlock() : headerPlace(14)}
 function headerPlace(col: number): string {
   const p = ' '.repeat(col)
   return `${p}(if (or (nil? apikey) (and (string? apikey) (or (= apikey NOT-FOUND) (= apikey ""))))
-${p}  (vs/delprop headers HEADER-AUTH)
+${p}  (vs/delprop headers cred)
 ${p}  (let [auth-prefix (or (vs/getpath options "auth.prefix") "")
 ${p}        apikey-val (if (string? apikey) apikey "")]
-${p}    (.put ^java.util.Map headers HEADER-AUTH
+${p}    (.put ^java.util.Map headers cred
 ${p}          (if (= auth-prefix "") apikey-val (str auth-prefix " " apikey-val)))))`
 }
 
@@ -117,14 +120,14 @@ function basicBlock(): string {
                       missing? (fn [v] (or (nil? v)
                                            (and (string? v) (or (= v NOT-FOUND) (= v "")))))]
                   (if (missing? apikey)
-                    (vs/delprop headers HEADER-AUTH)
+                    (vs/delprop headers cred)
                     (let [auth-prefix (or (vs/getpath options "auth.prefix") "")
                           b64 (.encodeToString (java.util.Base64/getEncoder)
                                                (.getBytes ^String (str apikey ":" (if (missing? secret) "" secret)) "UTF-8"))]
                       ;; The joined, encoded pair is a wire form neither
                       ;; credential's own registration covers.
                       (ucall ctx :clean-add b64)
-                      (.put ^java.util.Map headers HEADER-AUTH
+                      (.put ^java.util.Map headers cred
                             (if (= auth-prefix "") b64 (str auth-prefix " " b64))))))
 ${headerPlace(16)})`
 }
@@ -137,7 +140,7 @@ function renderQuery(spec: AuthSpec, head: string): string {
 (def QUERY-AUTH ${cljstr(spec.name)})
 (def OPTION-APIKEY "apikey")
 (def NOT-FOUND "__NOTFOUND__")
-
+${authName('QUERY-AUTH', false)}
 (defn u-prepare-auth [ctx]
   (let [spec (oget ctx :spec)]
     (if (nil? spec) [nil (ctx-error ctx "auth_no_spec" "Expected context spec property to be defined.")]
@@ -146,14 +149,17 @@ function renderQuery(spec: AuthSpec, head: string): string {
           (if (nil? (vs/getprop options "auth"))
             ;; Public APIs that need no auth omit the options.auth block entirely.
             (do (vs/delprop query QUERY-AUTH) [spec nil])
-            (let [apikey (vs/getprop options OPTION-APIKEY NOT-FOUND)]
+            (let [cred (prepare-auth-name options)
+                  apikey (vs/getprop options OPTION-APIKEY NOT-FOUND)]
+              ;; A credential left under the declared name would travel beside the renamed one.
+              (when (not= cred QUERY-AUTH) (vs/delprop query QUERY-AUTH))
               (if (or (nil? apikey) (and (string? apikey) (or (= apikey NOT-FOUND) (= apikey ""))))
-                (vs/delprop query QUERY-AUTH)
+                (vs/delprop query cred)
                 (let [apikey-val (if (string? apikey) apikey "")]
                   ;; NO PREFIX IN A QUERY STRING. \`?${spec.name}=Bearer%20abc\` is not a
                   ;; thing any API reads: the prefix is a header convention, so it is
                   ;; dropped here deliberately rather than silently concatenated.
-                  (.put ^java.util.Map query QUERY-AUTH apikey-val)))
+                  (.put ^java.util.Map query cred apikey-val)))
               [spec nil]))))))
 `
 }
@@ -167,27 +173,22 @@ function renderCookie(spec: AuthSpec, head: string): string {
 (def COOKIE-AUTH ${cljstr(spec.name)})
 (def OPTION-APIKEY "apikey")
 (def NOT-FOUND "__NOTFOUND__")
-
-;; The cookie header minus our own pair, every other cookie left untouched.
-(defn- cookies-without-cred [headers]
+${authName('COOKIE-AUTH', false)}
+;; The cookie header minus the named pair, every other cookie left untouched.
+(defn- cookies-without-cred [headers cred]
   (let [existing (vs/getprop headers HEADER-COOKIE)]
     (if (or (not (string? existing)) (= "" existing))
       ""
-      (str/join "; "
-                (remove (fn [piece]
-                          (or (= "" piece)
-                              (= COOKIE-AUTH piece)
-                              (str/starts-with? piece (str COOKIE-AUTH "="))))
-                        (map str/trim (str/split existing #";")))))))
-
-;; Set (a string) or remove (nil) our pair, leaving the rest in place.
-(defn- apply-cookie! [headers value]
-  (let [rest (cookies-without-cred headers)]
+      (str/join "; " (cookie-keep existing #{cred})))))
+
+;; Set (a string) or remove (nil) the named pair, leaving the rest in place.
+(defn- apply-cookie! [headers cred value]
+  (let [rest (cookies-without-cred headers cred)]
     (if (nil? value)
       (if (= "" rest)
         (vs/delprop headers HEADER-COOKIE)
         (.put ^java.util.Map headers HEADER-COOKIE rest))
-      (let [pair (str COOKIE-AUTH "=" value)]
+      (let [pair (str cred "=" value)]
         (.put ^java.util.Map headers HEADER-COOKIE
               (if (= "" rest) pair (str rest "; " pair)))))))
 
@@ -198,13 +199,16 @@ function renderCookie(spec: AuthSpec, head: string): string {
               options (client-options-map (oget ctx :client))]
           (if (nil? (vs/getprop options "auth"))
             ;; Public APIs that need no auth omit the options.auth block entirely.
-            (do (apply-cookie! headers nil) [spec nil])
-            (let [apikey (vs/getprop options OPTION-APIKEY NOT-FOUND)]
+            (do (apply-cookie! headers COOKIE-AUTH nil) [spec nil])
+            (let [cred (prepare-auth-name options)
+                  apikey (vs/getprop options OPTION-APIKEY NOT-FOUND)]
+              ;; A credential left under the declared name would travel beside the renamed one.
+              (when (not= cred COOKIE-AUTH) (apply-cookie! headers COOKIE-AUTH nil))
               (if (or (nil? apikey) (and (string? apikey) (or (= apikey NOT-FOUND) (= apikey ""))))
-                (apply-cookie! headers nil)
+                (apply-cookie! headers cred nil)
                 ;; NO PREFIX IN A COOKIE either - a cookie carries a bare
                 ;; \`name=value\` pair, not a header's scheme-prefixed credential.
-                (apply-cookie! headers (if (string? apikey) apikey "")))
+                (apply-cookie! headers cred (if (string? apikey) apikey "")))
               [spec nil]))))))
 `
 }
@@ -232,6 +236,18 @@ function renderInactive(spec: AuthSpec, head: string): string {
 }
 
 
+// The client's `auth.name` option, when set, replaces the declared name; a
+// header name travels lower-cased.
+function authName(declared: string, header: boolean): string {
+  return `
+;; The client's auth.name option, when set, replaces the name the API declares.
+(defn- prepare-auth-name [options]
+  (let [given (vs/getpath options "auth.name")]
+    (if (and (string? given) (not= "" given)) ${header ? '(.toLowerCase ^String given java.util.Locale/ROOT)' : 'given'} ${declared})))
+`
+}
+
+
 function authSwitchedOn(model: any): boolean {
   const auth = getModelPath(model, `main.${KIT}.config.auth`,
     { only_active: false, required: false })

package/project/.sdk/src/cmp/clojure/ReadmeEntity_clojure.ts

@@ -1,16 +1,19 @@
 
-import { cmp, each, Content, canonKey, canonScalarKey, entityIdField, opRequestShape } from '@voxgig/sdkgen'
+import { cmp, each, Content, canonKey, canonScalarKey, entityIdField, opRequestShape, opNeedsAction } from '@voxgig/sdkgen'
 
 import {
   KIT,
   getModelPath,
 } from '@voxgig/apidef'
 
+import { cljListMatch } from './utility_clojure'
+
 
 // A type-correct Clojure literal for a field's canonical type. The create
 // example builds a real struct map, so array/object render as (vs/jt)/(vs/jm).
 function cljLit(type: any, placeholder: string = 'example'): string {
   const k = canonScalarKey(type)
+  if ('NULL' === k) return 'nil'
   if ('INTEGER' === k || 'NUMBER' === k) return '1'
   if ('BOOLEAN' === k) return 'true'
   if ('ARRAY' === k) return '(vs/jt)'
@@ -40,6 +43,7 @@ const OP_DESC: Record<string, { method: string, desc: string }> = {
   list:   { method: '(list ent match ctrl)',   desc: 'List entities, optionally matching the given criteria.' },
   create: { method: '(create ent data ctrl)',  desc: 'Create a new entity with the given data.' },
   update: { method: '(update ent data ctrl)',  desc: 'Update an existing entity.' },
+  patch:  { method: '(patch ent data ctrl)',   desc: 'Change part of an existing entity.' },
   remove: { method: '(remove ent match ctrl)', desc: 'Remove the matching entity.' },
 }
 
@@ -65,6 +69,8 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 
   publishedEntities.map((entity: any) => {
     const opnames = Object.keys(entity.op || {})
+    // An op that needs an action has no plain call to show.
+    const callable = opnames.filter((o: string) => !opNeedsAction(entity.op[o]))
     const fields = Object.values(entity.fields || {})
     // Model-driven id key: null when this entity has no id-like field.
     const idF = entityIdField(entity)
@@ -120,7 +126,7 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    if (opnames.includes('load')) {
+    if (callable.includes('load')) {
       // The id key plus every REQUIRED match key (parent path params like
       // page_id) — the same shape the runtime resolves path params from.
       const loadItems = opRequestShape(entity, 'load').items
@@ -141,17 +147,17 @@ const ReadmeEntity = cmp(function ReadmeEntity(props: any) {
 `)
     }
 
-    if (opnames.includes('list')) {
+    if (callable.includes('list')) {
       Content(`#### Example: List
 
 \`\`\`clojure
-(def ${eLow}s (e-${eLow}/list (api/${eLow} client nil) nil nil))
+(def ${eLow}s (e-${eLow}/list (api/${eLow} client nil) ${cljListMatch(entity)} nil))
 \`\`\`
 
 `)
     }
 
-    if (opnames.includes('create')) {
+    if (callable.includes('create')) {
       // Members come from the SAME shape the runtime validates
       // (opRequestShape): every required member must appear.
       const createItems = opRequestShape(entity, 'create').items