The proxy provides an HTTP interface. Clients written in HTML+JS running inside web browsers use XMLHttpRequest to interact with Opera via the debugging proxy.
The main points:
The proxy listens for HTTP requests on port 8002 by default.
Requests to the proxy encode the desired operation in the path part of the GET or POST request. For example, a GET of "/services" retrieves a list of configured services, a GET of "/ecmascript-logger" retrieves the next available script logger datum, and a POST to "/ecmascript-logger" can send commands to that service.
If no data are available to return to the client when the request comes in, the proxy will keep the client waiting for some short time (20 seconds; experimental) before sending a timeout response, prompting the client to try again.
All data transmitted in a POST, and all data returned by either GET or POST, are on XML format.
A client library in "http-clients/clientlib.js" encapsulates much of the common functionality described below, like getting and enabling specific services and handling retries in the face of timeouts.
Because the tool clients are regular HTML+JS pages the normal security restrictions on XMLHttpRequest apply: XMLHttpRequest can only access the host and port from which the containing page was loaded. We work around this by loading the source for the tool client not from a file: URL but via the web server in the proxy. This is a hack, but it's adequate.
When the proxy is started it accepts a command line argument that names the directory from which to load tools. By default this is "../http-clients", so if you start the proxy from the "proxy/" directory in the source tree it will find the example tools. For your own use you can set things up differently, obviously.
Requests to the web server starting with the string "/file/" are served from the proxy's file directory.
All files served by the web server in the proxy are marked "no-cache", so it's pretty straightforward to experiment with tool ideas.
PLEASE NOTE that the way the client library interacts with the web server usually prevents simply reloading the web page containing the tool client. Instead you must close the tab and open a new tab with the tool client URL to reload the client. No doubt this can (and should) be fixed somehow.
The HTTP service is stateless and at this time the proxy has no support for cookies or session identifiers. There are some consequences of this.
There can only be a single client for a particular service through the HTTP interface. The proxy keeps an internal queue of data to be sent to HTTP clients for a service, and the first client to ask for a datum will get it. Thus any particular client will only see some of the data if multiple clients access the same service on the proxy.
Any "enable" message for a service will clear any backlog of messages for that service, because it is assuming that the client has restarted.
Since the HTTP protocol is stateless, a client that just disappears can't be detected (eg by a socket closing). The proxy will prevent a backlog of data by limiting the queue of unconsumed data in the proxy to some reasonable size (maybe 1000 items).
As a general rule the server returns "200 - OK", along with appropriate data.
Requests return <ok/> if they have no other data to provide.
Requests return <error/> on various kinds of error; sometimes that element may have a payload that details the error.
If Opera shuts down, any GET or POST request to an open service will result in a <quit/> message. When that message has been sent the service will be disabled and has to be re-enabled when Opera has restarted.
The client first reads the /services resource to obtain the list of available services:
GET /services
The response is an XML structure on the format:
<services>
<service name="service-name" />
...
</services>
If the desired service is available, the client enables it by accessing the service name in the /enable "directory", e.g.
GET /enable/http-logger
The response is <error/> if the service does not exist, otherwise <ok/>.
Data are read by posting simple GET requests with the name of the service as the path argument:
GET /http-logger
The response is normally the standard XML structure for the service.
If the service for some reason is not available, or can't deliver data in the timeout period, a <timeout/> response is delivered instead. The client should normally consider retrying the request.
Any response code other than 200 means the request failed.
Data are written by POST requests; the posted data must have XML format. The data should not have a "<?xml ... >" header, as this header is added by the proxy if necessary.
POST /ecmascript-logger <set-parameters reformat="yes" />
The response is always immediate and is either <ok/> or <error/>. A separate GET must be used to read returned data.
Files can be read from the server by accessing them under the virtual "/file" service:
GET /file/script-logger.html
Note this does not imply that the files should actually be located in a directory called "/file", this is just syntax to trigger special behavior in the web server.