view release on metacpan or  search on metacpan

lib/API/Docker/Role/Using.pm  view on Meta::CPAN

The clone holds the B<same client>, on the same terms: the resource classes
hold it as a C<weak_ref>, and the clone does too. So a clone never keeps a
client alive that the caller has let go, and never becomes the reason a client
outlives its scope.

The other side of that is the footgun this distribution already has:

    my $quick = API::Docker->new->containers->using(read_timeout => 5);
    $quick->list;   # dies: the client was gone at the end of the first line

Keep the client in a variable. That is not new here: the entity classes hold
it weakly for the same reason, so C<< API::Docker->new->images->list >> has
always handed back images whose C<client> was already gone.

Nothing else is shared: the options live on the clone, the original resource
class is not touched, and two clones of one resource class know nothing of
each other.

    my $r = $docker->containers;
    my $a = $r->using(read_timeout => 5);
    my $b = $r->using(read_timeout => 60);
    # $r is still unbounded, $a is 5, $b is 60

=head2 Chaining merges, key by key

    $docker->images->using(connect_timeout => 2)->using(read_timeout => 60)

carries both, and a repeated key takes the later value:

    ->using(read_timeout => 60)->using(read_timeout => 0)   # 0 wins

Merging rather than replacing, because the two bounds are independent: a
helper that hands out a resource class with a connect bound already on it, and
a caller that then tightens the read bound, are both saying what they mean --
and a C<using> that dropped the other half would do it silently, which is the
one outcome neither of them could have wanted.

=head2 What it refuses

Both are croaks rather than a shrug, because the failure they replace is
invisible: an option this role kept and no request read would leave the caller
believing a bound is in force that is not.

=over

=item * B<An unknown option.> C<< ->using(read_timout => 5) >> is a typo, and
carrying it would bound nothing while looking exactly like a call that does.

=item * B<No options at all.> C<< ->using() >> asks for a clone that differs
from the original in nothing. Where the pairs are computed rather than
written, decide it at the call:

    my $r = %bounds ? $docker->containers->using(%bounds) : $docker->containers;

=back

An odd number of arguments croaks too, before the pairs are read.

=head2 What has no clone of its own

B<The entity classes.> C<< $container->logs >> and its neighbours are
one-line delegations to the resource class, and they hold the container's own
daemon fields -- every one of them, verbatim -- rather than a call surface, so
a clone would have to copy a record whose shape is the daemon's. The bound
belongs where the request is built:

    $docker->containers->using(read_timeout => 5)->logs($container->id);

B<The client.> C<< $docker->using(...) >> would be a second client sharing
one connection state and one negotiated API version with the first. The
client already takes both bounds as constructor arguments, which is the level
it works at.

=head2 using

    my $bounded = $docker->containers->using(read_timeout => 5);

Returns a clone of the resource class that hands C<read_timeout> and
C<connect_timeout> to every request made through it. Takes those two options
and no others; an unknown one, an odd number of arguments, and an empty call
all croak.

What it carries is held in C<_request_options>, which is private and composed
into the resource classes alongside it: C<{}> on a resource class nobody
called C<using> on, and spliced by each resource method into the option list
it hands the transport.

=head1 SEE ALSO

=over

=item * L<API::Docker/TIMEOUTS> - what the two bounds cover, and what they do
not

=item * L<API::Docker::Role::HTTP/"Bounding a request that never ends"> -
C<read_timeout>, per transport

=item * L<API::Docker::Role::HTTP/"Bounding the connection itself"> -
C<connect_timeout>, per transport

=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>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> L<https://raudssus.de/>.

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

=cut