Example of a network handshake protocol

sample-comms-protocol.clj

(defn version-contract
  "Declaration of the handshake to allow client and server to agree on handling the next pieces"
  []
  [{::direction ::client->server
    ::initial-step true
    ::spec #(= % ::ohai)
    ::client-gen (fn [_] ::ohai)
    ::problem "Illegal greeting"}
   {::direction ::server->client
    ::spec (s/and keyword? #(= % ::orly?))
    ::server-gen (fn [_] ::orly?)
    ::problem "Broken handshake"}
   {::direction ::client->server
    ::spec ::icanhaz
    ::client-gen (fn [_] (list ::icanhaz {:frereth [[0 0 1]]}))}
   {::direction ::server->client
    ;; This spec is too loose.
    ;; It shall pick one of the versions suggested
    ;; by the client in the previous step.
    ;; Q: How can I document that formally?
    ::spec (s/or :match (s/and ::protocol-versions
                               #(= 1 (count %)))
                 :fail #(= % ::lolz))
    ::server-gen (fn [versions]
                   (if (contains? versions :frereth)
                     {:frereth (-> versions :frereth last)}
                     ::lolz))}])

The basic idea is:
client -> server: ::ohai
server -> client ::orly?
... auth needs to happen here...
client -> server (::icanhaz {$protocol-name [[v1 v1 v1] [v2 v2 v2]]})
server -> client #(if-let [proto (acceptable-protocol %)]
::lolz)