ewe - v0.3.0

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.with_read_body
  • ewe.with_port
  • ewe.with_random_port
  • ewe.with_ipv6
  • ewe.with_tls
  • ewe.with_name
  • ewe.on_start
  • ewe.on_crash
pub opaque type Builder(body)

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

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)

ServerInfo

</>

Represents started server’s information. Can be retrieved using ewe.get_server_info.

pub type ServerInfo {
  ServerInfo(
    scheme: http.Scheme,
    ip_address: IpAddress,
    port: Int,
  )
}

Constructors

Values

bind

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

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

bind_all

</> 
pub fn bind_all(builder: Builder(body)) -> Builder(body)

Binds server to all interfaces.

bytes

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

Sets response body to a bytes, sets content-length header. Doesn’t set content-type header.

get_client_info

</> 
pub fn get_client_info(
  connection: @internal Connection,
) -> Result(#(IpAddress, Int), Nil)

Performs an attempt to get the client’s IP address and port.

get_server_info

</> 
pub fn get_server_info(
  name: process.Name(@internal Message(ServerInfo)),
) -> Result(ServerInfo, Nil)

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

ip_address_to_string

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

Converts an IpAddress to a string for later printing.

json

</> 
pub fn json(
  response: response.Response(a),
  json: string_tree.StringTree,
) -> response.Response(bytes_tree.BytesTree)

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

new

</> 
pub fn new(
  handler: fn(request.Request(body)) -> response.Response(
    bytes_tree.BytesTree,
  ),
) -> Builder(body)

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

on_crash

</> 
pub fn on_crash(
  builder: Builder(body),
  on_crash: response.Response(bytes_tree.BytesTree),
) -> Builder(body)

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

on_start

</> 
pub fn on_start(
  builder: Builder(body),
  on_start: fn(ServerInfo) -> Nil,
) -> Builder(body)

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

read_body

</> 
pub fn read_body(
  req: request.Request(@internal Connection),
  size_limit size_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.

start

</> 
pub fn start(
  builder: Builder(@internal Connection),
) -> Result(
  actor.Started(static_supervisor.Supervisor),
  actor.StartError,
)

Starts the server.

supervised

</> 
pub fn supervised(
  builder: Builder(@internal Connection),
) -> 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(bytes_tree.BytesTree)

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

with_ipv6

</> 
pub fn with_ipv6(builder: Builder(body)) -> Builder(body)

Enables IPv6 support.

with_name

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

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

with_port

</> 
pub fn with_port(
  builder: Builder(body),
  port: Int,
) -> Builder(body)

Sets listening port for server.

with_random_port

</> 
pub fn with_random_port(builder: Builder(body)) -> Builder(body)

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

with_read_body

</> 
pub fn with_read_body(
  builder: Builder(BitArray),
  size_limit: Int,
  on_failure: fn(BodyError) -> response.Response(
    bytes_tree.BytesTree,
  ),
) -> Builder(@internal Connection)

With this option, body is read before handler is called, making request body available in handler (Request(BitArray)). If body is invalid or too large, on_failure function is called.

with_tls

</> 
pub fn with_tls(
  builder: Builder(body),
  certificate: String,
  keyfile: String,
) -> Builder(body)

Enables TLS support, requires certificate and key file.

✨ Search Document