/ 
Kubernetes-REST-1.107
⭐ Starred 2 / Kubernetes::REST::Role::IO

NAME

Kubernetes::REST::Role::IO - Interface role for HTTP backends

VERSION

version 1.107

SYNOPSIS

package My::AsyncIO;
use Moo;
with 'Kubernetes::REST::Role::IO';

sub call {
    my ($self, $req) = @_;
    # Execute HTTP request, return Kubernetes::REST::HTTPResponse
    ...
}

sub call_streaming {
    my ($self, $req, $data_callback) = @_;
    # Execute HTTP request with streaming callback
    ...
}

# Optional: full-duplex transport (WebSocket/SPDY)
sub call_duplex {
    my ($self, $req, %callbacks) = @_;
    ...
}

DESCRIPTION

This role defines the interface that HTTP backends must implement. Kubernetes::REST delegates all HTTP communication through this interface, making it possible to swap out the transport layer.

The default backend is Kubernetes::REST::LWPIO (using LWP::UserAgent). An alternative Kubernetes::REST::HTTPTinyIO (using HTTP::Tiny) is provided. To use an async event loop, implement this role with e.g. Net::Async::HTTP.

Both shipped backends are synchronous, request/response-only transports: neither implements call_duplex (see "supports_duplex" below), so Kubernetes::REST methods that need full-duplex transport (port_forward, exec, attach) croak against them by design. A backend that wants to support those needs to implement call_duplex($req, %callbacks) itself, as sketched in the "SYNOPSIS".

Encoding contract

Request and response bodies are bytes, never character strings - this holds for call and call_streaming alike, whatever kind of request they carry.

A backend receives $req->content already UTF-8 encoded (the core client's JSON encoder runs with utf8 => 1) and must put it on the wire unchanged. It must hand back $res->content - and every streaming chunk - as the bytes it received, undoing Content-Encoding (gzip) but not the charset.

Two different callers rely on this, for two different reasons:

  • For get/list/watch, Kubernetes::REST decodes UTF-8 itself once the JSON is parsed, together with IO::K8s. A backend that decodes the charset first causes silent double decoding (mojibake) on any non-ASCII value.

  • For log (streamed via call_streaming just like watch), the bytes are handed straight back to the caller undecoded, on purpose: container output is not guaranteed to be UTF-8, or even text, so there is no safe charset for the backend to assume. See "log" in Kubernetes::REST.

With LWP::UserAgent that means $res->decoded_content(charset => 'none') rather than $res->decoded_content. See also "ENCODING" in Kubernetes::REST for the full picture from the caller's side of this module.

call

my $response = $io->call($req);

Required. Execute an HTTP request. Receives a Kubernetes::REST::HTTPRequest with method, url, headers, and optionally content already set.

Must return a Kubernetes::REST::HTTPResponse with status and content, the latter as bytes - see "Encoding contract".

call_streaming

my $response = $io->call_streaming($req, $data_callback);

Required. Execute an HTTP request with streaming response. The $data_callback is called with each chunk of data as it arrives: $data_callback->($chunk). Chunks are bytes - see "Encoding contract".

Must return a Kubernetes::REST::HTTPResponse when the stream ends.

supports_duplex

if ($io->supports_duplex) {
    ...
}

Optional capability probe for full-duplex protocols used by Kubernetes subresources such as pod port-forward and exec/attach streams.

Returns true if the backend implements call_duplex, false otherwise.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/pplu/kubernetes-rest/issues.

IRC

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

CONTRIBUTING

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

AUTHORS

  • Torsten Raudssus <getty@cpan.org>

  • Jose Luis Martinez Torres <jlmartin@cpan.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2019-2026 by Jose Luis Martinez Torres <jlmartin@cpan.org>.

This is free software, licensed under:

The Apache License, Version 2.0, January 2004