API-Docker

 view release on metacpan or  search on metacpan

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

    . 'would return is the object it was called on. It carries '
    . join(' and ', sort keys %CARRIED)
    . '; where the pairs are computed, test for them at the call'
    unless @args;

  my %opts = @args;
  for my $name (sort keys %opts) {
    croak __PACKAGE__ . '->using does not carry \'' . $name . '\'. It carries '
      . join(' and ', sort keys %CARRIED) . '; everything else a request '
      . 'needs is an argument of the method that builds it'
      unless $CARRIED{$name};
  }

  # Built from the client and the options rather than copied wholesale: the
  # resource classes hold exactly one piece of state, the client, and passing
  # it through the constructor is what re-weakens the reference in the clone.
  return ref($self)->new(
    client           => $self->client,
    _request_options => { %{ $self->_request_options }, %opts },
  );
}



1;

__END__

=pod

=encoding UTF-8

=head1 NAME

API::Docker::Role::Using - A resource class clone that bounds a run of calls

=head1 VERSION

version 0.006

=head1 SYNOPSIS

    my $docker = API::Docker->new(read_timeout => 30);

    # the rule, for this client
    $docker->containers->list;

    # the exception, for these calls
    my $quick = $docker->containers->using(read_timeout => 5);
    $quick->list;
    $quick->inspect($id);

    # or in passing
    $docker->images->using(connect_timeout => 2, read_timeout => 60)
      ->pull(fromImage => 'alpine');

=head1 DESCRIPTION

L<API::Docker::Role::HTTP/read_timeout> and
L<API::Docker::Role::HTTP/connect_timeout> are attributes of the client, so
they are set once and hold for every request it makes. That is the right
level for a rule and the wrong one for an exception: a client bounded at 30
seconds is no help to the one call that must give up after 2, and a client
bounded at 2 cannot pull an image.

C<using> is the exception. It returns a B<clone of the resource class>
carrying the options, and every request made through that clone is given
them:

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

Only the two transport bounds may be carried. Everything else a request needs
-- query parameters, the body, a streaming callback -- is an argument of the
method that builds it, and a value carried past that method could only either
overwrite what it built or be overwritten by it.

=head2 The clone and the client

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.



( run in 0.446 second using v1.01-cache-2.11-cpan-234fa220139 )