NAME

Fancy::Middleware - Provides alternate implementation of Plack::Middleware in a Moose Role

VERSION

version 1.101680

SYNOPSIS

    use MooseX::Declare;
    
    class My::Custom::Middleware::Logger
    {
        with 'Fancy::Middleware';

        has logger =>
        (
            is => 'ro',
            isa => 'SomeLoggerClass',
            required => 1,
        );

        around preinvoke()
        {
            $self->env->{'my.custom.middleware.logger'} = $self->logger;
        }
    }

    ...

    my $app = My::Web::Simple::Subclass->as_psgi_app();
    $app = My::Custom::Middleware::Logger->wrap($app, logger => $some_logger_instance);

DESCRIPTION

Fancy::Middleware is an alternate implementation of the Plack::Middleware base class but as a Moose Role instead. This gives us a bit more flexibility in how how the Middleware functionality is gained in a class without having to explicitly subclass. That said, this Role should fit in just fine with other Plack::Middleware implemented solutions as the API is similar.

There are some differences that should be noted.

Three distinct "phases" were realized: "preinvoke", "invoke", "postinvoke". This allows more fine grained control on where in the process middleware customizations should take place.

Also, more validation is in place than provided by Plack::Middleware. The response is checked against "PSGIResponse" in POEx::Types::PSGIServer, the "env" hash is constrained to HashRef, and "app" is constrained to a CodeRef.

CLASS_METHODS

wrap

    (ClassName $class: CodeRef $app, @args)

wrap is defined by Plack::Middleware as a method that takes a PSGI application coderef and wraps is with the middleware, returning the now wrapped coderef.

Internally, this means the class itself is instantiated with the provided arguments with $app being passed to the constructor as well. Then to_app is called and the result returned.

PUBLIC_ATTRIBUTES

app

    is: ro, isa: CodeRef, required: 1

app is the actual PSGI application.

response

    is: ro, isa: PSGIResponse, writer: set_response

response holds the result from the invocation of the PSGI application. This is useful if the response needs to be filtered after invocation.

env

    is: ro, isa: HashRef, writer: set_env

env has the environment hash passed from the server during "call".

PUBLIC_METHODS

call

    (HashRef $env)

call is also defined by Plack::Middleware as the method to implement to perform work upon the provided application with the supplied $env hash. Instead of overriding this method, move your implementation pieces into one of the methods below.

preinvoke

preinvoke is called prior to "invoke". By default it simply returns. Exclude or advise this method to provide any work that should take place prior to actually invoking the application. Note, that there isn't a valid PSGIResponse at this point.

invoke

invoke executes "app" with "env" provided as the argument. The result is stored in "response". If application execution should be short circuited for any reason, this would be the place to do it.

postinvoke

postinvoke is called after invoke returns. If the "response" needs filtering applied to it, this is the place to do it.

to_app

to_app returns a coderef that closes around $self. When executed, it calls "call" with all of the arguments presented to it.

AUTHOR

  Nicholas R. Perez <nperez@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2010 by Nicholas R. Perez <nperez@cpan.org>.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

cpanm Fancy::Middleware

perl -MCPAN -e shell
install Fancy::Middleware