/ 
HTTP-Server-Multiplex-0.10
River stage zero No dependents
/ HTTP::Server::Directory

NAME

HTTP::Server::Directory - describe a server directory

INHERITANCE

HTTP::Server::Directory is extended by
  HTTP::Server::Directory::UserDirs

SYNOPSIS

# implicit creation of ::Directory object
my $vh = HTTP::Server::VirtualHost
  ->new(directories => {path => '/', location => ...})

# explicit use
my $root = HTTP::Server::Directory
  ->new(path => '/', location => '...');
my $vh = HTTP::Server::VirtualHost
  ->new(directories => $root);

DESCRIPTION

Each HTTP::Server::VirtualHost will define where the files are located. Parts of the URI path can map on different directories, with different permissions.

User directories, like used in the URI <http://xx/~user/yy> is implemented in HTTP::Server::Directory::UserDirs.

METHODS

Constructors

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

    Option  --Default
allow     <undef>
deny      <undef>
location  <required>
path      '/'

    . allow => CIDR|HOSTNAME|DOMAIN|CODE|ARRAY

      Allow all requests which pass any of these parameters, and none of the deny parameters. See "Allow access".

    . deny => CIDR|HOSTNAME|DOMAIN|CODE|ARRAY

    . location => DIRECTORY|CODE

      The absolute prefix DIRECTORY befor the path of the URI, or a CODE reference which will rewrite the path (only parameter) into the absolute file or directory name.

    . path => STRING

Attributes

$obj->location

$obj->path

Permissions

$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->filename(PATH)

    Convert a URI PATH into a directory path. Return undef if not possible.

DETAILS

Directory limits

Allow access

The allow() method handles access rights. When a trueth value is produced, then access is permitted.

The base class implements access rules via the allow or deny option of new(). These parameters are exclusive (which is slightly different from Apache); you can either allow or deny, but not both at the same time.

The parameters to allow or deny are an ARRAY with any combination of

IPv4 and IPv6 addresses
IPv4 and IPv6 address ranges in CIDR notation
hostname
domain name (leading dot)
your own CODE reference, which will be called with the IP address,
the hostname, the session, and the rewritten URI.

example: new(allow) parameters

MyVHOST->new( allow =>
   [ '192.168.2.1'           # IPv4
   , '10/32'                 # IPv4 CIDR
   , '10.0.0.0-10.3.255.255' # IPv4 range
   , '::dead:beef:0:0/110'   # IPv6 range
   , 'www.example.com'       # hostname
   , '.example.com'          # domain and subdomains
   , 'example.com'           # only this domain
   ], ...

example: create own access rules

If you have an ::VirtualHost extension class, you do this:

sub allow($$$)
{   my ($self, $session, $request, $uri) = @_;

    # General rules may refuse access already
    $self->SUPER::allow($session, $request, $uri)
        or return 0;

    # here your own checks
    # $session is a HTTP::Server::Session
    # $request is a HTTP::Request
    # $uri     is a URI::

    1;
}

You may also pass a code-ref to new(allow):

HTTP::Server::VirtualHost->new(allow => \&my_rules);

sub my_rules($$$$)   # called before each request
{   my ($ip, $host, $session, $uri) = @_;
    # return true if access is permitted
}

SEE ALSO

This module is part of HTTP-Server-Multiplex distribution version 0.10, built on September 10, 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