@voxgig/sdkgen 4.34.0 → 4.34.2

package/project/.sdk/tm/js/src/utility/PrepareBodyUtility.js

@@ -1,4 +1,6 @@
 
+const { isRawRequest, rawBody } = require('./MediaUtility')
+
 function prepareBody(ctx) {
   const op = ctx.op
 
@@ -9,6 +11,10 @@ function prepareBody(ctx) {
   let body = undefined
 
   if ('data' === op.input) {
+    if (isRawRequest(ctx.point)) {
+      return rawBody(ctx.reqdata)
+    }
+
     try {
       body = transformRequest(ctx)
     }

package/project/.sdk/tm/js/src/utility/PrepareHeadersUtility.js

@@ -1,4 +1,7 @@
 
+const { callArgs } = require('./ParamUtility')
+const { mediaHeaders } = require('./MediaUtility')
+
 function prepareHeaders(ctx) {
   const struct = ctx.utility.struct
   const clone = struct.clone
@@ -9,28 +12,66 @@ function prepareHeaders(ctx) {
 
   const options = client.options()
 
-  let out = clone(getprop(options, 'headers', {}))
-
-  // A header parameter travels as a header, under the name the definition
-  // gives it, and only from this call's own arguments. It replaces a default
-  // of the same name, whatever its case.
-  const hargs = (ctx.point && ctx.point.args && ctx.point.args.header) || []
-  for (const h of hargs) {
-    if (null == h || 'string' !== typeof h.name || '' === h.name) continue
-    let val = getprop(ctx.reqmatch, h.name)
-    if (null == val) val = getprop(ctx.reqdata, h.name)
-    if (null != val) {
-      const wire = String(h.orig || h.name).toLowerCase()
+  let out = mediaHeaders(ctx.point, clone(getprop(options, 'headers', {})))
+
+  // A header argument replaces a default of the same name, whatever its case.
+  for (const arg of callArgs(ctx, 'header')) {
+    if (null != arg.val) {
+      const wire = arg.wire.toLowerCase()
       for (const key of Object.keys(out)) {
         if (wire === key.toLowerCase()) delete out[key]
       }
-      out[wire] = stringify(val)
+      out[wire] = stringify(arg.val)
     }
   }
 
+  // A cookie argument travels in the cookie header, form serialized and
+  // percent-encoded, replacing a cookie of the same name among those the
+  // caller's headers already send.
+  const sent = callArgs(ctx, 'cookie').filter((arg) => null != arg.val)
+  if (0 < sent.length) {
+    const names = sent.flatMap((arg) => struct.ismap(arg.val) ?
+      struct.keysof(arg.val).map((key) => struct.escurl(key)) : [arg.wire])
+    const kept = []
+    for (const key of Object.keys(out)) {
+      if ('cookie' !== key.toLowerCase()) continue
+      if ('string' === typeof out[key]) kept.push(...cookieKeep(out[key], names))
+      delete out[key]
+    }
+    for (const arg of sent) {
+      const pair = cookiePair(struct, arg.wire, arg.val)
+      if ('' !== pair) kept.push(pair)
+    }
+    if (0 < kept.length) out['cookie'] = kept.join('; ')
+  }
+
   return out
 }
 
+// The form style of a cookie parameter: a list repeats the name, a map sends
+// its own keys, and every value is percent-encoded.
+function cookiePair(struct, wire, val) {
+  const esc = (v) => struct.escurl(struct.stringify(v))
+  const pairs = struct.islist(val) ? val.map((item) => wire + '=' + esc(item)) :
+    struct.ismap(val) ? struct.keysof(val).map((key) => struct.escurl(key) + '=' + esc(val[key])) :
+      [wire + '=' + esc(val)]
+  return pairs.join('; ')
+}
+
+
+// The caller's cookie pieces with the named cookies removed: a cookie is one
+// `;`-delimited piece, whatever its value holds.
+function cookieKeep(header, names) {
+  const kept = []
+  for (const piece of header.split(';')) {
+    const cookie = piece.trim()
+    if ('' !== cookie && !names.includes(cookie.split('=')[0].trim())) kept.push(cookie)
+  }
+  return kept
+}
+
+
 module.exports = {
-  prepareHeaders
+  prepareHeaders,
+  cookieKeep
 }

package/project/.sdk/tm/js/src/utility/PrepareMethodUtility.js

@@ -26,6 +26,15 @@ function prepareMethod(ctx) {
   return methodMap[key]
 }
 
+
+// Whether a comma-separated allow option names the item: whole names, any case.
+function allowed(list, item) {
+  const want = 'string' === typeof item ? item.toUpperCase() : ''
+  return '' !== want && 'string' === typeof list &&
+    list.split(',').some((name) => name.trim().toUpperCase() === want)
+}
+
 module.exports = {
+  allowed,
   prepareMethod
 }

package/project/.sdk/tm/js/src/utility/PrepareQueryUtility.js

@@ -1,4 +1,6 @@
 
+const { callArgs } = require('./ParamUtility')
+
 function prepareQuery(ctx) {
   const utility = ctx.utility
   const struct = utility.struct
@@ -13,27 +15,42 @@ function prepareQuery(ctx) {
 
   // A path parameter travels in the path. The generated config lists them as
   // args.params, which prepareParams reads; params is the older list of names.
-  // A header parameter travels in the headers, which prepareHeaders fills.
   const inpath = params.concat(
-    ((point.args && point.args.params) || []).map((p) => p && p.name),
-    ((point.args && point.args.header) || []).map((h) => h && h.name))
+    ((point.args && point.args.params) || []).map((p) => p && p.name))
 
   // A query parameter travels under the name the definition gives it, its
   // orig, which the model may have renamed for the caller.
   const wire = Object.create(null)
+  const declared = []
   for (const q of ((point.args && point.args.query) || [])) {
-    if (q && 'string' === typeof q.name && 'string' === typeof q.orig && '' !== q.orig) {
-      wire[q.name] = q.orig
+    if (q && 'string' === typeof q.name) {
+      declared.push(q.name)
+      if ('string' === typeof q.orig && '' !== q.orig) {
+        wire[q.name] = q.orig
+      }
     }
   }
 
+  // A header or cookie parameter travels in the headers, which prepareHeaders
+  // fills, unless a query parameter shares its name: then both are sent.
+  const elsewhere = ((point.args && point.args.header) || [])
+    .concat((point.args && point.args.cookie) || [])
+    .map((a) => a && a.name).filter((name) => !declared.includes(name))
+
   const out = {}
   for (let [key, val] of items(reqmatch)) {
-    if (null != val && '$action' !== key && !inpath.includes(key)) {
+    if (null != val && '$action' !== key && !inpath.includes(key) && !elsewhere.includes(key)) {
       out[null == wire[key] ? key : wire[key]] = val
     }
   }
 
+  // A create or update passes its query arguments in its data.
+  for (const arg of callArgs(ctx, 'query')) {
+    if (null != arg.val && !inpath.includes(arg.name)) {
+      out[arg.wire] = arg.val
+    }
+  }
+
   return out
 }
 

package/project/.sdk/tm/js/src/utility/ResultBodyUtility.js

@@ -1,18 +1,75 @@
 
+const PREVIEW_LENGTH = 160
+
+
 async function resultBody(ctx) {
   const response = ctx.response
   const result = ctx.result
 
   if (result) {
     if (response && response.json && null != response.body) {
-      const json = await response.json()
-      result.body = json
+      try {
+        const json = await response.json()
+        result.body = json
+      }
+      catch (err) {
+        if ('SyntaxError' !== err?.name) {
+          throw err
+        }
+        result.err = unreadableBody(ctx, {
+          status: result.status, headers: result.headers, text: err.text,
+          sent: ctx.spec?.headers, failed: result.err,
+        })
+      }
     }
   }
 
   return result
 }
 
+
+// A body that is not JSON. An HTTP failure keeps its own error, with the
+// response described; otherwise the code tells a wrong content type from
+// malformed JSON.
+function unreadableBody(ctx, res) {
+  const type = headerValue(res.headers, 'content-type')
+  const detail = 'HTTP ' + res.status + ', content-type ' + (type || 'none') +
+    ', user-agent ' + (ctx.utility.clean(ctx, headerValue(res.sent, 'user-agent')) || 'transport default') +
+    (null == res.text ? '' : ', body: ' + preview(ctx, res.text))
+
+  if (null != res.failed) {
+    res.failed.message += ' (' + detail + ')'
+    return res.failed
+  }
+
+  return '' === type || /json/i.test(type)
+    ? ctx.error('response_json_invalid', 'response: body is not valid JSON (' + detail + ')')
+    : ctx.error('response_content_type', 'response: expected JSON, got ' + type +
+      ' (' + detail + ')')
+}
+
+
+function headerValue(headers, name) {
+  if ('function' === typeof headers?.get) {
+    return String(headers.get(name) ?? '')
+  }
+  for (const key of Object.keys(headers || {})) {
+    if (name === key.toLowerCase()) {
+      return String(headers[key])
+    }
+  }
+  return ''
+}
+
+
+// Cleaned whole: a secret the bound would split could leave its prefix.
+function preview(ctx, text) {
+  const flat = ctx.utility.clean(ctx, String(text).replace(/\s+/g, ' ').trim())
+  return PREVIEW_LENGTH < flat.length ? flat.slice(0, PREVIEW_LENGTH) + '...' : flat
+}
+
+
 module.exports = {
-  resultBody
+  resultBody,
+  unreadableBody,
 }

package/project/.sdk/tm/js/src/utility/TransformRequestUtility.js

@@ -1,4 +1,6 @@
 
+const { callArgs } = require('./ParamUtility')
+
 function transformRequest(ctx) {
   const spec = ctx.spec
   const utility = ctx.utility
@@ -13,7 +15,7 @@ function transformRequest(ctx) {
   try {
     const reqform = point.transform.req
     const reqdata = isfunc(reqform) ? reqform(ctx) : transform({
-      reqdata: omit(ctx.reqdata, headerArgNames(ctx))
+      reqdata: omit(ctx.reqdata, routedArgNames(ctx))
     }, reqform)
 
     return stripAction(reqdata)
@@ -46,12 +48,19 @@ function stripAction(reqdata) {
 }
 
 
-// A header argument travels as a header, which prepareHeaders sends, so the
-// body is built from the request data without it.
-function headerArgNames(ctx) {
-  const hargs = (ctx.point && ctx.point.args && ctx.point.args.header) || []
-  return hargs.map((h) => h && h.name)
-    .filter((name) => 'string' === typeof name && '' !== name)
+// A header, cookie or query argument travels where prepareHeaders or
+// prepareQuery sends it, so the body is built from the request data without
+// it, unless the point marks it as a field the body keeps.
+function routedArgNames(ctx) {
+  return callArgs(ctx, 'header').concat(callArgs(ctx, 'cookie'), callArgs(ctx, 'query'))
+    .map((arg) => arg.name)
+    .filter((name) => !fieldArg(ctx, name))
+}
+
+
+function fieldArg(ctx, name) {
+  return ['header', 'cookie', 'query'].some((kind) =>
+    (ctx.point?.args?.[kind] || []).some((arg) => name === arg?.name && true === arg?.field))
 }
 
 

package/project/.sdk/tm/js/test/definition-runner.js

@@ -10,6 +10,9 @@ const assert = require('node:assert/strict')
 const KEY = 'definition-test-key'
 const BASE = 'http://definition.test'
 
+const RAW_TEXT = 'definition-test-body'
+const RAW_BYTES = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a, 0x00, 0xff])
+
 
 async function runDefinitionPoint(SDK, point) {
   const sent = []
@@ -33,7 +36,9 @@ async function runDefinitionPoint(SDK, point) {
   const input = { ...point.select }
   for (const arg of point.args) input[arg.name] = arg.value
   for (const h of point.headers || []) input[h.name] = h.value
+  for (const c of point.cookies || []) input[c.name] = c.value
   if (null != point.action) input.$action = point.action
+  if (null != point.rawBody) input.$body = rawSample(point)
 
   let result
   let error
@@ -61,11 +66,19 @@ async function runDefinitionPoint(SDK, point) {
   // Only what the definition declares, so never a path parameter again.
   const credentialQuery = (point.auth || []).flat()
     .filter((c) => 'query' === c.in).map((c) => c.name)
+  // prepareAuth sends the key whether or not this operation applies its scheme.
+  if (null != point.ownQuery) {
+    credentialQuery.push(point.ownQuery)
+  }
   for (const key of url.searchParams.keys()) {
     assert(point.query.includes(key) || credentialQuery.includes(key),
       'query parameter not in the definition: ' + key)
   }
 
+  for (const q of point.queryArgs || []) {
+    assert(url.searchParams.has(q.wire), 'query parameter not sent: ' + q.wire)
+  }
+
   // From the apikey alone, placed as the definition's security scheme says.
   if (null != point.auth && 0 < point.auth.length) {
     const headers = new Headers(init.headers)
@@ -81,8 +94,63 @@ async function runDefinitionPoint(SDK, point) {
   for (const h of point.headers || []) {
     const wire = h.wire.toLowerCase()
     if (credentialHeaders.includes(wire) || 'content-type' === wire) continue
-    assert.equal(new Headers(init.headers).get(wire), String(h.value),
-      'header parameter not sent as a header: ' + h.wire)
+    const sentValue = new Headers(init.headers).get(wire)
+    // A Cookie header argument is cookie pieces, which the cookie arguments and
+    // the cookie credential join, each replacing the piece whose name it owns.
+    if ('cookie' === wire) {
+      const owned = (point.cookies || []).map((c) => c.wire).concat((point.auth || []).flat()
+        .filter((c) => 'cookie' === c.in).map((c) => c.name))
+      const pieces = String(sentValue ?? '').split(';').map((c) => c.trim())
+      for (const piece of String(h.value).split(';').map((c) => c.trim()).filter((c) => '' !== c)) {
+        if (owned.includes(piece.split('=')[0].trim())) continue
+        assert(pieces.includes(piece), 'header parameter not sent as a header: ' + h.wire)
+      }
+      continue
+    }
+    assert.equal(sentValue, String(h.value), 'header parameter not sent as a header: ' + h.wire)
+  }
+
+  // A cookie parameter goes out in the cookie header as name=value, percent-encoded.
+  const cookies = String(new Headers(init.headers).get('cookie') ?? '')
+    .split(';').map((c) => c.trim())
+  for (const c of point.cookies || []) {
+    assert(cookies.includes(c.wire + '=' + encodeURIComponent(String(c.value))),
+      'cookie parameter not sent in the cookie header: ' + c.wire)
+  }
+
+  // Accept asks only for what a success response declares: its JSON type
+  // alone, when it declares one.
+  if (null != point.responseMedia) {
+    const declared = point.responseMedia
+    const asked = String(new Headers(init.headers).get('accept') ?? '').split(',')
+      .map(baseMedia).filter((type) => '' !== type)
+    assert(0 < asked.length, 'no Accept for a declared response body: ' + declared.join(', '))
+    for (const type of asked) {
+      assert(declared.some((d) => covers(d, type)),
+        'Accept asks for a type no success response declares: ' + type)
+    }
+    if (declared.some(isJson)) {
+      assert(1 === asked.length && isJson(asked[0]),
+        'Accept is not the declared JSON type alone: ' + asked.join(', '))
+    }
+  }
+
+  // A raw body goes out as given, under a type the definition declares.
+  if (null != point.rawBody) {
+    const type = baseMedia(new Headers(init.headers).get('content-type') ?? '')
+    assert(point.rawBody.media.some((d) => covers(d, type)),
+      'raw body sent as a type the definition does not declare: ' + type)
+    assert.deepEqual(bytesOf(init.body), bytesOf(rawSample(point)), 'raw body not sent as given')
+  }
+
+  // An argument the request body declares too goes out in the body as well.
+  if (0 < (point.bodyArgs || []).length) {
+    let sentBody
+    try { sentBody = JSON.parse(String(init.body)) }
+    catch (_e) { sentBody = undefined }
+    for (const name of point.bodyArgs) {
+      assert.deepEqual(sentBody?.[name], input[name], 'argument not sent in the body as well: ' + name)
+    }
   }
 
   if (null != error) {
@@ -102,7 +170,8 @@ async function runDefinitionPoint(SDK, point) {
         records.length)
     }
   }
-  else if ('load' === point.op || 'create' === point.op || 'update' === point.op) {
+  else if ('load' === point.op || 'create' === point.op || 'update' === point.op ||
+    'patch' === point.op) {
     const record = recordOf(point.sample, point.idField, point.entity)
     if (null != record) {
       assert.equal(result?.data?.()?.[point.idField], record[point.idField],
@@ -112,6 +181,37 @@ async function runDefinitionPoint(SDK, point) {
 }
 
 
+function rawSample(point) {
+  return point.rawBody.text ? RAW_TEXT : RAW_BYTES
+}
+
+
+function bytesOf(body) {
+  return 'string' === typeof body ? Buffer.from(body, 'utf8') :
+    body instanceof ArrayBuffer ? Buffer.from(new Uint8Array(body)) :
+      ArrayBuffer.isView(body) ? Buffer.from(body.buffer, body.byteOffset, body.byteLength) :
+        Buffer.from(String(body))
+}
+
+
+function baseMedia(type) {
+  return type.split(';')[0].trim().toLowerCase()
+}
+
+
+function isJson(type) {
+  const media = baseMedia(type)
+  return 'application/json' === media || 'text/json' === media || media.endsWith('+json')
+}
+
+
+function covers(declared, type) {
+  const media = baseMedia(declared)
+  return media === type || '*/*' === media ||
+    (media.endsWith('/*') && type.startsWith(media.slice(0, -1)))
+}
+
+
 function placed(cred, headers, url) {
   if ('query' === cred.in) {
     return KEY === url.searchParams.get(cred.name)

package/project/.sdk/tm/js/test/feature/Corpus.test.js

@@ -185,6 +185,15 @@ function tokensUsed(kase) {
 }
 
 
+// The first feature a case composes that this SDK does not generate. Such a
+// case is skipped rather than failed, as a section naming one is.
+function missingFeature(probe, kase) {
+  const named = Array.isArray(kase.feature) ? kase.feature.map((f) => f?.name) :
+    Object.keys(kase.feature || {})
+  return named.find((n) => 'string' === typeof n && !probe._rootctx.config.hasFeature(n))
+}
+
+
 // Assert that `actual` contains `expect`, recursively. Cases assert only the
 // fields they are about, so a full deepStrictEqual would force every case to
 // restate the whole record.
@@ -267,6 +276,7 @@ describe('FeatureCorpus', () => {
         `or an emptied fixture must fail loudly, not pass silently`)
 
       let ran = 0
+      const failed = []
       for (const raw of cases) {
         const need = tokensUsed(raw)
         if (ops.length < need) {
@@ -274,33 +284,52 @@ describe('FeatureCorpus', () => {
           continue
         }
 
+        const missing = missingFeature(probe, raw)
+        if (null != missing) {
+          t.diagnostic(`skip "${raw.name}": needs the ${missing} feature, ` +
+            'which this SDK does not generate')
+          continue
+        }
+
         const tokens = {}
         for (let i = 0; i < need; i++) { tokens['#OP' + (i + 1)] = ops[i].key }
 
         const kase = resolve(raw, tokens)
-        const client = makeClient(kase)
-
-        for (const step of (kase.op || [])) {
-          const ref = byKey[step.op]
-          ok(null != ref, `${kase.name}: no operation ${step.op}`)
-          try {
-            await client[ref.accessor]()[ref.op]({}, step.ctrl || {})
-            ok(null == step.err,
-              `${kase.name}: ${step.op} was expected to fail, and did not`)
-          }
-          catch (err) {
-            if (null == step.err) { throw err }
+        ran++
+
+        // Every failing case is reported, not only the first.
+        try {
+          const client = makeClient(kase)
+
+          for (const step of (kase.op || [])) {
+            const ref = byKey[step.op]
+            ok(null != ref, `${kase.name}: no operation ${step.op}`)
+            let err = undefined
+            try {
+              await client[ref.accessor]()[ref.op]({}, step.ctrl || {})
+            }
+            catch (e) {
+              err = e
+            }
+            if (null == step.err) {
+              ok(undefined === err,
+                `${kase.name}: ${step.op} failed unexpectedly: ${err?.message}`)
+              continue
+            }
+            ok(undefined !== err, `${kase.name}: ${step.op} was expected to fail, and did not`)
             if ('string' === typeof step.err) {
               deepStrictEqual(err.code, step.err, `${kase.name}: wrong error code`)
             }
           }
-        }
 
-        subset(client[`_${name}`], kase.out, `${kase.name}: _${name}`)
-        ran++
+          subset(client[`_${name}`], kase.out, `${kase.name}: _${name}`)
+        }
+        catch (err) {
+          const msg = String(err?.message ?? err)
+          failed.push(msg.startsWith(kase.name) ? msg : kase.name + ': ' + msg)
+        }
       }
 
-      ok(0 < ran, `every feature.${name} case was skipped`)
       // Say how many ran. A partial run is legitimate (an SDK with one
       // operation skips the cases needing two) but it should be visible
       // rather than inferred from a green tick - and it is the one line
@@ -308,6 +337,8 @@ describe('FeatureCorpus', () => {
       // language's runner.
       t.diagnostic(`feature.${name}: ran ${ran} of ${cases.length} ` +
         `case(s) against ${ops.length} operation(s)`)
+      ok(0 < ran, `every feature.${name} case was skipped`)
+      deepStrictEqual(failed, [], `feature.${name}: ${failed.length} case(s) failed`)
     })
   }
 })

package/project/.sdk/tm/js/test/feature/harness.js

@@ -66,7 +66,7 @@ function defaultServer() {
 
 function defaultMethod(op) {
   if ('create' === op) return 'POST'
-  if ('update' === op) return 'PATCH'
+  if ('update' === op || 'patch' === op) return 'PATCH'
   if ('remove' === op) return 'DELETE'
   return 'GET'
 }
@@ -243,6 +243,9 @@ function makeClient(spec) {
           headers: ctx.spec.headers,
           body: ctx.spec.body,
         }
+        if (null != ctx.ctrl.signal) {
+          fetchdef.signal = ctx.ctrl.signal
+        }
         response = await utility.fetcher(ctx, fetchdef.url, fetchdef)
       }
       ctx.response = response

package/project/.sdk/tm/js/test/feature/secrets/Secrets.test.js

@@ -282,9 +282,9 @@ describe('secrets', () => {
     assert.equal(stub.sent, 0,
       'a request must not go out unauthenticated because a provider broke,' +
       ' but one reached the transport: ' + wire(stub))
-    assert.ok(res instanceof Error,
-      'expected the provider Error, got: ' + JSON.stringify(res))
-    assert.match(String(res.message), /vault unreachable/)
+    assert.ok(res && false === res.ok && res.err instanceof Error,
+      'expected the provider Error as err, got: ' + JSON.stringify(res))
+    assert.match(String(res.err.message), /vault unreachable/)
 
     // CONTROL, which makes that zero mean REFUSED rather than UNWIRED: the
     // same construction with a WORKING provider must reach the same
@@ -308,9 +308,9 @@ describe('secrets', () => {
     assert.equal(stub.sent, 0,
       'a graphql request must not go out unauthenticated,' +
       ' but one reached the transport: ' + wire(stub))
-    assert.ok(res instanceof Error,
-      'expected the provider Error, got: ' + JSON.stringify(res))
-    assert.match(String(res.message), /vault unreachable/)
+    assert.ok(res && false === res.ok && res.err instanceof Error,
+      'expected the provider Error as err, got: ' + JSON.stringify(res))
+    assert.match(String(res.err.message), /vault unreachable/)
 
     const control = countingFetch()
     const ok = await rawSdk(control, WORKINGPROVIDER).graphql('{ thing }', {})
@@ -869,7 +869,7 @@ describe('secrets exchange', () => {
 
     const res = await sdk.direct({ path: '/thing' })
 
-    assert.ok(res instanceof Error || (res && false === res.ok),
+    assert.ok(res && false === res.ok && null != res.err,
       'expected a failure, got: ' + JSON.stringify(res))
     assert.equal(stub.api().length, 0,
       'a request must not go out unauthenticated because the chain was empty')