libwebsockets/READMEs

Unix Domain Sockets Reverse Proxy

Introduction

lws is able to use a mount to place reverse proxies into the URL space.

These are particularly useful when using Unix Domain Sockets, basically files in the server filesystem, to communicate between lws and a separate server process and integrate the result into a coherent URL namespace on the lws side.

This has the advantage that the actual web server that forwards the data from the unix socket owner is in a different process than the server that serves on the unix socket. If it has problems, they do not affect the actual public-facing web server. The unix domain socket server may be in a completely different language than the web server.

Compared to CGI, there are no forks to make a connection to the unix domain socket server.

Mount origin format

Unix Domain Sockets are effectively "files" in the server filesystem, and are defined by their filepath. The "server" side that is to be proxied opens the socket and listens on it, which creates a file in the server filesystem. The socket understands either http or https protocol.

Lws can be told to act as a proxy for that at a mountpoint in the lws vhost url space.

If your mount is expressed in C code, then the mount type is LWSMPRO_HTTP or LWSMPRO_HTTPS depending on the protocol the unix socket understands, and the origin address has the form +/path/to/unix/socket:/path/inside/mount.

The + at the start indicates it is a local unix socket we are proxying, and the ':' acts as a delimiter for the socket path, since unlike other addresses the unix socket path can contain '/' itself.

Connectivity rules and translations

Onward proxy connections from lws to the Unix Domain Socket happen using http/1.1. That implies transfer-encoding: chunking in the case that the length of the output is not known beforehand.

Lws takes care of stripping any chunking (which is illegal in h2) and translating between h1 and h2 header formats if the return connection is actually in http/2.

The h1 onward proxy connection translates the following headers from the return connection, which may be h1 or h2:

Header	Function
host	Which vhost
etag	Information on any etag the client has cached for this URI
if-modified-since	Information on the freshness of any etag the client has cached for this URI
accept-language	Which languages the return path client prefers
accept-encoding	Which compression encodings the client can accept
cache-control	Information from the return path client about cache acceptability
x-forwarded-for	The IP address of the return path client

This implies that the proxied connection can

• return 301 etc to say the return path client's etag is still valid

• choose to compress using an acceptable content-encoding

The following headers are translated from the headers replied via the onward connection (always h1) back to the return path (which may be h1 or h2)

Header	Function
content-length	If present, an assertion of how much payload is expected
content-type	The mimetype of the payload
etag	The canonical etag for the content at this URI
accept-language	This is returned to the return path client because there is no easy way for the return path client to know what it sent originally. It allows clientside selection of i18n.
content-encoding	Any compression format on the payload (selected from what the client sent in accept-encoding, if anything)
cache-control	The onward server's response about cacheability of its payload

h1 -> h2 conversion

Chunked encoding that may have been used on the outgoing proxy client connection is removed for h2 return connections (chunked encoding is illegal for h2).

Headers are converted to all lower-case and hpack format for h2 return connections.

Header and payload proxying is staged according to when the return connection (which may be an h2 child stream) is writable.

Behaviour is unix domain socket server unavailable

If the server that listens on the unix domain socket is down or being restarted, lws understands that it couldn't connect to it and returns a clean 503 response HTTP_STATUS_SERVICE_UNAVAILABLE along with a brief human-readable explanation.