💾 Archived View for tris.fyi › projects › amethyst › cgi.gmi captured on 2023-09-28 at 15:41:57. Gemini links have been rewritten to link to archived content

-=-=-=-=-=-=-

Amethyst CGI

Back to project page

Amethyst supports CGI on paths with the "cgi" option set to true. Any files marked as executable (chmod +x) are executed as described in this document.

Execution environment

CGI scripts are launched with the same environment variables as Amethyst itself is. The following additional environment variables are set to conform to the CGI specification:

GATEWAY_INTERFACE   "CGI/1.1"
SERVER_PROTOCOL     "Gemini/0.16.0"
SERVER_SOFTWARE     "Amethyst"
REMOTE_ADDR         IP address of requester
QUERY_STRING        URL query string, or empty string
SCRIPT_NAME         Original URL from the request
SERVER_NAME         Host name from the request
SERVER_PORT         Server listening port (usually 1965)

CGI response headers

Your script can send psuedo-headers to adjust how Amethyst serves your response to the client. Psuedo-headers must be sent at the very beginning of your script output, one per line, without empty lines separating them. (After it sees the first empty line or non-psuedo-header line, Amethyst stops looking for psuedo-headers.)

No psuedo-headers are required. By default, the script's content will be sent as "text/gemini" with the 20 OK status.

Here are the supported psuedo-headers:

Content-Type: text/plain
Status: 51
Location: /

Content-Type changes the meta information the server returns to the client. Normally this represents the MIME type of the response.

Status changes the status returned to the client (note that if you specify a status code not defined in the Gemini spec, it is ignored).

Location causes Amethyst to immediately stop parsing your script's output and immediately send a 30 Temporary Redirect response to the specified URL.

Execution behavior

Amethyst executes your script, waits for it to exit, then starts processing the output.

If your script exits with a status code other than 0, Amethyst returns a 42 CGI Error response. The meta information includes the exit code of the script.

Aside from processing psuedo-headers as described above, Amethyst doesn't attempt to process your script output, instead sending it directly to the client. This means that you are responsible for making sure your output is e.g. valid UTF-8 when returning text/gemini content.

Future extensions

Once proper client certificate support is added, client certificate hash and name information will be available to scripts.