/ 
Wurm-0.0.8
River stage zero No dependents
/ Wurm

NAME

Wurm - Simple. Easy. Crawls in your teeth. Web framework. Did I mention it was a web framework? Another one.

SYNOPSIS

use Wurm;
use Data::Dumper;

# Wurm applications are defined by a structure of anonymous
# sub-routines that get called based on the incoming request
# and where they live within the application tree.

# When a request is received it is first packaged into a
# C<$meal> which is then dispatched to a series of handlers.
# Handlers are expected to inspect, filter, and otherwise
# act on the request until a PSGI response is generated.
# Once a response is generated, dispatching halts and the
# response is returned back up the Plack chain.
# This process is called "folding".

# The internet really can be a series of tubes.
sub build_tube {
  my ($name) = @_;

  # Here we create a basic component skeleton which we will use
  # to build our application.  We use closures to capture
  # $name but sub-routines can also simply be copied throughout
  # the dispatch tree to duplicate behavior without creating
  # new sub-routines, modules, classes, or objects.

  return ({
    # Gate handlers are always called first when folding.
    # They are primarily meant for inspection, filtering,
    # and resource setup.

    # They will be called as Wurm traverses the URL path from
    # the request.  Wurm maintains C<PATH_INFO> information in
    # C<$meal->{tube}>.  As a request is dispatched, non-C<'/'>
    # atoms and a trailing C<'/'> are removed and concatenated
    # to C<$meal->{seen}>.  You can check C<$meal->{tube} eq ''>
    # to see if this component will be targeted for further dispatch.
    gate => sub {
      my $meal = shift;
      $meal->{log}->({level => 'debug',
        message => "$name ))) $meal->{tube}"});
      $meal->{vent}{to} = ucfirst $name
        if $meal->{tube} eq '';
      push @{$meal->{grit}{path}}, $name. '/gate';
      return;
    },

    # What is not seen here are Tube handlers.  Tube handlers are
    # what define the path ways within your application for dispatching
    # down C<PATH_INFO>.  Since this is just a skeleton, we will tie the
    # application together with tube handlers later.

    # Neck handlers are called when C<$meal->{tube} eq ''>.
    # Unless more advanced dispatching is performed at run-time,
    # this starts the final dispatch chain.
    neck => sub {
      my $meal = shift;
      push @{$meal->{grit}{path}}, $name. '/neck';
      return;
    },

    # Body handlers are used to dispatch based on the request method.
    # Unlike gate, neck, and tail handlers these require a slightly
    # more complex structure.  You must provide a C<HASH> that
    # contains handlers keyed off of the lower cased request method
    # you would like that code to process.
    body => {
      get => sub {
        my $meal = shift;
        push @{$meal->{grit}{path}}, $name. '/body:get';
        return;
      },
    },

    # Tail handlers are the final possible step in a dispatch chain
    # before a C<404> is generated.  While you can easily return a
    # response from a body handler, tail handlers give you the option
    # of tying multiple body response handling paths into a single spot.
    tail => sub {
      my $meal = shift;
      push @{$meal->{grit}{path}}, $name. '/tail';
      return wrap_it_up($meal);
    },
  })
};

# Look ma... modularity.
# More advanced applications might have a template engine or other
# data transformers contained in C<$meal->{mind}>.  C<$meal->{grit}>
# and C<$meal->{vent}> data areas are for your application to use
# as needed on a per-request basis.
sub wrap_it_up {
  my $meal = shift;

  my $path = join ', ', @{$meal->{grit}{path}};

  my $text = '';
  $text .= "$meal->{mind}{intro} $meal->{vent}{to},\n";
  $text .= "This is the path I took: $path\n";
  $text .= "This is what is in the tube: $meal->{tube}\n";
  $text .= "This is what I've seen: $meal->{seen}\n";

  # Wurm provides some easy response handlers.
  # They are probably too simple to be useful.
  # Good luck.
  return Wurm::_200('text/plain', $text);
}


# Now let's build the app!


# This is the root "controller".
my $wurm = build_tube('root');

# The case routine can be defined to munge the request meal.
# It is only called once at request entry.
$wurm->{case} = sub {
  my $meal = shift;
  $meal->{vent}{to}   = 'Nobody';
  $meal->{grit}{path} = [ ];
  return $meal;
};

# The pore routine can be defined to munge the response.
# It is only ever called once at request exit.
$wurm->{pore} = sub {
  my ($res, $meal) = @_;
  $res->[2][0] = $res->[2][0]
    . ($res->[0] == 200 ? '' : "\n")
    . 'PSGI env: '. Dumper($meal->{env})
  ;
  return $res;
};


# Tinker-tubes!

# Tubes are sub-tree structures that Wurm will re-dispatch to
# during a request based on elements in the URL path.  They
# have the exact same structure as described above with the
# exception that C<case()> and C<pore()> handlers are ignored.

# When a request begins, the HTTP C<PATH_INFO> information is
# copied to C<$meal->{tube}> with a leading C<'/'> removed.
# Wurm will remove a non-C<'/'> atom and trailing C<'/'> from
# C<$meal->{tube}> during each dispatch cycle and will
# re-dispatch the request to the folding tree defined under
# that atom.  If no folding tree is found for a particular atom,
# a C<404> is returned.

# This builds a path route for 'wurm/' and 'wurm'.
$wurm->{tube}{wurm} = build_tube('wurm');

# This builds more path routes ('wurm/{foo,bar,baz,qux}/').
$wurm->{tube}{wurm}{tube}{$_} = build_tube($_)
  for qw(foo bar baz qux);

# Now we have 'foo/' and 'baz/'.
$wurm->{tube}{$_} = $wurm->{tube}{wurm}{tube}{$_}
  for qw(foo baz);

# qux is special.
# It has a gate handler that will always return a 200.
# This will act like a catch all for 'wurm/qux/*'.
$wurm->{tube}{wurm}{tube}{qux}{gate} = sub {
  my $meal = shift;
  $meal->{vent}{to} = 'Lord Qux';
  push @{$meal->{grit}{path}}, '*/gate';
  return wrap_it_up($meal);
};

# Now turn the closure nightmare into a PSGI application.
# The second argument to wrapp() is the C<$meal->{mind}>.
# You can use it to store application-wide state like
# configuration or other global resources.
my $app = Wurm::wrapp($wurm, {intro => 'Hello'});
$app

DESCRIPTION

Wurm implements a fold-r Plack web application container. It is meant for quickly building PSGI-based applications using a multiple dispatch pattern that is driven by anonymous sub-routines. Requests are passed down a set of handlers based on PATH_INFO and REQUEST_METHOD. The dispatch chain is canceled as soon as a response is generated.

Applications are defined by a data structure that provides callback handlers. Request handlers are called with a context object known as a meal that contains request and application state. Handlers are expected to either return undef if dispatching should continue or a PSGI response.

MEALS

Life feeds on life.

When requests to your application are dispatched, they are first encased as a meal. The meal is a simple HASH reference with request and application state. It can be upgraded with fancier OO-related features when using Wurm::mob. See the relevant documentation there for more. In its simplest form, it will contain the following:

{
  env  => $env,
  log  => $log,
  tube => $env->{PATH_INFO},
  seen => '',
  mind => $mind,
  grit => { },
  vent => { },
}

  • env

    env is the PSGI $env as received.

  • log

    log is the PSGI logger in $env->{'psgix.logger'}. If one is not present, a stub routine is put in place. This allows you to call $meal->{log}->({...}) without checking for a logger first.

  • tube

    tube is the current series of tubes to traverse. As the request is dispatched, non-'/' atoms are removed with the trailing slash. The default is set to the PATH_INFO in the request with the leading '/' removed.

  • seen

    seen is the opposite of tube. As atoms are removed from tube, they are concatenated back onto seen. The combination of these should give you an idea of where the request is going and where it has been.

  • mind

    mind is an application-specific data structure that is passed to every request. The value is set when calling wrapp() to generate a PSGI application. This is typically where things like configuration or handles to application-wide resources should be kept.

  • grit

    grit is a per-request data area that is used for maintaining state. It is meant to be a "clean" area for building up data that may be passed to a template engine or data models.

  • vent

    vent is a per-request data area that is used for maintaining state. It differs from grit in that it is meant to house per-request data that is typically thrown away at the end of a request. This might include things like formatting flags or temporary information that should never be applied to a template or data model.

DISPATCHING

A fully dispatched request flows as follows:

case ->

  gate -> tube -> neck -> body -> tail -> 404
  ^       +-> 404
  +------ +

-> pore

The entry point for a request (case) converts a PSGI request into a meal. The meal is then passed as a single parameter to callback handlers that may be defined for the named stages above. Each stage represents a different type of routing logic or step within the dispatch chain.

Applications may define their own case callback which will be called after the default one. This allows per-request inspection and filtering before any dispatching. It is required that it return a meal.

sub case {
  my $meal = shift;
  # fix stuff in $meal here
  return $meal;
}

...

Wurm::wrap({case => \&case, ...});

After a request has been cased, it is dispatched according to the folding logic embedded in the application structure. If undef is returned from a handler, dispatching continues. Anything else is treated as a PSGI response that will be passed back up the Plack call chain.

All callback handlers have the same signature which is:

sub callback {
  my $meal = shift;
  return
    if $dispatching_should_continue;
  return $locally_defined_PSGI_response;
}

The following callback handlers may be defined for an application:

gate

Gate handlers are always called when present in the dispatch chain. This will include handlers for which the PATH_INFO may not apply directly since these will be called as the path is traversed. If $meal->{tube} is '', this is the last gate that will be called.

Wurm::wrapp({..., gate => \&handler, ...});
tube

Tube handlers are called when there are tubes to navigate. If $meal->{tube} is not '', it will be stripped of a leading non-'/' atom which will be used as a key for further delegation. If a dispatch structure exists for the path element, the request will be re-dispatched using this new structure thereby providing path folding. If no structure exists, a 404 is generated.

Wurm::wrapp({...,
  tube => {
    funky  => {gate => sub { }, ...},
    mondo  => {..., body => {get => sub { }}, ...},
    gnarly => {..., tail => sub { }},
  }
...});
neck

Neck handlers are run in between path matching and request method delegation. While multiple gate handlers can be called, only one neck handler should be called for any given request chain. It can be used for filtering or setting up requests prior to dispatching the request to body handlers.

Wurm::wrapp({..., neck => \&handler, ...});
body

Body handlers represent REQUEST_METHOD dispatching. The lower-cased value of the current request's method is used to choose which handler is used for delegatation. No restriction is made on the name so even esoteric methods like OPTIONS and CONNECT can be defined.

Wurm::wrapp({...,
  body => {
    get  => \&handler,
    lost => \&handler,
    head => \&handler,
    post => \&handler,
    man  => \&handler,
  }
...});
tail

Tail handlers are the last possible handler to be called in any dispatch chain. They can be used to bundle the response packaging logic of a busy chain into a single place. If a tail handler does not generate a response, a 404 response is returned.

Wurm::wrapp({..., tail => \&handler, ...});

The exit point (pore) is responsible for the final packaging of a proper PSGI response that is then passed back up the Plack call chain. The default will check for blessed response objects and call finalize() on them for you. Applications may define their own which will be called prior to the default:

sub pore {
  my ($cast, $meal) = @_;
  # $cast is the PSGI response generated by the dispatch
  # $meal is what generated $cast and is probably filthy
  return $cast;
}

...

Wurm::wrapp({..., pore => \&pore});

FUNCTIONS

Wurm::wrapp($wurm, $mind)

Converts a set of folding rules into a PSGI application. The $wurm parameter must be a HASH reference which can be configured according to the dispatch principles outlined above. If $mind is provided, it will be attached to each incoming request as $meal->{mind}.

Wurm::fold($meal, $wurm)

Dispatches a meal according to a set of folding rules. This is what performs all the work and is not meant to be called directly. Unless of course you need that much power. Use it wisely.

Wurm::bend($meal)

Removes a non-'/' atom and '/' from $meal->{tube}. If no atom is available, undef is returned. Otherwise the atom and a '/' are concatenated to $meal->{seen} and the atom is returned.

Wurm::_200($content_type, $content)

Very simplistic status code 200 generator. Sets the 'Content-Type' header and body content to the values provided and not much else.

Wurm::_201($location)

Generates a 201 redirect response with the location header set to the given value.

Wurm::_204()

Generates an empty 204 (No Content) response.

Wurm::_301($location)

Generates a 301 redirect response with the location header set to the given value.

Wurm::_302($location)

Generates a 302 redirect response with the location header set to the given value.

Wurm::_400()

Generates an empty 400 (Bad Request) response.

Wurm::_404()

Generates an empty 404 (Not Found) response.

Wurm::_500()

Generates an empty 500 (Internal Server Error) response.

SEE ALSO

Wurm::mob
Wurm::let
Wurm::Grub::REST

DISCLAIMER

This software is known to The State of California to be experimental.

AUTHOR

jason hord <pravus@cpan.org>

LICENSE

This software is information. It is subject only to local laws of physics.