@voxgig/sdkgen 4.34.0 → 4.34.1

package/project/.sdk/tm/php/utility/Fetcher.php

@@ -32,6 +32,9 @@ class ProjectNameFetcher
     {
         $method_str = strtoupper($fetchdef['method'] ?? 'GET');
         $body_str = $fetchdef['body'] ?? null;
+        if (is_resource($body_str)) {
+            $body_str = stream_get_contents($body_str);
+        }
         $headers = $fetchdef['headers'] ?? [];
 
         $header_lines = [];
@@ -83,8 +86,16 @@ class ProjectNameFetcher
         }
 
         $context = stream_context_create($opts);
+        error_clear_last();
         $response_body = @file_get_contents($fullurl, false, $context);
 
+        // A request that got no answer fails the operation. The stream
+        // wrapper's warning names the URL, which is left out.
+        if ($response_body === false) {
+            $warning = error_get_last()['message'] ?? 'request failed';
+            return [null, preg_replace('/^file_get_contents\(.*?\):\s*/', '', $warning)];
+        }
+
         $status = 0;
         $status_text = '';
         $resp_headers = [];
@@ -108,10 +119,13 @@ class ProjectNameFetcher
         }
 
         $json_body = null;
-        if ($response_body !== false && $response_body !== '') {
+        $unreadable = false;
+        if (trim($response_body) !== '') {
             $decoded = json_decode($response_body, true);
             if (json_last_error() === JSON_ERROR_NONE) {
                 $json_body = $decoded;
+            } else {
+                $unreadable = true;
             }
         }
 
@@ -121,7 +135,8 @@ class ProjectNameFetcher
                 'statusText' => $status_text,
                 'headers' => $resp_headers,
                 'json' => function () use ($json_body) { return $json_body; },
-                'body' => $response_body !== false ? $response_body : '',
+                'body' => $response_body,
+                'unreadable' => $unreadable,
             ],
             null,
         ];
@@ -201,10 +216,13 @@ class ProjectNameFetcher
         }
 
         $json_body = null;
-        if ($response_body !== '' && $response_body !== false) {
+        $unreadable = false;
+        if ($response_body !== false && trim((string)$response_body) !== '') {
             $decoded = json_decode($response_body, true);
             if (json_last_error() === JSON_ERROR_NONE) {
                 $json_body = $decoded;
+            } else {
+                $unreadable = true;
             }
         }
 
@@ -215,6 +233,7 @@ class ProjectNameFetcher
                 'headers' => $resp_kv,
                 'json' => function () use ($json_body) { return $json_body; },
                 'body' => (string)$response_body,
+                'unreadable' => $unreadable,
             ],
             null,
         ];
@@ -239,9 +258,10 @@ class ProjectNameFetcher
         // fall through to the default HTTP fetcher. The options builder
         // sometimes materializes `system.fetch` as an empty stdClass even
         // when the user didn't set one — that's a placeholder, not a value.
-        $is_empty_obj = ($sys_fetch instanceof \stdClass) && empty(get_object_vars($sys_fetch));
-        $is_empty_arr = is_array($sys_fetch) && empty($sys_fetch);
-        if ($sys_fetch === null || $is_empty_obj || $is_empty_arr) {
+        if (self::usesDefault($ctx)) {
+            if (null !== $ctx->spec) {
+                $ctx->spec->headers = self::sentHeaders($ctx->spec->headers);
+            }
             return self::defaultHttpFetch($fullurl, $fetchdef);
         }
         if (is_callable($sys_fetch)) {
@@ -250,4 +270,26 @@ class ProjectNameFetcher
 
         return [null, $ctx->make_error('fetch_invalid', 'system.fetch is not a valid function')];
     }
+
+    public static function usesDefault(ProjectNameContext $ctx): bool
+    {
+        $sys_fetch = \Voxgig\Struct\Struct::getpath($ctx->client->options_map(), 'system.fetch');
+        $is_empty_obj = ($sys_fetch instanceof \stdClass) && empty(get_object_vars($sys_fetch));
+        $is_empty_arr = is_array($sys_fetch) && empty($sys_fetch);
+        return $sys_fetch === null || $is_empty_obj || $is_empty_arr;
+    }
+
+    // The headers the default transport sends: the request's own, with its
+    // agent when they name none. A request's headers travel by value, so the
+    // transport cannot record the agent where the response is read.
+    public static function sentHeaders(array $headers): array
+    {
+        foreach ($headers as $k => $v) {
+            if (is_string($v) && strcasecmp((string)$k, 'user-agent') === 0) {
+                return $headers;
+            }
+        }
+        $headers['user-agent'] = self::DEFAULT_USER_AGENT;
+        return $headers;
+    }
 }

package/project/.sdk/tm/php/utility/MakeFetchDef.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 // ProjectName SDK utility: make_fetch_def
 
 require_once __DIR__ . '/../core/Result.php';
+require_once __DIR__ . '/Media.php';
 
 class ProjectNameMakeFetchDef
 {
@@ -28,7 +29,7 @@ class ProjectNameMakeFetchDef
 
         $fetchdef = ['url' => $url, 'method' => $spec->method, 'headers' => $spec->headers];
         if ($spec->body !== null) {
-            $fetchdef['body'] = is_array($spec->body) ? \Voxgig\Struct\Struct::jsonify($spec->body) : $spec->body;
+            $fetchdef['body'] = ProjectNameMedia::requestBody($ctx->point, $spec->body);
         }
 
         return [$fetchdef, null];

package/project/.sdk/tm/php/utility/MakePoint.php

@@ -4,9 +4,26 @@ declare(strict_types=1);
 // ProjectName SDK utility: make_point
 
 require_once __DIR__ . '/../core/Helpers.php';
+require_once __DIR__ . '/Param.php';
+require_once __DIR__ . '/PrepareMethod.php';
 
 class ProjectNameMakePoint
 {
+    // The path parameters of a point that neither the call nor the entity
+    // gives a value for, looked up as prepareParams looks them up.
+    private static function unfilled(ProjectNameContext $ctx, mixed $point): array
+    {
+        $parts = \Voxgig\Struct\Struct::getprop($point, 'parts');
+        $missing = [];
+        foreach (is_array($parts) ? $parts : [] as $part) {
+            if (is_string($part) && preg_match('/^\{([^{}\/]+)\}$/D', $part, $found) &&
+                null === ProjectNameParam::value($ctx, $point, $found[1])) {
+                $missing[] = $found[1];
+            }
+        }
+        return $missing;
+    }
+
     public static function call(ProjectNameContext $ctx): array
     {
         if (isset($ctx->out['point'])) {
@@ -24,10 +41,11 @@ class ProjectNameMakePoint
         $op = $ctx->op;
         $options = $ctx->options;
 
-        $allow_op = \Voxgig\Struct\Struct::getpath($options, 'allow.op') ?? '';
-        if (strpos($allow_op, $op->name) === false) {
+        $allow_op = \Voxgig\Struct\Struct::getpath($options, 'allow.op');
+        if (!ProjectNamePrepareMethod::allowed($allow_op, $op->name)) {
+            $shown = is_string($allow_op) ? $allow_op : '';
             return [null, $ctx->make_error('point_op_allow',
-                "Operation \"{$op->name}\" not allowed by SDK option allow.op value: \"{$allow_op}\"")];
+                "Operation \"{$op->name}\" not allowed by SDK option allow.op value: \"{$shown}\"")];
         }
 
         if (empty($op->points)) {
@@ -47,7 +65,9 @@ class ProjectNameMakePoint
                 $select_def = ProjectNameHelpers::to_map(\Voxgig\Struct\Struct::getprop($p, 'select'));
                 $found = true;
 
-                if ($selector && $select_def) {
+                // An empty stored match is falsy in PHP; the point's exist
+                // list is tested regardless.
+                if (null !== $selector && $select_def) {
                     $exist = \Voxgig\Struct\Struct::getprop($select_def, 'exist');
                     if (is_array($exist)) {
                         foreach ($exist as $ek) {
@@ -110,16 +130,40 @@ class ProjectNameMakePoint
                     $last = $parts[count($parts) - 1];
                     return is_string($last) && 0 === strpos($last, '{');
                 };
-                $point = $op->points[0];
-                foreach ($op->points as $p) {
-                    if ($terminal_param($p) !== $terminal_param($point)) {
-                        if ($terminal_param($p)) {
-                            $point = $p;
+                $own_point = function (array $points) use ($parts_len, $terminal_param) {
+                    $best = $points[0];
+                    foreach ($points as $p) {
+                        if ($terminal_param($p) !== $terminal_param($best)) {
+                            if ($terminal_param($p)) {
+                                $best = $p;
+                            }
+                        } elseif ($parts_len($p) < $parts_len($best)) {
+                            $best = $p;
                         }
-                    } elseif ($parts_len($p) < $parts_len($point)) {
-                        $point = $p;
                     }
+                    return $best;
+                };
+
+                // A call without an action falls back to a point without one,
+                // as generation does, and only to a route the call can fill.
+                $plain = array_values(array_filter($op->points, fn($p) => null ===
+                    \Voxgig\Struct\Struct::getprop(
+                        ProjectNameHelpers::to_map(\Voxgig\Struct\Struct::getprop($p, 'select')), '$action')));
+                if (0 === count($plain)) {
+                    return [null, $ctx->make_error('point_action_required',
+                        "Operation \"{$op->name}\" has only action endpoints; pass \$action to choose one.")];
+                }
+
+                $fillable = array_values(array_filter($plain,
+                    fn($p) => 0 === count(self::unfilled($ctx, $p))));
+
+                if (0 === count($fillable)) {
+                    return [null, $ctx->make_error('point_no_match',
+                        "Operation \"{$op->name}\" has no endpoint whose path parameters are all given (missing: " .
+                        implode(', ', self::unfilled($ctx, $own_point($plain))) . ").")];
                 }
+
+                $point = $own_point($fillable);
             }
 
             if ($reqselector) {

package/project/.sdk/tm/php/utility/MakeSpec.php

@@ -4,6 +4,7 @@ declare(strict_types=1);
 // ProjectName SDK utility: make_spec
 
 require_once __DIR__ . '/Graphql.php';
+require_once __DIR__ . '/PrepareMethod.php';
 
 require_once __DIR__ . '/../core/Spec.php';
 
@@ -12,6 +13,11 @@ class ProjectNameMakeSpec
     public static function call(ProjectNameContext $ctx): array
     {
         if (isset($ctx->out['spec'])) {
+            // A PreSpec hook (validate) rejects the operation by placing its
+            // error here; the pipeline raises it, and ctx->spec stays a spec.
+            if ($ctx->out['spec'] instanceof \Throwable) {
+                return [null, $ctx->out['spec']];
+            }
             $ctx->spec = $ctx->out['spec'];
             return [$ctx->spec, null];
         }
@@ -43,12 +49,12 @@ class ProjectNameMakeSpec
         // never a silently-allowed empty method.
         $method = ($utility->prepare_method)($ctx);
 
-        $allow_method = \Voxgig\Struct\Struct::getpath($options, 'allow.method') ?? '';
-        if (!is_string($method) || '' === $method
-            || strpos($allow_method, $method) === false) {
+        $allow_method = \Voxgig\Struct\Struct::getpath($options, 'allow.method');
+        if (!ProjectNamePrepareMethod::allowed($allow_method, $method)) {
             $shown = is_string($method) ? $method : '';
+            $list = is_string($allow_method) ? $allow_method : '';
             return [null, $ctx->make_error('spec_method_allow',
-                "Method \"{$shown}\" not allowed by SDK option allow.method value: \"{$allow_method}\"")];
+                "Method \"{$shown}\" not allowed by SDK option allow.method value: \"{$list}\"")];
         }
         $ctx->spec->method = $method;
 
@@ -78,11 +84,22 @@ class ProjectNameMakeSpec
             $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 = $ctx->spec->query;
+
         [$spec, $err] = ($utility->prepare_auth)($ctx);
         if ($err) {
             return [null, $err];
         }
 
+        $spec->authquery = [];
+        foreach ($spec->query as $key => $val) {
+            if (!array_key_exists($key, $query) || $query[$key] !== $val) {
+                $spec->authquery[] = $key;
+            }
+        }
+
         $ctx->spec = $spec;
         return [$spec, null];
     }

package/project/.sdk/tm/php/utility/MakeUrl.php

@@ -20,6 +20,9 @@ class ProjectNameMakeUrl
         $url = \Voxgig\Struct\Struct::join([$spec->base, $spec->prefix, $spec->path, $spec->suffix], '/', true);
         $resmatch = [];
 
+        // Sent with the request, never recorded as the entity's match.
+        $authquery = $spec->authquery ?? [];
+
         // 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 = $ctx->point ? \Voxgig\Struct\Struct::getprop($ctx->point, 'orig') : null;
@@ -42,6 +45,16 @@ class ProjectNameMakeUrl
             }
         }
 
+        // 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 = is_string($spec->base) ? rtrim($spec->base, '/') : '';
+        $route = str_starts_with($url, $base) ? substr($url, strlen($base)) : $url;
+        if (preg_match_all('/\{[^{}\/]+\}/', $route, $unfilled) > 0) {
+            return ['', $ctx->make_error('url_param_missing',
+                'URL path has no value for ' . implode(', ', $unfilled[0]) . '.')];
+        }
+
         // Append query string from spec.query.
         $qsep = '?';
         $query_items = \Voxgig\Struct\Struct::items($spec->query ?? null);
@@ -53,7 +66,9 @@ class ProjectNameMakeUrl
                     $val_str = is_string($val) ? $val : (string)$val;
                     $url .= $qsep . \Voxgig\Struct\Struct::escurl($key) . '=' . \Voxgig\Struct\Struct::escurl($val_str);
                     $qsep = '&';
-                    $resmatch[$key] = $val;
+                    if (!in_array($key, $authquery, true)) {
+                        $resmatch[$key] = $val;
+                    }
                 }
             }
         }

package/project/.sdk/tm/php/utility/Media.php

@@ -0,0 +1,111 @@
+<?php
+declare(strict_types=1);
+
+// 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.
+class ProjectNameMedia
+{
+    // The data key holding a raw request body. Like `$action`, it can never
+    // be a declared argument name.
+    public const RAW_BODY = '$body';
+
+    public static function isJsonMedia(mixed $media): bool
+    {
+        $m = strtolower(trim(explode(';', is_string($media) ? $media : '')[0]));
+        return 'application/json' === $m || 'text/json' === $m || str_ends_with($m, '+json');
+    }
+
+    // The declared JSON type alone, else every declared type in the model's
+    // order; null when no success response declares a body.
+    public static function acceptOf(mixed $point): ?string
+    {
+        $res = \Voxgig\Struct\Struct::getprop($point, 'response');
+        $media = \Voxgig\Struct\Struct::getprop($res, 'media');
+        if (!is_string($media) || '' === $media) {
+            return null;
+        }
+        if ('json' === \Voxgig\Struct\Struct::getprop($res, 'kind')) {
+            return $media;
+        }
+        $types = [$media];
+        $alts = \Voxgig\Struct\Struct::getprop($res, 'alternatives');
+        foreach (is_array($alts) ? $alts : [] as $alt) {
+            $m = \Voxgig\Struct\Struct::getprop($alt, 'media');
+            if (is_string($m) && '' !== $m) {
+                $types[] = $m;
+            }
+        }
+        return implode(', ', $types);
+    }
+
+    public static function isRawRequest(mixed $point): bool
+    {
+        return 'raw' === \Voxgig\Struct\Struct::getprop(\Voxgig\Struct\Struct::getprop($point, 'body'), 'kind');
+    }
+
+    public static function isJsonRequest(mixed $point): bool
+    {
+        return 'json' === \Voxgig\Struct\Struct::getprop(\Voxgig\Struct\Struct::getprop($point, 'body'), 'kind');
+    }
+
+    // A stream goes as given. An array or an object is JSON, and so is a
+    // scalar on a point that declares a JSON body.
+    public static function requestBody(mixed $point, mixed $body): mixed
+    {
+        if (is_resource($body)) {
+            return $body;
+        }
+        if (\Voxgig\Struct\Struct::isnode($body) || self::isJsonRequest($point)) {
+            return \Voxgig\Struct\Struct::jsonify($body);
+        }
+        return $body;
+    }
+
+    private static function hasHeader(array $headers, string $name): bool
+    {
+        foreach (array_keys($headers) as $key) {
+            if (is_string($key) && strtolower($key) === $name) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    // A caller's accept wins. A declared request type replaces each JSON
+    // content-type, the SDK default, and leaves any other the caller set.
+    public static function headers(mixed $point, array $headers): array
+    {
+        $accept = self::acceptOf($point);
+        if (null !== $accept && !self::hasHeader($headers, 'accept')) {
+            $headers['accept'] = $accept;
+        }
+
+        $body = \Voxgig\Struct\Struct::getprop($point, 'body');
+        $kind = \Voxgig\Struct\Struct::getprop($body, 'kind');
+        $media = \Voxgig\Struct\Struct::getprop($body, 'media');
+        if (('raw' === $kind || 'json' === $kind) && is_string($media) && '' !== $media) {
+            foreach (array_keys($headers) as $key) {
+                if (is_string($key) && 'content-type' === strtolower($key) &&
+                    self::isJsonMedia($headers[$key])) {
+                    unset($headers[$key]);
+                }
+            }
+            if (!self::hasHeader($headers, 'content-type')) {
+                $headers['content-type'] = $media;
+            }
+        }
+
+        return $headers;
+    }
+
+    // A string of bytes or text, or a stream, sent as it is. A stream can be
+    // read once, so it is read here, before the first attempt, and a retry
+    // sends the same bytes again.
+    public static function rawBody(mixed $reqdata): mixed
+    {
+        $body = is_array($reqdata) ? ($reqdata[self::RAW_BODY] ?? null) : null;
+        return is_resource($body) ? stream_get_contents($body) : $body;
+    }
+}

package/project/.sdk/tm/php/utility/Param.php

@@ -9,13 +9,6 @@ class ProjectNameParam
 {
     public static function call(ProjectNameContext $ctx, mixed $paramdef): mixed
     {
-        $point = $ctx->point;
-        $spec = $ctx->spec;
-        $match_val = $ctx->match;
-        $reqmatch = $ctx->reqmatch;
-        $data = $ctx->data;
-        $reqdata = $ctx->reqdata;
-
         $pt = \Voxgig\Struct\Struct::typify($paramdef);
         if ((\Voxgig\Struct\Struct::T_string & $pt) > 0) {
             $key = $paramdef;
@@ -24,45 +17,91 @@ class ProjectNameParam
             $key = is_string($k) ? $k : '';
         }
 
-        $akey = '';
+        $akey = self::alias($ctx->point, $key);
+        if ($ctx->spec && $akey !== '' &&
+            self::absent(\Voxgig\Struct\Struct::getprop($ctx->reqmatch, $key)) &&
+            self::absent(\Voxgig\Struct\Struct::getprop($ctx->match, $key))) {
+            $ctx->spec->alias_map[$akey] = $key;
+        }
+
+        return self::value($ctx, $ctx->point, $key);
+    }
+
+    // The name a point gives a parameter in the call, if it renames it.
+    private static function alias(mixed $point, string $key): string
+    {
         if ($point) {
             $alias_map = ProjectNameHelpers::to_map(\Voxgig\Struct\Struct::getprop($point, 'alias'));
             if ($alias_map) {
                 $ak = \Voxgig\Struct\Struct::getprop($alias_map, $key);
                 if (is_string($ak)) {
-                    $akey = $ak;
+                    return $ak;
                 }
             }
         }
+        return '';
+    }
 
-        $undef = '__UNDEFINED__';
+    private static function absent(mixed $val): bool
+    {
+        return $val === null || $val === '__UNDEFINED__';
+    }
 
-        $val = \Voxgig\Struct\Struct::getprop($reqmatch, $key);
-        if ($val === null || $val === $undef) {
-            $val = \Voxgig\Struct\Struct::getprop($match_val, $key);
+    // The value the call or its entity gives a point's parameter, under its
+    // name or the point's alias for it.
+    public static function value(ProjectNameContext $ctx, mixed $point, string $key): mixed
+    {
+        $akey = self::alias($point, $key);
+
+        $val = \Voxgig\Struct\Struct::getprop($ctx->reqmatch, $key);
+        if (self::absent($val)) {
+            $val = \Voxgig\Struct\Struct::getprop($ctx->match, $key);
         }
 
-        if (($val === null || $val === $undef) && $akey !== '') {
-            if ($spec) {
-                $spec->alias_map[$akey] = $key;
-            }
-            $val = \Voxgig\Struct\Struct::getprop($reqmatch, $akey);
+        if (self::absent($val) && $akey !== '') {
+            $val = \Voxgig\Struct\Struct::getprop($ctx->reqmatch, $akey);
         }
 
-        if ($val === null || $val === $undef) {
-            $val = \Voxgig\Struct\Struct::getprop($reqdata, $key);
+        if (self::absent($val)) {
+            $val = \Voxgig\Struct\Struct::getprop($ctx->reqdata, $key);
         }
-        if ($val === null || $val === $undef) {
-            $val = \Voxgig\Struct\Struct::getprop($data, $key);
+        if (self::absent($val)) {
+            $val = \Voxgig\Struct\Struct::getprop($ctx->data, $key);
         }
 
-        if (($val === null || $val === $undef) && $akey !== '') {
-            $val = \Voxgig\Struct\Struct::getprop($reqdata, $akey);
-            if ($val === null || $val === $undef) {
-                $val = \Voxgig\Struct\Struct::getprop($data, $akey);
+        if (self::absent($val) && $akey !== '') {
+            $val = \Voxgig\Struct\Struct::getprop($ctx->reqdata, $akey);
+            if (self::absent($val)) {
+                $val = \Voxgig\Struct\Struct::getprop($ctx->data, $akey);
             }
         }
 
-        return ($val === $undef) ? null : $val;
+        return self::absent($val) ? null : $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.
+    public static function callArgs(ProjectNameContext $ctx, string $kind): array
+    {
+        $defs = $ctx->point ? \Voxgig\Struct\Struct::getpath($ctx->point, 'args.' . $kind) : null;
+        $out = [];
+        foreach (is_array($defs) ? $defs : [] as $ad) {
+            $name = \Voxgig\Struct\Struct::getprop($ad, 'name');
+            if (!is_string($name) || '' === $name) {
+                continue;
+            }
+            $wire = \Voxgig\Struct\Struct::getprop($ad, 'orig');
+            if (!is_string($wire) || '' === $wire) {
+                $wire = $name;
+            }
+            $val = \Voxgig\Struct\Struct::getprop($ctx->reqmatch ?? [], $name);
+            if (null === $val) {
+                $val = \Voxgig\Struct\Struct::getprop($ctx->reqdata ?? [], $name);
+            }
+            $out[] = [$name, $wire, $val];
+        }
+        return $out;
     }
 }

package/project/.sdk/tm/php/utility/PrepareBody.php

@@ -3,11 +3,16 @@ declare(strict_types=1);
 
 // ProjectName SDK utility: prepare_body
 
+require_once __DIR__ . '/Media.php';
+
 class ProjectNamePrepareBody
 {
     public static function call(ProjectNameContext $ctx): mixed
     {
         if ($ctx->op->input === 'data') {
+            if (ProjectNameMedia::isRawRequest($ctx->point)) {
+                return ProjectNameMedia::rawBody($ctx->reqdata);
+            }
             $body = ($ctx->utility->transform_request)($ctx);
             // PHP cannot tell an empty map from an empty list, and this
             // vendored struct answers [] where the canonical transform