Packets

Crossfire packets contain a content length header with key Content-Length: followed by the number of characters (in decimal) contained in the packet body. The packet body is a UTF-8 string containing a JSON-formatted object. A packet's header and body is separated by a double CRLF (\r\n\r\n), and its body is terminated by a CRLF (\r\n).

Packet Format

At a minimum, all packet bodies contain the following values:

type string

The packet type, one of request, response or event.

seq number

The packet's sequence number, relative to other packets of the same type.

contextId string

The id of the packet's source or destination [context](#wiki-context). Packets without a specific source or destination context can either omit this argument or can include it with a value of null.

Example packet with type 'request':

Content-Length:69
\r\n\r\n
{
  "contextId":null,
  "type":"request",
  "seq":1,
  "command":"listcontexts"
}
\r\n

Request Packets

Request packets are sent from a client to a Crossfire server. They extend the basic packet format with the following additional values:

command string

The [command](#wiki-commands) name.

arguments object

The command-specific arguments accompanying the request.

Example:

Content-Length:219
\r\n\r\n
{
  "type":"request",
  "command":"setbreakpoint",
  "contextId":"http://localhost:8080/test.html",
  "seq":21,
  "arguments": { 
                 "position":0,
                 "enabled":true,
                 "target":"http://localhost:8080/test/some_javascript.js",
                 "line":9,
                 "ignoreCount":0,
                 "type":"line"
               }
}
\r\n

Response Packets

Response packets are sent from a Crossfire server to a client in response to a previous request packet. Even in the event of a failure to process a request, a response packet will be sent with the corresponding error code and any applicable details.

All responses extend the basic packet format with the following additional values:

command string

The [command](#wiki-commands) name.

requestSeq number

The sequence number of the original request.

body object

The command-specific values accompanying the response.

status object

Information about the success/failure of performing the request, and the server's resulting state.

The status object contains the following values:

code number

One of the following result codes:

• CODE_OK = 0
• CODE_MALFORMED_PACKET = 1 - the packet failed basic validation: bad form, missing directives, etc.
• CODE_MALFORMED_REQUEST = 2 - the request failed validation: did not have the "request" attribute, malformed arguments, etc
• CODE_COMMAND_NOT_IMPLEMENTED = 3 - the requested command does not exist in the server
• CODE_INVALID_ARGUMENT = 4 - one (or more) of the arguments specified with the request do not apply to the request made
• CODE_UNEXPECTED_EXCEPTION = 5 - an exception occurred processing the request, details are provided in the response
• CODE_COMMAND_FAILED = 6 - the command failed during processing unlike CODE_UNEXPECTED_EXCEPTION this would have a known cause
• CODE_INVALID_STATE = 7 - the server is in an invalid state to process the command, for example sending a continue request to a running server

running boolean

Indicates whether JavaScript is currently running on the server (as opposed to being suspended).

message string

A human-readable message, typically used to describe the cause of a failure.

stackTrace string

A human-readable stack trace, typically used to show information about an error that has occurred.

Example:

Content-Length:80
\r\n\r\n
{
  "type":"response",
  "command":"listcontexts",
  "contextId":"xf0.1a::9931113",
  "seq":2,
  "request_seq":1,
  "running":true,
  "success":true,
  "body":{
           "contexts":["http://localhost:8080/test.html"]
         }
}
\r\n

Event Packets

Event packets are sent from a Crossfire server to a client to communicate a server-initiated event. They extend the basic packet format with the following additional values:

event string

The [Event](#wiki-events) name.

body object

The event-specific values accompanying the event.

**Example:**

Content-Length:122
\r\n\r\n
{
  "type":"event",
  "event":"onContextCreated",
  "contextId":"xf0.1a::9931113",
  "seq":5,
  "body":{
           "href":"http://www.google.ca/"
         }
}