ewe

Types

BodyError

</>

Possible errors that can occur when reading a body.

pub type BodyError {
  BodyTooLarge
  InvalidBody
}

Constructors

```
BodyTooLarge
```
Body is larger than the provided limit.
```
InvalidBody
```
Body is malformed.

Builder

opaque </>

Ewe’s server builder. Contains all server configurations. Can be adjusted with the following functions:

ewe.bind
ewe.bind_all
ewe.listening
ewe.listening_random
ewe.enable_ipv6
ewe.enable_tls
ewe.with_name
ewe.on_start
ewe.quiet
ewe.on_crash
ewe.idle_timeout

pub opaque type Builder

ChunkedBody

</>

Represents a chunked response body. This type is used to send a chunked response to the client.

pub type ChunkedBody =
  @internal ChunkedBody

ChunkedNext

opaque </>

Represents an instruction on how chunked response should be processed.

continue processing the chunked response.
stop the chunked response normally.
stop the chunked response with abnormal reason.

pub opaque type ChunkedNext(user_state)

Represents a default body stored inside a Request type. Contains important information for retrieving the original request body or client’s information. Can be converted to a BitArray using ewe.read_body.

pub type Connection =
  @internal Connection

Consumer

</>

A convenient alias for a consumer that reads N amount of bytes from the request body stream.

pub type Consumer =
  fn(Int) -> Result(Stream, BodyError)

FileError

</>

Possible errors that can occur when setting response body from a file.

pub type FileError {
  NoEntry
  NoAccess
  IsDirectory
  UnknownFileError(dynamic.Dynamic)
}

Constructors

```
NoEntry
```
File does not exist.
```
NoAccess
```
Missing permission for reading the file, or for searching one of the parents directories.
```
IsDirectory
```
The named file is a directory.
```
UnknownFileError(dynamic.Dynamic)
```
Untypical file error.

IpAddress

</>

Represents an IP address of a client/server.

pub type IpAddress {
  IpV4(Int, Int, Int, Int)
  IpV6(Int, Int, Int, Int, Int, Int, Int, Int)
}

Constructors

```
IpV4(Int, Int, Int, Int)
```

IpV6(Int, Int, Int, Int, Int, Int, Int, Int)

Request

</>

A convenient alias for a HTTP request with a Connection as the body.

pub type Request =
  request.Request(@internal Connection)

Response

</>

A convenient alias for a HTTP response with a ResponseBody as the body.

pub type Response =
  response.Response(ResponseBody)

ResponseBody

</>

Represents possible response body options.

Types for direct usage:

Regular data: TextData, BytesData, BitsData, StringTreeData, Empty
Chunked data: ChunkedData

Types that should not be used directly:

File: see ewe.file to construct it.
ChunkedData: indicates that response body is being sent in chunks with chunked transfer encoding.
Websocket: indicates that request is being upgraded to a WebSocket connection.
SSE: indicates that request is being upgraded to a Server-Sent Events connection.

pub type ResponseBody {
  TextData(String)
  BytesData(bytes_tree.BytesTree)
  BitsData(BitArray)
  StringTreeData(string_tree.StringTree)
  Empty
  File(descriptor: @internal IoDevice, offset: Int, size: Int)
  Chunked
  Websocket
  SSE
}

Constructors

```
TextData(String)
```
Allows to set response body from a string.
```
BytesData(bytes_tree.BytesTree)
```
Allows to set response body from bytes.
```
BitsData(BitArray)
```
Allows to set response body from bits.
```
StringTreeData(string_tree.StringTree)
```
Allows to set response body from a string tree.
```
Empty
```
Allows to set empty response body.
```
File(descriptor: @internal IoDevice, offset: Int, size: Int)
```
Allows to set response body from a file more efficiently rather than sending contents in regular data types.
```
Chunked
```
Indicates that response body is being sent in chunks with chunked transfer encoding.
```
Websocket
```
Indicates that request is being upgraded to a WebSocket connection.
```
SSE
```
Indicates that request is being upgraded to a Server-Sent Events connection.

SSEConnection

</>

Represents a Server-Sent Events connection between a client and a server.

pub type SSEConnection =
  @internal SSEConnection

SSEEvent

</>

Represents a Server-Sent Events event. The event fields are:

event: a string identifying the type of event described.
data: the data field for the message.
id: event ID.
retry: The reconnection time. If the connection to the server is lost, the browser will wait for the specified time before attempting to reconnect.

Can be created using ewe.event and modified with ewe.event_name, ewe.event_id, and ewe.event_retry.

pub type SSEEvent =
  @internal SSEEvent

SSENext

opaque </>

Represents an instruction on how Server-Sent Events connection should proceed.

continue processing the Server-Sent Events connection.
stop the Server-Sent Events connection.
stop the Server-Sent Events connection with abnormal reason.

pub opaque type SSENext(user_state)

SocketAddress

</>

Represents client/server information. Can be retrieved using ewe.get_client_info/ewe.get_server_info.

pub type SocketAddress {
  SocketAddress(ip: IpAddress, port: Int)
}

Constructors

```
SocketAddress(ip: IpAddress, port: Int)
```

Stream

</>

Used to track the progress of reading the request body stream.

pub type Stream {
  Consumed(
    data: BitArray,
    next: fn(Int) -> Result(Stream, BodyError),
  )
  Done
}

Constructors

Consumed(
  data: BitArray,
  next: fn(Int) -> Result(Stream, BodyError),
)

Chunk of data has been consumed.

```
Done
```
Signifies that the request body stream has been fully consumed.

WebsocketConnection

</>

Represents a WebSocket connection between a client and a server.

pub type WebsocketConnection =
  @internal WebsocketConnection

WebsocketMessage

</>

Represents a WebSocket message received from the client.

pub type WebsocketMessage(user_message) {
  Text(String)
  Binary(BitArray)
  User(user_message)
}

Constructors

```
Text(String)
```
Indicate that text frame has been received.
```
Binary(BitArray)
```
Indicate that binary frame has been received.
```
User(user_message)
```
Indicate that user message has been received from WebSocket selector.

WebsocketNext

opaque </>

Represents an instruction on how WebSocket connection should proceed.

continue processing the WebSocket connection.
continue processing the WebSocket connection with selector for custom messages.
stop the WebSocket connection.
stop the WebSocket connection with abnormal reason.

pub opaque type WebsocketNext(user_state, user_message)

Values

bind

</>

pub fn bind(
  builder: Builder,
  interface interface: String,
) -> Builder

Binds server to a specific interface. Crashes program if the interface is invalid.

bind_all

</>

pub fn bind_all(builder: Builder) -> Builder

Binds server to all interfaces.

chunked_body

</>

pub fn chunked_body(
  req: request.Request(@internal Connection),
  resp: response.Response(a),
  on_init on_init: fn(process.Subject(user_message)) -> user_state,
  handler handler: fn(
    @internal ChunkedBody,
    user_state,
    user_message,
  ) -> ChunkedNext(user_state),
  on_close on_close: fn(@internal ChunkedBody, user_state) -> Nil,
) -> response.Response(ResponseBody)

Sets up the connection for chunked response.

on_init function is called once the chunked response process is initialized. The argument is subject that can be used to send chunks to the client. It must return initial state.

handler function is called for every message received. It must return instruction on how chunked response should proceed.

on_close function is called when the chunked response process is going to be stopped.

chunked_continue

</>

pub fn chunked_continue(
  user_state: user_state,
) -> ChunkedNext(user_state)

Instructs chunked response to continue processing.

chunked_stop

</>

pub fn chunked_stop() -> ChunkedNext(user_state)

Instructs chunked response to stop normally.

chunked_stop_abnormal

</>

pub fn chunked_stop_abnormal(
  reason: String,
) -> ChunkedNext(user_state)

Instructs chunked response to stop with abnormal reason.

enable_ipv6

</>

pub fn enable_ipv6(builder: Builder) -> Builder

Enables IPv6 support.

enable_tls

</>

pub fn enable_tls(
  builder: Builder,
  certificate_file certificate_file: String,
  key_file key_file: String,
) -> Builder

Enables TLS support, requires certificate and key file.

event

</>

pub fn event(data: String) -> @internal SSEEvent

Creates a new SSE event with the given data. Use ewe.event_name, ewe.event_id, and ewe.event_retry to modify other fields of the event.

event_id

</>

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

Sets the ID of the event.

event_name

</>

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

Sets the name of the event.

event_retry

</>

pub fn event_retry(
  event: @internal SSEEvent,
  retry: Int,
) -> @internal SSEEvent

Sets the retry time of the event.

file

</>

pub fn file(
  path: String,
  offset offset: option.Option(Int),
  limit limit: option.Option(Int),
) -> Result(ResponseBody, FileError)

Sets response body from file, sets content-length header.

get_client_info

</>

pub fn get_client_info(
  connection connection: @internal Connection,
) -> Result(SocketAddress, Nil)

Attempts to get the client’s socket address using request’s connection.

get_server_info

</>

pub fn get_server_info(
  listener_name name: process.Name(@internal Message),
) -> SocketAddress

Retrieves server’s socket address. Requires the same name as the one used in ewe.with_name and server to be started.

idle_timeout

</>

pub fn idle_timeout(
  builder: Builder,
  idle_timeout: Int,
) -> Builder

Sets a custom idle timeout in milliseconds for connections. If provided timeout is less than 0, 10_000ms will be used instead.

ip_address_to_string

</>

pub fn ip_address_to_string(address address: IpAddress) -> String

Converts an IpAddress to a String.

listening

</>

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

Sets listening port for server.

listening_random

</>

pub fn listening_random(builder: Builder) -> Builder

Sets listening port for server to a random port. Useful for testing.

new

</>

pub fn new(
  handler: fn(request.Request(@internal Connection)) -> response.Response(
    ResponseBody,
  ),
) -> Builder

Creates new server builder with handler provided.

Default configuration:

port: 8080
interface: 127.0.0.1
No ipv6 support
No TLS support
Default listener name for server information retrieval
on_start: prints Listening on <scheme>://<ip_address>:<port>
on_crash: empty 500 response
idle_timeout: connection is closed after 10_000ms of inactivity

on_crash

</>

pub fn on_crash(
  builder: Builder,
  on_crash: response.Response(ResponseBody),
) -> Builder

Sets a custom response that will be sent when server crashes.

on_start

</>

pub fn on_start(
  builder: Builder,
  on_start: fn(http.Scheme, SocketAddress) -> Nil,
) -> Builder

Sets a custom handler that will be called after server starts.

quiet

</>

pub fn quiet(builder: Builder) -> Builder

Sets an empty on_start function.

read_body

</>

pub fn read_body(
  req: request.Request(@internal Connection),
  bytes_limit bytes_limit: Int,
) -> Result(request.Request(BitArray), BodyError)

Reads body from the request. If request body is malformed, InvalidBody error is returned. On success, returns a request with body converted to BitArray.

When transfer-encoding header set as chunked, BodyTooLarge error is returned if accumulated body is larger than size_limit.
Ensures that content-length is in size_limit scope.

send_binary_frame

</>

pub fn send_binary_frame(
  conn: @internal WebsocketConnection,
  bits: BitArray,
) -> Result(Nil, socket.SocketReason)

Sends a binary frame to the websocket client.

send_chunk

</>

pub fn send_chunk(
  body: @internal ChunkedBody,
  chunk: BitArray,
) -> Result(Nil, socket.SocketReason)

Sends a chunk to the client.

send_event

</>

pub fn send_event(
  conn: @internal SSEConnection,
  event: @internal SSEEvent,
) -> Result(Nil, socket.SocketReason)

Sends a Server-Sent Events event to the client.

send_text_frame

</>

pub fn send_text_frame(
  conn: @internal WebsocketConnection,
  text: String,
) -> Result(Nil, socket.SocketReason)

Sends a text frame to the websocket client.

sse

</>

pub fn sse(
  req: request.Request(@internal Connection),
  on_init on_init: fn(process.Subject(user_message)) -> user_state,
  handler handler: fn(
    @internal SSEConnection,
    user_state,
    user_message,
  ) -> SSENext(user_state),
  on_close on_close: fn(@internal SSEConnection, user_state) -> Nil,
) -> response.Response(ResponseBody)

Sets up the connection for Server-Sent Events.

on_init function is called once process that handles SSE connection is initialized. The argument is subject that can be used to send messages to the client. It must return initial state.

handler function is called for every subject’s message received. It must return instruction on how SSE connection should proceed.

on_close function is called when SSE process is going to be stopped.

sse_continue

</>

pub fn sse_continue(
  user_state: user_state,
) -> SSENext(user_state)

Instructs Server-Sent Events connection to continue processing.

sse_stop

</>

pub fn sse_stop() -> SSENext(user_state)

Instructs Server-Sent Events connection to stop.

sse_stop_abnormal

</>

pub fn sse_stop_abnormal(reason: String) -> SSENext(user_state)

Instructs Server-Sent Events connection to stop with abnormal reason.

start

</>

pub fn start(
  builder: Builder,
) -> Result(
  actor.Started(static_supervisor.Supervisor),
  actor.StartError,
)

Starts the server with the provided configuration.

stream_body

</>

pub fn stream_body(
  req: request.Request(@internal Connection),
) -> Result(fn(Int) -> Result(Stream, BodyError), BodyError)

Returns the consumer function that reads N amount of bytes from the request body stream.

supervised

</>

pub fn supervised(
  builder: Builder,
) -> supervision.ChildSpecification(static_supervisor.Supervisor)

Creates a supervisor with the provided configuration that is a child of a supervision tree.

upgrade_websocket

</>

pub fn upgrade_websocket(
  req: request.Request(@internal Connection),
  on_init on_init: fn(
    @internal WebsocketConnection,
    process.Selector(user_message),
  ) -> #(user_state, process.Selector(user_message)),
  handler handler: fn(
    @internal WebsocketConnection,
    user_state,
    WebsocketMessage(user_message),
  ) -> WebsocketNext(user_state, user_message),
  on_close on_close: fn(@internal WebsocketConnection, user_state) -> Nil,
) -> response.Response(ResponseBody)

Upgrade request to a WebSocket connection. If the initial request is not valid for WebSocket upgrade, 400 response is sent.

on_init function is called once process that handles WebSocket connection is initialized. It must return a tuple with initial state and selector for custom messages. If there is no custom messages, user can pass the same selector from the argument

handler function is called for every WebSocket message received. It must return instruction on how WebSocket connection should proceed.

on_close function is called when WebSocket process is going to be stopped.

websocket_continue

</>

pub fn websocket_continue(
  user_state: user_state,
) -> WebsocketNext(user_state, user_message)

Instructs WebSocket connection to continue processing.

websocket_continue_with_selector

</>

pub fn websocket_continue_with_selector(
  user_state: user_state,
  selector: process.Selector(user_message),
) -> WebsocketNext(user_state, user_message)

Instructs WebSocket connection to continue processing, including selector for custom messages.

websocket_stop

</>

pub fn websocket_stop() -> WebsocketNext(user_state, user_message)

Instructs WebSocket connection to stop.

websocket_stop_abnormal

</>

pub fn websocket_stop_abnormal(
  reason: String,
) -> WebsocketNext(user_state, user_message)

Instructs WebSocket connection to stop with abnormal reason.

with_name

</>

pub fn with_name(
  builder: Builder,
  name: process.Name(@internal Message),
) -> Builder

Sets a custom process name for server information retrieval, allowing to use ewe.get_server_info after the server starts.

IP Address

Information

Builder

Server

Request

Response

Chunked Response

Websocket

Server-Sent Events

Constructors

Constructors

Constructors

Constructors

Constructors

Constructors

Constructors