mist

Types

Builder

pub opaque type Builder(request_body, response_body)

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
```

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(BitBuilder)
  Chunked(Iterator(BitBuilder))
  File(descriptor: file.FileDescriptor, offset: Int, length: Int)
}

Constructors

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

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

See mist.send_file to use this response type.

WebsocketBuilder

</>

pub opaque type WebsocketBuilder(state, message)

WebsocketMessage

</>

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

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

Constructors

```
Text(BitString)
```
```
Binary(BitString)
```
```
Closed
```
```
Shutdown
```
```
Custom(custom)
```

Functions

after_start

</>

pub fn after_start(builder: Builder(a, b), after_start: fn(Int) ->
    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.

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.

on_message

</>

pub fn on_message(builder: WebsocketBuilder(a, b), handler: fn(
    a,
    WebsocketConnection,
    WebsocketMessage(b),
  ) -> Next(a)) -> WebsocketBuilder(a, b)

Provides a function to call for each WebsocketMessage received by the process.

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(BitString),
  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(BitString, 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.

selecting

</>

pub fn selecting(builder: WebsocketBuilder(a, b), selector: Selector(
    b,
  )) -> WebsocketBuilder(a, b)

Provide an external selector for user-specified messages that the websocket process may receive. These will be provided in the Custom type.

send_binary_frame

</>

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

Sends a binary frame across the websocket.

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: BitString) -> Result(
  Nil,
  SocketReason,
)

Sends a text frame across the websocket.

start_http

</>

pub fn start_http(builder: Builder(Connection, ResponseData)) -> Result(
  Nil,
  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(
  Nil,
  StartError,
)

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.

upgrade

</>

pub fn upgrade(builder: WebsocketBuilder(a, b)) -> 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.

websocket

</>

pub fn websocket(request: Request(Connection)) -> WebsocketBuilder(
  Nil,
  a,
)

Initializes a builder for upgrading a connection to Websockets. The default handler will shut down the process on receipt of a message. The default state is empty, and no external messages can be received.

with_state

</>

pub fn with_state(builder: WebsocketBuilder(a, b), state: a) -> WebsocketBuilder(
  a,
  b,
)

Adds some initial state to the websocket handler.