Skip to main content
The Socket struct defines a network socket on which the server will listen and expose services.

​
Structure

​
name
Text
required
Unique socket name. Can be used on the command line to override the socket’s address:
  • --socket-addr <name>=<addr>
  • --socket-fd <name>=<fd>
​
address
Text
Address/port on which this socket will listen. If not specified, must be provided via command-line flag.Examples:
  • *:80: Listen on port 80 on all local IPv4 and IPv6 interfaces
  • 1.2.3.4: Listen on specific IPv4 address on default port
  • 1.2.3.4:80: Listen on specific IPv4 address and port
  • 1234:5678::abcd: Listen on specific IPv6 address on default port
  • [1234:5678::abcd]:80: Listen on specific IPv6 address and port
  • unix:/path/to/socket: Listen on Unix socket
  • unix-abstract:name: On Linux, listen on abstract Unix socket
  • example.com:80: DNS lookup to determine address
​
service
ServiceDesignator
required
Service name which should handle requests on this socket.

​
Protocol configuration

Each socket must specify one of the following protocols:

​
HTTP

​
http
HttpOptions
Serve unencrypted HTTP.
​
http.style
Style
default:"host"
HTTP style:
  • host: Normal HTTP (path in request line, separate Host header)
  • proxy: HTTP proxy protocol (full URL in request line)
​
http.forwardedProtoHeader
Text
Header name (e.g., X-Forwarded-Proto) that specifies the original protocol (http or https) when behind a reverse proxy.
​
http.cfBlobHeader
Text
Header name for encoding/parsing the request.cf object as JSON.
​
http.injectRequestHeaders
List<Header>
Headers automatically injected into all requests. Useful for adding authorization tokens.
​
http.injectResponseHeaders
List<Header>
Headers automatically injected into all responses.

​
HTTPS

​
https
group
Serve encrypted HTTPS.
  • options: HttpOptions (same as http)
  • tlsOptions: TlsOptions (TLS configuration)
​
https.tlsOptions.keypair
Keypair
required
Private key and certificate chain.
  • privateKey: PEM format (PKCS8, traditional RSA/DSA)
  • certificateChain: PEM format, starting with leaf certificate
Use Cap’n Proto’s embed directive to read from files.
​
https.tlsOptions.requireClientCerts
Bool
default:"false"
If true, reject connections without client certificates signed by trusted CAs.
​
https.tlsOptions.trustBrowserCas
Bool
default:"false"
If true, trust certificates signed by browser-trusted CAs. Set true for public internet connections.
​
https.tlsOptions.trustedCertificates
List<Text>
Additional CA certificates to trust, in PEM format.
​
https.tlsOptions.minVersion
Version
default:"goodDefault"
Minimum TLS version:
  • goodDefault: Maintainer-chosen default (recommended)
  • ssl3, tls1Dot0, tls1Dot1, tls1Dot2, tls1Dot3
​
https.tlsOptions.cipherList
Text
OpenSSL cipher list string. Generally only override for extreme compatibility needs or to quickly disable a broken algorithm.

​
Example

sockets = [
  ( name = "http",
    address = "*:8080",
    http = (),
    service = "main"
  ),
  ( name = "https",
    address = "*:8443",
    https = (
      options = (),
      tlsOptions = (
        keypair = (
          privateKey = embed "server-key.pem",
          certificateChain = embed "server-cert.pem"
        ),
        trustBrowserCas = true
      )
    ),
    service = "main"
  ),
  ( name = "internal",
    address = "unix:/var/run/workerd.sock",
    http = (),
    service = "admin"
  )
]

Build docs developers (and LLMs) love

Get started for freeTalk to us