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/Multicast port for managing SNMP or cluster management/messaging 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:

modifier1	datasize	modifier2	packet type	notes
0	size of WSGI block vars (HTTP request body excluded)	0	Standard WSGI request followed by the HTTP request body
1	reserved for UNBIT	-	-
2	reserved for UNBIT	-	-
3	reserved for UNBIT	-	-
5	size of PSGI block vars (HTTP request body excluded)	0	Standard PSGI request followed by the HTTP request body
6	size of LUA WSAPI block vars (HTTP request body excluded)	0	Standard LUA/WSAPI request followed by the HTTP request body
7	size of RACK block vars (HTTP request body excluded)	0	Standard RACK request followed by the HTTP request body
8	size of jwsgi block vars (HTTP request body excluded)	0	Standard jwsgi request followed by the HTTP request body
9	size of CGI block vars (HTTP request body excluded)	0	Standard CGI request followed by the HTTP request body
10	size of block vars	0-255	Management interface request: setup flag specified by modifier2. For a list of management flag look at ManagementFlag
14	size of CGI block vars (HTTP request body excluded)	0	Standard PHP request followed by the HTTP request body
17	size of Spooler block vars	0-255	Spooler request, the block vars is converted to a dictionary/hash/table and passed to the spooler callable. The second modifier is (for now) ignored
22	size of code string	0-255	Raw Code evaluation. The interpreter is choosen by the modifier2. 0 is Python, 5 is Perl	It does not return a valid uwsgi response, but a raw string (that can be an HTTP response)
26	0	0-255	call the fastfunc specified by the modifier2 field
30	size 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
31	size of block vars	0-255	Generic message passing (reserved)
32	size of char array	0-255	array of char passing (reserved)
33	size of marshal object	0-255	marshalled/serialzed object passing (reserved)
48	snmp specific	snmp specific	identify a SNMP request/response (mainly via UDP)
72	chr(TT)	chr(P)	corresponds to the 'HTTP' string and signal that this is an http response.
73	announce message size (for sanity check)	announce type (0 = hostname)	announce message
74	multicast message size (for sanity check)	0	array of chars -> custom multicast message managed by uwsgi.multicast_manager
95	cluster membership dict size	action	add/remove/enable/disable node from a cluster, action can be 0 = add, 1 = remove, 2 = enable, 3 = disable. Add action requires a dict of at least 3 keys, hostname, address and workers
96	log message size	0	remote logging (clustering/multicast/unicast)
97	0	0-1	brutal reload request (0 request - 1 confirmation)
98	0	0-1	graceful reload request (0 request - 1 confirmation)
99	size of options dictionary (if response)	0-1	request configuration data from a uwsgi node (even via multicast)
100	0	0-1	PING-PONG if modifier2 is 0 it is a PING request otherwise it is a PONG (a response). Useful for cluster health-check
101	size of packet	0	ECHO service
110	size of payload	0-255	uwsgi_signal framework (payload is optional), modifier2 is the signal num
111	size of packet	0-3	cache operations, 0->read, 1->write, 2->del, 3->dict_based
173	size of packet	0-1	RPC, the packet is a uwsgi array where the first item is the name of the function and the following are the args (if modifier2 is 1 the rpc will be 'raw' and all the response will be returned to the app(uwsgi header included, if available)
200	0	0	close-mark for persistent connections
224	size of packet	0	subscription packet. see SubscriptionServer
255	0	0-255	Generic 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];
}