Mark Overmeer > HTTP-Server-Multiplex > HTTP::Server::VirtualHost

Download:
HTTP-Server-Multiplex-0.11.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 0.11   Source  

NAME ^

HTTP::Server::VirtualHost - base-class for virtual host definitions

INHERITANCE ^

 HTTP::Server::VirtualHost is extended by
   HTTP::Server::VirtualHost::LocalHost

SYNOPSIS ^

 use HTTP::Server::Multiplex;

 my $vhost  = HTTP::Server::VirtualHost->new(@vhost_opts);
 my $daemon = HTTP::Server::Multiplex->new
   ( @other_options
   , vhosts => $vhost
   );

 # or
 my $daemon = HTTP::Server::Multiplex->new(@other_opts);
 $daemon->addVirtualHost($vhost);
 $daemon->addVirtualHost(@vhost2_opts);

 # create object which extends HTTP::Server::VirtualHost
 my $myvhost = MyVHost->new(...);
 $daemon->addVirtualHost($myvhost);

DESCRIPTION ^

These virtual host definitions are used by HTTP::Server::Multiplex, to implement (server) name based data seperation. Its features resemble those of Apache virtual hosts.

Each virtual host usually has to HTTP::Server::Directory slaves: one which describes the permissions for user directories (url paths in the form /~user/ ) and one for data outside the user space.

METHODS ^

Constructors

You may avoid the creation of extension classes for each virtual host, by using these options.

HTTP::Server::VirtualHost->new(OPTIONS|HASH-of-OPTIONS)

 Option        --Default
 aliases         []
 directories     <see text>
 directory_list  <false>
 documents       <undef>
 handlers        {}
 index_file      ['index.html', 'index.htm']
 name            <required>
 rewrite         <undef>
 user_dirs       <see text>

. aliases => HOSTNAME|ARRAY-of-HOSTNAMES

. directories => OBJECT|HASH|ARRAY

Pass one or more HTTP::Server::Directory OBJECTS, or HASHes which will be used to initialize them. If no information is provided, then only /~user urls and scripts can be used.

. directory_list => BOOLEAN

Enables the display of a directory, when it does not contain one of the index_file prepared defaults.

. documents => DIRECTORY

An absolute DIRECTORY for the location of the source files. Creates the most free HTTP::Server::Directory object. If you need things like access restrictions, then do not use this option but the directories option.

. handlers => HASH

The keys are path names, part of the request URIs. The values are CODE-references, called when that URI is addressed. The access rules are taken from the directory definition which is selected by the path, for that's all.

The handlers are called with a the connection (HTTP::Server::Connection), request (HTTP::Request), uri object (URI).

. index_file => STRING|ARRAY

When a directory is addressed, it is scanned whether one of these files exist. If so, the content will be shown.

. name => HOSTNAME

. rewrite => CODE

See rewrite().

. user_dirs => undef|OBJECT|HASH

If not specified, a HTTP::Server::Directory::UserDirs is created for you, with standard Apache behavior. You may provide your own OBJECT or a HASH which contains the parameters to create it. When you explicitly specify an undef value, then user directories will not be allowed.

Attributes

$obj->aliases

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

$obj->name

Returns the primary name for this server.

Handler

$obj->handleRequest(CONNECTION, REQUEST)

$obj->requestForMe(URI)

Re-check whether a request is really for this virtual host.

$obj->showDirectory(CONNECTION, REQUEST, PATH, LIST)

Overrule this method with the way you would like to display an automatically generated directory index.

Basic daemon actions

$obj->allow(CLIENT, SESSION, REQUEST, URI)

BE WARNED that the URI is the rewrite of the REQUEST uri, and therefore you should use that URI. The SESSION represents a user.

See "Allow access".

$obj->rewrite(URI)

Returns an URI object as result, which may be the original in case of no rewrite was needed. See "URI Rewrite".

Directories

$obj->addDirectory(OBJECT|OPTIONS)

Either pass a HTTP::Server::Directory OBJECT or the OPTIONS to create the object.

$obj->directoryOf(PATH)

Find the best matching HTTP::Server::Directory object.

$obj->filename(URI)

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

Access permissions

DETAILS ^

URI Rewrite

For each request, the rewrite() 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.

example: rewrite URI

  package My::Virtual::Host;
  use base 'HTTP::Server::VirtualHost';

  my %lookup =
    ( '/'     => '/index-en.html'
    , '/news' => 'http://news.example.org/index.html'
    );

  sub rewrite($)
  {  my ($self, $uri) = @_;

     # 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(/.*|$)!;
     
     # maybe more work in the base class
     $uri->SUPER::rewrite($uri);
  }

SEE ALSO ^

This module is part of HTTP-Server-Multiplex distribution version 0.11, built on October 01, 2008. Website: http://perl.overmeer.net/httpd-multiplex/

LICENSE ^

Copyrights 2008 by Mark Overmeer. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See http://www.perl.com/perl/misc/Artistic.html

syntax highlighting: