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.

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 with 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

get_client_info

</>

pub fn get_client_info(
  conn: Connection(a),
) -> Result(#(IpAddress, Int), 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_port

</>

pub fn get_port(server: Server) -> Result(Int, Nil)

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.

send

</>

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

Sends a BytesBuilder 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_pool_size

</>

pub fn with_pool_size(
  handler: Handler(a, b),
  size: Int,
) -> Handler(a, b)

Modify the size of the acceptor pool