omnimessage/server

Types

App

opaque </>

pub opaque type App(
  start_args,
  model,
  msg,
  encoding,
  decode_error,
)

Holds decode and encode functions for omnimessage messages. Decode errors will be called back for you to handle, while Encode errors are interpreted as “skip this message” – no error will be raised for them and they won’t be sent over.

Since an EncoderDecoder is expected to receive the whole message type of an application, but usually will ignore messages that aren’t shared, it’s best to define it as a thin wrapper around shared encoders/decoders:

// Holds shared message types, encoders and decoders
import shared

let encoder_decoder =
  EncoderDecoder(
    fn(msg) {
      case msg {
        // Messages must be encodable
        ClientMessage(message) -> Ok(shared.encode_client_message(message))
        // Return Error(Nil) for messages you don't want to send out
        _ -> Error(Nil)
      }
    },
    fn(encoded_msg) {
      // Unsupported messages will cause TransportError(DecodeError(error))
      shared.decode_server_message(encoded_msg)
      |> result.map(ServerMessage)
    },
  )

pub type EncoderDecoder(msg, encoding, decode_error) {
  EncoderDecoder(
    encode: fn(msg) -> Result(encoding, Nil),
    decode: fn(encoding) -> Result(msg, decode_error),
  )
}

Constructors

EncoderDecoder(
  encode: fn(msg) -> Result(encoding, Nil),
  decode: fn(encoding) -> Result(msg, decode_error),
)

Values

application

</>

pub fn application(
  init init: fn(a) -> #(b, Effect(c)),
  update update: fn(b, c) -> #(b, Effect(c)),
  encoder_decoder encoder_decoder: EncoderDecoder(c, d, e),
) -> App(a, b, c, d, e)

This creates a version of a Lustre application that can be used in omnimessage/server.start_actor (see below). A view is not necessary, as this application will never render anything.

component

</>

pub fn component(
  init init: fn(a) -> #(b, Effect(c)),
  update update: fn(b, c) -> #(b, Effect(c)),
  options options: List(Option(c)),
  encoder_decoder encoder_decoder: EncoderDecoder(c, d, e),
) -> App(a, b, c, d, e)

mist_websocket_application

</>

pub fn mist_websocket_application(
  req: Request(Connection),
  app: App(a, b, c, String, d),
  flags: a,
  on_error: fn(d) -> Nil,
) -> Response(ResponseData)

A mist websocket handler to automatically respond to omnimessage messages via a Lustre server component. The server component can then be used similarly to one created by an omnimessage/lustre and handle the messages via update, dispatch, and effects.

Return this as a response to the websocket init request.

req The mist request
app An application created with omnimessage/server.application
flags Flags to hand to the application’s init
on_error For handling decode errors

See a full example using this in the Readme or in the examples folder.

mist_websocket_pipe

</>

pub fn mist_websocket_pipe(
  req: Request(Connection),
  encoder_decoder: EncoderDecoder(a, String, b),
  handler: fn(a) -> a,
  on_error: fn(b) -> Nil,
) -> Response(ResponseData)

A mist websocket handler to automatically respond to omnimessage messages.

Return this as a response to the websocket init request.

req The mist request
encoder_decoder For encoding and decoding messages
handler For handling the incoming messages
on_error For handling decode errors

See a full example using this in the Readme or in the examples folder.

pipe

</>

pub fn pipe(
  msg: a,
  encoder_decoder: EncoderDecoder(b, a, c),
  handler: fn(b) -> b,
) -> Result(Option(a), c)

A utility function for easily handling messages:

let out_msg = pipe(in_msg, encoder_decoder, handler)

start_server_component

</>

pub fn start_server_component(
  app: App(a, b, c, d, e),
  with_args start_args: a,
  with_listener listener: fn(c) -> Nil,
) -> Result(Runtime(c), Error)

This is a beefed up version of lustre.start_actor that allows subscribing to messages dispatched inside the runtime.

This is what enables using a Lustre server component for communication, powering mist_websocket_application() below.

wisp_http_middleware

</>

pub fn wisp_http_middleware(
  req: Request(Connection),
  path: String,
  encoder_decoder: EncoderDecoder(a, String, b),
  handler: fn(a) -> a,
  fun: fn() -> Response(Body),
) -> Response(Body)

A wisp middleware to automatically handle HTTP POST omnimessage messages.

req The wisp request
path The path to which messages are POSTed
encoder_decoder For encoding and decoding messages
handler For handling the incoming messages

See a full example using this in the Readme or in the examples folder.