File Coverage

blib/lib/PAGI/Endpoint/Router.pm

Criterion	Covered	Total	%
statement	139	177	78.5
branch	23	36	63.8
condition	9	18	50.0
subroutine	33	45	73.3
pod	4	5	80.0
total	208	281	74.0

package PAGI::Endpoint::Router;
$PAGI::Endpoint::Router::VERSION = '0.002000';
use strict;
use warnings;

use Future::AsyncAwait;
use Carp qw(croak);
use Scalar::Util qw(blessed);
use Module::Load qw(load);


sub new {
    my ($class, %args) = @_;
    return bless {
        _state => {},
    }, $class;
}

# Worker-local state (NOT shared across workers)
sub state {
    my ($self) = @_;
    return $self->{_state};
}

# Override in subclass to use a custom context class
sub context_class { 'PAGI::Context' }

# Override in subclass to define routes
sub routes {
    my ($self, $r) = @_;
    # Default: no routes
}


sub to_app {
    my ($class) = @_;

    # Create instance that lives for app lifetime
    my $instance = blessed($class) ? $class : $class->new;

    # Build internal router
    load('PAGI::App::Router');
    my $internal_router = PAGI::App::Router->new;

    # Let subclass define routes
    $instance->_build_routes($internal_router);

    my $app = $internal_router->to_app;
    my $state = $instance->{_state};
    my $context_class = $instance->context_class;

    return async sub {
        my ($scope, $receive, $send) = @_;

        # Inject instance state into scope (allows $req->state to work)
        $scope->{state} //= $state;

        # HTTP routes return a response value that bubbles up through the
        # value-flow method middleware; send it once here. Other dispatch
        # outcomes (WS/SSE/mount/404/405) handle their own sending and yield
        # a non-respond-able value.
        my $res = await $app->($scope, $receive, $send);
        if (Scalar::Util::blessed($res) && $res->can('respond')) {
            require PAGI::Context;
            my $ctx = $context_class->new($scope, $receive, $send);
            await $ctx->respond($res);
        }
    };
}

sub _build_routes {
    my ($self, $r) = @_;

    # Create a wrapper router that intercepts route registration
    my $wrapper = PAGI::Endpoint::Router::RouteBuilder->new($self, $r);
    $self->routes($wrapper);
}

# Internal route builder that wraps handlers
package PAGI::Endpoint::Router::RouteBuilder;
$PAGI::Endpoint::Router::RouteBuilder::VERSION = '0.002000';
use strict;
use warnings;
use Future::AsyncAwait;
use Scalar::Util qw(blessed);

sub new {
    my ($class, $endpoint, $router) = @_;
    return bless {
        endpoint => $endpoint,
        router   => $router,
    }, $class;
}

# HTTP methods
sub get     { shift->_add_http_route('GET', @_) }
sub post    { shift->_add_http_route('POST', @_) }
sub put     { shift->_add_http_route('PUT', @_) }
sub patch   { shift->_add_http_route('PATCH', @_) }
sub delete  { shift->_add_http_route('DELETE', @_) }
sub head    { shift->_add_http_route('HEAD', @_) }
sub options { shift->_add_http_route('OPTIONS', @_) }

sub _add_http_route {
    my ($self, $method, $path, @rest) = @_;

    my ($middleware, $handler) = $self->_parse_route_args(@rest);

    # Wrap middleware
    my @wrapped_mw = map { $self->_wrap_middleware($_) } @$middleware;

    # Wrap handler
    my $wrapped = $self->_wrap_http_handler($handler);

    # Register with internal router using the appropriate HTTP method
    my $router_method = lc($method);
    $self->{router}->$router_method($path, @wrapped_mw ? (\@wrapped_mw, $wrapped) : $wrapped);

    return $self;
}

sub _parse_route_args {
    my ($self, @args) = @_;

    if (@args == 2 && ref($args[0]) eq 'ARRAY') {
        return ($args[0], $args[1]);
    }
    elsif (@args == 1) {
        return ([], $args[0]);
    }
    else {
        die "Invalid route arguments";
    }
}

sub _wrap_http_handler {
    my ($self, $handler) = @_;

    my $endpoint = $self->{endpoint};
    my $context_class = $endpoint->context_class;

    # If handler is a string, it's a method name
    if (!ref($handler)) {
        my $method_name = $handler;
        my $method = $endpoint->can($method_name)
            or die "No such method: $method_name in " . ref($endpoint);

        return async sub {
            my ($scope, $receive, $send) = @_;

            require PAGI::Context;

            my $ctx = $context_class->new($scope, $receive, $send);
            my $res = await $endpoint->$method($ctx);
            die "handler did not return a response\n"
                unless Scalar::Util::blessed($res) && $res->can('respond');
            return $res;
        };
    }

    # Already a coderef - wrap it
    return async sub {
        my ($scope, $receive, $send) = @_;

        require PAGI::Context;

        my $ctx = $context_class->new($scope, $receive, $send);
        my $res = await $handler->($ctx);
        die "handler did not return a response\n"
            unless Scalar::Util::blessed($res) && $res->can('respond');
        return $res;
    };
}

sub websocket {
    my ($self, $path, @rest) = @_;

    my ($middleware, $handler) = $self->_parse_route_args(@rest);
    my @wrapped_mw = map { $self->_wrap_middleware($_) } @$middleware;
    my $wrapped = $self->_wrap_websocket_handler($handler);

    $self->{router}->websocket($path, @wrapped_mw ? (\@wrapped_mw, $wrapped) : $wrapped);

    return $self;
}

sub _wrap_websocket_handler {
    my ($self, $handler) = @_;

    my $endpoint = $self->{endpoint};
    my $context_class = $endpoint->context_class;

    if (!ref($handler)) {
        my $method_name = $handler;
        my $method = $endpoint->can($method_name)
            or die "No such method: $method_name";

        return async sub {
            my ($scope, $receive, $send) = @_;

            require PAGI::Context;

            my $ctx = $context_class->new($scope, $receive, $send);

            await $endpoint->$method($ctx);
        };
    }

    return async sub {
        my ($scope, $receive, $send) = @_;

        require PAGI::Context;

        my $ctx = $context_class->new($scope, $receive, $send);

        await $handler->($ctx);
    };
}

sub sse {
    my ($self, $path, @rest) = @_;

    my ($middleware, $handler) = $self->_parse_route_args(@rest);
    my @wrapped_mw = map { $self->_wrap_middleware($_) } @$middleware;
    my $wrapped = $self->_wrap_sse_handler($handler);

    $self->{router}->sse($path, @wrapped_mw ? (\@wrapped_mw, $wrapped) : $wrapped);

    return $self;
}

sub _wrap_sse_handler {
    my ($self, $handler) = @_;

    my $endpoint = $self->{endpoint};
    my $context_class = $endpoint->context_class;

    if (!ref($handler)) {
        my $method_name = $handler;
        my $method = $endpoint->can($method_name)
            or die "No such method: $method_name";

        return async sub {
            my ($scope, $receive, $send) = @_;

            require PAGI::Context;

            my $ctx = $context_class->new($scope, $receive, $send);

            await $endpoint->$method($ctx);
        };
    }

    return async sub {
        my ($scope, $receive, $send) = @_;

        require PAGI::Context;

        my $ctx = $context_class->new($scope, $receive, $send);

        await $handler->($ctx);
    };
}

sub _wrap_middleware {
    my ($self, $mw) = @_;

    my $endpoint = $self->{endpoint};
    my $context_class = $endpoint->context_class;

    # String = endpoint method name → value-flow route middleware.
    if (!ref($mw)) {
        my $method = $endpoint->can($mw)
            or die "No such middleware method: $mw";

        return async sub {
            my ($scope, $receive, $send, $next) = @_;

            require PAGI::Context;

            my $ctx = $context_class->new($scope, $receive, $send);

            my $res = await $endpoint->$method($ctx, $next);
            die "route middleware '$mw' did not return a response\n"
                unless blessed($res) && $res->can('respond');
            return $res;
        };
    }

    # Coderefs/objects are standard (event) middleware: they belong at the
    # outer layer (App::Router mount/group), not inside an Endpoint route's
    # value-flow chain.
    die "Standard middleware (coderef/object) belong at the mount or group "
      . "level, not in an Endpoint route's middleware list; route middleware "
      . "are value-flow endpoint methods that return a response.\n";
}

# Pass through mount to internal router
sub mount {
    my ($self, @args) = @_;
    $self->{router}->mount(@args);
    return $self;
}

# Pass through name() to internal router
sub name {
    my ($self, $name) = @_;
    $self->{router}->name($name);
    return $self;
}

# Pass through as() to internal router
sub as {
    my ($self, $namespace) = @_;
    $self->{router}->as($namespace);
    return $self;
}

# Pass through uri_for() to internal router
sub uri_for {
    my ($self, @args) = @_;
    return $self->{router}->uri_for(@args);
}

# Pass through named_routes() to internal router
sub named_routes {
    my ($self) = @_;
    return $self->{router}->named_routes;
}

1;

__END__