freeswitch/libs/libscgi/protocol.txt

SCGI: A Simple Common Gateway Interface alternative
Neil Schemenauer <nas@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: */