=head1 NAME

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

=head1 INHERITANCE

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

=head1 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);

=head1 DESCRIPTION

Each L<HTTP::Server::VirtualHost|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 C<<http://xx/~user/yy>>
is implemented in L<HTTP::Server::Directory::UserDirs|HTTP::Server::Directory::UserDirs>.

=head1 METHODS

=head2 Constructors

HTTP::Server::Directory-E<gt>B<new>(OPTIONS|HASH-of-OPTIONS)

=over 4

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

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

=over 4

Allow all requests which pass any of these parameters, and none
of the deny parameters.  See L</Allow access>.

=back

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

=over 4

See C<allow> and L</Allow access>

=back

. location => DIRECTORY|CODE

=over 4

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.

=back

. path => STRING

=back

=head2 Attributes

$obj-E<gt>B<location>

=over 4

=back

$obj-E<gt>B<path>

=over 4

=back

=head2 Permissions

$obj-E<gt>B<allow>(CLIENT, SESSION, REQUEST, URI)

=over 4

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 L</Allow access>.

=back

$obj-E<gt>B<filename>(PATH)

=over 4

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

=back

=head1 DETAILS

=head2 Directory limits

=head3 Allow access

The L<allow()|HTTP::Server::Directory/"Permissions"> method handles access rights.  When a trueth value is
produced, then access is permitted.

The base class implements access rules via the C<allow> or C<deny>
option of L<new()|HTTP::Server::Directory/"Constructors">.  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 C<allow> or C<deny> are an ARRAY with any combination of

=over 4

=item IPv4 and IPv6 addresses

=item IPv4 and IPv6 address ranges in CIDR notation

=item hostname

=item domain name (leading dot)

=item your own CODE reference, which will be called with the IP address,

  the hostname, the session, and the rewritten URI.

=back

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 L<new(allow)|HTTP::Server::Directory/"Constructors">:

 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
 }

=head1 SEE ALSO

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

=head1 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 F<http://www.perl.com/perl/misc/Artistic.html>