@apollo-deploy/tesseract 1.9.0 → 2.1.0

package/templates/php/transport.hbs

@@ -10,6 +10,7 @@ declare(strict_types=1);
 
 namespace {{namespace}};
 
+use DateTimeImmutable;
 use GuzzleHttp\Client as GuzzleClient;
 use GuzzleHttp\ClientInterface;
 use GuzzleHttp\Exception\ConnectException;
@@ -19,15 +20,11 @@ use GuzzleHttp\RequestOptions;
 use Psr\Http\Message\ResponseInterface;
 use Throwable;
 
-/**
- * HTTP transport layer with retry logic and security scheme injection.
- *
- * Wraps a GuzzleHttp\Client and provides executeRequest() for typed
- * request/response handling with automatic auth header injection
- * and configurable retry with exponential backoff + jitter.
- */
 class Transport
 {
+    private const RETRYABLE_METHODS = ['GET', 'HEAD', 'OPTIONS', 'PUT', 'DELETE'];
+    private const RETRYABLE_STATUSES = [408, 425, 429, 500, 502, 503, 504];
+
     private ClientInterface $http;
 
     /** @var array<string, mixed> */
@@ -38,6 +35,7 @@ class Transport
      *     baseUrl?: string,
      *     timeoutMs?: int,
      *     retries?: array{attempts?: int, backoffMs?: int, jitter?: bool, maxBackoffMs?: int},
+     *     retryUnsafeRequests?: bool,
      *     defaultHeaders?: array<string, string>,
      {{#each securitySchemes}}
      *     {{configKey}}?: string,
@@ -46,14 +44,16 @@ class Transport
      */
     public function __construct(array $config = [])
     {
-        $this->config = $config;
-
-        $baseUrl = rtrim($config['baseUrl'] ?? '{{baseUrl}}', '/');
-        $timeoutMs = $config['timeoutMs'] ?? 15000;
+        $timeoutMs = (int) ($config['timeoutMs'] ?? 15000);
+        if ($timeoutMs <= 0) {
+            throw new \InvalidArgumentException('timeoutMs must be greater than zero');
+        }
 
+        $this->config = $config;
+        $baseUrl = rtrim((string) ($config['baseUrl'] ?? '{{baseUrl}}'), '/');
         $headers = $config['defaultHeaders'] ?? [];
         $headers['Accept'] = $headers['Accept'] ?? 'application/json';
-        $headers['User-Agent'] = $headers['User-Agent'] ?? '{{clientName}}-php-sdk/{{version}}';
+        $headers['User-Agent'] = $headers['User-Agent'] ?? '{{clientName}}-php-sdk/{{packageVersion}}';
 
         $this->http = new GuzzleClient([
             'base_uri' => $baseUrl . '/',
@@ -64,217 +64,264 @@ class Transport
     }
 
     /**
-     * Execute an HTTP request with retry logic and auth injection.
-     *
      * @param array{
      *     method: string,
      *     path: string,
      *     query?: array<string, mixed>,
      *     body?: mixed,
      *     headers?: array<string, string>,
+     *     contentType?: string,
      *     timeoutMs?: int,
+     *     retries?: int,
+     *     retryUnsafeRequests?: bool,
+     *     stream?: bool,
      * } $requestDef
-     * @return ResponseInterface
      * @throws SDKError
      */
     public function executeRequest(array $requestDef): ResponseInterface
     {
-        $method = strtoupper($requestDef['method']);
-        $path = ltrim($requestDef['path'], '/');
+        $method = strtoupper((string) $requestDef['method']);
+        $path = ltrim((string) $requestDef['path'], '/');
         $query = $requestDef['query'] ?? [];
         $body = $requestDef['body'] ?? null;
-        $extraHeaders = $requestDef['headers'] ?? [];
-        $timeoutMs = $requestDef['timeoutMs'] ?? null;
-
-        // ── Inject auth headers ────────────────────────────────────────────
-        $authHeaders = $this->buildAuthHeaders();
-
-        $options = [
-            RequestOptions::HEADERS => array_merge($authHeaders, $extraHeaders),
-        ];
+        $headers = array_merge($this->buildAuthHeaders(), $requestDef['headers'] ?? []);
+        $contentType = (string) ($requestDef['contentType'] ?? 'application/json');
 
-        if (!empty($query)) {
+        $options = [RequestOptions::HEADERS => $headers];
+        if ($query !== []) {
             $options[RequestOptions::QUERY] = $query;
         }
-
         if ($body !== null) {
-            $options[RequestOptions::JSON] = $body;
+            if ($contentType === 'application/json') {
+                $options[RequestOptions::JSON] = $body;
+            } elseif ($contentType === 'multipart/form-data' && is_array($body)) {
+                $options[RequestOptions::MULTIPART] = $body;
+            } else {
+                $options[RequestOptions::BODY] = $body;
+                $options[RequestOptions::HEADERS]['Content-Type'] = $contentType;
+            }
         }
-
-        if ($timeoutMs !== null) {
+        if (($requestDef['stream'] ?? false) === true) {
+            $options[RequestOptions::STREAM] = true;
+        }
+        if (isset($requestDef['timeoutMs'])) {
+            $timeoutMs = (int) $requestDef['timeoutMs'];
+            if ($timeoutMs <= 0) {
+                throw new \InvalidArgumentException('timeoutMs must be greater than zero');
+            }
             $options[RequestOptions::TIMEOUT] = $timeoutMs / 1000.0;
         }
 
-        // ── Execute with retry ─────────────────────────────────────────────
-        return $this->executeWithRetry($method, $path, $options);
+        $retryConfig = $this->config['retries'] ?? [];
+        $maxRetries = max(0, (int) ($requestDef['retries'] ?? $retryConfig['attempts'] ?? 3));
+        $retryUnsafe = (bool) (
+            $requestDef['retryUnsafeRequests']
+            ?? $this->config['retryUnsafeRequests']
+            ?? false
+        );
+
+        return $this->executeWithRetry(
+            $method,
+            $path,
+            $options,
+            $maxRetries,
+            $retryUnsafe,
+        );
     }
 
-    /**
-     * Execute with configurable retry logic.
-     */
-    private function executeWithRetry(string $method, string $path, array $options): ResponseInterface
-    {
+    /** @throws SDKError */
+    private function executeWithRetry(
+        string $method,
+        string $path,
+        array $options,
+        int $maxRetries,
+        bool $retryUnsafe,
+    ): ResponseInterface {
         $retryConfig = $this->config['retries'] ?? [];
-        $maxAttempts = $retryConfig['attempts'] ?? 3;
-        $baseBackoffMs = $retryConfig['backoffMs'] ?? 400;
-        $useJitter = $retryConfig['jitter'] ?? true;
-        $maxBackoffMs = $retryConfig['maxBackoffMs'] ?? 30000;
-
-        $lastException = null;
+        $baseBackoffMs = max(0, (int) ($retryConfig['backoffMs'] ?? 400));
+        $useJitter = (bool) ($retryConfig['jitter'] ?? true);
+        $maxBackoffMs = max($baseBackoffMs, (int) ($retryConfig['maxBackoffMs'] ?? 30000));
+        $canRetry = $this->canRetryMethod($method, $options[RequestOptions::HEADERS] ?? [], $retryUnsafe);
+        $lastError = null;
 
-        for ($attempt = 1; $attempt <= $maxAttempts; $attempt++) {
+        for ($attempt = 0; $attempt <= $maxRetries; $attempt++) {
             try {
                 $request = new Request($method, $path, $options[RequestOptions::HEADERS] ?? []);
                 $response = $this->http->send($request, $options);
-
-                // Retry on server errors (5xx) and 429 (rate limit)
                 $status = $response->getStatusCode();
-                if ($status < 500 && $status !== 429) {
+
+                if ($status >= 200 && $status < 300) {
                     return $response;
                 }
 
-                if ($attempt < $maxAttempts) {
-                    $delayMs = $this->calculateBackoff($attempt, $baseBackoffMs, $useJitter, $maxBackoffMs);
-                    $this->sleep($delayMs);
+                $lastError = $this->errorFromResponse($response);
+                if (!$canRetry || !in_array($status, self::RETRYABLE_STATUSES, true) || $attempt >= $maxRetries) {
+                    throw $lastError;
                 }
-            } catch (ConnectException $e) {
-                $lastException = $e;
 
-                if ($attempt < $maxAttempts) {
-                    $delayMs = $this->calculateBackoff($attempt, $baseBackoffMs, $useJitter, $maxBackoffMs);
-                    $this->sleep($delayMs);
+                $this->sleep($this->retryDelayMs(
+                    $response->getHeaderLine('Retry-After'),
+                    $attempt,
+                    $baseBackoffMs,
+                    $useJitter,
+                    $maxBackoffMs,
+                ));
+            } catch (ConnectException $exception) {
+                $lastError = SDKError::fromException($exception);
+                if (!$canRetry || $attempt >= $maxRetries) {
+                    throw $lastError;
                 }
-            } catch (RequestException $e) {
-                $response = $e->getResponse();
-                if ($response !== null) {
-                    $status = $response->getStatusCode();
-                    if ($status >= 500 || $status === 429) {
-                        $lastException = $e;
-                        if ($attempt < $maxAttempts) {
-                            $delayMs = $this->calculateBackoff($attempt, $baseBackoffMs, $useJitter, $maxBackoffMs);
-                            $this->sleep($delayMs);
-                        }
-                        continue;
-                    }
+                $this->sleep($this->retryDelayMs(
+                    null,
+                    $attempt,
+                    $baseBackoffMs,
+                    $useJitter,
+                    $maxBackoffMs,
+                ));
+            } catch (RequestException $exception) {
+                $response = $exception->getResponse();
+                $lastError = $response === null
+                    ? SDKError::fromException($exception)
+                    : $this->errorFromResponse($response, $exception);
+                if (
+                    !$canRetry
+                    || $attempt >= $maxRetries
+                    || ($response !== null && !in_array($response->getStatusCode(), self::RETRYABLE_STATUSES, true))
+                ) {
+                    throw $lastError;
                 }
-                throw $this->mapToSDKError($e);
+                $this->sleep($this->retryDelayMs(
+                    $response?->getHeaderLine('Retry-After'),
+                    $attempt,
+                    $baseBackoffMs,
+                    $useJitter,
+                    $maxBackoffMs,
+                ));
             }
         }
 
-        // All retries exhausted
-        if ($lastException instanceof RequestException) {
-            throw $this->mapToSDKError($lastException);
+        throw $lastError ?? new SDKError('Request failed after retries', 0, 'RETRY_EXHAUSTED');
+    }
+
+    /** @param array<string, string> $headers */
+    private function canRetryMethod(string $method, array $headers, bool $retryUnsafe): bool
+    {
+        if ($retryUnsafe || in_array($method, self::RETRYABLE_METHODS, true)) {
+            return true;
+        }
+        $effectiveHeaders = array_merge($this->config['defaultHeaders'] ?? [], $headers);
+        foreach ($effectiveHeaders as $name => $value) {
+            if (strcasecmp((string) $name, 'X-Idempotency-Key') === 0 && $value !== '') {
+                return true;
+            }
         }
+        return false;
+    }
 
-        if ($lastException instanceof Throwable) {
-            throw SDKError::fromException($lastException);
+    private function retryDelayMs(
+        ?string $retryAfter,
+        int $attempt,
+        int $baseMs,
+        bool $jitter,
+        int $maxMs,
+    ): int {
+        $retryAfterMs = $this->parseRetryAfterMs($retryAfter);
+        if ($retryAfterMs !== null) {
+            return min($retryAfterMs, $maxMs);
         }
 
-        throw new SDKError('Request failed after ' . $maxAttempts . ' attempts');
+        $cap = min($baseMs * (2 ** $attempt), $maxMs);
+        return $jitter ? random_int(0, max(0, $cap)) : $cap;
     }
 
-    /**
-     * Build auth headers from configured security schemes.
-     *
-     * @return array<string, string>
-     */
+    private function parseRetryAfterMs(?string $value): ?int
+    {
+        if ($value === null || trim($value) === '') {
+            return null;
+        }
+        if (is_numeric($value)) {
+            return max(0, (int) ceil((float) $value * 1000));
+        }
+        try {
+            $time = new DateTimeImmutable($value);
+            return max(0, ($time->getTimestamp() - time()) * 1000);
+        } catch (Throwable) {
+            return null;
+        }
+    }
+
+    /** @return array<string, string> */
     private function buildAuthHeaders(): array
     {
         $headers = [];
-
-        {{#each securitySchemes}}
-        {{#if (eq type "apiKey")}}
-        {{#if (eq in "header")}}
-        // {{name}} — API key in header
+{{#each securitySchemes}}
+{{#if (eq type "apiKey")}}
+{{#if (eq in "header")}}
         if (!empty($this->config['{{configKey}}'])) {
             $headers['{{paramName}}'] = $this->config['{{configKey}}'];
         }
-        {{/if}}
-        {{/if}}
-
-        {{#if (and (eq type "http") (eq scheme "bearer"))}}
-        // {{name}} — Bearer token
+{{/if}}
+{{/if}}
+{{#if (and (eq type "http") (eq scheme "bearer"))}}
         if (!empty($this->config['{{configKey}}'])) {
             $headers['Authorization'] = 'Bearer ' . $this->config['{{configKey}}'];
         }
-        {{/if}}
-
-        {{#if (eq type "oauth2")}}
-        // {{name}} — OAuth2 access token
+{{/if}}
+{{#if (eq type "oauth2")}}
         if (!empty($this->config['{{configKey}}'])) {
             $headers['Authorization'] = 'Bearer ' . $this->config['{{configKey}}'];
         }
-        {{/if}}
-
-        {{#if (eq type "openIdConnect")}}
-        // {{name}} — OpenID Connect token
+{{/if}}
+{{#if (eq type "openIdConnect")}}
         if (!empty($this->config['{{configKey}}'])) {
             $headers['Authorization'] = 'Bearer ' . $this->config['{{configKey}}'];
         }
-        {{/if}}
-        {{/each}}
-
+{{/if}}
+{{/each}}
         return $headers;
     }
 
-    /**
-     * Calculate exponential backoff with optional jitter.
-     */
-    private function calculateBackoff(int $attempt, int $baseMs, bool $jitter, int $maxMs): int
-    {
-        $delay = $baseMs * (2 ** ($attempt - 1));
-
-        if ($jitter) {
-            $delay = (int) ($delay * (0.5 + (mt_rand() / mt_getrandmax()) * 0.5));
-        }
-
-        return min($delay, $maxMs);
-    }
-
-    /**
-     * Sleep for a given number of milliseconds.
-     */
     private function sleep(int $milliseconds): void
     {
-        usleep($milliseconds * 1000);
-    }
-
-    /**
-     * Map a Guzzle RequestException to an SDKError.
-     */
-    private function mapToSDKError(RequestException $exception): SDKError
-    {
-        $response = $exception->getResponse();
-
-        if ($response === null) {
-            return SDKError::fromException($exception);
+        if ($milliseconds > 0) {
+            usleep($milliseconds * 1000);
         }
+    }
 
-        $status = $response->getStatusCode();
+    private function errorFromResponse(
+        ResponseInterface $response,
+        ?Throwable $previous = null,
+    ): SDKError {
         $body = $this->decodeResponseBody($response);
-
-        $message = $body['message'] ?? $body['error'] ?? $exception->getMessage();
-        $code = $body['code'] ?? $body['error_code'] ?? 'UNKNOWN';
-        $requestId = $response->getHeaderLine('x-request-id') ?: null;
+        $nested = is_array($body['error'] ?? null) ? $body['error'] : [];
+        $message = $body['message'] ?? $nested['message'] ?? null;
+        if ($message === null && is_string($body['error'] ?? null)) {
+            $message = $body['error'];
+        }
+        $message ??= trim((string) ($body['raw'] ?? ''));
+        $code = $body['code'] ?? $body['error_code'] ?? $nested['code'] ?? null;
+        if ($code === null && is_string($body['error'] ?? null)) {
+            $code = $body['error'];
+        }
+        $requestId = $body['request_id']
+            ?? $response->getHeaderLine('x-request-id')
+            ?: $response->getHeaderLine('request-id')
+            ?: null;
 
         return new SDKError(
-            message: (string) $message,
-            status: $status,
-            code: (string) $code,
+            message: (string) ($message ?: 'HTTP ' . $response->getStatusCode()),
+            status: $response->getStatusCode(),
+            code: (string) ($code ?: 'HTTP_ERROR'),
             requestId: $requestId,
-            previous: $exception,
+            responseBody: $body,
+            previous: $previous,
         );
     }
 
-    /**
-     * Decode a PSR-7 response body, returning an associative array.
-     *
-     * @return array<string, mixed>
-     */
+    /** @return array<string, mixed> */
     private function decodeResponseBody(ResponseInterface $response): array
     {
         $contents = $response->getBody()->__toString();
-
         try {
             $decoded = json_decode($contents, true, 512, JSON_THROW_ON_ERROR);
             return is_array($decoded) ? $decoded : ['raw' => $decoded];

package/templates/php/types.hbs

@@ -1,92 +1,95 @@
 <?php
 
-/**
- * @generated
- * This file was automatically generated by Tesseract.
- * DO NOT MODIFY THIS FILE DIRECTLY.
- */
-
 declare(strict_types=1);
 
 namespace {{namespace}};
 
 {{#each schemas}}
-{{#if isEnum}}
-/**
-{{#if description}}
- * {{description}}
- *
-{{/if}}
- * @generated
- */
-enum {{name}}: {{#each properties}}{{#if @first}}{{type}}{{/if}}{{/each}}
+{{#if external}}
+/** External schema placeholder for {{name}}. */
+class {{targetName}}
+{
+    /** @param array<string, mixed> $data */
+    public function __construct(public array $data = [])
+    {
+    }
+
+    /** @param array<string, mixed> $data */
+    public static function fromArray(array $data): self
+    {
+        return new self($data);
+    }
+
+    /** @return array<string, mixed> */
+    public function toArray(): array
+    {
+        return $this->data;
+    }
+}
+
+{{else if isEnum}}
+enum {{targetName}}: {{enumType}}
 {
 {{#each enumValues}}
-    case {{this}} = '{{this}}';
+    case {{name}} = {{{literal}}};
 {{/each}}
 }
 
-{{else if isTypeAlias}}
-{{!-- PHP type aliases are not direct; they are used as docblock hints --}}
-{{!-- Skipping type alias: {{name}} --}}
-
 {{else if isUnionType}}
-{{!-- PHP union types are handled via properties, not standalone declarations --}}
-{{!-- Skipping union type: {{name}} --}}
+/** Union schema {{name}}. */
+final class {{targetName}}
+{
+    public function __construct(public mixed $value)
+    {
+    }
+}
+
+{{else if isIntersectionType}}
+/** Intersection schema {{name}}. */
+class {{targetName}}
+{
+    /** @param array<string, mixed> $data */
+    public function __construct(public array $data = [])
+    {
+    }
+}
+
+{{else if isTypeAlias}}
+// Type alias {{name}} is represented inline as {{{aliasType}}}.
 
 {{else}}
-/**
-{{#if description}}
- * {{description}}
- *
-{{/if}}
- * @generated
+/**{{#if description}}
+ * {{description}}{{/if}}
  */
-class {{name}}{{#if extends}} extends {{extends}}{{/if}}
+class {{targetName}}{{#if targetExtends}} extends {{targetExtends}}{{/if}}
 {
 {{#each properties}}
-    /**
-     * @var {{tsType type nullable}}
-     */
-    public {{#if nullable}}?{{/if}}{{type}} ${{name}}{{#if defaultValue}} = {{{json defaultValue}}}{{/if}};
-
+    /** @var {{docType}} */
+    public {{targetType}} ${{propertyName}}{{#if hasDefault}} = {{{defaultLiteral}}}{{else if optional}} = null{{/if}};
 {{/each}}
 
-    /**
-     * @param array<string, mixed> $data
-     */
+    /** @param array<string, mixed> $data */
     public static function fromArray(array $data): self
     {
         $instance = new self();
-
-        {{#each properties}}
-        {{#if (eq type "string")}}
-        $instance->{{name}} = isset($data['{{name}}']) ? (string) $data['{{name}}'] : {{#if required}}throw new \InvalidArgumentException('Missing required field: {{name}}'){{else}}null{{/if}};
-        {{else if (eq type "int")}}
-        $instance->{{name}} = isset($data['{{name}}']) ? (int) $data['{{name}}'] : {{#if required}}throw new \InvalidArgumentException('Missing required field: {{name}}'){{else}}null{{/if}};
-        {{else if (eq type "float")}}
-        $instance->{{name}} = isset($data['{{name}}']) ? (float) $data['{{name}}'] : {{#if required}}throw new \InvalidArgumentException('Missing required field: {{name}}'){{else}}null{{/if}};
-        {{else if (eq type "bool")}}
-        $instance->{{name}} = isset($data['{{name}}']) ? (bool) $data['{{name}}'] : {{#if required}}throw new \InvalidArgumentException('Missing required field: {{name}}'){{else}}null{{/if}};
-        {{else if (eq type "array")}}
-        $instance->{{name}} = isset($data['{{name}}']) ? (array) $data['{{name}}'] : {{#if required}}[]{{else}}null{{/if}};
-        {{else}}
-        $instance->{{name}} = $data['{{name}}'] ?? {{#if required}}throw new \InvalidArgumentException('Missing required field: {{name}}'){{else}}null{{/if}};
-        {{/if}}
-
-        {{/each}}
+{{#each properties}}
+{{#if required}}
+        if (!array_key_exists('{{name}}', $data)) {
+            throw new \InvalidArgumentException('Missing required field: {{name}}');
+        }
+{{/if}}
+        $instance->{{propertyName}} = $data['{{name}}'] ?? {{#if hasDefault}}{{{defaultLiteral}}}{{else}}null{{/if}};
+{{/each}}
         return $instance;
     }
 
-    /**
-     * @return array<string, mixed>
-     */
+    /** @return array<string, mixed> */
     public function toArray(): array
     {
         return [
-            {{#each properties}}
-            '{{name}}' => $this->{{name}},
-            {{/each}}
+{{#each properties}}
+            '{{name}}' => $this->{{propertyName}},
+{{/each}}
         ];
     }
 }

package/templates/python/client.hbs

@@ -4,7 +4,7 @@ from typing import Optional, Dict, Any, List, Callable, Union
 import httpx
 from .transport import create_transport, SDKTransport, RequestOptions
 {{#each groups}}
-from .resources.{{fileName}} import {{interfaceName}}
+from .resources.{{fileModule}} import {{interfaceName}}
 {{/each}}
 
 {{#if hasSSE}}
@@ -34,6 +34,7 @@ class {{clientName}}ClientConfig:
 {{/each}}
         timeout_ms: int = 15000,
         retries: int = 3,
+        retry_unsafe_requests: bool = False,
         default_headers: Optional[Dict[str, str]] = None,
         on_request: Optional[Callable] = None,
         on_response: Optional[Callable] = None,
@@ -45,6 +46,7 @@ class {{clientName}}ClientConfig:
 {{/each}}
         self.timeout_ms = timeout_ms
         self.retries = retries
+        self.retry_unsafe_requests = retry_unsafe_requests
         self.default_headers = default_headers or {}
         self.on_request = on_request
         self.on_response = on_response
@@ -63,15 +65,26 @@ class {{clientName}}Client:
 {{/each}}
             timeout_ms=self.config.timeout_ms,
             retries=self.config.retries,
+            retry_unsafe_requests=self.config.retry_unsafe_requests,
             default_headers=self.config.default_headers,
             on_request=self.config.on_request,
             on_response=self.config.on_response,
             on_error=self.config.on_error,
         )
 {{#each groups}}
-        self.{{snakeCase name}} = {{interfaceName}}(self._transport)
+        self.{{accessorName}} = {{interfaceName}}(self._transport)
 {{/each}}
 
+    def close(self) -> None:
+        """Close the underlying HTTP connection pool."""
+        self._transport.close()
+
+    def __enter__(self) -> "{{clientName}}Client":
+        return self
+
+    def __exit__(self, *_: Any) -> None:
+        self.close()
+
 
 def create_{{snakeCase clientName}}_client(
     base_url: str = "{{baseUrl}}",