The uwsgi protocol

The uwsgi (lowercase !) protocol is the protocol used by the uWSGI server.

It is a binary protocol that can carry every type of information.

The first 4 bytes of a uwsgi packet describe the type of information.

Every uwsgi request generates an uwsgi response. As you will see even the webserver handlers obey to this rule as an HTTP response is a valid uwsgi packet (look at the 72 modifier1)

The protocol works mainly via TCP but the Master process can bind to a UDP port for managing SNMP or cluster management requests.

SCTP support is on work.

uwsgi packet header

struct uwsgi_packet_header {
    uint8_t modifier1;
    uint16_t datasize;
    uint8_t modifier2;
};

unless otherwise specified the datasize value contains the size (16bit LE) of the packet body.

The packet type

The modifier1 value of the uwsgi packet header describe the type of information. This is the curent list of packet types:

modifier1datasizemodifier2packet type
0size of WSGI block vars (HTTP request body excluded)0 (if defined the size of the block vars is 24bit le, for now none of the webserver handlers support this feature)Standard WSGI request followed by the HTTP request body
1reserved for UNBIT--
2reserved for UNBIT--
3reserved for UNBIT--
5size of PSGI block vars (HTTP request body excluded)0Standard PSGI request followed by the HTTP request body
10size of block vars0-255 Management interface request: setup flag specified by modifier2. For a list of management flag look at ManagementFlag
17size of Spooler block vars0-255Spooler request, the block vars is converted in a python dictionary and passed to the spooler callable. The second modifier is (for now) ignored
2600-255call the fastfunc specified by the modifier2 field
30size of WSGI block vars (HTTP request body excluded)0 (if defined the size of the block vars is 24bit le, for now none of the webserver handlers support this feature)Standard WSGI request followed by the HTTP request body. The PATH_INFO is automatically modified, removing the SCRIPT_NAME from it
31size of block vars0-255Generic message passing. The block of vars is converted to a python dictionary and passed to the configured callable. The modifier2 arg is passed as the second argument.
32size of char array0-255array of char passing.The char sequence is converted to a python string and passed to the configured callable. The modifier2 is passed as the second argument.
33size of marshal object0-255Python Object (marshaled) passing. The marshal block is re-encoded to a python object and passed to the configured callable. The modifier2 is passed as the second argument.
41size of block varsextended size of block varsGeneric message passing (24bit LE size). The block of vars is converted to a python dictionary and passed to the configured callable. A 0 is passed as the second argument.
42size of char arrayextended size of char arrayarray of char passing (24bit LE size).The char sequence is converted to a python string and passed to the configured callable. A 0 is passed as the second argument.
43size of marshal objectextended size of marshal objectPython Object (marshaled in 24bit LE size) passing. The marshal block is re-encoded to a python object and passed to the configured callable. A 0 is passed as the second argument.
48snmp specificsnmp specificidentify a SNMP request/response (mainly via UDP)
72chr(TT)chr(P) corresponds to the 'HTTP' string and signal that this is an http response.
10000-1PING-PONG if modifier2 is 0 it is a PING request otherwise it is a PONG (a response). Useful for cluster health-check
25500-255Generic response. Request dependent. For example a spooler response set 0 for a failed spool or 1 for a successfull one

The uwsgi vars

The uwsgi block vars represent a dictionary/hash. Every key-value is encoded in this way:

struct uwsgi_var {
    uint16_t key_size;
    uint8_t key[key_size];
    uint16_t val_size;
    uint8_t val[val_size];
}