File Coverage

blib/lib/Apache/Stage.pm
Criterion Covered Total %
statement 1 3 33.3
branch n/a
condition n/a
subroutine 1 1 100.0
pod n/a
total 2 4 50.0


line stmt bran cond sub pod time code
1             package Apache::Stage;
2 1     1   3643 use Apache::Constants qw(DECLINED);
  0            
  0            
3             use strict;
4             use vars qw($VERSION $STAGE_REGEX $DEBUG);
5              
6             $VERSION = '1.20';
7             $DEBUG = 0;
8              
9             sub handler {
10             my($r) = @_;
11              
12             my($redir,$chimp,$subr,$subret);
13             $STAGE_REGEX ||= $r->dir_config("apache_stage_regex") ||
14             q{ ^ (/STAGE/[^/]*) (.*) $ };
15             ($chimp, $redir) = $r->prev->uri =~ m| $STAGE_REGEX |ox;
16             return DECLINED unless length($redir);
17              
18             # Try it
19             $subr = $r->lookup_uri($redir);
20             $subret = $subr->run;
21              
22             # Propagate error or success code
23             $r->status($subret);
24              
25             # Handle 301/2. That often indicates a forgotten trailing slash.
26             if ($subret == 301 or $subret == 302) {
27              
28             # Read Location
29             $redir = $subr->header_out("Location");
30              
31             # Rewrite Location
32             require URI::URL;
33             my $uri = URI::URL->new($redir);
34             $uri->path($chimp . $uri->path);
35             $r->header_out("Location",$uri->abs->as_string);
36              
37             # Header out leads to immediate rerequest by browser
38             $r->send_http_header;
39             }
40              
41             $r->log_error("redir[$redir] chimp[$chimp] subr[$subr] subret[$subret]")
42             if $DEBUG;
43             }
44              
45             1;
46              
47             =head1 NAME
48              
49             Apache::Stage - Manage A Staging Directory
50              
51             =head1 SYNOPSIS
52              
53            
54             # this location is served by normal apache. It's recommended to
55             # restrict access to this location to registered authors of this
56             # site, but a restriction isn't necessary
57             ErrorDocument 403 /stage-redir
58             ErrorDocument 404 /stage-redir
59            
60              
61            
62             # the name of this location must match the ErrorDocument redirects
63             # above
64              
65             # PerlSetVar apache_stage_regex " ^ (/STAGE/[^/]*) (.*) $ "
66              
67             # This regex has to split a staged URI into two parts. It is
68             # evaluated with the /ox switch in effect, so this will NOT be a
69             # per-directory variable. The first part will be thrown away and
70             # just the second part will be served if the original URI cannot
71             # be accessed. In case of 301 and 302 redirects the first part
72             # will be prepended again. The default regex is defined as above
73             # which means that URIS will be split into "/STAGE/anyuser" and
74             # the rest.
75              
76             SetHandler perl-script
77             PerlHandler Apache::Stage
78             Options ExecCGI
79              
80            
81              
82             =head1 DESCRIPTION
83              
84             A staging place is a place where an author of an HTML document checks
85             the look and feel of a document before it's uploaded to the final
86             location. A staging place doesn't need to be a separate server, nor
87             need it be a mirror of the "real" tree, and not even a tree of
88             symbolic links. A sparse directory tree that holds nothing but the
89             staged files will do.
90              
91             Apache::Stage implements a staging directory that needs a minimum of space.
92             Per default the path for the per-user staging directory is hardcoded as
93              
94             /STAGE/any-user-name
95              
96             The code cares for proper internal and external redirects for any
97             documents that are not in the stage directory tree. This means that
98             all graphics are displayed as they will be later after the staged
99             files will have been published. The following table describes what has
100             been tested:
101              
102             Location Redirect to Comment
103              
104             /STAGE/u1/ / Homepage. Internal Redirect.
105              
106             /STAGE/u2/dir1 /dir1/ Really /dir1/index.html
107              
108             /STAGE/u3/dir2 /dir2/ Directory has no index.html
109             Options Indexes is off, thus
110             "Forbidden"
111              
112             /STAGE/u4/dir2/foo /dir2/foo Internal redirect.
113              
114             /STAGE/u5/bar - Exists really, no redirect
115             necessary
116              
117             /STAGE/u6 - Fails unless location exists
118              
119             The entries described in SYNOPSIS in the access.conf or an equivalent
120             place define the name of the staging directory, the name of an
121             internal location that catches the exception when a document is not in
122             the staging directory, and the regular expression that transforms the
123             staging URI into the corresponding public URI.
124              
125             With this setup only ErrorDocument 403 and 404 will be served by
126             Apache::Stage. If you need coexistence with different ErrorDocument
127             handlers, you will either have to disable them for /STAGE or integrate
128             the code of Apache::Stage into an if/else branch based on the path.
129              
130             =head1 HISTORY
131              
132             This module has not changed since 1997.
133              
134             =head1 AUTHOR
135              
136             andreas.koenig@anima.de
137              
138             =head1 LICENSE
139              
140             This program is free software; you can redistribute it and/or modify
141             it under the same terms as Perl itself.
142              
143             =cut