view release on metacpan or  search on metacpan

lib/Consul.pm  view on Meta::CPAN

=head1 SYNOPSIS

    use Consul;
    
    my $consul = Consul->new;
    say $consul->status->leader;
    
    # shortcut to single API
    my $status = Consul->status;
    say $status->leader;

=head1 DESCRIPTION

This is a client library for accessing and manipulating data in a Consul
cluster. It targets the Consul v1 HTTP API.

This module is quite low-level. You're expected to have a good understanding of
Consul and its API to understand the methods this module provides. See L</SEE ALSO>
for further reading.

=head1 WARNING

This is still under development. The documentation isn't all there yet (in
particular about the return types) and a couple of APIs aren't implemented.
It's still very useful and I don't expect huge changes, but please take care
when upgrading. Open an issue if there's something you need that isn't here and
I'll get right on it!

=head1 CONSTRUCTOR

=head2 new

    my $consul = Consul->new( %args );

This constructor returns a new Consul client object. Valid arguments include:

=over 4

=item *

C<host>

Hostname or IP address of an Consul server (default: C<127.0.0.1>)

=item *

C<port>

Port where the Consul server is listening (default: C<8500>)

=item *

C<ssl>

Use SSL/TLS (ie HTTPS) when talking to the Consul server (default: off)

=item *

C<timeout>

Request timeout. If a request to Consul takes longer that this, the endpoint
method will fail (default: 15).

=item *

C<token>

Consul ACL token.  This is used to set the C<X-Consul-Token> HTTP header.  Typically
Consul agents are pre-configured with a default ACL token, or ACLs are not enabled
at all, so this option only needs to be set in certain cases.

=item *

C<request_cb>

A callback to an alternative method to make the actual HTTP request. The
callback is of the form:

    sub {
        my ($self, $req) = @_;
        ... do HTTP call
        $req->callback->(Consul::Response->new(...));
    }

C<$req> is a C<Consul::Request> object, and has the following attributes:

=over 4

=item *

C<method>

The HTTP method for the request.

=item *

C<url>

The complete URL to request. This is fully formed, and includes scheme, host,
port and query parameters. You shouldn't need to touch it.

=item *

C<headers>

A L<Hash::MultiValue> object containing any headers that should be added to the
request.

=item *

C<content>

The body content for the request.

=item *

C<callback>

A callback to call when the request is completed. It takes a single
C<Consul::Response> object as its parameter.

=item *

C<args>

A hashref containing the original arguments passed in to the endpoint method.

=back

The C<callback> function should be called with a C<Consul::Response> object
containing the values returned by the Consul server in response to the request.
Create one with C<new>, passing the following attributes:

=over 4

=item *

C<status>

The integer status code.

=item *

C<reason>

The status reason phrase.

=item *

C<headers>

A L<Hash::MultiValue> containing the response headers.

=item *

C<content>

Any body content returned in the response.

=item *

C<request>

The C<Consul::Request> object passed to the callback.

=back

Consul itself provides a default C<request_cb> that uses L<HTTP::Tiny> to make
calls to the server. If you provide one, you should honour the value of the
C<timeout> argument.

C<request_cb> can be used in conjunction with the C<cb> option to all API method
endpoints to get asynchronous behaviour. It's recommended however that you
don't use this directly, but rather use a module like L<AnyEvent::Consul> to
take care of that for you.

If you just want to use this module to make simple calls to your Consul
cluster, you can ignore this option entirely.

=item *

C<error_cb>

A callback to an alternative method to handle internal errors (usually HTTP
errors). The callback is of the form:

    sub {
        my ($err) = @_;
        ... output $err ...
    }

The default callback simply calls C<croak>.

=back

=head1 ENDPOINTS

Individual API endpoints are implemented in separate modules. The following
methods will return a context objects for the named API. Alternatively, you can
request an API context directly from the Consul package. In that case,
C<Consul-E<gt>new> is called implicitly.

    # these are equivalent
    my $agent = Consul->new( %args )->agent;
    my $agent = Consul->agent( %args );

=head2 kv

Key/value store API. See L<Consul::API::KV>.

=head2 agent

Agent API. See L<Consul::API::Agent>.

=head2 catalog

Catalog (nodes and services) API. See L<Consul::API::Catalog>.

=head2 health

Health check API. See L<Consul::API::Health>.

=head2 session

Sessions API. See L<Consul::API::Session>.

=head2 acl

Access control API. See L<Consul::API::ACL>.

=head2 event

User event API. See L<Consul::API::Event>.

=head2 status

System status API. See L<Consul::API::Status>.

=head1 METHOD OPTIONS

All API methods implemented by the endpoints can take a number of arguments.
Most of those are documented in the endpoint documentation. There are however
some that are common to all methods:

=over 4

=item *

C<cb>

A callback to call with the results of the method. Without this, the results
are returned from the method, but only if C<request_cb> is synchronous. If an
asynchronous C<request_cb> is used without a C<cb> being passed to the method, the
method return value is undefined.

If you just want to use this module to make simple calls to your Consul
cluster, you can ignore this option entirely.

C<error_cb>

A callback to an alternative method to handle internal errors (usually HTTP
errors).  errors). The callback is of the form:

    sub {
        my ($err) = @_;
        ... output $err ...
    }

The default callback calls the C<error_cb> for the API object itself, which by
default, simply calls croak.

=back

=head1 BLOCKING QUERIES

Some Consul API endpoints support a feature called a "blocking query". These
endpoints allow long-polling for changes, and support some extra information
about the server state, including the Raft index, in the response headers.

The corresponding endpoint methods, when called in array context, will return a
second value. This is an object with three methods, C<index>, C<last_contact>
and C<known_leader>, corresponding to the similarly-named header fields. You
can use these to set up state watches, CAS writes, and so on.

See the Consul API docs for more information.

=head1 SEE ALSO

=over 4

=item *

L<AnyEvent::Consul> - a wrapper providing asynchronous operation

=item *

L<https://www.consul.io/docs/agent/http.html> - Consul HTTP API documentation

=back

=head1 SUPPORT

=head2 Bugs / Feature Requests

Please report any bugs or feature requests through the issue tracker
at L<https://github.com/robn/Consul/issues>.
You will be notified automatically of any progress on your issue.

=head2 Source Code

This is open source software. The code repository is available for
public review and contribution under the terms of the license.

L<https://github.com/robn/Consul>

  git clone https://github.com/robn/Consul.git

=head1 CONTRIBUTORS

=over 4

=item *

Rob N ★ <robn@robn.io>

=item *

Aran Deltac <bluefeet@gmail.com>

=item *

Michael McClimon

=back

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2015 by Rob N ★.

This is free software; you can redistribute it and/or modify it under