Transport protocol

This document defines the protocols by which Opera and debugging clients communicate via the debugging proxy using TCP/IP connections.

Version: 1.0 draft 1, 2006-07-04

Agents and channels

The communicating agents are "Opera", the "proxy", and the various debugging "clients". In addition, there are debugging "services" inside Opera on whose behalf Opera manages the communication. (See the architecture document for an overall description of the structure of the system.)

Opera and the clients connect to the proxy via bidirectional TCP/IP channels in arbitrary order at arbitrary times.

Only one Opera instance can be connected to the proxy at any one time. An arbitrary number of clients can be connected simultaneously.

Any agent can close any channel at any time without prior notice. When a channel is closed by the agent at one end, the agent at the other end should interpret this in exactly the same way as receiving a *quit message (see below).

Any received *quit message on a channel should be interpreted to mean that the channel on which it was received is closing, and the agent that sent the *quit should subsequently close its end of the channel.

General message format

All data communicated is Unicode character data encoded as UTF-16 in big-endian (network) byte order.

A message is comprised of a character count, a keyword, and arbitrary data:

    count keyword data

The count and keyword are followed by exactly one ASCII blank (0x0020). Note carefully that the blank is a terminator, not a separator.

The count is comprised of a sequence of characters in the ASCII numerals range (0x0030 through 0x0039) and represents a base-10 number that gives the length of the message, not counting the characters of the count field or the count field's terminating blank character. Leading zeroes are prohibited. The length of the count is at most 10 characters, and its value is at most 231-1.

Keywords are either reserved words, which all start with an ASCII asterisk character (0x002A), or names of debugging services. Keywords may not contain the ASCII comma character (0x002C) but are otherwise unrestricted.

Message flow overview

This schema provides an overall view of message flow between the agents. More information is given in the following description of the messages.

            Opera              proxy                 client

*services     ---------------->
                                    ----------------->   *services
                                    <-----------------   *enable
*enable       <----------------
data          <--------------------------------------->  data
                                ....
                                    <------------------  *quit
*disable      <----------------
*quit         ---------------->
                                    ------------------>  *hostquit
                                    ------------------>  *quit

Control messages: Opera/proxy protocol

(The character count prefix is omitted in the following description.)

To proxy: *services message

When Opera makes a successful connection to the proxy it sends a single message:

    *services <service-names>

Here <service-names> is a comma-separated list (with no embedded blanks) of names of services provided by the debuggers built into Opera.

For example, if Opera is configured with the HTTP logger and the URL player, it would send:

    *services http-logger,url-player

To Opera: *enable message

When the proxy wants to activate a debugging service in Opera (which happens when the first client asks for the service) it sends one message per service:

    *enable <service-name>

Here <service-name> is the name of the service to enable. For example, to enable the HTTP logger it sends this:

    *enable http-logger

To Opera: *disable message

When the proxy wants to deactivate a debugging service in Opera (which happens when the last client using the service has quit) it sends one message per service:

    *disable <service-name>

Here <service-name> is the name of the service to disable. For example, to disable the HTTP logger it sends this:

    *disable http-logger

To either: *quit message

The *quit message is sent to Opera when the proxy terminates operation. No communication with the proxy will be possible once it has sent the *quit message. When Opera receives this message it should disable all debugging services that are currently enabled.

The *quit message is also sent by Opera to the proxy when Opera terminates operation. No communication with Opera is possible once Opera has sent the *quit message. When the proxy receives this message it broadcasts *hostquit to all of its clients.

The message consists simply of the keyword:

    *quit

Control messages: Client/proxy protocol

(The character count prefix is omitted in the following description.)

To client: *services message

When the client connects to the proxy it does not send anything, but waits for a *services message from the proxy.

The format of the message is as for the Opera/proxy case.

To proxy: *enable message

Once the client has received the list of services and has determined that the services it needs to interact with is on the list, it sends an *enable message to the proxy to enable all the services it needs:

    *enable <service-names>

Here <service-names> is a comma-separated list of service names.

This message has a secondary effect: it causes the proxy to forward all data messages bearing that service name to the client.

For example, if the client wishes to enable the console logger and the JavaScript debugger, and receive data traffic for those services, it would send:

    *enable console-logger,javascript-debugger

To either: *quit message

The *quit message is sent from the proxy to a client to signify that the proxy is about to terminate, and that the client should disconnect from the proxy.

The *quit message is also sent from the client to the proxy to signify that the client is terminating. The proxy will then send *disable messages to Opera for all services for which the quitting client was the last active client.

The format of the message is the same as for the Opera/proxy case.

To client: *hostquit message

The *hostquit message is sent from the proxy to a client to signify that Opera is about to terminate.

The client may keep the connection to the proxy, waiting for a new *services message when a new Opera instance connects.

The format of the message is the same as for the Opera/proxy case.

Data messages

Data messages carry traffic between a debugging client and a debugging service inside Opera, and can be sent by either side. They take the form of a service name followed by arbitrary data:

    <service-name> <data>

For example, the HTTP logger service might send messages that look like this:

    http-logger 0x00371548 3 HTTP/1.0 ...

The proxy performs routing of messages from Opera to the clients: any client having asked to enable the service whose name appears in a message from Opera, will receive that message.

Issues / thoughts

Bugs