/ 
Prim-0.01
/ PrimServer

NAME

PrimServer - turns your script into a socket based prim server

SYNOPSIS

use PrimServer;

PrimServer->new('hello.somecompany.com',
                'file.acl',
                hello => { CODE => \&hello_sub,
                           DOC  => 'Greets you as you greeted it.'
                         },
);

# echos its name followed by its arguments
sub hello_sub {
  return "hello_sub ", @_;
}

See the source code file called 'server' for a more involved example.

DESCRIPTION

For a better example of how to use this module see the script called server in the distribution directory.

If you want to serve objects, look at PrimObjectServer.pm instead of this module.

A prim server is a participant in the Perl Remote Invocation of Methods paradigm, which allows one perl script to run things inside another perl interpreter either on the same box or remotely (remote prim has not yet been implemented).

To reconstruct yourself as a prim server, call the PrimServer constructor with the name you want to be known by and a hash containing the external names of your exposed methods as keys and hashes with CODE and DOC keys as values. CODE's value must be a valid code reference. DOC's value should be some useful description of what you take and return, for the benefit of the caller. The constructor never returns. Any valid requests from clients are dispatched to the functions you named by its internal infinite connection accepting loop.

It is a good idea to use dots in the name of your server (the first argument to the constructor). This avoids name conflicts. I suggest you use the Java convention of ending the name with your company's registered domain name. What you put before that could be for internal use. For example the above server might register as hello.europeansystems.somecompany.com. The first part is the simple name, the middle part contains company specific categories, the final part is the company's registered domain. When network discovery methods are added, the dots will be used to help them.

The observant reader will have noticed by now that there are no remote objects mentioned above. If you need to serve objects, see PrimObjectServer.pm. This avoids the need for you to roll your own.

Keep in mind that you cannot use the names Prim_constructor or _Prim_discover for function names in your API, since these are used on the client side. Other methods which perl invokes magically are also unavailable as remote methods (since you and the client are using them in their normal manner).

There is currently no security. Anyone who can see your box can run any method you name. Of course, the method itself could have some authentication. In the future I would like to incorporate this into the server. You would either provide a more complex API structure or a directory name where that information could be found. I'm open to suggestions.

INTERNALS

The server made on your behalf by this script uses the following scheme. It binds a socket to an ephemeral port, writes that port number in /tmp/name.prim (where name is the one you passed to new), and goes into an infinite connection accepting loop. For each connection a new child is forked. Requests are stateless, so after receiving a caller request and sending the reply, the child server dies. (PrimObjectServer.pm works differently.)

All requests and responses use the prim protocols. There are described in the protocols file in the distribution directory. To sum up, they are valid xml with the root tag of prim. The ending </prim> tag is used as a sentinal value. All packets must be newline terminated.

BUGS

Though the connection loop forks, it does not time out. A client could fail to complete a valid request. For honest clients, their own time out should be enough to fix this, but nefarious clients could use the lack of a time out to conduct a denial of service attack.

There is no way to shutdown a PrimServer gracefully. That in turn means that there is no way to deregister the server (by removing its /tmp prim file), so clients will receive 'Connection refused' instead of 'No such server up at this time'.

At this point, due to the implementation of PrimClient.pm, only the localhost can provide prim services.

AUTHOR

Phil Crow, philcrow2000@yahoo.com

new

Turns your script into a server. Pass it two things:

  1. The name you want others to call your object.

  2. A hash with your exposed function names as keys and code references to implement those functions as values (the name of the key and the function may differ).

This function NEVER returns. It goes into a standard forking accept loop on the socket it creates.