1Apache::RPC::Server(3)User Contributed Perl DocumentationApache::RPC::Server(3)
2
3
4

NAME

6       Apache::RPC::Server - A subclass of RPC::XML::Server tuned for mod_perl
7

SYNOPSIS

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
26           # In the start-up Perl file:
27           use Apache::RPC::Server;
28

DESCRIPTION

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
33       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
43       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

SUBROUTINES/METHODS

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
53   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
58       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
66           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
70       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
79           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
86       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
94           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
99           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
105           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
110           prefix  The prefix is used in retrieving certain configuration
111                   settings from the Apache configuration file.
112
113           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
118       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
128           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
133       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
140           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
144       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
149       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
154       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
159   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
165       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
171       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
181           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
185       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
192       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
204       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
210       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
220       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
229   Specifying methods to the server(s)
230       Methods are provided to an Apache::RPC::Server object in three ways:
231
232       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
238       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
244       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
249       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
258   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
264       In doing this, two immediate benefits are gained:
265
266       (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
273       (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
280       The following example illustrates these concepts in a fairly simple
281       environment:
282
283           # In httpd.conf:
284           <Perl>
285
286           # First, create and configure some Apache::RPC::Server objects
287
288           # 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
296           # 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
314           </Perl>
315
316       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
320       "handler()" method for each of the locations to be handed the
321       Apache::RPC::Server object directly. Note also that the value assigned
322       to "PerlHandler" cannot be a lexical variable, or it will be out of
323       scope when the handler is called.
324

DIAGNOSTICS

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
330       Where appropriate, the "log_error" method from the Apache package is
331       called to note internal errors.
332

CAVEATS

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

BUGS

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

SUPPORT

347       •   RT: CPAN's request tracker
348
349           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=RPC-XML>
350
351       •   AnnoCPAN: Annotated CPAN documentation
352
353           <http://annocpan.org/dist/RPC-XML>
354
355       •   CPAN Ratings
356
357           <http://cpanratings.perl.org/d/RPC-XML>
358
359       •   Search CPAN
360
361           <http://search.cpan.org/dist/RPC-XML>
362
363       •   MetaCPAN
364
365           <https://metacpan.org/release/RPC-XML>
366
367       •   Source code on GitHub
368
369           <http://github.com/rjray/rpc-xml>
370
372       This file and the code within are copyright (c) 2011 by Randy J. Ray.
373
374       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

CREDITS

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

SEE ALSO

385       RPC::XML::Server, RPC::XML
386

AUTHOR

388       Randy J. Ray "<rjray@blackperl.com>"
389
390
391
392perl v5.34.0                      2021-07-22            Apache::RPC::Server(3)
Impressum