HTTPD interface to the proxy

Introduction

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:

See the documentation in the client library for more information. The directory "http-clients/" also contains example clients, see eg "script-logger.html".

Practical issues of using HTML+JS tools

Security restrictions

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.

Issues with stateless service

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.

Single client

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.

Auto-disabling of service

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).

General responses

Response codes

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.

Configuring a service

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/>.

Reading data

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.

Writing data

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.

Reading files

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.