view release on metacpan or  search on metacpan

lib/EV/Etcd.pm  view on Meta::CPAN

        auth_token => $saved_token,
    );

=back

=head1 ENCODING

Keys and values are stored by etcd as raw bytes; this module does not perform
any character encoding. If you pass a Perl string with the UTF-8 flag set
(e.g. a literal containing non-ASCII characters under C<use utf8>), the UTF-8
byte representation is what gets stored. Values returned by C<get> are byte
strings without the UTF-8 flag — string-equality with the original literal
will fail unless you decode explicitly.

For character data, encode/decode at the boundary using L<Encode>:

    use Encode qw(encode_utf8 decode_utf8);

    $client->put($key, encode_utf8($value), sub { ... });
    $client->get($key, sub {
        my ($resp) = @_;
        my $value = decode_utf8($resp->{kvs}[0]{value});
    });

=head1 ERROR HANDLING

Errors are returned as hash references with the following structure:

    {
        code      => 14,              # gRPC status code (integer)
        status    => "UNAVAILABLE",   # gRPC status name (string)
        message   => "Connection refused",  # Error message
        source    => "get",           # Which operation failed
        retryable => 1,               # Whether the error is retryable
    }

The C<retryable> field indicates whether the error is transient (status codes:
UNAVAILABLE, RESOURCE_EXHAUSTED, ABORTED, DEADLINE_EXCEEDED).
Streaming operations (watch, keepalive, observe) automatically reconnect
with linear backoff whenever the stream ends for any reason other than an
explicit cancel — connection loss, server restart, graceful close — up to
C<max_retries> attempts (the attempt counter resets as the stream makes
progress). The error callback fires once reconnection is disabled or
exhausted. Errors the server sends I<on> the stream — a watch cancelled or
compacted away, an expired lease — are reported immediately and do not
reconnect. A fully silent network partition (no FIN/RST reaching the
client) is indistinguishable from an idle stream: no gRPC keepalive pings
are configured, so such an outage surfaces only once connectivity returns
or the OS abandons the connection. Unary RPCs (get, put, delete, etc.) do
not retry automatically; use the C<retryable> field to implement
application-level retry logic.

=head1 CALLBACK LIFETIMES

Callbacks are stored in C structures that are invisible to Perl's garbage
collector. A callback closure that captures the client (or its own stream
handle) forms a reference cycle that Perl cannot reclaim: the objects stay
alive until the stream is cancelled or the client is destroyed, even if all
Perl-side references are dropped.

For long-lived streams, capture a weakened client reference and call
C<cancel()> when the stream is no longer needed:

    use Scalar::Util 'weaken';

    my $client = EV::Etcd->new(endpoints => ['127.0.0.1:2379']);
    weaken(my $weak = $client);
    my $watch = $client->watch('/my/key', sub {
        my ($resp, $err) = @_;
        return if $err;
        $weak->put('/my/seen', 1, sub {}) if $weak;
    });
    # ... later:
    $watch->cancel(sub { });

=head1 KEY-VALUE OPERATIONS

=head2 put

    $client->put($key, $value, $callback);
    $client->put($key, $value, \%opts, $callback);

Put a key-value pair into etcd.

Options:

=over 4

=item lease

Lease ID to associate with the key.

=item prev_kv

If true, returns the previous key-value pair in the response.

=item ignore_value

If true, updates the lease without changing the value.

=item ignore_lease

If true, updates the value without changing the lease.

=back

The callback receives C<($response, $error)>. Response keys: C<header>, plus
C<prev_kv> (a kv hashref) when the C<prev_kv> option is set.

=head2 get

    $client->get($key, $callback);
    $client->get($key, \%opts, $callback);

Get key(s) from etcd.

Options:

=over 4

=item prefix

If true, returns all keys with the given prefix.

=item range_end

End of the key range to query.