Module Rpc_server

module Rpc_server: sig .. end

exception Connection_lost

raised by the 'reply' function if the connection to the original caller has been lost in the meantime.

type t 

represents a server for an RPC program

type session 

identifies a pair of a call and a reply

type connection_id 

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.

val create : ?program_number:Rtypes.uint4 ->
       ?version_number:Rtypes.uint4 ->
       Unixqueue.event_system ->
       connector ->
       Rpc.protocol ->
       Rpc.mode -> Rpc_program.t -> binding list -> int -> t

Deprecated creation of an RPC server. For new programs, use create2 or one of its variants.

Creates a new server that is pushed onto the event queue. The connector, protocol and mode values control the network type of the server. Note that not all combinations are valid; the following can be used:

• any connector, protocol=Tcp, mode=Socket: creates a classic TCP server socket that allows multiple stream connections at the same time
• connector=Descriptor s, protocol=Tcp, mode=BiPipe: (where s is one half of a socketpair) creates a stream socket that is the endpoint of a point-to-point stream connection (bidirectional pipe)
• any Internet namespace connector, protocol=Udp, mode=Socket: creates a UDP server socket that allows serving multiple datagrams

Note: If 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 necessary.

connector = Dynamic_descriptor: The open descriptor is closed after use.

The 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 ?program_number and ?version_number override the numbers specified in the passed program.

Notes on servers:

• servers that allow multiple connections never terminate by themselves
• servers for only one connection (endpoint of a bidirectional pipe) terminate if they see an EOF on the stream; in this case the stream is closed by the server
• the create function 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.

class type socket_config = object .. end

val default_socket_config : socket_config

class default_socket_config : socket_config

type mode2 = [ `Dummy of Rpc.protocol
       | `Multiplexer_endpoint of Rpc_transport.rpc_multiplex_controller
       | `Socket of Rpc.protocol * connector * socket_config
       | `Socket_endpoint of Rpc.protocol * Unix.file_descr ] 

Determines the type of the server for create2:

• `Socket_endpoint(proto,fd): Socket fd is a connected socket descriptor used for communication. proto determines the encapsulation; should be Tcp for stream sockets and Udp for datagram sockets.

• `Multiplexer_endpoint m: m is an RPC multiplex controller.

• `Socket(proto, conn, config): Opens or uses a server socket according to conn. proto determines the encapsulation; should be Tcp for stream sockets and Udp for datagram sockets. config specifies configuration details.

Despite their names, `Socket_endpoint and `Socket also support Win32 named pipes.

val create2 : mode2 -> Unixqueue.event_system -> t

Creates a server according to the mode2 argument. This kind of server does initially not have any bindings.

val bind : ?program_number:Rtypes.uint4 ->
       ?version_number:Rtypes.uint4 ->
       Rpc_program.t -> binding list -> t -> unit

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 same server.

val unbind : ?program_number:Rtypes.uint4 ->
       ?version_number:Rtypes.uint4 -> Rpc_program.t -> t -> unit

Unbinds the program if it is bound by the server

val bound_programs : t -> Rpc_program.t list

Returns the bound programs

val get_event_system : session -> Unixqueue.event_system

Find out the event system that contains the 'session'

val get_connection_id : session -> connection_id

Get the connection_id

val get_xid : session -> Rtypes.uint4

Returns the session ID. Important note: This number identifies the session from the caller's view, not from the server's view!

val get_socket_name : session -> Unix.sockaddr

val get_peer_name : session -> Unix.sockaddr

Return the address of the socket serving the session, and the client socket, resp. These functions fail if the server is not running on a socket.

val get_conn_socket_name : connection_id -> Unix.sockaddr

val get_conn_peer_name : connection_id -> Unix.sockaddr

Return the address of the socket serving the connection, and the client socket, resp. These functions fail if the server is not running on a socket.

val get_server : session -> t

Returns the server instance of the session

val get_main_socket_name : t -> Unix.sockaddr

Returns the address of the server socket, or the address of the bidirectional pipe. This function fails if the main file descriptor is not a socket.

val get_protocol : t -> Rpc.protocol

Return whether Tcp or Udp

val get_srv_event_system : t -> Unixqueue.unix_event_system

Returns the event system

val get_last_proc_info : t -> string

Get a debug string describing the last invoked procedure

type rule = [ `Accept
       | `Accept_limit_length of int * rule
       | `Deny
       | `Drop
       | `Reject
       | `Reject_with of Rpc.server_error ] 

val set_session_filter : t -> (Rpc_transport.sockaddr -> rule) -> unit

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 `Reject_with Rpc.Auth_too_weak `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.

val set_session_filter_2 : t ->
       (Rpc_transport.sockaddr -> connection_id -> rule) ->
       unit

Same as set_session_filter, but the filter gets as second argument the connection ID.

val reply : session -> Xdr.xdr_value -> unit

Asynchronous procedures can reply their results with this function.

NOTES:

• As with synchronous procedures, the transfer is not reliable since the connection may be broken at any time
• If it is already known that the connection is down, a Connection_lost exception is raised.
• If you don't want to reply to a certain call, just don't reply. Unreplied calls do not allocate memory.
• It is possible to reply several times ("batch mode"), but the client must support it, too. Just call reply several times for the same session.

val reply_error : session -> Rpc.server_error -> unit

Like reply, but an error condition is sent back to the caller.

val set_exception_handler : t -> (exn -> unit) -> unit

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:

• The default exception handler logs a `Crit message using Netlog.
• I/O problems usually lead to an 'Abort' of the whole server.

val set_onclose_action : t -> (connection_id -> unit) -> unit

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 called for 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.

val set_timeout : t -> float -> unit

Sets the timeout for the transport.

val stop_server : ?graceful:bool -> t -> unit

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.

val stop_connection : t -> connection_id -> unit

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).

type auth_peeker = [ `None
       | `Peek_descriptor of Unix.file_descr -> string option
       | `Peek_multiplexer of
           Rpc_transport.rpc_multiplex_controller -> string option ] 

class type auth_method = object .. end

val set_auth_methods : t -> auth_method list -> unit

Sets the available authentication methods. By default, the list is set to auth_none . If none of the methods apply, the call is rejected (Auth_too_weak).

val auth_none : auth_method

The authentication method "AUTH_NONE", i.e. no user name is passed. The function get_user will return "".

val auth_too_weak : auth_method

The method that always rejects.

val auth_transport : auth_method

Authenticate by trusting the transport layer. The user returned by the multiplexer's method peer_user_name is taken.

val get_user : session -> string

Returns the user name as returned by the authentication method. See the description of the method for the format of the user name string.

val get_auth_method : session -> auth_method

Returns the method that was used to authenticate the user.

val verbose : bool -> unit

Deprecated. Set whether you want debug messages to stderr or not

module Debug: sig .. end