Adjust docs and tests regarding PAGI distro split

Author: bbrtj

Changes

@@ -1,6 +1,16 @@
 Revision history for Thunderhorse
 
 {{$NEXT}}
+	[Public interface changes]
+	- Added connection attribute to Context
+	- Added empty_res, send_res, try_send_res methods to Context
+	- Added is_ready method to Response
+
+	[Breaking changes]
+	- Response is now a value (via PAGI::Tools change)
+		- awaiting response's calls which used to send data like "text", "html" etc. is now wrong - remove "await" calls
+	- Thunderhorse dependencies no longer ensure pagi-server will be installed (via PAGI distribution split)
+		- pagi-server is now a part of a separate PAGI::Server module, which is not a direct dependency for Thunderhorse
 
 0.105 - 2026-05-25
 	[Changes]

lib/Thunderhorse.pm

@@ -110,7 +110,13 @@ sub build_handler ($controller, $destination)
 			}
 		}
 
-		# this needs to be here, since we want to use $send from this context
+		# NOTE: this method will not send the response if we already sent or if
+		# the response is not ready. It does not check whether the context is
+		# consumed altogether, so a manually consumed context with a non-ready
+		# response will not send anything, likely rendering some kind of error
+		# page (but not 404). Currently, a PAGI error is raised, informing
+		# about app returning without sending respnose.
+		# NOTE: this needs to be here, since we want to use $send from this context
 		await $ctx->try_send_res;
 
 		# if this is a bridge and bridge did not render, it means we are
@@ -217,6 +223,10 @@ Scripts must be called using C<pagi-server> (or other PAGI-specific software).
 Running the script using C<perl> does nothing, as the application cannot run
 itself - it will be built, but it will not set up a webserver.
 
+C<pagi-server> can be obtained separately from L<PAGI::Server> module.
+Thunderhorse does not automatically include PAGI::Server as its dependency,
+since it is not coupled with any specific PAGI server implementation.
+
 =back
 
 =head2 The thunderhorse script
@@ -647,7 +657,7 @@ would expect.
 One unique feature of Thunderhorse is that it does not stop searching for
 matches once it finds a match. Instead, it gathers a list of matching locations
 and then proceeds to execute them in order. It stops once one of the handlers
-consumes the context, which is usually done by sending a response. If no
+consumes the context, which is usually done by setting a response body. If no
 handlers consumed the context, a I<404 Not Found> error page is rendered.
 
 This allows for superb flexibility, but has a couple of interesting side
@@ -768,6 +778,30 @@ matching. If we let C<important_auth> run before C<login_page>, for example by
 setting its order to C<-2>, it will effectively become a bridge for
 C<login_page>.
 
+Currently, the context can be consumed by:
+
+=over
+
+=item * Setting the response body in L<Thunderhorse::Context/res>
+
+=item * Setting the response status to one of the statuses which does not require a body
+
+=item * Closing a websocket connection in L<Thunderhorse::Context/ws>
+
+=item * Closing a sse connection in L<Thunderhorse::Context/sse>
+
+=item * Manually sending any response via PAGI, triggering C<response_started> in C<pagi.connection> scope key
+
+=item * Manually consuming the context via L<Thunderhorse::Context/consume> call
+
+=back
+
+This system should be pretty bulletproof, however once you use the last option
+and call L<Thunderhorse::Context/consume>, all safety measures are off - it's
+now your responsibility to make sure the route handler will render something
+eventually. If it doesn't, you will get a low-level PAGI exception and an error
+page completely bypassing any Thunderhorse error rendering. Use with caution.
+
 =head2 Controllers
 
 By default, all routes defined in the application's C<build> method belong to

lib/Thunderhorse/Context.pm

@@ -239,6 +239,13 @@ used, or other middleware that will populate C<pagi.session> scope key.
 L<PAGI::Session> will throw an exception if C<pagi.session> is not present in
 scope.
 
+=head3 connection
+
+Connection object for this context, taken from PAGI scope. Connection objects
+are inserted into the scope by the server, and there is no clear subclass they
+will inherit from. They follow a duck-typed interface though, and can be
+trusted to have at least C<response_started> method.
+
 =head2 Methods
 
 =head3 new
@@ -289,6 +296,31 @@ Returns true if the context has been consumed either explicitly via
 L</consume>, or implicitly by sending a response, closing a WebSocket
 connection, or closing an SSE stream.
 
+=head3 empty_res
+
+	$new_res = $ctx->empty_res()
+
+Discards the current response attached to the context, then builds and returns
+a fresh one. Useful if you want to completely discard response data.
+
+=head3 send_res
+
+	await $ctx->send_res()
+
+Tries to send the response back to the client. Dies if the response has already
+been sent. Force-sends the response even if it has an empty body.
+
+=head3 try_send_res
+
+	$ctx->try_send_res()
+
+Similar as L</send_res>, but does nothing if the response has already been
+sent. Also skips sending the response if it is not ready yet, according to
+L<Thunderhorse::Response/is_ready>.
+
+Note that you don't have to use this method explicitly. Thunderhorse will
+automatically use it after the route handler returns.
+
 =head1 SEE ALSO
 
 L<Thunderhorse>, L<Gears::Context>, L<Thunderhorse::Request>,

lib/Thunderhorse/Request.pm

@@ -89,11 +89,10 @@ constructor arguments.
 
 =head3 update
 
-	$req->update()
+	$req->update($scope, $receive, $send)
 
-Updates the internal PAGI scope and receiver from the context's PAGI tuple.
-Called automatically when the context's PAGI tuple changes via
-setter of L<Thunderhorse::Context/pagi>.
+Updates the internal PAGI scope and receiver. Called automatically when the
+context's PAGI tuple changes via setter of L<Thunderhorse::Context/pagi>.
 
 =head1 SEE ALSO
 

lib/Thunderhorse/Response.pm

@@ -58,7 +58,7 @@ Thunderhorse::Response - Response wrapper for Thunderhorse
 
 Thunderhorse::Response is a thin wrapper around L<PAGI::Response> that
 integrates with L<Thunderhorse::Context>. It provides a fluent interface for
-building and sending HTTP responses, including JSON, HTML, redirects, and file
+building HTTP responses, including JSON, HTML, redirects, and file
 downloads.
 
 This class extends L<PAGI::Response> and mixes in C<Thunderhorse::Message> to
@@ -88,11 +88,21 @@ constructor arguments.
 
 =head3 update
 
-	$res->update()
+	$res->update($scope, $receive, $send)
 
-Updates the internal PAGI scope and sender from the context's PAGI tuple.
-Called automatically when the context's PAGI tuple changes via
-setter of L<Thunderhorse::Context/pagi>.
+Updates the internal PAGI scope. Called automatically when the context's PAGI
+tuple changes via setter of L<Thunderhorse::Context/pagi>.
+
+=head3 is_ready
+
+	$bool = $res->is_ready()
+
+Returns whether this response is ready as far as Thunderhorse is concerned.
+Responses which are ready will cause the context to become consumed after the
+route handler returns.
+
+Response is ready if it has a body, or if it has a status which does not
+require body like C<204 No Content> or C<3XX>.
 
 =head1 SEE ALSO
 

lib/Thunderhorse/SSE.pm

@@ -76,11 +76,11 @@ constructor arguments.
 
 =head3 update
 
-	$sse->update()
+	$sse->update($scope, $receive, $send)
 
-Updates the internal PAGI scope, receiver, and sender from the context's PAGI
-tuple. Called automatically when the context's PAGI tuple changes via
-setter of L<Thunderhorse::Context/pagi>.
+Updates the internal PAGI scope, receiver, and sender. Called automatically
+when the context's PAGI tuple changes via setter of
+L<Thunderhorse::Context/pagi>.
 
 =head1 SEE ALSO
 

lib/Thunderhorse/WebSocket.pm

@@ -76,11 +76,11 @@ constructor arguments.
 
 =head3 update
 
-	$ws->update()
+	$ws->update($scope, $receive, $send)
 
-Updates the internal PAGI scope, receiver, and sender from the context's PAGI
-tuple. Called automatically when the context's PAGI tuple changes via
-setter of L<Thunderhorse::Context/pagi>.
+Updates the internal PAGI scope, receiver, and sender. Called automatically
+when the context's PAGI tuple changes via setter of
+L<Thunderhorse::Context/pagi>.
 
 =head1 SEE ALSO
 

t/edge.t

@@ -44,6 +44,8 @@ package EdgeApp {
 		$r->add('/only_post' => {to => 'print_method', action => 'http.post'});
 
 		$r->add('/future' => {to => 'return_future'});
+
+		$r->add('/bad_consume' => {to => 'bad_consume'});
 	}
 
 	sub stash_and_return ($self, $ctx, $msg)
@@ -68,6 +70,12 @@ package EdgeApp {
 	{
 		return $ctx->res->text('return text without await');
 	}
+
+	sub bad_consume ($self, $ctx)
+	{
+		# this consumes the context without sending anything
+		$ctx->consume;
+	}
 };
 
 my $app = EdgeApp->new;
@@ -130,5 +138,14 @@ subtest 'returning future from handler should work' => sub {
 	http_text_is 'return text without await';
 };
 
+subtest 'should throw an exception when the context is consumed without sending anything' => sub {
+	my $ex = dies {
+		http $app, GET '/bad_consume';
+		fail "call succeeded with error " . http->status;
+	};
+
+	like $ex, qr{App returned without sending response}, 'exception ok';
+};
+
 done_testing;
 

t/facade.t

@@ -17,7 +17,6 @@ package FacadeApp::Controller::Test::Facade {
 	{
 		await $self->app->loop->delay_future(after => 0.5);
 		$self->res->text('Something');
-		await $self->send_res;
 	}
 }
 
@@ -47,6 +46,38 @@ package FacadeApp::Controller::Test {
 			}
 		);
 
+		# ditto, but return a promise instead of awaiting
+		$router->add(
+			'/good2' => {
+				to => sub ($self, $ctx) {
+					return $ctx->send_something_later;
+				}
+			}
+		);
+
+		# this is also good, because calling send_res explicitly should not
+		# hurt TH as a whole.
+		$router->add(
+			'/good_send' => {
+				to => async sub ($self, $ctx) {
+					await $ctx->send_something_later;
+					await $ctx->send_res;
+				}
+			}
+		);
+
+		# ditto, but less confidently
+		$router->add(
+			'/good_send2' => {
+				to => async sub ($self, $ctx) {
+					$ctx->consume;
+					await $ctx->send_something_later;
+					await $ctx->try_send_res;
+					return;
+				}
+			}
+		);
+
 		# this is bad, because it consumes the context explicitly but does not
 		# await. This behavior is wrong on PAGI level, which forces fully
 		# rendered response before server finishes handling the app
@@ -92,6 +123,27 @@ subtest 'should render /good' => sub {
 	http_text_is 'Something';
 };
 
+subtest 'should render /good2' => sub {
+	http $app, GET '/good2';
+	http_status_is 200;
+	http_header_is 'Content-Type', 'text/plain; charset=utf-8';
+	http_text_is 'Something';
+};
+
+subtest 'should render /good_send' => sub {
+	http $app, GET '/good_send';
+	http_status_is 200;
+	http_header_is 'Content-Type', 'text/plain; charset=utf-8';
+	http_text_is 'Something';
+};
+
+subtest 'should render /good_send2' => sub {
+	http $app, GET '/good_send2';
+	http_status_is 200;
+	http_header_is 'Content-Type', 'text/plain; charset=utf-8';
+	http_text_is 'Something';
+};
+
 subtest 'should not render /consumed' => sub {
 	like dies {
 		http $app, GET '/consumed';