Implement middleware helper

Changes

@@ -1,11 +1,16 @@
 Revision history for Kelp
 
 {{$NEXT}}
+            [New Interface]
+            - Added middleware_obj attribute to Kelp
+
+            [Changes]
+            - Middleware building is now done using Kelp::Middleware
 
 2.18 - 2024-10-08
             [New Interface]
             - Added after_unrendered hook to Kelp
-            - Added order attribute and compare method to routes
+            - Added order attribute and compare method to Kelp::Routes::Pattern
 
             [Changes]
             - Fixed bridge without trailing slash being used for longer routes on the same level

lib/Kelp.pm

@@ -21,6 +21,7 @@ attr -name => sub { (ref($_[0]) =~ /(\w+)$/) ? $1 : 'Noname' };
 attr request_obj => 'Kelp::Request';
 attr response_obj => 'Kelp::Response';
 attr context_obj => 'Kelp::Context';
+attr middleware_obj => 'Kelp::Middleware';
 
 # Debug
 attr long_error => $ENV{KELP_LONG_ERROR} // 0;
@@ -267,25 +268,11 @@ sub run
 
     Kelp::Util::_DEBUG(1 => 'Running the application...');
 
-    # Add middleware
-    if (defined(my $middleware = $self->config('middleware'))) {
-        for my $class (@$middleware) {
-
-            # Make sure the middleware was not already loaded
-            # This does not apply for testing, in which case we want
-            # the middleware to wrap every single time
-            next if $self->{_loaded_middleware}->{$class}++ && !$ENV{KELP_TESTING};
-
-            my $mw = Plack::Util::load_class($class, 'Plack::Middleware');
-            my $args = $self->config("middleware_init.$class") // {};
-
-            Kelp::Util::_DEBUG(modules => "Wrapping app in $mw middleware with args: ", $args);
-
-            $app = $mw->wrap($app, %$args);
-        }
-    }
+    my $middleware = Kelp::Util::load_package($self->middleware_obj)->new(
+        app => $self,
+    );
 
-    return $app;
+    return $middleware->wrap($app);
 }
 
 sub psgi
@@ -581,6 +568,11 @@ L<Kelp::Module::Config> for more information.
 Provide a custom package name to define the ::Context object. Defaults to
 L<Kelp::Context>.
 
+=head2 middleware_obj
+
+Provide a custom package name to define the middleware object. Defaults to
+L<Kelp::Middleware>.
+
 =head2 request_obj
 
 Provide a custom package name to define the ::Request object. Defaults to
@@ -852,8 +844,8 @@ every route.
 
 =head2 run
 
-This method builds and returns the PSGI app. You can override it in order to
-include middleware. See L<Kelp::Manual/Adding middleware> for an example.
+This method builds and returns the PSGI app. You can override it to get more
+control over PSGI representation of the app.
 
 =head2 param
 

lib/Kelp/Manual.pod

@@ -650,7 +650,7 @@ information and examples.
 
 =head2 Adding middleware
 
-Kelp, being Plack-centric, will let you easily add middleware. There are three
+Kelp, being Plack-centric, will let you easily add middleware. There are four
 possible ways to add middleware to your application, and all three ways can be
 used separately or together.
 
@@ -672,9 +672,30 @@ the corresponding initializing arguments in the C<middleware_init> hash:
     }
 
 The middleware will be added in the order you specify in the C<middleware>
-array.
+array. See L<Kelp::Middleware/Advanced> for details.
 
-=head3 In C<app.psgi>:
+=head3 By subclassing L<Kelp::Middleware>
+
+L<Kelp::Middleware> is a class which handles wrapping application in middleware
+based on config. Subclassing it may be the most powerful way to add more
+middleware if configuration is not enough.
+
+    # lib/MyApp.pm
+    attr middleware_obj => 'MyMiddleware';
+
+    # lib/MyMiddleware.pm
+    use Kelp::Base 'Kelp::Middleware';
+
+    sub wrap {
+        my $self = shift;
+        my $app = $self->SUPER::wrap(@_);
+        $app = Plack::Middleware::ContentLength->wrap($app);
+        return $app;
+    }
+
+This lets you add middleware before or after config middleware (or disable config middleware completely).
+
+=head3 In C<app.psgi>
 
     # app.psgi
     use MyApp;
@@ -687,7 +708,7 @@ array.
         $app->run;
     };
 
-=head3 By overriding the L<Kelp/run> subroutine in C<lib/MyApp.pm>:
+=head3 By overriding the L<Kelp/run> subroutine in C<lib/MyApp.pm>
 
 Make sure you call C<SUPER> first, and then wrap new middleware around the
 returned app.

lib/Kelp/Middleware.pm

@@ -0,0 +1,76 @@
+package Kelp::Middleware;
+
+use Kelp::Base;
+use Plack::Util;
+use Kelp::Util;
+use Carp;
+
+attr -app => sub { croak 'app is required' };
+
+sub wrap
+{
+    my ($self, $psgi) = @_;
+
+    if (defined(my $middleware = $self->app->config('middleware'))) {
+        for my $class (@$middleware) {
+
+            # Make sure the middleware was not already loaded
+            # This does not apply for testing, in which case we want
+            # the middleware to wrap every single time
+            next if $self->{_loaded_middleware}->{$class}++ && !$ENV{KELP_TESTING};
+
+            my $mw = Plack::Util::load_class($class, 'Plack::Middleware');
+            my $args = $self->app->config("middleware_init.$class") // {};
+
+            Kelp::Util::_DEBUG(modules => "Wrapping app in $mw middleware with args: ", $args);
+
+            $psgi = $mw->wrap($psgi, %$args);
+        }
+    }
+
+    return $psgi;
+}
+
+1;
+
+__END__
+
+=pod
+
+=head1 NAME
+
+Kelp::Middleware - Kelp app wrapper (PSGI middleware)
+
+=head1 SYNOPSIS
+
+    middleware => [qw(TrailingSlashKiller Static)],
+    middleware_init => {
+        TrailingSlashKiller => {
+            redirect => 1,
+        },
+        Static => {
+            path => qr{^/static},
+            root => '.',
+        },
+    }
+
+=head1 DESCRIPTION
+
+This is a small helper object which wraps Kelp in PSGI middleware. It is loaded
+and constructed by Kelp based on the value of L<Kelp/middleware_obj> (class
+name).
+
+=head1 ATTRIBUTES
+
+=head2 app
+
+Main application object. Required.
+
+=head1 METHODS
+
+=head2 wrap
+
+    $wrapped_psgi = $object->wrap($psgi)
+
+Wraps the object in all middlewares according to L</app> configuration.
+