EV-Etcd
view release on metacpan or search on metacpan
lib/EV/Etcd.pm view on Meta::CPAN
use v5.10;
use EV;
use EV::Etcd;
my $client = EV::Etcd->new(
endpoints => ['127.0.0.1:2379'],
);
# Async put
$client->put('/my/key', 'value', sub {
my ($resp, $err) = @_;
die $err->{message} if $err;
say "Put succeeded, revision: $resp->{header}{revision}";
});
# Async get
$client->get('/my/key', sub {
my ($resp, $err) = @_;
die $err->{message} if $err;
say "Value: $resp->{kvs}[0]{value}";
});
# Watch
$client->watch('/my/key', sub {
my ($resp, $err) = @_;
return warn "Watch error: $err->{message}\n" if $err;
for my $event (@{$resp->{events}}) {
say "Event: $event->{type} on $event->{kv}{key}";
}
});
EV::run;
=head1 DESCRIPTION
EV::Etcd provides a high-performance async client for etcd v3 using native
gRPC Core C API integrated with the EV event loop.
=head1 METHODS
=head2 new
my $client = EV::Etcd->new(%options);
Options:
=over 4
=item endpoints
ArrayRef of etcd endpoints (host:port). Optional; defaults to
C<['127.0.0.1:2379']>. When more than one is provided, the client uses the
first endpoint and rotates to subsequent endpoints on connection failure.
=item timeout
RPC timeout in seconds. Default is 30 seconds. Minimum value is 1 second.
=item max_retries
Maximum number of reconnection attempts for streaming operations (watch,
lease_keepalive, election_observe) after a connection failure. Default is 3.
Set to 0 to disable automatic reconnection.
=item health_interval
Interval in seconds for health monitoring. Default is 0 (disabled).
When enabled, the client periodically checks the gRPC channel connectivity
state and calls the on_health_change callback when the connection state changes.
=item on_health_change
Callback called when the connection health status changes. Receives two
arguments: a boolean indicating health status (1=healthy, 0=unhealthy) and
the current endpoint string.
my $client = EV::Etcd->new(
endpoints => ['127.0.0.1:2379'],
health_interval => 5,
on_health_change => sub {
my ($is_healthy, $endpoint) = @_;
warn $is_healthy ? "Connected to $endpoint" : "Disconnected from $endpoint";
},
);
=item auth_token
Pre-set authentication token. Use this to create an authenticated client
without calling authenticate() first. Useful when you already have a valid
token from a previous session.
my $client = EV::Etcd->new(
endpoints => ['127.0.0.1:2379'],
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:
lib/EV/Etcd.pm view on Meta::CPAN
=head2 EV::Etcd::Watch Methods
=head3 cancel
$watch->cancel($callback);
Cancel the watch. The callback receives C<($response, $error)> when
cancellation is complete. The response is an empty hash reference on success.
Calling C<cancel> on an already-cancelled handle is safe: the callback fires
immediately with success. The handle remains valid as a Perl reference until
you drop it.
$watch->cancel(sub {
my ($resp, $err) = @_;
if ($err) {
warn "Cancel failed: $err->{message}";
} else {
print "Watch cancelled\n";
}
});
=head1 LEASE SERVICE
=head2 lease_grant
$client->lease_grant($ttl, $callback);
Grant a lease with the specified TTL (time-to-live) in seconds.
The callback receives C<($response, $error)>. Response keys:
=over 4
=item id
The lease ID.
=item ttl
The actual TTL granted by the server.
=item header
Standard response header.
=back
=head2 lease_revoke
$client->lease_revoke($lease_id, $callback);
Revoke a lease. All keys attached to the lease will be deleted. The response
contains C<header> only.
=head2 lease_keepalive
my $keepalive = $client->lease_keepalive($lease_id, $callback);
my $keepalive = $client->lease_keepalive($lease_id, \%opts, $callback);
Keep a lease alive. Creates a bidirectional streaming connection that keeps
the lease refreshed. Returns an C<EV::Etcd::Keepalive> object that can be
used to cancel the keepalive stream:
$keepalive->cancel(sub { my ($resp, $err) = @_; });
Options:
=over 4
=item auto_reconnect
If true, the keepalive stream will automatically reconnect after a connection
failure, with exponential backoff up to C<max_retries> (set on the client).
Default is 1 (enabled). Pass C<0> to disable.
=back
The keepalive callback receives C<($response, $error)> for each tick. On
success the response includes C<id>, C<ttl>, and C<header>. When the lease
has expired the server sends C<ttl=0>; the client maps that to an error
callback with C<< source => "keepalive" >> and status C<NOT_FOUND>.
=head2 EV::Etcd::Keepalive Methods
=head3 cancel
$keepalive->cancel($callback);
Cancel the keepalive stream. The callback receives C<($response, $error)>
when cancellation is complete. The response is an empty hash reference on
success.
Calling C<cancel> on an already-cancelled handle is safe: the callback fires
immediately with success. The handle remains valid as a Perl reference until
you drop it.
=head2 lease_time_to_live
$client->lease_time_to_live($lease_id, $callback);
$client->lease_time_to_live($lease_id, \%opts, $callback);
Get the remaining TTL of a lease.
Options:
=over 4
=item keys
If true, also return the list of keys attached to this lease.
=back
The callback receives C<($response, $error)>. Response keys:
=over 4
=item id
The lease ID.
lib/EV/Etcd.pm view on Meta::CPAN
Update the leader's value. Only the current leader can proclaim. The
response contains C<header> only.
Arguments:
=over 4
=item leader
The leader hashref returned in C<< $resp->{leader} >> from C<election_campaign>.
=item value
The new value to announce.
=item callback
Called with C<($response, $error)> when complete.
=back
Example:
$client->election_proclaim($leader, "new-value", sub {
my ($resp, $err) = @_;
warn "Proclaim failed: $err->{message}" if $err;
});
=head2 election_resign
$client->election_resign($leader, $callback);
Voluntarily give up leadership. The response contains C<header> only.
Arguments:
=over 4
=item leader
The leader hashref returned in C<< $resp->{leader} >> from C<election_campaign>.
=item callback
Called with C<($response, $error)> when complete.
=back
Example:
$client->election_resign($leader, sub {
my ($resp, $err) = @_;
say "Resigned from leadership" unless $err;
});
=head2 election_observe
my $observe = $client->election_observe($name, $callback);
my $observe = $client->election_observe($name, \%opts, $callback);
Observe leader changes for an election. This creates a streaming connection
that receives notifications whenever the leader changes. Returns an
C<EV::Etcd::Observe> object that can be used to cancel the observe stream:
$observe->cancel(sub { my ($resp, $err) = @_; });
Arguments:
=over 4
=item name
The name of the election to observe.
=item callback
Called with C<($response, $error)> for each leader change.
=back
Options:
=over 4
=item auto_reconnect
If true, automatically reconnect after connection failures. Default is true.
=back
The response contains:
=over 4
=item kv
The key-value pair of the current leader.
=item header
Standard response header.
=back
Example:
my $observe = $client->election_observe("my-election", sub {
my ($resp, $err) = @_;
if ($err) {
warn "Observe error: $err->{message}";
return;
}
say "Leader changed: $resp->{kv}{value}";
});
=head2 EV::Etcd::Observe Methods
=head3 cancel
$observe->cancel($callback);
( run in 0.387 second using v1.01-cache-2.11-cpan-6aa56a78535 )