Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

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.md
index 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.md
index 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 Java
builder 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 path
prefix (e.g. behind a proxy at `/v1`) is preserved.
## Development
diff --git a/sdk/php/README.md b/sdk/php/README.md
index 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 exception
when 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 no
response and lasted at least the whole `timeout`, so a failure of that length from another cause, such as a
slow name-resolution error, is reported as a timeout too. A `timeout` of `0` has no bound to compare with, and
on Guzzle 7 the wait for the response headers is still ended by PHP's `default_socket_timeout` (60 seconds by