glisten

Types

Connection

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

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

Constructors

Connection(
  socket: Socket,
  transport: Transport,
  subject: Subject(handler.Message(user_message)),
)

Arguments

transport

This provides a uniform interface for both TCP and SSL methods.

ConnectionInfo

</>

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

Constructors

ConnectionInfo(port: Int, ip_address: IpAddress)

Handler

opaque </>

pub opaque type Handler(user_message, data)

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 serve(_ssl).

pub type Loop(user_message, data) =
  fn(Message(user_message), data, Connection(user_message)) ->
    actor.Next(Message(user_message), data)

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

This holds information about the server. Returned by the start_server / start_ssl_server methods, it will allow you to get access to an OS-assigned port. Eventually, it will be used for graceful shutdown, and potentially other information.

pub opaque type Server

Socket

</>

pub type Socket =
  InternalSocket

SocketReason

</>

pub type SocketReason =
  InternalSocketReason

StartError

</>

Reasons that serve might fail

pub type StartError {
  ListenerClosed
  ListenerTimeout
  AcceptorTimeout
  AcceptorFailed(process.ExitReason)
  AcceptorCrashed(Dynamic)
  SystemError(SocketReason)
}

Constructors

```
ListenerClosed
```
```
ListenerTimeout
```
```
AcceptorTimeout
```
```
AcceptorFailed(process.ExitReason)
```
```
AcceptorCrashed(Dynamic)
```
```
SystemError(SocketReason)
```

Functions

bind

</>

pub fn bind(
  handler: Handler(a, b),
  interface: String,
) -> Handler(a, b)

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.

get_client_info

</>

pub fn get_client_info(
  conn: Connection(a),
) -> 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(
  server: Server,
  timeout: Int,
) -> Result(ConnectionInfo, CallError(State))

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

get_supervisor

</>

pub fn get_supervisor(server: Server) -> Subject(Message)

Gets the underlying supervisor Subject from the Server.

handler

</>

pub fn handler(
  on_init: fn(Connection(a)) -> #(b, Option(Selector(a))),
  loop: fn(Message(a), b, Connection(a)) -> Next(Message(a), b),
) -> Handler(a, b)

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.

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).

send

</>

pub fn send(
  conn: Connection(a),
  msg: BytesTree,
) -> Result(Nil, SocketReason)

Sends a BytesTree message over the socket using the active transport

serve

</>

pub fn serve(
  handler: Handler(a, b),
  port: Int,
) -> Result(Subject(Message), StartError)

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

serve_ssl

</>

pub fn serve_ssl(
  handler: Handler(a, b),
  port port: Int,
  certfile certfile: String,
  keyfile keyfile: String,
) -> Result(Subject(Message), StartError)

Start the SSL server with the given handler on the provided port. The key and cert files must be provided, valid, and readable by the current user.

start_server

</>

pub fn start_server(
  handler: Handler(a, b),
  port: Int,
) -> Result(Server, StartError)

Starts a TCP server and returns the Server construct. This is useful if you need access to the port. In the future, it will also allow graceful shutdown. There may also be other metadata attached to this return value.

start_ssl_server

</>

pub fn start_ssl_server(
  handler: Handler(a, b),
  port port: Int,
  certfile certfile: String,
  keyfile keyfile: String,
) -> Result(Server, StartError)

Starts an SSL server and returns the Server construct. This is useful if you need access to the port. In the future, it will also allow graceful shutdown. There may also be other metadata attached to this return value.

with_close

</>

pub fn with_close(
  handler: Handler(a, b),
  on_close: fn(b) -> Nil,
) -> Handler(a, b)

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

with_http2

</>

pub fn with_http2(handler: Handler(a, b)) -> Handler(a, b)

Sets the ALPN supported protocols to include HTTP/2. It’s currently being exposed only for mist to provide this support. For a TCP library, you definitely do not need it.

with_ipv6

</>

pub fn with_ipv6(handler: Handler(a, b)) -> Handler(a, b)

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(
  handler: Handler(a, b),
  size: Int,
) -> Handler(a, b)

Modify the size of the acceptor pool