
=pod

=head1 NAME

Director HowTo

=head1 SYNOPSIS

L<Apache::Mogile::Dispatch> allows you to set 'directors' which decide if a given
uri is to be handled through mogile or a set of static servers. This is makes
it very easy to migrate gradually to using MogileFS.

=head1 FUNCTIONS

There are two functions that are required with every director. They are
L<memcache_key> and L<get_direction>.

=head2 memcache_key

This function returns the memcache key to use. If you do not plan on using
memcache you must include this anyway.

=head2 get_direction

This function returns a hashref containing several keys that are used by
L<Apache2::Module::Dispatch> to determine if mogile is to be used or not.

=over

=item mogile

Values: 0, 1, undef

=item reproxy

Values: url, undef

=item canonical_domain

Values: hostname, undef

If this value is returned than it is prepended to the filename when looking
up mogile files.

  GET /index.html
  HOST: socklabs.com

  if ($canonical_domain) # file: /socklabs.com/index.html
  if (! $canonical_domain) # file: /index.html

=back

=head1 EXAMPLE

The following is a simple example of a director. It uses the request hostname
as the memcache key and get_direction returns processed yaml. See
t/FakeDispatch.pm for more information.

  ## -- http.conf
  </Perl>
    use SocklabsDirector;
  </Perl>

  ## -- SocklabsDirector.pm
  package SocklabsDirector;
  
  use strict;
  use warnings;
  
  use APR::Table ();
  use APR::SockAddr ();
  use Apache2::RequestRec ();
  use Apache2::RequestUtil ();
  use Apache2::Connection ();
  use Apache2::Filter ();
  use Apache2::RequestRec ();
  use Apache2::Module;
  use Apache2::CmdParms ();
  use Apache2::Directive ();
  use Apache2::Log ();
  use Apache2::URI ();
  use Apache2::Const -compile => qw(DECLINED OK OR_ALL RSRC_CONF TAKE1 RAW_ARGS NO_ARGS DONE NOT_FOUND);
  
  use LWP::UserAgent;
  use YAML::Syck;
  
  use constant FAKEDIRECTOR_URL => 'http://localhost:8529/FakeDispatch';
  
  sub memcache_key {
      my ($self, $r, $config) = @_;
      return $r->hostname;
  }
  
  sub get_direction {
      my ($self, $r, $config) = @_;
      my $ua = LWP::UserAgent->new;
      my $url = FAKEDIRECTOR_URL . '?domain=' . $r->hostname;
      my $response = $ua->get($url);
      if ($response->is_success) {
          return Load($response->content);
      }
      return 0;
  }
  
  1;

=head1 IDEAS

=over

=item * hostname based directing

=item * uri/location based directing

=back

=cut
