Protocol specifications

[stevana]

Joe Armstrong makes the point that an API specification is not enough in many cases, for example consider the POSIX filesystem API:

• open: takes a filepath and returns a file descriptor;
• write: takes a file descriptor and string and returns how many bytes it
  successfully wrote;
• close: takes a file descriptor and closes it, thus freeing up resources.

Nothing in the API says, for example, that we can't continue writing to a file descriptor that has been closed! This is where protocols come in, saying for which sequences of API calls are valid. Here's the protocol for the POSIX filesystem API, taken from one of Joe's talks:

    start & open(File, Modes) ->
      {ok, Handle} & ready |
      {error, Reason} & closed.

    ready & close(Handle) ->
      ok & closed | 
      {error, Reason} & closed.

    ready & read(Handle, int) ->
      {ok, Bin} & ready |
      {error, E} & closed.

So a protcol is a 4-tuple: before-state, input, output and after-state.

Joe further suggests that these protocols can be enforced at run-time by so called "contract checkers", essentially man-in-the-middle proxies between two nodes that enforce that the nodes follow the protocol. Essentially run-time session-type checkers. If a node breaks the contract, the contract checker will return an error with the violation (rather than passing the message on to the node downstream).

Protocols seem useful form a testing/fuzzing point of view also, in that they let us avoid calling operations of an API from an invalid state, or conversely let's us ensure that we get errors when we call operations from an invalid state.

It would be nice if we could generate the contract checkers from the protocol specification and furthermore use them during testing to get nice error messages.

See also:

• Connecting Things Together is Really Difficult but it Could and Should be Rather Easy (CodeMesh 2014);
• Getting Erlang to talk to the outside world (2002).