NAME

    Conduit - serve HTTP with Future::IO

SYNOPSIS

       use Conduit;
       use Future::AsyncAwait;
    
       my $server = Conduit->new(
          port     => 8080,
          psgi_app => sub ( $env ) {
             return [
                200,
                [ "Content-Type" => "text/plain" ],
                [ "Hello, world!" ]
             ];
          },
       );
    
       await $server->run;

DESCRIPTION

    This module allows a program to respond asynchronously to HTTP requests
    as part of a program based on Future::IO. It currently supports either
    a simple HTTP::Message-based responder or a PSGI application, but the
    intention is to allow PAGI and possibly other interface shapes in a
    later version.

    This is currently experimental, serving also as a testbed for how to
    design larger systems using Future::IO, and hopefully soon as a way to
    test out the PAGI design.

    This module reports basic metrics about received requests and sent
    responses via Metrics::Any, as described by Conduit::Metrics.

PARAMETERS

 port

       port => $int

    TCP port number to listen on for HTTP requests.

    Either this or the listensock parameter must be provided; though the
    latter is intended for internal and unit-test purposes and will not be
    otherwise documented.

 responder

       responder => $app
    
          $response = await $app->( $request );

    A code reference to the responder used for handling requests.

    It will be passed an HTTP::Request instance containing the incoming
    request and is expected to yield an HTTP::Response instance via a
    future. As a small convenience, the server will fill in the protocol
    and content_length fields of the response if they are not provided by
    the responder.

 psgi_app

       psgi_app => $app

    A code reference to the PSGI application used for handling requests.

    Currently, exactly one of responder or psgi_app must be provided, but
    the intention is soon to allow other forms of responders, such as PAGI
    as alternatives.

METHODS

 run

       $run_f = $conduit->run;

    Starts operation of the server, allowing it to accept new connections,
    serve requests, and run the application.

    Returns a Future instance that in normal circumstances should never
    complete; it will remain pending indefinitely. The toplevel program can
    either await this if it has nothing else to do, or add that to a
    collection such as with Future::Selector.

TODO

    Honestly, quite a lot. Almost everything in fact. ;)

      * PAGI support; likely in preference to any more PSGI.

      * Maybe support streaming PSGI responses, though it would still be
      preferrable to do this with PAGI first.

      * Investigate split IPv4+IPv6 serving, whether it needs two socket or
      one will suffice. This may be OS-dependent.

      * HTTPS, perhaps via IO::Socket::SSL or maybe something newer?

      * Look into what's required to support some sort of websocket thing
      in addition to plain HTTP.

AUTHOR

    Paul Evans <leonerd@leonerd.org.uk>