glisten - v8.0.1

glisten

Types

Builder

opaque </> 
pub opaque type Builder(state, user_message)

Connection

</>

This type holds useful bits of data for the active connection.

pub type Connection(user_message) {
  Connection(
    socket: socket.Socket,
    transport: transport.Transport,
    subject: process.Subject(@internal Message(user_message)),
  )
}

Constructors

ConnectionInfo

</> 
pub type ConnectionInfo {
  ConnectionInfo(port: Int, ip_address: IpAddress)
}

Constructors 

  • ConnectionInfo(port: Int, ip_address: IpAddress)

IpAddress

</>

This is used to describe the connecting client’s IP address.

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)

Loop

</>

This is the shape of the function you need to provide for the handler argument to start.

pub type Loop(state, user_message) =
  fn(state, Message(user_message), Connection(user_message)) -> Next(
    state,
    Message(user_message),
  )

Message

</>

Your provided loop function will receive these message types as the first argument.

pub type Message(user_message) {
  Packet(BitArray)
  User(user_message)
}

Constructors 

  • Packet(BitArray)

    These are messages received from the socket

  • User(user_message)

    These are any messages received from the selector returned from on_init

Next

opaque </> 
pub opaque type Next(user_state, user_message)

Socket

</> 
pub type Socket =
  socket.Socket

SocketReason

</> 
pub type SocketReason =
  socket.SocketReason

Values

bind

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

This sets the interface for glisten to listen on. It accepts the following strings: “localhost”, valid IPv4 addresses (i.e. “127.0.0.1”), and valid IPv6 addresses (i.e. “::1”). If an invalid value is provided, this will panic.

continue

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

get_client_info

</> 
pub fn get_client_info(
  conn: Connection(user_message),
) -> Result(ConnectionInfo, Nil)

Tries to read the IP address and port of a connected client. It will return valid IPv4 or IPv6 addresses, attempting to return the most relevant one for the client.

get_server_info

</> 
pub fn get_server_info(
  listener: process.Name(@internal Message),
  timeout: Int,
) -> ConnectionInfo

Returns the user-provided port or the OS-assigned value if 0 was provided.

ip_address_to_string

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

Convenience function for convert an IpAddress type into a string. It will convert IPv6 addresses to the canonical short-hand (ie. loopback is ::1).

new

</> 
pub fn new(
  on_init: fn(Connection(user_message)) -> #(
    state,
    option.Option(process.Selector(user_message)),
  ),
  loop: fn(state, Message(user_message), Connection(user_message)) -> Next(
    state,
    Message(user_message),
  ),
) -> Builder(state, user_message)

Create a new handler for each connection. The required arguments mirror the actor.start API from gleam_otp. The default pool is 10 accceptor processes.

send

</> 
pub fn send(
  conn: Connection(user_message),
  msg: bytes_tree.BytesTree,
) -> Result(Nil, socket.SocketReason)

Sends a BytesTree message over the socket using the active transport

start

</> 
pub fn start(
  builder: Builder(state, user_message),
  port: Int,
) -> Result(
  actor.Started(static_supervisor.Supervisor),
  actor.StartError,
)

Start the TCP server with the given handler on the provided port

stop

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

stop_abnormal

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

supervised

</> 
pub fn supervised(
  handler: Builder(state, user_message),
  port: Int,
) -> supervision.ChildSpecification(static_supervisor.Supervisor)

Helper method for building a child specification for use in a supervision tree.

with_close

</> 
pub fn with_close(
  builder: Builder(state, user_message),
  on_close: fn(state) -> Nil,
) -> Builder(state, user_message)

Adds a function to the handler to be called when the connection is closed.

with_ipv6

</> 
pub fn with_ipv6(
  builder: Builder(state, user_message),
) -> Builder(state, user_message)

By default, glisten listens on localhost only over IPv4. With an IPv4 address, you can call this builder method to also serve over IPv6 on that interface. If it is not supported, your application will crash. If you call this with an IPv6 interface specified, it will have no effect.

with_pool_size

</> 
pub fn with_pool_size(
  builder: Builder(state, user_message),
  size: Int,
) -> Builder(state, user_message)

Modify the size of the acceptor pool

with_selector

</> 
pub fn with_selector(
  next: Next(user_state, user_message),
  selector: process.Selector(user_message),
) -> Next(user_state, user_message)

with_tls

</> 
pub fn with_tls(
  builder: Builder(state, user_message),
  certfile cert: String,
  keyfile key: String,
) -> Builder(state, user_message)

To use TLS, provide a path to a certficate and key file.

✨ Search Document