Listener Reference

Listener address and protocol configuration for ServerBlock.listen.

A Listen value binds the server to a local address (TCP or Unix socket) and controls which HTTP protocol versions are negotiated on that socket. In most cases, the string shorthand (e.g., ":8080") is sufficient; use the full object form when you need to customize protocol selection.

> This page is auto-generated from the PKL schema. See the guide for usage examples.

Types

`Protocol`

HTTP protocol version identifier for listener protocol negotiation.

"h1" — HTTP/1.1 over TCP (always available; widest client support)
"h2" — HTTP/2 over TLS via ALPN negotiation (multiplexed streams)
"h2c" — HTTP/2 over cleartext TCP (prior-knowledge mode; use only

on trusted internal networks where TLS is unnecessary)

"h3" — HTTP/3 over QUIC/UDP (requires TLS; a companion UDP

listener is opened automatically on the same port)

"webrtc" — WebRTC data channels over UDP (STUN/DTLS/SCTP). See

WebRtcListener for handler configuration.

pkl

typealias Protocol = "h1" | "h2" | "h2c" | "h3" | "webrtc"

---

`Listen`

Describes a single listener socket bound by the server.

In most configurations, the string shorthand in ServerBlock.listen is sufficient. Use this class when you need to customize protocol selection per listener.

Examples:

pkl

new { address = ":8080" }                  — all interfaces, port 8080
new { address = "0.0.0.0:443" }            — explicit IPv4 wildcard
new { address = "[::]:443" }               — dual-stack IPv6 wildcard
new { address = "unix:///run/elide.sock" } — Unix domain socket

Field	Type	Default	Description
`address`	String(!isEmpty)	(required)	Socket address to bind. Accepts several forms:
`protocols`	Listing	`defaultProtocols`	HTTP protocol versions negotiated on this listener. Clients that do

`address`

Socket address to bind. Accepts several forms:

:PORT — all interfaces on the given port HOST:PORT — bind to a specific interface and port [IPv6]:PORT — IPv6 address and port unix:///path/to/sock — Unix domain socket (absolute path) unix://./relative.sock — Unix domain socket (relative path)

For TCP listeners, the port must not conflict with other listeners in the same server block unless they differ by protocol (e.g., TCP vs. UDP for h3).

`protocols`

HTTP protocol versions negotiated on this listener. Clients that do not support any listed protocol fall back to the highest mutually supported version.

Defaults to ["h1", "h2"]. Add "h3" to enable QUIC — this requires TLS and opens a companion UDP listener on the same port. Use allProtocols as a shorthand for { "h1"; "h2"; "h3" }.

---