Like the client, the RPC server module is programmed on top of the Unixqueue event system. It pushes itself on an existing Unixqueue as a new service that accepts RPC calls, forwards them to configurable functions, and sends the replies back.
The server module can manage two kinds of RPC functions: synchronous and asynchronous. Synchronous functions compute their result immediately and thus the result can be sent back just after the evaluation of the function has finished. In contrast to this, asynchronous functions only get noticed about the call and need not to know immediately what should be answered. Typically, an asynchronous function initiates a second communication channel and its result depends on what happens on the second channel. The communication on this channel is done in an asynchronous way, too, and can be managed by the same event system that carries out the RPC service. After several input or output events, the result has somehow been computed, and the answer can be sent back to the original caller. To do so, the asynchronous RPC function invokes 'reply' together with the necessary session IDs that identify the answer among all answers.
raised by the 'reply' function if the connection to the original caller has been lost in the meantime.
represents a server for an RPC program
identifies a pair of a call and a reply
identifies the connection of a session. For connectionless servers, every session gets a new connection_id. You can compare connection_ids to find out whether two sessions belong to the same connection. Use "=" for equality.
# | Localhost of int
|(*||The service is installed on 'localhost' and listens on the given port number. A number of 0 means that the port is chosen by the operating system. Note: The service is only locally reachable.||*)|
# | Portmapped
|(*||The service is installed on every network interface; the port is chosen by the operating system; the program is registered with the portmapper||*)|
|(*||The service is installed on the passed interface/port combination. Use Unix.inet_addr_any to listen on all network interfaces. Use port 0 to automatically choose the port number.||*)|
# | Unix of string
|(*||The service is installed on a Unix domain socket. Note: the socket path must not exist when the server is started, and the socket must be unlinked when the server terminates. Note Win32: Unix domain sockets are emulated by writing the inet4 port number into a one-line file.||*)|
# | W32_pipe of string
|(*||The service is installed for a named pipe. (Only for Win32.)||*)|
|(*||The service listens on the given file descriptor.||*)|
|(*||The service listens on the returned file descriptor.||*)|
Deprecated creation of an RPC server. For new programs, use
or one of its variants.
Creates a new server that is pushed onto the event queue.
mode values control the network
type of the server. Note that not all combinations are valid; the
following can be used:
mode=Socket: creates a classic TCP server socket that allows multiple stream connections at the same time
sis one half of a socketpair) creates a stream socket that is the endpoint of a point-to-point stream connection (bidirectional pipe)
mode=Socket: creates a UDP server socket that allows serving multiple datagrams
connector = Descriptor _ the file descriptor is not opened by
this module and not closed. The other
connectors work automatically
regarding this point, i.e. descriptors are opened and closed as
connector = Dynamic_descriptor: The open descriptor is closed after use.
Rpc_program.t specifies the procedures that are available and
their signatures. The
binding list should contain for every procedure
name the function that handles calls of the procedures.
The remaining integer is the maximum number of waiting connections if a classic Tcp server socket is used; other connection types ignore this number.
The optional arguments
the numbers specified in the passed program.
Notes on servers:
createfunction may block if the connector is Portmapped
Note for UDP servers: Due to limitations of the ocaml runtime there is a limit of 16K per message.
Determines the type of the server for
fdis a connected socket descriptor used for communication.
protodetermines the encapsulation; should be
Tcpfor stream sockets and
Udpfor datagram sockets.
mis an RPC multiplex controller.
`Socket(proto, conn, config): Opens or uses a server socket according to
protodetermines the encapsulation; should be
Tcpfor stream sockets and
Udpfor datagram sockets.
configspecifies configuration details.
Despite their names,
`Socket also support
Win32 named pipes.
Binds the program as specified by the
binding list. If the portmapper
must be informed, this action is started (and continued in the
background). One can bind several programs in several versions to the
Whether this is a server in
`Dummy mode. These servers cannot be
used for communication
If set, the filter function is invoked every time the beginning of a new RPC call is received, and the result of the filter function determines what to do with the call:
`Deny: TCP connections are immediately closed; UDP packets are dropped
`Drop: The call is dropped (it does not allocate memory)
`Reject_with: A response is sent back that the call is rejected. The
parameter specified the error code
`Reject: The same as
`Accept: The call is accepted without limitation (the default if no
filter is installed)
`Accept_limit_length(n,r): If the call is longer than n bytes, the rule
r will be applied
The parameter of the filter function is the socket address of the client.
The intention of filters is to prevent denial of service attacks. A simple but good filter for TCP servers is set_filter srv (fun _ -> (`Accept_limit_length(n,`Deny)) which accepts messages up to n bytes without limit, and denies longer messages. n is the length of the longest sensible message.
For UDP servers, there is an implicit limit of 16K, so it is not necessary to care about this.
Another application is to restrict which systems can contact this server, based on the IP address of the client.
Note that this is not a protection against distributed denial of service attacks.
Asynchronous procedures can reply their results with this function.
reply. Unreplied calls do not allocate memory.
replyseveral times for the same session.
Sets the exception handler for the server. The exception handler gets most exceptions raised by the functions that are bound to procedures. The exception handler does not get Abort exceptions and any exceptions resulting from I/O problems.
NOTES ABOUT EXCEPTIONS:
`Critmessage using [root:Netlog].
Every time a connection is closed, the onclose function is called
with the closed connection.
The default onclose action is to do nothing. The function is also
Descriptor connectors when the socket should be closed
(for these connectors the socket is not closed by this module).
Note that this action only applies to closed connections. It will not be executed for closed sockets in general (closed master socket, closed datagram socket).
If several onclose actions are set, they will be executed in reverse order.
Stops the server: If a TCP server socket is listening, it is immediately closed. The shutdown procedure for the connections is initiated. Pending result messages are dropped.
graceful: If true, the shutdown procedure is deferred until all
responses have been transferred back to the caller. This includes
any responses added to the message queue in the current callback.
New calls are not accepted.
Schedules a special event that causes the connection to be stopped in the
very near future. The function has only an effect for stream-oriented
servers (mode = Tcp). The connection socket will be closed (unless it
was passed using
Descriptor). Nothing happens for datagram-oriented
servers (mode = Udp).
Encoders and decoders are allowed to raise the exceptions Rpc_server.Late_drop and Rpc.Rpc_server.
|(*||The authentication method generates the positive response
of this RPC call:
# | Auth_drop
|(*||Authentication demands to drop the message||*)|
This can be raised in encryption/decryption functions to prevent that a response is sent.
The name of the authentication method
Which credential flavors are handled by this method
If available, this function is called for every accepted connection. It may return the user name. Notes:
peekis only called once after the stream connection has been accepted
authenticate srv conn_id details f:
This method is called when a remote call has arrived. Its task is
to determine the client user and pass the user name (and the verifier)
back. If the user cannot be authenticated, the call must be rejected.
When the method has done the authentication, it calls the passed
f with the
auth_result. This function can be called
immediately or asynchronously.
Changed in Ocamlnet-3.3: the arguments
xid are new. Added new
The authentication method "AUTH_NONE", i.e. no user name is passed.
get_user will return "".
Authenticate by trusting the transport layer. The user returned by the multiplexer's method peer_user_name is taken.
Returns the user name as returned by the authentication method. See the description of the method for the format of the user name string.
Deprecated. Set whether you want debug messages to stderr or not
Internal function. Cancels all pending I/O operations, and deallocates buffers. This function has only one purpose: The RPC servers inherited by a Netplex child process return memory. The RPC server is unusable after this.