Snodo.OTP.Contract behaviour (snodo_otp v0.4.3)

Copy Markdown View Source

One module describes a GenServer's remote-callable operations for both sides. The server side (Snodo.OTP.Server.expose/2) turns it into Snodo.Tool.GenServer declarations: JSON in, Elixir message, reply term, JSON out. The client side (Snodo.OTP.Proxy) uses the inverse pair: Elixir message in, JSON out over the wire, JSON reply back to a term.

Nothing is inferred. An operation exists because the contract names it, with its schema, which keeps the boundary the GenServer tool experiment settled on: a client never chooses a process, atom or term.

Summary

Types

op()

Callbacks

build_message(name, args)

Server side: validated JSON arguments to the GenServer message.

decode_reply(name, json)

Client side: the JSON reply object back to the term the caller expects.

encode_call(message)

Client side: a GenServer.call message to an operation and JSON arguments, or :nomatch.

encode_cast(message)

Client side: a GenServer.cast message to an operation and JSON arguments, or :nomatch.

encode_reply(name, reply)

Server side: the GenServer reply to a JSON object.

ops()

The operations, in catalog order.

Types

op()

@type op() :: %{
  :name => String.t(),
  :kind => :call | :cast,
  :input_schema => map(),
  optional(:output_schema) => map(),
  optional(:description) => String.t(),
  optional(:timeout) => pos_integer()
}

Callbacks

build_message(name, args)

@callback build_message(name :: String.t(), args :: map()) :: term()

Server side: validated JSON arguments to the GenServer message.

decode_reply(name, json)

@callback decode_reply(name :: String.t(), json :: map()) :: term()

Client side: the JSON reply object back to the term the caller expects.

encode_call(message)

@callback encode_call(message :: term()) :: {String.t(), map()} | :nomatch

Client side: a GenServer.call message to an operation and JSON arguments, or :nomatch.

encode_cast(message)

@callback encode_cast(message :: term()) :: {String.t(), map()} | :nomatch

Client side: a GenServer.cast message to an operation and JSON arguments, or :nomatch.

encode_reply(name, reply)

@callback encode_reply(name :: String.t(), reply :: term()) :: map()

Server side: the GenServer reply to a JSON object.

ops()

@callback ops() :: [op()]

The operations, in catalog order.