/ 
Plack-Client-0.01-TRIAL
River stage one • 1 direct dependent • 1 total dependent
/ Plack::Client

NAME

Plack::Client - abstract interface to remote web servers and local PSGI apps

VERSION

version 0.01

SYNOPSIS

use Plack::Client;
my $client = Plack::Client->new({ myapp => sub { ... } });
my $res1 = $client->get('http://google.com/');
my $res2 = $client->post(
    'psgi-local://myapp/foo.html',
    ['Content-Type' => 'text/plain'],
    "foo"
);

DESCRIPTION

NOTE: This is a trial release while I work out what the API should be. Use at your own risk!

A common task required in more complicated web applications is communicating with various web services for different tasks. These web services may be spread among a number of different servers, but some of them may be on the local server, and for those, there's no reason to require accessing them through the network; assuming the app is written using Plack, the app coderef for the service already exists in the current process, so a lot of time could be saved by just calling it directly.

The key issue here then becomes providing an interface that allows accessing both local and remote services through a common api, so that services can be moved between servers with only a small change in configuration, rather than having to change the actual code involved in accessing it. This module solves this issue by providing an API similar to LWP::UserAgent, but using an underlying implementation consisting entirely of Plack apps. Local apps are distinguished from remote apps by the URL scheme: remote URLs use http or https, while local URLs use psgi-local or psgi-local-ssl. For instance, accessing /foo on a remote application would look like this: $client->get('http://some.other.server.com/foo'), and accessing the same thing on a local application would look like this: $client->get('psgi-local://myapp/foo'), but they will both give the same result. This API allows a simple config file change to be all that's necessary to migrate your service to a different server.

METHODS

new

my $client = Plack::Client->new(
    apps => {
        foo => sub { ... },
        bar => MyApp->new->to_app,
    }
)

Constructor. Takes a hash of arguments, with these keys being valid:

apps

A mapping of local app names to PSGI app coderefs. These are the apps that will be available via the psgi-local URL scheme.

apps

my $apps = $client->apps;

Returns the apps hashref that was passed to the constructor.

app_for

my $app = $client->app_for('foo');

Returns the app corresponding to the given app name (or undef, if no such app exists).

request

$client->request(
    'POST',
    'http://example.com/',
    ['Content-Type' => 'text/plain'],
    "content",
);
$client->request(HTTP::Request->new(...));
$client->request($env);
$client->request(Plack::Request->new(...));

This method performs most of the work for this module. It takes a request in any of several forms, makes the request, and returns the response as a Plack::Response object. The request can be in the form of an HTTP::Request or Plack::Request object directly, or it can take arguments to pass to the constructor of either of those two modules (so see those two modules for a description of exactly what is valid).

get

post

put

delete

$client->get('http://example.com/foo');
$client->head('psgi-local://bar/admin');
$client->post('https://example.com/submit', [], "my submission");
$client->put('psgi-local-ssl://foo/new-item', [], "something new");
$client->delete('http://example.com/item/2');

These methods are just shorthand for request. They only allow the "URL, headers, body" API; for anything more complicated, request should be used directly.

BUGS

No known bugs.

Please report any bugs through RT: email bug-plack-client at rt.cpan.org, or browse to http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Plack-Client.

SEE ALSO

SUPPORT

You can find this documentation for this module with the perldoc command.

perldoc Plack::Client

You can also look for information at:

AUTHOR

Jesse Luehrs <doy at tozt dot net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2011 by Jesse Luehrs.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.