/ 
Conduit-0.03
/ Conduit

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>