File Coverage

blib/lib/Conduit.pm

Criterion	Covered	Total	%
statement	39	50	78.0
branch	3	4	75.0
condition			n/a
subroutine	10	12	83.3
pod	2	3	66.6
total	54	69	78.2

#  You may distribute under the terms of either the GNU General Public License
#  or the Artistic License (the same terms as Perl itself)
#
#  (C) Paul Evans, 2026 -- [e-mail]

use v5.36;

use Future::AsyncAwait;
use Object::Pad 0.800;

package Conduit 0.03;
class Conduit
   :strict(params);

=head1 NAME

C - serve HTTP with L

=head1 SYNOPSIS

=for highlighter language=perl

   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;

=head1 DESCRIPTION

This module allows a program to respond asynchronously to HTTP requests as
part of a program based on L. It currently supports either a
simple L-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 B, serving also as a testbed for how to design
larger systems using C, and hopefully soon as a way to test out
the PAGI design.

This module reports basic metrics about received requests and sent responses
via L, as described by L.

=cut

use Carp;

use Future::IO 0.17;
use Future::Selector;
use IO::Socket::IP;

use Conduit::Client;

=head1 PARAMETERS

=head2 port

   port => $int

TCP port number to listen on for HTTP requests.

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

=cut

field $listensock :param = undef;
ADJUST :params (
   :$port = undef,
) {
   defined( $port ) or defined( $listensock ) or
      croak "Require either 'port' or 'listensock'";

   $listensock //= IO::Socket::IP->new(
      LocalPort => $port,
      Listen    => 5,
      ReuseAddr => 1,
   );
}

method port () { return $listensock->sockport; }

=head2 responder

   responder => $app

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

A code reference to the responder used for handling requests.

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

=head2 psgi_app

   psgi_app => $app

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

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

=cut

field $responder :param = undef;
field $psgi_app :param  = undef;

ADJUST {
   defined $responder or defined $psgi_app or
      croak "Require either 'responder' or 'psgi_app'";

   defined( $responder ) + defined( $psgi_app ) == 1 or
      croak "Require exactly one of 'responder' or 'psgi_app'";
}

=head1 METHODS

=cut

field $selector = Future::Selector->new;

async method listen ()
{
   while( my $clientsock = await Future::IO->accept( $listensock ) ) {
      my $client;
      if( $responder ) {
         $client = Conduit::Client::_ForHTTP->new(
            responder => $responder,
            server    => $self,
            socket    => $clientsock,
         );
      }
      elsif( $psgi_app ) {
         $client = Conduit::Client::_ForPSGI->new(
            psgi_app => $psgi_app,
            server   => $self,
            socket   => $clientsock,
         );
      }
      else {
         die "TODO: other app shapes?";
      }

      $selector->add(
         data => $client,
         f    => $client->run
            ->else( sub ( $err, @ ) {
               chomp $err;
               warn "Conduit client connection failed: $err\n";
               Future->done; # don't make the server fail
            }),
      );
   }
}

=head2 run

   $run_f = $conduit->run;

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

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

=cut

async method run ()
{
   $selector->add( data => "accept", f => $self->listen );
   await $selector->run;
}

=head1 TODO

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

=over 4

=item *

L support; likely in preference to any more PSGI.

=item *

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

=item *

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

=item *

HTTPS, perhaps via L or maybe something newer?

=item *

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

=back

=cut

=head1 AUTHOR

Paul Evans

=cut

0x55AA;