{"schema":"libjg2-1", "vpath":"/git/", "avatar":"/git/avatar/", "alang":"", "gen_ut":1731654024, "reponame":"libwebsockets", "desc":"libwebsockets lightweight C networking library", "owner": { "name": "Andy Green", "email": "andy@warmcat.com", "md5": "c50933ca2aa61e0fe2c43d46bb6b59cb" },"url":"https://libwebsockets.org/repo/libwebsockets", "f":3, "items": [ {"schema":"libjg2-1", "cid":"70f082fac4b455fdc05a2658059beb73", "oid":{ "oid": "6328231f2aa628632344d96a58e25c3b194af506", "alias": [ "refs/heads/main"]},"blobname": "READMEs/README.unix-domain-reverse-proxy.md", "blob": "## Unix Domain Sockets Reverse Proxy\n\n### Introduction\n\nlws is able to use a mount to place reverse proxies into the URL space.\n\nThese are particularly useful when using Unix Domain Sockets, basically\nfiles in the server filesystem, to communicate between lws and a separate\nserver process and integrate the result into a coherent URL namespace on\nthe lws side. It's also possible to proxy using tcp sockets.\n\n\n\nThis has the advantage that the actual web server that forwards the\ndata from the unix socket owner is in a different process than the server\nthat serves on the unix socket. If it has problems, they do not affect\nthe actual public-facing web server. The unix domain socket server may\nbe in a completely different language than the web server.\n\nCompared to CGI, there are no forks to make a connection to the unix\ndomain socket server.\n\n### Mount origin format\n\nUnix Domain Sockets are effectively \u0022files\u0022 in the server filesystem, and\nare defined by their filepath. The \u0022server\u0022 side that is to be proxied opens\nthe socket and listens on it, which creates a file in the server filesystem.\nThe socket understands either http or https protocol.\n\nLws can be told to act as a proxy for that at a mountpoint in the lws vhost\nurl space.\n\nIf your mount is expressed in C code, then the mount type is LWSMPRO_HTTP or\nLWSMPRO_HTTPS depending on the protocol the unix socket understands, and the\norigin address has the form `+/path/to/unix/socket:/path/inside/mount`.\n\nThe + at the start indicates it is a local unix socket we are proxying, and\nthe ':' acts as a delimiter for the socket path, since unlike other addresses\nthe unix socket path can contain '/' itself.\n\n### Connectivity rules and translations\n\nOnward proxy connections from lws to the Unix Domain Socket happen using\nhttp/1.1. That implies `transfer-encoding: chunking` in the case that the\nlength of the output is not known beforehand.\n\nLws takes care of stripping any chunking (which is illegal in h2) and\ntranslating between h1 and h2 header formats if the return connection is\nactually in http/2.\n\nThe h1 onward proxy connection translates the following headers from the return\nconnection, which may be h1 or h2:\n\nHeader|Function\n---|---\nhost|Which vhost\netag|Information on any etag the client has cached for this URI\nif-modified-since|Information on the freshness of any etag the client has cached for this URI\naccept-language|Which languages the return path client prefers\naccept-encoding|Which compression encodings the client can accept\ncache-control|Information from the return path client about cache acceptability\nx-forwarded-for|The IP address of the return path client\n\nThis implies that the proxied connection can\n\n - return 301 etc to say the return path client's etag is still valid\n\n - choose to compress using an acceptable content-encoding\n\nThe following headers are translated from the headers replied via the onward\nconnection (always h1) back to the return path (which may be h1 or h2)\n\nHeader|Function\n---|---\ncontent-length|If present, an assertion of how much payload is expected\ncontent-type|The mimetype of the payload\netag|The canonical etag for the content at this URI\naccept-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.\ncontent-encoding|Any compression format on the payload (selected from what the client sent in accept-encoding, if anything)\ncache-control|The onward server's response about cacheability of its payload\n\n### h1 -\u003e h2 conversion\n\nChunked encoding that may have been used on the outgoing proxy client connection\nis removed for h2 return connections (chunked encoding is illegal for h2).\n\nHeaders are converted to all lower-case and hpack format for h2 return connections.\n\nHeader and payload proxying is staged according to when the return connection\n(which may be an h2 child stream) is writable.\n\n### Behaviour if unix domain socket server unavailable\n\nIf the server that listens on the unix domain socket is down or being restarted,\nlws understands that it couldn't connect to it and returns a clean 503 response\n`HTTP_STATUS_SERVICE_UNAVAILABLE` along with a brief human-readable explanation.\n\nThe generated status page produced will try to bring in a stylesheet\n`/error.css`. This allows you to produce a styled error pages with logos,\ngraphics etc. See [this](https://libwebsockets.org/git/badrepo) for an example of what you can do with it.\n\n","s":{"c":1731654024,"u": 279}} ],"g": 2139,"chitpc": 0,"ehitpc": 0,"indexed":0 , "ab": 1, "si": 0, "db":0, "di":0, "sat":0, "lfc": "0000"}