bundles/org.simantics.databoard/src-isv/spec/Remote Procedure Call.mediawiki

   1 =Remote Procedure Call=
   2 Databoard RPC is a method call interface.
   3 Server is an object that handles service requests.
   4 The server publishes an [[#Interfaces]] that contains a list of callable methods.
   5
   6 ===Network Protocol===
   7 The protocol is very simple. There are two conversing peers, one is ''the client'' and the other ''the server''.
   8 Both parties introduce callable ''network interface''. Typically, the server's has plenty of procedures, and client's
   9 has some callbacks.
  10 The connection starts with handshake and is then followed by repeating conversation of writing ''Requests'' and reading ''Responses''.
  11
  12 In handshake, boths peers write their ''InterfaceDescription'' and message size limits.
  13 (See [[#Definitions|Definitions]]).
  14 Then both parties make a decision to whether accept or reject the other's interface.
  15
  16 =Interfaces=
  17 ''A function type'' can be constructed as <tt>D -> R</tt>, where <tt>D</tt> is the domain and <tt>R</tt> the range of the function.
  18 If the function can throw exceptions, it is denoted as <tt>D -> R throws E<sub>1</sub>, ..., E<sub>k</sub></tt>, where
  19 <tt>E<sub>i</sub></tt> is a datatype for an exception. Multi-parameter types can be defined using the tuple notation:
  20     Double -> Double
  21     () -> String
  22     (Integer,Integer) -> Integer
  23     Integer -> Integer throws IndexOutOfRange
  24
  25 ''A method definition'' is a combination of name and method type.
  26 The format is following, <tt>method M : T</tt>, where <tt>M</tt> is the name and <tt>T</tt> the type of the method.
  27 <tt>T</tt> has to be a function type.
  28     method getSamples : TimeSegment -> Sample[],
  29     method read : ReadRequest -> Sample,
  30     method getValueBounds : TimeSegment -> Sample[2]
  31
  32 ''Interface'' is a specification of fields and methods the interface has to have.
  33 The interface is defined as a record that contains fields and methods definitions in the curly braces.
  34     interface HistoryRecord = {
  35              records : TimeSeries,
  36
  37              method getSamples : TimeSegment -> Sample[],
  38              method read : ReadRequest -> Sample,
  39              method getValueBounds : TimeSegment -> Sample[2]
  40          }
  41
  42 Interfaces may extend other interfaces. This is denoted as <tt>interface I extends B<sub>1</sub>, ..., B<sub>k</sub> { ... }</tt>.
  43     interface MutableHistoryRecord extends HistoryRecord = {
  44              method write : Sample[] -> {},
  45              method clear : {} -> {}
  46          }
  47
  48 ====Request====
  49 Client sends RequestHeader, followed by a serialization of the message's request argument.
  50 The datatype and thus serialization format of the request argument was defined in MethodType which was informed by the server in the handshake.
  51
  52 The server processes the procedure request.
  53 * On procedure success, ResponseHeader is sent, followed by a serialization of ResponseType. ResponseType serialization format was declared in MethodType.
  54 * On procedure failure, ExecutionError_ is sent, followed by a serialization of ErrorType. ErrorType format was declared in MethodType.
  55 * On unexpected error, Exception_ is sent
  56 * On invalid method number, InvalidMethodError is sent
  57 * On request or response message size exceeded, ResponseTooLargeError is sent
  58
  59
  60 ==Definitions==
  61   type Interface = {
  62          methodDefinitions : Map(MethodTypeDefinition, {})
  63        }
  64
  65   type InterfaceDefinition = {
  66          name : String,
  67          type : Interface
  68        }
  69
  70   type MethodType = {
  71          requestType : DataType,
  72          responseType : DataType,
  73          errorType : UnionType
  74        }
  75
  76   type MethodTypeDefinition = {
  77          name : String,
  78          type : MethodType
  79        }
  80
  81   type Handshake = | Version0
  82
  83   type Version0 = {
  84          recvMsgLimit : Integer,
  85          sendMsgLimit : Integer,
  86          methods : MethodTypeDefinition[]
  87        }
  88
  89   type Message = | RequestHeader RequestHeader
  90                  | ResponseHeader ResponseHeader
  91                  | ExecutionError_ ExecutionError_
  92                  | Exception_ Exception_
  93                  | InvalidMethodError InvalidMethodError
  94                  | ResponseTooLarge ResponseTooLarge
  95
  96   type RequestHeader = {
  97          requestId : Integer,
  98          methodId : Integer
  99        }
 100
 101   type ResponseHeader = {
 102          requestId : Integer
 103        }
 104
 105   type ExecutionError_ = {
 106          requestId : Integer
 107        }
 108
 109   type InvalidMethodError = {
 110          requestId : Integer
 111        }
 112
 113   type Exception_ = {
 114          requestId : Integer,
 115          message : String
 116        }
 117
 118   type ResponseTooLarge = {
 119          requestId : Integer
 120        }