1## Unix Domain Sockets Reverse Proxy 2 3### Introduction 4 5lws is able to use a mount to place reverse proxies into the URL space. 6 7These are particularly useful when using Unix Domain Sockets, basically 8files in the server filesystem, to communicate between lws and a separate 9server process and integrate the result into a coherent URL namespace on 10the lws side. It's also possible to proxy using tcp sockets. 11 12 13 14This has the advantage that the actual web server that forwards the 15data from the unix socket owner is in a different process than the server 16that serves on the unix socket. If it has problems, they do not affect 17the actual public-facing web server. The unix domain socket server may 18be in a completely different language than the web server. 19 20Compared to CGI, there are no forks to make a connection to the unix 21domain socket server. 22 23### Mount origin format 24 25Unix Domain Sockets are effectively "files" in the server filesystem, and 26are defined by their filepath. The "server" side that is to be proxied opens 27the socket and listens on it, which creates a file in the server filesystem. 28The socket understands either http or https protocol. 29 30Lws can be told to act as a proxy for that at a mountpoint in the lws vhost 31url space. 32 33If your mount is expressed in C code, then the mount type is LWSMPRO_HTTP or 34LWSMPRO_HTTPS depending on the protocol the unix socket understands, and the 35origin address has the form `+/path/to/unix/socket:/path/inside/mount`. 36 37The + at the start indicates it is a local unix socket we are proxying, and 38the ':' acts as a delimiter for the socket path, since unlike other addresses 39the unix socket path can contain '/' itself. 40 41### Connectivity rules and translations 42 43Onward proxy connections from lws to the Unix Domain Socket happen using 44http/1.1. That implies `transfer-encoding: chunking` in the case that the 45length of the output is not known beforehand. 46 47Lws takes care of stripping any chunking (which is illegal in h2) and 48translating between h1 and h2 header formats if the return connection is 49actually in http/2. 50 51The h1 onward proxy connection translates the following headers from the return 52connection, which may be h1 or h2: 53 54Header|Function 55---|--- 56host|Which vhost 57etag|Information on any etag the client has cached for this URI 58if-modified-since|Information on the freshness of any etag the client has cached for this URI 59accept-language|Which languages the return path client prefers 60accept-encoding|Which compression encodings the client can accept 61cache-control|Information from the return path client about cache acceptability 62x-forwarded-for|The IP address of the return path client 63 64This implies that the proxied connection can 65 66 - return 301 etc to say the return path client's etag is still valid 67 68 - choose to compress using an acceptable content-encoding 69 70The following headers are translated from the headers replied via the onward 71connection (always h1) back to the return path (which may be h1 or h2) 72 73Header|Function 74---|--- 75content-length|If present, an assertion of how much payload is expected 76content-type|The mimetype of the payload 77etag|The canonical etag for the content at this URI 78accept-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. 79content-encoding|Any compression format on the payload (selected from what the client sent in accept-encoding, if anything) 80cache-control|The onward server's response about cacheability of its payload 81 82### h1 -> h2 conversion 83 84Chunked encoding that may have been used on the outgoing proxy client connection 85is removed for h2 return connections (chunked encoding is illegal for h2). 86 87Headers are converted to all lower-case and hpack format for h2 return connections. 88 89Header and payload proxying is staged according to when the return connection 90(which may be an h2 child stream) is writable. 91 92### Behaviour if unix domain socket server unavailable 93 94If the server that listens on the unix domain socket is down or being restarted, 95lws understands that it couldn't connect to it and returns a clean 503 response 96`HTTP_STATUS_SERVICE_UNAVAILABLE` along with a brief human-readable explanation. 97 98The generated status page produced will try to bring in a stylesheet 99`/error.css`. This allows you to produce a styled error pages with logos, 100graphics etc. See [this](https://libwebsockets.org/git/badrepo) for an example of what you can do with it. 101 102
