view release on metacpan or  search on metacpan

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

an other host.  Configuration like for C<rewrite>.

=item rewrite => CODE|METHOD|HASH

When a request arrives, the URI can be rewritten to become an other
request. See L</URI Rewrite>.

[0.21] When a METHOD name is specified, that will be called on
the virtual host object.  An HASH as parameter is interpreted as a
simple lookup table.

=item user_dirs => undef|OBJECT|HASH

With an (empty?) HASH which contains instantiation parameter, an
L<Any::Daemon::HTTP::UserDirs|Any::Daemon::HTTP::UserDirs> is created for you, with
standard Apache behavior.  You may provide your own OBJECT.  Without
this parameter, there are no public user pages.

=back

=back

=head2 Attributes

=over 4

=item $obj-E<gt>B<aliases>()

Returns a list of all aliases (alternative names) for this server.

=item $obj-E<gt>B<generateAliases>($hostname)

=item Any::Daemon::HTTP::VirtualHost-E<gt>B<generateAliases>($hostname)

=item $obj-E<gt>B<name>()

Returns the primary name for this server.

=back

=head2 Handler

=over 4

=item $obj-E<gt>B<addHandler>(CODE|METHOD|PAIRS|HASH)

Handlers are called to dynamically generate responses, for instance
to fill-in templates.  The L</DETAILS> section below explains how
handlers work.

When only CODE is given, then this will be the default handler for all
paths (under '/', top). [0.21] CODE may also be a $method name.

Usually, you pass some PAIRS or a HASH, relating PATH names inside
the virtual host into function references or method names to be used for
that tree.

example: 

  $vhost->addHandler('/' => \&default_handler
     , '/upload' => \&upload_handler);

  $vhost->addHandler(\&default_handler);

  # [0.21] will call $vhost->formHandle
  $vhost->addHandler('/form' => 'formHandler');

=item $obj-E<gt>B<addHandlers>($params)

Alias for L<addHandler()|Any::Daemon::HTTP::VirtualHost/"Handler">.

=item $obj-E<gt>B<findHandler>($uri|$path|@segments)

Find the handler which matches the given $uri best.  The $uri is the
rewritten URI of the request, an URI object.  It's $path is sufficient,
may also be broken into path @segments already.

=item $obj-E<gt>B<handleRequest>( $server, $session, $request, [$uri] )

=back

=head2 Basic daemon actions

=over 4

=item $obj-E<gt>B<addSource>($source)

The $source objects extend L<Any::Daemon::HTTP::Source|Any::Daemon::HTTP::Source>, for instance a
C<::Directory> or a C<::Proxy>.  You can find them back via L<sourceFor()|Any::Daemon::HTTP::VirtualHost/"Directories">.

=item $obj-E<gt>B<mustRedirect>($uri)

[0.21] Returns an HTTP::Response object if the $uri needs to be
redirected, according to the vhost configuration.

=item $obj-E<gt>B<redirect>( $uri, [$http_code] )

[0.21] Returns an HTTP::Response object of the $uri.

=item $obj-E<gt>B<rewrite>($uri)

Returns an $uri object as result, which may be the original in case of
no rewrite was needed.  See L</URI Rewrite>.

=back

=head2 Directories

=over 4

=item $obj-E<gt>B<addDirectory>($object|HASH|%options)

Either pass a L<Any::Daemon::HTTP::Directory|Any::Daemon::HTTP::Directory> $object or the %options to
create the object.  When %options are provided, they are passed to
L<Any::Daemon::HTTP::Directory::new()|Any::Daemon::HTTP::Directory/"Constructors"> to create the $object.

=item $obj-E<gt>B<filename>($uri)

Translate the $uri into a filename, without checking for existence.  Returns
C<undef> is not possible.

=item $obj-E<gt>B<sourceFor>($path|$path_segments)

Find the best matching L<Any::Daemon::HTTP::Source|Any::Daemon::HTTP::Source> object, which
might be a C<::UserDirs>, a C<::Directory>, or a C<::Proxy>.

=back

=head2 Proxies

=over 4

=item $obj-E<gt>B<addProxy>($object|HASH|%options)

Either pass a L<Any::Daemon::HTTP::Proxy|Any::Daemon::HTTP::Proxy> $object or the %options to
create the object.  When %options are provided, they are passed to
L<Any::Daemon::HTTP::Proxy::new()|Any::Daemon::HTTP::Proxy/"Constructors"> to create the $object.

=back

=head1 DETAILS

=head2 Handlers

Handlers are called to dynamically generate responses, for instance
to fill-in templates.  In other frameworks, they are called 'routes'
or 'get'.

When a request for an URI is received, it is first checked whether
a static file can fulfil the request.  If not, a search is started
for the handler with the longest path.

  # /upload($|/*) goes to the upload_handler
  $vhost->addHandlers
    ( '/'       => \&default_handler
    , '/upload' => \&upload_handler
    );

  # Missing files go to the default_handler
  # which is actually replacing the existing one
  $vhost->addHandler(\&default_handler);

  # [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($$$$)