Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(sdk-php): state what the timeout bounds on Guzzle 7 streams
Yudhi Armyndharis5a55d6bcee3c
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.mdindex bc20c3c58..277274afe 100644--- a/docs/18-sdk-design.md+++ b/docs/18-sdk-design.md@@ -1090,7 +1090,7 @@ All payloads are associative arrays; all listed methods are synchronous and retu### Error Handling-All exceptions the SDK raises itself live in `OpenWA\Exceptions` and descend from `OpenWAException` (which extends PHP's `\Exception`). A transport failure that is not a timeout (a refused connection, a reset, a TLS verification failure) surfaces as one of Guzzle's own `GuzzleHttp\Exception\TransferException` subclasses and an invalid argument as `InvalidArgumentException`, so a catch-all names those as well. The subclass depends on the Guzzle major (a reset is a `RequestException` on Guzzle 7 and a `NetworkException`, which is not a `RequestException`, on Guzzle 8), so catch `TransferException` rather than a subclass. On Guzzle 7's stream handler (a host without `ext-curl`) a `timeout` of `0` still leaves PHP's `default_socket_timeout` before the response headers, and that wait ends with such a failure too, not an `OpenWATimeoutException` (see the [PHP README](../sdk/php/README.md)). Any non-2xx response is raised as an `OpenWAApiException`; the static `classify()` factory picks the most specific subclass by status code. An `OpenWAApiException` carries the HTTP status (`getStatus(): int`), the parsed error body (`getBody(): mixed`), and the NestJS `error` kind when present (`getErrorKind(): ?string`), plus the body's `code` (`getErrorCode(): ?string`), the retry delay in seconds from the body's `retryAfterSeconds` or the `Retry-After` header (`getRetryAfterSeconds(): ?int`) and the response headers (`getHeaders(): array`).+All exceptions the SDK raises itself live in `OpenWA\Exceptions` and descend from `OpenWAException` (which extends PHP's `\Exception`). A transport failure that is not a timeout (a refused connection, a reset, a TLS verification failure) surfaces as one of Guzzle's own `GuzzleHttp\Exception\TransferException` subclasses and an invalid argument as `InvalidArgumentException`, so a catch-all names those as well. The subclass depends on the Guzzle major (a reset is a `RequestException` on Guzzle 7 and a `NetworkException`, which is not a `RequestException`, on Guzzle 8), so catch `TransferException` rather than a subclass. On Guzzle 7's stream handler (a host without `ext-curl`) a `timeout` of `0` still leaves PHP's `default_socket_timeout` before the response headers, and that wait ends with such a failure too, not an `OpenWATimeoutException` (see the [PHP README](../sdk/php/README.md)). That handler also bounds each wait rather than the whole call: a silence in the body can last up to about twice the `timeout` before it is cut off, and a body that keeps trickling bytes is not cut off at all, while cURL and Guzzle 8's stream handler bound the whole call. Any non-2xx response is raised as an `OpenWAApiException`; the static `classify()` factory picks the most specific subclass by status code. An `OpenWAApiException` carries the HTTP status (`getStatus(): int`), the parsed error body (`getBody(): mixed`), and the NestJS `error` kind when present (`getErrorKind(): ?string`), plus the body's `code` (`getErrorCode(): ?string`), the retry delay in seconds from the body's `retryAfterSeconds` or the `Retry-After` header (`getRetryAfterSeconds(): ?int`) and the response headers (`getHeaders(): array`).| Exception | Extends | Trigger || ----------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |diff --git a/sdk/README.md b/sdk/README.mdindex d0ca47e6d..ec92d62d3 100644--- a/sdk/README.md+++ b/sdk/README.md@@ -277,12 +277,15 @@ testing, retry, tracing, or metrics. See [`go/README.md`](go/README.md).- **Default timeout** is 30s (configurable). `0` turns it off in the JavaScript,Python and PHP clients; the Go client reads `0` as the 30s default and the Javabuilder refuses it. The JavaScript, PHP, Go and Java clients bound the whole call,- response body included. The Python client's is per network operation- (connect, read, write, pool), so a response that keeps trickling bytes is not- cut off. On PHP, Guzzle 7's stream handler (a host without `ext-curl`) differs: a- `0` still leaves PHP's `default_socket_timeout` (60s by default) before the- response headers, and that wait ends with a Guzzle exception, not- `OpenWATimeoutException`; see the PHP README. Path segments (chat / message ids) are percent-encoded; a base-URL path+ response body included, except PHP on Guzzle 7's stream handler (below). The+ Python client's is per network operation (connect, read, write, pool), so a+ response that keeps trickling bytes is not cut off. On PHP, Guzzle 7's stream+ handler (a host without `ext-curl`) bounds each wait instead of the whole call:+ the wait for the response headers and each silence in the body, which can last+ up to about twice the `timeout`. A body that keeps trickling bytes is therefore+ not cut off. There a `0` still leaves PHP's `default_socket_timeout` (60s by+ default) before the response headers, and that wait ends with a Guzzle+ exception, not `OpenWATimeoutException`; see the PHP README. Path segments (chat / message ids) are percent-encoded; a base-URL pathprefix (e.g. behind a proxy at `/v1`) is preserved.## Developmentdiff --git a/sdk/php/README.md b/sdk/php/README.mdindex 3321ed688..9d45ab46e 100644--- a/sdk/php/README.md+++ b/sdk/php/README.md@@ -51,7 +51,7 @@ $client = new Client([]);```-The SDK `timeout` (30 seconds by default) applies to every request, including those sent through an injected client, and overrides that client's own `timeout`. On Guzzle 8 it is also sent as `read_timeout`, the idle bound of Guzzle's stream handler (the one in use when ext-curl is missing, or when you inject a `StreamHandler`), so it replaces a `read_timeout` set on the injected client, and `0` removes that bound. The SDK has no separate idle-timeout setting: a stricter idle bound means a lower `timeout`, which also limits the whole call. cURL handlers ignore `read_timeout`, and Guzzle 7 leaves the injected client's value alone.+The SDK `timeout` (30 seconds by default) applies to every request, including those sent through an injected client, and overrides that client's own `timeout`. On Guzzle 8 it is also sent as `read_timeout`, the idle bound of Guzzle's stream handler (the one in use when ext-curl is missing, or when you inject a `StreamHandler`), so it replaces a `read_timeout` set on the injected client, and `0` removes that bound. The SDK has no separate idle-timeout setting: a stricter idle bound means a lower `timeout`, which also limits the whole call except on Guzzle 7's stream handler, where it bounds each wait instead (see [Errors](#errors)). cURL handlers ignore `read_timeout`, and Guzzle 7 leaves the injected client's value alone.The optional `defaultHeaders` map accepts strings, scalar values, null, and non-empty lists of those values. Numbers, booleans, and null are converted to text. An empty list is rejected by header name before any request is sent because Guzzle 8 cannot represent a header with zero values. Use `''` for an empty header value.@@ -89,7 +89,10 @@ unchanged.Guzzle's stream handler, which Guzzle uses on a host without `ext-curl`, throws a plain Guzzle exceptionwhen a gateway stays silent past the timeout, before the response headers on either Guzzle major and, on-Guzzle 7, in the middle of the body. The SDK turns such a failure into `OpenWATimeoutException` when it has no+Guzzle 7, in the middle of the body, where a silence can last up to about twice the `timeout` before it+is cut off. On Guzzle 7 that handler bounds each wait, not the whole call, so a body that keeps trickling+bytes is not cut off and arrives however long it takes; cURL, and Guzzle 8's stream handler, bound the+whole call. The SDK turns such a failure into `OpenWATimeoutException` when it has noresponse and lasted at least the whole `timeout`, so a failure of that length from another cause, such as aslow name-resolution error, is reported as a timeout too. A `timeout` of `0` has no bound to compare with, andon Guzzle 7 the wait for the response headers is still ended by PHP's `default_socket_timeout` (60 seconds by