/ 
Langertha-Knarr-1.102
/ Langertha::Knarr::Role::UpstreamHTTP

NAME

Langertha::Knarr::Role::UpstreamHTTP - Timed Net::Async::HTTP client for handlers that call an upstream

VERSION

version 1.102

SYNOPSIS

package My::Handler;
use Moose;
with 'Langertha::Knarr::Handler', 'Langertha::Knarr::Role::UpstreamHTTP';

my $resp = await $self->_upstream_request_f( request => $http_req );
# streaming: stall_timeout instead of a total timeout
await $self->_upstream_request_f( request => $http_req, on_header => sub { ... } );

DESCRIPTION

The HTTP client of the handlers that call an upstream themselves (Langertha::Knarr::Handler::Passthrough, Langertha::Knarr::Handler::A2AClient, Langertha::Knarr::Handler::ACPClient) and the timeouts it applies. Net::Async::HTTP sets none of its own, so an upstream that accepts the connection and never answers would hold the client's request open forever.

A plain request gets "timeout" as its total time. A streaming request (on_header, or stream => 1 for a stream read whole) gets "stall_timeout" instead: the time the upstream may stay silent, since a long steady stream is legitimate. On expiry the future fails with <class>: upstream <url> timed out after Ns and the category timeout or stall_timeout, which "is_upstream_timeout" recognizes.

timeout

Seconds a non-streaming upstream request may take in total. Default 300; 0 disables it. Set from upstream_timeout / KNARR_UPSTREAM_TIMEOUT by knarr start.

stall_timeout

Seconds a streaming upstream request may go without receiving a byte, waiting for the response headers included. Default 120; 0 disables it. Set from upstream_stall_timeout / KNARR_UPSTREAM_STALL_TIMEOUT by knarr start.

loop

Optional IO::Async::Loop. Defaults to IO::Async::Loop->new.

is_upstream_timeout

my $is_timeout = Langertha::Knarr::Role::UpstreamHTTP->is_upstream_timeout($category);

True when a failure category from Net::Async::HTTP is one of its timeouts (timeout, stall_timeout).

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/langertha-knarr/issues.

IRC

Join #langertha on irc.perl.org or message Getty directly.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.