The Spartan Protocol Specification
Last updated 2021-03-24
1 Overview
spartan:// is a client-to-server protocol designed for hobbyists. Spartan draws on ideas from gemini, gopher, and http to create something new, yet familiar. It strives to be simple, fun, and inspiring.
Spartan sends ASCII-encoded, plaintext requests over TCP. Arbitrary text and binary files are supported for both upload and download. Like gemini, the default hypertext document in spartan is text/gemini. A special line type ("=:") is used to prompt for input. Spartan has four status codes: "success", "redirect", "server error", and "client error".
Spartan is not opinionated about how or what you use it for, only that you have fun doing so!
2 Requests
A spartan request is a single ASCII-encoded request line followed by an optional data block.
request = request-line [data-block] request-line = host SP path-absolute SP content-length CRLF
The host component specifies the host of the server that the request is being sent to. The port number should not be included in the host component. Hosts that contain non-ASCII characters (IDNs) should be converted to punycode.
The path component specifies the resource that is being requested. It must be absolute and begin with a "/" character.
The data block can be used by the client to upload arbitrary data to the server. The content-length component specifies the length, in bytes, of the data block. A content length of "0" means that no extra data will be attached to the request.
The format of uploaded data is left up to the server to define based on surrounding context. It might contain plain text, binary data, or a mixed encoding.
2.1 Reference: example spartan requests
# Download a text file example.com /files/about.txt 0 # Post to a message board example.com /guestbook/submit 12 Hello world! # Upload an audio file example.com /upload/africa.mp3 3145728 <binary data stream...>
3 Responses
A spartan response is single ASCII-encoded status line followed by an optional response body.
Spartan responses use single-digit status codes to indicate success or failure.
reply = success / redirect / client-error / server-error success = '2' SP mimetype CRLF body redirect = '3' SP path-absolute CRLF client-error = '4' SP errormsg CRLF server-error = '5' SP errormsg CRLF
"2": Success
A status of "2" indicates that the resource was successfully received, understood, and accepted. The mimetype should contain the MIME of the response document. It may also include a charset parameter to specify an encoding for the document. The default encoding for "text/*" documents should be assumed to be UTF-8.
"3": Redirect
A status of "3" indicates that the resource is located at a different location. The client should make a new request to the indicated absolute path. Redirects can only be specified to the same host as the original request.
"4": Client Error
A status of "4" indicates that the request contains bad syntax or cannot be fulfilled. The error message should contain a human readable description about the error.
"5": Server Error
A status of "5" indicates that the server is unable to fulfil an otherwise valid request. The error message should contain a human readable description about the error.
3.1 Reference: example spartan responses
# Success 2 text/plain; charset=utf-8 In a hole in the ground there lived a hobbit. Not a nasty, dirty, wet hole, filled with the ends of worms and an oozy smell, nor yet a dry, bare... # Redirect 3 /new/path/ # Client Error 4 File "/files/meaning_of_life.txt" not found # Server Error 5 Server is experiencing heavy load
4 Document Format
The spartan protocol uses gemtext (text/gemini) as its preferred hyperlink document.
4.1 Prompt Line
One additional, non-standard line type is defined to support data upload.
=:[<whitespace>]<URL>[<whitespace><USER-FRIENDLY LINK NAME>]
A prompt line should be treated the same as a "=>" link line, except that the client should prompt the user to define data to include as the [data-block] before sending the request. The precise UI for data input is not mandated, but some possible
forms might include a text box widget or a file picker widget.
This eliminates the need for gemini's "10 INPUT" response status code, and offers more flexibility to document authors by providing the equivalent of HTML's