Apache2::HookRun(3pm)

1docs::api::Apache2::HooUksReurn(C3o)ntributed Perl Documdeonctsa:t:iaopni::Apache2::HookRun(3)
2
3
4

NAME

6       Apache2::HookRun - Perl API for Invoking Apache HTTP phases
7

Synopsis

9         # httpd.conf
10         PerlProcessConnectionHandler MyApache2::PseudoHTTP::handler
11
12         #file:MyApache2/PseudoHTTP.pm
13         #---------------------------
14         package MyApache2::PseudoHTTP;
15
16         use Apache2::HookRun ();
17         use Apache2::RequestUtil ();
18         use Apache2::RequestRec ();
19
20         use Apache2::Const -compile => qw(OK DECLINED DONE SERVER_ERROR);
21
22         # implement the HTTP protocol cycle in protocol handler
23         sub handler {
24             my $c = shift;
25             my $r = Apache2::RequestRec->new($c);
26
27             # register any custom callbacks here, e.g.:
28             # $r->push_handlers(PerlAccessHandler => \&my_access);
29
30             $rc = $r->run_post_read_request();
31             return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
32
33             $rc = $r->run_translate_name;
34             return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
35
36             $rc = $r->run_map_to_storage;
37             return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
38
39             # this must be run all a big havoc will happen in the following
40             # phases
41             $r->location_merge($path);
42
43             $rc = $r->run_header_parser;
44             return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
45
46             my $args = $r->args ⎪⎪ '';
47             if ($args eq 'die') {
48                 $r->die(Apache2::Const::SERVER_ERROR);
49                 return Apache2::Const::DONE;
50             }
51
52             $rc = $r->run_access_checker;
53             return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
54
55             $rc = $r->run_auth_checker;
56             return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
57
58             $rc = $r->run_check_user_id;
59             return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
60
61             $rc = $r->run_type_checker;
62             return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
63
64             $rc = $r->run_fixups;
65             return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
66
67             # $r->run_handler is called internally by $r->invoke_handler,
68             # invoke_handler sets all kind of filters, and does a few other
69             # things but it's possible to call $r->run_handler, bypassing
70             # invoke_handler
71             $rc = $r->invoke_handler;
72             return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
73
74             $rc = $r->run_log_transaction;
75             return $rc unless $rc == Apache2::Const::OK or $rc == Apache2::Const::DECLINED;
76
77             return Apache2::Const::OK;
78         }
79

Description

81       "Apache2::HookRun" exposes parts of the Apache HTTP protocol implemen‐
82       tation, responsible for invoking callbacks for each HTTP Request cycle
83       phase.
84
85       Armed with that API, you could run some of the http protocol framework
86       parts when implementing your own protocols. For example see how HTTP
87       AAA (access, auth and authz) hooks are called from a protocol handler,
88       implementing a command server, which has nothing to do with HTTP. Also
89       you can see in Synopsis how to re-implement Apache HTTP cycle in the
90       protocol handler.
91
92       Using this API you could probably also change the normal Apache behav‐
93       ior (e.g. invoking some hooks earlier than normal, or later), but
94       before doing that you will probably need to spend some time reading
95       through the Apache C code. That's why some of the methods in this docu‐
96       ment, point you to the specific functions in the Apache source code. If
97       you just try to use the methods from this module, without understanding
98       them well, don't be surprised if you will get some nasty crashes, from
99       which mod_perl can't protect you.
100

API

102       "Apache2::HookRun" provides the following functions and/or methods:
103
104       "die"
105
106       Kill the current request
107
108         $r->die($type);
109
110       obj: $r ( "Apache2::RequestRec object" )
111           The current request
112
113       arg1: $type ( integer )
114           Why the request is dieing. Expects an Apache status constant.
115
116       ret: no return value
117       since: 2.0.00
118
119       This method doesn't really abort the request, it just handles the send‐
120       ing of the error response, logging the error and such.  You want to
121       take a look at the internals of "ap_die()" in httpd-2.0/mod‐
122       ules/http/http_request.c for more details.
123
124       "invoke_handler"
125
126       Run the response phase.
127
128         $rc = $r->invoke_handler();
129
130       obj: $r ( "Apache2::RequestRec object" )
131           The current request
132
133       ret: $rc ( integer )
134           The status of the current phase run: "Apache2::Const::OK",
135           "Apache2::HTTP_..."
136
137       since: 2.0.00
138
139       "invoke_handler()" allows modules to insert filters, sets a default
140       handler if none is set, runs "run_handler()" and handles some errors.
141
142       For more details see "ap_invoke_handler()" in httpd-2.0/server/con‐
143       fig.c.
144
145       "run_access_checker"
146
147       Run the resource access control phase.
148
149         $rc = $r->run_access_checker();
150
151       obj: $r ( "Apache2::RequestRec object" )
152           the current request
153
154       ret: $rc ( integer )
155           The status of the current phase run: "Apache2::Const::OK",
156           "Apache2::Const::DECLINED", "Apache2::HTTP_...".
157
158       since: 2.0.00
159
160       This phase runs before a user is authenticated, so this hook is really
161       to apply additional restrictions independent of a user. It also runs
162       independent of '"Require"' directive usage.
163
164       "run_auth_checker"
165
166       Run the authentication phase.
167
168         $rc = $r->run_auth_checker();
169
170       obj: $r ( "Apache2::RequestRec object" )
171           the current request
172
173       ret: $rc ( integer )
174           The status of the current phase run: "Apache2::Const::OK",
175           "Apache2::Const::DECLINED", "Apache2::HTTP_...".
176
177       since: 2.0.00
178
179       This phase is used to check to see if the resource being requested is
180       available for the authenticated user ("$r->user" and
181       "$r->ap_auth_type").
182
183       It runs after the access_checker and check_user_id hooks.
184
185       Note that it will only be called if Apache determines that access con‐
186       trol has been applied to this resource (through a '"Require"' direc‐
187       tive).
188
189       "run_check_user_id"
190
191       Run the authorization phase.
192
193         $rc = $r->run_check_user_id();
194
195       obj: $r ( "Apache2::RequestRec object" )
196           The current request
197
198       ret: $rc ( integer )
199           The status of the current phase run: "Apache2::Const::OK",
200           "Apache2::Const::DECLINED", "Apache2::HTTP_...".
201
202       since: 2.0.00
203
204       This hook is used to analyze the request headers, authenticate the
205       user, and set the user information in the request record ("$r->user"
206       and "$r->ap_auth_type").
207
208       This hook is only run when Apache determines that authentication/autho‐
209       rization is required for this resource (as determined by the
210       '"Require"' directive).
211
212       It runs after the access_checker hook, and before the auth_checker
213       hook.
214
215       "run_fixups"
216
217       Run the fixup phase.
218
219         $rc = $r->run_fixups();
220
221       obj: $r ( "Apache2::RequestRec object" )
222           The current request
223
224       ret: $rc ( integer )
225           The status of the current phase run: "Apache2::Const::OK",
226           "Apache2::Const::DECLINED", "Apache2::HTTP_...".
227
228       since: 2.0.00
229
230       This phase allows modules to perform module-specific fixing of HTTP
231       header fields.  This is invoked just before the response phase.
232
233       "run_handler"
234
235       Run the response phase.
236
237         $rc = $r->run_handler();
238
239       obj: $r ( "Apache2::RequestRec object" )
240           The request_rec
241
242       ret: $rc ( integer )
243           The status of the current phase run: "Apache2::Const::OK",
244           "Apache2::Const::DECLINED", "Apache2::HTTP_...".
245
246       since: 2.0.00
247
248       "run_handler()" is called internally by "invoke_handler()". Use
249       "run_handler()" only if you want to bypass the extra functionality pro‐
250       vided by "invoke_handler()".
251
252       "run_header_parser"
253
254       Run the header parser phase.
255
256         $rc = $r->run_header_parser();
257
258       obj: $r ( "Apache2::RequestRec object" )
259           The current request
260
261       ret: $rc ( integer )
262           "Apache2::Const::OK" or "Apache2::Const::DECLINED".
263
264       since: 2.0.00
265
266       "run_log_transaction"
267
268       Run the logging phase.
269
270         $rc = $r->run_log_transaction();
271
272       obj: $r ( "Apache2::RequestRec object" )
273           The current request
274
275       ret: $rc ( integer )
276           The status of the current phase run: "Apache2::Const::OK",
277           "Apache2::Const::DECLINED", "Apache2::HTTP_..."
278
279       since: 2.0.00
280
281       This hook allows modules to perform any module-specific logging activi‐
282       ties over and above the normal server things.
283
284       "run_map_to_storage"
285
286       Run the map_to_storage phase.
287
288         $rc = $r->run_map_to_storage();
289
290       obj: $r ( "Apache2::RequestRec object" )
291           The current request
292
293       ret: $rc ( integer )
294           "Apache2::Const::DONE" (or "Apache2::HTTP_*") if this contextless
295           request was just fulfilled (such as "TRACE"), "Apache2::Const::OK"
296           if this is not a file, and "Apache2::Const::DECLINED" if this is a
297           file.  The core map_to_storage ("Apache2::HOOK_RUN_LAST") will
298           "directory_walk()" and "file_walk()" the "$r->filename" (all inter‐
299           nal C functions).
300
301       since: 2.0.00
302
303       This phase allows modules to set the per_dir_config based on their own
304       context (such as "<Proxy>" sections) and responds to contextless
305       requests such as "TRACE" that need no security or filesystem mapping
306       based on the filesystem.
307
308       "run_post_read_request"
309
310       Run the post_read_request phase.
311
312         $rc = $r->run_post_read_request();
313
314       obj: $r ( "Apache2::RequestRec object" )
315           The current request
316
317       ret: $rc ( integer )
318           The status of the current phase run: "Apache2::Const::OK" or
319           "Apache2::Const::DECLINED".
320
321       since: 2.0.00
322
323       This phase is run right after "read_request()" or "internal_redi‐
324       rect()", and not run during any subrequests.  This hook allows modules
325       to affect the request immediately after the request has been read, and
326       before any other phases have been processes.  This allows modules to
327       make decisions based upon the input header fields
328
329       "run_translate_name"
330
331       Run the translate phase.
332
333         $rc = $r->run_translate_name();
334
335       obj: $r ( "Apache2::RequestRec object" )
336           The current request
337
338       ret: $rc ( integer )
339           The status of the current phase run: "Apache2::Const::OK",
340           "Apache2::Const::DECLINED", "Apache2::HTTP_...".
341
342       since: 2.0.00
343
344       This phase gives modules an opportunity to translate the URI into an
345       actual filename.  If no modules do anything special, the server's
346       default rules will be applied.
347
348       "run_type_checker"
349
350       Run the type_checker phase.
351
352         $rc = $r->run_type_checker();
353
354       obj: $r ( "Apache2::RequestRec object" )
355           the current request
356
357       ret: $rc ( integer )
358           The status of the current phase run: "Apache2::Const::OK",
359           "Apache2::Const::DECLINED", "Apache2::HTTP_...".
360
361       since: 2.0.00
362
363       This phase is used to determine and/or set the various document type
364       information bits, like "Content-type" (via "$r->content_type"), lan‐
365       guage, etc.
366

Copyright

371       mod_perl 2.0 and its core modules are copyrighted under The Apache
372       Software License, Version 2.0.
373

Authors

375       The mod_perl development team and numerous contributors.
376
377
378
379perl v5.8.8                       2006-11-19    docs::api::Apache2::HookRun(3)

NAME

Synopsis

Description

API

See Also

Copyright

Authors