[spec] ☿️ — a symbolic protocol

Petite Abeille petite.abeille at gmail.com
Sun Feb 28 22:19:34 GMT 2021


The multiaddr bellow is the default location of a Mercury (☿️) service:


A multiaddr describes how to connect to a ☿️ service — for example, ➊ using DNS, ➋ resolve hostname ☿️.xyz, and ➌ connect over tcp ➍ to  port 1961.

To find a ☿️ multiaddr, query the host ☿️ DNS TXT record:

# dig +short TXT ☿️._tcp.☿️.xyz.

By default, a ☿️ service runs over TCP, at port 1961 †

A ☿️:// request is one-line —4,096 bytes long at most, UTF-8 encoded— containing a fully qualified, normalized Internationalized Resource Identifier (IRI):


An IRI is an UTF-8 version of an Uniform Resource Identifier (URI). 
An URI can be either an Uniform Resource Locator (URL), or Uniform Resource Name (URN).

An example of a ☿️ request, followed by a text/☿️ response:

# echo -e '☿️://☿️.xyz/\r\n' | nc 1961
㉉ text/☿️;charset=utf-8;
Hello ☿️!

∞ ☿️://☿️.xyz/license CC0-1.0 
<end of connection> 

A successful ☿️ response is a one-line with status ㉉—optionally followed by a content type, plus associated attributes, such as encoding:  

㉉ text/☿️;charset=utf-8;

The content type is optional — defaulting to text/☿️, UTF-8 encoded.

The content itself follow the  ㉉ status line — terminated by the service dropping the network connection.

There are 3 status codes:

㉉ [20] SUCCESS — one-line, with optional content type, plus attributes, 4,096 bytes long at most, UTF-8 encoded
㉉ text/☿️;charset=utf-8;

㉊ [30] REDIRECT — one-line IRI, fully qualified, and normalized, 4,096 bytes long at most, UTF-8 encoded
㉊ ☿️://☿️.xyz/

㉋ [40] ERROR — one-line, 4,096 bytes long at most, UTF-8 encoded, with optional description 
㉋ ⚠︎

A text/☿️ consists of two line types: text, and link. 

A link is denoted as one-line, starting with the infinity symbol (∞), followed by a space, followed by a fully qualified, and normalized, IRI — optionally followed by a space and description:

∞ ☿️://☿️.xyz/license CC0-1.0

All other lines are regular text lines.

A ☿️ URL may anchor a text/☿️ line number:


A ☿️ service may optionally respond to the urn:☿️:capa directive — listing additional capabilities, specific to the service, as text/☿️ links:

# echo -e 'urn:☿️:capa' | nc 1961
㉉ text/☿️;charset=utf-8;
∞ urn:☿️:capa
∞ urn:☿️:capa:connection:keep-alive
∞ urn:☿️:capa:transfer-encoding:chunked
∞ urn:☿️:capa:turn
<end of connection> 

Capabilities are optional, and not part of the ☿️ protocol. They are documented separately.

# while true; do { echo -e '㉉\r\n∞ urn:☿️:capa'; } | nc -l 1958; done
# echo -e 'urn:☿️:capa\r\n' | nc 1958
∞ urn:☿️:capa
<end of connection> 

That's all folks.


† NASA's Project Mercury was the first human spaceflight program of the United States, running from 1958 through 1963. The first crewed flight took place in 1961. Therefore the port number.

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.orbitalfox.eu/archives/gemini/attachments/20210228/b49f927c/attachment-0001.htm>

More information about the Gemini mailing list