@voxgig/sdkgen 4.34.0 → 4.34.1

package/project/.sdk/tm/py/pkg/utility/make_spec.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
 from projectname_sdk.core.spec import ProjectNameSpec
 from projectname_sdk.utility.graphql import GRAPHQL_CONTENT_TYPE
+from projectname_sdk.utility.prepare_method import allowed
 
 
 def make_spec_util(ctx):
@@ -50,11 +51,11 @@ def make_spec_util(ctx):
 
     ctx.spec.method = utility.prepare_method(ctx)
 
-    allow_method = vs.getpath(options, "allow.method") or ""
-    if isinstance(allow_method, str) and ctx.spec.method not in allow_method:
+    allow_method = vs.getpath(options, "allow.method")
+    if not allowed(allow_method, ctx.spec.method):
         return None, ctx.make_error("spec_method_allow",
-            'Method "' + ctx.spec.method +
-            '" not allowed by SDK option allow.method value: "' + allow_method + '"')
+            'Method "' + str(ctx.spec.method) +
+            '" not allowed by SDK option allow.method value: "' + str(allow_method) + '"')
 
     ctx.spec.params = utility.prepare_params(ctx)
     ctx.spec.query = utility.prepare_query(ctx)
@@ -79,9 +80,16 @@ def make_spec_util(ctx):
     if ctx.ctrl.explain is not None:
         ctx.ctrl.explain["spec"] = ctx.spec
 
+    # Whatever prepare_auth sets in the query, under whichever name, is the
+    # credential; a key it leaves as it was is the caller's.
+    query = dict(ctx.spec.query or {})
+
     spec, err = utility.prepare_auth(ctx)
     if err is not None:
         return None, err
 
+    spec.authquery = [k for k, v in (spec.query or {}).items()
+                      if k not in query or query[k] != v]
+
     ctx.spec = spec
     return spec, None

package/project/.sdk/tm/py/pkg/utility/make_url.py

@@ -1,9 +1,14 @@
 # ProjectName SDK utility: make_url
 
 from __future__ import annotations
+import re
+
 from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
 
 
+_PLACEHOLDER = re.compile(r"\{[^{}/]+\}")
+
+
 def make_url_util(ctx):
     spec = ctx.spec
     result = ctx.result
@@ -18,6 +23,9 @@ def make_url_util(ctx):
     url = vs.join([spec.base, spec.prefix, spec.path, spec.suffix], "/", True)
     resmatch = {}
 
+    # Sent with the request, never recorded as the entity's match.
+    authquery = getattr(spec, "authquery", None) or []
+
     # A route the definition ends with a slash keeps it: a server such as a
     # Django REST one redirects or refuses the route without it.
     orig = vs.getprop(ctx.point, "orig") if ctx.point is not None else None
@@ -36,6 +44,15 @@ def make_url_util(ctx):
                 url = url.replace("{" + key + "}", encoded)
                 resmatch[key] = val
 
+    # 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.
+    base = spec.base.rstrip("/") if isinstance(spec.base, str) else ""
+    route = url[len(base):] if url.startswith(base) else url
+    unfilled = _PLACEHOLDER.findall(route)
+    if 0 < len(unfilled):
+        return "", ctx.make_error("url_param_missing",
+            "URL path has no value for " + ", ".join(unfilled) + ".")
+
     # Append query string from spec.query.
     qsep = "?"
     query_items = vs.items(getattr(spec, "query", None))
@@ -47,7 +64,8 @@ def make_url_util(ctx):
                 val_str = val if isinstance(val, str) else str(val)
                 url += qsep + vs.escurl(key) + "=" + vs.escurl(val_str)
                 qsep = "&"
-                resmatch[key] = val
+                if key not in authquery:
+                    resmatch[key] = val
 
     result.resmatch = resmatch
 

package/project/.sdk/tm/py/pkg/utility/media.py

@@ -0,0 +1,88 @@
+# ProjectName SDK utility: media
+
+# 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.
+
+from __future__ import annotations
+from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
+
+
+# The data key holding a raw request body. Like `$action`, it can never be a
+# declared argument name.
+RAW_BODY = "$body"
+
+
+def is_json_media(media):
+    m = str(media if media is not None else "").split(";")[0].strip().lower()
+    return m == "application/json" or m == "text/json" or m.endswith("+json")
+
+
+# The declared JSON type alone, else every declared type in the model's
+# order; None when no success response declares a body.
+def accept_of(point):
+    res = vs.getprop(point, "response")
+    media = vs.getprop(res, "media")
+    if not isinstance(media, str) or media == "":
+        return None
+    if vs.getprop(res, "kind") == "json":
+        return media
+    types = [media]
+    alts = vs.getprop(res, "alternatives")
+    if isinstance(alts, list):
+        for alt in alts:
+            m = vs.getprop(alt, "media")
+            if isinstance(m, str) and m != "":
+                types.append(m)
+    return ", ".join(types)
+
+
+def is_raw_request(point):
+    return vs.getpath(point, "body.kind") == "raw"
+
+
+def is_json_request(point):
+    return vs.getpath(point, "body.kind") == "json"
+
+
+# Bytes or a file object go as given. A dict or a list is JSON, and so is a
+# scalar on a point that declares a JSON body.
+def request_body(point, body):
+    if isinstance(body, (bytes, bytearray, memoryview)) or callable(getattr(body, "read", None)):
+        return body
+    if vs.isnode(body) or is_json_request(point):
+        return vs.jsonify(body)
+    return body
+
+
+def _has_header(headers, name):
+    return any(isinstance(k, str) and k.lower() == name for k in headers)
+
+
+# A caller's accept wins. A declared request type replaces each JSON
+# content-type, the SDK default, and leaves any other the caller set.
+def media_headers(point, headers):
+    accept = accept_of(point)
+    if accept is not None and not _has_header(headers, "accept"):
+        headers["accept"] = accept
+
+    body = vs.getprop(point, "body")
+    kind = vs.getprop(body, "kind")
+    media = vs.getprop(body, "media")
+    if kind in ("raw", "json") and isinstance(media, str) and media != "":
+        for key in [k for k in headers if isinstance(k, str) and k.lower() == "content-type"
+                    and is_json_media(headers[k])]:
+            del headers[key]
+        if not _has_header(headers, "content-type"):
+            headers["content-type"] = media
+
+    return headers
+
+
+# Bytes, a file object or a string, sent as they are. A file object can be read
+# once, so it is read here, before the first attempt, and a retry sends the
+# same bytes again.
+def raw_body(reqdata):
+    body = reqdata.get(RAW_BODY) if isinstance(reqdata, dict) else None
+    if body is not None and callable(getattr(body, "read", None)):
+        return body.read()
+    return body

package/project/.sdk/tm/py/pkg/utility/param.py

@@ -6,13 +6,6 @@ from projectname_sdk.core.helpers import to_map
 
 
 def param_util(ctx, paramdef):
-    point = ctx.point
-    spec = ctx.spec
-    match = ctx.match
-    reqmatch = ctx.reqmatch
-    data = ctx.data
-    reqdata = ctx.reqdata
-
     pt = vs.typify(paramdef)
     key = ""
 
@@ -23,33 +16,69 @@ def param_util(ctx, paramdef):
         if isinstance(k, str):
             key = k
 
-    akey = ""
+    akey = _param_alias(ctx.point, key)
+    if ctx.spec is not None and akey != "" and \
+            vs.getprop(ctx.reqmatch, key) is None and vs.getprop(ctx.match, key) is None:
+        ctx.spec.alias[akey] = key
+
+    return param_value(ctx, ctx.point, key)
+
+
+def _param_alias(point, key):
+    # The name a point gives a parameter in the call, if it renames it.
     if point is not None:
         alias = to_map(vs.getprop(point, "alias"))
         if alias is not None:
             ak = vs.getprop(alias, key)
             if isinstance(ak, str):
-                akey = ak
+                return ak
+    return ""
 
-    val = vs.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.
+def param_value(ctx, point, key):
+    akey = _param_alias(point, key)
+
+    val = vs.getprop(ctx.reqmatch, key)
 
     if val is None:
-        val = vs.getprop(match, key)
+        val = vs.getprop(ctx.match, key)
 
     if val is None and akey != "":
-        if spec is not None:
-            spec.alias[akey] = key
-        val = vs.getprop(reqmatch, akey)
+        val = vs.getprop(ctx.reqmatch, akey)
 
     if val is None:
-        val = vs.getprop(reqdata, key)
+        val = vs.getprop(ctx.reqdata, key)
 
     if val is None:
-        val = vs.getprop(data, key)
+        val = vs.getprop(ctx.data, key)
 
     if val is None and akey != "":
-        val = vs.getprop(reqdata, akey)
+        val = vs.getprop(ctx.reqdata, akey)
         if val is None:
-            val = vs.getprop(data, akey)
+            val = vs.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.
+def call_args(ctx, kind):
+    out = []
+    defs = vs.getpath(ctx.point, "args." + kind) if ctx.point is not None else None
+    if isinstance(defs, list):
+        for ad in defs:
+            name = vs.getprop(ad, "name")
+            if not isinstance(name, str) or name == "":
+                continue
+            wire = vs.getprop(ad, "orig")
+            if not isinstance(wire, str) or wire == "":
+                wire = name
+            val = vs.getprop(ctx.reqmatch or {}, name)
+            if val is None:
+                val = vs.getprop(ctx.reqdata or {}, name)
+            out.append((name, wire, val))
+    return out

package/project/.sdk/tm/py/pkg/utility/prepare_body.py

@@ -1,10 +1,14 @@
 # ProjectName SDK utility: prepare_body
 
+from projectname_sdk.utility.media import is_raw_request, raw_body
+
 
 def prepare_body_util(ctx):
     op = ctx.op
 
     if op.input == "data":
+        if is_raw_request(ctx.point):
+            return raw_body(ctx.reqdata)
         body = ctx.utility.transform_request(ctx)
         return body
 

package/project/.sdk/tm/py/pkg/utility/prepare_headers.py

@@ -2,6 +2,22 @@
 
 from __future__ import annotations
 from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.utility.param import call_args
+from projectname_sdk.utility.media import media_headers
+
+
+# The form style of a cookie parameter: a list repeats the name, a map sends
+# its own keys, and every value is percent-encoded.
+def _cookie_pair(wire, val):
+    def esc(v):
+        return vs.escurl(vs.stringify(v))
+    if vs.islist(val):
+        pairs = [wire + "=" + esc(item) for item in val]
+    elif vs.ismap(val):
+        pairs = [vs.escurl(key) + "=" + esc(val[key]) for key in vs.keysof(val)]
+    else:
+        pairs = [wire + "=" + esc(val)]
+    return "; ".join(pairs)
 
 
 def prepare_headers_util(ctx):
@@ -13,26 +29,46 @@ def prepare_headers_util(ctx):
         cloned = vs.clone(headers)
         if isinstance(cloned, dict):
             out = cloned
+    out = media_headers(ctx.point, out)
+
+    # A header argument replaces a default of the same name, whatever its case.
+    for _name, orig, val in call_args(ctx, "header"):
+        if val is not None:
+            wire = orig.lower()
+            for key in [k for k in out if isinstance(k, str) and k.lower() == wire]:
+                del out[key]
+            out[wire] = vs.stringify(val)
 
-    # 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.
-    hl = vs.getpath(ctx.point, "args.header") if ctx.point is not None else None
-    if isinstance(hl, list):
-        for hd in hl:
-            name = vs.getprop(hd, "name")
-            if not isinstance(name, str) or name == "":
-                continue
-            orig = vs.getprop(hd, "orig")
-            if not isinstance(orig, str) or orig == "":
-                orig = name
-            val = vs.getprop(ctx.reqmatch or {}, name)
-            if val is None:
-                val = vs.getprop(ctx.reqdata or {}, name)
-            if val is not None:
-                wire = orig.lower()
-                for key in [k for k in out if isinstance(k, str) and k.lower() == wire]:
-                    del out[key]
-                out[wire] = vs.stringify(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.
+    sent = [(orig, val) for _name, orig, val in call_args(ctx, "cookie") if val is not None]
+    if sent:
+        names = [n for orig, val in sent
+                 for n in ([vs.escurl(k) for k in vs.keysof(val)] if vs.ismap(val) else [orig])]
+        kept = []
+        for key in [k for k in out if isinstance(k, str) and k.lower() == "cookie"]:
+            given = out.pop(key)
+            if isinstance(given, str):
+                kept.extend(cookie_keep(given, names))
+        for orig, val in sent:
+            pair = _cookie_pair(orig, val)
+            if pair != "":
+                kept.append(pair)
+        if kept:
+            out["cookie"] = "; ".join(kept)
 
     return out
+
+
+def cookie_keep(header, names):
+    """The caller's cookie pieces with the named cookies removed.
+
+    A cookie is one ;-delimited piece, whatever its value holds.
+    """
+    kept = []
+    for piece in header.split(";"):
+        cookie = piece.strip()
+        if cookie != "" and cookie.split("=", 1)[0].strip() not in names:
+            kept.append(cookie)
+    return kept

package/project/.sdk/tm/py/pkg/utility/prepare_method.py

@@ -27,3 +27,10 @@ def prepare_method_util(ctx):
     # The silent-pass inline runner hid a stray "GET" fallback here; the
     # shared corpus (prepareMethod, opname "bad" -> null) pins it now.
     return METHOD_MAP.get(opname)
+
+
+# Whether a comma-separated allow option names the item: whole names, any case.
+def allowed(names, item):
+    want = item.upper() if isinstance(item, str) else ""
+    return "" != want and isinstance(names, str) and any(
+        name.strip().upper() == want for name in names.split(","))

package/project/.sdk/tm/py/pkg/utility/prepare_query.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
+from projectname_sdk.utility.param import call_args
 
 
 def _contains_param(params, s):
@@ -29,14 +30,17 @@ def prepare_query_util(ctx):
                 name = vs.getprop(pd, "name")
                 if isinstance(name, str):
                     params.append(name)
-        # A header parameter travels in the headers, which prepare_headers
-        # fills.
-        hl = vs.getpath(point, "args.header")
-        if isinstance(hl, list):
-            for hd in hl:
-                name = vs.getprop(hd, "name")
-                if isinstance(name, str):
-                    params.append(name)
+        # A header or cookie parameter travels in the headers, which
+        # prepare_headers fills, unless a query parameter shares its name:
+        # then both are sent.
+        ql = vs.getpath(point, "args.query")
+        declared = [vs.getprop(qd, "name") for qd in ql] if isinstance(ql, list) else []
+        for located in (vs.getpath(point, "args.header"), vs.getpath(point, "args.cookie")):
+            if isinstance(located, list):
+                for hd in located:
+                    name = vs.getprop(hd, "name")
+                    if isinstance(name, str) and name not in declared:
+                        params.append(name)
 
     # A query parameter travels under the name the definition gives it, its
     # orig, which the model may have renamed for the caller.
@@ -60,4 +64,9 @@ def prepare_query_util(ctx):
                     and not _contains_param(params, key):
                 out[wire.get(key, key)] = val
 
+    # A create or update passes its query arguments in its data.
+    for name, orig, val in call_args(ctx, "query"):
+        if val is not None and not _contains_param(params, name):
+            out[orig] = val
+
     return out

package/project/.sdk/tm/py/pkg/utility/result_body.py

@@ -1,5 +1,10 @@
 # ProjectName SDK utility: result_body
 
+import re
+
+
+PREVIEW_LENGTH = 160
+
 
 def result_body_util(ctx):
     response = ctx.response
@@ -9,5 +14,51 @@ def result_body_util(ctx):
         if response is not None and response.json_func is not None and response.body is not None:
             json_data = response.json_func()
             result.body = json_data
+        if response is not None and getattr(response, "unreadable", False):
+            sent = ctx.spec.headers if ctx.spec is not None else None
+            result.err = unreadable_body(ctx, result.status, result.headers, response.body,
+                                         sent, 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.
+def unreadable_body(ctx, status, headers, text, sent, failed):
+    ctype = _header_value(headers, "content-type")
+    agent = ctx.utility.clean(ctx, _header_value(sent, "user-agent")) or "transport default"
+    detail = ("HTTP " + str(status) + ", content-type " + (ctype or "none") +
+              ", user-agent " + str(agent) +
+              ("" if text is None else ", body: " + _preview(ctx, text)))
+
+    if failed is not None:
+        if isinstance(failed, str):
+            return failed + " (" + detail + ")"
+        message = str(failed) + " (" + detail + ")"
+        if hasattr(failed, "msg"):
+            failed.msg = message
+        failed.args = (message,)
+        return failed
+
+    if "" == ctype or "json" in ctype.lower():
+        return ctx.make_error("response_json_invalid",
+                              "response: body is not valid JSON (" + detail + ")")
+    return ctx.make_error("response_content_type",
+                          "response: expected JSON, got " + ctype + " (" + detail + ")")
+
+
+def _header_value(headers, name):
+    if not isinstance(headers, dict):
+        return ""
+    for key, val in headers.items():
+        if name == str(key).lower():
+            return str(val)
+    return ""
+
+
+# Cleaned whole: a secret the bound would split could leave its prefix.
+def _preview(ctx, text):
+    flat = ctx.utility.clean(ctx, re.sub(r"\s+", " ", str(text)).strip())
+    flat = str(flat)
+    return flat[:PREVIEW_LENGTH] + "..." if len(flat) > PREVIEW_LENGTH else flat

package/project/.sdk/tm/py/pkg/utility/transform_request.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 from projectname_sdk.utility.voxgig_struct import voxgig_struct as vs
 from projectname_sdk.core.helpers import to_map
+from projectname_sdk.utility.param import call_args
 
 
 # `$action` selects the point (see make_point_util); it is never an API field,
@@ -11,14 +12,22 @@ def _strip_action(reqdata):
     return _omit(reqdata, ["$action"])
 
 
-# A header argument travels as a header, which prepare_headers_util sends, so
-# the body is built from the request data without it.
-def _header_arg_names(point):
-    hl = vs.getpath(point, "args.header") if point is not None else None
-    if not isinstance(hl, list):
-        return []
-    names = [vs.getprop(hd, "name") for hd in hl]
-    return [n for n in names if isinstance(n, str) and n != ""]
+# A header, cookie or query argument travels where prepare_headers_util or
+# prepare_query_util sends it, so the body is built from the request data
+# without it, unless the entity declares it as a field too.
+def _routed_arg_names(ctx):
+    return [name for name, _orig, _val in
+            call_args(ctx, "header") + call_args(ctx, "cookie") + call_args(ctx, "query")
+            if not _field_arg(ctx, name)]
+
+
+def _field_arg(ctx, name):
+    for kind in ("header", "cookie", "query"):
+        defs = vs.getpath(ctx.point, "args." + kind) if ctx.point is not None else None
+        for arg in defs if isinstance(defs, list) else []:
+            if vs.getprop(arg, "name") == name and vs.getprop(arg, "field") is True:
+                return True
+    return False
 
 
 def _omit(reqdata, names):
@@ -34,7 +43,7 @@ def transform_request_util(ctx):
     if spec is not None:
         spec.step = "reqform"
 
-    data = _omit(ctx.reqdata, _header_arg_names(point))
+    data = _omit(ctx.reqdata, _routed_arg_names(ctx))
 
     transform = to_map(vs.getprop(point, "transform"))
     if transform is None:

package/project/.sdk/tm/py/test/feature_harness.py

@@ -97,7 +97,7 @@ def recording_server(reply=None):
 def default_method(op):
     if op == "create":
         return "POST"
-    if op == "update":
+    if op == "update" or op == "patch":
         return "PATCH"
     if op == "remove":
         return "DELETE"

package/project/.sdk/tm/py/test/runner.py

@@ -13,7 +13,7 @@ class ProjectNameTestRunner:
     @staticmethod
     def load_env_local():
         try:
-            with open("../../.env.local", "r") as f:
+            with open("../../.env.local", "r", encoding="utf-8") as f:
                 content = f.read()
         except (FileNotFoundError, IOError):
             return
@@ -74,7 +74,7 @@ class ProjectNameTestRunner:
             return ProjectNameTestRunner._test_control
         ctrl_path = os.path.join(os.path.dirname(__file__), "sdk-test-control.json")
         try:
-            with open(ctrl_path, "r") as f:
+            with open(ctrl_path, "r", encoding="utf-8") as f:
                 ProjectNameTestRunner._test_control = json.load(f)
         except (FileNotFoundError, IOError, ValueError):
             ProjectNameTestRunner._test_control = {
@@ -195,3 +195,78 @@ def live_client_options():
 
 def live_delay_ms():
     return ProjectNameTestRunner.live_delay_ms()
+
+
+def live_miss(strict, reason):
+    """A live check that did not pass, as main.kit.test.live.strict decides:
+    strict fails the test, lenient skips it with the same reason."""
+    import pytest
+    if strict:
+        pytest.fail(reason, pytrace=False)
+    pytest.skip(reason)
+
+
+def live_empty(reason):
+    """An account holding no record for the test to read skips either way."""
+    import pytest
+    pytest.skip(reason)
+
+
+def live_list(data):
+    """A live list response's records: the body, or the first list an
+    envelope object holds."""
+    if isinstance(data, list):
+        return data
+    if isinstance(data, dict):
+        for value in data.values():
+            if isinstance(value, list):
+                return value
+    return None
+
+
+def live_describe(result):
+    """A live response for a message: the SDK's error, or else its status
+    and content type, never its body."""
+    err = result.get("err") if isinstance(result, dict) else None
+    if err is not None:
+        return str(err)
+    headers = result.get("headers") if isinstance(result, dict) else None
+    ctype = None
+    if isinstance(headers, dict):
+        ctype = next((v for k, v in headers.items() if str(k).lower() == "content-type"), None)
+    return "HTTP " + str(result.get("status") if isinstance(result, dict) else None) + \
+        (" " + str(ctype).split(";")[0].strip() if ctype else "")
+
+
+def live_existing(setup, strict, name, list_call):
+    """Finds the record a create-less flow reads live: the first its list
+    returns, put where the flow reads the fixture's existing records."""
+    try:
+        found = list_call()
+    except Exception as err:
+        live_miss(strict, f"Live list discovery failed: {err}")
+    if not isinstance(found, list):
+        live_miss(strict, "Live list discovery returned no list")
+    if 0 == len(found):
+        live_empty(f"The account has no {name} record to load")
+    existing = setup["data"].setdefault("existing", {})
+    existing[name] = {"live01": entity_data(found[0])}
+
+
+def live_observe(live_env, strict):
+    """A flow test decorator: in a lenient live run a failing check skips
+    the test, observing the live API rather than failing on it."""
+    import functools
+
+    def wrap(fn):
+        @functools.wraps(fn)
+        def run(*args, **kwargs):
+            try:
+                return fn(*args, **kwargs)
+            except Exception as err:
+                if strict or "TRUE" != os.environ.get(live_env):
+                    raise
+                import pytest
+                pytest.skip(f"live run, main.kit.test.live.strict is false: {err!r}")
+        return run
+    return wrap