@voxgig/sdkgen 4.34.0 → 4.34.1

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

@@ -28,6 +28,9 @@ function makeUrl(ctx) {
   }
   let resmatch = {}
 
+  // Sent with the request, never recorded as the entity's match.
+  const authquery = spec.authquery || []
+
   const params = spec.params
 
   for (let [key, val] of items(params)) {
@@ -37,6 +40,26 @@ function makeUrl(ctx) {
     }
   }
 
+  // A placeholder left in the route would send the request to the wrong route.
+  // The base's own placeholders are server variables, resolved with the options.
+  const base = ('string' === typeof spec.base ? spec.base : '').replace(/\/+$/, '')
+  const route = url.startsWith(base) ? url.slice(base.length) : url
+  const unfilled = route.match(/\{[^{}\/]+\}/g)
+  if (null != unfilled) {
+    return ctx.error('url_param_missing', 'URL path has no value for ' + unfilled.join(', ') + '.')
+  }
+
+  let qsep = '?'
+  for (let [key, val] of items(spec.query)) {
+    if (null != val) {
+      url += qsep + escurl(key) + '=' + escurl(val)
+      qsep = '&'
+      if (!authquery.includes(key)) {
+        resmatch[key] = val
+      }
+    }
+  }
+
   result.resmatch = resmatch
 
   return url

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

@@ -0,0 +1,145 @@
+
+// The media types a point declares: `response` (the model's `rs`) for the
+// Accept header, and `body` (the model's `rb`) for the request body.
+
+
+// The data key holding a raw request body. Like `$action`, it can never be a
+// declared argument name.
+const RAW_BODY = '$body'
+
+
+function isJsonMedia(type) {
+  const media = String(null == type ? '' : type).split(';')[0].trim().toLowerCase()
+  return 'application/json' === media || 'text/json' === media || media.endsWith('+json')
+}
+
+
+// The declared JSON type alone, else every declared type in the model's
+// order; nothing when no success response declares a body.
+function acceptOf(point) {
+  const res = null == point ? undefined : point.response
+  if (null == res || 'string' !== typeof res.media || '' === res.media) {
+    return undefined
+  }
+  if ('json' === res.kind) {
+    return res.media
+  }
+  const alts = Array.isArray(res.alternatives) ? res.alternatives : []
+  return [res.media, ...alts.map((alt) => null == alt ? undefined : alt.media)]
+    .filter((media) => 'string' === typeof media && '' !== media)
+    .join(', ')
+}
+
+
+function isRawRequest(point) {
+  return null != point && null != point.body && 'raw' === point.body.kind
+}
+
+
+function isJsonRequest(point) {
+  return null != point && null != point.body && 'json' === point.body.kind
+}
+
+
+function hasHeader(headers, name) {
+  return Object.keys(headers).some((key) => name === key.toLowerCase())
+}
+
+
+// A caller's accept wins. A declared request type replaces each JSON
+// content-type, the SDK default, and leaves any other the caller set.
+function mediaHeaders(point, headers) {
+  const accept = acceptOf(point)
+  if (null != accept && !hasHeader(headers, 'accept')) {
+    headers.accept = accept
+  }
+
+  const body = null == point ? undefined : point.body
+  if (null != body && ('raw' === body.kind || 'json' === body.kind) &&
+    'string' === typeof body.media && '' !== body.media) {
+    for (const key of Object.keys(headers)) {
+      if ('content-type' === key.toLowerCase() && isJsonMedia(headers[key])) {
+        delete headers[key]
+      }
+    }
+    if (!hasHeader(headers, 'content-type')) {
+      headers['content-type'] = body.media
+    }
+  }
+
+  return headers
+}
+
+
+function rawBody(reqdata) {
+  return null != reqdata && 'object' === typeof reqdata ? reqdata[RAW_BODY] : undefined
+}
+
+
+function isStream(value) {
+  return null != value && 'object' === typeof value &&
+    (('undefined' !== typeof ReadableStream && value instanceof ReadableStream) ||
+      'function' === typeof value[Symbol.asyncIterator])
+}
+
+
+// A stream can be read once. makeRequest reads it before the first attempt,
+// so that a retry sends the same bytes again.
+async function readStream(stream) {
+  const chunks = []
+  if ('undefined' !== typeof ReadableStream && stream instanceof ReadableStream) {
+    const reader = stream.getReader()
+    for (; ;) {
+      const { done, value } = await reader.read()
+      if (done) {
+        break
+      }
+      chunks.push(chunkBytes(value))
+    }
+  }
+  else {
+    for await (const chunk of stream) {
+      chunks.push(chunkBytes(chunk))
+    }
+  }
+
+  const out = new Uint8Array(chunks.reduce((n, c) => n + c.byteLength, 0))
+  let at = 0
+  for (const chunk of chunks) {
+    out.set(chunk, at)
+    at += chunk.byteLength
+  }
+  return out
+}
+
+
+function chunkBytes(chunk) {
+  if ('string' === typeof chunk) {
+    return new TextEncoder().encode(chunk)
+  }
+  if (chunk instanceof ArrayBuffer) {
+    return new Uint8Array(chunk)
+  }
+  return new Uint8Array(chunk.buffer, chunk.byteOffset, chunk.byteLength)
+}
+
+
+// Bytes, a Blob or a stream: fetch sends these as they are.
+function isRawValue(value) {
+  return value instanceof ArrayBuffer || ArrayBuffer.isView(value) ||
+    ('undefined' !== typeof Blob && value instanceof Blob) || isStream(value)
+}
+
+
+module.exports = {
+  RAW_BODY,
+  acceptOf,
+  isJsonMedia,
+  isJsonRequest,
+  isRawRequest,
+  isRawValue,
+  isStream,
+  mediaHeaders,
+  rawBody,
+  readStream,
+}

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

@@ -2,10 +2,6 @@
 function param(ctx, paramdef) {
   const point = ctx.point
   const spec = ctx.spec
-  const match = ctx.match
-  const reqmatch = ctx.reqmatch
-  const data = ctx.data
-  const reqdata = ctx.reqdata
 
   const utility = ctx.utility
   const struct = utility.struct
@@ -20,42 +16,74 @@ function param(ctx, paramdef) {
 
   const key = 0 < (T_string & pt) ? paramdef : getprop(paramdef, 'name')
 
-  let akey = getprop(point.alias, key)
+  const akey = getprop(point.alias, key)
+
+  if (null != spec && null != akey &&
+    null == getprop(ctx.reqmatch, key) && null == getprop(ctx.match, key)) {
+    setprop(spec.alias, akey, key)
+  }
+
+  return paramValue(ctx, point, key)
+}
 
-  let val = getprop(reqmatch, key)
+
+// The value the call or its entity gives a point's parameter, under its name
+// or the point's alias for it.
+function paramValue(ctx, point, key) {
+  const getprop = ctx.utility.struct.getprop
+  const akey = getprop(point && point.alias, key)
+
+  let val = getprop(ctx.reqmatch, key)
 
   if (null == val) {
-    val = getprop(match, key)
+    val = getprop(ctx.match, key)
   }
 
   if (null == val && null != akey) {
-
-    if (null != spec) {
-      setprop(spec.alias, akey, key)
-    }
-
-    val = getprop(reqmatch, akey)
+    val = getprop(ctx.reqmatch, akey)
   }
 
   if (null == val) {
-    val = getprop(reqdata, key)
+    val = getprop(ctx.reqdata, key)
   }
 
   if (null == val) {
-    val = getprop(data, key)
+    val = getprop(ctx.data, key)
   }
 
   if (null == val && null != akey) {
-    val = getprop(reqdata, akey)
+    val = getprop(ctx.reqdata, akey)
 
     if (null == val) {
-      val = getprop(data, akey)
+      val = getprop(ctx.data, akey)
     }
   }
 
   return val
 }
 
+
+// The arguments a point declares in one location, query or header, each with
+// the name it travels under and the value this call passes in its match or
+// else its data. Unlike a path parameter, the entity's stored match and data
+// never supply one.
+function callArgs(ctx, kind) {
+  const getprop = ctx.utility.struct.getprop
+  const declared = (ctx.point && ctx.point.args && ctx.point.args[kind]) || []
+  const out = []
+
+  for (const arg of declared) {
+    if (null == arg || 'string' !== typeof arg.name || '' === arg.name) continue
+    let val = getprop(ctx.reqmatch, arg.name)
+    if (null == val) val = getprop(ctx.reqdata, arg.name)
+    out.push({ name: arg.name, wire: String(arg.orig || arg.name), val })
+  }
+
+  return out
+}
+
 module.exports = {
-  param
+  param,
+  paramValue,
+  callArgs,
 }

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 entity declares it as a field too.
+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))
 }