# `socketio.packet`

The day to day user doesn’t need to use this module directly.

The packets used internally (that might be exposed if you override the `process_packet()` method of your Namespace) are dictionaries, and are different from one message type to another.

## Internal packet types

Here is a list of message types available in the Socket.IO protocol:

### The connect packet

    {"type": "connect",
     "qs": "",
     "endpoint": "/chat"}

The `qs` parameter is a query string you can add to the io.connect(‘/chat?a=b’); calls on the client side.

The message packet, equivalent to Socket.IO version 0.6’s string message:

    {"type": "message",
     "data": "this is the sent string",
     "endpoint": "/chat"}

    {"type": "message",
     "data": "some message, but please reply",
     "ack": True,
     "id": 5,
     "endpoint": "/chat"}

This last message includes a msg_id, and asks for an ack, which you can reply to with `self.ack()`, so that the client-side callback is fired upon reception.

### The json packet

The json packet is like a message, with no name (unlike events) but with structure JSON data attached. It is automatically decoded by gevent-socketio.

    {"type": "json",
     "data": {"this": "is a json object"},
     "endpoint": "/chat"}

    {"type": "json",
     "data": {"this": "is a json object", "please": "reply"},
     "ack": True,
     "id": 5,
     "endpoint": "/chat"}

The same `ack` mechanics also apply for the `json` packet.

### The event packet

The event packet holds a `name` and some `args` as a list. They are taken as a list on the browser side (you can `socket.emit("event", many, parameters`) in the browser) and passed in as is.

    {"type": "event",
     "endpoint": "/chat",
     "name": "my_event",
     "args": []}

    {"type": "event",
     "endpoint": "/chat",
     "name": "my_event",
     "ack": True,
     "id": 123,
     "args": [{"my": "object"}, 2, "mystring"]}

The same ack semantics apply here as well.

[INSERT: mark the difference between when YOU create the packet, and when you receive it, and what you must do with it according to different ack values]

### The heartbeat packet

The heartbeat packet just marks the connection as alive for another amount of time.

    {"type": "heartbeat",
     "endpoint": ""}

This packet is for the global namespace (or empty namespace).

## Ack mechanics

The client sends a message of the sort:

    {"type": "message",
     "id": 140,
     "ack": True,
     "endpoint": "/tobi",
     "data": ''}

The ‘ack’ value is ‘true’, marking that we want an automatic ‘ack’ when it receives the packet. The Node.js version sends the ack itself, without any server-side code interaction. It dispatches the packet only after sending back an ack, so the ack isn’t really a reply. It’s just marking the server received it, but not if the event/message/json was properly processed.

The automated reply from such a request is:

    {"type": "ack",
     "ackId": 140,
     "endpoint": '',
     "args": []}

Where ‘ackId’ corresponds to the ‘id’ of the originating message. Upon reception of this ‘ack’ message, the client then looks in an object if there is a callback function to call associated with this message id (140). If so, runs it, otherwise, drops the packet.

There is a second way to ask for an ack, sending a packet like this:

    {"type": "event",
     "id": 1,
     "ack": "data",
     "endpoint": '',
     "name": 'tobi',
     "args": []}

    {"type": "json",
     "id": 1,
     "ack": "data",
     "endpoint": '',
     "data": {"a": "b"}}

and the same goes for a ‘message’ packet, which has the ‘ack’ equal to ‘data’. When the server receives such a packet, it dispatches the corresponding event (either the named event specified in an ‘event’ type packet, or ‘message’ or ‘json, if the type is so), and adds as a parameter, in addition to the ‘args’ passed by the event (or ‘data’ for ‘message’/’json’), the ack() function to call (it encloses the packet ‘id’ already). Any number of arguments passed to that ‘ack()’ function will be passed on to the client-side, and given as parameter on the client-side function.

That is the returning ‘ack’ message, with the data ready to be passed as arguments to the saved callback on the client side:

    {"type": "ack",
     "ackId": 12,
     "endpoint": '',
     "args": ['woot', 'wa']}

To learn more, see the test_packet.py test cases. It also shows the serialization that happens on the wire.

## Other module members

`socketio.packet.``decode`(rawstr, json_loads=<function default_json_loads>)

  Decode a rawstr packet arriving from the socket into a dict.

`socketio.packet.``encode`(data, json_dumps=<function default_json_dumps>)

  Encode an attribute dict into a byte string.