NAME
Sub::Middler - Middleware subroutine chaining
SYNOPSIS
use strict;
use warnings;
use Sub::Middler;
my $middler=Sub::Middler->new;
$middler->register(mw1(x=>1));
$middler->register(mw2(y=>10));
my $head=$middler->link(
sub {
print "Result: $_[0]\n";
}
);
$head->(0); # Call the Chain
# Middleware 1
sub mw1 {
my %options=@_;
sub {
my ($next, $index, @optional)=@_;
sub {
my $work=$_[0]+$options{x};
$next->($work);
}
}
}
# Middleware 2
sub mw2 {
my %options=@_;
sub {
my ($next, $index, @optional)=@_;
sub {
my $work= $_[0]*$options{y};
$next->( $work);
}
}
}DESCRIPTION
A small module, facilitating linking together subroutines, acting as middleware or filters into chains with low runtime overhead.
To achieve this, the 'complexity' is offloaded to the definition of middleware/filters subroutines. They must be wrapped in subroutines appropriately to facilitate the lexical binding of linking variables.
This differs from other 'sub chaining' modules as it does not use a loop internally to iterate over a list of subroutines at runtime. As such there is no implicit call to the 'next' item in the chain. Each stage can run the following stage synchronously or asynchronously or not at all. Each element in the chain is responsible for how and when it calls the 'next'.
Finally the arguments and signatures of each stage of middleware are completely user defined and are not interfered with by this module. This allows reuse of the @_ array in calling subsequent stages for ultimate performance if you know what you're doing.
API
Managing a chain
new
my $object=Sub::Middler->new;Creates a empty middler object ready to accept middleware. The object is a blessed array reference which stores the middleware directly.
register
$object->register(my_middlware());Appends the middleware to the internal list for later linking.
append, add
Alias for register
link
$object->link($last,[@args]);Links together the registered middleware in the sequence of addition. Each middleware is intrinsically linked to the next middleware in the list. The last middleware being linked to the $last argument, which must be a code ref.
The $last ref MUST be a regular subroutine reference, acting as the 'kernel' as described in following sections.
Calls die if $last is not a code ref.
Any optional additional arguments @args are passed to this function are passed on to each 'maker' sub after the $next and $index, parameters. This gives an alternative approach to distributing configuration data to each item in the chain prior to runtime. It is up to each item's maker sub to store relevant passed values as they see fit.
Creating Middleware
To achieve low over head in linking middleware, functional programming techniques (higher order functions) are utilised. This also give the greatest flexibility to the middleware, as signatures are completely user defined.
The trade off is that the middleware must be defined in a certain code structure. While this isn't difficult, it takes a minute to wrap your head around.
Middlware Definition
Middleware must be a subroutine (top/name) which returns a anonymous subroutine (maker), which also returns a anonymous subroutine to perform work (kernel).
This sounds complicated by this is what is looks like in code:
sub my_middleware { (1) Top/name subroutine
my %options=@_; Store any config
sub { (2) maker sub is returned
my ($next, $index, @optional)=@_; (3) Must store at least $next
sub { (4) Returns the kernel sub
# Code here implements your middleware
# %options are lexically accessable here
# as are the @optional parameters
# Execute the next item in the chain
$next->(...); (5) Does work and calls the next entry
(6) Post work if applicable
}
}
}- Top Subroutine
-
The top sub routine (1) can take any arguments you desire and can be called what you like. The idea is it represents your middleware/filter and stores any setup lexically for the maker sub to close over. It returns the maker sub.
- Maker Subroutine
-
This anonymous sub (2) closes over the variables stored in Top and is the input to this module (via
register). When being linked (called) by this module it is provided at least two arguments: the reference to the next item in the chain and the current middleware index. These MUST be stored to be useful, but can be called anything you like (3).Any optional/additional arguments supplied during a call to
linkare also used as arguments 'as is' to all maker subroutines in the chain. - Kernel subroutine
-
This anonymous subroutine (4) actually performs the work of the middleware/filter. After work is done, the next item in the chain must be called explicitly (5). This supports synchronous or asynchronous middleware. Any extra work can be performed after the chain is completed after this call (6).
LINKING CHAINS
Multiple chains of middleware can be linked together. This needs to be done in reverse order. The last chain after being linked, becomes the $last item when linking the preceding chain and so on.
EXAMPLES
The synopsis example can be found in the examples directory of this distribution.
SEE ALSO
Sub::Chain and Sub::Pipeline links together subs. They provide other features that this module does not.
These iterate over a list of subroutines at runtime to achieve named subs etc. where as this module pre links subroutines together, reducing overhead.
AUTHOR
Ruben Westerberg, <drclaw@mac.com>
REPOSITORTY and BUGS
Please report any bugs via git hub: http://github.com/drclaw1394/perl-sub-middler
COPYRIGHT AND LICENSE
Copyright (C) 2023 by Ruben Westerberg
This library is free software; you can redistribute it and/or modify it under the same terms as Perl or the MIT license.
DISCLAIMER OF WARRANTIES
THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.