Hexajuice interface

myeisha edited this page Jan 26, 2015 · 1 revision

Overview

Hexajuice is a utility that turns actions and notifications in a hexabus network into a stream of JSON object an vice versa. Currently, all operations supported by libhexabus Sockets and Listeners are supported, with the exception of asynchronous error delivery and packet stream filtering.

Hexajuice takes a stream of JSON objects as input, each object on its own line, and gives a stream of JSON objects as output, again each on its own line. Input lines describe actions to execute (such as sending packets or manipulating sockets), while output lines describe responses to such actions.

This page describes only the input and output format of hexajuice and their mapping to the hexabus protocol. As such, knowledge of the hexabus protocol is required to understand this page.

Input format

Each command to hexajuice must be given as a JSON object, with one object per line of input. A command always contains a command field which, unsurprisingly, identifies the command to execute.

Fields of the same name always have the same meaning and the same format.

Data types for fields

All fields are typed, and while the JSON datatype of a field is not fixed, the string representation of a value must be a valid value for the type of the field.

Types used by hexajuice are:

  • string: any string
  • uintN: unsigned integer. Value must be in [0, 2^N - 1]
  • bool: 0 or 1
  • hxb_datatype: any datatype string hexaswitch accepts as valid
  • T[]: JSON array with elements of type T

Types for hxb_datatype values

  • UIntN, uN: uintN
  • IntN, sN: intN
  • Bool, b: bool
  • Binary(N), bN: uint8[N]
  • String, s: string (length limit: 127 bytes)
  • Float, f: number

List of fields

  • command: string. Command to execute.
  • interface: string. Name of a valid network interface.
  • socket: string. Opaque name used to identify a socket.
  • address, to: string or object{ip: string, port:uint16}
  • packet: object. See below under Format of input packets

Sockets

Many commands require or allow a socket argument. Commands that allow (but not require) the socket argument will use a default socket when the argument is not given. This socket will be implicitly opened on first use. When socket is specified in the command, the named socket must be open.

Command listen

Required fields: interface

Allows reception of multicast packets from a hexabus network on interface. While at least one listen command is active, received multicast packets will be printed to the output stream on reception.

Command ignore

Required fields: interface

Cancels the effect of a previous listen command.

Command open

Required fields: socket

Opens a hexabus socket and identifies it as socket for further use. No socket of the same name may exist.

Command close

Required fields: socket

Closes the identified socket.

Command mcast_from

Required fields: interface

Optional fields: socket (default: "")

Instructs the system to use interface the outgoing interfaces for multicast packets sent from socket.

Command bind

Required fields: address

Optional fields: socket (default: "")

Binds the socket to the given address and port. When address is a string, the socket will be bound to a random, previously unused port.

Command send

*Required fields:packet`

Optional fields: socket (default: ""), to (default: {"ip": "ff05::205", "port": 61616})

Sends the given packet to destination to using socket socket.

Command quit

Quits the program.

Format of input packets

Input packets must always contain a type field that determines the packet type, presence of other fields depends on the type. All packets may contain a flags field of type uint8 (default: 0). No flags are currently used.

Type error (HXB_PTYPE_ERROR)

Required fields: code (uint8)

Type query (HXB_PTYPE_QUERY)

Required fields: eid (uint32)

Type epquery (HXB_PTYPE_EPQUERY)

Required fields: eid (uint32)

Type epinfo (HXB_PTYPE_EPINFO)

Required fields: eid (uint32), datatype (hxb_datatype), value (string)

Type info (HXB_PTYPE_INFO)

Required fields: eid (uint32), datatype (hxb_datatype), value (type for datatype)

Type write (HXB_PTYPE_WRITE)

Required fields: eid (uint32), datatype (hxb_datatype), value (type for datatype)

Format of output packets

The format of output packets is an extension of the format used for input packets. Additionally to all fields listed for input packets (with their defaults explicitly given), output packets also contain a from field of type object{ip: string, port: uint16}.

Unicast packets received on a socket will contain an additional field socket that identifies the socket the packets was received on. Multicast packets will not contain this field, distinguishing multicast packets from unicast packets.

Error output format

When a command cannot be executed successfully, a error line is generated. Error lines are object with a key error of object type that further explains the error that occured. All such error objects contain a field type that broadly classifies the type of error.

Type invalid input

Something in the input was incorrect. Contains a descriptive string in diag. If not the entire input was incorrect, field will contain the name of the field that was found to be incorrect.

Type system error

The system produced an error during network operations. Contains fields category, code and message with system-dependent contents.

Type unknown

All other errors. Contains a descriptive string in diag, if one is available.

Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.