@apollo-deploy/tesseract 1.8.0 → 2.0.0

package/templates/rust/readme.hbs

@@ -1,76 +1,63 @@
-# {{title}}
+# {{title}} Rust SDK
 
-{{#if description}}{{description}}{{/if}}
+{{#if description}}{{description}}{{else}}Rust client for the {{title}} API.{{/if}}
 
-{{#unless description}}An auto-generated Rust SDK for the {{title}} API.{{/unless}}
+> Generated by Tesseract. Generated source files should not be edited manually.
 
 ## Installation
 
-Add this to your `Cargo.toml`:
-
 ```toml
 [dependencies]
-{{crateName}} = "{{#if packageVersion}}{{packageVersion}}{{else}}0.1.0{{/if}}"
+{{crateName}} = "{{packageVersion}}"
 ```
 
-## Quick Start
+## Quick start
 
 ```rust
-use {{crateName}}::Client;
-use {{crateName}}::ClientConfig;
+use {{crateName}}::{Client, ClientConfig};
 
 #[tokio::main]
 async fn main() -> Result<(), Box<dyn std::error::Error>> {
-    let mut config = ClientConfig::default();
-{{#each securitySchemes}}
-{{#if (eq type "apiKey")}}
-    config.{{snakeCase configKey}} = Some("your-api-key".to_string());
-{{/if}}
-{{#if (and (eq type "http") (eq scheme "bearer"))}}
-    config.{{snakeCase configKey}} = Some("your-bearer-token".to_string());
+    let client = Client::new(ClientConfig::default());
+{{#if groups.length}}
+    let _api = &client.{{snakeCase groups.[0].name}};
 {{/if}}
-{{/each}}
-
-    let client = Client::new(config);
-
-    // Use domain clients
-{{#each groups}}
-{{#if @first}}
-    // let result = client.{{snakeCase name}}.some_operation().await?;
-{{/if}}
-{{/each}}
-
     Ok(())
 }
 ```
 
-## API Reference
+## Configuration and reliability
 
-{{#each groups}}
-### {{interfaceName}}
+The generated client supports bounded timeouts, exponential-backoff retries, `Retry-After` handling, structured `SdkError` values, and safe client reuse. Unsafe requests are not retried unless they are explicitly made idempotent or unsafe retries are enabled.
 
-{{#if description}}
-{{description}}
-{{/if}}
+```rust
+use std::time::Duration;
 
-| Method | HTTP | Description |
-|--------|------|-------------|
-{{#each operations}}
-| `{{snakeCase name}}()` | `{{httpMethod}}` | {{#if summary}}{{summary}}{{else}}—{{/if}} |
-{{/each}}
+let config = ClientConfig {
+    timeout: Duration::from_secs(30),
+    max_retries: 3,
+    ..Default::default()
+};
+```
 
+## Documentation
+
+- [Documentation index](./docs/README.md)
+- [Generated types](./docs/types.md)
+
+| Domain | Description |
+|---|---|
+{{#each groups}}
+| [{{interfaceName}}](./docs/domains/{{fileName}}.md) | {{#if description}}{{description}}{{else}}{{name}} operations{{/if}} |
 {{/each}}
 
-## Error Handling
+## Error handling
+
+All operations return `Result<T, SdkError>`. API errors retain the HTTP status, machine-readable code, request ID, and response body where available.
 
-All API methods return `Result<T, SdkError>`. The `SdkError` enum has these variants:
+## Requirements
 
-| Variant | Description |
-|---------|-------------|
-| `ApiError` | Server returned an error (4xx/5xx) |
-| `NetworkError` | Request failed due to connectivity issues |
-| `DeserializationError` | Response body could not be parsed |
-| `ValidationError` | Invalid request parameters |
+- Rust 1.75 or later
 
 ## License
 

package/templates/rust/transport.hbs

@@ -2,11 +2,11 @@ use crate::error::SdkError;
 use reqwest::{Client as ReqwestClient, Method, RequestBuilder, Response, StatusCode};
 use serde::de::DeserializeOwned;
 use serde::Serialize;
+use std::collections::HashMap;
 use std::sync::Arc;
-use std::time::Duration;
+use std::time::{Duration, SystemTime, UNIX_EPOCH};
 use url::Url;
 
-/// Internal transport configuration.
 #[derive(Debug, Clone)]
 pub struct TransportConfig {
     pub base_url: String,
@@ -15,13 +15,10 @@ pub struct TransportConfig {
 {{/each}}
     pub timeout: Duration,
     pub max_retries: u32,
+    pub retry_unsafe_requests: bool,
+    pub default_headers: HashMap<String, String>,
 }
 
-/// HTTP transport layer for the SDK.
-///
-/// Handles request building, authentication, retries, and error mapping.
-/// Cloning a `Transport` produces a shallow clone that shares the underlying
-/// reqwest client.
 #[derive(Clone)]
 pub struct Transport {
     client: ReqwestClient,
@@ -29,20 +26,15 @@ pub struct Transport {
 }
 
 impl Transport {
-    /// Create a new transport with the given configuration.
     pub fn new(config: TransportConfig) -> Self {
         let client = ReqwestClient::builder()
             .timeout(config.timeout)
+            .user_agent("{{crateName}}-rust-sdk/{{packageVersion}}")
             .build()
             .expect("failed to build reqwest client");
-
-        Self {
-            client,
-            config: Arc::new(config),
-        }
+        Self { client, config: Arc::new(config) }
     }
 
-    /// Execute a request, deserializing the response body as JSON.
     pub async fn execute<T: DeserializeOwned>(
         &self,
         method: Method,
@@ -51,23 +43,11 @@ impl Transport {
         body: Option<&(impl Serialize + ?Sized)>,
         headers: Option<&[(String, String)]>,
     ) -> Result<T, SdkError> {
-        let url = self.build_url(path, query)?;
-
-        let mut req = self.client.request(method, url);
-
-        req = self.apply_auth(req);
-        req = self.apply_headers(req, headers);
-
-        if let Some(b) = body {
-            req = req.json(b);
-        }
-
-        let response = self.execute_with_retry(req).await?;
-
+        let request = self.build_request(method.clone(), path, query, body, headers)?;
+        let response = self.execute_with_retry(request, &method, headers).await?;
         self.handle_response(response).await
     }
 
-    /// Execute a request that returns the raw response text.
     pub async fn execute_raw(
         &self,
         method: Method,
@@ -76,212 +56,243 @@ impl Transport {
         body: Option<&(impl Serialize + ?Sized)>,
         headers: Option<&[(String, String)]>,
     ) -> Result<String, SdkError> {
-        let url = self.build_url(path, query)?;
-
-        let mut req = self.client.request(method, url);
-
-        req = self.apply_auth(req);
-        req = self.apply_headers(req, headers);
-
-        if let Some(b) = body {
-            req = req.json(b);
-        }
-
-        let response = self.execute_with_retry(req).await?;
-
+        let request = self.build_request(method.clone(), path, query, body, headers)?;
+        let response = self.execute_with_retry(request, &method, headers).await?;
         let status = response.status();
-        let text = response.text().await.map_err(|e| {
-            SdkError::DeserializationError(format!("failed to read response body: {}", e))
+        let request_id = response
+            .headers()
+            .get("x-request-id")
+            .or_else(|| response.headers().get("request-id"))
+            .and_then(|value| value.to_str().ok())
+            .map(String::from);
+        let text = response.text().await.map_err(|error| {
+            SdkError::DeserializationError(format!("failed to read response body: {}", error))
         })?;
-
         if status.is_success() {
             Ok(text)
         } else {
-            Err(self.build_api_error(status, &text))
+            Err(Self::build_api_error(status, request_id, &text))
         }
     }
 
-    // ── private helpers ─────────────────────────────────────────────────────
+    fn build_request(
+        &self,
+        method: Method,
+        path: &str,
+        query: Option<&[(String, String)]>,
+        body: Option<&(impl Serialize + ?Sized)>,
+        headers: Option<&[(String, String)]>,
+    ) -> Result<RequestBuilder, SdkError> {
+        let url = self.build_url(path, query)?;
+        let mut request = self.client.request(method, url);
+        request = self.apply_auth(request);
+        request = self.apply_headers(request, headers);
+        if let Some(body) = body {
+            request = request.json(body);
+        }
+        Ok(request)
+    }
 
     fn build_url(
         &self,
         path: &str,
         query: Option<&[(String, String)]>,
     ) -> Result<Url, SdkError> {
-        let base = Url::parse(&self.config.base_url).map_err(|e| {
-            SdkError::ValidationError(format!("invalid base URL: {}", e))
-        })?;
-
-        let joined = base.join(path).map_err(|e| {
-            SdkError::ValidationError(format!("invalid path '{}': {}", path, e))
-        })?;
-
+        let base = Url::parse(&self.config.base_url)
+            .map_err(|error| SdkError::ValidationError(format!("invalid base URL: {}", error)))?;
+        let mut url = base
+            .join(path)
+            .map_err(|error| SdkError::ValidationError(format!("invalid path '{}': {}", path, error)))?;
         if let Some(params) = query {
-            let mut url = joined;
-            {
-                let mut qp = url.query_pairs_mut();
-                for (k, v) in params {
-                    qp.append_pair(k, v);
-                }
+            let mut pairs = url.query_pairs_mut();
+            for (key, value) in params {
+                pairs.append_pair(key, value);
             }
-            Ok(url)
-        } else {
-            Ok(joined)
         }
+        Ok(url)
     }
 
-    fn apply_auth(&self, mut req: RequestBuilder) -> RequestBuilder {
+    fn apply_auth(&self, mut request: RequestBuilder) -> RequestBuilder {
 {{#each securitySchemes}}
 {{#if (eq type "apiKey")}}
 {{#if (eq in "header")}}
         if let Some(ref key) = self.config.{{snakeCase configKey}} {
-            req = req.header("{{paramName}}", key);
+            request = request.header("{{paramName}}", key);
         }
 {{/if}}
-{{#if (eq in "query")}}
-        // API key via query parameter handled during URL construction
 {{/if}}
-{{/if}}
-{{#if (and (eq type "http") (eq scheme "bearer"))}}
-        if let Some(ref token) = self.config.{{snakeCase configKey}} {
-            req = req.header("Authorization", format!("Bearer {}", token));
-        }
-{{/if}}
-{{#if (eq type "oauth2")}}
+{{#if (or (and (eq type "http") (eq scheme "bearer")) (eq type "oauth2") (eq type "openIdConnect"))}}
         if let Some(ref token) = self.config.{{snakeCase configKey}} {
-            req = req.header("Authorization", format!("Bearer {}", token));
-        }
-{{/if}}
-{{#if (eq type "openIdConnect")}}
-        if let Some(ref token) = self.config.{{snakeCase configKey}} {
-            req = req.header("Authorization", format!("Bearer {}", token));
+            request = request.bearer_auth(token);
         }
 {{/if}}
 {{/each}}
-        req
+        request
     }
 
     fn apply_headers(
         &self,
-        mut req: RequestBuilder,
+        mut request: RequestBuilder,
         headers: Option<&[(String, String)]>,
     ) -> RequestBuilder {
-        if let Some(hdrs) = headers {
-            for (key, value) in hdrs {
-                req = req.header(key.as_str(), value.as_str());
+        request = request.header("Accept", "application/json");
+        for (key, value) in &self.config.default_headers {
+            request = request.header(key, value);
+        }
+        if let Some(headers) = headers {
+            for (key, value) in headers {
+                request = request.header(key, value);
             }
         }
-        req
+        request
     }
 
     async fn execute_with_retry(
         &self,
-        req: RequestBuilder,
+        request: RequestBuilder,
+        method: &Method,
+        headers: Option<&[(String, String)]>,
     ) -> Result<Response, SdkError> {
-        let max_retries = self.config.max_retries;
+        let can_retry = self.can_retry(method, headers);
         let mut attempt = 0u32;
 
         loop {
-            let request = req
-                .try_clone()
-                .ok_or_else(|| SdkError::NetworkError("failed to clone request for retry".to_string()))?;
-
-            match request.send().await {
+            let current = request.try_clone().ok_or_else(|| {
+                SdkError::NetworkError("request body cannot be cloned for execution".to_string())
+            })?;
+            match current.send().await {
                 Ok(response) => {
                     let status = response.status();
-
-                    // Retry on server errors (5xx) and 429 Too Many Requests
-                    if status.is_server_error() || status == StatusCode::TOO_MANY_REQUESTS {
-                        if attempt < max_retries {
-                            attempt += 1;
-                            let backoff = Duration::from_millis(
-                                200u64 * 2u64.pow(attempt),
-                            );
-                            tokio::time::sleep(backoff).await;
-                            continue;
-                        }
+                    if can_retry && is_retryable_status(status) && attempt < self.config.max_retries {
+                        let delay = retry_delay(response.headers().get("retry-after"), attempt);
+                        attempt += 1;
+                        tokio::time::sleep(delay).await;
+                        continue;
                     }
                     return Ok(response);
                 }
-                Err(e) => {
-                    if attempt < max_retries && e.is_connect() || e.is_timeout() {
+                Err(error) => {
+                    if can_retry
+                        && attempt < self.config.max_retries
+                        && (error.is_connect() || error.is_timeout() || error.is_request())
+                    {
+                        let delay = retry_delay(None, attempt);
                         attempt += 1;
-                        let backoff = Duration::from_millis(
-                            200u64 * 2u64.pow(attempt),
-                        );
-                        tokio::time::sleep(backoff).await;
+                        tokio::time::sleep(delay).await;
                         continue;
                     }
-                    return Err(SdkError::NetworkError(e.to_string()));
+                    return Err(SdkError::NetworkError(error.to_string()));
                 }
             }
         }
     }
 
-    async fn handle_response<T: DeserializeOwned>(
-        &self,
-        response: Response,
-    ) -> Result<T, SdkError> {
+    fn can_retry(&self, method: &Method, headers: Option<&[(String, String)]>) -> bool {
+        if self.config.retry_unsafe_requests
+            || method == Method::GET
+            || method == Method::HEAD
+            || method == Method::OPTIONS
+            || method == Method::PUT
+            || method == Method::DELETE
+        {
+            return true;
+        }
+
+        self.config
+            .default_headers
+            .iter()
+            .chain(headers.unwrap_or_default().iter())
+            .any(|(name, value)| name.eq_ignore_ascii_case("x-idempotency-key") && !value.is_empty())
+    }
+
+    async fn handle_response<T: DeserializeOwned>(&self, response: Response) -> Result<T, SdkError> {
         let status = response.status();
-        let text = response.text().await.map_err(|e| {
-            SdkError::DeserializationError(format!("failed to read response body: {}", e))
+        let request_id = response
+            .headers()
+            .get("x-request-id")
+            .or_else(|| response.headers().get("request-id"))
+            .and_then(|value| value.to_str().ok())
+            .map(String::from);
+        let text = response.text().await.map_err(|error| {
+            SdkError::DeserializationError(format!("failed to read response body: {}", error))
         })?;
-
         if status.is_success() {
-            serde_json::from_str(&text).map_err(|e| {
-                SdkError::DeserializationError(format!(
-                    "failed to deserialize response (status {}): {}",
-                    status, e
-                ))
-            })
+            if text.trim().is_empty() {
+                serde_json::from_str("null").map_err(|error| {
+                    SdkError::DeserializationError(format!("empty response could not be decoded: {}", error))
+                })
+            } else {
+                serde_json::from_str(&text).map_err(|error| {
+                    SdkError::DeserializationError(format!(
+                        "failed to deserialize response (status {}): {}",
+                        status, error
+                    ))
+                })
+            }
         } else {
-            Err(self.build_api_error(status, &text))
+            Err(Self::build_api_error(status, request_id, &text))
         }
     }
 
-    fn build_api_error(&self, status: StatusCode, body: &str) -> SdkError {
-        // Try to extract structured error info from the JSON body
-        let code = serde_json::from_str::<serde_json::Value>(body)
-            .ok()
-            .and_then(|v| {
-                v.get("code")
-                    .or_else(|| v.get("error"))
-                    .and_then(|c| c.as_str().map(String::from))
-                    .or_else(|| {
-                        v.get("error")
-                            .and_then(|e| e.get("code"))
-                            .and_then(|c| c.as_str().map(String::from))
-                    })
-            });
-
-        let message = serde_json::from_str::<serde_json::Value>(body)
-            .ok()
-            .and_then(|v| {
-                v.get("message")
-                    .or_else(|| v.get("error"))
-                    .and_then(|m| {
-                        if m.is_string() {
-                            m.as_str().map(String::from)
-                        } else {
-                            m.get("message").and_then(|s| s.as_str().map(String::from))
-                        }
-                    })
-            })
-            .unwrap_or_else(|| body.to_string());
-
+    fn build_api_error(status: StatusCode, request_id: Option<String>, body: &str) -> SdkError {
+        let parsed = serde_json::from_str::<serde_json::Value>(body).ok();
+        let nested = parsed.as_ref().and_then(|value| value.get("error"));
+        let code = parsed
+            .as_ref()
+            .and_then(|value| value.get("code"))
+            .or_else(|| nested.and_then(|value| value.get("code")))
+            .or_else(|| nested.filter(|value| value.is_string()))
+            .and_then(|value| value.as_str())
+            .map(String::from);
+        let message = parsed
+            .as_ref()
+            .and_then(|value| value.get("message"))
+            .or_else(|| nested.and_then(|value| value.get("message")))
+            .or_else(|| nested.filter(|value| value.is_string()))
+            .and_then(|value| value.as_str())
+            .unwrap_or(body)
+            .to_string();
+        let body_request_id = parsed
+            .as_ref()
+            .and_then(|value| value.get("request_id"))
+            .and_then(|value| value.as_str())
+            .map(String::from);
         SdkError::ApiError {
             status: status.as_u16(),
             code,
             message,
+            request_id: body_request_id.or(request_id),
             body: body.to_string(),
         }
     }
 }
 
+fn is_retryable_status(status: StatusCode) -> bool {
+    matches!(status.as_u16(), 408 | 425 | 429 | 500 | 502 | 503 | 504)
+}
+
+fn retry_delay(retry_after: Option<&reqwest::header::HeaderValue>, attempt: u32) -> Duration {
+    if let Some(value) = retry_after.and_then(|value| value.to_str().ok()) {
+        if let Ok(seconds) = value.parse::<f64>() {
+            return Duration::from_secs_f64(seconds.max(0.0).min(30.0));
+        }
+        if let Ok(time) = httpdate::parse_http_date(value) {
+            if let Ok(delay) = time.duration_since(SystemTime::now()) {
+                return delay.min(Duration::from_secs(30));
+            }
+        }
+    }
+    let base = (400u64.saturating_mul(2u64.saturating_pow(attempt))).min(30_000);
+    let jitter = SystemTime::now()
+        .duration_since(UNIX_EPOCH)
+        .unwrap_or_default()
+        .subsec_nanos() as u64
+        % (base / 2 + 1);
+    Duration::from_millis((base + jitter).min(30_000))
+}
+
 impl std::fmt::Debug for Transport {
-    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
-        f.debug_struct("Transport")
-            .field("config", &self.config)
-            .finish()
+    fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
+        formatter.debug_struct("Transport").field("config", &self.config).finish()
     }
 }