howto: do an internal apache redirect from mod_perl

[shadedecho]

Inside of a perl CGI script (run through mod_perl on Apache), I want to be able to inspect a URL and based on certain conditions, either decide to allow the requested file or alternately respond with some other behavior (like a 404 or whatever).

So, essentially, I have a .htaccess file routing all my requests to one perl script, and I want that perl script to be the gateway that decides if a certain file is ok to request or not.

The catch is, when I want to allow the file to be requested (like a .html file for instance) I don't want to have to sniff/guess the content-type and then open the file and echo the contents. I just want to signal to Apache to serve the file as normal (via just a normal internal redirect).

I do not want a regular 301 redirect that the browser will be notified about, I want an internal redirect so the user/browser don't know the difference.

 

[shadedecho]

OK, so I think I've found the right module to do what I want:

http://perl.apache.org/docs/2.0/api/Apache2/SubRequest.html

However, the code samples here assume the presence of this magical $r that I don't know where it comes from. It's not automatically defined in my perl script.

  use Apache2::SubRequest ();
  $r->internal_redirect($new_uri);

So, how do I create $r (or access it)?

I've seen this:

sub handler {
  my $r = shift;
  my $req = Apache2::Request->new($r);
  #...
}

But I'm left wondering, does "handler" function automatically get called? Or is there some other magic to get it called?