SCGI: A Simple Common Gateway Interface alternative
Neil Schemenauer <nas@python.ca>
2006-01-12

1. Introduction

The SCGI protocol is a replacement for the Common Gateway Interface
(CGI) protocol. It is a standard for applications to interface with
HTTP servers. It is similar to FastCGI but is designed to be easier
to implement.

In this document, a string of 8-bit bytes may be written in two
different forms: as a series of hexadecimal numbers between angle
brackets, or as a sequence of ASCII characters between double quotes.
For example, <68 65 6c 6c 6f 20 77 6f 72 6c 64 21> is a string of
length 12; it is the same as the string "hello world!". Note that
these notations are part of this document, not part of the protocol.


2. Protocol

The client connects to a SCGI server over a reliable stream protocol
allowing transmission of 8-bit bytes. The client begins by sending a
request. See section 3 for the format of the request. When the SCGI
server sees the end of the request it sends back a response and closes
the connection. The format of the response is not specified by this
protocol.


3. Request Format

A request consists of a number of headers and a body. The format of
the headers is:

headers ::= header*
header ::= name NUL value NUL
name ::= notnull+
value ::= notnull+
notnull ::= <01> | <02> | <03> | ... | <ff>
NUL = <00>

Duplicate names are not allowed in the headers. The first header
must have the name "CONTENT_LENGTH" and a value that is a nonempty
sequence of ASCII digits giving the of the body length in decimal.
The "CONTENT_LENGTH" header must always be present, even if its
value is "0". There must also always be a header with the name
"SCGI" and a value of "1". In order to facilitate the transition
from CGI, standard CGI environment variables should be provided as
SCGI headers.

The headers are sent encoded as a netstring. Netstring encoding is
explained in section 4. The body is sent following the headers and
its length is specified by the "CONTENT_LENGTH" header.


4. Netstrings

Any string of 8-bit bytes may be encoded as [len]":"[string]",". Here
[string] is the string and [len] is a nonempty sequence of ASCII
digits giving the length of [string] in decimal. The ASCII digits are
<30> for 0, <31> for 1, and so on up through <39> for 9. Extra zeros
at the front of [len] are prohibited: [len] begins with <30> exactly
when [string] is empty.

For example, the string "hello world!" is encoded as <31 32 3a 68 65
6c 6c 6f 20 77 6f 72 6c 64 21 2c>, i.e., "12:hello world!,". The empty
string is encoded as "0:,".

[len]":"[string]"," is called a netstring. [string] is called the
interpretation of the netstring.


5. Example

The web server (a SCGI client) opens a connection and sends the
concatenation of the following strings:

"70:"
"CONTENT_LENGTH" <00> "27" <00>
"SCGI" <00> "1" <00>
"REQUEST_METHOD" <00> "POST" <00>
"REQUEST_URI" <00> "/deepthought" <00>
","
"What is the answer to life?"

The SCGI server sends the following response:

"Status: 200 OK" <0d 0a>
"Content-Type: text/plain" <0d 0a>
"" <0d 0a>
"42"

The SCGI server closes the connection.


6. Copyright

This document has been placed in the public domain.


/* vim: set ai tw=74 et sw=4 sts=4: */