module Rpc_server:sig..end
RPC servers
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.
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.
type connector =
| |
Localhost of |
(* | 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. IPv6: not supported for compatibility reasons | *) |
| |
Portmapped |
(* | The service is installed on every network interface; the port is chosen by the operating system; the program is registered with the portmapper (or rpcbind). IPv6: if the socket can be bound to ::, this is preferred. Also,
if | *) |
| |
Internet of |
(* | The service is installed on the passed interface/port combination.
Use | *) |
| |
Unix of |
(* | 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 |
(* | The service is installed for a named pipe. (Only for Win32.) | *) |
| |
Descriptor of |
(* | The service listens on the given file descriptor. | *) |
| |
Dynamic_descriptor of |
(* | The service listens on the returned file descriptor. | *) |
type binding_sync = {
|
sync_name : |
(* | procedure name | *) |
|
sync_proc : |
(* | the function that implements the procedure | *) |
type binding_async = {
|
async_name : |
(* | procedure name | *) |
|
async_invoke : |
(* | A function that is called when the procedure is called | *) |
type binding =
| |
Sync of |
(* | bind a synchonous procedure | *) |
| |
Async of |
(* | bind an asynchonous procedure | *) |
val connector_of_sockaddr : Unix.sockaddr -> connectorConverts the socket address into a connector
val connector_of_socksymbol : Netsockaddr.socksymbol -> connectorConverts the Netsockaddr.socksymbol into a connector
val create : ?program_number:Netnumber.uint4 ->
?version_number:Netnumber.uint4 ->
Unixqueue.event_system ->
connector ->
Rpc.protocol ->
Rpc.mode -> Rpc_program.t -> binding list -> int -> tDeprecated 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:
connector, protocol=Tcp, mode=Socket:
creates a classic TCP server socket that allows multiple
stream connections at the same timeconnector=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)protocol=Udp, mode=Socket:
creates a UDP server socket that allows serving multiple datagramsNote: 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:
create function may block if the connector is PortmappedNote 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
val tls_socket_config : (module Netsys_crypto_types.TLS_CONFIG) -> socket_configThis configuration establishes TLS when accepting new connections.
It is (so far) only compatible with Rpc.Tcp.
class tls_socket_config :(module Netsys_crypto_types.TLS_CONFIG) ->socket_config
TLS configuration as class
typeinternal_pipe =Netxdr.xdr_value Netsys_polypipe.polypipe
typeinternal_socket =Netxdr.xdr_value Netsys_polysocket.polyserver
typemode2 =[ `Dummy of Rpc.protocol
| `Internal_endpoint of internal_pipe * internal_pipe
| `Internal_socket of internal_socket
| `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.`Internal_endpoint(rd,wr): Creates a server that exchanges
data over the pair of polypipes (rd,wr) (see Netsys_polypipe).
The polypipes will be closed when the connection is terminated.`Internal_socket psock: Creates a server that accepts connections
from the polysocket server psock (see Netsys_polysocket).
The polysocket will be closed when the server is stopped.Despite their names, `Socket_endpoint and `Socket also support
Win32 named pipes.
val create2 : mode2 -> Unixqueue.event_system -> tCreates a server according to the mode2 argument. This kind of server
does initially not have any bindings.
val bind : ?program_number:Netnumber.uint4 ->
?version_number:Netnumber.uint4 ->
?pm_continue:bool ->
Rpc_program.t -> binding list -> t -> unitBinds 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.
pm_continue: you need to set this to true for all follow-up binds
after the first one. If pm_continue is false, the portmapper entry
is completely removed before a new registration is done. If it is true,
the new registration is appended to the existing one.
val unbind : ?program_number:Netnumber.uint4 ->
?version_number:Netnumber.uint4 -> Rpc_program.t -> t -> unitUnbinds the program if it is bound by the server
val bound_programs : t -> Rpc_program.t listReturns the bound programs
val get_event_system : session -> Unixqueue.event_systemFind out the event system that contains the 'session'
val get_connection_id : session -> connection_idGet the connection_id
val get_xid : session -> Netnumber.uint4Returns 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.sockaddrReturn 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.sockaddrReturn 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 -> tReturns the server instance of the session
val get_main_socket_name : t -> Unix.sockaddrReturns 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.protocolReturn whether Tcp or Udp
val get_srv_event_system : t -> Unixqueue.unix_event_systemReturns the event system
val get_last_proc_info : t -> stringGet a debug string describing the last invoked procedure
val is_dummy : t -> boolWhether this is a server in `Dummy mode. These servers cannot be
used for communication
val get_tls_session_props : session -> Nettls_support.tls_session_props optionGet the TLS properties so far TLS is enabled
val get_gssapi_props : session -> Netsys_gssapi.server_props optionGet the GSSAPI properties if available
typerule =[ `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) -> unitIf 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) ->
unitSame as set_session_filter, but the filter gets as second argument the
connection ID.
val set_mstring_factories : t -> Netxdr_mstring.named_mstring_factories -> unitSets the mstring factories to use for decoding requests containing managed strings
val reply : session -> Netxdr.xdr_value -> unitAsynchronous procedures can reply their results with this function.
NOTES:
reply.
Unreplied calls do not allocate memory.reply several times for the same
session.val reply_error : session -> Rpc.server_error -> unitLike reply, but an error condition is sent back to the caller.
val set_exception_handler : t -> (exn -> string -> unit) -> unitSets 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.
The string is the backtrace if present, or "" otherwise.
NOTES ABOUT EXCEPTIONS:
`Crit message using Netlog.val set_onclose_action : t -> (connection_id -> unit) -> unitEvery 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 -> unitSets the timeout for the transport.
val stop_server : ?graceful:bool -> t -> unitStops 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 -> unitSchedules 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_result =
| |
Auth_positive of |
(* | Successful authentication:
Encoders and decoders are allowed to raise the exceptions
| *) |
| |
Auth_negative of |
(* | Failed authentication | *) |
| |
Auth_reply of |
(* | The authentication method generates the positive response
of this RPC call:
| *) |
| |
Auth_drop |
(* | Authentication demands to drop the message | *) |
exception Late_drop
This can be raised in encryption/decryption functions to prevent that a response is sent.
typeauth_peeker =[ `None
| `Peek_descriptor of Unix.file_descr -> string option
| `Peek_multiplexer of
Rpc_transport.rpc_multiplex_controller -> string option ]
class type auth_details =object..end
class type auth_method =object..end
val set_auth_methods : t -> auth_method list -> unitSets 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_methodThe authentication method "AUTH_NONE", i.e. no user name is passed.
The function get_user will return "".
val auth_too_weak : auth_methodThe method that always rejects.
val auth_transport : auth_methodAuthenticate by trusting the transport layer. The user returned by the multiplexer's method peer_user_name is taken. Use this for getting the user name from a client certificate.
val get_user : session -> stringReturns 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_methodReturns the method that was used to authenticate the user.
val xdr_ctx : t -> Netxdr.ctxGet the recommended XDR context
val verbose : bool -> unitDeprecated. Set whether you want debug messages to stderr or not
val detach : t -> unitInternal 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.
val set_debug_name : t -> string -> unitSet a name printed with debug messages
val get_debug_name : t -> stringGet the debug name
module Debug:sig..end