ubf_server.md

Module ubf_server

• Description
• Data Types
• Function Index
• Function Details

UBF server-side public API.

This module implements most of the commonly-used server-side
functions: starting TCP listeners and registering their
implementation callback modules.

We implement several different wire formats for accessing the same
implementation of a UBF(b) protocol-checking server:

• UBF(a). This is Joe Armstrong's original implementation.

• EBF, a.k.a. Erlang Binary Format. This protocol uses common Erlang wire formats, the {packet, 4} protocol from inets for TCP connections, and the term_to_binary()/binary_to_term() BIFs for payload encoding. These wire formats are used to pass Erlang terms between a UBF(b) contract checking server and a client that does not support the UBF(a) wire format but does support Erlang's native wire formats.

• JSF, a.k.a the JSon Format. Similar to EBF, except that JavaScript's JSON encoding is used for the wire protocol instead of UBF(a) or Erlang's native wire formats.

• TBF, a.k.a the Thrift Binary Format. Similar to EBF, except that Thrift's binary encoding is used for the wire protocol instead of UBF(a) or Erlang's native wire formats.

  There is no "stop" function.  To stop the server, instead stop the
  TCP service manager that controls it: see the +proc_socket_server+
  module for extra details.

  See the documentation for the +file_plugin+ module for extra
  commentary on writing an UBF server implementation module.

.

Data Types

ipport()

ipport() = pos_integer()

name()

name() = atom()

options()

options() = [{atom(), term()}]

plugins()

plugins() = [module()]

Function Index

init/5
start/2	Start a server and a TCP listener on port Port and register all of the protocol implementation modules in the Plugins list. Here we start the server. .
start/3	Start a registered server and a TCP listener on port Port and register all of the protocol implementation modules in the Plugins list. If Name is undefined, the server is not registered. Here we start the server. .
start/4	Start a registered server and a TCP listener on port Port with the Options properties list and register all of the protocol implementation modules in the Plugins list. If Name is undefined, the server is not registered Valid properties in the Options proplist are: {idletimer, integer() | infinity} Maximum time (in milliseconds) that a client connection may remain idle before the server will close the connection. Default: infinity {maxconn, integer()} Maximum number of simultaneous TCP connections allowed. Default: 10,000. {proto, {ubf | ebf | atom()}} Enable the UBF, EBF, or an alternative protocol wire format. Default: ubf. {proto, {ubf | ebf | atom(), [atom() | tuple()]}} Enable the UBF, EBF, or an alternative protocol wire format with options. Default: {ubf, []}. Supported options: - safe Prevents decoding data that may be used to attack the Erlang system. In the event of receiving unsafe data, decoding fails with a badarg error. {registeredname, atom()} Set the name to be registered for the TCP listener. If undefined, a default name is automatically registered. Default: undefined. {statelessrpc, true | false} Run the stateless variety of a UBF(b) contract. A stateless contract is an extension of Joe Armstrong's original UBF server implementation. Default: false. {startplugin, atom()} Set the starting plugin, set after a client first connects to the server. If not set, client may select the service using the startSession() API. There is no default setting. {serverhello, ubfstring() | undefined} Meta contract greeting string, sent when a client first connects to the server. If undefined, server hello is not sent to the client. Default: "meta_server". {simplerpc, true | false} Set the simple RPC mode. If true, server returns only the rpc reply to client. If false, server returns the rpc reply and next state to client. Default: false. {verboserpc, true | false} Set the verbose RPC mode. If true, server calls the plugin handler with the rpc request and matched contract types. If false, server calls the plugin handler only with the rpc request. Default: false. {tlog_module, atom() | {atom(), boolean()}} Set the transaction log callback module and optionally control the built-in calls by contract_manager_tlog to the error_logger module. If the 2-tuple representation is used and the boolean() member is false, then calls to error_logger will not be attempted. Default: undefined. {process_options, list()} Specify additional options used for spawning server and/or client related erlang processes. Typically used to specify non-default, garbage collection options. Default: []. .
start_link/2	See start/2, but also link the server processs to the caller. .
start_link/3	See start/3, but also link the server processs to the caller. .
start_link/4	See start/4, but also link the server processs to the caller. .
start_term_listener/3

Function Details

init/5

init(Name::name(), Parent::pid(), Plugins::plugins(), Port::ipport(), Options::options()) -> pid()

start/2

start(Plugins::plugins(), Port::ipport()) -> true

Start a server and a TCP listener on port Port and register all of the protocol implementation modules in the Plugins list.

Here we start the server.

start/3

start(Name::name(), Plugins::plugins(), Port::ipport()) -> true

Start a registered server and a TCP listener on port Port and register all of the protocol implementation modules in the Plugins list. If Name is undefined, the server is not registered.

Here we start the server.

start/4

start(Name::name(), Plugins::plugins(), Port::ipport(), Options::options()) -> true

Start a registered server and a TCP listener on port Port with the Options properties list and register all of the protocol implementation modules in the Plugins list. If Name is undefined, the server is not registered

Valid properties in the Options proplist are:

• {idletimer, integer() | infinity} Maximum time (in milliseconds) that a client connection may remain idle before the server will close the connection. Default: infinity

• {maxconn, integer()} Maximum number of simultaneous TCP connections allowed. Default: 10,000.

• {proto, {ubf | ebf | atom()}} Enable the UBF, EBF, or an alternative protocol wire format. Default: ubf.

• {proto, {ubf | ebf | atom(), [atom() | tuple()]}} Enable the UBF, EBF, or an alternative protocol wire format with options. Default: {ubf, []}.

  Supported options:
  - safe  Prevents decoding data that may be used to attack the
    Erlang system.  In the event of receiving unsafe data, decoding
    fails with a badarg error.

• {registeredname, atom()} Set the name to be registered for the TCP listener. If undefined, a default name is automatically registered. Default: undefined.

• {statelessrpc, true | false} Run the stateless variety of a UBF(b) contract. A stateless contract is an extension of Joe Armstrong's original UBF server implementation. Default: false.

• {startplugin, atom()} Set the starting plugin, set after a client first connects to the server. If not set, client may select the service using the startSession() API. There is no default setting.

• {serverhello, ubfstring() | undefined} Meta contract greeting string, sent when a client first connects to the server. If undefined, server hello is not sent to the client. Default: "meta_server".

• {simplerpc, true | false} Set the simple RPC mode. If true, server returns only the rpc reply to client. If false, server returns the rpc reply and next state to client. Default: false.

• {verboserpc, true | false} Set the verbose RPC mode. If true, server calls the plugin handler with the rpc request and matched contract types. If false, server calls the plugin handler only with the rpc request. Default: false.

• {tlog_module, atom() | {atom(), boolean()}} Set the transaction log callback module and optionally control the built-in calls by contract_manager_tlog to the error_logger module. If the 2-tuple representation is used and the boolean() member is false, then calls to error_logger will not be attempted. Default: undefined.

• {process_options, list()} Specify additional options used for spawning server and/or client related erlang processes. Typically used to specify non-default, garbage collection options. Default: [].

start_link/2

start_link(Plugins::plugins(), Port::ipport()) -> true

See start/2, but also link the server processs to the caller.

start_link/3

start_link(Name::name(), Plugins::plugins(), Port::ipport()) -> true

See start/3, but also link the server processs to the caller.

start_link/4

start_link(Name::name(), Plugins::plugins(), Port::ipport(), Options::options()) -> true

See start/4, but also link the server processs to the caller.

start_term_listener/3

start_term_listener(Server0::pid(), Plugins::plugins(), Options::options()) -> pid()