File Coverage

blib/lib/PAGI/Lifespan.pm

Criterion	Covered	Total	%
statement	87	88	98.8
branch	26	32	81.2
condition	21	35	60.0
subroutine	14	15	93.3
pod	4	9	44.4
total	152	179	84.9

package PAGI::Lifespan;
$PAGI::Lifespan::VERSION = '0.002000';
use strict;
use warnings;
use Future::AsyncAwait;
use Carp qw(croak);
use PAGI::Utils ();


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

    my $app = delete $args{app};
    $app = PAGI::Utils::to_app($app) if defined $app;

    my @handlers;
    push @handlers, {
        startup  => $args{startup},
        shutdown => $args{shutdown},
    } if $args{startup} || $args{shutdown};

    return bless {
        app       => $app,
        _handlers => \@handlers,
        _state    => undef,
    }, $class;
}

sub state { shift->{_state} }

sub on_startup {
    my ($self, $cb) = @_;
    return $self->register(startup => $cb);
}

sub on_shutdown {
    my ($self, $cb) = @_;
    return $self->register(shutdown => $cb);
}

sub register {
    my ($self, %args) = @_;
    return $self unless $args{startup} || $args{shutdown};
    push @{$self->{_handlers}}, {
        startup  => $args{startup},
        shutdown => $args{shutdown},
    };
    return $self;
}

sub for_scope {
    my ($class, $scope) = @_;
    croak "scope is required" unless $scope && ref($scope) eq 'HASH';
    return $scope->{'pagi.lifespan.manager'} //= $class->new;
}

sub wrap {
    my ($class, $app, %args) = @_;

    my $self = $class->new(app => $app, %args);
    return $self->to_app;
}

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

    my $app = $self->{app};
    croak "PAGI::Lifespan->to_app requires an app" unless $app;

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

        my $type = $scope->{type} // '';

        if ($type eq 'lifespan') {
            $scope->{'pagi.lifespan.manager'} //= $self;
            $scope->{state} //= {};
            await $app->($scope, $receive, $send);
            return await $self->handle($scope, $receive, $send);
        }

        my $inner_scope = { %$scope };
        $inner_scope->{state} //= ($self->{_state} // {});
        $self->{_state} = $inner_scope->{state};

        await $app->($inner_scope, $receive, $send);
    };

    return $wrapper;
}

async sub handle {
    my ($self, $scope, $receive, $send) = @_;
    return 0 unless $scope && ($scope->{type} // '') eq 'lifespan';
    return 0 if $scope->{'pagi.lifespan.handled'};
    $scope->{'pagi.lifespan.handled'} = 1;

    my @handlers;
    if (my $extra = $scope->{'pagi.lifespan.handlers'}) {
        push @handlers, @$extra;
    }
    push @handlers, @{$self->{_handlers} // []};

    my $state = $scope->{state} //= {};
    $self->{_state} = $state;

    while (1) {
        my $msg = await $receive->();
        my $type = $msg->{type} // '';

        if ($type eq 'lifespan.startup') {
            for my $handler (@handlers) {
                next unless $handler->{startup};
                eval { await $handler->{startup}->($state) };
                if ($@) {
                    await $send->({
                        type    => 'lifespan.startup.failed',
                        message => "$@",
                    });
                    return;
                }
            }
            await $send->({ type => 'lifespan.startup.complete' });
        }
        elsif ($type eq 'lifespan.shutdown') {
            # Run every shutdown handler (best-effort cleanup: one failing
            # handler must not prevent the others from releasing resources),
            # collecting any errors so they can be reported rather than swallowed.
            my @errors;
            for my $handler (reverse @handlers) {
                next unless $handler->{shutdown};
                eval { await $handler->{shutdown}->($state) };
                push @errors, "$@" if $@;
            }
            if (@errors) {
                await $send->({
                    type    => 'lifespan.shutdown.failed',
                    message => join("\n", @errors),
                });
            }
            else {
                await $send->({ type => 'lifespan.shutdown.complete' });
            }
            return 1;
        }
    }
}

1;

__END__