view release on metacpan or  search on metacpan

lib/Any/Daemon/HTTP/VirtualHost.pod  view on Meta::CPAN

  # [0.21] This will call $vhost->formHandle(...), especially
  # useful in your virtual host sub-class.
  $vhost->addHandler('/form' => 'formHandler');

The handlers are called with many arguments, and should return an
HTTP::Response object:

  $vhost->addHandler('/upload' => $handler);
  my $resp = $hander->($vhost, $session, $req, $uri, $tree);

  $vhost->addHandler('/form' => $method);
  my $resp = $vhost->$method($session, $req, $uri, $tree);

In which

=over 4

=item * C<$vhost> is an C<Any::Daemon::HTTP::VirtualHost>,

=item * C<$session> is an L<Any::Daemon::HTTP::Session|Any::Daemon::HTTP::Session>,

=item * C<$req> is an HTTP::Request,

=item * C<$uri> an URI after rewrite rules, and

=item * C<$tree> the selected C<Any::Daemon::HTTP::Directory>.

=back

The handler could work like this:

  sub formHandler($$$$)
  {   my ($vhost, $session, $req, $uri, $tree) = @_;
      # in OO extended vhosts, then $vhost => $self

      # Decode path parameters in Plack style
      # ignore two components: '/' and 'form' from the path
      my (undef, undef, $name, @more) = $uri->path_segments;

      HTTP::Response->new(HTTP_OK, ...);
  }

=head2 Your virtual host as class

When your virtual host has larger configuration or many handlers --or when
you like clean programming--, it may be a good choice to put your code
in a separate package with the normal Object Oriented extension mechanism.

You may need to implement your own information persistence via databases
or configation files.  For that, extend L<Any::Daemon::HTTP::Session|Any::Daemon::HTTP::Session>.

B<. Example: own virtual host>

  package My::Service;
  use parent 'Any::Daemon::HTTP::VirtualHost';

  sub init($)
  {   my ($self, $args) = @_;
      $args->{session_class} = 'My::Service::Session';
      $self->SUPER::init($args);
      
      $self->addDirectory(...);
      $self->addHandler(a => 'ah');
      ... etc ...
      $self;
  }

  sub ah($$$$)
  {   my ($self, $session, $request, $uri, $tree) = @_;
      return HTTP::Response->new(...);
  }

  package My::Service::Session;
  use parent 'Any::Daemon::HTTP::Session';

=head2 URI Rewrite

For each request, the L<rewrite()|Any::Daemon::HTTP::VirtualHost/"Basic daemon actions"> method is called to see whether a
rewrite of the URI is required.  The method must return the original URI
object (the only parameter) or a new URI object.

B<. Example: usage>

  my $vhost = Any::Daemon::HTTP::VirtualHost
    ->new(..., rewrite => \&rewrite);

  my $vhost = My::Service     # see above
    ->new(..., rewrite => 'rewrite');

  my $vhost = My::Service     # see above
    ->new(..., rewrite => \%lookup_table);

B<. Example: rewrite URI>

  my %lookup =
    ( '/'     => '/index-en.html'
    , '/news' => '/news/2013/index.html'
    );

  sub rewrite($)
  {  my ($vhost, $uri) = @_;
     # when called as method, $vhost --> $self

     # with lookup table
     $uri = URI->new_abs($lookup{$uri->path}, $uri)
         if exists $lookup{$uri->path};

     # whole directory trees
     $uri = URI->new_abs('/somewhere/else'.$1, $uri)
         if $uri->path =~ m!^/some/dir(/.*|$)!;
     
     $uri;
  }

=head2 Using Template Toolkit

Connecting this server to the popular Template Toolkit web-page
framework is quite simple:

  # Use TT only for pages under /status