-- Leo's gemini proxy
-- Connecting to satch.xyz:1965...
-- Connected
-- Sending request
-- Meta line: 20 text/gemini
Right now GMAP is a work in progress and has no specification, but this document is meant as a record of standards to be used between implementers while the protocol is developed and set in stone.
The GMAP uses standardized Gemini requests and some misfin messages to fetch messages from the server to the client and tell the server when messages are read, deleted, archived, sent, or otherwise organized.
Servers can make message fetch available on any reasonable port over gemini://, but misfin clients SHOULD use the default port of 1958 if not otherwise configured.
Each message MUST have a message ID which is chosen by the server and unique to a given misfin account. This can be an md5 hash of the message contents and timestamp, an integer value, or anything in between. Clients shouldn't care how the message ID is chosen or assign any other special meaning to it, they should just treat it as a unique arbitrary string.
Misfin clients must use the following information in order to work with a misfin server over GMAP:
Hostname
Misfin certificate and private key (generated by the server)
Misfin clients CAN be given the additional information for configuration purposes, which will override the client defaults:
Gemini port number (to use instead of 1958 for gemini requests)
GMAP misfin address (for sent mail and drafts)
This gemini server interface should be accessible only by requests made using the misfin keypair associated with the account or another verified client certificate associated with the same account.
Individual messages should be available at gemini://host.name:port/msgid/<msgid>. This address should serve a text file of type text/plain with the exact same format by which misfin messages are transmitted over the wire, but with all relevant metadata included. The recipients line MAY be excluded if there was only one recipient, namely the misfin account which is making the request to the server.
At the address gemini://host.name:port/tag/<tagname> there should be a plaintext list of message IDs which have the named tag. The list should be separated by commas with optional whitespace. Tags therefore must not contain spaces or other characters which must be escaped in urls.
gemini://host.name:port/tag/ should return a list of all message ids stored by the server. There is no untag action which can be done here.
The client may request gemini://host.name:port/tag/<tagname>/YYYY-MM-DDTHH:MM:SSZ in 24 hour UTC to get a list of only those messages received since a given time. An analogous thing can be done without specifying a tagname.
A gemini request of gemini://host.name:port/tag/<tagname>?<msgid> should add the tag <tagname> to <msgid> if it does not already have that tag. gemini://host.name:port/untag/<tagname>?<msgid> should remove the tag. Servers should tack the most recent tag or untag action on a given message (even if it is tagging a message that already had the tag, the timestamp should be updated).
A gemini request of gemini://host.name:port/delete?<msgid> MUST result in the message being permanently deleted from the server and its message ID being removed from all tag lists ONLY if the message was previously tagged "Trash". In the event that this request is made for a message ID which does not have the "Trash" tag, then the server should respond with a 51 Not Found status (indicating that the specified message was not found in the trash).
Servers MUST respond to these requests with appropriate gemini status codes, where a 20 indicates success. What is served after the 20 (such as the mime type and response body) MAY be ignored by the client. Servers MUST NOT respond to requests with 1* status codes. 3* codes can be used to communicate that the same request should be tried again elsewhere, but they MUST only be used to redirect to a different hostname or port, as the path and query must be as specified.
Servers and clients MUST use the following tagnames for the following things:
These tags can be thought of as "folder" tags:
"Inbox" for an inbox folder where new messages appear by default;
"Archive" for received mail which is kept but not tagged with "Inbox" or "Trash";
"Sent" for messages which have been sent by the misfin address;
"Drafts" for messages which have been composed and stored but not sent;
The remaining tags can be thought of as "status" tags:
"Trash" for mail marked for deletion. This mail MUST NOT be listed in tag list requests for tags other than "Trash", however that mail MUST be tagged as it previously had been if it removed from the trash.
"Unread" which is a tag which should be automatically assigned to messages when they are first received
Clients and servers need not make an explicit distinction between these two types, as the communication of tagging and untagging is the same for both types.
Users can specify their own tags. Tags may contain letters of either case, digits, underscores, and dashes, but no other characters. Any kind of tag hierarchy or "nesting" must be handled exclusively by the client. Additionally, these tags must all function as generic tags with no special rules that must be commicated by the server.
Clients which use GMAP MUST tell servers when they send messages. This is done by sending a copy of the sent message to the server's GMAP mailbox. This can be simply the admin address of the server, or it can be a dedicated gmap@host.name address, as configured by the user. Clients should default to using gmap@host.name if not otherwise configured.
When clients send sent mail to servers, they MUST include recipients information and timestamps in the metadata fields and MAY include sender information.
Clients SHOULD also tell servers when drafts are created or modified by sending the draft as a misfin message to the GMAP server address. Drafts must be sent with recipients metadata and may be sent with timestamps and/or senders metadata.
For modified drafts and sending mail which has previously been assigned a message ID by the server, clients MUST begin the message body with a "MGID:<msgid>" metadata line which servers MUST check for and parse in order to determine which draft has been modified or sent. This syntax MUST only be checked when servers receive incoming mail to the GMAP handling address which is from an account on that server.
And other notes... tag deletion action (keep tags around until manually removed)
List custom tags option
For a given message, see last modification timestamp per tag, status
Get deletions and tag modifications since given timestamp
On sync, clients ask for events list since a certain timestamp and make sure they're up to date
-- Response ended
-- Page fetched on Mon May 20 16:23:10 2024