@apollo-deploy/tesseract 1.9.0 → 2.1.0

package/templates/csharp/transport.hbs

@@ -4,16 +4,15 @@ using System;
 using System.Collections.Generic;
 using System.IO;
 using System.Linq;
+using System.Net;
 using System.Net.Http;
 using System.Text;
 using System.Text.Json;
 using System.Threading;
 using System.Threading.Tasks;
 
-/// <summary>
-/// Configuration for the HTTP transport layer.
-/// </summary>
-public class TransportConfig
+/// <summary>Configuration for the HTTP transport layer.</summary>
+public sealed class TransportConfig
 {
     public string BaseUrl { get; set; } = "";
 {{#each securitySchemes}}
@@ -21,33 +20,54 @@ public class TransportConfig
 {{/each}}
     public int TimeoutMs { get; set; } = 15000;
     public int MaxRetries { get; set; } = 3;
+    public bool RetryUnsafeRequests { get; set; }
     public Dictionary<string, string>? DefaultHeaders { get; set; }
 }
 
 /// <summary>
-/// Low-level HTTP transport handling authentication, serialization, retries, and error normalization.
+/// Low-level HTTP transport handling authentication, serialization, bounded retries,
+/// cancellation, and normalized API errors.
 /// </summary>
-public class Transport
+public sealed class Transport : IDisposable
 {
+    private static readonly HashSet<HttpStatusCode> RetryableStatuses = new()
+    {
+        HttpStatusCode.RequestTimeout,
+        (HttpStatusCode)425,
+        (HttpStatusCode)429,
+        HttpStatusCode.InternalServerError,
+        HttpStatusCode.BadGateway,
+        HttpStatusCode.ServiceUnavailable,
+        HttpStatusCode.GatewayTimeout,
+    };
+
     private readonly TransportConfig _config;
     private readonly HttpClient _httpClient;
-    private static readonly JsonSerializerOptions _jsonOptions = new()
+    private readonly bool _ownsHttpClient;
+
+    private static readonly JsonSerializerOptions JsonOptions = new()
     {
         PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
         PropertyNameCaseInsensitive = true,
         DefaultIgnoreCondition = System.Text.Json.Serialization.JsonIgnoreCondition.WhenWritingNull,
     };
 
-    public Transport(TransportConfig config)
+    public Transport(TransportConfig config, HttpClient? httpClient = null)
     {
+        if (string.IsNullOrWhiteSpace(config.BaseUrl))
+            throw new ArgumentException("BaseUrl must not be blank", nameof(config));
+        if (config.TimeoutMs <= 0)
+            throw new ArgumentOutOfRangeException(nameof(config), "TimeoutMs must be greater than zero");
+        if (config.MaxRetries < 0)
+            throw new ArgumentOutOfRangeException(nameof(config), "MaxRetries must not be negative");
+
         _config = config;
-        _httpClient = new HttpClient
-        {
-            Timeout = TimeSpan.FromMilliseconds(config.TimeoutMs),
-        };
+        _ownsHttpClient = httpClient is null;
+        _httpClient = httpClient ?? new HttpClient();
+        _httpClient.Timeout = TimeSpan.FromMilliseconds(config.TimeoutMs);
     }
 
-    public class Request
+    public sealed class Request
     {
         public HttpMethod Method { get; set; } = HttpMethod.Get;
         public string Path { get; set; } = "";
@@ -59,136 +79,165 @@ public class Transport
 
     public async Task<T> ExecuteAsync<T>(Request request, CancellationToken cancellationToken = default)
     {
-        return await ExecuteWithRetriesAsync<T>(request, _config.MaxRetries, cancellationToken);
+        using var response = await SendWithRetriesAsync(
+            request,
+            HttpCompletionOption.ResponseContentRead,
+            cancellationToken);
+        var body = await response.Content.ReadAsStringAsync(cancellationToken);
+        EnsureSuccess(response, body);
+
+        if (string.IsNullOrWhiteSpace(body)) return default!;
+
+        try
+        {
+            return JsonSerializer.Deserialize<T>(body, JsonOptions)
+                ?? throw new JsonException("Response body was JSON null");
+        }
+        catch (JsonException error)
+        {
+            throw new SdkException(
+                (int)response.StatusCode,
+                "DESERIALIZE_ERROR",
+                "Failed to deserialize response body",
+                GetRequestId(response),
+                error);
+        }
     }
 
     public async Task<byte[]> ExecuteRawAsync(Request request, CancellationToken cancellationToken = default)
     {
-        return await ExecuteRawWithRetriesAsync(request, _config.MaxRetries, cancellationToken);
+        using var response = await SendWithRetriesAsync(
+            request,
+            HttpCompletionOption.ResponseContentRead,
+            cancellationToken);
+        var body = await response.Content.ReadAsByteArrayAsync(cancellationToken);
+        if (!response.IsSuccessStatusCode)
+            throw ParseErrorResponse(response, Encoding.UTF8.GetString(body));
+        return body;
     }
 
-    public async Task<HttpResponseMessage> StreamAsync(Request request, CancellationToken cancellationToken = default)
+    /// <summary>
+    /// Executes a streaming request. The caller owns and must dispose the returned response.
+    /// </summary>
+    public async Task<HttpResponseMessage> StreamAsync(
+        Request request,
+        CancellationToken cancellationToken = default)
     {
-        using var httpRequest = BuildRequest(request);
-        var response = await _httpClient.SendAsync(
-            httpRequest,
+        var response = await SendWithRetriesAsync(
+            request,
             HttpCompletionOption.ResponseHeadersRead,
             cancellationToken);
-        if (!response.IsSuccessStatusCode)
-        {
-            var errorBody = await response.Content.ReadAsStringAsync(cancellationToken);
-            throw ParseErrorResponse(response, errorBody);
-        }
-        return response;
+        if (response.IsSuccessStatusCode) return response;
+
+        var body = await response.Content.ReadAsStringAsync(cancellationToken);
+        var error = ParseErrorResponse(response, body);
+        response.Dispose();
+        throw error;
+    }
+
+    public void Dispose()
+    {
+        if (_ownsHttpClient) _httpClient.Dispose();
     }
 
-    private async Task<T> ExecuteWithRetriesAsync<T>(
-        Request request, int maxRetries, CancellationToken cancellationToken)
+    private async Task<HttpResponseMessage> SendWithRetriesAsync(
+        Request request,
+        HttpCompletionOption completionOption,
+        CancellationToken cancellationToken)
     {
-        Exception? lastException = null;
-        for (int attempt = 0; attempt <= maxRetries; attempt++)
+        var canRetry = CanRetry(request);
+
+        for (var attempt = 0; attempt <= _config.MaxRetries; attempt++)
         {
-            if (attempt > 0)
-            {
-                var backoff = (int)Math.Pow(2, attempt - 1) * 200;
-                var jitter = Random.Shared.Next(backoff / 2);
-                await Task.Delay(backoff + jitter, cancellationToken);
-            }
             try
             {
                 using var httpRequest = BuildRequest(request);
-                using var response = await _httpClient.SendAsync(httpRequest, cancellationToken);
-                var body = await response.Content.ReadAsStringAsync(cancellationToken);
-                if (response.IsSuccessStatusCode)
-                {
-                    if (string.IsNullOrEmpty(body)) return default!;
-                    var result = JsonSerializer.Deserialize<T>(body, _jsonOptions);
-                    if (result == null)
-                        throw new SdkException((int)response.StatusCode, "DESERIALIZE_ERROR",
-                            "Failed to deserialize response body", GetRequestId(response));
-                    return result;
-                }
-                if ((int)response.StatusCode >= 500 && attempt < maxRetries)
+                var response = await _httpClient.SendAsync(
+                    httpRequest,
+                    completionOption,
+                    cancellationToken);
+
+                if (response.IsSuccessStatusCode ||
+                    !canRetry ||
+                    !RetryableStatuses.Contains(response.StatusCode) ||
+                    attempt == _config.MaxRetries)
                 {
-                    lastException = ParseErrorResponse(response, body);
-                    continue;
+                    return response;
                 }
-                throw ParseErrorResponse(response, body);
-            }
-            catch (SdkException) { throw; }
-            catch (TaskCanceledException) when (cancellationToken.IsCancellationRequested) { throw; }
-            catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) { throw; }
-            catch (Exception ex) when (IsRetryable(ex) && attempt < maxRetries) { lastException = ex; }
-            catch (Exception ex)
-            {
-                throw new SdkException(0, "REQUEST_ERROR", ex.Message, null, ex);
-            }
-        }
-        throw new SdkException(0, "MAX_RETRIES_EXCEEDED",
-            "Request failed after " + (maxRetries + 1) + " attempts", null, lastException);
-    }
 
-    private async Task<byte[]> ExecuteRawWithRetriesAsync(
-        Request request, int maxRetries, CancellationToken cancellationToken)
-    {
-        Exception? lastException = null;
-        for (int attempt = 0; attempt <= maxRetries; attempt++)
-        {
-            if (attempt > 0)
+                var delay = GetRetryDelay(response, attempt);
+                response.Dispose();
+                await Task.Delay(delay, cancellationToken);
+            }
+            catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested)
             {
-                var backoff = (int)Math.Pow(2, attempt - 1) * 200;
-                var jitter = Random.Shared.Next(backoff / 2);
-                await Task.Delay(backoff + jitter, cancellationToken);
+                throw;
             }
-            try
+            catch (Exception error) when (IsNetworkError(error))
             {
-                using var httpRequest = BuildRequest(request);
-                using var response = await _httpClient.SendAsync(httpRequest, cancellationToken);
-                var body = await response.Content.ReadAsByteArrayAsync(cancellationToken);
-                if (response.IsSuccessStatusCode) return body;
-                var bodyString = Encoding.UTF8.GetString(body);
-                if ((int)response.StatusCode >= 500 && attempt < maxRetries)
+                if (!canRetry || attempt == _config.MaxRetries)
                 {
-                    lastException = ParseErrorResponse(response, bodyString);
-                    continue;
+                    throw new SdkException(
+                        0,
+                        "REQUEST_ERROR",
+                        "Network error: " + error.Message,
+                        null,
+                        error);
                 }
-                throw ParseErrorResponse(response, bodyString);
+
+                await Task.Delay(GetBackoff(attempt), cancellationToken);
             }
-            catch (SdkException) { throw; }
-            catch (TaskCanceledException) when (cancellationToken.IsCancellationRequested) { throw; }
-            catch (OperationCanceledException) when (cancellationToken.IsCancellationRequested) { throw; }
-            catch (Exception ex) when (IsRetryable(ex) && attempt < maxRetries) { lastException = ex; }
-            catch (Exception ex)
+            catch (SdkException)
             {
-                throw new SdkException(0, "REQUEST_ERROR", ex.Message, null, ex);
+                throw;
+            }
+            catch (Exception error)
+            {
+                throw new SdkException(0, "REQUEST_ERROR", error.Message, null, error);
             }
         }
-        throw new SdkException(0, "MAX_RETRIES_EXCEEDED",
-            "Request failed after " + (maxRetries + 1) + " attempts", null, lastException);
+
+        throw new SdkException(
+            0,
+            "MAX_RETRIES_EXCEEDED",
+            "Request failed after " + (_config.MaxRetries + 1) + " attempts",
+            null);
     }
 
     private HttpRequestMessage BuildRequest(Request request)
     {
-        var baseUri = new Uri(_config.BaseUrl.TrimEnd('/') + "/");
-        var fullUri = new Uri(baseUri, request.Path.TrimStart('/'));
+        var baseUri = new Uri(_config.BaseUrl.TrimEnd('/') + "/", UriKind.Absolute);
+        var builder = new UriBuilder(new Uri(baseUri, request.Path.TrimStart('/')));
+        var query = new List<string>();
 
-        if (request.Query?.Count > 0)
+        if (!string.IsNullOrEmpty(builder.Query))
+            query.Add(builder.Query.TrimStart('?'));
+
+        if (request.Query != null)
         {
-            var queryString = string.Join("&",
-                request.Query.Select(kv =>
-                    Uri.EscapeDataString(kv.Key) + "=" + Uri.EscapeDataString(kv.Value)));
-            var separator = fullUri.Query.Length > 0 ? "&" : "";
-            fullUri = new Uri(fullUri, fullUri.PathAndQuery + separator + queryString);
+            query.AddRange(request.Query.Select(pair =>
+                Uri.EscapeDataString(pair.Key) + "=" + Uri.EscapeDataString(pair.Value)));
         }
 
-        var httpRequest = new HttpRequestMessage(request.Method, fullUri);
+{{#each securitySchemes}}
+{{#if (eq type "apiKey")}}
+{{#if (eq in "query")}}
+        if (!string.IsNullOrEmpty(_config.{{pascalCase configKey}}))
+            query.Add("{{paramName}}=" + Uri.EscapeDataString(_config.{{pascalCase configKey}}));
+{{/if}}
+{{/if}}
+{{/each}}
+
+        builder.Query = string.Join("&", query.Where(value => !string.IsNullOrWhiteSpace(value)));
+        var httpRequest = new HttpRequestMessage(request.Method, builder.Uri);
+
+        httpRequest.Headers.TryAddWithoutValidation("Accept", "application/json");
+        httpRequest.Headers.TryAddWithoutValidation("User-Agent", "{{packageName}}/{{packageVersion}}");
 
         if (_config.DefaultHeaders != null)
         {
             foreach (var (key, value) in _config.DefaultHeaders)
-            {
                 httpRequest.Headers.TryAddWithoutValidation(key, value);
-            }
         }
 
 {{#each securitySchemes}}
@@ -197,14 +246,6 @@ public class Transport
         if (!string.IsNullOrEmpty(_config.{{pascalCase configKey}}))
             httpRequest.Headers.TryAddWithoutValidation("{{paramName}}", _config.{{pascalCase configKey}});
 {{/if}}
-{{#if (eq in "query")}}
-        if (!string.IsNullOrEmpty(_config.{{pascalCase configKey}}))
-        {
-            var sep = fullUri.Query.Length > 0 ? "&" : "";
-            fullUri = new Uri(fullUri, fullUri.PathAndQuery + sep + "{{paramName}}=" + Uri.EscapeDataString(_config.{{pascalCase configKey}}));
-            httpRequest.RequestUri = fullUri;
-        }
-{{/if}}
 {{/if}}
 {{#if (and (eq type "http") (eq scheme "bearer"))}}
         if (!string.IsNullOrEmpty(_config.{{pascalCase configKey}}))
@@ -223,7 +264,7 @@ public class Transport
         if (request.Body != null)
         {
             var contentType = request.ContentType ?? "application/json";
-            var json = JsonSerializer.Serialize(request.Body, _jsonOptions);
+            var json = JsonSerializer.Serialize(request.Body, JsonOptions);
             httpRequest.Content = new StringContent(json, Encoding.UTF8, contentType);
         }
 
@@ -232,28 +273,66 @@ public class Transport
             foreach (var (key, value) in request.Headers)
             {
                 if (key.Equals("Content-Type", StringComparison.OrdinalIgnoreCase) && httpRequest.Content != null)
-                {
                     httpRequest.Content.Headers.ContentType =
                         new System.Net.Http.Headers.MediaTypeHeaderValue(value);
-                }
                 else
-                {
                     httpRequest.Headers.TryAddWithoutValidation(key, value);
-                }
             }
         }
 
         return httpRequest;
     }
 
-    private static bool IsRetryable(Exception ex)
+    private bool CanRetry(Request request)
+    {
+        if (_config.RetryUnsafeRequests ||
+            request.Method == HttpMethod.Get ||
+            request.Method == HttpMethod.Head ||
+            request.Method == HttpMethod.Options ||
+            request.Method == HttpMethod.Put ||
+            request.Method == HttpMethod.Delete)
+        {
+            return true;
+        }
+
+        return _config.DefaultHeaders?.Any(pair =>
+                   pair.Key.Equals("X-Idempotency-Key", StringComparison.OrdinalIgnoreCase) &&
+                   !string.IsNullOrEmpty(pair.Value)) == true ||
+               request.Headers?.Any(pair =>
+                   pair.Key.Equals("X-Idempotency-Key", StringComparison.OrdinalIgnoreCase) &&
+                   !string.IsNullOrEmpty(pair.Value)) == true;
+    }
+
+    private static TimeSpan GetRetryDelay(HttpResponseMessage response, int attempt)
     {
-        return ex is HttpRequestException ||
-               ex is TaskCanceledException ||
-               ex is IOException ||
-               ex.Message.Contains("connection") ||
-               ex.Message.Contains("timeout") ||
-               ex.Message.Contains("reset");
+        var retryAfter = response.Headers.RetryAfter;
+        if (retryAfter?.Delta is { } delta)
+            return ClampDelay(delta);
+        if (retryAfter?.Date is { } date)
+            return ClampDelay(date - DateTimeOffset.UtcNow);
+        return GetBackoff(attempt);
+    }
+
+    private static TimeSpan GetBackoff(int attempt)
+    {
+        var exponential = Math.Min(30_000, 200 * Math.Pow(2, Math.Min(attempt, 10)));
+        var jitter = Random.Shared.NextDouble() * exponential / 2;
+        return TimeSpan.FromMilliseconds(Math.Min(30_000, exponential + jitter));
+    }
+
+    private static TimeSpan ClampDelay(TimeSpan delay)
+    {
+        if (delay < TimeSpan.Zero) return TimeSpan.Zero;
+        return delay > TimeSpan.FromSeconds(30) ? TimeSpan.FromSeconds(30) : delay;
+    }
+
+    private static bool IsNetworkError(Exception error) =>
+        error is HttpRequestException or IOException or TaskCanceledException or TimeoutException;
+
+    private static void EnsureSuccess(HttpResponseMessage response, string body)
+    {
+        if (!response.IsSuccessStatusCode)
+            throw ParseErrorResponse(response, body);
     }
 
     private static SdkException ParseErrorResponse(HttpResponseMessage response, string body)
@@ -261,31 +340,54 @@ public class Transport
         var requestId = GetRequestId(response);
         try
         {
-            using var doc = JsonDocument.Parse(body);
-            var root = doc.RootElement;
-            var code = "";
-            var message = "";
-            if (root.TryGetProperty("code", out var codeEl)) code = codeEl.GetString() ?? "";
-            if (root.TryGetProperty("message", out var msgEl)) message = msgEl.GetString() ?? "";
-            else if (root.TryGetProperty("error", out var errEl)) message = errEl.GetString() ?? "";
-            if (string.IsNullOrEmpty(message)) message = body.Trim();
+            using var document = JsonDocument.Parse(body);
+            var root = document.RootElement;
+            var code = ReadString(root, "code");
+            var message = ReadString(root, "message");
+
+            if (root.TryGetProperty("error", out var error))
+            {
+                if (error.ValueKind == JsonValueKind.Object)
+                {
+                    code ??= ReadString(error, "code");
+                    message ??= ReadString(error, "message");
+                }
+                else if (error.ValueKind == JsonValueKind.String)
+                {
+                    message ??= error.GetString();
+                }
+            }
+
+            message ??= string.IsNullOrWhiteSpace(body)
+                ? "HTTP " + (int)response.StatusCode + ": " + response.ReasonPhrase
+                : body.Trim();
+
             return new SdkException((int)response.StatusCode, code, message, requestId);
         }
         catch (JsonException)
         {
-            return new SdkException((int)response.StatusCode, "",
+            return new SdkException(
+                (int)response.StatusCode,
+                null,
                 string.IsNullOrWhiteSpace(body)
                     ? "HTTP " + (int)response.StatusCode + ": " + response.ReasonPhrase
-                    : body.Trim(), requestId);
+                    : body.Trim(),
+                requestId);
         }
     }
 
+    private static string? ReadString(JsonElement value, string property) =>
+        value.TryGetProperty(property, out var element) && element.ValueKind == JsonValueKind.String
+            ? element.GetString()
+            : null;
+
     private static string? GetRequestId(HttpResponseMessage response)
     {
-        if (response.Headers.TryGetValues("X-Request-ID", out var values))
-            return values.FirstOrDefault();
-        if (response.Headers.TryGetValues("x-request-id", out values))
-            return values.FirstOrDefault();
+        foreach (var name in new[] { "x-request-id", "request-id" })
+        {
+            if (response.Headers.TryGetValues(name, out var values))
+                return values.FirstOrDefault();
+        }
         return null;
     }
 }

package/templates/csharp/types.hbs

@@ -2,103 +2,57 @@ namespace {{namespace}};
 
 using System;
 using System.Collections.Generic;
+using System.Runtime.Serialization;
 using System.Text.Json;
 using System.Text.Json.Serialization;
 
 {{#each schemas}}
-{{#if (neq ownership.kind "external")}}
-{{#if isEnum}}
-/// <summary>
-{{#if description}}
-/// {{description}}
-{{else}}
-/// {{name}} enumeration.
-{{/if}}
-/// </summary>
+{{#if external}}
+/// <summary>External schema placeholder for {{targetName}}.</summary>
+public sealed class {{targetName}}
+{
+    public JsonElement Value { get; set; }
+}
+
+{{else if isEnum}}
+/// <summary>{{#if description}}{{description}}{{else}}{{targetName}} enumeration.{{/if}}</summary>
 [JsonConverter(typeof(JsonStringEnumConverter))]
-public enum {{name}}
+public enum {{targetName}}
 {
 {{#each enumValues}}
-    /// <summary>
-    /// {{this}} value.
-    /// </summary>
-    [JsonStringEnumMemberName("{{this}}")]
-    {{pascalCase ../name}}{{pascalCase this}},
+    [EnumMember(Value = "{{value}}")] {{name}},
 {{/each}}
 }
 
 {{else if isUnionType}}
-/// <summary>
-{{#if description}}
-/// {{description}}
-{{else}}
-/// {{name}} union type.
-{{/if}}
-/// </summary>
-public class {{name}}
+/// <summary>{{#if description}}{{description}}{{else}}{{targetName}} union value.{{/if}}</summary>
+public sealed class {{targetName}}
 {
-    private readonly object _value;
-    private readonly Type _type;
-
-{{#each unionMembers}}
-    /// <summary>
-    /// Creates a {{../name}} from a {{this}} value.
-    /// </summary>
-    public {{../name}}({{this}} value)
-    {
-        _value = value!;
-        _type = typeof({{this}});
-    }
-
-{{/each}}
+    public {{targetName}}(object value) => Value = value;
+    public object Value { get; }
+}
 
-    /// <summary>
-    /// Gets the underlying value.
-    /// </summary>
-    public object Value => _value;
+{{else if isTypeAlias}}
+// {{name}} is emitted inline as {{{targetAliasType}}}.
 
-    /// <summary>
-    /// Attempts to get the value as the specified type.
-    /// </summary>
-    public bool TryGet<T>(out T? value)
-    {
-        if (_value is T v)
-        {
-            value = v;
-            return true;
-        }
-        value = default;
-        return false;
-    }
+{{else if isIntersectionType}}
+/// <summary>{{#if description}}{{description}}{{else}}{{targetName}} intersection value.{{/if}}</summary>
+public sealed class {{targetName}}
+{
+    public Dictionary<string, JsonElement> Values { get; set; } = new();
 }
 
 {{else}}
-/// <summary>
-{{#if description}}
-/// {{description}}
-{{else}}
-/// {{name}} schema type.
-{{/if}}
-/// </summary>
-public class {{name}}
+/// <summary>{{#if description}}{{description}}{{else}}{{targetName}} schema type.{{/if}}</summary>
+public class {{targetName}}{{#if targetExtends}} : {{targetExtends}}{{/if}}
 {
 {{#each properties}}
-    /// <summary>
-    {{#if description}}
-    /// {{description}}
-    {{/if}}
-    /// </summary>
-    [JsonPropertyName("{{name}}")]
-    {{#if (or nullable (not required))}}
-    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]
-    {{/if}}
-    {{#if deprecated}}
-    [Obsolete]
-    {{/if}}
-    public {{#if (eq type "string")}}{{#if (eq format "date-time")}}DateTime{{else}}string{{/if}}{{else if (eq type "integer")}}int{{else if (eq type "number")}}double{{else if (eq type "boolean")}}bool{{else if (eq type "array")}}List<object>?{{else}}{{type}}{{/if}}{{#if (or nullable (not required))}}?{{/if}} {{pascalCase name}} { get; set; }
+    [JsonPropertyName("{{name}}")]{{#if optional}}
+    [JsonIgnore(Condition = JsonIgnoreCondition.WhenWritingNull)]{{/if}}{{#if deprecated}}
+    [Obsolete]{{/if}}
+    public {{targetType}} {{pascalCase name}} { get; set; }{{{initializer}}}
 {{/each}}
 }
-{{/if}}
 
 {{/if}}
 {{/each}}