Free, Open Source, Self-Hosted WhatsApp API Gateway
TypeScript apibotgatewayself-hostedwhatsappwhatsapp-apiwhatsapp-automationwhatsapp-botwhatsapp-gatewaywhatsapp-gateway-apiwhatsapp-webwhatsapp-web-api
docs(sdk): state the PHP timeout limits on the stream handler
Yudhi Armyndharis39d1acd6937c
diff --git a/docs/18-sdk-design.md b/docs/18-sdk-design.mdindex 8d9bd09a6..545948df8 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. 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's stream handler (a host without `ext-curl`) a gateway that stays silent past the timeout is 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`).| Exception | Extends | Trigger || ----------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |diff --git a/sdk/README.md b/sdk/README.mdindex 17a7eeb4a..1efd0396f 100644--- a/sdk/README.md+++ b/sdk/README.md@@ -279,7 +279,11 @@ testing, retry, tracing, or metrics. See [`go/README.md`](go/README.md).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. Path segments (chat / message ids) are percent-encoded; a base-URL path+ cut off. On PHP, Guzzle's stream handler (a host without `ext-curl`) differs: a+ gateway that stays silent past the timeout surfaces as a Guzzle exception, not+ `OpenWATimeoutException`, and on Guzzle 7 a `0` still leaves PHP's+ `default_socket_timeout` (60s by default) before the response headers; 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 1193814db..b65f1423e 100644--- a/sdk/php/README.md+++ b/sdk/php/README.md@@ -79,6 +79,14 @@ may still have been applied, so re-read the state before repeating it. In a routforward that fails before reaching the owner node answers 503, one that fails after the requestreached it answers 502 or 504, and a 503 from the owner itself is relayed unchanged.+Timeouts differ on Guzzle's stream handler, which Guzzle uses on a host without `ext-curl` (the cURL+handler is unaffected). A gateway that stays silent past the timeout surfaces as a Guzzle exception+instead of `OpenWATimeoutException`: before the response headers on either Guzzle major+(`ConnectException` on Guzzle 7, `RequestException` on Guzzle 8) and, on Guzzle 7, in the middle of the+body. On Guzzle 7 a `timeout` of `0` does not turn the wait for the response headers off either: PHP's+`default_socket_timeout` (60 seconds by default) still ends it. Catch `GuzzleHttp\Exception\TransferException`+as well as `OpenWATimeoutException` if the application must handle a silent gateway on such a host.+```phpuse OpenWA\Exceptions\OpenWANotFoundException;