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
82       implementation, responsible for invoking callbacks for each HTTP
83       Request cycle 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
93       behavior (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
96       document, point you to the specific functions in the Apache source
97       code. If you just try to use the methods from this module, without
98       understanding them well, don't be surprised if you will get some nasty
99       crashes, from which mod_perl can't protect you.
100

API

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

Copyright

358       mod_perl 2.0 and its core modules are copyrighted under The Apache
359       Software License, Version 2.0.
360

Authors

362       The mod_perl development team and numerous contributors.
363
364
365
366perl v5.34.0                      2022-02-02    docs::api::Apache2::HookRun(3)

NAME

Synopsis

Description

API

See Also

Copyright

Authors