		The InSyTrack protocol, version 1





 This document is created for protocol implementators (of alternative
implementations than the one provided with the InSyTrack software) and
for those who wish to understand how InSyTrack works at the network level.

 Users who wish to use the implementation provided with the InSyTrack
software should instead read the texinfo & man documentation and perhaps
the respective C header files.



1. Connection establishment
   ========================

 Version 1 of the InSyTrack protocol is uni-directional: the clients
only produce data, while the server only receives data.
 To establish a connection using InSyTrack protocol, a simple network
connect() call on the client side is enough. The connection handshake
performed by the lower network layers is enough.


2. Negotiation of the protocol and capabilities.
   =============================================

 There is none. Transmitting InSyTrack datagrams may begin immediately
after establishing a connection.


3. Format of the InSyTrack datagrams
   =================================

 Each datagram consists of six fields:
	- the InSyTrack start-of-message marker
	- the type of the InSyTrack datagram
	- the length of the message ID (flow ID)
	- the length of the message body
	- the message ID (flow ID)
	- the message body

 These fields are described in more detail in the details of particular
datagrams below.

  * the ID usage mark datagram
    __________________________

	a. The InSyTrack start-of-message marker
	   -------------------------------------

    This marker is a four-byte value of 0xBDBDBDBD (BDBDBDBD hexadecimal),
    transmitted in any order.

	b. The type of the InSyTrack datagram
	   ----------------------------------

    This field is a two-byte value of this message's type:
	- INSYTRACK_MESSAGE_DATA, value = 0
    The two bytes are transmitted in network byte order (big-endian), so the
    high-order byte is transmitted first.

	c. The length of the message ID (flow ID)
	   --------------------------------------

    This two-byte field contains the length of the message ID to be reported
    (marked). The number is received as unsigned (i.e. no sign bits).
    The two bytes are transmitted in network byte order (big-endian), so the
    high-order byte is transmitted first.

	d. The length of the message body
	   ------------------------------

    This two-byte field contains the length of the message body (any additional
    information to be passed with the flow ID, like the location where the mark
    occurred etc.). The number is received as unsigned (i.e. no sign bits).
    The two bytes are transmitted in network byte order (big-endian), so the
    high-order byte is transmitted first.

	e. The message ID (flow ID)
	   ------------------------

    This field can be from 0 to 65535 bytes long, inclusive, and can contain
    any arbitrary user-provided data that should be processed by the server
    as the message/flow ID (can contain both printable and non-printable
    characters).

	f. The message body
	   ----------------

    This field can be from 0 to 65535 bytes long, inclusive, and can contain
    any arbitrary user-provided data that should be processed by the server
    as the message body (can contain both printable and non-printable
    characters to be processed as any additional data that was sent with
    the given message/flow ID, including being discarded).

  * the ID last usage mark datagram
    _______________________________

    All fields are the same as in the "ID usage mark datagram", except for
    the type of the InSyTrack datagram:

	b. The type of the InSyTrack datagram
	   ----------------------------------

    This field is a two-byte value of this message's type:
	- INSYTRACK_MESSAGE_LAST, value = 1
    The two bytes are transmitted in network byte order (big-endian), so the
    high-order byte is transmitted first.

4. Recommendations
   ===============

 This section contains recommendations about the various elements of the
protocol. This section is not required for understanding the InSyTrack
protocol or implementing InSyTrack clients or servers.

 a. Short message/flow ID and body
    ------------------------------

  Keep the ID and body of the message reasonably short. Marking a usage of
  an ID is synchronous (blocking), so the longer they are, the longer it takes
  to transmit them. This can disrupt the timings of the flow being analyzed.

 b. Reliable network protocol
    -------------------------

  A reliable transmission protocol should be used so that no usage marks are
  lost or incorrectly retransmitted. The reasonable default is the TCP
  protocol. UDP and other protocols still can be used, if required.

 c. Printable message ID and body (ASCII)
    -------------------------------------

  When implementing an InSyTrack client, use message IDs any bodies consisting
  only of printable characters as there is no guarantee what the server does
  with the message. If the server prints the messages to the terminal, sending
  non-printable characters (especially the terminal control sequences) can
  mess up the terminal on the receiving side. Sending start-of-message markers
  inside the message ID or body can mess up the queue on the server.
  UUIDs converted to a printable form are a good example of both a unique
  and printable ID.

 d. Use the start-of-message marker only to verify the start of the next
    message, not to find it
    --------------------------------------------------------------------

  Don't search for the start-of-message marker in the incoming data as the
  marker could be a part of the message ID or body (by recommendation (c) it
  shouldn't, but this is not prohibited), so interpretting the bytes after it
  can give incorrect results. Instead, use the length values contained in
  the message to process the message and check if the start-of-message marker
  is present immediately after. If it is not, skip as many bytes as needed
  to find the next message.

 e. Don't send any data between messages
    ------------------------------------

  Don't send more data than the message should take. The message should take
  exactly 4+2+2+2 bytes + the length of the message ID + the length of the
  message body and should be immediately followed by the next message (by its
  start-of-message marker). Badly formed data can mess up the receiving side.


