/ 
Plack-Client-0.06
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.06

SYNOPSIS

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

DESCRIPTION

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. The app to use for a given request is determined based on the URL schema; for instance, $client->get('http://example.com/foo') would call a Plack::App::Proxy app to retrieve a remote resource, while $client->get('psgi-local://myapp/foo') would directly call the myapp app coderef that was passed into the constructor for the psgi-local backend. This API allows a simple config file change to be all that's necessary to migrate your service to a different server. The list of available URL schemas is determined by the arguments passed to the constructor, which map schemas to backends which return appropriate apps based on the request.

METHODS

new

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

Constructor. Takes a hash of arguments, where keys are URL schemas, and values are backends which handle those schemas. Backends are really just coderefs which receive a Plack::Request and return a PSGI application coderef, but see Plack::Client::Backend for a more structured way to define these. Hashref and arrayref values are also valid, and will be dereferenced and passed to the constructor of the default backend for that scheme (the class Plack::Client::Backend::$scheme, where $scheme has dashes replaced by underscores).

backend

$client->backend('http');
$client->backend($req->uri);

Returns the backend object used to generate apps for the given URL scheme or URI object. By default, the SSL variant of a scheme will be handled by the same backend as the non-SSL variant, although this can be overridden by explicitly specifying a backend for the SSL variant. SSL variants are indicated by appending -ssl to the scheme (or by being equal to https).

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

Please see those modules/websites for more information related to this module.

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.