File Coverage

blib/lib/PAGI/Endpoint/Router.pm

Criterion	Covered	Total	%
statement	148	182	81.3
branch	21	32	65.6
condition	4	6	66.6
subroutine	36	48	75.0
pod	4	5	80.0
total	213	273	78.0

package PAGI::Endpoint::Router;
$PAGI::Endpoint::Router::VERSION = '0.002001';
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};

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

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

        # HTTP route apps respond at their own boundary (via _build_value_app).
        # WS/SSE/mount/404/405 all handle their own sending.
        await $app->($scope, $receive, $send);
    };
}

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.002001';
use strict;
use warnings;
use Future::AsyncAwait;
use Carp qw(croak);
use PAGI::Utils qw(is_response);

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);

    my $app = $self->_build_value_app($middleware, $handler);

    my $router_method = lc($method);
    $self->{router}->$router_method($path, $app);

    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 _build_value_app {
    my ($self, $method_mw, $handler) = @_;

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

    my @mw = map { $self->_resolve_value_mw($_) } @$method_mw;   # async sub($ctx,$next)->Response
    my $handler_code = $self->_resolve_handler($handler);         # async sub($ctx)->Response

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

        require PAGI::Context;
        my $ctx = $ctx_class->new($scope, $receive, $send);

        my $next = async sub { await $handler_code->($ctx) };
        for my $m (reverse @mw) {
            my $inner = $next;
            $next = async sub { await $m->($ctx, $inner) };
        }

        await $ctx->respond(await $next->());
    };
}

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

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

    if (!ref($handler)) {
        my $method = $endpoint->can($handler)
            or die "No such method: $handler in " . ref($endpoint);
        return async sub {
            my ($ctx) = @_;
            my $res = await $endpoint->$method($ctx);
            croak "handler did not return a response"
                unless is_response($res);
            return $res;
        };
    }

    return async sub {
        my ($ctx) = @_;
        my $res = await $handler->($ctx);
        croak "handler did not return a response"
            unless is_response($res);
        return $res;
    };
}

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

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

    die "WebSocket routes do not support route-level middleware; "
      . "apply event middleware at the mount or group level\n"
        if @$middleware;

    my $wrapped = $self->_wrap_websocket_handler($handler);

    $self->{router}->websocket($path, $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);

    die "SSE routes do not support route-level middleware; "
      . "apply event middleware at the mount or group level\n"
        if @$middleware;

    my $wrapped = $self->_wrap_sse_handler($handler);

    $self->{router}->sse($path, $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 _resolve_value_mw {
    my ($self, $mw) = @_;

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

    # 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 ($ctx, $next) = @_;
            my $res = await $endpoint->$method($ctx, $next);
            croak "route middleware '$mw' did not return a response"
                unless is_response($res);
            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__