NAME
Clustericious::Client - Constructor for clients of Clustericious apps.
SYNOPSIS
package Foo::Client;
use Clustericious::Client;
route 'welcome' => '/'; # GET /
route status; # GET /status
route myobj => [ 'MyObject' ]; # GET /myobj
route something => GET => '/some/';
route remove => DELETE => '/something/';
object 'obj'; # Defaults to /obj
object 'foo' => '/something/foo'; # Can override the URL
route status => \"Get the status"; # Scalar refs are documentation
route_doc status => "Get the status"; # or you can use route_doc
route_args status => [ # route_args sets method or cli arguments
{
name => 'full',
type => '=s',
required => 0,
doc => 'get a full status',
},
];
route_args wrinkle => [ # methods correspond to "route"s
{
name => 'time'
}
];
sub wrinkle { # provides cli command as well as a method
my $c = shift;
my %args = @_;
if ($args{time}) {
...
}
}
----------------------------------------------------------------------
use Foo::Client;
my $f = Foo::Client->new();
my $f = Foo::Client->new(server_url => 'http://someurl');
my $f = Foo::Client->new(app => 'MyApp'); # For testing...
my $welcome = $f->welcome(); # GET /
my $status = $f->status(); # GET /status
my $myobj = $f->myobj('key'); # GET /myobj/key, MyObject->new()
my $something = $f->something('this'); # GET /some/this
$f->remove('foo'); # DELETE /something/foo
my $obj = $f->obj('this', 27); # GET /obj/this/27
# Returns either 'Foo::Client::Obj' or 'Clustericious::Client::Object'
$f->obj({ set => 'this' }); # POST /obj
$f->obj('this', 27, { set => 'this' }); # POST /obj/this/27
$f->obj_delete('this', 27); # DELETE /obj/this/27
my $obj = $f->foo('this'); # GET /something/foo/this
$f->status(full => "yes");
$f->wrinkle( time => 1 );
----------------------
#!/bin/sh
fooclient status
fooclient status --full yes
fooclient wrinkle --time
DESCRIPTION
Some very simple helper functions with a clean syntax to build a REST type client suitable for Clustericious applications.
The builder functions add methods to the client object that translate into basic REST functions. All of the 'built' methods return undef on failure of the REST/HTTP call, and auto-decode the returned body into a data structure if it is application/json.
Using Clustericious::Client also allows for easy creation of both perl APIs and command line clients for a Clustericious server. See Clustericious::Client::Command.
ATTRIBUTES
This class inherits from Mojo::Base, and handles attributes like that class. The following additional attributes are used.
client
A client to process the HTTP stuff with. Defaults to a Mojo::UserAgent.
app
For testing, you can specify a Mojolicious app name.
server_url
You can override the URL prefix for the client, otherwise it will look it up in the config file.
res
After an HTTP error, the built methods return undef. This function will return the Mojo::Message::Response from the server.
res->code and res->message are the returned HTTP code and message.
METHODS
new
my $f = Foo::Client->new();
my $f = Foo::Client->new(server_url => 'http://someurl');
my $f = Foo::Client->new(app => 'MyApp'); # For testing...
If the configuration file has a "url" entry, this will be used as the default url (first case above). Additionally, if the ssh_tunnel key is given in the config file, a tunnel may be created automatically (and destroyed when the client is destroyed). Here's a sample configuration :
"url" : "http://localhost:12345",
"ssh_tunnel" : {
"remote_host" : "omidev",
"server_host" : "localhost",
"server_port" : "9014"
},
This would automatically execute this
ssh -N -L12345:localhost:9014 omidev
in the background.
tx
The most recent HTTP::Transaction.
userinfo
Credentials currently stored.
remote
Tell the client to use the remote information in the configuration. For instance, if the config has
remotes :
test :
url: http://foo
bar :
url: http://baz
username : one
password : two
Then setting remote("test") uses the first url, and setting remote("bar") uses the second one.
remotes
Return a list of available remotes.
login
Log in to the server. This will send basic auth info along with every subsequent request.
$f->login; # looks for username and password in $app.conf
$f->login("elmer", "fudd");
$f->login(username => "elmer", password => "fudd");
errorstring
After an error, this returns an error string made up of the server error code and message. (use res->code and res->message to get the parts)
(e.g. "Error: (500) Internal Server Error")
FUNCTIONS
route
route 'subname'; # GET /subname
route subname => '/url'; # GET /url
route subname => GET => '/url'; # GET /url
route subname => POST => '/url'; # POST /url
route subname => DELETE => '/url'; # DELETE /url
route subname => ['SomeObjectClass'];
route subname \"<documentation> <for> <some> <args>";
Makes a method subname() that does the REST action. Any scalar arguments are tacked onto the end of the url separated by a slash. If any argument begins with "--", it and its successor are treated as part of URL query string (for a GET request). If any argument begins with a single "-", it and it successor are treated as HTTP headers to send (for a GET request). If you pass a hash reference, the method changes to POST and the hash is encoded into the body as application/json.
A hash reference after a POST method becomes headers.
A scalar reference as the final argument adds documentation about this route which will be displayed by the command-line client.
route_meta
Set metadata attributes for this route.
route_meta 'bucket_map' => { auto_failover => 1 }
route_meta 'bucket_map' => { quiet_post => 1 }
route_meta 'bucket_map' => { skip_existing => 1 }
route_args
Set arguments for this route. This allows command line options to be automatically transformed into method arguments. route_args associates an array ref with the name of a route. Each entry in the array ref is a hashref which may have keys as shown in this example :
route_args send => [
{
name => 'what', # name of the route
type => '=s', # type (see L<Getopt::Long>)
alt => 'long|extra|big', # alternative names
required => 0, # Is it required?
doc => 'get a full status', # brief documentation
},
{
name => 'items', # name of the route
type => '=s', # type (see L<Getopt::Long>)
doc => 'send a list of items' # brief docs
preprocess => 'list' # make an array ref from a list
},
];
The keys have the following effect :
- name
-
The name of the option. This should be preceded by two dashes on the command line. It is also sent as the named argument to the method call.
- type
-
A type, as described in Getopt::Long. This will be appended to the name to form the option specification.
- alt
-
An alternative name or names (joined by |).
- required
-
If this arg is required, set this to 1.
- doc
-
A brief description to be printed in error messages and help documenation.
- preprocess
-
Can be either 'yamldoc' or 'list'. In both cases, the argument is expected to refer to either a filename which exists, or else "-" for STDIN. The contents are then transformed from YAML (for yamldoc), or split on carriage returns (for list) to form either a data structure or an arrayref, respectively.
object
object 'objname'; # defaults to URL /objname
object objname => '/some/url';
Creates two methods, one named with the supplied objname() (used for create, retrieve, update), and one named objname_delete().
Any scalar arguments to the created functions are tacked onto the end of the url. Performs a GET by default, but if you pass a hash reference, the method changes to POST and the hash is encoded into the body as application/json.
The 'object' routes will automatically look for a class named with the object name, but upper case first letter and first after any underscores, which are removed:
object 'myobj'; Foo::Client::Myobj;
object 'my_obj'; Foo::Client::MyObj;
If such a class isn't found, object will default to returning a Clustericious::Client::Object.
meta_for
Get the metadata for a route.
$client->meta_for('welcome');
Returns a Clustericious::Client::Meta::Route object.
COMMON ROUTES
These are routes that are automatically supported by all clients. See Clustericious::RouteBuilder::Common. Each of these must also be in Clustericious::Client::Meta for there to be documentation.
version
Retrieve the version on the server.
status
Retrieve the status from the server.
api
Retrieve the API from the server
logtail
Get the last N lines of the server log file.
ssh_tunnel_is_up
Check to see if an ssh tunnel is alive for the current client.
stop_ssh_tunnel
Stop any running ssh tunnel for this client.
ENVIRONMENT
Set ACPS_SUPPRESS_404 to a regular expression in order to not print messages when a 404 response is returned from urls matching that regex.
AUTHORS
Brian Duggan
Graham Ollis
Curt Tilmes
NOTES
This is a beta release. The API is subject to changes without notice.