💾 Archived View for rawtext.club › ~sloum › geminilist › 002792.gmi captured on 2024-03-21 at 15:35:51. Gemini links have been rewritten to link to archived content
⬅️ Previous capture (2020-10-31)
-=-=-=-=-=-=-
John Cowan cowan at ccil.org
Mon Sep 28 01:22:34 BST 2020
- - - - - - - - - - - - - - - - - - -
Dioscuri is a protocol intended to supplement Gemini for doing things likeuploading files, performing remote actions, and running an applicationserver. It is the POST to Gemini's GET. Dioscuri servers will run on adifferent port altogether, so that they do not interfere with Geminiservers. Dioscuri, unlike Gemini, absolutely *requires* the use of clientcertificates.
Great thanks to the members of irc://tilde.chat/gemini, especially lukeeand aravk.
The name "Dioscuri" is the Latinized spelling of the Greek name for theHeavenly Twins, Castor and Pollux/Polydeukes, who were called Gemini inLatin; the constellation is named after them. I say dee-OH-skoo-ree, butGreeks, classicists, and others should feel free to pronounce the nametheir way.
=======
A Dioscuri request starts out with the client sending a single line,<URL><SP><MEDIA-TYPE><CR><LF>. This indicates that a body follows whichshould be interpreted according to the media type. For example, "gemini://example.org/foo text/gemini\r\n" means that the Dioscuri server should dosomething with the following body, which is of type text/gemini. Exactlywhat happens depends on the server and the URL. For example, it mightreplace the contents of "foo" with the uploaded body. Alternatively,"gemini://example.org/do/this text/javascript\r\n" might cause theJavaScript in the uploaded body to be executed on the server.
As a special case, a client can send a Dioscuri header without a media typeor separating space, in which case no request body is allowed or expected.This can be used if the contents of the URL are sufficient to tell theserver what to do.
=======
When Dioscuri has received the header and body, then it does whatever itdoes and returns a regular Gemini header with some extensions. If theserver is going to be conversational, it will process the uploaded bodywith whatever semantics it assigns to it and then send a regular Geminiresponse header. For example, an application server might be sent aheader "<URL> application/json\r\n" followed by a JSON value, computesomething, and return "20 application/json\r\n" followed by the computedJSON value.
If the server has nothing to send to the client, as in the case of anupload, it can respond with "20\r\n", which means that there is no responsebody.
=======
By mutual agreement between the client and the server, the server mayreturn "70 <URL>\r\n" not followed by a body. This code means that therequest has succeeded, but rather than the server sending a response bodyin the same TCP connection, the response body can be found at <URL>.
A use case for this is that the client wishes to add a new file to acontainer (directory or whatever) in the server but leaves it up to theserver to choose the new URL according to some algorithm (random,timestamp, etc.) So a request of "<container-URL> text/gemini\r\n"followed by the body would in such a case respond "60 <object-URL>\r\n",meaning that the new resource can be found at <object-URL>.
All other 2-digit response codes have the same meaning in Dioscuri as inGermini. The reason for not using the 30 code in place of 60 is that 30would mean "redirect the request", as for all other cases of 30, whereas 60means "the response can be found here." I thought of using 21, but thatwould make the second status digit an essential part of the protocol. Notethat like 2x, 6x is considered a success.
=======
Finally, an implementation note: the TCP library used to implement Dioscuriclients must be able to separately close the input and the output sides ofthe TCP connection to the server. So in the application server discussedabove, the client closes the output side of its socket when it has sent thebody, and the server receives EOF when it attempts to read more body.However, the input side on the client must remain open so that theserver's response can be read.
Comments?
John Cowan http://vrici.lojban.org/~cowan cowan at ccil.orgAnd it was said that ever after, if any man looked in that Stone,unless he had a great strength of will to turn it to other purpose,he saw only two aged hands withering in flame. --"The Pyre of Denethor"-------------- next part --------------An HTML attachment was scrubbed...URL: <https://lists.orbitalfox.eu/archives/gemini/attachments/20200927/1020e3cd/attachment.htm>