Merge pull request #5 from Thunderhorse-Framework/feature/pagi-tools

Adjust TH to the newest PAGI::Tools

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]

cpanfile

@@ -3,7 +3,7 @@ on 'test' => sub {
 };
 
 requires 'perl' => '5.040';
-requires 'PAGI' => '0.001023';
+requires 'PAGI::Tools' => '0.002000';
 requires 'Gears' => '0.104';
 requires 'Mooish::Base' => '1.005';
 requires 'Future::AsyncAwait' => 0;

ex/full-app/lib/FullApp/Controller/API.pm

@@ -27,7 +27,7 @@ sub flatten_locations ($self, $level)
 	return @out;
 }
 
-async sub list_locations ($self, $ctx)
+sub list_locations ($self, $ctx)
 {
 	my @locations = map {
 		+{
@@ -39,6 +39,6 @@ async sub list_locations ($self, $ctx)
 		}
 	} $self->flatten_locations($self->router);
 
-	await $ctx->res->json(\@locations);
+	$ctx->res->json(\@locations);
 }
 

lib/Thunderhorse.pm

@@ -110,6 +110,15 @@ sub build_handler ($controller, $destination)
 			}
 		}
 
+		# 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
 		# free to go deeper. Avoid first match, as it was handled already
 		# above
@@ -214,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
@@ -388,29 +401,29 @@ Return value of the destination sub is by default sent to the requestor as
 C<text/html> with status code C<200>. This is a common and handy shortcut, but
 it is equally easy to do something else. Take the following destination example:
 
-	async sub send_custom ($self, $ctx)
+	async sub build_custom ($self, $ctx)
 	{
-		await $ctx->res->text('Plaintext response');
+		$ctx->res->text('Plaintext response');
 		return 'this will not get rendered';
 	}
 
-This takes response (L<Thunderhorse::Response>) from context, and sends
-plaintext manually. This action I<consumes> the context, marking it as
-finished. In this case, return value of the destination is ignored. Note that
-the await call on C<< ->text >> method is mandatory.
+This takes response (L<Thunderhorse::Response>) from context, and sets
+plaintext body manually. This action I<consumes> the context, marking it as
+finished. In this case, return value of the destination is ignored.
+
 
 Another example:
 
-	sub send_custom2 ($self, $ctx)
+	sub set_custom2 ($self, $ctx)
 	{
-		$ctx->res->status(400)->content_type('text/plain');
-		return 'this is rendered as plaintext and status 400';
+		$ctx->res->content_type('text/plain');
+		return 'this is rendered as plaintext';
 	}
 
 This time, the return value of the destination is not ignored, since only
 setting response metadata does not cause the context to be consumed. Status and
 I<Content-Type> header will not be overridden, so the response will be sent as
-plaintext. In this case, there is no need to await anything.
+plaintext.
 
 While not very common, a destination can be unimplemented when C<to> is
 skipped. Unimplemented locations will be "stepped over" during request
@@ -523,10 +536,10 @@ bridge is created when you call C<add> on the result of another C<add>:
 
 When C</admin/users> is requested, both C<check_admin> and C<list_users> will
 be called in sequence. The bridge destination receives the same arguments as
-regular destinations. If the bridge consumes the context (by sending a
-response), further matching stops. Otherwise, the next matching location is
-called. For this reason, bridge destinations should return C<undef> explicitly
-to avoid consuming the context by accident:
+regular destinations. If the bridge consumes the context, further matching
+stops. Otherwise, the next matching location is called. For this reason, bridge
+destinations should return C<undef> explicitly to avoid consuming the context
+by accident:
 
 	sub check_admin ($self, $ctx)
 	{
@@ -644,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
@@ -765,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
@@ -1286,7 +1323,7 @@ This hook's method B<cannot be declared on a controller level>.
 The C<on_error> hook is called when an exception occurs during request
 processing.
 
-This hook should consume the context by sending a response. The default handler
+This hook should consume the context by setting a response. The default handler
 calls L</render_error> method a text page with an error message.
 
 =head3 Overriding system methods
@@ -1311,7 +1348,7 @@ following things:
 
 =item * tries to set C<Content-Type> header to C<text/html> (if it was not set already)
 
-=item * awaits sending C<$result> to the client using L<PAGI::Response/send> method (as text)
+=item * sets C<$result> as the response body
 
 =back
 
@@ -1323,11 +1360,12 @@ references and render them as JSON/YAML.
 	async sub render_error($self, $ctx, $code, $message = undef) { ... }
 	async sub render_error($self, $controller, $ctx, $code, $message = undef) { ... }
 
-This method's default implementation sends a plain text response with code
+This method's default implementation builds a plain text response with code
 C<500>. The default implementation checks C<is_production> method of the
 application to avoid rendering the original error message which may contain
 sensitive information. It also acknowledges the existence of L<Gears::X::HTTP>,
-which may change the error code to something else.
+which may change the error code to something else. Original response is
+discarded and a new one is built.
 
 =head2 Performance tuning
 

lib/Thunderhorse/App.pm

@@ -208,6 +208,7 @@ async sub pagi ($self, $scope, $receive, $send)
 	# the context
 	if (!$ctx->is_consumed) {
 		await $self->render_error(undef, $ctx, 404);
+		await $ctx->send_res;
 	}
 
 	return;
@@ -240,15 +241,12 @@ sub run ($self)
 async sub render_error ($self, $controller, $ctx, $code, $message = undef)
 {
 	$message = defined $message && !$self->is_production ? $message : status_message($code);
-	await $ctx->res->status($code)->text($message);
+	$ctx->empty_res->status($code)->text($message);
 }
 
 async sub render_response ($self, $controller, $ctx, $result)
 {
-	await $ctx->res
-		->status_try(200)
-		->content_type_try('text/html')
-		->send($result);
+	$ctx->res->status_try(200)->html($result);
 }
 
 #########################

lib/Thunderhorse/Context.pm

@@ -5,6 +5,7 @@ use Mooish::Base -standard;
 
 use Devel::StrictMode;
 
+use Future::AsyncAwait;
 use Thunderhorse::Request;
 use Thunderhorse::Response;
 use Thunderhorse::WebSocket;
@@ -30,9 +31,15 @@ has field 'req' => (
 	default => sub ($self) { Thunderhorse::Request->new(context => $self) },
 );
 
+has field 'connection' => (
+	(STRICT ? (isa => HasMethods ['response_started']) : ()),
+	lazy => sub ($self) { $self->scope->{'pagi.connection'} },
+);
+
 has field 'res' => (
 	(STRICT ? (isa => InstanceOf ['Thunderhorse::Response']) : ()),
-	default => sub ($self) { Thunderhorse::Response->new(context => $self) },
+	lazy => sub ($self) { Thunderhorse::Response->new(context => $self) },
+	clearer => -hidden,
 );
 
 # NOTE: websocket must be lazy, because it will die if scope is not websocket
@@ -105,11 +112,41 @@ sub consume ($self)
 sub is_consumed ($self)
 {
 	return $self->_consumed
-		|| $self->res->is_sent
+		|| $self->connection->response_started
+		|| $self->res->is_ready
 		|| ($self->has_ws && $self->ws->is_closed)
 		|| ($self->has_sse && $self->sse->is_closed);
 }
 
+sub empty_res ($self)
+{
+	$self->_clear_res;
+	return $self->res;
+}
+
+async sub send_res ($self)
+{
+	# NOTE: we check a general pagi constraint, but raise a thunderhorse exception -
+	# should it just die()?
+	Gears::X::Thunderhorse->raise('response was already sent')
+		if $self->connection->response_started;
+
+	await $self->res->respond($self->sender);
+
+	return;
+}
+
+async sub try_send_res ($self)
+{
+	return
+		if $self->connection->response_started;
+
+	await $self->res->respond($self->sender)
+		if $self->res->is_ready;
+
+	return;
+}
+
 __END__
 
 =head1 NAME
@@ -124,7 +161,7 @@ Thunderhorse::Context - Request handling context
 		my $stashed_value = $ctx->stash->get('key');
 		my $session_value = $ctx->session->get('key');
 
-		await $ctx->res->text("Hello World");
+		$ctx->res->text("Hello World");
 	}
 
 =head1 DESCRIPTION
@@ -202,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
@@ -252,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/Controller.pm

@@ -117,7 +117,7 @@ Thunderhorse::Controller - Base controller class for Thunderhorse
 
 	async sub show ($self, $ctx, $id)
 	{
-		await $ctx->res->text("User ID: $id");
+		$ctx->res->text("User ID: $id");
 	}
 
 =head1 DESCRIPTION

lib/Thunderhorse/Cookbook.pod

@@ -21,7 +21,7 @@ L<Thunderhorse::App/render_error>:
 			$html = $controller->template('error/error', {title => status_message($code)});
 		}
 
-		await $ctx->res->status($code)->html($html);
+		$ctx->res->status($code)->html($html);
 	}
 
 For example for error 404, code above will try to render C<error/404.tt>

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