branch: externals/url-scgi
commit 62a6cf93053cfcfd05357fe86316fc02636e4d2e
Author: Stefan Kangas <skan...@skangas.se>
Commit: Stefan Kangas <skan...@skangas.se>
Update documentation and add new doc/ directory
---
doc/scgi-protocol.txt | 101 ++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 101 insertions(+)
diff --git a/doc/scgi-protocol.txt b/doc/scgi-protocol.txt
new file mode 100644
index 0000000000..34c128005f
--- /dev/null
+++ b/doc/scgi-protocol.txt
@@ -0,0 +1,101 @@
+SCGI: A Simple Common Gateway Interface alternative
+Neil Schemenauer <n...@python.ca>
+2008-06-23
+
+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: */
