| 1 | package PAGI::Context; | ||||||||||||||||||||||||||||||||||
| 2 | 28 | $PAGI::Context::VERSION = '0.002002'; | |||||||||||||||||||||||||||||||||
| 3 | 28 | ▶ | use strict; | ||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||
| 4 | 28 | ▶ | use warnings; | ||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||
| 5 | 28 | ▶ | use Carp qw(croak); | ||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||
| 6 | 28 | ▶ | use Scalar::Util qw(blessed); | ||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||
| 7 | 28 | ▶ | use Future::AsyncAwait; | ||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||
| 8 | 28 | ▶ | use Future; | ||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||
| 9 | 28 | ▶ | use PAGI::Utils::SecureCompare qw(secure_compare); | ||||||||||||||||||||||||||||||||
|
Subroutine
BEGIN: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||
| 10 | |||||||||||||||||||||||||||||||||||
| 11 | =encoding UTF-8 | ||||||||||||||||||||||||||||||||||
| 12 | |||||||||||||||||||||||||||||||||||
| 13 | =head1 NAME | ||||||||||||||||||||||||||||||||||
| 14 | |||||||||||||||||||||||||||||||||||
| 15 | PAGI::Context - Per-request context with protocol-specific subclasses | ||||||||||||||||||||||||||||||||||
| 16 | |||||||||||||||||||||||||||||||||||
| 17 | =head1 SYNOPSIS | ||||||||||||||||||||||||||||||||||
| 18 | |||||||||||||||||||||||||||||||||||
| 19 | use PAGI::Context; | ||||||||||||||||||||||||||||||||||
| 20 | use Future::AsyncAwait; | ||||||||||||||||||||||||||||||||||
| 21 | |||||||||||||||||||||||||||||||||||
| 22 | # Factory returns the right subclass based on scope type | ||||||||||||||||||||||||||||||||||
| 23 | my $ctx = PAGI::Context->new($scope, $receive, $send); | ||||||||||||||||||||||||||||||||||
| 24 | |||||||||||||||||||||||||||||||||||
| 25 | # Shared methods (all protocol types) | ||||||||||||||||||||||||||||||||||
| 26 | my $type = $ctx->type; # 'http', 'websocket', 'sse' | ||||||||||||||||||||||||||||||||||
| 27 | my $path = $ctx->path; | ||||||||||||||||||||||||||||||||||
| 28 | my $stash = $ctx->stash; # PAGI::Stash | ||||||||||||||||||||||||||||||||||
| 29 | my $session = $ctx->session; # PAGI::Session | ||||||||||||||||||||||||||||||||||
| 30 | |||||||||||||||||||||||||||||||||||
| 31 | # WebSocket context - protocol ops directly on $ctx | ||||||||||||||||||||||||||||||||||
| 32 | await $ctx->accept; | ||||||||||||||||||||||||||||||||||
| 33 | await $ctx->send_json({ msg => 'hello' }); | ||||||||||||||||||||||||||||||||||
| 34 | my $text = await $ctx->receive_text; | ||||||||||||||||||||||||||||||||||
| 35 | await $ctx->close; | ||||||||||||||||||||||||||||||||||
| 36 | |||||||||||||||||||||||||||||||||||
| 37 | # SSE context - same idea | ||||||||||||||||||||||||||||||||||
| 38 | await $ctx->send_event(event => 'update', data => $payload); | ||||||||||||||||||||||||||||||||||
| 39 | await $ctx->keepalive(25); | ||||||||||||||||||||||||||||||||||
| 40 | |||||||||||||||||||||||||||||||||||
| 41 | # Event dispatcher - works on any protocol type | ||||||||||||||||||||||||||||||||||
| 42 | my $reason = await $ctx | ||||||||||||||||||||||||||||||||||
| 43 | ->on('websocket.receive', async sub { ... }) | ||||||||||||||||||||||||||||||||||
| 44 | ->on('chat.message', async sub { ... }) | ||||||||||||||||||||||||||||||||||
| 45 | ->on_error(sub { ... }) | ||||||||||||||||||||||||||||||||||
| 46 | ->run; # returns 'disconnect', 'stop', or 'error' | ||||||||||||||||||||||||||||||||||
| 47 | |||||||||||||||||||||||||||||||||||
| 48 | # Underlying protocol objects still available | ||||||||||||||||||||||||||||||||||
| 49 | my $ws = $ctx->websocket; # PAGI::WebSocket (WS only) | ||||||||||||||||||||||||||||||||||
| 50 | my $sse = $ctx->sse; # PAGI::SSE (SSE only) | ||||||||||||||||||||||||||||||||||
| 51 | my $req = $ctx->request; # PAGI::Request (HTTP only) | ||||||||||||||||||||||||||||||||||
| 52 | my $res = $ctx->response; # PAGI::Response (HTTP only) | ||||||||||||||||||||||||||||||||||
| 53 | |||||||||||||||||||||||||||||||||||
| 54 | =head1 DESCRIPTION | ||||||||||||||||||||||||||||||||||
| 55 | |||||||||||||||||||||||||||||||||||
| 56 | PAGI::Context is a factory and base class that provides a unified entry | ||||||||||||||||||||||||||||||||||
| 57 | point for per-request context. Calling C<< PAGI::Context->new(...) >> | ||||||||||||||||||||||||||||||||||
| 58 | inspects C<< $scope->{type} >> and returns the appropriate subclass: | ||||||||||||||||||||||||||||||||||
| 59 | L<PAGI::Context::HTTP>, L<PAGI::Context::WebSocket>, or | ||||||||||||||||||||||||||||||||||
| 60 | L<PAGI::Context::SSE>. | ||||||||||||||||||||||||||||||||||
| 61 | |||||||||||||||||||||||||||||||||||
| 62 | Shared methods (scope accessors, stash, session, event dispatcher) live | ||||||||||||||||||||||||||||||||||
| 63 | on the base class. Protocol-specific methods are delegated from | ||||||||||||||||||||||||||||||||||
| 64 | subclasses so you can use C<$ctx> as your single object: | ||||||||||||||||||||||||||||||||||
| 65 | |||||||||||||||||||||||||||||||||||
| 66 | # Instead of: | ||||||||||||||||||||||||||||||||||
| 67 | my $ws = $ctx->websocket; | ||||||||||||||||||||||||||||||||||
| 68 | await $ws->send_json($data); # closes over $ws in every handler | ||||||||||||||||||||||||||||||||||
| 69 | |||||||||||||||||||||||||||||||||||
| 70 | # Just do: | ||||||||||||||||||||||||||||||||||
| 71 | await $ctx->send_json($data); # $ctx is already in scope | ||||||||||||||||||||||||||||||||||
| 72 | |||||||||||||||||||||||||||||||||||
| 73 | =head2 Protocol Shape | ||||||||||||||||||||||||||||||||||
| 74 | |||||||||||||||||||||||||||||||||||
| 75 | Each context type has a different set of available methods. Calling a | ||||||||||||||||||||||||||||||||||
| 76 | method that belongs to a different protocol type raises a standard Perl | ||||||||||||||||||||||||||||||||||
| 77 | C<Can't locate object method> error. | ||||||||||||||||||||||||||||||||||
| 78 | |||||||||||||||||||||||||||||||||||
| 79 | Method HTTP WebSocket SSE | ||||||||||||||||||||||||||||||||||
| 80 | ────────────────── ────── ────────── ────── | ||||||||||||||||||||||||||||||||||
| 81 | request, response yes - - | ||||||||||||||||||||||||||||||||||
| 82 | text, html, json yes - - | ||||||||||||||||||||||||||||||||||
| 83 | redirect yes - - | ||||||||||||||||||||||||||||||||||
| 84 | method yes - - | ||||||||||||||||||||||||||||||||||
| 85 | accept - yes - | ||||||||||||||||||||||||||||||||||
| 86 | send_text - yes - | ||||||||||||||||||||||||||||||||||
| 87 | send_bytes - yes - | ||||||||||||||||||||||||||||||||||
| 88 | send_json - yes yes | ||||||||||||||||||||||||||||||||||
| 89 | send - - yes | ||||||||||||||||||||||||||||||||||
| 90 | send_event - - yes | ||||||||||||||||||||||||||||||||||
| 91 | send_comment - - yes | ||||||||||||||||||||||||||||||||||
| 92 | start - - yes | ||||||||||||||||||||||||||||||||||
| 93 | close - yes yes | ||||||||||||||||||||||||||||||||||
| 94 | query / query_param - yes(query) yes(query_param) | ||||||||||||||||||||||||||||||||||
| 95 | is_connected base* WS override - | ||||||||||||||||||||||||||||||||||
| 96 | is_closed - yes yes | ||||||||||||||||||||||||||||||||||
| 97 | is_started - - yes | ||||||||||||||||||||||||||||||||||
| 98 | keepalive - yes yes | ||||||||||||||||||||||||||||||||||
| 99 | each_text, etc. - yes - | ||||||||||||||||||||||||||||||||||
| 100 | each, every - - yes | ||||||||||||||||||||||||||||||||||
| 101 | |||||||||||||||||||||||||||||||||||
| 102 | *is_connected on WebSocket contexts checks WS handshake state, | ||||||||||||||||||||||||||||||||||
| 103 | not the TCP-level pagi.connection that the base class uses. | ||||||||||||||||||||||||||||||||||
| 104 | |||||||||||||||||||||||||||||||||||
| 105 | See L<PAGI::Context::WebSocket> and L<PAGI::Context::SSE> for the | ||||||||||||||||||||||||||||||||||
| 106 | full method reference on each subclass. | ||||||||||||||||||||||||||||||||||
| 107 | |||||||||||||||||||||||||||||||||||
| 108 | =head1 EXTENSIBILITY | ||||||||||||||||||||||||||||||||||
| 109 | |||||||||||||||||||||||||||||||||||
| 110 | Override C<_type_map> to add or replace protocol types: | ||||||||||||||||||||||||||||||||||
| 111 | |||||||||||||||||||||||||||||||||||
| 112 | package MyApp::Context; | ||||||||||||||||||||||||||||||||||
| 113 | our @ISA = ('PAGI::Context'); | ||||||||||||||||||||||||||||||||||
| 114 | |||||||||||||||||||||||||||||||||||
| 115 | sub _type_map { | ||||||||||||||||||||||||||||||||||
| 116 | my ($class) = @_; | ||||||||||||||||||||||||||||||||||
| 117 | return { | ||||||||||||||||||||||||||||||||||
| 118 | %{ $class->SUPER::_type_map }, | ||||||||||||||||||||||||||||||||||
| 119 | grpc => 'MyApp::Context::GRPC', | ||||||||||||||||||||||||||||||||||
| 120 | }; | ||||||||||||||||||||||||||||||||||
| 121 | } | ||||||||||||||||||||||||||||||||||
| 122 | |||||||||||||||||||||||||||||||||||
| 123 | Override C<_resolve_class> for custom resolution logic beyond the type map. | ||||||||||||||||||||||||||||||||||
| 124 | |||||||||||||||||||||||||||||||||||
| 125 | =head1 CONSTRUCTOR | ||||||||||||||||||||||||||||||||||
| 126 | |||||||||||||||||||||||||||||||||||
| 127 | =head2 new | ||||||||||||||||||||||||||||||||||
| 128 | |||||||||||||||||||||||||||||||||||
| 129 | my $ctx = PAGI::Context->new($scope, $receive, $send); | ||||||||||||||||||||||||||||||||||
| 130 | |||||||||||||||||||||||||||||||||||
| 131 | Factory constructor. Returns a subclass instance based on | ||||||||||||||||||||||||||||||||||
| 132 | C<< $scope->{type} >>. Defaults to HTTP if type is missing or unknown. | ||||||||||||||||||||||||||||||||||
| 133 | |||||||||||||||||||||||||||||||||||
| 134 | =cut | ||||||||||||||||||||||||||||||||||
| 135 | |||||||||||||||||||||||||||||||||||
| 136 | 233 | ▶ | sub new { | ||||||||||||||||||||||||||||||||
|
Subroutine
new: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 137 | 233 | my ($class, $scope, $receive, $send) = @_; | |||||||||||||||||||||||||||||||||
| 138 | 233 | my $subclass = $class->_resolve_class($scope); | |||||||||||||||||||||||||||||||||
| 139 | 233 | return bless { | |||||||||||||||||||||||||||||||||
| 140 | scope => $scope, | ||||||||||||||||||||||||||||||||||
| 141 | receive => $receive, | ||||||||||||||||||||||||||||||||||
| 142 | send => $send, | ||||||||||||||||||||||||||||||||||
| 143 | }, $subclass; | ||||||||||||||||||||||||||||||||||
| 144 | } | ||||||||||||||||||||||||||||||||||
| 145 | |||||||||||||||||||||||||||||||||||
| 146 | =head1 CLASS METHODS | ||||||||||||||||||||||||||||||||||
| 147 | |||||||||||||||||||||||||||||||||||
| 148 | =head2 _type_map | ||||||||||||||||||||||||||||||||||
| 149 | |||||||||||||||||||||||||||||||||||
| 150 | my $map = PAGI::Context->_type_map; | ||||||||||||||||||||||||||||||||||
| 151 | |||||||||||||||||||||||||||||||||||
| 152 | Returns a hashref mapping scope type strings to subclass package names. | ||||||||||||||||||||||||||||||||||
| 153 | Override in a subclass to add or replace protocol types. | ||||||||||||||||||||||||||||||||||
| 154 | |||||||||||||||||||||||||||||||||||
| 155 | =cut | ||||||||||||||||||||||||||||||||||
| 156 | |||||||||||||||||||||||||||||||||||
| 157 | 240 | ▶ | sub _type_map { | ||||||||||||||||||||||||||||||||
|
Subroutine
_type_map: called CC=1 SCAR=0.0
| |||||||||||||||||||||||||||||||||||
| 158 | return { | ||||||||||||||||||||||||||||||||||
| 159 | 240 | http => 'PAGI::Context::HTTP', | |||||||||||||||||||||||||||||||||
| 160 | websocket => 'PAGI::Context::WebSocket', | ||||||||||||||||||||||||||||||||||
| 161 | sse => 'PAGI::Context::SSE', | ||||||||||||||||||||||||||||||||||
| 162 | }; | ||||||||||||||||||||||||||||||||||
| 163 | } | ||||||||||||||||||||||||||||||||||
| 164 | |||||||||||||||||||||||||||||||||||
| 165 | =head2 _resolve_class | ||||||||||||||||||||||||||||||||||
| 166 | |||||||||||||||||||||||||||||||||||
| 167 | my $class = PAGI::Context->_resolve_class($scope); | ||||||||||||||||||||||||||||||||||
| 168 | |||||||||||||||||||||||||||||||||||
| 169 | Resolves the scope to a subclass package name. Looks up | ||||||||||||||||||||||||||||||||||
| 170 | C<< $scope->{type} >> in C<_type_map>; defaults to the C<http> mapping | ||||||||||||||||||||||||||||||||||
| 171 | if the type is missing or unknown. Override for custom resolution logic. | ||||||||||||||||||||||||||||||||||
| 172 | |||||||||||||||||||||||||||||||||||
| 173 | =cut | ||||||||||||||||||||||||||||||||||
| 174 | |||||||||||||||||||||||||||||||||||
| 175 | 237 | ▶ | sub _resolve_class { | ||||||||||||||||||||||||||||||||
|
Subroutine
_resolve_class: called CC=3 SCAR=11.0
| |||||||||||||||||||||||||||||||||||
| 176 | 237 | my ($class, $scope) = @_; | |||||||||||||||||||||||||||||||||
| 177 | 237 | ▶ | my $type = $scope->{type} // 'http'; | ||||||||||||||||||||||||||||||||
|
Condition100%2/2
$scope->{"type"} // "http"
MC/DC100%1/1
$scope->{"type"} // "http"
$scope->{"type"}
Truth table100%2/2
A
A= $scope->{"type"}
| |||||||||||||||||||||||||||||||||||
| 178 | 237 | ▶ | return $class->_type_map->{$type} // $class->_type_map->{http}; | ||||||||||||||||||||||||||||||||
|
Condition66%2/3
$class->_type_map->{$type} // $class->_type_map->{"http"}
MC/DC0%0/2
$class->_type_map->{$type} // $class->_type_map->{"http"}
$class->_type_map->{$type}
$class->_type_map->{"http"}
Truth table66%2/3
A // B
A= $class->_type_map->{$type}B= $class->_type_map->{"http"}
| |||||||||||||||||||||||||||||||||||
| 179 | } | ||||||||||||||||||||||||||||||||||
| 180 | |||||||||||||||||||||||||||||||||||
| 181 | =head1 METHODS | ||||||||||||||||||||||||||||||||||
| 182 | |||||||||||||||||||||||||||||||||||
| 183 | =head2 Scope Accessors | ||||||||||||||||||||||||||||||||||
| 184 | |||||||||||||||||||||||||||||||||||
| 185 | $ctx->scope; # raw $scope hashref | ||||||||||||||||||||||||||||||||||
| 186 | $ctx->type; # $scope->{type} | ||||||||||||||||||||||||||||||||||
| 187 | $ctx->path; # $scope->{path} | ||||||||||||||||||||||||||||||||||
| 188 | $ctx->raw_path; # $scope->{raw_path} // $scope->{path} | ||||||||||||||||||||||||||||||||||
| 189 | $ctx->query_string; # $scope->{query_string} // '' | ||||||||||||||||||||||||||||||||||
| 190 | $ctx->scheme; # $scope->{scheme} // 'http' | ||||||||||||||||||||||||||||||||||
| 191 | $ctx->client; # $scope->{client} | ||||||||||||||||||||||||||||||||||
| 192 | $ctx->server; # $scope->{server} | ||||||||||||||||||||||||||||||||||
| 193 | $ctx->headers; # $scope->{headers} arrayref of [name, value] | ||||||||||||||||||||||||||||||||||
| 194 | |||||||||||||||||||||||||||||||||||
| 195 | =cut | ||||||||||||||||||||||||||||||||||
| 196 | |||||||||||||||||||||||||||||||||||
| 197 | 3 | ▶ | sub scope { shift->{scope} } | ||||||||||||||||||||||||||||||||
|
Subroutine
scope: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 198 | 51 | ▶ | sub type { shift->{scope}{type} } | ||||||||||||||||||||||||||||||||
|
Subroutine
type: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 199 | 4 | ▶ | sub path { shift->{scope}{path} } | ||||||||||||||||||||||||||||||||
|
Subroutine
path: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 200 | 3 | ▶ | sub raw_path { my $s = shift; $s->{scope}{raw_path} // $s->{scope}{path} } | ||||||||||||||||||||||||||||||||
|
Subroutine
raw_path: called CC=2 SCAR=6.9
Pod
undocumented
Condition100%3/3
$s->{"scope"}{"raw_path"} // $s->{"scope"}{"path"}
MC/DC100%2/2
$s->{"scope"}{"raw_path"} // $s->{"scope"}{"path"}
$s->{"scope"}{"raw_path"}
$s->{"scope"}{"path"}
Truth table100%3/3
A // B
A= $s->{"scope"}{"raw_path"}B= $s->{"scope"}{"path"}
| |||||||||||||||||||||||||||||||||||
| 201 | 2 | ▶ | sub query_string { shift->{scope}{query_string} // '' } | ||||||||||||||||||||||||||||||||
|
Subroutine
query_string: called CC=2 SCAR=6.9
Pod
undocumented
Condition100%2/2
+(shift())->{"scope"}{"query_string"} // ""
MC/DC100%1/1
+(shift())->{"scope"}{"query_string"} // ""
+(shift())->{"scope"}{"query_string"}
Truth table100%2/2
A
A= +(shift())->{"scope"}{"query_string"}
| |||||||||||||||||||||||||||||||||||
| 202 | 2 | ▶ | sub scheme { shift->{scope}{scheme} // 'http' } | ||||||||||||||||||||||||||||||||
|
Subroutine
scheme: called CC=2 SCAR=6.9
Pod
undocumented
Condition100%2/2
+(shift())->{"scope"}{"scheme"} // "http"
MC/DC100%1/1
+(shift())->{"scope"}{"scheme"} // "http"
+(shift())->{"scope"}{"scheme"}
Truth table100%2/2
A
A= +(shift())->{"scope"}{"scheme"}
| |||||||||||||||||||||||||||||||||||
| 203 | 1 | ▶ | sub client { shift->{scope}{client} } | ||||||||||||||||||||||||||||||||
|
Subroutine
client: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 204 | 1 | ▶ | sub server { shift->{scope}{server} } | ||||||||||||||||||||||||||||||||
|
Subroutine
server: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 205 | 1 | ▶ | sub headers { shift->{scope}{headers} } | ||||||||||||||||||||||||||||||||
|
Subroutine
headers: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 206 | |||||||||||||||||||||||||||||||||||
| 207 | =head2 assert_http, assert_websocket, assert_sse | ||||||||||||||||||||||||||||||||||
| 208 | |||||||||||||||||||||||||||||||||||
| 209 | my $ctx = PAGI::Context->new($scope, $receive, $send)->assert_http; | ||||||||||||||||||||||||||||||||||
| 210 | |||||||||||||||||||||||||||||||||||
| 211 | Type guards for handlers that support only one protocol. Each returns the | ||||||||||||||||||||||||||||||||||
| 212 | context unchanged when C<< $ctx->type >> matches, and C<croak>s with a clear | ||||||||||||||||||||||||||||||||||
| 213 | message otherwise — turning a forgotten scope-type check into a loud, early | ||||||||||||||||||||||||||||||||||
| 214 | failure instead of a confusing C<Can't locate object method> deeper in the | ||||||||||||||||||||||||||||||||||
| 215 | handler. Because they chain off the polymorphic L</new>, the whole gate is one | ||||||||||||||||||||||||||||||||||
| 216 | line: | ||||||||||||||||||||||||||||||||||
| 217 | |||||||||||||||||||||||||||||||||||
| 218 | my $ctx = PAGI::Context->new(@_)->assert_http; # croaks unless the scope is http | ||||||||||||||||||||||||||||||||||
| 219 | |||||||||||||||||||||||||||||||||||
| 220 | They are named C<assert_*> rather than C<< PAGI::Context->http >> / | ||||||||||||||||||||||||||||||||||
| 221 | C<< ->websocket >> because C<websocket> and C<sse> are already instance methods | ||||||||||||||||||||||||||||||||||
| 222 | that return the underlying channel objects. | ||||||||||||||||||||||||||||||||||
| 223 | |||||||||||||||||||||||||||||||||||
| 224 | =cut | ||||||||||||||||||||||||||||||||||
| 225 | |||||||||||||||||||||||||||||||||||
| 226 | 3 | ▶ | sub assert_http { $_[0]->_assert_type('http') } | ||||||||||||||||||||||||||||||||
|
Subroutine
assert_http: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 227 | 2 | ▶ | sub assert_websocket { $_[0]->_assert_type('websocket') } | ||||||||||||||||||||||||||||||||
|
Subroutine
assert_websocket: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 228 | 2 | ▶ | sub assert_sse { $_[0]->_assert_type('sse') } | ||||||||||||||||||||||||||||||||
|
Subroutine
assert_sse: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 229 | |||||||||||||||||||||||||||||||||||
| 230 | 7 | ▶ | sub _assert_type { | ||||||||||||||||||||||||||||||||
|
Subroutine
_assert_type: called CC=3 SCAR=11.0
| |||||||||||||||||||||||||||||||||||
| 231 | 7 | my ($self, $want) = @_; | |||||||||||||||||||||||||||||||||
| 232 | 7 | ▶ | my $got = $self->type // '(none)'; | ||||||||||||||||||||||||||||||||
|
Condition50%1/2
$self->type // "(none)"
MC/DC0%0/1
$self->type // "(none)"
$self->type
Truth table50%1/2
A
A= $self->type
| |||||||||||||||||||||||||||||||||||
| 233 | 7 | ▶ | croak "expected a '$want' context, got a '$got' context" unless $got eq $want; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 234 | 4 | return $self; | |||||||||||||||||||||||||||||||||
| 235 | } | ||||||||||||||||||||||||||||||||||
| 236 | |||||||||||||||||||||||||||||||||||
| 237 | =head2 Path Parameters | ||||||||||||||||||||||||||||||||||
| 238 | |||||||||||||||||||||||||||||||||||
| 239 | my $params = $ctx->path_params; # hashref | ||||||||||||||||||||||||||||||||||
| 240 | my $id = $ctx->path_param('id'); # strict: dies if missing | ||||||||||||||||||||||||||||||||||
| 241 | my $id = $ctx->path_param('id', strict => 0); # returns undef | ||||||||||||||||||||||||||||||||||
| 242 | |||||||||||||||||||||||||||||||||||
| 243 | C<path_params> returns the C<< $scope->{path_params} >> hashref (set by | ||||||||||||||||||||||||||||||||||
| 244 | the router), defaulting to C<{}> if not present. | ||||||||||||||||||||||||||||||||||
| 245 | |||||||||||||||||||||||||||||||||||
| 246 | C<path_param> returns a single parameter by name. By default it dies if | ||||||||||||||||||||||||||||||||||
| 247 | the key is not found (strict mode). Pass C<< strict => 0 >> to return | ||||||||||||||||||||||||||||||||||
| 248 | C<undef> for missing keys instead. | ||||||||||||||||||||||||||||||||||
| 249 | |||||||||||||||||||||||||||||||||||
| 250 | =cut | ||||||||||||||||||||||||||||||||||
| 251 | |||||||||||||||||||||||||||||||||||
| 252 | 8 | ▶ | sub path_params { | ||||||||||||||||||||||||||||||||
|
Subroutine
path_params: called CC=2 SCAR=6.9
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 253 | 8 | my ($self) = @_; | |||||||||||||||||||||||||||||||||
| 254 | 8 | ▶ | return $self->{scope}{path_params} // {}; | ||||||||||||||||||||||||||||||||
|
Condition100%2/2
$self->{"scope"}{"path_params"} // {}
MC/DC100%1/1
$self->{"scope"}{"path_params"} // {}
$self->{"scope"}{"path_params"}
Truth table100%2/2
A
A= $self->{"scope"}{"path_params"}
| |||||||||||||||||||||||||||||||||||
| 255 | } | ||||||||||||||||||||||||||||||||||
| 256 | |||||||||||||||||||||||||||||||||||
| 257 | 6 | ▶ | sub path_param { | ||||||||||||||||||||||||||||||||
|
Subroutine
path_param: called CC=5 SCAR=16.1
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 258 | 6 | my ($self, $name, %opts) = @_; | |||||||||||||||||||||||||||||||||
| 259 | 6 | ▶ | my $strict = exists $opts{strict} ? $opts{strict} : 1; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 260 | 6 | my $params = $self->path_params; | |||||||||||||||||||||||||||||||||
| 261 | |||||||||||||||||||||||||||||||||||
| 262 | 6 | ▶ | if ($strict && !exists $params->{$name}) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
$strict and not exists $params->{$name}
MC/DC100%2/2
$strict and not exists $params->{$name}
$strict
not exists $params->{$name}
Truth table100%3/3
A and not(B)
A= $strictB= not exists $params->{$name}
| |||||||||||||||||||||||||||||||||||
| 263 | 1 | my @available = sort keys %$params; | |||||||||||||||||||||||||||||||||
| 264 | 1 | ▶ | die "path_param '$name' not found. " | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 265 | . (@available ? "Available: " . join(', ', @available) : "No path params set") | ||||||||||||||||||||||||||||||||||
| 266 | . "\n"; | ||||||||||||||||||||||||||||||||||
| 267 | } | ||||||||||||||||||||||||||||||||||
| 268 | |||||||||||||||||||||||||||||||||||
| 269 | 5 | return $params->{$name}; | |||||||||||||||||||||||||||||||||
| 270 | } | ||||||||||||||||||||||||||||||||||
| 271 | |||||||||||||||||||||||||||||||||||
| 272 | =head2 Protocol Introspection | ||||||||||||||||||||||||||||||||||
| 273 | |||||||||||||||||||||||||||||||||||
| 274 | $ctx->is_http; # true if type eq 'http' | ||||||||||||||||||||||||||||||||||
| 275 | $ctx->is_websocket; # true if type eq 'websocket' | ||||||||||||||||||||||||||||||||||
| 276 | $ctx->is_sse; # true if type eq 'sse' | ||||||||||||||||||||||||||||||||||
| 277 | |||||||||||||||||||||||||||||||||||
| 278 | =cut | ||||||||||||||||||||||||||||||||||
| 279 | |||||||||||||||||||||||||||||||||||
| 280 | 5 | ▶ | sub is_http { (shift->{scope}{type} // '') eq 'http' } | ||||||||||||||||||||||||||||||||
|
Subroutine
is_http: called CC=2 SCAR=7.6
Pod
undocumented
Condition50%1/2
+(shift())->{"scope"}{"type"} // ""
MC/DC0%0/1
+(shift())->{"scope"}{"type"} // ""
+(shift())->{"scope"}{"type"}
Truth table50%1/2
A
A= +(shift())->{"scope"}{"type"}
| |||||||||||||||||||||||||||||||||||
| 281 | 5 | ▶ | sub is_websocket { (shift->{scope}{type} // '') eq 'websocket' } | ||||||||||||||||||||||||||||||||
|
Subroutine
is_websocket: called CC=2 SCAR=7.6
Pod
undocumented
Condition50%1/2
+(shift())->{"scope"}{"type"} // ""
MC/DC0%0/1
+(shift())->{"scope"}{"type"} // ""
+(shift())->{"scope"}{"type"}
Truth table50%1/2
A
A= +(shift())->{"scope"}{"type"}
| |||||||||||||||||||||||||||||||||||
| 282 | 4 | ▶ | sub is_sse { (shift->{scope}{type} // '') eq 'sse' } | ||||||||||||||||||||||||||||||||
|
Subroutine
is_sse: called CC=2 SCAR=7.6
Pod
undocumented
Condition50%1/2
+(shift())->{"scope"}{"type"} // ""
MC/DC0%0/1
+(shift())->{"scope"}{"type"} // ""
+(shift())->{"scope"}{"type"}
Truth table50%1/2
A
A= +(shift())->{"scope"}{"type"}
| |||||||||||||||||||||||||||||||||||
| 283 | |||||||||||||||||||||||||||||||||||
| 284 | =head2 header | ||||||||||||||||||||||||||||||||||
| 285 | |||||||||||||||||||||||||||||||||||
| 286 | my $value = $ctx->header('Content-Type'); | ||||||||||||||||||||||||||||||||||
| 287 | |||||||||||||||||||||||||||||||||||
| 288 | Returns the last value for the named header (case-insensitive), or | ||||||||||||||||||||||||||||||||||
| 289 | C<undef> if not found. | ||||||||||||||||||||||||||||||||||
| 290 | |||||||||||||||||||||||||||||||||||
| 291 | =cut | ||||||||||||||||||||||||||||||||||
| 292 | |||||||||||||||||||||||||||||||||||
| 293 | 12 | ▶ | sub header { | ||||||||||||||||||||||||||||||||
|
Subroutine
header: called CC=4 SCAR=13.9
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 294 | 12 | my ($self, $name) = @_; | |||||||||||||||||||||||||||||||||
| 295 | 12 | $name = lc($name); | |||||||||||||||||||||||||||||||||
| 296 | 12 | my $value; | |||||||||||||||||||||||||||||||||
| 297 | 12 | ▶ | for my $pair (@{$self->{scope}{headers} // []}) { | ||||||||||||||||||||||||||||||||
|
Condition50%1/2
$self->{"scope"}{"headers"} // []
MC/DC0%0/1
$self->{"scope"}{"headers"} // []
$self->{"scope"}{"headers"}
Truth table50%1/2
A
A= $self->{"scope"}{"headers"}
| |||||||||||||||||||||||||||||||||||
| 298 | 25 | ▶ | if (lc($pair->[0]) eq $name) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 299 | 10 | $value = $pair->[1]; | |||||||||||||||||||||||||||||||||
| 300 | } | ||||||||||||||||||||||||||||||||||
| 301 | } | ||||||||||||||||||||||||||||||||||
| 302 | 12 | return $value; | |||||||||||||||||||||||||||||||||
| 303 | } | ||||||||||||||||||||||||||||||||||
| 304 | |||||||||||||||||||||||||||||||||||
| 305 | =head2 receive | ||||||||||||||||||||||||||||||||||
| 306 | |||||||||||||||||||||||||||||||||||
| 307 | my $receive = $ctx->receive; | ||||||||||||||||||||||||||||||||||
| 308 | |||||||||||||||||||||||||||||||||||
| 309 | Returns the raw C<$receive> coderef. Calling it returns a L<Future> that | ||||||||||||||||||||||||||||||||||
| 310 | resolves to the next protocol event hashref from the client. | ||||||||||||||||||||||||||||||||||
| 311 | |||||||||||||||||||||||||||||||||||
| 312 | # Read an HTTP request body event | ||||||||||||||||||||||||||||||||||
| 313 | my $event = await $ctx->receive->(); | ||||||||||||||||||||||||||||||||||
| 314 | # $event = { type => 'http.request', body => '...' } | ||||||||||||||||||||||||||||||||||
| 315 | |||||||||||||||||||||||||||||||||||
| 316 | # Read a WebSocket message | ||||||||||||||||||||||||||||||||||
| 317 | my $msg = await $ctx->receive->(); | ||||||||||||||||||||||||||||||||||
| 318 | # $msg = { type => 'websocket.receive', text => 'hello' } | ||||||||||||||||||||||||||||||||||
| 319 | |||||||||||||||||||||||||||||||||||
| 320 | Most users should prefer the protocol helpers (C<< $ctx->request >>, | ||||||||||||||||||||||||||||||||||
| 321 | C<< $ctx->websocket >>, C<< $ctx->sse >>) which handle the event | ||||||||||||||||||||||||||||||||||
| 322 | protocol internally. Use C<receive> only for raw protocol access. | ||||||||||||||||||||||||||||||||||
| 323 | |||||||||||||||||||||||||||||||||||
| 324 | =head2 send | ||||||||||||||||||||||||||||||||||
| 325 | |||||||||||||||||||||||||||||||||||
| 326 | my $send = $ctx->send; | ||||||||||||||||||||||||||||||||||
| 327 | |||||||||||||||||||||||||||||||||||
| 328 | Returns the raw C<$send> coderef. Calling it with an event hashref | ||||||||||||||||||||||||||||||||||
| 329 | returns a L<Future> that resolves when the event has been sent. | ||||||||||||||||||||||||||||||||||
| 330 | |||||||||||||||||||||||||||||||||||
| 331 | # Send an HTTP response (two events: start + body) | ||||||||||||||||||||||||||||||||||
| 332 | await $ctx->send->({ type => 'http.response.start', status => 200, | ||||||||||||||||||||||||||||||||||
| 333 | headers => [['content-type', 'text/plain']] }); | ||||||||||||||||||||||||||||||||||
| 334 | await $ctx->send->({ type => 'http.response.body', body => 'Hello' }); | ||||||||||||||||||||||||||||||||||
| 335 | |||||||||||||||||||||||||||||||||||
| 336 | # Accept a WebSocket connection | ||||||||||||||||||||||||||||||||||
| 337 | await $ctx->send->({ type => 'websocket.accept' }); | ||||||||||||||||||||||||||||||||||
| 338 | |||||||||||||||||||||||||||||||||||
| 339 | Most users should prefer the protocol helpers (C<< $ctx->response >>, | ||||||||||||||||||||||||||||||||||
| 340 | C<< $ctx->websocket >>, C<< $ctx->sse >>) which build and send events | ||||||||||||||||||||||||||||||||||
| 341 | for you. Use C<send> only for raw protocol access. | ||||||||||||||||||||||||||||||||||
| 342 | |||||||||||||||||||||||||||||||||||
| 343 | =head2 raw_send | ||||||||||||||||||||||||||||||||||
| 344 | |||||||||||||||||||||||||||||||||||
| 345 | my $send = $ctx->raw_send; | ||||||||||||||||||||||||||||||||||
| 346 | |||||||||||||||||||||||||||||||||||
| 347 | Returns the raw C<$send> coderef on B<any> context type. On the base context | ||||||||||||||||||||||||||||||||||
| 348 | this is identical to L</send>, but subclasses never override C<raw_send>, whereas | ||||||||||||||||||||||||||||||||||
| 349 | some override C<send>: L<PAGI::Context::SSE> replaces C<send> with a C<sse.send> | ||||||||||||||||||||||||||||||||||
| 350 | convenience (C<< $ctx->send($data) >> sends an SSE data event). So when you are | ||||||||||||||||||||||||||||||||||
| 351 | holding an SSE (or any) context and need the actual underlying channel rather | ||||||||||||||||||||||||||||||||||
| 352 | than the protocol convenience, reach for C<raw_send>. | ||||||||||||||||||||||||||||||||||
| 353 | |||||||||||||||||||||||||||||||||||
| 354 | The reason you reach for it: emitting your B<own> event types that something | ||||||||||||||||||||||||||||||||||
| 355 | downstream (a middleware) translates into the wire protocol — the same shape | ||||||||||||||||||||||||||||||||||
| 356 | PAGI's SSE/WebSocket layers themselves use (C<sse.send> / C<websocket.send> are | ||||||||||||||||||||||||||||||||||
| 357 | custom send events a layer renders). | ||||||||||||||||||||||||||||||||||
| 358 | |||||||||||||||||||||||||||||||||||
| 359 | # Inside an SSE handler: $ctx->send would emit an sse.send for you, but we | ||||||||||||||||||||||||||||||||||
| 360 | # want to emit our own typed event for a middleware to render. | ||||||||||||||||||||||||||||||||||
| 361 | my $emit = $ctx->raw_send; | ||||||||||||||||||||||||||||||||||
| 362 | await $emit->({ type => 'app.event', name => 'tick', data => 1 }); | ||||||||||||||||||||||||||||||||||
| 363 | |||||||||||||||||||||||||||||||||||
| 364 | # A middleware wrapping $send catches it and renders to the wire: | ||||||||||||||||||||||||||||||||||
| 365 | # my $wrapped = async sub ($ev) { | ||||||||||||||||||||||||||||||||||
| 366 | # if (($ev->{type} // '') eq 'app.event') { | ||||||||||||||||||||||||||||||||||
| 367 | # await $send->({ type => 'sse.send', event => $ev->{name}, | ||||||||||||||||||||||||||||||||||
| 368 | # data => encode_json({ value => $ev->{data} }) }); | ||||||||||||||||||||||||||||||||||
| 369 | # return; | ||||||||||||||||||||||||||||||||||
| 370 | # } | ||||||||||||||||||||||||||||||||||
| 371 | # await $send->($ev); # real protocol events pass through | ||||||||||||||||||||||||||||||||||
| 372 | # }; | ||||||||||||||||||||||||||||||||||
| 373 | |||||||||||||||||||||||||||||||||||
| 374 | Note the trap C<raw_send> avoids: on an SSE context C<< $ctx->send >> is a | ||||||||||||||||||||||||||||||||||
| 375 | B<method that sends> (it calls C<< $ctx->sse->send >>), not an accessor — so | ||||||||||||||||||||||||||||||||||
| 376 | C<< $ctx->send >> there is not the raw coderef. C<raw_send> always is. | ||||||||||||||||||||||||||||||||||
| 377 | |||||||||||||||||||||||||||||||||||
| 378 | =cut | ||||||||||||||||||||||||||||||||||
| 379 | |||||||||||||||||||||||||||||||||||
| 380 | 1 | ▶ | sub receive { shift->{receive} } | ||||||||||||||||||||||||||||||||
|
Subroutine
receive: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 381 | 2 | ▶ | sub send { shift->{send} } | ||||||||||||||||||||||||||||||||
|
Subroutine
send: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 382 | 3 | ▶ | sub raw_send { shift->{send} } | ||||||||||||||||||||||||||||||||
|
Subroutine
raw_send: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 383 | |||||||||||||||||||||||||||||||||||
| 384 | =head2 stash | ||||||||||||||||||||||||||||||||||
| 385 | |||||||||||||||||||||||||||||||||||
| 386 | my $stash = $ctx->stash; # PAGI::Stash instance | ||||||||||||||||||||||||||||||||||
| 387 | |||||||||||||||||||||||||||||||||||
| 388 | Returns a L<PAGI::Stash> wrapping C<< $scope->{'pagi.stash'} >>. | ||||||||||||||||||||||||||||||||||
| 389 | Lazy-constructed and cached. | ||||||||||||||||||||||||||||||||||
| 390 | |||||||||||||||||||||||||||||||||||
| 391 | =head2 session | ||||||||||||||||||||||||||||||||||
| 392 | |||||||||||||||||||||||||||||||||||
| 393 | my $session = $ctx->session; # PAGI::Session instance | ||||||||||||||||||||||||||||||||||
| 394 | |||||||||||||||||||||||||||||||||||
| 395 | Returns a L<PAGI::Session> wrapping C<< $scope->{'pagi.session'} >>. | ||||||||||||||||||||||||||||||||||
| 396 | Lazy-constructed and cached. Dies if session middleware has not run. | ||||||||||||||||||||||||||||||||||
| 397 | Use C<has_session> to check availability first. | ||||||||||||||||||||||||||||||||||
| 398 | |||||||||||||||||||||||||||||||||||
| 399 | =head2 has_session | ||||||||||||||||||||||||||||||||||
| 400 | |||||||||||||||||||||||||||||||||||
| 401 | if ($ctx->has_session) { | ||||||||||||||||||||||||||||||||||
| 402 | my $user_id = $ctx->session->get('user_id'); | ||||||||||||||||||||||||||||||||||
| 403 | } | ||||||||||||||||||||||||||||||||||
| 404 | |||||||||||||||||||||||||||||||||||
| 405 | Returns true if session middleware has populated C<< $scope->{'pagi.session'} >>. | ||||||||||||||||||||||||||||||||||
| 406 | |||||||||||||||||||||||||||||||||||
| 407 | =head2 state | ||||||||||||||||||||||||||||||||||
| 408 | |||||||||||||||||||||||||||||||||||
| 409 | my $state = $ctx->state; # hashref | ||||||||||||||||||||||||||||||||||
| 410 | |||||||||||||||||||||||||||||||||||
| 411 | Returns C<< $scope->{state} >> - the app/endpoint-level shared state. | ||||||||||||||||||||||||||||||||||
| 412 | |||||||||||||||||||||||||||||||||||
| 413 | =head2 csrf_token | ||||||||||||||||||||||||||||||||||
| 414 | |||||||||||||||||||||||||||||||||||
| 415 | my $token = $ctx->csrf_token; | ||||||||||||||||||||||||||||||||||
| 416 | |||||||||||||||||||||||||||||||||||
| 417 | Returns C<< $scope->{csrf_token} >>, the token minted or persisted by | ||||||||||||||||||||||||||||||||||
| 418 | L<PAGI::Middleware::CSRF>. C<undef> if that middleware is not enabled. | ||||||||||||||||||||||||||||||||||
| 419 | |||||||||||||||||||||||||||||||||||
| 420 | Embed it in a form's hidden field so a submitted request can be checked with | ||||||||||||||||||||||||||||||||||
| 421 | L</csrf_verify>: | ||||||||||||||||||||||||||||||||||
| 422 | |||||||||||||||||||||||||||||||||||
| 423 | <input type="hidden" name="_csrf_token" value="<%= $ctx->csrf_token %>"> | ||||||||||||||||||||||||||||||||||
| 424 | |||||||||||||||||||||||||||||||||||
| 425 | or in a C<< <meta> >> tag for JavaScript to read and send back as a header | ||||||||||||||||||||||||||||||||||
| 426 | (the cookie itself is C<HttpOnly> and not readable from script): | ||||||||||||||||||||||||||||||||||
| 427 | |||||||||||||||||||||||||||||||||||
| 428 | <meta name="csrf-token" content="<%= $ctx->csrf_token %>"> | ||||||||||||||||||||||||||||||||||
| 429 | |||||||||||||||||||||||||||||||||||
| 430 | =head2 csrf_verify | ||||||||||||||||||||||||||||||||||
| 431 | |||||||||||||||||||||||||||||||||||
| 432 | if ($ctx->csrf_verify($submitted_token)) { ... } | ||||||||||||||||||||||||||||||||||
| 433 | |||||||||||||||||||||||||||||||||||
| 434 | Timing-safe comparison of C<$submitted_token> against C<< $ctx->csrf_token >>. | ||||||||||||||||||||||||||||||||||
| 435 | Returns true on a match, false otherwise -- including when either side is | ||||||||||||||||||||||||||||||||||
| 436 | missing or empty. Intended for C<< enforce => 'app' >> mode on | ||||||||||||||||||||||||||||||||||
| 437 | L<PAGI::Middleware::CSRF>, where the middleware only issues the token and the | ||||||||||||||||||||||||||||||||||
| 438 | app validates it once it has parsed the submitted params: | ||||||||||||||||||||||||||||||||||
| 439 | |||||||||||||||||||||||||||||||||||
| 440 | return $ctx->text('CSRF token validation failed', status => 403) | ||||||||||||||||||||||||||||||||||
| 441 | unless $ctx->csrf_verify($params->{_csrf_token}); | ||||||||||||||||||||||||||||||||||
| 442 | |||||||||||||||||||||||||||||||||||
| 443 | The app decides the response for a failed check; this method only reports | ||||||||||||||||||||||||||||||||||
| 444 | match or no match. | ||||||||||||||||||||||||||||||||||
| 445 | |||||||||||||||||||||||||||||||||||
| 446 | =cut | ||||||||||||||||||||||||||||||||||
| 447 | |||||||||||||||||||||||||||||||||||
| 448 | 17 | ▶ | sub stash { | ||||||||||||||||||||||||||||||||
|
Subroutine
stash: called CC=2 SCAR=7.0
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 449 | 17 | my ($self) = @_; | |||||||||||||||||||||||||||||||||
| 450 | 17 | ▶ | return $self->{_stash} //= do { | ||||||||||||||||||||||||||||||||
|
Condition66%2/3
$self->{"_stash"} //= do {
require PAGI::Stash;
"PAGI::Stash"->new($self->{"scope"})
}
MC/DC0%0/2
$self->{"_stash"} //= do {
require PAGI::Stash;
"PAGI::Stash"->new($self->{"scope"})
}
$self->{"_stash"}
do {
require PAGI::Stash;
"PAGI::Stash"->new($self->{"scope"})
}
Truth table66%2/3
A //= B
A= $self->{"_stash"}B= do {
require PAGI::Stash;
"PAGI::Stash"->new($self->{"scope"})
}
| |||||||||||||||||||||||||||||||||||
| 451 | 10 | require PAGI::Stash; | |||||||||||||||||||||||||||||||||
| 452 | 10 | PAGI::Stash->new($self->{scope}); | |||||||||||||||||||||||||||||||||
| 453 | }; | ||||||||||||||||||||||||||||||||||
| 454 | } | ||||||||||||||||||||||||||||||||||
| 455 | |||||||||||||||||||||||||||||||||||
| 456 | 3 | ▶ | sub session { | ||||||||||||||||||||||||||||||||
|
Subroutine
session: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 457 | 3 | my ($self) = @_; | |||||||||||||||||||||||||||||||||
| 458 | 3 | ▶ | return $self->{_session} //= do { | ||||||||||||||||||||||||||||||||
|
Condition100%3/3
$self->{"_session"} //= do {
require PAGI::Session;
"PAGI::Session"->new($self->{"scope"})
}
MC/DC100%2/2
$self->{"_session"} //= do {
require PAGI::Session;
"PAGI::Session"->new($self->{"scope"})
}
$self->{"_session"}
do {
require PAGI::Session;
"PAGI::Session"->new($self->{"scope"})
}
Truth table100%3/3
A //= B
A= $self->{"_session"}B= do {
require PAGI::Session;
"PAGI::Session"->new($self->{"scope"})
}
| |||||||||||||||||||||||||||||||||||
| 459 | 2 | require PAGI::Session; | |||||||||||||||||||||||||||||||||
| 460 | 2 | PAGI::Session->new($self->{scope}); | |||||||||||||||||||||||||||||||||
| 461 | }; | ||||||||||||||||||||||||||||||||||
| 462 | } | ||||||||||||||||||||||||||||||||||
| 463 | |||||||||||||||||||||||||||||||||||
| 464 | 2 | ▶ | sub has_session { | ||||||||||||||||||||||||||||||||
|
Subroutine
has_session: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 465 | 2 | my ($self) = @_; | |||||||||||||||||||||||||||||||||
| 466 | 2 | ▶ | return exists $self->{scope}{'pagi.session'} ? 1 : 0; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 467 | } | ||||||||||||||||||||||||||||||||||
| 468 | |||||||||||||||||||||||||||||||||||
| 469 | 11 | ▶ | sub state { | ||||||||||||||||||||||||||||||||
|
Subroutine
state: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 470 | 11 | my ($self) = @_; | |||||||||||||||||||||||||||||||||
| 471 | 11 | ▶ | return $self->{scope}{state} // {}; | ||||||||||||||||||||||||||||||||
|
Condition100%2/2
$self->{"scope"}{"state"} // {}
MC/DC100%1/1
$self->{"scope"}{"state"} // {}
$self->{"scope"}{"state"}
Truth table100%2/2
A
A= $self->{"scope"}{"state"}
| |||||||||||||||||||||||||||||||||||
| 472 | } | ||||||||||||||||||||||||||||||||||
| 473 | |||||||||||||||||||||||||||||||||||
| 474 | 2 | ▶ | sub csrf_token { | ||||||||||||||||||||||||||||||||
|
Subroutine
csrf_token: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 475 | 2 | my ($self) = @_; | |||||||||||||||||||||||||||||||||
| 476 | 2 | return $self->{scope}{csrf_token}; | |||||||||||||||||||||||||||||||||
| 477 | } | ||||||||||||||||||||||||||||||||||
| 478 | |||||||||||||||||||||||||||||||||||
| 479 | 6 | ▶ | sub csrf_verify { | ||||||||||||||||||||||||||||||||
|
Subroutine
csrf_verify: called CC=5 SCAR=16.1
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 480 | 6 | my ($self, $submitted) = @_; | |||||||||||||||||||||||||||||||||
| 481 | 6 | my $expected = $self->{scope}{csrf_token}; | |||||||||||||||||||||||||||||||||
| 482 | 6 | ▶ | return 0 unless defined $submitted && length($submitted); | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
defined $submitted and length $submitted
MC/DC100%2/2
defined $submitted and length $submitted
defined $submitted
length $submitted
Truth table100%3/3
A and B
A= defined $submittedB= length $submitted
| |||||||||||||||||||||||||||||||||||
| 483 | 3 | ▶ | return 0 unless defined $expected && length($expected); | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
defined $expected and length $expected
MC/DC50%1/2
defined $expected and length $expected
defined $expected
length $expected
Truth table66%2/3
A and B
A= defined $expectedB= length $expected
| |||||||||||||||||||||||||||||||||||
| 484 | 2 | return secure_compare($submitted, $expected); | |||||||||||||||||||||||||||||||||
| 485 | } | ||||||||||||||||||||||||||||||||||
| 486 | |||||||||||||||||||||||||||||||||||
| 487 | =head2 Connection State | ||||||||||||||||||||||||||||||||||
| 488 | |||||||||||||||||||||||||||||||||||
| 489 | $ctx->connection; # PAGI::Server::ConnectionState object | ||||||||||||||||||||||||||||||||||
| 490 | $ctx->is_connected; # boolean | ||||||||||||||||||||||||||||||||||
| 491 | $ctx->is_disconnected; # boolean | ||||||||||||||||||||||||||||||||||
| 492 | $ctx->disconnect_reason; # string or undef (abnormal disconnect only) | ||||||||||||||||||||||||||||||||||
| 493 | $ctx->on_disconnect($cb); # callback on abnormal disconnect | ||||||||||||||||||||||||||||||||||
| 494 | $ctx->on_complete($cb); # callback on clean completion | ||||||||||||||||||||||||||||||||||
| 495 | |||||||||||||||||||||||||||||||||||
| 496 | Delegates to C<< $scope->{'pagi.connection'} >>. C<on_disconnect> fires only on | ||||||||||||||||||||||||||||||||||
| 497 | an abnormal end and C<on_complete> only on a clean finish -- exactly one per | ||||||||||||||||||||||||||||||||||
| 498 | request. | ||||||||||||||||||||||||||||||||||
| 499 | |||||||||||||||||||||||||||||||||||
| 500 | C<< $ctx->buffered_amount >>, C<< $ctx->high_water_mark >>, and | ||||||||||||||||||||||||||||||||||
| 501 | C<< $ctx->low_water_mark >> expose outbound flow control via the server's | ||||||||||||||||||||||||||||||||||
| 502 | C<pagi.transport> handle (see L<PAGI::Spec::Www/"Transport Flow Control">): | ||||||||||||||||||||||||||||||||||
| 503 | bytes queued for the client but not yet on the wire, and the backpressure band. | ||||||||||||||||||||||||||||||||||
| 504 | C<buffered_amount> returns C<0> (and the watermarks C<undef>) when the server | ||||||||||||||||||||||||||||||||||
| 505 | does not provide the handle. | ||||||||||||||||||||||||||||||||||
| 506 | |||||||||||||||||||||||||||||||||||
| 507 | C<< $ctx->on_high_water($cb) >> and C<< $ctx->on_drain($cb) >> register | ||||||||||||||||||||||||||||||||||
| 508 | edge-triggered backpressure callbacks (pause/resume a producer), and | ||||||||||||||||||||||||||||||||||
| 509 | C<< $ctx->is_writable >> is true while the buffer is below the high mark. Both | ||||||||||||||||||||||||||||||||||
| 510 | delegate to C<pagi.transport> and degrade quietly -- the callbacks become no-ops | ||||||||||||||||||||||||||||||||||
| 511 | and C<is_writable> stays true -- when the handle (or its callback support) is | ||||||||||||||||||||||||||||||||||
| 512 | absent. | ||||||||||||||||||||||||||||||||||
| 513 | |||||||||||||||||||||||||||||||||||
| 514 | =cut | ||||||||||||||||||||||||||||||||||
| 515 | |||||||||||||||||||||||||||||||||||
| 516 | 13 | ▶ | sub connection { | ||||||||||||||||||||||||||||||||
|
Subroutine
connection: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 517 | 13 | my ($self) = @_; | |||||||||||||||||||||||||||||||||
| 518 | 13 | return $self->{scope}{'pagi.connection'}; | |||||||||||||||||||||||||||||||||
| 519 | } | ||||||||||||||||||||||||||||||||||
| 520 | |||||||||||||||||||||||||||||||||||
| 521 | 6 | ▶ | sub is_connected { | ||||||||||||||||||||||||||||||||
|
Subroutine
is_connected: called CC=2 SCAR=6.9
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 522 | 6 | my ($self) = @_; | |||||||||||||||||||||||||||||||||
| 523 | 6 | my $conn = $self->connection; | |||||||||||||||||||||||||||||||||
| 524 | 6 | ▶ | return 0 unless $conn; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 525 | 4 | return $conn->is_connected; | |||||||||||||||||||||||||||||||||
| 526 | } | ||||||||||||||||||||||||||||||||||
| 527 | |||||||||||||||||||||||||||||||||||
| 528 | 6 | ▶ | sub is_disconnected { | ||||||||||||||||||||||||||||||||
|
Subroutine
is_disconnected: called CC=1 SCAR=0.0
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 529 | 6 | my ($self) = @_; | |||||||||||||||||||||||||||||||||
| 530 | 6 | return !$self->is_connected; | |||||||||||||||||||||||||||||||||
| 531 | } | ||||||||||||||||||||||||||||||||||
| 532 | |||||||||||||||||||||||||||||||||||
| 533 | 3 | ▶ | sub disconnect_reason { | ||||||||||||||||||||||||||||||||
|
Subroutine
disconnect_reason: called CC=2 SCAR=6.9
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 534 | 3 | my ($self) = @_; | |||||||||||||||||||||||||||||||||
| 535 | 3 | my $conn = $self->connection; | |||||||||||||||||||||||||||||||||
| 536 | 3 | ▶ | return undef unless $conn; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 537 | 2 | return $conn->disconnect_reason; | |||||||||||||||||||||||||||||||||
| 538 | } | ||||||||||||||||||||||||||||||||||
| 539 | |||||||||||||||||||||||||||||||||||
| 540 | 1 | ▶ | sub on_disconnect { | ||||||||||||||||||||||||||||||||
|
Subroutine
on_disconnect: called CC=2 SCAR=7.0
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 541 | 1 | my ($self, $cb) = @_; | |||||||||||||||||||||||||||||||||
| 542 | 1 | my $conn = $self->connection; | |||||||||||||||||||||||||||||||||
| 543 | 1 | ▶ | return unless $conn; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 544 | 1 | $conn->on_disconnect($cb); | |||||||||||||||||||||||||||||||||
| 545 | } | ||||||||||||||||||||||||||||||||||
| 546 | |||||||||||||||||||||||||||||||||||
| 547 | 2 | ▶ | sub on_complete { | ||||||||||||||||||||||||||||||||
|
Subroutine
on_complete: called CC=2 SCAR=6.9
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 548 | 2 | my ($self, $cb) = @_; | |||||||||||||||||||||||||||||||||
| 549 | 2 | my $conn = $self->connection; | |||||||||||||||||||||||||||||||||
| 550 | 2 | ▶ | return unless $conn; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 551 | 1 | $conn->on_complete($cb); | |||||||||||||||||||||||||||||||||
| 552 | } | ||||||||||||||||||||||||||||||||||
| 553 | |||||||||||||||||||||||||||||||||||
| 554 | # Outbound flow-control introspection (delegates to the pagi.transport handle) | ||||||||||||||||||||||||||||||||||
| 555 | 2 | ▶ | sub buffered_amount { | ||||||||||||||||||||||||||||||||
|
Subroutine
buffered_amount: called CC=2 SCAR=6.9
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 556 | 2 | my $self = shift; | |||||||||||||||||||||||||||||||||
| 557 | 2 | my $t = $self->{scope}{'pagi.transport'}; | |||||||||||||||||||||||||||||||||
| 558 | 2 | ▶ | return 0 unless $t; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 559 | 1 | return $t->buffered_amount; | |||||||||||||||||||||||||||||||||
| 560 | } | ||||||||||||||||||||||||||||||||||
| 561 | |||||||||||||||||||||||||||||||||||
| 562 | 2 | ▶ | sub high_water_mark { | ||||||||||||||||||||||||||||||||
|
Subroutine
high_water_mark: called CC=2 SCAR=6.9
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 563 | 2 | my $self = shift; | |||||||||||||||||||||||||||||||||
| 564 | 2 | my $t = $self->{scope}{'pagi.transport'}; | |||||||||||||||||||||||||||||||||
| 565 | 2 | ▶ | return undef unless $t; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 566 | 1 | return $t->high_water_mark; | |||||||||||||||||||||||||||||||||
| 567 | } | ||||||||||||||||||||||||||||||||||
| 568 | |||||||||||||||||||||||||||||||||||
| 569 | 2 | ▶ | sub low_water_mark { | ||||||||||||||||||||||||||||||||
|
Subroutine
low_water_mark: called CC=2 SCAR=6.9
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 570 | 2 | my $self = shift; | |||||||||||||||||||||||||||||||||
| 571 | 2 | my $t = $self->{scope}{'pagi.transport'}; | |||||||||||||||||||||||||||||||||
| 572 | 2 | ▶ | return undef unless $t; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 573 | 1 | return $t->low_water_mark; | |||||||||||||||||||||||||||||||||
| 574 | } | ||||||||||||||||||||||||||||||||||
| 575 | |||||||||||||||||||||||||||||||||||
| 576 | 2 | ▶ | sub on_high_water { | ||||||||||||||||||||||||||||||||
|
Subroutine
on_high_water: called CC=3 SCAR=11.0
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 577 | 2 | my ($self, $cb) = @_; | |||||||||||||||||||||||||||||||||
| 578 | 2 | my $t = $self->{scope}{'pagi.transport'}; | |||||||||||||||||||||||||||||||||
| 579 | 2 | ▶ | $t->on_high_water($cb) if $t && $t->can('on_high_water'); | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
$t and $t->can("on_high_water")
MC/DC50%1/2
$t and $t->can("on_high_water")
$t
$t->can("on_high_water")
Truth table66%2/3
A and B
A= $tB= $t->can("on_high_water")
| |||||||||||||||||||||||||||||||||||
| 580 | 2 | return $self; | |||||||||||||||||||||||||||||||||
| 581 | } | ||||||||||||||||||||||||||||||||||
| 582 | |||||||||||||||||||||||||||||||||||
| 583 | 2 | ▶ | sub on_drain { | ||||||||||||||||||||||||||||||||
|
Subroutine
on_drain: called CC=3 SCAR=11.0
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 584 | 2 | my ($self, $cb) = @_; | |||||||||||||||||||||||||||||||||
| 585 | 2 | my $t = $self->{scope}{'pagi.transport'}; | |||||||||||||||||||||||||||||||||
| 586 | 2 | ▶ | $t->on_drain($cb) if $t && $t->can('on_drain'); | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
$t and $t->can("on_drain")
MC/DC50%1/2
$t and $t->can("on_drain")
$t
$t->can("on_drain")
Truth table66%2/3
A and B
A= $tB= $t->can("on_drain")
| |||||||||||||||||||||||||||||||||||
| 587 | 2 | return $self; | |||||||||||||||||||||||||||||||||
| 588 | } | ||||||||||||||||||||||||||||||||||
| 589 | |||||||||||||||||||||||||||||||||||
| 590 | 3 | ▶ | sub is_writable { | ||||||||||||||||||||||||||||||||
|
Subroutine
is_writable: called CC=4 SCAR=13.9
Pod
undocumented
| |||||||||||||||||||||||||||||||||||
| 591 | 3 | my $self = shift; | |||||||||||||||||||||||||||||||||
| 592 | 3 | my $t = $self->{scope}{'pagi.transport'}; | |||||||||||||||||||||||||||||||||
| 593 | 3 | ▶ | return 1 unless $t; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 594 | 2 | my $high = $t->high_water_mark; | |||||||||||||||||||||||||||||||||
| 595 | 2 | ▶ | return 1 unless defined $high; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 596 | 2 | ▶ | return $t->buffered_amount < $high ? 1 : 0; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 597 | } | ||||||||||||||||||||||||||||||||||
| 598 | |||||||||||||||||||||||||||||||||||
| 599 | =head1 EVENT DISPATCHER | ||||||||||||||||||||||||||||||||||
| 600 | |||||||||||||||||||||||||||||||||||
| 601 | The event dispatcher provides a generic, protocol-agnostic way to handle | ||||||||||||||||||||||||||||||||||
| 602 | PAGI events. It is most useful when the receive stream carries a mix of | ||||||||||||||||||||||||||||||||||
| 603 | protocol events and application-level events injected by middleware such | ||||||||||||||||||||||||||||||||||
| 604 | as C<PAGI::Middleware::Channels>. | ||||||||||||||||||||||||||||||||||
| 605 | |||||||||||||||||||||||||||||||||||
| 606 | my $ctx = PAGI::Context->new($scope, $receive, $send); | ||||||||||||||||||||||||||||||||||
| 607 | |||||||||||||||||||||||||||||||||||
| 608 | $ctx->on('websocket.receive', async sub { | ||||||||||||||||||||||||||||||||||
| 609 | my ($ctx, $event) = @_; | ||||||||||||||||||||||||||||||||||
| 610 | my $text = $event->{text} // ''; | ||||||||||||||||||||||||||||||||||
| 611 | await $ctx->send->({ type => 'websocket.send', text => "echo: $text" }); | ||||||||||||||||||||||||||||||||||
| 612 | }); | ||||||||||||||||||||||||||||||||||
| 613 | |||||||||||||||||||||||||||||||||||
| 614 | $ctx->on('chat.message', async sub { | ||||||||||||||||||||||||||||||||||
| 615 | my ($ctx, $event) = @_; | ||||||||||||||||||||||||||||||||||
| 616 | # handle a channel-injected event | ||||||||||||||||||||||||||||||||||
| 617 | }); | ||||||||||||||||||||||||||||||||||
| 618 | |||||||||||||||||||||||||||||||||||
| 619 | $ctx->on_error(sub { | ||||||||||||||||||||||||||||||||||
| 620 | my ($ctx, $error, $source) = @_; | ||||||||||||||||||||||||||||||||||
| 621 | warn "[$source] $error"; | ||||||||||||||||||||||||||||||||||
| 622 | }); | ||||||||||||||||||||||||||||||||||
| 623 | |||||||||||||||||||||||||||||||||||
| 624 | my $reason = await $ctx->run; # 'disconnect', 'stop', or 'error' | ||||||||||||||||||||||||||||||||||
| 625 | |||||||||||||||||||||||||||||||||||
| 626 | =head2 on | ||||||||||||||||||||||||||||||||||
| 627 | |||||||||||||||||||||||||||||||||||
| 628 | $ctx->on($event_type, $callback); # returns $ctx | ||||||||||||||||||||||||||||||||||
| 629 | |||||||||||||||||||||||||||||||||||
| 630 | Register a handler for a raw PAGI event type string. Multiple handlers | ||||||||||||||||||||||||||||||||||
| 631 | may be registered for the same type; they are called in registration order. | ||||||||||||||||||||||||||||||||||
| 632 | Handlers receive C<($ctx, $event)>. Handlers may be plain coderefs or | ||||||||||||||||||||||||||||||||||
| 633 | C<async sub>s; if a handler returns a L<Future>, C<run()> awaits it before | ||||||||||||||||||||||||||||||||||
| 634 | continuing. | ||||||||||||||||||||||||||||||||||
| 635 | |||||||||||||||||||||||||||||||||||
| 636 | Returns C<$ctx> for chaining. | ||||||||||||||||||||||||||||||||||
| 637 | |||||||||||||||||||||||||||||||||||
| 638 | =head2 on_default | ||||||||||||||||||||||||||||||||||
| 639 | |||||||||||||||||||||||||||||||||||
| 640 | $ctx->on_default($callback); # returns $ctx | ||||||||||||||||||||||||||||||||||
| 641 | |||||||||||||||||||||||||||||||||||
| 642 | Register a single fallback handler, called with C<($ctx, $event)> for any | ||||||||||||||||||||||||||||||||||
| 643 | event that has no type-specific handler. The last registration wins. The | ||||||||||||||||||||||||||||||||||
| 644 | callback may be a plain coderef or an C<async sub>; if it returns a L<Future>, | ||||||||||||||||||||||||||||||||||
| 645 | C<run()> awaits it. Exceptions are routed to C<on_error> with | ||||||||||||||||||||||||||||||||||
| 646 | C<source = 'handler'>. | ||||||||||||||||||||||||||||||||||
| 647 | |||||||||||||||||||||||||||||||||||
| 648 | B<The terminal disconnect event is excluded.> C<on_default> does B<not> fire | ||||||||||||||||||||||||||||||||||
| 649 | for the protocol's disconnect event (C<websocket.disconnect>, C<sse.disconnect>, | ||||||||||||||||||||||||||||||||||
| 650 | C<http.disconnect>): that event ends the loop normally and is not treated as an | ||||||||||||||||||||||||||||||||||
| 651 | "unhandled" surprise. To run cleanup or logging on disconnect, register a | ||||||||||||||||||||||||||||||||||
| 652 | handler for it explicitly instead: | ||||||||||||||||||||||||||||||||||
| 653 | |||||||||||||||||||||||||||||||||||
| 654 | $ctx->on('websocket.disconnect', sub { ... }); | ||||||||||||||||||||||||||||||||||
| 655 | |||||||||||||||||||||||||||||||||||
| 656 | Returns C<$ctx> for chaining. | ||||||||||||||||||||||||||||||||||
| 657 | |||||||||||||||||||||||||||||||||||
| 658 | =head2 on_error | ||||||||||||||||||||||||||||||||||
| 659 | |||||||||||||||||||||||||||||||||||
| 660 | $ctx->on_error($callback); # returns $ctx | ||||||||||||||||||||||||||||||||||
| 661 | |||||||||||||||||||||||||||||||||||
| 662 | Register an error callback. It is called when C<$receive-E<gt>()> fails | ||||||||||||||||||||||||||||||||||
| 663 | (C<$source = 'receive'>) or when a registered handler throws (C<$source = | ||||||||||||||||||||||||||||||||||
| 664 | 'handler'>). Callbacks receive C<($ctx, $error, $source)>. | ||||||||||||||||||||||||||||||||||
| 665 | |||||||||||||||||||||||||||||||||||
| 666 | Multiple callbacks may be registered and are called in order. Callbacks | ||||||||||||||||||||||||||||||||||
| 667 | may be C<async sub>s; if a callback returns a L<Future>, it is awaited. | ||||||||||||||||||||||||||||||||||
| 668 | If no callbacks are registered, errors are emitted via C<warn>. | ||||||||||||||||||||||||||||||||||
| 669 | |||||||||||||||||||||||||||||||||||
| 670 | Returns C<$ctx> for chaining. | ||||||||||||||||||||||||||||||||||
| 671 | |||||||||||||||||||||||||||||||||||
| 672 | Handlers and error callbacks are cleared automatically when C<run()> | ||||||||||||||||||||||||||||||||||
| 673 | resolves, so closures that capture C<$ctx> do not leak -- you do not need | ||||||||||||||||||||||||||||||||||
| 674 | to C<weaken> them. (Weakening only matters if you register callbacks and | ||||||||||||||||||||||||||||||||||
| 675 | never call C<run()>.) | ||||||||||||||||||||||||||||||||||
| 676 | |||||||||||||||||||||||||||||||||||
| 677 | =head2 stop | ||||||||||||||||||||||||||||||||||
| 678 | |||||||||||||||||||||||||||||||||||
| 679 | $ctx->stop; # returns $ctx | ||||||||||||||||||||||||||||||||||
| 680 | |||||||||||||||||||||||||||||||||||
| 681 | Signal the C<run()> loop to exit cleanly after the current event's handlers | ||||||||||||||||||||||||||||||||||
| 682 | finish, before the next event is read. C<run()> will resolve with reason | ||||||||||||||||||||||||||||||||||
| 683 | C<'stop'>. | ||||||||||||||||||||||||||||||||||
| 684 | |||||||||||||||||||||||||||||||||||
| 685 | Returns C<$ctx> for chaining. | ||||||||||||||||||||||||||||||||||
| 686 | |||||||||||||||||||||||||||||||||||
| 687 | =head2 run | ||||||||||||||||||||||||||||||||||
| 688 | |||||||||||||||||||||||||||||||||||
| 689 | my $reason = await $ctx->run; | ||||||||||||||||||||||||||||||||||
| 690 | |||||||||||||||||||||||||||||||||||
| 691 | Start the event dispatch loop. Reads events from the receive stream and | ||||||||||||||||||||||||||||||||||
| 692 | dispatches each to registered handlers. The loop runs until one of: | ||||||||||||||||||||||||||||||||||
| 693 | |||||||||||||||||||||||||||||||||||
| 694 | =over 4 | ||||||||||||||||||||||||||||||||||
| 695 | |||||||||||||||||||||||||||||||||||
| 696 | =item * The protocol's terminal disconnect event arrives (C<websocket.disconnect>, | ||||||||||||||||||||||||||||||||||
| 697 | C<sse.disconnect>, C<http.disconnect>) - resolves with C<'disconnect'> | ||||||||||||||||||||||||||||||||||
| 698 | |||||||||||||||||||||||||||||||||||
| 699 | =item * C<stop()> was called - resolves with C<'stop'> | ||||||||||||||||||||||||||||||||||
| 700 | |||||||||||||||||||||||||||||||||||
| 701 | =item * C<$receive-E<gt>()> fails - fires C<on_error> callbacks and resolves | ||||||||||||||||||||||||||||||||||
| 702 | with C<'error'> | ||||||||||||||||||||||||||||||||||
| 703 | |||||||||||||||||||||||||||||||||||
| 704 | =back | ||||||||||||||||||||||||||||||||||
| 705 | |||||||||||||||||||||||||||||||||||
| 706 | C<run()> always resolves successfully (never rejects). The caller does | ||||||||||||||||||||||||||||||||||
| 707 | not need to C<catch> it. | ||||||||||||||||||||||||||||||||||
| 708 | |||||||||||||||||||||||||||||||||||
| 709 | Calling C<run()> a second time while already running throws synchronously. | ||||||||||||||||||||||||||||||||||
| 710 | |||||||||||||||||||||||||||||||||||
| 711 | When run() resolves, all registered handlers and error callbacks are | ||||||||||||||||||||||||||||||||||
| 712 | cleared to break closure-based reference cycles. | ||||||||||||||||||||||||||||||||||
| 713 | |||||||||||||||||||||||||||||||||||
| 714 | =cut | ||||||||||||||||||||||||||||||||||
| 715 | |||||||||||||||||||||||||||||||||||
| 716 | # --------------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||
| 717 | # Event dispatcher - on(), on_error(), stop(), run() | ||||||||||||||||||||||||||||||||||
| 718 | # --------------------------------------------------------------------------- | ||||||||||||||||||||||||||||||||||
| 719 | |||||||||||||||||||||||||||||||||||
| 720 | # Terminal event type by scope type (websocket.*, sse.*, http.* are reserved) | ||||||||||||||||||||||||||||||||||
| 721 | 28 | my %_TERMINAL = ( | |||||||||||||||||||||||||||||||||
| 722 | websocket => 'websocket.disconnect', | ||||||||||||||||||||||||||||||||||
| 723 | sse => 'sse.disconnect', | ||||||||||||||||||||||||||||||||||
| 724 | http => 'http.disconnect', | ||||||||||||||||||||||||||||||||||
| 725 | ); | ||||||||||||||||||||||||||||||||||
| 726 | |||||||||||||||||||||||||||||||||||
| 727 | 40 | ▶ | sub _terminal_event_type { | ||||||||||||||||||||||||||||||||
|
Subroutine
_terminal_event_type: called CC=2 SCAR=7.2
| |||||||||||||||||||||||||||||||||||
| 728 | 40 | my ($self) = @_; | |||||||||||||||||||||||||||||||||
| 729 | 40 | ▶ | return $_TERMINAL{ $self->type // '' }; | ||||||||||||||||||||||||||||||||
|
Condition50%1/2
$self->type // ""
MC/DC0%0/1
$self->type // ""
$self->type
Truth table50%1/2
A
A= $self->type
| |||||||||||||||||||||||||||||||||||
| 730 | } | ||||||||||||||||||||||||||||||||||
| 731 | |||||||||||||||||||||||||||||||||||
| 732 | # Register a handler for a raw PAGI event type string. | ||||||||||||||||||||||||||||||||||
| 733 | # Returns $self for chaining. | ||||||||||||||||||||||||||||||||||
| 734 | 27 | ▶ | sub on { | ||||||||||||||||||||||||||||||||
|
Subroutine
on: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 735 | 27 | my ($self, $type, $cb) = @_; | |||||||||||||||||||||||||||||||||
| 736 | 27 | push @{ $self->{_handlers}{$type} }, $cb; | |||||||||||||||||||||||||||||||||
| 737 | 27 | return $self; | |||||||||||||||||||||||||||||||||
| 738 | } | ||||||||||||||||||||||||||||||||||
| 739 | |||||||||||||||||||||||||||||||||||
| 740 | # Register a single fallback handler for events with no type-specific handler | ||||||||||||||||||||||||||||||||||
| 741 | # (except the terminal disconnect). Last registration wins. Returns $self. | ||||||||||||||||||||||||||||||||||
| 742 | 5 | ▶ | sub on_default { | ||||||||||||||||||||||||||||||||
|
Subroutine
on_default: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 743 | 5 | my ($self, $cb) = @_; | |||||||||||||||||||||||||||||||||
| 744 | 5 | $self->{_on_default} = $cb; | |||||||||||||||||||||||||||||||||
| 745 | 5 | return $self; | |||||||||||||||||||||||||||||||||
| 746 | } | ||||||||||||||||||||||||||||||||||
| 747 | |||||||||||||||||||||||||||||||||||
| 748 | # Register an error handler. Called for both $receive->() failures | ||||||||||||||||||||||||||||||||||
| 749 | # (source='receive') and handler exceptions (source='handler'). | ||||||||||||||||||||||||||||||||||
| 750 | # Returns $self for chaining. | ||||||||||||||||||||||||||||||||||
| 751 | 14 | ▶ | sub on_error { | ||||||||||||||||||||||||||||||||
|
Subroutine
on_error: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 752 | 14 | my ($self, $cb) = @_; | |||||||||||||||||||||||||||||||||
| 753 | 14 | push @{ $self->{_on_error} }, $cb; | |||||||||||||||||||||||||||||||||
| 754 | 14 | return $self; | |||||||||||||||||||||||||||||||||
| 755 | } | ||||||||||||||||||||||||||||||||||
| 756 | |||||||||||||||||||||||||||||||||||
| 757 | # Signal the run() loop to exit after the current handler finishes. | ||||||||||||||||||||||||||||||||||
| 758 | 2 | ▶ | sub stop { | ||||||||||||||||||||||||||||||||
|
Subroutine
stop: called CC=1 SCAR=0.0
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 759 | 2 | my ($self) = @_; | |||||||||||||||||||||||||||||||||
| 760 | 2 | $self->{_stopped} = 1; | |||||||||||||||||||||||||||||||||
| 761 | 2 | return $self; | |||||||||||||||||||||||||||||||||
| 762 | } | ||||||||||||||||||||||||||||||||||
| 763 | |||||||||||||||||||||||||||||||||||
| 764 | # Internal: fire error callbacks with ($ctx, $error, $source). | ||||||||||||||||||||||||||||||||||
| 765 | 13 | ▶ | async sub _trigger_ctx_error { | ||||||||||||||||||||||||||||||||
|
Subroutine
_trigger_ctx_error: called CC=6 SCAR=17.9
| |||||||||||||||||||||||||||||||||||
| 766 | 13 | my ($self, $error, $source) = @_; | |||||||||||||||||||||||||||||||||
| 767 | |||||||||||||||||||||||||||||||||||
| 768 | 13 | for my $cb (@{ $self->{_on_error} }) { | |||||||||||||||||||||||||||||||||
| 769 | 12 | eval { | |||||||||||||||||||||||||||||||||
| 770 | 12 | my $r = $cb->($self, $error, $source); | |||||||||||||||||||||||||||||||||
| 771 | 11 | ▶ | if (blessed($r) && $r->isa('Future')) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
builtin::blessed($r) and $r->isa("Future")
MC/DC50%1/2
builtin::blessed($r) and $r->isa("Future")
builtin::blessed($r)
$r->isa("Future")
Truth table66%2/3
A and B
A= builtin::blessed($r)B= $r->isa("Future")
| |||||||||||||||||||||||||||||||||||
| 772 | 2 | await $r; | |||||||||||||||||||||||||||||||||
| 773 | } | ||||||||||||||||||||||||||||||||||
| 774 | }; | ||||||||||||||||||||||||||||||||||
| 775 | 12 | ▶ | if ($@) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 776 | 2 | warn "PAGI::Context on_error callback error: $@"; | |||||||||||||||||||||||||||||||||
| 777 | } | ||||||||||||||||||||||||||||||||||
| 778 | } | ||||||||||||||||||||||||||||||||||
| 779 | |||||||||||||||||||||||||||||||||||
| 780 | 13 | ▶ | if (!@{ $self->{_on_error} }) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 781 | 4 | warn "PAGI::Context error ($source): $error"; | |||||||||||||||||||||||||||||||||
| 782 | } | ||||||||||||||||||||||||||||||||||
| 783 | 28 | } | |||||||||||||||||||||||||||||||||
| 784 | |||||||||||||||||||||||||||||||||||
| 785 | # Hook for protocol subclasses (Context::WebSocket, Context::SSE) to sync | ||||||||||||||||||||||||||||||||||
| 786 | # their underlying object's close state when the terminal disconnect event | ||||||||||||||||||||||||||||||||||
| 787 | # is consumed here in _run() rather than through the object's own | ||||||||||||||||||||||||||||||||||
| 788 | # receive()/run(). The base class has no underlying object, so this is a | ||||||||||||||||||||||||||||||||||
| 789 | # no-op; overridden by the subclasses that have one. | ||||||||||||||||||||||||||||||||||
| 790 | 0 | ▶ | async sub _sync_terminal_disconnect { return; } | ||||||||||||||||||||||||||||||||
|
Subroutine
_sync_terminal_disconnect: not called CC=1 SCAR=2.6
| |||||||||||||||||||||||||||||||||||
| 791 | |||||||||||||||||||||||||||||||||||
| 792 | # Run the event dispatch loop. A plain sub so a re-entrant call croaks | ||||||||||||||||||||||||||||||||||
| 793 | # synchronously (rather than as a failed Future); the async loop is in _run(). | ||||||||||||||||||||||||||||||||||
| 794 | # Always resolves (never rejects). Returns reason: 'disconnect', 'stop', 'error'. | ||||||||||||||||||||||||||||||||||
| 795 | 42 | ▶ | sub run { | ||||||||||||||||||||||||||||||||
|
Subroutine
run: called CC=2 SCAR=6.9
Pod
documented
| |||||||||||||||||||||||||||||||||||
| 796 | 42 | my ($self) = @_; | |||||||||||||||||||||||||||||||||
| 797 | croak "PAGI::Context run() called while already running" | ||||||||||||||||||||||||||||||||||
| 798 | 42 | ▶ | if $self->{_running}; | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 799 | 40 | $self->{_running} = 1; | |||||||||||||||||||||||||||||||||
| 800 | 40 | return $self->_run; | |||||||||||||||||||||||||||||||||
| 801 | } | ||||||||||||||||||||||||||||||||||
| 802 | |||||||||||||||||||||||||||||||||||
| 803 | 40 | ▶ | async sub _run { | ||||||||||||||||||||||||||||||||
|
Subroutine
_run: called CC=22 SCAR=31.0
| |||||||||||||||||||||||||||||||||||
| 804 | 40 | my ($self) = @_; | |||||||||||||||||||||||||||||||||
| 805 | 40 | $self->{_stopped} = 0; | |||||||||||||||||||||||||||||||||
| 806 | 40 | ▶ | $self->{_on_error} //= []; | ||||||||||||||||||||||||||||||||
|
Condition100%2/2
$self->{"_on_error"} //= []
MC/DC100%1/1
$self->{"_on_error"} //= []
$self->{"_on_error"}
Truth table100%2/2
A
A= $self->{"_on_error"}
| |||||||||||||||||||||||||||||||||||
| 807 | |||||||||||||||||||||||||||||||||||
| 808 | 40 | my $reason = 'stop'; | |||||||||||||||||||||||||||||||||
| 809 | 40 | my $terminal = $self->_terminal_event_type; | |||||||||||||||||||||||||||||||||
| 810 | |||||||||||||||||||||||||||||||||||
| 811 | 40 | ▶ | LOOP: while (!$self->{_stopped}) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 812 | 60 | my $event = eval { await $self->{receive}->() }; | |||||||||||||||||||||||||||||||||
| 813 | 60 | ▶ | if (my $err = $@) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 814 | 9 | await $self->_trigger_ctx_error($err, 'receive'); | |||||||||||||||||||||||||||||||||
| 815 | 9 | $reason = 'error'; | |||||||||||||||||||||||||||||||||
| 816 | 9 | last LOOP; | |||||||||||||||||||||||||||||||||
| 817 | } | ||||||||||||||||||||||||||||||||||
| 818 | |||||||||||||||||||||||||||||||||||
| 819 | 51 | ▶ | my $type = $event->{type} // ''; | ||||||||||||||||||||||||||||||||
|
Condition50%1/2
$event->{"type"} // ""
MC/DC0%0/1
$event->{"type"} // ""
$event->{"type"}
Truth table50%1/2
A
A= $event->{"type"}
| |||||||||||||||||||||||||||||||||||
| 820 | |||||||||||||||||||||||||||||||||||
| 821 | # Snapshot before iterating - on() calls from inside a handler | ||||||||||||||||||||||||||||||||||
| 822 | # must not affect the current iteration. | ||||||||||||||||||||||||||||||||||
| 823 | 51 | ▶ | my @handlers = @{ $self->{_handlers}{$type} // [] }; | ||||||||||||||||||||||||||||||||
|
Condition100%2/2
$self->{"_handlers"}{$type} // []
MC/DC100%1/1
$self->{"_handlers"}{$type} // []
$self->{"_handlers"}{$type}
Truth table100%2/2
A
A= $self->{"_handlers"}{$type}
| |||||||||||||||||||||||||||||||||||
| 824 | |||||||||||||||||||||||||||||||||||
| 825 | 51 | ▶ | if (@handlers) { | ||||||||||||||||||||||||||||||||
|
Branch: 3 branches
| |||||||||||||||||||||||||||||||||||
| 826 | 20 | for my $cb (@handlers) { | |||||||||||||||||||||||||||||||||
| 827 | 22 | eval { | |||||||||||||||||||||||||||||||||
| 828 | 22 | my $r = $cb->($self, $event); | |||||||||||||||||||||||||||||||||
| 829 | 19 | ▶ | if (blessed($r) && $r->isa('Future')) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition100%3/3
builtin::blessed($r) and $r->isa("Future")
MC/DC100%2/2
builtin::blessed($r) and $r->isa("Future")
builtin::blessed($r)
$r->isa("Future")
Truth table100%3/3
A and B
A= builtin::blessed($r)B= $r->isa("Future")
| |||||||||||||||||||||||||||||||||||
| 830 | 1 | await $r; | |||||||||||||||||||||||||||||||||
| 831 | } | ||||||||||||||||||||||||||||||||||
| 832 | }; | ||||||||||||||||||||||||||||||||||
| 833 | 22 | ▶ | if (my $err = $@) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 834 | 3 | await $self->_trigger_ctx_error($err, 'handler'); | |||||||||||||||||||||||||||||||||
| 835 | } | ||||||||||||||||||||||||||||||||||
| 836 | } | ||||||||||||||||||||||||||||||||||
| 837 | ▶ | } elsif ($self->{_on_default} && !($terminal && $type eq $terminal)) { | |||||||||||||||||||||||||||||||||
|
Condition83%5/6
$self->{"_on_default"} and not $terminal && $type eq $terminal
$terminal && $type eq $terminal
MC/DC66%2/3
$self->{"_on_default"} and not $terminal && $type eq $terminal
$self->{"_on_default"}
$terminal
$type eq $terminal
Truth table75%3/4
A and not(B && C)
A= $self->{"_on_default"}B= $terminalC= $type eq $terminal
| |||||||||||||||||||||||||||||||||||
| 838 | 2 | eval { | |||||||||||||||||||||||||||||||||
| 839 | 2 | my $r = $self->{_on_default}->($self, $event); | |||||||||||||||||||||||||||||||||
| 840 | 2 | ▶ | if (blessed($r) && $r->isa('Future')) { await $r; } | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
builtin::blessed($r) and $r->isa("Future")
MC/DC50%1/2
builtin::blessed($r) and $r->isa("Future")
builtin::blessed($r)
$r->isa("Future")
Truth table66%2/3
A and B
A= builtin::blessed($r)B= $r->isa("Future")
| |||||||||||||||||||||||||||||||||||
| 841 | }; | ||||||||||||||||||||||||||||||||||
| 842 | 2 | ▶ | if (my $err = $@) { await $self->_trigger_ctx_error($err, 'handler'); } | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
| |||||||||||||||||||||||||||||||||||
| 843 | ▶ | } elsif ($ENV{PAGI_DEBUG} && !($terminal && $type eq $terminal)) { | |||||||||||||||||||||||||||||||||
|
Condition83%5/6
$ENV{"PAGI_DEBUG"} and not $terminal && $type eq $terminal
$terminal && $type eq $terminal
MC/DC66%2/3
$ENV{"PAGI_DEBUG"} and not $terminal && $type eq $terminal
$ENV{"PAGI_DEBUG"}
$terminal
$type eq $terminal
Truth table75%3/4
A and not(B && C)
A= $ENV{"PAGI_DEBUG"}B= $terminalC= $type eq $terminal
| |||||||||||||||||||||||||||||||||||
| 844 | 1 | warn "PAGI::Context: unhandled event type '$type'\n"; | |||||||||||||||||||||||||||||||||
| 845 | } | ||||||||||||||||||||||||||||||||||
| 846 | |||||||||||||||||||||||||||||||||||
| 847 | 51 | ▶ | if ($terminal && $type eq $terminal) { | ||||||||||||||||||||||||||||||||
|
Branch: 1 branch
Condition66%2/3
$terminal and $type eq $terminal
MC/DC50%1/2
$terminal and $type eq $terminal
$terminal
$type eq $terminal
Truth table66%2/3
A and B
A= $terminalB= $type eq $terminal
| |||||||||||||||||||||||||||||||||||
| 848 | 29 | $reason = 'disconnect'; | |||||||||||||||||||||||||||||||||
| 849 | 29 | await $self->_sync_terminal_disconnect($event->{code}, $event->{reason}); | |||||||||||||||||||||||||||||||||
| 850 | 29 | last LOOP; | |||||||||||||||||||||||||||||||||
| 851 | } | ||||||||||||||||||||||||||||||||||
| 852 | } | ||||||||||||||||||||||||||||||||||
| 853 | |||||||||||||||||||||||||||||||||||
| 854 | # Clear callbacks to break any closure-based reference cycles. | ||||||||||||||||||||||||||||||||||
| 855 | 40 | $self->{_handlers} = {}; | |||||||||||||||||||||||||||||||||
| 856 | 40 | $self->{_on_error} = []; | |||||||||||||||||||||||||||||||||
| 857 | 40 | $self->{_on_default} = undef; | |||||||||||||||||||||||||||||||||
| 858 | 40 | $self->{_running} = 0; | |||||||||||||||||||||||||||||||||
| 859 | 40 | $self->{_stopped} = 0; | |||||||||||||||||||||||||||||||||
| 860 | |||||||||||||||||||||||||||||||||||
| 861 | 40 | return $reason; | |||||||||||||||||||||||||||||||||
| 862 | 28 | } | |||||||||||||||||||||||||||||||||
| 863 | |||||||||||||||||||||||||||||||||||
| 864 | # Load subclasses | ||||||||||||||||||||||||||||||||||
| 865 | 28 | require PAGI::Context::HTTP; | |||||||||||||||||||||||||||||||||
| 866 | 28 | require PAGI::Context::WebSocket; | |||||||||||||||||||||||||||||||||
| 867 | 28 | require PAGI::Context::SSE; | |||||||||||||||||||||||||||||||||
| 868 | |||||||||||||||||||||||||||||||||||
| 869 | 28 | 1; | |||||||||||||||||||||||||||||||||
| 870 | |||||||||||||||||||||||||||||||||||
| 871 | __END__ | ||||||||||||||||||||||||||||||||||