mist

Types

Builder

pub opaque type Builder(request_body, response_body)

CertificateError

</>

These are the types of errors raised by trying to read the certificate and key files.

pub type CertificateError {
  NoCertificate
  NoKey
  NoKeyOrCertificate
}

Constructors

```
NoCertificate
```
```
NoKey
```
```
NoKeyOrCertificate
```

Re-exported type that represents the default Request body type. See mist.read_body to convert this type into a BitString. The Connection also holds some additional information about the request. Currently, the only useful field is client_ip which is a Result with a tuple of integers representing the IPv4 address.

pub type Connection =
  InternalConnection

FileError

</>

Potential errors when opening a file to send. This list is currently not exhaustive with POSIX errors.

pub type FileError {
  IsDir
  NoAccess
  NoEntry
  UnknownFileError
}

Constructors

```
IsDir
```
```
NoAccess
```
```
NoEntry
```
```
UnknownFileError
```

HttpsError

</>

These are the possible errors raised when trying to start an Https server. If there are issues reading the certificate or key files, those will be returned.

pub type HttpsError {
  GlistenError(glisten.StartError)
  CertificateError(CertificateError)
}

Constructors

```
GlistenError(glisten.StartError)
```
```
CertificateError(CertificateError)
```

ReadError

</>

The possible errors from reading the request body. If the size is larger than the provided value, ExcessBody is returned. If there is an error reading the body from the socket or the body is malformed (i.e a chunked request with invalid sizes), MalformedBody is returned.

pub type ReadError {
  ExcessBody
  MalformedBody
}

Constructors

```
ExcessBody
```
```
MalformedBody
```

ResponseData

</>

The response body type. This allows mist to handle these different cases for you. Bytes is the regular data return. Websocket will upgrade the socket to websockets, but should not be used directly. See the mist.upgrade function for usage. Chunked will use Transfer-Encoding: chunked to send an iterator in chunks. File will use Erlang’s sendfile to more efficiently return a file to the client.

pub type ResponseData {
  Websocket(Selector(ProcessDown))
  Bytes(BytesBuilder)
  Chunked(Iterator(BytesBuilder))
  File(descriptor: file.FileDescriptor, offset: Int, length: Int)
  ServerSentEvents(Selector(ProcessDown))
}

Constructors

```
Websocket(Selector(ProcessDown))
```
```
Bytes(BytesBuilder)
```
```
Chunked(Iterator(BytesBuilder))
```

File(descriptor: file.FileDescriptor, offset: Int, length: Int)

See mist.send_file to use this response type.

```
ServerSentEvents(Selector(ProcessDown))
```

SSEConnection

</>

pub opaque type SSEConnection

SSEEvent

</>

pub opaque type SSEEvent

WebsocketConnection

</>

pub type WebsocketConnection =
  InternalWebsocketConnection

WebsocketMessage

</>

These are the types of messages that a websocket handler may receive.

pub type WebsocketMessage(custom) {
  Text(String)
  Binary(BitArray)
  Closed
  Shutdown
  Custom(custom)
}

Constructors

```
Text(String)
```
```
Binary(BitArray)
```
```
Closed
```
```
Shutdown
```
```
Custom(custom)
```

Functions

after_start

</>

pub fn after_start(
  builder: Builder(a, b),
  after_start: fn(Int, Scheme) -> Nil,
) -> Builder(a, b)

Override the default function to be called after the service starts. The default is to log a message with the listening port.

event

</>

pub fn event(data: StringBuilder) -> SSEEvent

event_id

</>

pub fn event_id(event: SSEEvent, id: String) -> SSEEvent

event_name

</>

pub fn event_name(event: SSEEvent, name: String) -> SSEEvent

new

</>

pub fn new(
  handler: fn(Request(a)) -> Response(b),
) -> Builder(a, b)

Create a new mist handler with a given function. The default port is 4000.

port

</>

pub fn port(builder: Builder(a, b), port: Int) -> Builder(a, b)

Assign a different listening port to the service.

read_body

</>

pub fn read_body(
  req: Request(Connection),
  max_body_limit max_body_limit: Int,
) -> Result(Request(BitArray), ReadError)

The request body is not pulled from the socket until requested. The content-length header is used to determine whether the socket is read from or not. The read may also fail, and a ReadError is raised.

read_request_body

</>

pub fn read_request_body(
  builder: Builder(BitArray, a),
  bytes_limit bytes_limit: Int,
  failure_response failure_response: Response(a),
) -> Builder(Connection, a)

This function allows for implicitly reading the body of requests up to a given size. If the size is too large, or the read fails, the provided failure_response will be sent back as the response.

send_binary_frame

</>

pub fn send_binary_frame(
  connection: WebsocketConnection,
  frame: BitArray,
) -> Result(Nil, SocketReason)

Sends a binary frame across the websocket.

send_event

</>

pub fn send_event(
  conn: SSEConnection,
  event: SSEEvent,
) -> Result(Nil, Nil)

send_file

</>

pub fn send_file(
  path: String,
  offset offset: Int,
  limit limit: Option(Int),
) -> Result(ResponseData, FileError)

To respond with a file using Erlang’s sendfile, use this function with the specified offset and limit (optional). It will attempt to open the file for reading, get its file size, and then send the file. If the read errors, this will return the relevant FileError. Generally, this will be more memory efficient than manually doing this process with mist.Bytes.

send_text_frame

</>

pub fn send_text_frame(
  connection: WebsocketConnection,
  frame: String,
) -> Result(Nil, SocketReason)

Sends a text frame across the websocket.

server_sent_events

</>

pub fn server_sent_events(
  request req: Request(Connection),
  initial_response resp: Response(a),
  init init: fn() -> InitResult(b, c),
  loop loop: fn(c, SSEConnection, b) -> Next(c, b),
) -> Response(ResponseData)

Sets up the connection for server-sent events. The initial response provided here will have its headers included in the SSE setup. The body is discarded. The init and loop parameters follow the same shape as the gleam/otp/actor module.

NOTE: There is no proper way within the spec for the server to “close” the SSE connection. There are ways around it.

See: examples/eventz for a sample usage.

start_http

</>

pub fn start_http(
  builder: Builder(Connection, ResponseData),
) -> Result(Subject(Message), StartError)

Start a mist service over HTTP with the provided builder.

start_https

</>

pub fn start_https(
  builder: Builder(Connection, ResponseData),
  certfile certfile: String,
  keyfile keyfile: String,
) -> Result(Subject(Message), HttpsError)

Start a mist service over HTTPS with the provided builder. This method requires both a certificate file and a key file. The library will attempt to read these files off of the disk.

stream

</>

pub fn stream(
  req: Request(Connection),
) -> Result(fn(Int) -> Result(Chunk, ReadError), ReadError)

Rather than explicitly reading either the whole body (optionally up to N bytes), this function allows you to consume a stream of the request body. Any errors reading the body will propagate out, or Chunks will be emitted. This provides a consume method to attempt to grab the next size chunk from the socket.

websocket

</>

pub fn websocket(
  request request: Request(Connection),
  handler handler: fn(a, WebsocketConnection, WebsocketMessage(b)) ->
    Next(b, a),
  on_init on_init: fn(WebsocketConnection) ->
    #(a, Option(Selector(b))),
  on_close on_close: fn(a) -> Nil,
) -> Response(ResponseData)

Upgrade a request to handle websockets. If the request is malformed, or the websocket process fails to initialize, an empty 400 response will be sent to the client.

The on_init method will be called when the actual WebSocket process is started, and the return value is the initial state and an optional selector for receiving user messages.

The on_close method is called when the WebSocket process shuts down for any reason, valid or otherwise.