The Titan protocol is a sister-protocol to Gemini. Where as Gemini is used to read pages in Gemini space, Titan is used to write pages in Gemini space.
It is expected that a resources that you can read using Gemini may be writeable using Titan. Thus, a URL points to “resource”. If you point your Gemini client to that URL, you’re “reading” the resource.
A Titan URL uses the “titan” scheme instead of “gemini”. If you point your Titan-enabled client at this Titan URL, you’re “writing” to that resource.
A Titan URL uses extra parameters. Parameters are not query parameters! There is no question mark after the URL. Parameters are separated from the rest of the URL and each other using a semicolon and they come as key/value pairs.
URI producing applications often use the reserved characters allowed in a segment to delimit scheme-specific or dereference-handler-specific subcomponents. For example, the semicolon (”;”) and equals (”=”) reserved characters are often used to delimit parameters and parameter values applicable to that segment. – RFC 3986
Titan uses three parameters:
For an implementation of this as two little Bash functions, see Gemini Titan. Using the two commands, you could read the page using “gemini communitywiki.org/page/Test” and you could write the current date to the page using “date --iso-8601 | titan communitywiki.org/raw/Test hello”.
Note that the protocol only does authorization: you bear a token (the password) of authorization. People can pass it on and invite other people to join. The editing is anonymous.
A server that would like to identify its users, maybe give them different capabilities depending on who they are, would use client certificates to establish identity and act accordingly. That is, authentication is already part of Gemini and as such applies just as much to Titan. It doesn’t change any part of what has been said above, however.
This particular server has the peculiarity that only the “raw” pages can be edited. That is:
To read the Test page in Gemini format, use “gemini://communitywiki.org/page/Test”.
To read the Test page in raw format, use “gemini://communitywiki.org/raw/Test”
To write to the raw page, use “titan://communitywiki.org/raw/Test;token=hello;mime=plain/text;size=10” followed by a payload of ten bytes.
The size parameter is needed so that the server can distinguish between a really slow upload and the end of the upload. The alternative would be to wait for a sequence of special bytes, like the end of a line, or a dot on a line by itself. But none of that allows for binary uploads, of course. For binary uploads, a size is mandatory, or you need a timeout, making life hard for people without a good connection, or you open yourself up to a denial of service attack by people uploading gigabytes of data, thrashing your memory, or your temp filesystem.
And that’s also where the mime type comes in. If you don’t want to rely on the filenames, you need some out of band information on what people are uploading.
The token is necessary to defend against vandalism or spam – the only alternative would be the mandatory registering of client certificates. I feel that raises the barrier to entry quite considerably.
Also: if you use client certificates, will you mandate the same if people can upload/edit pages via the web or some other protocol? The token translates well between Gemini and the web.