1Apache::RPC::Server(3)User Contributed Perl DocumentationApache::RPC::Server(3)
2
6 Apache::RPC::Server - A subclass of RPC::XML::Server tuned for mod_perl
7
9 # In httpd.conf:
10 PerlModule Apache::RPC::Server
11 PerlSetVar RpcMethodDir /var/www/rpc:/usr/lib/perl5/RPC-shared
12 PerlChildInitHandler Apache::RPC::Server->init_handler
13 ...
14 <Location /RPC>
15 SetHandler perl-script
16 PerlHandler Apache::RPC::Server
17 </Location>
18 </Location /RPC-limited>
19 SetHandler perl-script
20 PerlHandler Apache::RPC::Server
21 PerlSetVar RPCOptPrefix RpcLimit
22 PerlSetVar RpcLimitRpcServer Limited
23 PerlSetVar RpcLimitRpcMethodDir /usr/lib/perl5/RPC-shared
24 </Location>
25 # In the start-up Perl file:
27 use Apache::RPC::Server;
28
30 The Apache::RPC::Server module is a subclassing of RPC::XML::Server
31 that is tuned and designed for use within Apache with mod_perl.
32 Provided are phase-handlers for the general request-processing phase
34 ("PerlHandler") and the child-process initialization phase
35 ("PerlChildInitHandler"). The module should be loaded either by
36 inclusion in a server start-up Perl script or by directives in the
37 server configuration file (generally httpd.con). One loaded, the
38 configuration file may assign the module to handle one or more given
39 locations with the general set of "<Location>" directives and familiar
40 options. Additional configuration settings specific to this module are
41 detailed below.
42 Generally, externally-available methods are provided as files in the
44 XML dialect explained in RPC::XML::Server. A subclass derived from this
45 class may of course use the methods provided by this class and its
46 parent class for adding and manipulating the method table.
47
49 The methods that the server publishes are provided by a combination of
50 the installation files and Apache configuration values. Details on
51 remote method syntax and semantics is covered in RPC::XML::Server.
52 Methods
54 In addition to inheriting all the methods from RPC::XML::Server, the
55 following methods are either added or overloaded by
56 Apache::RPC::Server:
57 handler
59 This is the default content-handler routine that mod_perl expects
60 when the module is defined as managing the specified location. This
61 is provided as a method handler, meaning that the first argument is
62 either an object reference or a static string with the class name.
63 This allows for other packages to easily subclass
64 Apache::RPC::Server.
65 This routine takes care of examining the incoming request, choosing
67 an appropriate server object to actually process the request, and
68 returning the results of the remote method call to the client.
69 init_handler
71 This is another Apache-level handler, this one designed for
72 installation as a "PerlChildInitHandler". At present, its only
73 function is to iterate over all server object currently in the
74 internal tables and invoke the "child_started" method (detailed
75 below) on each. Setting this handler assures that each child has a
76 correct impression of when it started as opposed to the start time
77 of the server itself.
78 Note that this is only applied to those servers known to the master
80 Apache process. In most cases, this will only be the default server
81 object as described above. That is because of the delayed-loading
82 nature of all servers beyond the default, which are likely only in
83 child-specific memory. There are some configuration options
84 described in the next section that can affect and alter this.
85 new(HASH)
87 This is the class constructor. It calls the superclass "new"
88 method, then performs some additional steps. These include
89 installing the default methods (which includes an Apache-specific
90 version of "system.status"), adding the installation directory of
91 this module to the method search path, and adding any directories
92 or explicitly-requested methods to the server object.
93 The arguments to the constructor are regarded as a hash table (not
95 a hash reference), and are mostly passed unchanged to the
96 constructor for RPC::XML::Server. Three parameters are of concern
97 to this class:
98 apache The value associated with this key is a reference to an
100 Apache request object. If this is not passed, then it is
101 assumed that this is being called in the start-up phase of
102 the server and the value returned from "Apache->server"
103 (see Apache) is used.
104 server_id
106 This provides the server ID string for the RPC server (not
107 to be confused with the Apache server) that is being
108 configured.
109 prefix The prefix is used in retrieving certain configuration
111 settings from the Apache configuration file.
112 The server identification string and prefix concepts are explained
114 in more detail in the next section. See RPC::XML::Server for a full
115 list of what additional arguments may be passed to new for eventual
116 proxy to the parent class constructor.
117 child_started([BOOLEAN])
119 This method is very similar to the "started" method provided by
120 RPC::XML::Server. When called with no argument or an argument that
121 evaluates to a false value, it returns the UNIX-style time value of
122 when this child process was started. Due to the child-management
123 model of Apache, this may very well be different from the value
124 returned by "started" itself. If given an argument that evaluates
125 as true, the current system time is set as the new child-start
126 time.
127 If the server has not been configured to set this at child
129 initialization, then the main "started" value is returned. The name
130 is different so that a child may specify both server-start and
131 child-start times with clear distinction.
132 get_server(APACHEREQ|STRING)
134 Get the server object that corresponds to the argument passed. If
135 the argument is a reference to an Apache request object, use it to
136 determine the name (by path, etc.) and return that object. If the
137 parameter is not a reference, it is assumed to be the specific name
138 desired.
139 If the requested server object does not yet exist, an attempt will
141 be made to create it and add it to the internal table. The newly-
142 created object is then returned.
143 list_servers
145 Return a list of the names used for all the current server
146 instances. Does not return the server objects themselves (use
147 get_server, above, for that).
148 version
150 This method behaves exactly like the RPC::XML::Server method,
151 except that the version string returned is specific to this module
152 instead.
153 INSTALL_DIR
155 As with version, this is an overload of the parent-class static
156 method that returns the installation directory of this particular
157 module.
158 Apache configuration semantics
160 In addition to the known directives such as "PerlHandler" and
161 "PerlChildInitHandler", configuration of this system is controlled
162 through a variety of settings that are manipulated with the
163 "PerlSetVar" and "PerlAddVar" directives. These variables are:
164 RPCOptPrefix [STRING]
166 Sets a prefix string to be applied to all of the following names
167 before trying to read their values. Useful for setting within a
168 "<Location>" block to ensure that no settings from a higher point
169 in the hierarchy influence the server being defined.
170 RpcServer [STRING]
172 Specify the name of the server to use for this location. If not
173 passed, then the default server is used. This server may also be
174 explicitly requested by the name """<default>""". If more than one
175 server is going to be created within the same Apache environment,
176 this setting should always be used outside the default area so that
177 the default server is not loaded down with extra method
178 definitions. If a sub-location changes the default server, those
179 changes will be felt by any location that uses that server.
180 Different locations may share the same server by specifying the
182 name with this variable. This is useful for managing varied access
183 schemes, traffic analysis, etc.
184 RpcMethodDir [DIRECTORY]
186 This variable specifies directories to be scanned for method
187 "*.xpl" files. To specify more than one directory, separate them
188 with "":"" just as with any other directory-path expression. All
189 directories are kept (in the order specified) as the search path
190 for future loading of methods.
191 RpcMethod [FILENAME]
193 This is akin to the directory-specification option above, but only
194 provides a single method at a time. It may also have multiple
195 values separated by colons. The method is loaded into the server
196 table. If the name is not an absolute pathname, then it is searched
197 for in the directories that currently comprise the path. The
198 directories above, however, have not been added to the search path
199 yet. This is because these directives are processed immediately
200 after the directory specifications, and thus do not need to be
201 searched. This directive is designed to allow selective overriding
202 of methods in the previously-specified directories.
203 RpcDefMethods [YES|NO]
205 If specified and set to "no" (case-insensitive), suppresses the
206 loading of the system default methods that are provided with this
207 package. The absence of this setting is interpreted as a "yes", so
208 explicitly specifying such is not needed.
209 RpcAutoMethods [YES|NO]
211 If specified and set to "yes", enables the automatic searching for
212 a requested remote method that is unknown to the server object
213 handling the request. If set to "no" (or not set at all), then a
214 request for an unknown function causes the object instance to
215 report an error. If the routine is still not found, the error is
216 reported. Enabling this is a security risk, and should only be
217 permitted by a server administrator with fully informed
218 acknowledgement and consent.
219 RpcAutoUpdates [YES|NO]
221 If specified and set to "yes", enables the checking of the
222 modification time of the file from which a method was originally
223 loaded. If the file has changed, the method is re-loaded before
224 execution is handed off. As with the auto-loading of methods, this
225 represents a potential security risk, and should only be permitted
226 by a server administrator with fully informed acknowledgement and
227 consent.
228 Specifying methods to the server(s)
230 Methods are provided to an Apache::RPC::Server object in three ways:
231 Default methods
233 Unless suppressed by a "RpcDefMethods" option, the methods shipped
234 with this package are loaded into the table. The
235 Apache::RPC::Server objects get a slightly different version of
236 "system.status" than the parent class does.
237 Configured directories
239 All method files (those ending in a suffix of "*.xpl") in the
240 directories specified in the relevant "RpcMethodDir" settings are
241 read next. These directories are also (after the next step) added
242 to the search path the object uses.
243 By specific inclusion
245 Any methods specified directly by use of "RpcMethod" settings are
246 loaded last. This allows for them to override methods that may have
247 been loaded from the system defaults or the specified directories.
248 If a request is made for an unknown method, the object will first
250 attempt to find it by searching the path of directories that were given
251 in the configuration as well as those that are part of the system
252 (installation-level directories). If it is still not found, then an
253 error is reported back to the requestor. By using this technique, it is
254 possible to add methods to a running server without restarting it. It
255 is a potential security hole, however, and it is for that reason that
256 the previously-documented "RpcAutoMethods" setting is provided.
257 Usage Within <Perl> Sections
259 To truly unlock the power of having the RPC server attached to a
260 mod_perl environment, the application and configuration of the server
261 should be done within Perl-configuration blocks on the Apache server
262 itself.
263 In doing this, two immediate benefits are gained:
265 (1) The rpc-server object gets created in the master Apache process,
267 rather than within each child as a side-effect of the first
268 request. Especially in cases where there are going to be more than
269 one server in use within the Apache environment, this boosts
270 performance by allowing newly-created children to already have the
271 server object and method table readily available.
272 (2) It becomes possible to exert more detailed control over the
274 creation and configuration of each server object. Combining the
275 get_method and add_method operations permits "sharing" (of a sort)
276 of methods between server objects. Recall from the RPC::XML::Server
277 documentation that, when a method is invoked, the first argument is
278 the server object that is marshalling it.
279 The following example illustrates these concepts in a fairly simple
281 environment:
282 # In httpd.conf:
284 <Perl>
285 # First, create and configure some Apache::RPC::Server objects
287 # One regular one, with the standard settings:
289 $main::defobj = Apache::RPC::Server->new(path => '/RPC',
290 auto_methods => 1,
291 auto_updates => 1);
292 # One version without the default methods, and no auto-actions
293 $main::secobj = Apache::RPC::Server->new(no_default => 1,
294 path => '/rpc-secured');
295 # Imagine that add_method and/or add_methods_in_dir has been used to
297 # add to the methods tables for those objects. Now assign them to
298 # locations managed by Apache:
299 $Location{'/RPC'} =
300 {
301 SetHandler => 'perl-script',
302 PerlHandler => '$main::defobj'
303 };
304 $Location{'/rpc-secure'} =
305 {
306 SetHandler => 'perl-script',
307 PerlHandler => '$main::secobj',
308 AuthUserFile => '/etc/some_file',
309 AuthType => 'Basic',
310 AuthName => 'SecuredRPC',
311 'require' => 'valid-user'
312 };
313 </Perl>
315 Note that the assignment of the "PerlHandler" value was a string
317 representation of the object reference itself. mod_perl performs a sort
318 of "thaw" of this string when the location is accessed. Since this
319 class implements itself as a method handler, this causes the handler()
320 method for each of the locations to be handed the Apache::RPC::Server
321 object directly. Note also that the value assigned to "PerlHandler"
322 cannot be a lexical variable, or it will be out of scope when the
323 handler is called.
324
326 All methods return some type of reference on success, or an error
327 string on failure. Non-reference return values should always be
328 interpreted as errors unless otherwise noted.
329 Where appropriate, the "log_error" method from the Apache package is
331 called to note internal errors.
332
334 This began as a reference implementation in which clarity of process
335 and readability of the code took precedence over general efficiency. It
336 is now being maintained as production code, but may still have parts
337 that could be written more efficiently.
338
340 Please report any bugs or feature requests to "bug-rpc-xml at
341 rt.cpan.org", or through the web interface at
342 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=RPC-XML>. I will be
343 notified, and then you'll automatically be notified of progress on your
344 bug as I make changes.
345
347 • RT: CPAN's request tracker
348 <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
350 • AnnoCPAN: Annotated CPAN documentation
352 <http://annocpan.org/dist/RPC-XML>
354 • CPAN Ratings
356 <http://cpanratings.perl.org/d/RPC-XML>
358 • Search CPAN
360 <http://search.cpan.org/dist/RPC-XML>
362 • MetaCPAN
364 <https://metacpan.org/release/RPC-XML>
366 • Source code on GitHub
368 <http://github.com/rjray/rpc-xml>
370
372 This file and the code within are copyright (c) 2011 by Randy J. Ray.
373 Copying and distribution are permitted under the terms of the Artistic
375 License 2.0
376 (<http://www.opensource.org/licenses/artistic-license-2.0.php>) or the
377 GNU LGPL 2.1 (<http://www.opensource.org/licenses/lgpl-2.1.php>).
378
380 The XML-RPC standard is Copyright (c) 1998-2001, UserLand Software,
381 Inc. See <http://www.xmlrpc.com> for more information about the XML-
382 RPC specification.
383
385 RPC::XML::Server, RPC::XML
386
388 Randy J. Ray "<rjray@blackperl.com>"
389perl v5.36.0 2023-01-20 Apache::RPC::Server(3)