.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Plack::Middleware 3pm"
.TH Plack::Middleware 3pm 2024-01-20 "perl v5.38.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Plack::Middleware \- Base class for easy\-to\-use PSGI middleware
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  package Plack::Middleware::Foo;
\&  use parent qw( Plack::Middleware );
\&
\&  sub call {
\&      my($self, $env) = @_;
\&      # Do something with $env
\&
\&      # $self\->app is the original app
\&      my $res = $self\->app\->($env);
\&
\&      # Do something with $res
\&      return $res;
\&  }
\&
\&  # then in app.psgi
\&  use Plack::Builder;
\&
\&  my $app = sub { ... } # as usual
\&
\&  builder {
\&      enable "Plack::Middleware::Foo";
\&      enable "Plack::Middleware::Bar", %options;
\&      $app;
\&  };
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Plack::Middleware is a utility base class to write PSGI
middleware. All you have to do is to inherit from Plack::Middleware
and then implement the callback \f(CW\*(C`call\*(C'\fR method (or the \f(CW\*(C`to_app\*(C'\fR method
that would return the PSGI code reference) to do the actual work. You
can use \f(CW\*(C`$self\->app\*(C'\fR to call the original (wrapped) application.
.PP
Your middleware object is created at the PSGI application compile time
and is persistent during the web server life cycle (unless it is a
non-persistent environment such as CGI), so you should never set or
cache per-request data like \f(CW$env\fR in your middleware object. See
also "OBJECT LIFECYCLE" in Plack::Component.
.PP
See Plack::Builder how to actually enable middleware in your
\&\fI.psgi\fR application file using the DSL. If you do not like our
builder DSL, you can also use the \f(CW\*(C`wrap\*(C'\fR method to wrap your application
with a middleware:
.PP
.Vb 1
\&  use Plack::Middleware::Foo;
\&
\&  my $app = sub { ... };
\&  $app = Plack::Middleware::Foo\->wrap($app, %options);
\&  $app = Plack::Middleware::Bar\->wrap($app, %options);
.Ve
.SH "RESPONSE CALLBACK"
.IX Header "RESPONSE CALLBACK"
The typical middleware is written like this:
.PP
.Vb 2
\&  package Plack::Middleware::Something;
\&  use parent qw(Plack::Middleware);
\&
\&  sub call {
\&      my($self, $env) = @_;
\&      # pre\-processing $env
\&      my $res = $self\->app\->($env);
\&      # post\-processing $res
\&      return $res;
\&  }
.Ve
.PP
The tricky thing about post-processing the response is that it could
either be an immediate 3 element array ref, or a code reference that
implements the delayed (streaming) interface.
.PP
Dealing with these two types of response in each piece of middleware
is pointless, so you're recommended to use the \f(CW\*(C`response_cb\*(C'\fR wrapper
function in Plack::Util when implementing a post processing
middleware.
.PP
.Vb 4
\&  sub call {
\&      my($self, $env) = @_;
\&      # pre\-processing $env
\&      my $res = $self\->app\->($env);
\&
\&      return Plack::Util::response_cb($res, sub {
\&          my $res = shift;
\&          # do something with $res;
\&      });
\&  }
.Ve
.PP
The callback function gets a response as an array reference, and you can
update the reference to implement the post-processing. In the normal
case, this arrayref will have three elements (as described by the PSGI
spec), but will have only two elements when using a \f(CW$writer\fR as
described below.
.PP
.Vb 3
\&  package Plack::Middleware::Always500;
\&  use parent qw(Plack::Middleware);
\&  use Plack::Util;
\&
\&  sub call {
\&      my($self, $env) = @_;
\&      my $res  = $self\->app\->($env);
\&      return Plack::Util::response_cb($res, sub {
\&          my $res = shift;
\&          $res\->[0] = 500;
\&          return;
\&      });
\&  }
.Ve
.PP
In this example, the callback gets the \f(CW$res\fR and updates its first
element (status code) to 500. Using \f(CW\*(C`response_cb\*(C'\fR makes sure that
this works with the delayed response too.
.PP
You're not required (and not recommended either) to return a new array
reference \- they will be simply ignored. You're suggested to
explicitly return, unless you fiddle with the content filter callback
(see below).
.PP
Similarly, note that you have to keep the \f(CW$res\fR reference when you
swap the entire response.
.PP
.Vb 5
\&  Plack::Util::response_cb($res, sub {
\&      my $res = shift;
\&      $res = [ $new_status, $new_headers, $new_body ]; # THIS DOES NOT WORK
\&      return;
\&  });
.Ve
.PP
This does not work, since assigning a new anonymous array to \f(CW$res\fR
doesn't update the original PSGI response value. You should instead
do:
.PP
.Vb 5
\&  Plack::Util::response_cb($res, sub {
\&      my $res = shift;
\&      @$res = ($new_status, $new_headers, $new_body); # THIS WORKS
\&      return;
\&  });
.Ve
.PP
The third element of the response array ref is a body, and it could
be either an arrayref or IO::Handle\-ish object. The application could
also make use of the \f(CW$writer\fR object if \f(CW\*(C`psgi.streaming\*(C'\fR is in
effect, and in this case, the third element will not exist
(\f(CW\*(C`@$res == 2\*(C'\fR). Dealing with these variants is again really painful,
and \f(CW\*(C`response_cb\*(C'\fR can take care of that too, by allowing you to return
a content filter as a code reference.
.PP
.Vb 10
\&  # replace all "Foo" in content body with "Bar"
\&  Plack::Util::response_cb($res, sub {
\&      my $res = shift;
\&      return sub {
\&          my $chunk = shift;
\&          return unless defined $chunk;
\&          $chunk =~ s/Foo/Bar/g;
\&          return $chunk;
\&      }
\&  });
.Ve
.PP
The callback takes one argument \f(CW$chunk\fR and your callback is
expected to return the updated chunk. If the given \f(CW$chunk\fR is undef,
it means the stream has reached the end, so your callback should also
return undef, or return the final chunk and return undef when called
next time.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Plack Plack::Builder Plack::Component