Gemini Mention

So, what is ``Gemini Mention?''

Gemini mention is a simple protocol to notify a URL when it's being linked, and for pages to request such notifications. It is based upoon Webmentions, but with modifications to work within the Gemini community.

Webmention

Conformance

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", " SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

RFC-2119 Key words for use in RFCs to Indicate Requirement Levels

Discovery of a Gemini endpoint

To specify the location of a Gemini mention endpoint, a Gemini page MUST have a link pointing to it. This link MUST contain a query string of "gemini-mention" to make it easy for a client to location the endpoint.

=> gemini://example.com/cgi-bin/gm.cgi?gemini-mention Are you talking to me?

The query string "gemini-mention" is not used further in the protocol---it only serves to mark the endpoint itself. An implementation SHOULD support queries to the endpoint with the query string "gemini-mention" by sending a description of the protocol (like this text), or redirect to a page of text. A client SHOULD NOT send the Gemini mention endpoint the query "gemini-mention".

If a Gemini page does not contain a Gemini mention endpoint, a client SHOULD NOT send a Gemini mention about that page to the server. A client SHOULD only send Gemini mentions to pages with the Gemini mention endpoint specified in the page.

Rational

An issue with Gemini is that there are no headers in the reply to send this link, nor are is there a way to embed the link within the document with the required semantics as one can do via HTTP or HTML:

GET /the-post HTTP/1.1
Host: example.com
Link: <https://example.com/cgi-bin/wm.cgi>

<html>
<head>
  ...
  <link rel="webmention" href="https://example.com/cgi-bin/wm.cgi">
  ... 
</head>

<body>
  ...
  <a rel="webmention" href="https://example.com/cgi-bin/wm.cgi">
  ...
</body>
</html>

Requiring a known path for the Gemini mention might restrict who can participate in receiving Gemini mentions, or require major changes to a particular server implementation. Also, requiring specific text as the description would restrict it to English speakers. That leaves the only solution to be a particular query string to mark the Gemini mention endpoint to use.

The Protocol

Gemini mentions are sent from a source URI to a target URI to inform the target URI that the source URI has linked to it (all links are for example only):

Alice writes a Gemini post (posted at <gemini://alice.example.com/post>).
Bob writes a post referencing Alice's post (posted at <gemini://bob.example.net/post>) and somehow informs his server to do a Gemini mention.
Bob's server MUST fetch Alice's post and scan it for a Gemini mention endpoint (example: <gemini://alice.example.com/cgi-bin/mention?gemini-mention>). If the page does not contain a Gemini mention endpoint, the server MUST stop processing. It MAY inform Bob of this condition.
Bob's server MUST send a query to the Gemini mention endpoint it found, replacing the query string "gemini-mention" with two name/value pairs: "source" set to Bob's URI, and "target" set to Alice's URI (example: <gemini://alice.example.com/cgi-bin/gm.cgi?source=gemini://bob.example.net/post&target=gemini://alice.example.com/post>).
Alice's server, upon receiving the above query, MUST check that the target variable of the query contains a valid URI for her site. If it does not, it MUST stop processing and reply to the query with '59 Bad Request'.
Alice's server MUST fetch the source URI (following any redirects) and check that it contains a link that matches the target URI sent in. If the source URI does not exist or the page does not contain a link that matches the target URI, then the server MUST stop processing and reply to the query with '59 Bad Request'.
The quest is valid---Alice's server MUST reply with '20' (success) and send back either 'text/plain' or 'text/gemini' with a human readable text. Alice's server MAY then do what it wants with the information.
Bob's server MAY inform Bob of the results of the Gemini mention.