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

Copyright

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

Authors

361       The mod_perl development team and numerous contributors.
362
363
364
365perl v5.38.0                      2023-07-20    docs::api::Apache2::HookRun(3)

NAME

Synopsis

Description

API

See Also

Copyright

Authors