XINA API

From 699wiki
Jump to navigation Jump to search

The XINA API provides direct access to the XINA server.

XINA Tunnel

XINA Tunnel is a Java application which provides a bridge between application(s) using the XINA API and the XINA server.

To access the XINA server, the user must first launch the XINA Tunnel application, which will prompt the user to log in to the XINA server. Once this step is completed XINA Tunnel launches a local server, which provides a tunnel to the XINA server. Applications implementing the XINA API may then open a standard TCP connection to XINA Tunnel and begin communicating with the XINA server.

XProtocol

XProtocol is the TCP protocol used to communicate with the XINA server.

XProtocol is designed to be simple and easy to implement. It uses a basic data encoding method which can be parsed in-place as a stream is read. All communication takes place in the form of UTF-8 encoded strings. The strings are encoded in tokens of the following format:

token type: one byte ASCII character indicating the token type
header prefix length: one byte ASCII digit indicating length of the prefix in bytes
header prefix: ASCII digits indicating the length of the header string in bytes
header: UTF-8 encoded string of (header prefix count) bytes
prefix length: one byte ASCII digit indicating length of the prefix in bytes
prefix: ASCII digits indicating the length of the string in bytes
string: UTF-8 encoded string of (prefix count) bytes

For example:

14cake = "cake"
213big hamburger = "big hamburger"

The maximum allowed length of a single token is 4MB (4,194,304 bytes). A token may also be empty, which can be denoted with either the prefix "10" or the shorthand prefix "0".

There are also special code tokens, which do not contain data. They are transmitted by replacing the prefix length byte with a single ASCII character. There are currently three code tokens:

  • END - 'E' (0x45) - marks the end of a command, explained below
  • CANCEL - 'C' (0x43) - cancels a command, explained below
  • CLOSE - 'X' (0x58) - closes the connection with XINA Tunnel

Initialization

When an application opens a connection with the XINA Tunnel, it must first send a single token containing an XProtocol initialization JSON object:

{
 "version": "2.1"
}

Currently the only attribute for this object is the XProtocol version number, which is currently 2.1. More attributes will be added in the future. The XINA Tunnel will then respond with an XProtocol status JSON object indicating if the initialization is accepted. If it is not, the connection will then be closed by XINA Tunnel. If it is accepted the application may then begin sending XProtocol commands.

Command Structure

The bulk of the XProtocol syntax consists of a collection of discrete actions. Actions are fully transactional; any changes performed by an action must all be successful or no changes will be committed.

Action

Each action is encoded as a single JSON object, which is sent in a single token. The format of each action is detailed below. In general each action has the basic form:

{
 "action": <string>,
 "meta":   <object> (optional)
 ...
}

The value of the action key determines the rest of the format of the object.

The meta key is reserved for action metadata. There is currently no standard format for this object.

Binary Data

After the action token a client may send one or more binary data objects. Each object must be preceded by a JSON header object in the following format:

{
 "object_id": <string>
}

This is followed by the actual binary data. To support files larger than the token limit of 4MB, files must be split into bins of 4MB or less. These are delimited using additional JSON objects with the format:

{
 "done": <boolean>
}

Note:

  • not all actions require binary objects
  • binary objects do not need to be provided in any particular order
  • each binary object object_id must be unique in the current action
  • all binary objects referenced in the action must be provided

Completion

After any binary objects are sent, the client must send an END token to signal the server to execute the command. At any time before sending the END the client may send a CANCEL token to cancel the current action, and the server will reset and wait for a new action.

For example, an action with two file objects, with one file greater than 4MB in size, would require the following tokens:

  • { <action> }
  • { "object_id": "small_file" }
  • <binary data>
  • { "done": true }
  • { "object_id": "big_file" }
  • <binary data>
  • { "done": false }
  • <binary data>
  • { "done": true }
  • END

Status

After an END or CANCEL token is received, the server will respond with a status token in the following format:

{
 "type": <"OK" or "ER">,
 "code": <int>,
 "message": <string>
}

The type attribute indicates if the command was executed successfully. The status code is a numeric value which provides a more specific status of the action. The message token provides additional information about the status (it may be null). Status codes are loosely based on HTTP status codes. A full list is available at the end of this document.

Note that the server may send an error status message before the full command has been submitted, because the command is parsed as it is received. If this occurs the server will then wait until an END or CANCEL token is received, and then begin waiting for the next command. This allows an asynchronous client to cancel a command which is erroneous before sending the entire command, which can be beneficial for very long commands (such as those containing file data).

Response

Most actions do not return a response, and the server will return to listening after sending the status for the next action.

Actions which do return a response will only do so if the status message was OK.

Syntax

Common Elements

Structure Actions

Data Actions

Administrative Actions