From d77b21e374a6745e9bfb92ebfcb150b905b54c6e Mon Sep 17 00:00:00 2001 From: Rodrigo Arias Mallo Date: Mon, 30 Dec 2024 18:25:19 +0100 Subject: Add RFC 003: UNIX sockets in ULRs --- rfc/003-unix-sockets/index.html | 125 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 125 insertions(+) create mode 100644 rfc/003-unix-sockets/index.html diff --git a/rfc/003-unix-sockets/index.html b/rfc/003-unix-sockets/index.html new file mode 100644 index 0000000..17119d6 --- /dev/null +++ b/rfc/003-unix-sockets/index.html @@ -0,0 +1,125 @@ + + + + Dillo RFC 003 - UNIX sockets in URLs + + + + +

Dillo RFC 003 - UNIX sockets in URLs

+ +

State: Draft
Date: Draft on 2024-12-30
Author: Rodrigo Arias Mallo + <rodarima@gmail.com>

+ +

Abstract

+ +

This document adds UNIX sockets support to URLs by using host names with the TLD +“.unix” and a unix.hosts file that describe where in the file system +the socket file is located for a given host.

+ +

Proposal

+ +

UNIX sockets allow permissions to be established on a socket so that only a user +or a group of users can connect to it. However, the HTTP protocol doesn’t make +provisions to specify how to connect to UNIX sockets, and instead it uses TCP +to connect to a given host, which is resolved via DNS to an IP address.

+ +

To allow connecting to UNIX sockets, we propose using a special top level +domain (TLD) “.unix” which can be mapped to a local UNIX socket. In +this way, an URL like the following:

+ +

http://example.unix/index.html
+

+ +

Will search for a socket file mapped to “example.unix” and +perform a HTTP query over that socket to retrieve the “/index.html” +file. Similarly, other protocols like Gopher or Gemini can work with UNIX +sockets in the same way.

+ +

This scheme allows a user to place the sockets in any path of their choosing, +which doesn’t need to be revealed in the URL.

+ +

To support this scheme, a unix.hosts file is be used with a similar syntax as +the hosts file, in such a way that a user can define its own aliases:

+ +

unix:~/.dillo/example.sock    example.unix
+

+ +

Similarly, a system-wide configuration could be made available, and still +inherit the benefits from UNIX permissions:

+ +

unix:/var/lib/foobar.sock     foobar.unix
+

+ +

This proposal fails gracefully when a URL referring to a UNIX socket is +opened by a program that doesn’t support UNIX hosts, as the top level +domain “.unix” doesn’t exist +[1]. +Additionally, a program may determine that a host ending with .unix will use a +UNIX connection, so it is not needed to query any DNS server.

+ +

If no entry is found on the unix.hosts file for a given .unix host a default +set of locations for the UNIX socket could be attempted, but this is left out of +the current proposal.

+ +

Implementation details

+ +

This proposal could be implemented by any program that performs network +operations, it is not specific to Dillo. The following sections apply only to +Dillo itself, but may serve as a reference to other implementations.

+ +

The unix.hosts file

+ +

The format of the hosts file extends the syntax of /etc/hosts to allow hosts +that begin with the “unix:” prefix and are followed by a path. The +rest of the line defines aliases to that socket separated by white-spaces.

+ +

unix:/var/lib/foobar.sock  foobar.unix
+

+ +

The symbol ~ is expanded by the value of the $HOME variable of +the user performing the lookup. Therefore, to define sockets in the user home +directory:

+ +

unix:~/foobar.sock  foobar.unix  foo-bar.unix
+

+ +

UNIX host resolution

+ +

The process to resolve a UNIX host is quite simple. First, determine if the +URL host name ends in “.unix”. If so, follow the steps below. +Otherwise, proceed with the current host resolution, possibly querying DNS +servers.

+ +

To find how to connect to a .unix host, identify a matching entry in the +hosts.unix file by looking at all the aliases for each UNIX socket. If there is +a match, use the unix socket patch of that line and the socket() interface with +the AF_UNIX family.

+ +

Multiple entries

+ +

In order to give users the ability to redefine aliases to their own UNIX +sockets, the entries in the unix.hosts file have precedence over the ones in the +system-wide unix.hosts configuration file.

+ + + -- cgit v1.2.3