ewe

Types

BodyError

</>

Possible errors that can occur when reading a body.

pub type BodyError {
  BodyTooLarge
  InvalidBody
}

Constructors

```
BodyTooLarge
```
```
InvalidBody
```

Builder

opaque </>

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

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

pub opaque type Builder

Connection

</>

Represents a connection between a client and a server, stored inside a Request. Can be converted to a BitArray using ewe.read_body.

pub type Connection =
  @internal Connection

Consumer

</>

Alias for consumer type for reading 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 file.

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

Constructors

```
NoEntry
```
```
NoAccess
```
```
IsDirectory
```
```
UnknownFileError(dynamic.Dynamic)
```

IpAddress

</>

Represents an IP address. Appears when accessing client’s information (ewe.client_stats) or on_start handler (ewe.on_start).

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)

opaque </>

Represents 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 Next(user_state, user_message)

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

opaque </>

Represents a response body. To set the response body, use the following functions:

ewe.text
ewe.bytes
ewe.bits
ewe.string_tree
ewe.empty
ewe.json
ewe.file
ewe.chunked

pub opaque type ResponseBody

SocketAddress

</>

Represents client or server information. Can be retrieved using ewe.get_server_info or ewe.get_client_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),
)

```
Done
```

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)
```
```
Binary(BitArray)
```
```
User(user_message)
```

Values

bind

</>

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

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

bind_all

</>

pub fn bind_all(builder: Builder) -> Builder

Binds server to all interfaces.

bits

</>

pub fn bits(
  response: response.Response(a),
  bits: BitArray,
) -> response.Response(ResponseBody)

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

bytes

</>

pub fn bytes(
  response: response.Response(a),
  bytes: bytes_tree.BytesTree,
) -> response.Response(ResponseBody)

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

chunked

</>

pub fn chunked(
  response: response.Response(a),
  yielder: yielder.Yielder(BitArray),
) -> response.Response(ResponseBody)

Sets response body from yielder, sets transfer-encoding header to chunked.

continue

</>

pub fn continue(
  user_state: user_state,
) -> Next(user_state, user_message)

Instructs WebSocket connection to continue processing.

continue_with_selector

</>

pub fn continue_with_selector(
  user_state: user_state,
  selector: process.Selector(user_message),
) -> Next(user_state, user_message)

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

empty

</>

pub fn empty(
  response: response.Response(a),
) -> response.Response(ResponseBody)

Sets response body to empty, sets content-length header to 0.

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.

file

</>

pub fn file(
  response: response.Response(a),
  path: String,
) -> Result(response.Response(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)

Performs an attempt to get the client’s socket address.

get_server_info

</>

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

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

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 for later printing.

json

</>

pub fn json(
  response: response.Response(a),
  json json: string_tree.StringTree,
) -> response.Response(ResponseBody)

Sets response body from string tree (use gleam_json package and encode using json.to_string_tree), sets content-type to application/json; charset=utf-8 and content-length headers.

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 process 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 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 a 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_text_frame

</>

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

Sends a text frame to the websocket client.

set_information_name

</>

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

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

start

</>

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

Starts the server.

stop

</>

pub fn stop() -> Next(user_state, user_message)

Instructs WebSocket connection to stop.

stop_abnormal

</>

pub fn stop_abnormal(
  reason: String,
) -> Next(user_state, user_message)

Instructs WebSocket connection to stop with abnormal reason.

stream_body

</>

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

Streams the request body.

string_tree

</>

pub fn string_tree(
  response: response.Response(a),
  string_tree: string_tree.StringTree,
) -> response.Response(ResponseBody)

Sets response body from string tree, sets content-length header.

supervised

</>

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

Creates a supervisor that can be appended to a supervision tree.

text

</>

pub fn text(
  response: response.Response(a),
  text: String,
) -> response.Response(ResponseBody)

Sets response body from string, sets content-type to text/plain; charset=utf-8 and content-length headers.

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),
  ) -> Next(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. Handler must return instruction on how WebSocket connection should proceed.

use_expression

</>

pub fn use_expression(
  handler: fn() -> Result(
    response.Response(ResponseBody),
    response.Response(ResponseBody),
  ),
) -> response.Response(ResponseBody)

Experimental function that simplifies error handling in handlers when working with Result type.

Example

pub fn handle_echo(
  req: Request,
) -> Response {
  let content_type =
    request.get_header(req, "content-type")
    |> result.unwrap("text/plain")

   // Start the use_expression block
   use <- ewe.use_expression()

   // Now you can use result.try with use expressions
   // If any step fails, the error response is automatically returned
   use req <- result.try(
     ewe.read_body(req, 1024)
     |> result.replace_error(
       response.new(400)
       |> ewe.json(error_json("Invalid request body")),
     ),
   )

   response.new(200)
   |> ewe.bits(req.body)
   |> response.set_header("content-type", content_type)
   |> Ok 
}

IP Address

Information

Builder

Server

Request

Response

Websocket

Experimental

Constructors

Constructors

Constructors

Constructors

Constructors

Constructors

Example