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
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.
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.
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
(The character count prefix is omitted in the following description.)
*services messageWhen 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
*enable messageWhen 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
*disable messageWhen 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
*quit messageThe *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
(The character count prefix is omitted in the following description.)
*services messageWhen 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.
*enable messageOnce 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
*quit messageThe *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.
*hostquit messageThe *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 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.
*enable and
*disable sent to Opera can't take multiple service
names, and so be consistent with the message sent from the client
to the proxy.