File Coverage

blib/lib/PAGI/Middleware.pm

Criterion	Covered	Total	%
statement	34	39	87.1
branch	3	6	50.0
condition	2	4	50.0
subroutine	10	11	90.9
pod	6	6	100.0
total	55	66	83.3

package PAGI::Middleware;
$PAGI::Middleware::VERSION = '0.002000';
use strict;
use warnings;
use Future::AsyncAwait;

=head1 NAME

PAGI::Middleware - Base class for PAGI middleware

=head1 SYNOPSIS

    # Create a custom middleware
    package My::Middleware;
    use parent 'PAGI::Middleware';

    sub wrap {
        my ($self, $app) = @_;

        return async sub  {
        my ($scope, $receive, $send) = @_;
            # Modify scope for inner app
            my $modified_scope = $self->modify_scope($scope, {
                custom_key => 'custom_value',
            });

            # Call inner app with modified scope
            await $app->($modified_scope, $receive, $send);
        };
    }

    # Use the builder DSL
    use PAGI::Middleware::Builder;

    my $app = builder {
        enable 'My::Middleware', option => 'value';
        enable_if { $_[0]->{path} =~ m{^/api/} } 'RateLimit', limit => 100;
        mount '/static' => $static_app;
        $my_app;
    };

=head1 DESCRIPTION

PAGI::Middleware provides a base class for implementing middleware that wraps
PAGI applications. Middleware can modify the request scope, intercept responses,
or perform cross-cutting concerns like logging, authentication, or compression.

=head1 METHODS

=head2 new

    my $middleware = PAGI::Middleware->new(%config);

Create a new middleware instance. Configuration options are stored and
accessible via C<$self-E{config}>.

=cut

sub new {
    my ($class, %config) = @_;

    my $self = bless {
        config => \%config,
    }, $class;
    $self->_init(\%config);
    return $self;
}

=head2 _init

    $self->_init(\%config);

Hook for subclasses to perform initialization. Called by new().
Default implementation does nothing.

=cut

sub _init {
    my ($self, $config) = @_;

    # Subclasses can override
}

=head2 wrap

    my $wrapped_app = $middleware->wrap($app);

Wrap a PAGI application. Returns a new async sub that handles
the middleware logic. Subclasses MUST override this method.

=cut

sub wrap {
    my ($self, $app) = @_;

    die "Subclass must implement wrap()";
}

=head2 modify_scope

    my $new_scope = $self->modify_scope($scope, \%additions);

Return a new scope -- a shallow copy of C<$scope> with C<%additions> merged in --
B. This is the supported way to pass extra data to
inner apps, and the canonical middleware in this distribution use it.

Why copy instead of writing C<< $scope->{key} = ... >> directly? Middleware form a
stack, and the scope you are handed is shared with the layers around you. Mutating
it in place lets your change leak B to parent and sibling layers (and, for
a long-lived WebSocket scope, persist across every event on the connection).
Copying keeps your additions B -- seen by the inner app you call,
invisible to everyone above.

The copy is B on purpose. Top-level keys you add are private to the new
scope, but values that are B -- the C object, the
lifespan C namespace, the stash -- are shared, so the inner app still sees
the same connection state and shared objects. A deep copy would sever those. One
corollary worth knowing: a plain B set as a top-level scope key does not
propagate back to outer layers, so to share mutable state across layers you mutate
B (see L). The full model -- and why it works
this way -- is in L.

=cut

sub modify_scope {
    my ($self, $scope, $additions) = @_;
    $additions //= {};

    return { %$scope, %$additions };
}

=head2 intercept_send

    my $wrapped_send = $self->intercept_send($send, \&interceptor);

Wrap the $send callback to intercept outgoing events.
The interceptor is called with ($event, $original_send) and should
return a Future.

    my $wrapped_send = $self->intercept_send($send, async sub  {
        my ($event, $original_send) = @_;
        if ($event->{type} eq 'http.response.start') {
            # Modify headers
            push @{$event->{headers}}, ['x-custom', 'value'];
        }
        await $original_send->($event);
    });

=cut

sub intercept_send {
    my ($self, $send, $interceptor) = @_;

    return async sub  {
        my ($event) = @_;
        await $interceptor->($event, $send);
    };
}

=head2 buffer_request_body

    my ($body, $final_event) = await $self->buffer_request_body($receive);

Collect all request body chunks into a single string.
Returns the complete body and the final http.request event.

=cut

async sub buffer_request_body {
    my ($self, $receive) = @_;

    my $body = '';
    my $event;

    while (1) {
        $event = await $receive->();

        if ($event->{type} eq 'http.request') {
            $body .= $event->{body} // '';
            last unless $event->{more};
        } elsif ($event->{type} eq 'http.disconnect') {
            last;
        }
    }

    return ($body, $event);
}

=head2 call

    await $middleware->call($scope, $receive, $send, $app);

Convenience method to invoke the middleware with an app.
Equivalent to:

    my $wrapped = $middleware->wrap($app);
    await $wrapped->($scope, $receive, $send);

=cut

async sub call {
    my ($self, $scope, $receive, $send, $app) = @_;

    my $wrapped = $self->wrap($app);
    await $wrapped->($scope, $receive, $send);
}

1;

__END__