view release on metacpan or  search on metacpan

lib/AnyEvent/HTTPD/ExtDirect.pod  view on Meta::CPAN

=pod

=begin readme text

AnyEvent::HTTPD::ExtDirect
==========================

=end readme

=for readme stop

=head1 NAME

AnyEvent::HTTPD::ExtDirect - RPC::ExtDirect gateway for AnyEvent::HTTPD

=head1 SYNOPSIS

    use RPC::ExtDirect::Config;
    use AnyEvent::HTTPD::ExtDirect;
    
    # Ext.Direct Action packages go here
    use My::Server::Foo;
    use My::Server::Bar;
    
    my $config = RPC::ExtDirect::Config->new(
        api_path    => '/api',
        router_path => '/router',
        poll_path   => '/events',
    );
    
    my $httpd = AnyEvent::HTTPD::ExtDirect->new( config => $config );
    
    $httpd->run;

=head1 DESCRIPTION

=for readme continue

This module provides an L<RPC::ExtDirect> gateway implementation for
L<AnyEvent::HTTPD>, a simple lightweight event based web server.
Unlike other gateways like L<Plack::Middleware::ExtDirect> or
L<CGI::ExtDirect>, this module is in fact more of an application
server than just a plugin. You can think of it as L<Plack> framework
and L<Plack::Middleware::ExtDirect> combined into one package.

That said, the asynchronous event based nature of AnyEvent::HTTPD
allows using it both as a standalone application server, and as a part
of a larger program that may do other things besides serving Ext.Direct
or plain HTTP requests. See L</"Non-blocking server"> below.

If you are not familiar with Ext.Direct, more information can be found
in L<RPC::ExtDirect::Intro>.

=for readme stop

=head1 USAGE

=head2 Configuration

To configure an AnyEvent::HTTPD::ExtDirect instance, you will need to
create an instance of L<RPC::ExtDirect::Config> with all required
options set, and pass it to AnyEvent::HTTPD::ExtDirect
L<constructor|/new> to be used. This step is optional; by default the
Config instance in the
L<global API instance|RPC::ExtDirect::API/"GLOBAL API TREE INSTANCE">
will be used instead.

Refer to L<RPC::ExtDirect::Config/OPTIONS> for the list of
configuration options and their default values.

=head2 Entry points

AnyEvent::HTTPD::ExtDirect has three main entry points: the
L<API|RPC::ExtDirect::Intro/API> generator, the
L<Router|RPC::ExtDirect::Intro/Router>, and the
L<Event Provider|RPC::ExtDirect::Intro/"Event Provider">. Each of
these has to be assigned a unique server side URI that clients will
GET/POST requests to. The API generator URI is usually hardcoded in
the client; the Router and Event Provider URIs are advertised as a
part of the L<API declaration|RPC::ExtDirect::Intro/"API declaration">
provided by the API generator.

The entry point URIs are configured with the
L<api_path|RPC::ExtDirect::Config/api_path>,
L<router_path|RPC::ExtDirect::Config/router_path>, and
L<poll_path|RPC::ExtDirect::Config/poll_path> Config options as shown
in the L</SYNOPSIS>. These configuration options have default values
that will work out of box; refer to L<RPC::ExtDirect::Config> for
details.

=head2 Non-blocking server

AnyEvent::HTTPD::ExtDirect can be used not only as a standalone event
based application server, but also as an embedded Ext.Direct engine
in a larger event based application. This is important and is worth
repeating: the non-blocking server approach will only work if your
application is event based, adhering to L<AnyEvent> conventions!

To use AnyEvent::HTTPD::ExtDirect as a non-blocking server, create
an instance of it, prime it by calling L</set_callbacks>, and
save a reference to it:

    my $httpd = AnyEvent::HTTPD::ExtDirect->new( config => $config );
    $httpd->set_callbacks( ... );

Saving a reference to the server instance is important; if you don't