API-Docker
view release on metacpan or search on metacpan
lib/API/Docker/Error/HTTP.pm view on Meta::CPAN
documents.
=head2 It is still the string it replaces
Everything this class replaces was a plain C<croak> of a string, and callers
rely on that. It overloads stringification (with C<< fallback => 1 >>, so
comparison, concatenation, C<sprintf> and matching all work through it) and
produces byte for byte what C<croak> died with before: the same
C<Docker API error (STATUS): REASON> text, followed by Carp's own
C< at FILE line N.> location suffix, naming the same frame. Code written
against the old behaviour keeps working unchanged:
eval { $docker->containers->inspect($id) };
if ($@) {
(my $reason = $@) =~ s/\s+at\s+\S+\s+line\s+\d+\.?//g; # still works
die "no good: $@"; # still works
warn $@ if $@ =~ /404/; # still works
}
Note that a substitution B<on> C<$@> replaces the object in that scalar with a
plain string, as it would with any overloaded object, so take a copy first if
L</status> is still wanted afterwards.
The boolean overload is explicit rather than derived from the string, so an
engine message of C<0> cannot make a live exception test false.
=head2 What it does not replace
Catching this class is B<not> a reliable way to catch a failed operation, and
the POD of the streaming methods still says to inspect C<$@> as a string.
Two exception classes reach a caller and which one it is depends on the
engine: a failure the daemon decides before it commits to a status arrives
here, while one it decides after arrives as an L<API::Docker::Error::Stream>
inside a stream that was already answered with HTTP 200. C<< ->status >> is
the extra for a caller that has already established it is holding one of
these, not the new recommended way to detect failure.
The C<response> out-parameter of L<API::Docker::Role::HTTP/get> is untouched
by this class and is not superseded by it: it is the only way to the status of
a request that did B<not> fail -- a C<304 Not Modified> from starting an
already-running container, or the C<X-Docker-Container-Path-Stat> header a
successful C<HEAD> carries its whole payload in.
=head2 message
The reason on its own, without the location suffix: the same
C<Docker API error (STATUS): REASON> text the transport croaked before this
class existed, where C<REASON> is the engine's C<message> field, its
C<errorDetail.message>, its flat C<error> key or the raw body, in that order
of preference.
=head2 location
Carp's location suffix (C< at FILE line N.\n>), captured at the point the
error was raised so it names the same frame a plain C<croak> would have named.
Kept apart from L</message> so a caller can have the reason without it.
=head2 status
The HTTP status code: C<404>, C<409>, C<500>. This is the whole point of the
class -- the one part of an engine error that is documented per endpoint and
identical across engines.
It arrives off the status line as a string of digits, exactly as
C<< $res{status} >> from L<API::Docker::Role::HTTP>'s C<response> option does,
so compare it numerically (C<< $err->status == 404 >>) rather than relying on
a type.
=head2 reason
The status line's reason phrase as the engine sent it (C<Not Found>,
C<Conflict>). Informational: it comes off the wire, not from a table, so it is
no more of a stable interface than the error body's prose. Branch on
L</status>.
=head2 body
The response body verbatim, before any decoding -- the bytes the engine sent.
Empty string when it sent none.
=head2 data
The decoded body, or C<undef> when there was nothing to decode or decoding
failed. Usually the HashRef the engine's C<{"message":...}> shape decodes to,
which is where an engine-specific extra such as Podman's C<cause> key can be
read; an array-shaped body decodes to an ArrayRef, so check the C<ref> before
subscripting it.
=head2 as_string
my $text = $err->as_string; # same as "$err"
The message and the location suffix, concatenated. This is what the
stringification overload returns.
=head1 SEE ALSO
=over
=item * L<API::Docker::Role::HTTP> - Raises this error; see its C<response>
option for the status of a request that did not fail
=item * L<API::Docker::Error::Stream> - Raised instead for a failure reported
inside a stream the daemon already answered with HTTP 200
=back
=head1 SUPPORT
=head2 Issues
Please report bugs and feature requests on GitHub at
L<https://github.com/Getty/p5-api-docker/issues>.
=head1 CONTRIBUTING
Contributions are welcome! Please fork the repository and submit a pull request.
=head1 AUTHOR
Torsten Raudssus <getty@cpan.org>
( run in 3.251 seconds using v1.01-cache-2.11-cpan-f9ab5d97e31 )