API-Docker
view release on metacpan or search on metacpan
lib/API/Docker/Role/HTTP.pm view on Meta::CPAN
package API::Docker::Role::HTTP;
# ABSTRACT: HTTP transport role for Docker Engine API
our $VERSION = '0.004';
use Moo::Role;
use IO::Socket::UNIX;
use IO::Socket::INET;
# For the sysread method on a plain filehandle: _pull calls it as a method so
# that IO::Socket::SSL's own gets picked up rather than the builtin. See _pull.
use IO::Handle;
use Socket qw( SOL_SOCKET SO_RCVTIMEO );
# How a read that delivered nothing says it ran out of time rather than out of
# stream (EAGAIN/EWOULDBLOCK), and how it says it was interrupted rather than
# either (EINTR). See _pull and _timed_out.
use Errno qw( EAGAIN EWOULDBLOCK EINTR );
use JSON::MaybeXS qw( encode_json decode_json );
use Scalar::Util qw( looks_like_number );
use Path::Tiny;
use Carp qw( croak shortmess );
use Log::Any qw( $log );
use API::Docker::Error::HTTP;
use API::Docker::Error::Stream;
use API::Docker::Error::Timeout;
use API::Docker::Error::Truncated;
use namespace::clean;
requires 'host';
requires 'api_version';
requires 'tls';
requires 'cert_path';
requires 'tls_insecure';
# Docker stream frame types, indexed by the first byte of the frame header.
my @STREAM_TYPE = qw( stdin stdout stderr );
# A field name is an RFC 9110 token and nothing else. Anything outside this
# set -- CR, LF, a space, a colon -- is rejected rather than stripped; see
# _assert_header_name.
my $HEADER_NAME = qr/\A[0-9A-Za-z!#\$%&'*+.^_`|~-]+\z/;
# The request-target path is caller data -- a container name, an image
# reference -- spliced straight into the request line as /v$version$path, so a
# byte the line's own grammar reads rewrites the request rather than naming a
# resource: CR or LF ends the line, a space opens the HTTP-version field, and
# a ? or # opens the query or fragment. It is held to the RFC 3986 origin-form
# path character set -- unreserved, the sub-delims, and : @ % / -- and
# rejected, not sanitised, for the reason a header name is (see
# _assert_request_path). Query parameters carry the ? and everything after it
# and are assembled separately below, each element run through _uri_encode.
my $REQUEST_PATH = qr{\A[A-Za-z0-9\-._~:/\@!\$&'()*+,;=%]*\z};
# The three units a response can be cut into, one option each. A request picks
# one of them, or none and gets the buffered path; see _stream_handler.
my @STREAM_OPTION = qw( on_event on_frame on_chunk );
# What a response body has to start with to be worth handing to decode_json.
# An object or an array is not the whole of JSON: the engine answers several
# endpoints with a bare JSON scalar, and a `null` used to come back as the
# four-character string 'null'. See _request.
my $JSON_BODY = qr/\A\s*(?:[\[\{"]|-?[0-9]|true|false|null)/;
# How much is asked for per sysread. Strictly an upper bound -- sysread
# returns what has arrived rather than filling to it (see _pull), so on a live
# feed a call typically comes back with one burst, and asking for 64K costs
# nothing but the size of the buffer it lands in.
my $READ_SIZE = 64 * 1024;
has read_timeout => (
is => 'ro',
);
has connect_timeout => (
is => 'ro',
);
has _socket => (
is => 'lazy',
clearer => '_clear_socket',
);
# The connect timeout and the endpoint it belongs to, on their way to
# _build__socket. It is a lazy builder and so cannot be handed an argument,
# and the value is per request rather than per client -- hence rw, with
# _reconnect as the only writer, setting it immediately before the build and
# clearing it immediately after. Unset is the whole of the old behaviour: no
# Timeout on any constructor, and the plain croak on a failure.
has _pending_connect => (
is => 'rw',
init_arg => undef,
);
sub _build__socket {
my ($self) = @_;
my $host = $self->host;
my $pending = $self->_pending_connect;
my $timeout = $pending ? $pending->{timeout} : undef;
if ($host =~ m{^unix://(.+)$}) {
my $path = $1;
$log->debugf("Connecting to Unix socket: %s", $path);
my $sock = IO::Socket::UNIX->new(
Peer => $path,
Type => SOCK_STREAM,
$timeout ? (Timeout => $timeout) : (),
);
unless ($sock) {
# Asked before anything else can touch $@ or $!, which is the whole of
# the evidence; see _connect_expired.
$self->_croak_connect_timeout($pending, 'unix://' . $path)
if $self->_connect_expired($timeout);
croak "Cannot connect to Unix socket $path: $!";
}
return $sock;
}
elsif ($host =~ m{^tcp://([^:]+):(\d+)$}) {
my ($addr, $port) = ($1, $2);
unless ($self->tls) {
$log->debugf("Connecting to TCP %s:%s", $addr, $port);
my $sock = IO::Socket::INET->new(
PeerAddr => $addr,
PeerPort => $port,
Proto => 'tcp',
$timeout ? (Timeout => $timeout) : (),
);
unless ($sock) {
$self->_croak_connect_timeout($pending, $addr . ':' . $port)
if $self->_connect_expired($timeout);
croak "Cannot connect to $addr:$port: $!";
}
return $sock;
}
# Built before the connection is opened: a cert_path that names nothing,
# or half a client certificate, is a configuration mistake and the caller
# should hear about it as one rather than as a handshake failure.
my %ssl = $self->_ssl_options($addr);
$log->debugf("Connecting to TCP %s:%s over TLS (verification %s)",
$addr, $port, $self->tls_insecure ? 'off' : 'on');
my $sock = IO::Socket::SSL->new(
PeerAddr => $addr,
PeerPort => $port,
Proto => 'tcp',
$timeout ? (Timeout => $timeout) : (),
%ssl,
);
unless ($sock) {
$self->_croak_connect_timeout($pending, $addr . ':' . $port . ' (TLS)')
if $self->_connect_expired($timeout);
# $SSL_ERROR carries the handshake failure -- an untrusted certificate,
# a name that does not match -- and $! the plain connect failure. Both
# are named because either can be the one that happened. The pragma is
# for the package variable of a module that is not loaded at compile
# time, which perl would otherwise report as a probable typo.
no warnings 'once';
croak 'Cannot connect to ' . $addr . ':' . $port . ' over TLS: '
. ($IO::Socket::SSL::SSL_ERROR || $! || 'unknown error');
}
return $sock;
}
else {
croak "Unsupported host format: $host (expected unix:// or tcp://)";
}
}
# Loaded here rather than with the other modules at the top of the file.
# IO::Socket::SSL pulls in Net::SSLeay, which is XS compiled against libssl,
# and the unix:// transport -- local Docker, rootless Podman, the default and
# the only one most installations use -- never needs a byte of it. A hard
# dependency would make this client unbuildable on a machine with no OpenSSL
# headers for the sake of a transport it is not using, so it is a recommended
# one and this is the point where its absence becomes an error.
sub _load_ssl {
my ($self) = @_;
return 1 if eval { require IO::Socket::SSL; 1 };
my $why = $@ || 'unknown error';
$why =~ s/\s+\z//;
croak __PACKAGE__ . ': tls => 1 needs IO::Socket::SSL, which failed to '
. 'load (' . $why . '). It is a recommended rather than a required '
. 'dependency because the unix:// transport never uses it -- install it '
. 'with `cpanm IO::Socket::SSL` (or `cpanm --with-recommends '
. 'API::Docker`)';
}
# The IO::Socket::SSL arguments for this client, as a plain hash, so the
# policy can be read off without opening a connection.
sub _ssl_options {
my ($self, $addr) = @_;
$self->_load_ssl;
# SNI, sent whether or not the certificate is checked: a terminator serving
# several names needs it to pick the right one, and that is true of an
# unverified connection too.
my %ssl = ( SSL_hostname => $addr );
if ($self->tls_insecure) {
# Everything below is off deliberately, and the attribute that got us here
# says so in its name. Encryption without verification stops a passive
# listener and nothing else: whoever answers the connection chooses the
# certificate, so anyone able to redirect it reads and rewrites the
# traffic -- credentials, image contents, container commands.
$ssl{SSL_verify_mode} = IO::Socket::SSL::SSL_VERIFY_NONE();
$ssl{SSL_verifycn_scheme} = undef;
}
else {
$ssl{SSL_verify_mode} = IO::Socket::SSL::SSL_VERIFY_PEER();
# The name is checked against the certificate as well as the chain: a
# valid certificate for some other host is not this host.
$ssl{SSL_verifycn_scheme} = 'http';
$ssl{SSL_verifycn_name} = $addr;
}
return (%ssl, $self->_ssl_certificates);
}
# cert.pem, key.pem and ca.pem in one directory -- the layout the docker CLI
# writes and the one cert_path has always pointed at, whether or not anything
# read it.
sub _ssl_certificates {
my ($self) = @_;
my $dir = $self->cert_path;
return () unless defined $dir && length $dir;
# cert_path defaults from DOCKER_CERT_PATH, so it can arrive from a machine's
# environment rather than from this caller -- but it is only looked at once
# TLS was asked for, and at that point a path naming nothing is a mistake
# worth stopping on rather than quietly connecting without the certificates
# the caller believes are in use.
my $path = path($dir);
croak __PACKAGE__ . ": cert_path $dir is not a directory. TLS expects the "
. 'layout the docker CLI writes -- ca.pem, cert.pem and key.pem in one '
. 'directory -- and this names nothing that could hold it'
unless $path->is_dir;
my %ssl;
# No ca.pem is not an error: verifying a daemon behind a terminator with a
# publicly trusted certificate needs no private trust anchor, and the
# default store is then the right one. See L</"TLS on a tcp:// connection">.
my $ca = $path->child('ca.pem');
$ssl{SSL_ca_file} = "$ca" if $ca->exists;
my $cert = $path->child('cert.pem');
my $key = $path->child('key.pem');
my @half = grep { !$_->[1]->exists }
( [ 'cert.pem', $cert ], [ 'key.pem', $key ] );
# One of the two is never a mode, only ever an accident: a key with no
# certificate proves nothing and a certificate with no key cannot be used.
croak __PACKAGE__ . ': cert_path ' . $dir . ' has ' . $half[0][0]
. ' missing while the other half of the client certificate is there. '
. 'Both cert.pem and key.pem are needed, or neither'
if @half == 1;
if (!@half) {
$ssl{SSL_cert_file} = "$cert";
$ssl{SSL_key_file} = "$key";
}
return %ssl;
}
sub _reconnect {
my ($self, $pending) = @_;
$self->_clear_socket;
# Cleared on the way out whichever way the build went, so a later _socket
# built by anything but a request -- a test subclass, a caller reaching for
# it directly -- never picks up the last request's bound.
$self->_pending_connect($pending);
my $sock;
my $ok = eval { $sock = $self->_socket; 1 };
my $err = $@;
$self->_pending_connect(undef);
die $err unless $ok;
return $sock;
}
# Whether the connect that has just failed failed because the bound fired.
# Asked with nothing in between, because $@ and $! are the whole of the
# evidence and both are global.
#
# $@ rather than errno: IO::Socket writes 'connect: timeout' there, and only
# there, when its own select() ran out -- measured, against a host that drops
# SYNs, where $! is ETIMEDOUT, which the kernel also produces on its own after
# two minutes with no Timeout set at all.
#
# EAGAIN is the second shape and belongs to unix:// alone. Measured against a
# listener whose backlog is full: with no Timeout the connect blocks
# indefinitely (still blocked after 8s), and with one it fails at once with
# EAGAIN, because IO::Socket does the timed connect non-blocking and an
# AF_UNIX connect has no in-progress state to wait on. So on that transport
# the option does not wait, it refuses -- but a connect that failed with
# EAGAIN is still one the bound ended, and reporting it as anything else would
# name a cause the caller cannot act on.
sub _connect_expired {
my ($self, $timeout) = @_;
return 0 unless $timeout;
return 1 if defined $@ && $@ =~ /connect: timeout\z/;
return 1 if $! == EAGAIN || $! == EWOULDBLOCK;
return 0;
}
sub _croak_connect_timeout {
my ($self, $pending, $where) = @_;
my $endpoint = $pending->{endpoint};
# See _croak_timeout for why the object goes into a variable first and why
# the location is captured by hand.
my $error = API::Docker::Error::Timeout->new(
message => 'Docker API connect timeout'
. (defined $endpoint && length $endpoint ? ' (' . $endpoint . ')' : '')
. ': ' . $where . ' did not accept within ' . $pending->{timeout} . 's',
location => shortmess(''),
endpoint => defined $endpoint ? $endpoint : '',
timeout => $pending->{timeout},
phase => 'connect',
);
croak $error;
}
# undef for "no timeout", which is both the default and the explicit 0, so a
# client carrying a default can be opted out of for one request. Anything that
# is not a non-negative number is a caller mistake and is refused rather than
# rounded to something: silently reading a typo as "off" would hand back the
# hang the caller was asking to be protected from.
sub _timeout_value {
my ($self, $name, $timeout) = @_;
return undef unless defined $timeout;
croak __PACKAGE__ . '->_request ' . $name . ' must be a non-negative number '
. 'of seconds (0 or undef for none), not "' . $timeout . '"'
unless !ref $timeout && looks_like_number($timeout) && $timeout >= 0;
return $timeout > 0 ? $timeout : undef;
}
sub _read_timeout_value {
my ($self, $timeout) = @_;
return $self->_timeout_value('read_timeout', $timeout);
}
sub _connect_timeout_value {
my ($self, $timeout) = @_;
return $self->_timeout_value('connect_timeout', $timeout);
}
# Why SO_RCVTIMEO and not select(): a bound that reads the socket cannot see
# what is already buffered above it, and would fire while the data it was
# waiting for was in hand. That was true of PerlIO's read-ahead when this was
# written (measured: after one readline of a socket holding
# "one\ntwo\nthree\n", two whole lines sit in the PerlIO buffer and select()
# says the handle is not ready), and it is true of _read_buffer now. A
# select-based bound would have to be asked only when that buffer is empty,
# which is one more invariant to keep for no gain: SO_RCVTIMEO bounds the one
# syscall in _pull for one setsockopt, and gets idle-since-the-last-byte
# semantics for free, which is the semantics these endpoints need (karr k52:
# the buffered frames arrive, and *then* the socket stalls -- a
# time-to-first-byte bound would never fire).
sub _apply_read_timeout {
my ($self, $sock, $timeout) = @_;
return unless $timeout;
my $packed;
if ($^O eq 'MSWin32' || $^O eq 'cygwin') {
# Winsock takes a DWORD of milliseconds here rather than a struct timeval,
# and reads a zero as "wait forever" -- so a sub-millisecond request is
# rounded up instead of becoming the hang it asked to avoid. Reasoned from
# the Winsock documentation and NOT measured: there is no Windows here.
# What makes that safe to ship is the croak below -- a shape the platform
# rejects is reported rather than ignored.
my $ms = int($timeout * 1000 + 0.5);
$ms = 1 if $ms < 1;
$packed = pack('L', $ms);
}
else {
# struct timeval: two native longs, seconds then microseconds. Measured on
# Linux x86_64 against unix://, plain tcp:// and TLS.
my $sec = int($timeout);
my $usec = int(($timeout - $sec) * 1_000_000 + 0.5);
if ($usec >= 1_000_000) { $sec++; $usec -= 1_000_000 }
$packed = pack('l!l!', $sec, $usec);
}
# Never a warning and never a silent pass. A caller that asked for a bound
# and did not get one is left waiting on exactly the hang the option exists
# to end, and would have no way to tell that from a daemon being slow.
setsockopt($sock, SOL_SOCKET, SO_RCVTIMEO, $packed)
or croak __PACKAGE__ . ': cannot set a read timeout of ' . $timeout
. 's on this socket: ' . $! . '. Refusing to continue without it -- a '
. 'bound that is not in force is worse than no bound at all, because '
. 'the caller is relying on it';
return;
}
# A read that did not deliver did not deliver for one of two reasons, and they
# are not the same thing: the stream ended, or the clock ran out. errno is the
# only thing that separates them -- measured, both eof() and $fh->error are
# true after a timeout just as they are at a clean end, and asking eof() costs
# a second full timeout. So $! is zeroed immediately before the read in _pull
# and captured immediately after it, with nothing in between: it is only
# meaningful after a failure, and any operation in between would overwrite it.
#
# Without this the readers would take a timeout for the end of the response and
# return a truncated body as a whole one. That is the reason karr k59 is not
# just the setsockopt: switching the option on alone would turn a hang into
# silent data loss, which is the worse of the two.
sub _timed_out {
my ($self, $ctx, $errno) = @_;
return 0 unless $ctx->{timeout};
return ($errno == EAGAIN || $errno == EWOULDBLOCK) ? 1 : 0;
}
sub _croak_timeout {
my ($self, $ctx, $partial) = @_;
$partial = '' unless defined $partial;
# Only ever set once a stream is past its status line, so an error body read
# whole on the way to a >= 400 croak is still reported in bytes.
my $summary = $ctx->{summary} ? $ctx->{summary}->() : undef;
my $after = $summary
? ' after ' . $summary->{delivered} . ' unit'
. ($summary->{delivered} == 1 ? '' : 's')
: length($partial)
? ' after ' . length($partial) . ' byte'
. (length($partial) == 1 ? '' : 's')
: ', nothing arrived at all';
# Carp hands a reference straight back rather than decorating it, so this
# croak is a die with an object -- hence the location captured by hand,
# which names the same frame a croak of a plain string would have named.
# The object goes into a variable first: `croak CLASS->new(...)` is indirect
# object syntax and parses as CLASS->croak(new(...)).
my $error = API::Docker::Error::Timeout->new(
message => 'Docker API read timeout (' . $ctx->{endpoint} . '): '
. $ctx->{timeout} . 's of silence' . $after,
location => shortmess(''),
endpoint => $ctx->{endpoint},
timeout => $ctx->{timeout},
partial => $partial,
summary => $summary,
);
croak $error;
}
# The other way a response ends before it is finished, and the one that needs
# no option to be armed: the daemon closed mid-sentence (karr k64).
#
# It is deliberately not folded into _croak_timeout. A timeout is the absence
# of an answer inside a bound the caller asked for, and it can fire on a
# response that would have completed; this is a statement about the response
# itself, made by comparing the body against what the response announced, and
# it fires whether or not anything was bounded. The two carry the same
# "here is what did arrive" contract and nothing else.
#
# $ctx->{partial} and $ctx->{summary} are read exactly as _croak_timeout reads
# them, so a buffered read reports bytes and a streamed one reports units,
# with no site having to know which it is.
sub _croak_truncated {
my ($self, $ctx, %what) = @_;
my $summary = $ctx->{summary} ? $ctx->{summary}->() : undef;
my $partial = $ctx->{partial} ? ${ $ctx->{partial} } : '';
my $arrived = $summary
? $summary->{delivered} . ' unit'
. ($summary->{delivered} == 1 ? '' : 's') . ' delivered'
: length($partial)
? length($partial) . ' byte'
. (length($partial) == 1 ? '' : 's') . ' arrived'
: 'nothing arrived at all';
# Empty when a reader is driven directly rather than through _request, which
# is how t/role_http.t drives them: an endpoint nobody named is left out of
# the message rather than interpolated as the empty string.
my $endpoint = defined $ctx->{endpoint} ? $ctx->{endpoint} : '';
# The two phases with an announced length say the same sentence about it, so
# they name the piece and let this write it; the two without pass the whole
# detail, there being no count to put in one.
my $detail = $what{detail};
unless (defined $detail) {
my $short = $what{expected} - $what{received};
$detail = $what{piece} . ' stopped ' . $short . ' byte'
. ($short == 1 ? '' : 's') . ' short of the ' . $what{expected}
. ' it announced';
}
# Carp hands a reference straight back rather than decorating it, so this
# croak is a die with an object -- hence the location captured by hand,
# which names the same frame a croak of a plain string would have named.
# The object goes into a variable first: `croak CLASS->new(...)` is indirect
# object syntax and parses as CLASS->croak(new(...)).
my $error = API::Docker::Error::Truncated->new(
message => 'Docker API response truncated'
. (length $endpoint ? ' (' . $endpoint . ')' : '') . ': '
. $detail . '; ' . $arrived,
location => shortmess(''),
endpoint => $endpoint,
phase => $what{phase},
expected => $what{expected},
received => $what{received},
partial => $partial,
summary => $summary,
);
croak $error;
}
# ---------------------------------------------------------------------------
# Reading, in one buffer regime
#
# Every byte of a response is taken off the handle by _pull and by nothing
# else, and every reader below is served out of the buffer _pull fills. That
# is not an optimisation, it is the only shape that works (karr k60).
#
# What forced it: perl's read() is fread-shaped. It loops until it has the
# LENGTH it was asked for or the stream ends -- it does not return what has
# arrived. Measured on an AF_UNIX socketpair whose peer writes 6 bytes, waits
# half a second, writes 6 more and closes: read($sock, $buf, 65536) came back
# with 12 after 0.90s, having waited for the close, while sysread came back
# with 6 in 0.00s. On the endpoints with neither a Content-Length nor chunked
# encoding -- attach, logs(follow), exec/start, all
# application/vnd.docker.raw-stream -- the reader asks for $READ_SIZE, so
# read() delivered nothing to an on_frame/on_chunk callback until 64K had
# piled up or the daemon hung up. On a stream that never ends it would deliver
# nothing at all. The POD promised those callbacks the bytes as they arrive,
# and that promise was not kept.
#
# Why it could not be fixed at the one site that had the bug: _read_head read
# the status line and the headers with <$sock>, and PerlIO reads ahead. The
# bytes past the header block were sitting in a buffer this code cannot reach
# -- there is no supported way to take them back out; ungetc is layer-
# dependent, seek does not work on a socket, and select/MSG_PEEK see the
# kernel's buffer rather than PerlIO's. So switching only the body reads to
# sysread would have silently dropped the start of every body. Either all read
# sites move together or none do.
#
# The buffer lives on the handle rather than on the client or in the context:
# it is the unconsumed bytes of *that* handle, its lifetime is the handle's,
# and a client that opens a socket per request therefore has nothing to reset.
# ${*$sock}{...} is the IO::Socket idiom for exactly this and was measured to
# work on a real socket, a lexical filehandle, a bareword glob and a tied
# handle alike.
my $RBUF = __PACKAGE__ . '/rbuf';
sub _read_buffer {
my ($self, $sock) = @_;
${*$sock}{$RBUF} = '' unless defined ${*$sock}{$RBUF};
return \${*$sock}{$RBUF};
}
# The one physical read. It answers with what happened rather than with a
# count, because a count makes every reader re-derive the same distinction and
# an undef quietly becoming an end of stream at any one of them is the silent
# truncation this transport must not have:
#
# 'data' something was appended to the buffer -- however little
# 'eof' the stream ended
# 'timeout' the read_timeout expired with nothing to show for it
#
# What TLS does here, since it is not obvious from the call. IO::Socket::SSL
# ties the glob, so the builtin sysread reaches the same place -- SSL_HANDLE's
# READ delegates to the object's own sysread -- and the method form is written
# out only so that the dispatch is visible rather than accidental. What does
# matter is sysread rather than read: IO::Socket::SSL's sysread is a single
# Net::SSLeay::read, one record, while its read is ssl_read_all on a blocking
# socket, which is the same fill semantics this is here to get away from.
#
# A short positive read is never an end of stream and never an expiry. Over
# TLS it is the normal case, one plaintext record at a time; over a plain
# socket it is whatever the kernel had. Both are data.
#
# SSL_WANT_READ and SSL_WANT_WRITE are deliberately not retried. On a blocking
# socket they arrive as EWOULDBLOCK (IO::Socket::SSL's _skip_rw_error does
# `$! ||= EWOULDBLOCK`) and mean the underlying receive would have blocked --
# which, with SO_RCVTIMEO in force, is the bound firing and nothing else.
# Retrying would be a busy loop on WANT_READ and could not make progress on
# WANT_WRITE in any case, so they are reported as the timeout they are.
lib/API/Docker/Role/HTTP.pm view on Meta::CPAN
# indirect object syntax and parses as CLASS->croak(new(...)).
my $error = API::Docker::Error::Stream->new(
message => 'Docker API stream error (' . $endpoint . '): ' . $reason,
events => $events,
location => shortmess(''),
);
croak $error;
}
return;
}
sub _assert_header_name {
my ($self, $name) = @_;
return if defined $name && $name =~ $HEADER_NAME;
my $display = defined $name ? $name : '';
$display =~ s/([^\x20-\x7E])/sprintf('\\x%02X', ord $1)/ge;
croak __PACKAGE__ . '->_request invalid header name "' . $display . '": a '
. 'header name must be an RFC 9110 token (letters, digits and '
. '!#$%&\'*+-.^_`|~). A name is rejected rather than sanitised: unlike a '
. 'value, there is no benign way for one to carry CR, LF, a space or a '
. 'colon, and rewriting it would send a header the caller never wrote';
}
sub _assert_request_path {
my ($self, $path) = @_;
return if defined $path && $path =~ $REQUEST_PATH;
my $display = defined $path ? $path : '';
$display =~ s/([^\x20-\x7E])/sprintf('\\x%02X', ord $1)/ge;
croak __PACKAGE__ . '->_request invalid request path "' . $display . '": a '
. 'path may hold only request-target characters (letters, digits, -._~ '
. 'and :/@!$&\'()*+,;=%). It is spliced straight into the request line, so '
. 'a space, CR, LF, ? or # in a container name or image reference would '
. 'rewrite the request rather than name a resource. A path is rejected '
. 'rather than sanitised: percent-encoding it here cannot tell a path '
. 'separator from data -- pass query parameters as `params`, not in the '
. 'path';
}
sub _read_response {
my ($self, $sock, $method, $ctx) = @_;
# A context is what _request builds to say how long a silence may last and
# what the exception has to name. It defaults to an empty one -- no timeout,
# every read exactly as it was -- so the readers stay drivable directly, as
# t/role_http.t drives them.
$ctx ||= {};
my $head = $self->_read_head($sock, $ctx);
return [ @$head, $self->_read_body($sock, $head->[2], $method, $ctx) ];
}
sub _read_head {
my ($self, $sock, $ctx) = @_;
$ctx ||= {};
# Looped so a 1xx informational response is read whole and passed by: it is a
# complete head -- a status line and an optional field section closed by the
# blank line -- with no body of its own, sent before the real response
# (RFC 9110 section 15.2). Without this the reader took the 1xx status as the
# response and then read the real response as its body. A 100 Continue is the
# one an HTTP/1.1 client is most likely to be sent; 102 and 103 have the same
# framing.
while (1) {
my $status_line = $self->_read_line($sock, $ctx);
# A daemon that closed without answering at all, which is the one shape here
# that was never silent and is left saying exactly what it always said.
croak "No response from Docker daemon" unless defined $status_line;
$self->_assert_status_line($ctx, $status_line);
$status_line =~ s/\r?\n$//;
my ($proto, $status_code, $status_text) = split /\s+/, $status_line, 3;
# while(1)-and-assert rather than `while (my $line = ...)`, which is the
# same shape _read_chunked uses and for the same reason: the loop used to
# end on anything false, so an end of stream inside the header block left it
# exactly as the blank line would have. The assert is now the only way out
# that is not the blank line.
my %headers;
while (1) {
my $line = $self->_read_line($sock, $ctx);
$self->_assert_header_line($ctx, $line);
$line =~ s/\r?\n$//;
last if $line eq '';
if ($line =~ /^([^:]+):\s*(.*)$/) {
$headers{lc $1} = $2;
}
}
# The status code is three digits by now (_assert_status_line), so a 1xx is
# exactly 100..199. Its headers are dropped with it and the next head read.
next if $status_code >= 100 && $status_code < 200;
return [$status_code, $status_text, \%headers];
}
}
# The two ways the head ends early, and neither of them has a byte count to
# compare either (karr k73).
#
# karr k64 left the head out on the grounds that nothing in a status line or a
# header block announces its own length, so there was no announcement to hold
# a short one against. True, and beside the point: an announcement is not what
# is being checked here, any more than it is in _assert_chunk_header one level
# down. HTTP/1.1 frames the head by terminating every line, and the field
# section by an empty line that is mandatory even when there are no fields at
# all (RFC 9112 section 2.1), so "the stream ended where the terminator
# belongs" is a complete test on its own. It is the same question that reader
# already asks about a chunk header, asked of the head.
#
# What it was worth. A head cut short is not just a bogus status: the response
# is then read with whichever headers happened to arrive, and a cut landing
# before Content-Length or Transfer-Encoding leaves neither -- which is
# exactly the close-delimited branch of _read_body, where an EOF is the
# legitimate end and nothing looks wrong. Measured over a socketpair whose
# peer writes "HTTP/1.1 200 OK\r\nContent-Type: application/json\r\nX-Half"
# and closes: status 200, one header, an empty body, no complaint. The cuts
# that did get caught were caught by accident one level lower, because the
# half-arrived header happened to be one of those two.
#
# Nothing legitimate ends a head without the blank line, which was measured
# rather than taken from the RFC, on both engines and including the two heads
# an engine writes by hand instead of through its HTTP server: attach and
# /exec/{id}/start answer with "HTTP/1.1 200 OK", one Content-Type line and
# the blank line, on Docker 29.7.2 and on rootless Podman 5.8.4 alike. So do
# 204, 304, HEAD, chunked and every other shape either of them produces.
sub _assert_status_line {
my ($self, $ctx, $line) = @_;
# Only the unterminated half: a status line that never started at all is the
# croak above, which says something better than this could.
$self->_croak_truncated($ctx, phase => 'status-line',
detail => 'the stream ended inside the status line, after '
. length($line) . ' byte' . (length($line) == 1 ? '' : 's') . ' of one')
unless $line =~ /\n\z/;
# Terminated, and now: is it an HTTP status line at all? RFC 9112 section 4:
# HTTP-version SP status-code SP [ reason-phrase ], with status-code exactly
# three digits. A line that arrived whole but is not this shape -- a proxy's
# plain-text banner, an ICY greeting, an HTML error page -- would otherwise
# be split on whitespace in _read_head and its second word run through the
# >= 400 comparison as the status. It is refused here rather than silently
# misread, the same way a non-hexadecimal chunk size is one level down.
my $stripped = $line =~ s/\r?\n\z//r;
$self->_croak_truncated($ctx, phase => 'status-line',
detail => "the status line '" . $stripped
. "' is not a well-formed HTTP status line")
unless $stripped =~ m{\AHTTP/[0-9]+\.[0-9]+ [0-9]{3}(?: .*)?\z};
return;
}
# Both halves here, because the header block has no equivalent of that croak:
# undef is a block that was never closed -- with no headers at all, or after
# some -- and an unterminated line is one cut in the middle of a field.
sub _assert_header_line {
my ($self, $ctx, $line) = @_;
$self->_croak_truncated($ctx, phase => 'header-block',
detail => 'the stream ended where a header line belongs, with no blank '
. 'line to close the header block')
unless defined $line;
$self->_croak_truncated($ctx, phase => 'header-block',
detail => 'the stream ended inside a header line, after '
. length($line) . ' byte' . (length($line) == 1 ? '' : 's') . ' of one')
unless $line =~ /\n\z/;
return;
}
sub _read_body {
my ($self, $sock, $headers, $method, $ctx) = @_;
$ctx ||= {};
# A HEAD response repeats the header fields the equivalent GET would send --
# Content-Length and Transfer-Encoding included -- and then sends no body at
# all. Every branch below would wait for bytes that never arrive: until the
# daemon closes the connection at best, and forever if it does not. So the
# body is not read for HEAD, whatever the headers promise.
return '' if defined $method && uc($method) eq 'HEAD';
if ($headers->{'transfer-encoding'}
&& lc($headers->{'transfer-encoding'}) eq 'chunked') {
return $self->_read_chunked($sock, $ctx);
}
if (defined $headers->{'content-length'}) {
my $len = $self->_assert_content_length($ctx, $headers->{'content-length'});
return '' unless $len > 0;
my $body = '';
# What a timeout hands over instead of dropping: see
# API::Docker::Error::Timeout/partial. localised so the context goes back
# to carrying nothing once this body is done with.
local $ctx->{partial} = \$body;
# An announced length is a promise, and a stream that ends before it is
# kept is truncation rather than the end of the body; see _read_exact.
$self->_read_exact($sock, $len, \$body, $ctx, 'content-length',
'the body');
return $body;
}
lib/API/Docker/Role/HTTP.pm view on Meta::CPAN
stopped => sub { $stopped },
summary => sub { { delivered => $delivered, stopped => $stopped ? 1 : 0 } },
};
}
sub _read_chunked {
my ($self, $sock, $ctx) = @_;
$ctx ||= {};
my $body = '';
# See _read_body: the accumulator a timeout hands over. The chunk data is
# appended to it directly rather than to a per-chunk temporary, so a stall
# in the middle of a chunk still carries the bytes of that chunk out with
# the exception. The two are otherwise the same -- the temporary was only
# ever concatenated onto $body straight afterwards.
local $ctx->{partial} = \$body;
while (1) {
my $chunk_header = $self->_read_line($sock, $ctx);
my $chunk_size = $self->_assert_chunk_header($ctx, $chunk_header);
last if $chunk_size == 0;
$self->_read_exact($sock, $chunk_size, \$body, $ctx, 'chunk-data',
'a chunk');
# Read trailing \r\n after chunk data
$self->_assert_chunk_terminator($ctx, $self->_read_line($sock, $ctx));
}
return $body;
}
# The two places a chunked body ends without saying so, and neither of them
# has a byte count to compare (karr k64).
#
# A chunked body is terminated by a chunk of size zero and by nothing else, so
# an end of stream where the next chunk header belongs is the daemon hanging
# up mid-body -- not the end of it. The reader used to `last unless defined`
# there and hand back the chunks that had completed as the whole response.
#
# _read_line answers an end of stream with what is left in the buffer and no
# terminator, exactly as the readline it replaces did (see there), so an
# unterminated line is the other half of the same question: a header cut in
# half is `hex('1')` and reads as a perfectly good chunk of one byte.
sub _assert_chunk_header {
my ($self, $ctx, $line) = @_;
$self->_croak_truncated($ctx, phase => 'chunk-header',
detail => 'the stream ended where a chunk header belongs, with no '
. 'terminating zero chunk')
unless defined $line;
$self->_croak_truncated($ctx, phase => 'chunk-header',
detail => 'the stream ended inside a chunk header, after '
. length($line) . ' byte' . (length($line) == 1 ? '' : 's') . ' of one')
unless $line =~ /\n\z/;
# The line arrived whole and terminated, and its size is not a hexadecimal
# number. Left to hex() that warns once and reads as 0 -- the terminating
# zero chunk -- so a 200 whose framing is corrupt used to come back as an
# empty body, the same body-shaped lie a truncation is. A chunk size is hex
# digits, optionally followed by a ';' extension (RFC 9112 section 7.1.1),
# which is read past and discarded; anything else is refused here rather than
# silently misread by the caller. The returned size is parsed from the same
# match, so hex() is called on nothing but hex digits and never has cause to
# warn on a legal extension either.
my ($size) = $line =~ /^([0-9A-Fa-f]+)(?:;.*)?\r?\n\z/;
$self->_croak_truncated($ctx, phase => 'chunk-header',
detail => "the chunk size line '" . ($line =~ s/\r?\n\z//r)
. "' is not a hexadecimal number")
unless defined $size;
return hex($size);
}
# Completeness only, never content: a terminator that arrived but is not CRLF
# is a daemon speaking chunked wrongly, which is a different complaint and one
# this reader has never made.
sub _assert_chunk_terminator {
my ($self, $ctx, $line) = @_;
$self->_croak_truncated($ctx, phase => 'chunk-terminator',
detail => 'the stream ended before the CRLF that terminates a chunk')
unless defined $line && $line =~ /\n\z/;
return;
}
# The declared body length, validated to be the digits RFC 9110 section 8.6
# requires before it is compared against or counted down (karr k113). The
# sibling of _assert_chunk_header's hex check: a Content-Length that is not a
# number -- 'abc', an empty value, a duplicated '11, 11', a leading space --
# left as it stood is run through `$len > 0`, which warns once ("isn't
# numeric") and reads as 0, so the body is taken to be empty and a response
# that had one comes back blank. Refused here rather than silently misread, so
# hex()'s sibling warning is never reached either.
sub _assert_content_length {
my ($self, $ctx, $value) = @_;
return $value if $value =~ /\A[0-9]+\z/;
$self->_croak_truncated($ctx, phase => 'content-length',
detail => "the Content-Length header '" . $value . "' is not a number");
}
sub _uri_encode {
my ($str) = @_;
# Escape a character string by its UTF-8 bytes ('ü' -> %C3%BC, not %FC), and
# a byte string as it stands. ord() on a character is not its wire byte: a
# name or tag typed under `use utf8`, or read through a :utf8 layer, arrives
# as characters and used to escape to a lone high byte or a bare codepoint
# (%FC, %4E2D) that is not UTF-8 at all. But the encoding cannot be
# unconditional: encode_json has already handed a HASH param (filters among
# them) its UTF-8 octets, and re-encoding those would double them
# (%C3%BC -> %C3%83%C2%BC). The utf8 flag is exactly that distinction -- on
# for a decoded string, off for encode_json's output -- so a copy is encoded
# only when it carries one, leaving the caller's own value untouched either
# way.
my $bytes = $str;
utf8::encode($bytes) if utf8::is_utf8($bytes);
$bytes =~ s/([^A-Za-z0-9\-_.~:\/])/sprintf("%%%02X", ord($1))/ge;
return $bytes;
}
sub get {
my ($self, $path, %opts) = @_;
return $self->_request('GET', $path, %opts);
}
sub post {
my ($self, $path, $body, %opts) = @_;
$opts{body} = $body if defined $body;
return $self->_request('POST', $path, %opts);
}
sub put {
my ($self, $path, $body, %opts) = @_;
$opts{body} = $body if defined $body;
return $self->_request('PUT', $path, %opts);
}
sub delete_request {
my ($self, $path, %opts) = @_;
return $self->_request('DELETE', $path, %opts);
}
lib/API/Docker/Role/HTTP.pm view on Meta::CPAN
return [] unless defined $body && length $body;
my $frames = $tty ? undef : $self->_demux_frames($body);
return $frames if $frames;
return [ { stream => 'raw', data => $body } ];
}
sub _demux_frames {
my ($self, $body) = @_;
my $len = length $body;
my $pos = 0;
my @frames;
while ($pos < $len) {
return undef if $len - $pos < 8;
my ($type, $pad1, $pad2, $pad3, $size) = unpack 'C4 N', substr($body, $pos, 8);
return undef if $type > $#STREAM_TYPE;
return undef if $pad1 || $pad2 || $pad3;
return undef if $len - $pos - 8 < $size;
push @frames, {
stream => $STREAM_TYPE[$type],
data => substr($body, $pos + 8, $size),
};
$pos += 8 + $size;
}
return undef unless @frames;
return \@frames;
}
1;
__END__
=pod
=encoding UTF-8
=head1 NAME
API::Docker::Role::HTTP - HTTP transport role for Docker Engine API
=head1 VERSION
version 0.004
=head1 SYNOPSIS
package MyDockerClient;
use Moo;
has host => (is => 'ro', required => 1);
has api_version => (is => 'ro');
has tls => (is => 'ro', default => 0);
has cert_path => (is => 'ro');
has tls_insecure => (is => 'ro', default => 0);
with 'API::Docker::Role::HTTP';
# Now use get, post, put, delete_request, head methods
my $data = $self->get('/containers/json');
=head1 DESCRIPTION
This role provides HTTP transport for the Docker Engine API. It implements
HTTP/1.1 communication over Unix sockets and TCP sockets without depending on
heavy HTTP client libraries like LWP.
Features:
=over
=item * Unix socket transport (C<unix://...>)
=item * TCP socket transport (C<tcp://host:port>), in the clear or over TLS
with client certificates (L</"TLS on a tcp:// connection">)
=item * HTTP/1.1 chunked transfer encoding
=item * Automatic JSON encoding/decoding
=item * Newline-delimited JSON event streams (C<< ndjson => 1 >>), including
the failures the engine reports inside an HTTP 200 body
=item * Demultiplexing of the Docker stream format (L</stream_frames>)
=item * Incremental delivery of a response through a per-request callback, so
the endpoints that never close are usable at all (L</"Streaming a response as
it arrives">)
=item * Request/response logging via L<Log::Any>
=item * Automatic connection management
=back
Consuming classes must provide C<host>, C<api_version>, C<tls>, C<cert_path>
and C<tls_insecure> attributes. The last three are read only by the C<tcp://>
branch of the socket builder, and only when TLS is asked for, but the contract
is stated once rather than probed for at connect time.
A C<unix://> connection is a local socket with no wire to protect and is never
encrypted; it ignores all three attributes, and L<API::Docker> refuses the
combination at construction rather than letting a request for an encrypted
transport be answered with an unencrypted one. A C<tcp://> connection is
B<plaintext unless C<< tls => 1 >>>, which is the whole of the difference --
see L</"TLS on a tcp:// connection">.
=head2 TLS on a tcp:// connection
C<< tls => 1 >> replaces the L<IO::Socket::INET> connection with an
L<IO::Socket::SSL> one and changes nothing else: the same request writer, the
same reader, the same everything above the socket.
my $docker = API::Docker->new(
host => 'tcp://dockerhost:2376',
tls => 1,
cert_path => '/home/me/.docker',
);
=head3 What the certificates are, and where
C<cert_path> names a directory in the layout the C<docker> CLI writes, and
each of the three files is used if it is there:
=over
=item * F<ca.pem> - the trust anchor the daemon's certificate is checked
against
=item * F<cert.pem> and F<key.pem> - this client's certificate and private
key, sent when the daemon asks the client to identify itself
=back
The two halves of the client certificate go together: one of them present
without the other is a croak, because a key with no certificate proves nothing
and a certificate with no key cannot be used. A directory holding only
F<ca.pem> is fine -- that is a daemon this client verifies but does not
authenticate to. A C<cert_path> that names nothing is a croak: it is read only
once TLS was asked for, and at that point a path pointing nowhere means the
caller believes certificates are in use that are not.
C<cert_path> defaults from C<DOCKER_CERT_PATH>, so on a machine that also runs
the C<docker> CLI it arrives set. Without C<< tls => 1 >> nothing reads it, so
that costs nothing; with it, pass C<< cert_path => undef >> to use the system
trust store instead of the CLI's private one.
=head3 TLS with no certificates at all
It means B<encrypt and verify against the system trust store>, not an error.
C<tls> asks for a connection that is encrypted and whose far end is
authenticated. It does not ask to authenticate this client, which is what the
files on disk are for, and treating the absence of a client certificate as a
missing precondition would conflate the two. The deployment with no
certificate files is real, and is the one this role's documentation used to
recommend before there was any TLS here: a terminator -- nginx, stunnel,
Traefik -- in front of the daemon, holding a publicly trusted certificate.
There is nothing for a C<cert_path> to point at in that setup.
It is also the safe reading rather than the lax one: verification stays on
either way, so the mode reached by configuring nothing is the verifying mode.
A stock C<dockerd --tlsverify> uses a private CA that the system store does
not have, and such a connection fails with a verification error naming exactly
that -- which is the intended outcome, not a silent downgrade. Point
C<cert_path> at the directory holding its F<ca.pem> and it verifies.
=head3 Turning verification off
C<< tls_insecure => 1 >>, and the name is the whole of the warning. It sets
C<SSL_VERIFY_NONE> and switches the hostname check off, which leaves a
connection that is encrypted against a passive listener and against nothing
else: whoever answers chooses the certificate, so anyone able to redirect the
connection reads and rewrites everything on it -- registry credentials,
image contents, the commands containers are started with.
It exists for a self-signed daemon certificate whose CA is genuinely not to
hand. The better answer to that is nearly always F<ca.pem>: a self-signed
certificate is its own CA and can be used as the anchor directly.
=head3 The dependency
L<IO::Socket::SSL> is a B<recommended>, not a required, dependency, and it is
loaded at the moment the first TLS connection is opened. It brings in
L<Net::SSLeay>, which is XS compiled against libssl, and the C<unix://>
transport -- local Docker, rootless Podman, the default -- never needs any of
it; requiring it would make this client unbuildable on a machine with no
OpenSSL headers for the sake of a transport it is not using. Without it,
C<< tls => 1 >> croaks naming the module and how to install it, at the same
point every other connection failure is reported.
=head2 read_timeout
Seconds of silence after which a request gives up and croaks with an
L<API::Docker::Error::Timeout>. C<undef> -- the default, and what every
existing caller gets -- means no timeout at all and is the behaviour this
distribution has always had. C<0> means the same and is the way to say it
explicitly, so a client carrying a default can be opted out of per request.
my $docker = API::Docker->new(read_timeout => 30);
$docker->system->using(read_timeout => 0)->events; # this one may wait
Per request it is an option of L</get>, L</post>, L</put>, L</delete_request>
and L</head>. A resource class carries it through
L<API::Docker::Role::Using/using>, which clones the class rather than taking
it per method -- up for a slow endpoint, down for a stream that should not
stall, off with C<0>.
See L</"Bounding a request that never ends"> for what it does and does not
cover, and L<API::Docker/"What a timeout covers"> for the same question
asked of both bounds at once.
=head2 connect_timeout
Seconds after which opening the connection gives up and croaks with an
L<API::Docker::Error::Timeout> whose C<< ->phase >> is C<'connect'>. C<undef>
-- the default, and what every existing caller gets -- means no bound and is
the behaviour this distribution has always had; C<0> means the same and is the
way to say it explicitly.
my $docker = API::Docker->new(connect_timeout => 5);
$docker->system->using(connect_timeout => 0)->version; # may wait
Separate from L</read_timeout> rather than folded into it, because the two
bound different things and want different numbers: a connect is either
immediate or broken, while a read is waiting on work the daemon has to do.
Per request it is an option of L</get>, L</post>, L</put>, L</delete_request>
and L</head>. A resource class carries it through
L<API::Docker::Role::Using/using>. See L</"Bounding the connection itself">
lib/API/Docker/Role/HTTP.pm view on Meta::CPAN
Options:
=over
=item * C<params> - HashRef of query parameters; a HashRef value is JSON-encoded
=item * C<headers> - HashRef of extra HTTP headers, e.g.
C<< { 'X-Registry-Auth' => $b64 } >>
=item * C<ndjson> - Parse the body as newline-delimited JSON and always
return an ArrayRef of events, even for a stream carrying a single object.
Named for the format rather than C<stream>, which is already a query
parameter of C</events> and C</containers/{id}/stats>. An C<errorDetail>
event in such a stream croaks; see L</"Failure inside a 200 response">
=item * C<croak_on_error> - Default true, and only consulted with
C<< ndjson => 1 >>. Set it false for a stream whose objects are engine data
rather than the outcome of one operation -- C</events> is the only such
endpoint here
=item * C<raw> - Never decode the body; return the response bytes verbatim
=item * C<response> - HashRef the status line and the response headers are
written into; see L</"Reading the status line and the response headers">
=item * C<on_event>, C<on_frame>, C<on_chunk> - CodeRef called with each unit
of the response as it arrives, instead of the body being buffered and
returned. At most one of the three; see L</"Streaming a response as it
arrives">
=item * C<read_timeout> - Seconds of silence after which this request gives up
and croaks with an L<API::Docker::Error::Timeout>. Overrides the
L</read_timeout> attribute; C<0> means no timeout. See L</"Bounding a request
that never ends">
=item * C<connect_timeout> - Seconds after which opening the connection gives
up and croaks with an L<API::Docker::Error::Timeout> whose C<< ->phase >> is
C<'connect'>. Overrides the L</connect_timeout> attribute; C<0> means no
bound. See L</"Bounding the connection itself">
=item * C<headers> names are validated, not sanitised; see
L</"Header names are rejected, header values are stripped">
=back
=head2 Bounding a request that never ends
Nothing above stops a request waiting forever. C<Connection: close> asks the
daemon to hang up when it is done, and the readers wait for that -- so a
daemon that has nothing more to send and does not hang up leaves the client
blocked with no way out. That is not hypothetical: attaching to a container
that has B<already exited> answers, delivers the buffered frames and then
holds the connection open indefinitely on rootless Podman (karr k52), and
C</containers/{id}/stats> opened on a running container does not end when that
container exits on Docker -- it degrades into zero-filled readings and keeps
going (karr k59).
L</read_timeout> bounds that:
# Give up after two seconds of silence rather than waiting forever.
my $frames = $docker->containers->using(read_timeout => 2)->attach($id);
=head3 It is an idle timeout, not a deadline
The clock measures the time since the last byte arrived, not the time since
the request started. A stream that keeps producing runs as long as it likes;
one that stops producing is cut off. That distinction is the whole point --
both hangs above deliver data first and stall afterwards, so a bound on the
total time would have to be set longer than any legitimate stream, and a bound
on the time to the first byte would never fire at all.
=head3 There is no default, and no per-endpoint default either
Off unless asked for, everywhere. Whether a silence is a stall or normal is a
property of the workload rather than of the endpoint: C</build> with a large
context is legitimately quiet for as long as C</events> is, and a built-in
default on C<attach> would kill a perfectly healthy session at an idle shell
prompt. So no existing call changes behaviour, and picking the number is the
caller's -- who is the only one who knows what the request is for.
For the two endpoints above, if you want a figure to start from: a couple of
seconds is right for C<attach> or C<logs> used to collect what is already
there, and something above the daemon's own emit interval -- Docker sends a
stats reading about once a second -- for C<stats>.
=head3 What happens when it expires
The request croaks, on every path, with an L<API::Docker::Error::Timeout>. It
never returns a truncated response: a short body satisfies every return shape
this role promises and would be indistinguishable from a complete one. The
exception carries what did arrive -- C<< ->partial >> for a buffered request,
C<< ->summary >> for a streamed one -- so collecting what there is and then
stopping is an C<eval>:
my $out = '';
eval {
$docker->containers->using(read_timeout => 2)->attach($id,
on_frame => sub { $out .= $_[0]{data} });
};
die $@ if $@ && !(ref $@
&& $@->isa('API::Docker::Error::Timeout'));
That class's own documentation has the reasoning for why this is fatal even
where the caller already holds every unit.
=head3 What it does not cover
Only reading. Connecting is bounded separately by L</connect_timeout>, and
writing the request is not bounded at all -- which matters only for a large
C</build> context sent to a daemon that has stopped reading.
It is implemented with C<SO_RCVTIMEO> on the socket, which was measured to
behave the same over C<unix://>, plain C<tcp://> and TLS: the timeout fires,
the handle is not left unusable, and reading afterwards works. The C<struct
timeval> it is set with was measured on Linux; on Windows the millisecond
C<DWORD> Winsock documents is sent instead, which is reasoned rather than
measured. A platform that rejects either croaks rather than continuing without
the bound.
Over TLS it is not quite an idle timer on the plaintext. C<SO_RCVTIMEO> bounds
each blocking receive on the underlying socket, and one plaintext read can
consume several of those while a TLS record arrives in pieces -- so a record
dribbling in slowly enough resets the clock without a byte reaching the
caller. It still bounds the hang, which is what it is for.
=head2 Bounding the connection itself
L</connect_timeout> is the other half, and it is off by default for the same
reason: nothing here changes behaviour unless it is asked for.
my $docker = API::Docker->new(connect_timeout => 5, read_timeout => 30);
What it does is not the same on all three transports, and the difference was
measured rather than assumed:
=over
=item * C<tcp://> -- a real bound. Against a host that drops SYNs, an unbounded
connect waits for the kernel's own timeout, which on Linux is over two
minutes; C<< connect_timeout => 2 >> gave up after 2.00s. This is the case the
option exists for.
=item * C<unix://> -- a bound, but it does not wait. A connect to a Unix socket
whose listen backlog is full blocks: measured against a listener with
C<< Listen => 1 >> and nobody accepting, still blocked after 8 seconds. With a
C<connect_timeout> set it fails at once instead, with C<EAGAIN> -- because
C<IO::Socket> performs a timed connect non-blocking, and an C<AF_UNIX> connect
has no in-progress state to wait on. So the hang is gone, at the price of not
tolerating even a momentary backlog. A socket path that does not exist is
C<ENOENT> either way and is not affected.
=item * TLS -- bounds the TCP connect only. The handshake that follows it runs
on the connected socket, before L</read_timeout>'s C<SO_RCVTIMEO> is applied,
and is not covered by either.
=back
An expiry croaks with an L<API::Docker::Error::Timeout> carrying
C<< ->phase >> C<'connect'>, C<< ->timeout >> the value that expired and an
empty C<< ->partial >> -- there is no response to have part of. Every other
connect failure croaks with the plain string it always did: a refused
connection, a missing socket path and a rejected certificate are diagnoses,
not timeouts, and rewriting them as one would name a cause the caller cannot
act on.
=head2 Streaming a response as it arrives
Without one of these options a request is read whole, then parsed. That is
right for a request/response endpoint and wrong for every endpoint whose point
is that it keeps going: C<< logs(follow => 1) >>, C</events> with no C<until>
and C</containers/{id}/stats> with no C<< stream => 0 >> never return, because
the daemon never closes and there is nothing else to wait for.
A callback is half the answer -- it decides what to do with each unit, and it
can stop. L</"Bounding a request that never ends"> is the other half, for the
stream that stops arriving without ever ending.
Pass a callback and the body is handed over piece by piece instead:
my $summary = $client->get('/events',
croak_on_error => 0,
on_event => sub {
my ($event, $stop) = @_;
print $event->{status}, "\n";
$stop->() if $event->{status} eq 'destroy';
},
);
$summary; # { delivered => 7, stopped => 1 }
=head3 One unit per call, and three units to choose from
The engine's streaming endpoints do not share a natural unit, so there is an
option per unit and a request picks one:
=over
=item * C<on_event> - one decoded HashRef per newline-delimited JSON object.
For C</events> and the C</build>, C</images/create>, C</images/*/push>
progress streams
=item * C<on_frame> - one C<< { stream => ..., data => ... } >> HashRef per
demultiplexed frame of the Docker stream format. For
C<< /containers/{id}/logs >> and C<< /exec/{id}/start >>; normally reached
through L</stream_frames> rather than directly
( run in 3.052 seconds using v1.01-cache-2.11-cpan-d01c6094234 )