1 : Abstract 2 : Conventions Used In This Document 2.1 : Definitions 2.1.1 : Operating Server 2.1.2 : Application 3 : Operating Server Requirements 3.1 : Execution 3.1 : Stream Forwarding 3.1 : Error Detection 4 : Application Requirements 4.1 : Handling Protocols 4.2 : Handling Requests 4.3 : Handling Signals 5 : Environment 5.1 : Working Directory 5.2 : Environment Variables 5.2.1 : Required Variables 5.2.2 : Protocol Variables 5.3 : Standard File Descriptors 5.3.1 : Stdin 5.3.2 : Stdout 5.3.3 : Stderr
SIGI, pronounced "see-gee", is an attempt to reinvent CGI in a way that is more applicable to the smallnet as well as allowing easier multiplexing of applications across protocols. This document serves as an informal specification of this interface for other possible implementations to follow.
CGI as an interface assumes some amount of uniformity across the protocols it abstracts, as the standard environment variables "REQUEST_METHOD", "REMOTE_HOST", and even URI specific variables such as "QUERY_STRING" suggests. These assumptions extend to the response headers as a concept, and its attempt to abstract protocol specific information from the executed CGI application. SIGI attempts to minimize these assumptions, so that implementing servers can avoid implementing dead components of a specification, and so that SIGI applications can be given ample control over their own operation.
SIGI takes inspiration from Unix's "inetd", while still retaining the support that CGI provides to its executed applications.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
Special definitions for use in this document, any other phrases can be assumed to follow canonical definitions.
The operating server is a listening network appliance that executes applications in a way conforming to this document. As a side effect of this definition, operating servers MUST utilize a streaming network protocol such as TCP.
A piece of software that is executed by the operating server under unspecified circumstances, and that conform to this document.
Operating servers SHOULD NOT block on execution of a SIGI application. This is in contrast to the aforementioned "inetd" inspiration, and allows for SIGI application support to effectively supplant CGI on the server. In the event that a timeout is reached while executing an application, SIGINT MUST be sent to the application.
Operating servers MUST NOT reuse applications for requests. New requests MUST be provided a new application, unless a rate limiting mechanism is in place.
Operating servers MUST forward well formed output from the application to the response stream related to the request sent to the application. In the event of ill formed data the server MAY forward without interception, or may follow the operation specified below.
Operating servers MAY intercept output from an application to detect for errors before forwarding. If an application is caught sending erroneous information, the SIGINT signal MUST be sent to the misbehaving application. If the application fails to die within an arbitrary timeout period, the application SHOULD be killed by force.
A simpler mechanism defined in this document is the empty error indicator. In the event an application shutdowns without any output, the operating server SHOULD interpret that as an error condition. In such a circumstance, a generic "server error" response MAY be sent to the response stream.
Applications MUST produce well formed information following the known protocol defined by the operating server. When an application begins execution, it SHOULD confirm that the operating server expects a protocol known by the application.
If an application is executed and it does not support the protocol expected, it SHOULD NOT continue operation. As there is no control stream between the operating server and the application, the application SHOULD immediately shutdown. This will satisfy the requirements to return the empty error indicator, as defined in 3.3.
Applications MUST handle only a single request, and MUST NOT produce more than a single response. The handling and orchestration of multiple request/response pairs is managed by the operating server that executes the application. After a request is handled and a full response produced, the application MUST shutdown.
Applications SHOULD handle the SIGINT signal, for when the operating server has decided that the application needs to be shutdown. In such a circumstance, cleanup routines SHOULD execute immediately and the application SHOULD shutdown as soon as possible.
An application's working directory MUST be the directory the executable file resides in.
The following environment variables are REQUIRED to be compliant with this specification:
GATEWAY_INTERFACE= # MUST be "SIGI/1". SERVER_SOFTWARE= # The name and version of the operating server. SERVER_PROTOCOL= # The protocol this server expects the application to use. SERVER_ROOT= # The root directory that application should remain in. SERVER_NAME= # The canonical name of the server, either IP or hostname. SCRIPT_NAME= # The canonical name of the script, usually the filename. REMOTE_ADDR= # The network address of the requesting client.
Furthermore, any protocol specific variables MUST be prefixed with the value provided by "SERVER_PROTOCOL", followed by an underscore. As an example, here is an example of what MAY be sent to an application when the protocol "GEMINI" is provided:
GEMINI_URL= # The URL of the Gemini request. GEMINI_ANSWER= # The answer to a previously asked question.
For protocols that support request bodies, "stdin" MUST start at the beginning of said request body. If the protocol does not support request bodies, then "stdin" MUST be a NULL stream ("/dev/null" on Unix, "nul" on Windows).
This file descriptor MUST be the response output stream for the application. It MUST NOT have a truncating size limit, and MUST support arbitrarily sized response streams.
This file descriptor SHOULD be the log output stream for the application. Operating servers SHOULD route "stderr" output to a relevant logging system.