@voxgig/sdkgen 1.3.7 → 1.3.9

package/project/.sdk/tm/php/core/Result.php

@@ -14,6 +14,13 @@ class ProjectNameResult
     public mixed $resdata;
     public ?array $resmatch;
 
+    // Feature extensions: pagination info (paging feature) and a Generator
+    // factory closure (streaming feature). Null/false when the features are
+    // inactive or the operation is not a list.
+    public mixed $paging;
+    public bool $streaming;
+    public mixed $stream;
+
     public function __construct(array $resmap = [])
     {
         $this->ok = \Voxgig\Struct\Struct::getprop($resmap, 'ok') === true;
@@ -31,5 +38,8 @@ class ProjectNameResult
         $this->resdata = ($rd === '__UNDEFINED__' || $rd === null) ? null : $rd;
         $rm = \Voxgig\Struct\Struct::getprop($resmap, 'resmatch');
         $this->resmatch = is_array($rm) ? $rm : null;
+        $this->paging = null;
+        $this->streaming = false;
+        $this->stream = null;
     }
 }

package/project/.sdk/tm/php/feature/AuditFeature.php

@@ -0,0 +1,125 @@
+<?php
+declare(strict_types=1);
+
+// ProjectName SDK audit feature
+
+require_once __DIR__ . '/BaseFeature.php';
+
+// Audit trail. Emits one structured record per operation — who (actor),
+// what (entity + op), the outcome, and a correlation id — suitable for
+// compliance logging. Records accumulate on `client->_audit['records']`
+// (bounded by `max`, default 1000) and, when a `sink` callback is supplied,
+// are also pushed to it (e.g. to forward to a SIEM). The actor is taken
+// from a per-call `ctrl->actor`, then options `actor`, then 'anonymous'.
+// Timestamps use the injectable `now` clock so tests stay deterministic.
+// Mirrors ts/src/feature/audit/AuditFeature.ts.
+class ProjectNameAuditFeature extends ProjectNameBaseFeature
+{
+    private mixed $client;
+    private ?array $options;
+    private int $seq;
+    private ?\WeakMap $seen;
+
+    public function __construct()
+    {
+        parent::__construct();
+        $this->version = '0.0.1';
+        $this->name = 'audit';
+        $this->active = true;
+        $this->client = null;
+        $this->options = null;
+        $this->seq = 0;
+        $this->seen = null;
+    }
+
+    public function init(ProjectNameContext $ctx, array $options): void
+    {
+        $this->client = $ctx->client;
+        $this->options = $options;
+        $this->active = ($options['active'] ?? null) === true;
+        $this->seq = 0;
+        $this->seen = new \WeakMap();
+
+        if (!$this->active) {
+            return;
+        }
+
+        $client = $this->client;
+        if (!isset($client->_audit)) {
+            $client->_audit = ['records' => []];
+        }
+    }
+
+    public function PreDone(ProjectNameContext $ctx): void
+    {
+        if (!$this->active) {
+            return;
+        }
+        // Outcome reflects the actual result; a non-2xx reaches PreDone
+        // before the pipeline raises.
+        $ok = $ctx->result !== null && $ctx->result->ok !== false && $ctx->result->err === null;
+        $this->_emit($ctx, $ok ? 'ok' : 'error');
+    }
+
+    public function PreUnexpected(ProjectNameContext $ctx): void
+    {
+        if (!$this->active) {
+            return;
+        }
+        $this->_emit($ctx, 'error');
+    }
+
+    private function _emit(ProjectNameContext $ctx, string $outcome): void
+    {
+        // One record per operation (PreDone + a following PreUnexpected on a
+        // non-2xx must not double-log).
+        if ($this->seen === null || isset($this->seen[$ctx])) {
+            return;
+        }
+        $this->seen[$ctx] = true;
+        $this->seq++;
+
+        // ctrl->actor is an optional extension property on the control
+        // object; absent means "not set per call".
+        $ctrl_actor = $ctx->ctrl->actor ?? null;
+        $actor = (is_string($ctrl_actor) && $ctrl_actor !== '') ? $ctrl_actor
+            : ($this->options['actor'] ?? null);
+        $actor = (is_string($actor) && $actor !== '') ? $actor : 'anonymous';
+
+        $record = [
+            'seq' => $this->seq,
+            'ts' => $this->_now(),
+            'actor' => $actor,
+            'entity' => $ctx->op->entity !== '' ? $ctx->op->entity : '_',
+            'op' => $ctx->op->name !== '' ? $ctx->op->name : '_',
+            'outcome' => $outcome,
+            'status' => $ctx->result !== null ? $ctx->result->status : null,
+            'correlationId' => $ctx->id,
+        ];
+
+        $client = $this->client;
+        $client->_audit['records'][] = $record;
+        $max = is_numeric($this->options['max'] ?? null) ? (int)$this->options['max'] : 1000;
+        while (count($client->_audit['records']) > $max) {
+            array_shift($client->_audit['records']);
+        }
+
+        $sink = $this->options['sink'] ?? null;
+        if (is_callable($sink)) {
+            try {
+                $sink($record);
+            } catch (\Throwable $_e) {
+                // Sink failures must never break the pipeline.
+            }
+        }
+    }
+
+    private function _now(): float
+    {
+        $now = $this->options['now'] ?? null;
+        if (is_callable($now)) {
+            return (float)$now();
+        }
+        return microtime(true) * 1000.0;
+    }
+}

package/project/.sdk/tm/php/feature/BaseFeature.php

@@ -9,6 +9,12 @@ class ProjectNameBaseFeature
     public string $name;
     public bool $active;
 
+    // Positions this feature when added via the client `extend` option:
+    // "__before__" / "__after__" / "__replace__" name an already-added
+    // feature (mirrors the ts feature `_options`). Declared so setting it
+    // on an extension instance avoids the dynamic-property deprecation.
+    public ?array $_options = null;
+
     public function __construct()
     {
         $this->version = '0.0.1';

package/project/.sdk/tm/php/feature/CacheFeature.php

@@ -0,0 +1,158 @@
+<?php
+declare(strict_types=1);
+
+// ProjectName SDK cache feature
+
+require_once __DIR__ . '/BaseFeature.php';
+
+// Response caching for safe (read) requests. Wraps the active transport and
+// serves a fresh cached snapshot instead of hitting the network when the
+// same method+URL was fetched within `ttl` ms (default 5000). Only
+// successful (2xx) responses to cacheable methods (default: GET) are
+// stored, keyed by method+URL. The cache is bounded (`max` entries, default
+// 256, oldest evicted first) and every hit/miss/bypass is recorded on
+// `client->_cache` for inspection. Snapshots replay through a fresh `json`
+// closure so both the current caller and later hits can read the body
+// repeatedly. Mirrors ts/src/feature/cache/CacheFeature.ts.
+class ProjectNameCacheFeature extends ProjectNameBaseFeature
+{
+    private mixed $client;
+    private ?array $options;
+    private array $store;
+
+    public function __construct()
+    {
+        parent::__construct();
+        $this->version = '0.0.1';
+        $this->name = 'cache';
+        $this->active = true;
+        $this->client = null;
+        $this->options = null;
+        $this->store = [];
+    }
+
+    public function init(ProjectNameContext $ctx, array $options): void
+    {
+        $this->client = $ctx->client;
+        $this->options = $options;
+        $this->active = ($options['active'] ?? null) === true;
+
+        if (!$this->active) {
+            return;
+        }
+
+        $this->store = [];
+
+        $utility = $ctx->utility;
+        $inner = $utility->fetcher;
+
+        $utility->fetcher = function (ProjectNameContext $ctx2, string $url, array $fetchdef) use ($inner): array {
+            return $this->_through($ctx2, $url, $fetchdef, $inner);
+        };
+    }
+
+    private function _through(ProjectNameContext $ctx, string $url, array $fetchdef, callable $inner): array
+    {
+        $method = strtoupper((string)($fetchdef['method'] ?? 'GET'));
+        $methods = $this->options['methods'] ?? ['GET'];
+
+        if (!is_array($methods) || !in_array($method, $methods, true)) {
+            return $inner($ctx, $url, $fetchdef);
+        }
+
+        $key = $method . ' ' . $url;
+        $now = $this->_now();
+        $hit = $this->store[$key] ?? null;
+
+        if ($hit !== null && $hit['expiry'] > $now) {
+            $this->_track('hit');
+            return [$this->_replay($hit['snapshot']), null];
+        }
+
+        [$res, $err] = $inner($ctx, $url, $fetchdef);
+
+        if ($this->_cacheable($res, $err)) {
+            $snapshot = $this->_snapshot($res);
+            $ttl = is_numeric($this->options['ttl'] ?? null) ? (float)$this->options['ttl'] : 5000.0;
+            $this->_evict();
+            $this->store[$key] = ['expiry' => $now + $ttl, 'snapshot' => $snapshot];
+            $this->_track('miss');
+            return [$this->_replay($snapshot), null];
+        }
+
+        $this->_track('bypass');
+        return [$res, $err];
+    }
+
+    private function _cacheable(mixed $res, mixed $err): bool
+    {
+        if ($err !== null || !is_array($res)) {
+            return false;
+        }
+        $status = $res['status'] ?? null;
+        return is_numeric($status) && (int)$status >= 200 && (int)$status < 300;
+    }
+
+    private function _snapshot(array $res): array
+    {
+        $data = null;
+        $jf = $res['json'] ?? null;
+        if (is_callable($jf)) {
+            try {
+                $data = $jf();
+            } catch (\Throwable $_e) {
+                $data = null;
+            }
+        }
+        $headers = is_array($res['headers'] ?? null) ? $res['headers'] : [];
+        return [
+            'status' => $res['status'] ?? null,
+            'statusText' => $res['statusText'] ?? '',
+            'data' => $data,
+            'headers' => $headers,
+        ];
+    }
+
+    private function _replay(array $snapshot): array
+    {
+        $data = $snapshot['data'];
+        return [
+            'status' => $snapshot['status'],
+            'statusText' => $snapshot['statusText'],
+            'body' => 'not-used',
+            // Fresh closure per replay: the body is re-readable on every hit.
+            'json' => function () use ($data) { return $data; },
+            'headers' => $snapshot['headers'],
+        ];
+    }
+
+    private function _evict(): void
+    {
+        $max = is_numeric($this->options['max'] ?? null) ? (int)$this->options['max'] : 256;
+        while (count($this->store) >= $max) {
+            $oldest = array_key_first($this->store);
+            if ($oldest === null) {
+                break;
+            }
+            unset($this->store[$oldest]);
+        }
+    }
+
+    private function _now(): float
+    {
+        $now = $this->options['now'] ?? null;
+        if (is_callable($now)) {
+            return (float)$now();
+        }
+        return microtime(true) * 1000.0;
+    }
+
+    private function _track(string $kind): void
+    {
+        $client = $this->client;
+        if (!isset($client->_cache)) {
+            $client->_cache = ['hit' => 0, 'miss' => 0, 'bypass' => 0];
+        }
+        $client->_cache[$kind]++;
+    }
+}

package/project/.sdk/tm/php/feature/ClienttrackFeature.php

@@ -0,0 +1,126 @@
+<?php
+declare(strict_types=1);
+
+// ProjectName SDK clienttrack feature
+
+require_once __DIR__ . '/BaseFeature.php';
+
+// Client tracking. Establishes a stable per-client session id at
+// construction and stamps identifying headers on every request: a
+// `User-Agent` (`<clientName>/<clientVersion>`), an `X-Client-Id`
+// (session), and a fresh per-request `X-Request-Id`. This lets a server
+// correlate all traffic from one SDK instance and each individual call.
+// Caller-provided User-Agent / X-Client-Id values are never clobbered.
+// Header names, client name/version and the id generator (`idgen`) are
+// configurable; the session id and request counter are exposed on
+// `client->_clienttrack`. Mirrors
+// ts/src/feature/clienttrack/ClienttrackFeature.ts.
+class ProjectNameClienttrackFeature extends ProjectNameBaseFeature
+{
+    private mixed $client;
+    private ?array $options;
+    private string $session;
+    private int $requests;
+
+    public function __construct()
+    {
+        parent::__construct();
+        $this->version = '0.0.1';
+        $this->name = 'clienttrack';
+        $this->active = true;
+        $this->client = null;
+        $this->options = null;
+        $this->session = '';
+        $this->requests = 0;
+    }
+
+    public function init(ProjectNameContext $ctx, array $options): void
+    {
+        $this->client = $ctx->client;
+        $this->options = $options;
+        $this->active = ($options['active'] ?? null) === true;
+        $this->requests = 0;
+    }
+
+    public function PostConstruct(ProjectNameContext $_ctx): void
+    {
+        if (!$this->active) {
+            return;
+        }
+        $sid = $this->options['sessionId'] ?? null;
+        $this->session = (is_string($sid) && $sid !== '') ? $sid : $this->_genid('session');
+        $this->client->_clienttrack = [
+            'session' => $this->session,
+            'requests' => 0,
+            'clientName' => $this->_name(),
+        ];
+    }
+
+    public function PreRequest(ProjectNameContext $ctx): void
+    {
+        if (!$this->active) {
+            return;
+        }
+        $spec = $ctx->spec;
+        if ($spec === null) {
+            return;
+        }
+        if ($this->session === '') {
+            // PreRequest before PostConstruct: lazily create the session id.
+            $sid = $this->options['sessionId'] ?? null;
+            $this->session = (is_string($sid) && $sid !== '') ? $sid : $this->_genid('session');
+        }
+
+        $h = $this->options['headers'] ?? [];
+        if (!is_array($h)) {
+            $h = [];
+        }
+        $this->requests++;
+        $request_id = $this->_genid('request');
+
+        $this->_set($spec->headers, $h['agent'] ?? 'User-Agent', $this->_name());
+        $this->_set($spec->headers, $h['client'] ?? 'X-Client-Id', $this->session);
+        $spec->headers[$h['request'] ?? 'X-Request-Id'] = $request_id;
+
+        $client = $this->client;
+        if (!isset($client->_clienttrack)) {
+            $client->_clienttrack = [
+                'session' => $this->session,
+                'requests' => 0,
+                'clientName' => $this->_name(),
+            ];
+        }
+        $client->_clienttrack['requests'] = $this->requests;
+        $client->_clienttrack['lastRequestId'] = $request_id;
+    }
+
+    // Do not clobber a caller-provided value (e.g. a custom User-Agent).
+    private function _set(array &$headers, string $name, string $value): void
+    {
+        $lower = strtolower($name);
+        foreach ($headers as $k => $_v) {
+            if (is_string($k) && strtolower($k) === $lower) {
+                return;
+            }
+        }
+        $headers[$name] = $value;
+    }
+
+    private function _name(): string
+    {
+        $name = $this->options['clientName'] ?? null;
+        $name = (is_string($name) && $name !== '') ? $name : 'ProjectName-SDK';
+        $version = $this->options['clientVersion'] ?? null;
+        $version = (is_string($version) && $version !== '') ? $version : '0.0.1';
+        return $name . '/' . $version;
+    }
+
+    private function _genid(string $kind): string
+    {
+        $idgen = $this->options['idgen'] ?? null;
+        if (is_callable($idgen)) {
+            return (string)$idgen($kind);
+        }
+        return substr($kind[0] . '-' . bin2hex(random_bytes(9)), 0, 20);
+    }
+}

package/project/.sdk/tm/php/feature/DebugFeature.php

@@ -0,0 +1,167 @@
+<?php
+declare(strict_types=1);
+
+// ProjectName SDK debug feature
+
+require_once __DIR__ . '/BaseFeature.php';
+
+// Request/response capture for debugging. Records a bounded ring buffer of
+// per-operation traces — method, URL, redacted headers, response status and
+// timing — on `client->_debug['entries']`. Sensitive header values
+// (matching `redact`, default authorization/cookie/api-key style names) are
+// masked. An optional `onEntry` callback receives each finished entry (e.g.
+// to stream to a console). `max` caps the buffer (default 100). Mirrors
+// ts/src/feature/debug/DebugFeature.ts.
+class ProjectNameDebugFeature extends ProjectNameBaseFeature
+{
+    private mixed $client;
+    private ?array $options;
+    private ?\WeakMap $entries;
+
+    public function __construct()
+    {
+        parent::__construct();
+        $this->version = '0.0.1';
+        $this->name = 'debug';
+        $this->active = true;
+        $this->client = null;
+        $this->options = null;
+        $this->entries = null;
+    }
+
+    public function init(ProjectNameContext $ctx, array $options): void
+    {
+        $this->client = $ctx->client;
+        $this->options = $options;
+        $this->active = ($options['active'] ?? null) === true;
+        $this->entries = new \WeakMap();
+
+        if (!$this->active) {
+            return;
+        }
+
+        $client = $this->client;
+        if (!isset($client->_debug)) {
+            $client->_debug = ['entries' => []];
+        }
+    }
+
+    public function PreRequest(ProjectNameContext $ctx): void
+    {
+        if (!$this->active || $this->entries === null) {
+            return;
+        }
+        $spec = $ctx->spec;
+        $entry = [
+            'op' => ($ctx->op->entity !== '' ? $ctx->op->entity : '_')
+                . '.' . ($ctx->op->name !== '' ? $ctx->op->name : '_'),
+            'method' => $spec !== null ? $spec->method : null,
+            'url' => $spec !== null ? ($spec->url !== '' ? $spec->url : $spec->path) : null,
+            'headers' => $this->_redact($spec !== null ? $spec->headers : null),
+            'start' => $this->_now(),
+            'status' => null,
+            'ok' => null,
+            'durationMs' => null,
+            'error' => null,
+        ];
+        $this->entries[$ctx] = $entry;
+    }
+
+    public function PreResponse(ProjectNameContext $ctx): void
+    {
+        if (!$this->active || $this->entries === null || !isset($this->entries[$ctx])) {
+            return;
+        }
+        $entry = $this->entries[$ctx];
+        $response = $ctx->response;
+        if ($response !== null) {
+            $entry['status'] = $response->status;
+            if (($entry['url'] === null || $entry['url'] === '') && $ctx->spec !== null) {
+                $entry['url'] = $ctx->spec->url;
+            }
+            // PHP arrays are value types: write the updated entry back.
+            $this->entries[$ctx] = $entry;
+        }
+    }
+
+    public function PreDone(ProjectNameContext $ctx): void
+    {
+        if (!$this->active) {
+            return;
+        }
+        $this->_finish($ctx, true);
+    }
+
+    public function PreUnexpected(ProjectNameContext $ctx): void
+    {
+        if (!$this->active) {
+            return;
+        }
+        if ($this->entries !== null && isset($this->entries[$ctx])) {
+            $entry = $this->entries[$ctx];
+            $err = $ctx->ctrl->err;
+            $entry['error'] = ($err instanceof \Throwable) ? $err->getMessage() : null;
+            $this->entries[$ctx] = $entry;
+        }
+        $this->_finish($ctx, false);
+    }
+
+    private function _finish(ProjectNameContext $ctx, bool $ok): void
+    {
+        // Finish once per operation: a PreDone followed by an unexpected
+        // failure finds no open entry and no-ops.
+        if ($this->entries === null || !isset($this->entries[$ctx])) {
+            return;
+        }
+        $entry = $this->entries[$ctx];
+        unset($this->entries[$ctx]);
+
+        $entry['ok'] = $ok && ($ctx->result === null || $ctx->result->ok !== false);
+        $entry['durationMs'] = max(0.0, $this->_now() - (float)$entry['start']);
+        if ($entry['status'] === null && $ctx->result !== null) {
+            $entry['status'] = $ctx->result->status;
+        }
+
+        $client = $this->client;
+        $client->_debug['entries'][] = $entry;
+        $max = is_numeric($this->options['max'] ?? null) ? (int)$this->options['max'] : 100;
+        while (count($client->_debug['entries']) > $max) {
+            array_shift($client->_debug['entries']);
+        }
+
+        $on_entry = $this->options['onEntry'] ?? null;
+        if (is_callable($on_entry)) {
+            try {
+                $on_entry($entry);
+            } catch (\Throwable $_e) {
+                // Callback failures must never break the pipeline.
+            }
+        }
+    }
+
+    private function _redact(mixed $headers): array
+    {
+        if (!is_array($headers)) {
+            return [];
+        }
+        $patterns = $this->options['redact'] ??
+            ['authorization', 'cookie', 'set-cookie', 'api-key', 'apikey', 'x-api-key', 'idempotency-key'];
+        if (!is_array($patterns)) {
+            $patterns = [];
+        }
+        $out = [];
+        foreach ($headers as $k => $v) {
+            $out[$k] = in_array(strtolower((string)$k), $patterns, true) ? '<redacted>' : $v;
+        }
+        return $out;
+    }
+
+    private function _now(): float
+    {
+        $now = $this->options['now'] ?? null;
+        if (is_callable($now)) {
+            return (float)$now();
+        }
+        return microtime(true) * 1000.0;
+    }
+}