RemoteFile v1.0

RemoteFile is a message-based data protocol used by two sides in a point-to-point communication link (e.g. in a socket connection). It’s primary use case is to act as the application layer of an active APX session.

After connection setup, the protocol is fully bidirectional (This is not a traditional request-response protocol) which means that data can be written at any time by both sides.

Each side of the connection maintains a 1GB block of virtual memory. This is called the local address space. Each byte in this memory can be addressed as 0-1073741823 and is of unsigned type (value 0-255).

In addition to the local 1GB address space, each side also maintains another 1GB block of virtual memory. This is called the remote memory. The last 1KB (1024 bytes) of this address space is reserved and is called the control area.

The basic principle behind RemoteFile is about continous data synchronization (or data mirroring). When a byte is updated in local memory at end-point A, the change is reflected into the remote memory at end-point B (transmitted as a write operation from A to B). Likewise, any change in B’s local memory is reflected to A’s remote memory (transmitted as write operation from B to A).

Each side of the connection can only perform a single operation on the opened socket (or other point-to-point communication link).

---

Example:

Write(0x10,2,[5,6])

Writes two bytes at start address 0x10. After operation is complete the byte at address 16 contains value 5 and the next byte contains value 6.

---

Files

Rule #1:

A memory write to an address outside the control area is illegal, unless:

1. A file exists in that address range.
2. The file mapped in that range has been previousy opened by remote connection end-point.

Directly after connection is established, the remote memory is empty except for the 1KB control area. Before write operations can take place a file must be mapped into the remote memory address space.

A file in RemoteFile is simply a byte-array that is mapped to a start-address somewhere in the 1GB memory range.

Each file has:

• A (file) name
• A start-address (where it is mapped)
• A size in bytes

Creating a new file is done by sending a special command to the control area. The remote side (of the connection) processes the command and can at that point take a decision to either:

• Open the file
• Not open the file.

In case the file is opened, the remote side sends a File Open command back to the local side of the connection containing the start-address of the file (The start-address is the unique identifier of a file). Local side then responds by sending the complete content of the file (done using a single write operation). After initial file write, only the deltas (or data changes) are transmitted (updating individual byte or bytes).

RemoteFile Messages

All communication is message-based, each message has two components:

1. A message header, containing the length of the message.
2. A message body, containing the message data (also known as message payload).

Since RemoteFile is designed to be used on any communication link it does not officially define a message header since there usually exists protocols for this already.

In case you are communicating over a socket (or other stream-based communication) you can use NumHeader as the message header protocol. If you plan to use RemoteFile on TCP then NumHeader32 is the recommended choice.

RemoteFile Greeting Header

The very first message a client sends to server is the greeting. It’s similar in concept to the HTTP header. It consists of a single message (see above) where the payload is a multi-line text string. (This is the only text message defined in the protocol.)

The first line of the message is:

RMFP/1.0\n

After the first line, a set of key-value attributes can be set by the client (Similar to MIME-headers) Each line of the message ends with a single newline character (unlike TCP which uses \r\n). In addition, the message must end with a single new-line character.

Example:

RMFP/1.0\n\n

The total length of the header message must not be longer than 127 bytes. This is because the short-form of both NumHeader16 and NumHeader32 are identical. This means the the message header (message size) can be a single byte in both cases. What NumHeader format is actually used by the client is specified in the greeting header.

Greeting attributes

NumHeader Attribute

The NumHeader attribute specifies if 16-bit or 32-bit header is being used on consecutive messages from the client.

Example:

RMFP/1.0\nNumHeader: 32\n\n

Binary Messages

After the greeting header is sent/received, the only allowed operation is writing data into remote memory using binary messages.

Each write message contains two parts (of the message payload):

1. Address Header (integer)
2. Data Buffer (byte-array)

The length of the data buffer is determined by subtracting the length of the address header from the total message length (extracted from the message header).

When combined with the NumHeader protocol there are four different scenarios that can occur.

The Address Header

The address header can have two forms:

1. Low — Uses 2 bytes
2. High — USes 4 bytes

AddressHeader - Low address form (0-16383):

AddressHeader - High address form (0-0x3FFFFFFF):

AddressHeader Flags

HIGH_BIT

When set to 0, the AddressHeader occupies 2 bytes and uses a 14-bit address range (0-16383).

When set to 1, the AddressHeader occupies 4 bytes and uses a 30-bit address range (16384-1073741823).

In both cases the address value is encoded as big endian.

---

NOTE

Files whose data change frequently should be mapped to the first 16KB range. Files that change rarely (or not at all) can be mapped anywhere else.

---

MORE_BIT

This is used for message fragmentation. The bit is set to 1 as long as there is more data to send (from the same write operation). The very last packet in the write operation should have its more bit set to zero to mark end of operation.

Upper application layers should not be notified until an entire write operation has been received (MORE_BIT=0).

RemoteFile Header Examples

Short Length & Low Address

Long Length & Low Address

NumHeader16

NumHeader32

Short Length & High Address

Long Length & High Address

NumHeader16

NumHeader32

The Control Area

The last 1KB (1024 bytes) of the 1GB address range is a special control area. Writing data here means you are sending control commands to the remote side (the owner of that memory area). The memory range of this area is 0x3FFFFC00 - 0x3FFFFFFF.

This special control area is used for:

• Creating and revoking files.
• Opening and closing files.

Control Commands

The start address is always 0x3FFFFC00 which is the first byte of the area. The format and length of each control command is found below. Note that the length of any command must never exceed 1024 bytes.

In this version of the protocol most integers are encoded as little endian (will be more generic in a future version). When an integer is encoded as little endian the type ends with the letters “LE”. As an example, the designation U32LE means unsigned 32-bit integer encoded as little endian.

CmdType

The command type is a 32-bit unsigned integer which uniquely identifes what type of command has been encoded.

Acknowledge Command

The acknowledge command can be used as a response to previously received command.

Negative Acknowledge Command

The negative acknowledge command can be used as a response to previously received command.

FileInfo Command

Both sides of the communication link sends zero or more FileInfo commands (one per file) informing the other side which files it currently has available (mapped into memory). The length of the struct is 48 bytes + the length of the file name which is the last part of the struct.

Since the longest message that can be sent to the special file area is 1024 bytes, the longest possible file name is 975 bytes (1 byte reserved for the null terminator).

FileType

DigestType

Example:

Multiple FileInfo structs

It’s allowed to send multiple FileInfo structs in a single control command (as long as the 1024 limit is not exceeded). In this case, only the first struct holds the CmdType field meaning that StartAddress of the next file is found right after the null-terminator of the file name of previous file.

Note that support for multiple FileInfos is not yet implemented in c-apx as of v0.3.0.

FileRevoke Command

The file revoke command is the opposite of FileInfo. It unmaps the file from the memory map. If remote side had the file open it’s automatically closed.

Heartbeat Commands

A client can check if the underlying connection (e.g. socket) is alive by sending a heartbeat request to server. The server then replies back with a heartbeat response.

Request:

Response:

Ping Commands

A ping command is a more sophisticated form of heartbeat. The initator takes a timestamp which is sent in request. The same timestamp is echoed back in the response. In addition, a specific (memory mapped) file can be picked as the target of the ping. This can be used in a future implementation to relay pings from client to client. Use the special file address 0xFFFFFFFF if you don’t want to target a specific file.

Request:

Response:

File Open/Close Commands

After a FileInfo struct has been received you can choose to open the file by sending back a file open command. The file to open is identified by the start address from previously received FileInfo.

FileOpen:

FileClose:

It’s an illegal operation to open/close a file before corresponding FileInfo struct has been received.