Introduction

Tio protocol is simple and inspired by the memcached protocol, as we can see in the following telnet/nc session (just note ">>" prefix sent data, it's not part of the protocol):

>> ping abc
answer ok PONG abc
>> create test volatile_list
answer ok handle 1
>> get_count 1
answer ok count 0
>> push_back 1 value string 3
>> abc
answer ok
>> push_back 1 value string 9
>> hello tio
answer ok
>> get_count 1
answer ok count 2
>> get 1 key int 1
>> 0
answer ok data key int 1 value string 3
0
abc
>> get 1 key int 1
>> 1
answer ok data key int 1 value string 9
1
hello tio

** reconnect **

>> open teste
answer error key not found
>> open test
answer ok handle 1
>> subscribe 1 0
answer ok
event 1 push_back value string 3
abc
event 1 push_back value string 9
hello tio
>> push_bac
answer error invalid command
>> push_back 1 value
answer error Invalid parameter count
>> push_back 1 value string 4
>> xpto
event 1 push_back value string 4
xpto
answer ok
>> get 1 key int 2
>> -1
answer ok data key int 2 value string 4
2
xpto
>> subscribe 1
answer error already subscribed
>> unsubscribe 1
answer ok
>> subscribe 1
answer ok
>> delete 1 key int 1
>> 0
event 1 delete key int 1
0
answer ok

Basics

• All commands follow the pattern <command> <parameters> and are terminated by a "\r\n" or "\n"
• Protocol also expects "\r\n" after data sent on data commands, like push_back. Actually, it expects two more chars, you can add everything. If you're using netcat instead telnet like I do, you will need to press enter twice to send "\n\n".
• Volatile containers survive reconnections, but don't survive a Tio restart.
• Subscribe command has an optional second parameter used to inform the index to start the transmission. If you don't send this parameters, the behavior depends on the container you are using. When using maps, you will receive a "set" event for each existent item. If it's a list or vector, you will not receive current items if subscribing with no args.
• You can access index based containers (like lists) using negative indexes, just like in Python language. -1 points to the last member, -2 to the item before the last, and so on. You can use this when subscribing to lists too.

Data Model

Every item on a container has three fields: key, value and metadata. Value and metadata are set by the user. The key field interpretation depends on the container:

• Lists and vectors: key is the item index, and can't be changed
• Maps: the key is (surprise!), the item key. Maps only support string keys, but you can access them using a integer index

Simple Commands

syntax: command_name <required parameters> [optional parameter]

>> create <name> <type>

answer ok <handle>

Create a container, or open if it already exists. Note you can inform a real type (like volatile_map) or an type alias (create using the --alias command line parameter)

>> open <name> [type]

answer ok <handle>

Open an existing container. The "type" parameters is optional, you can open a container without knowing its type

Data Commands

The data commands syntax follow the following pattern:

>> command_name <handle> [<key | value | metadata> <data_type> <data_size>]... ? >> \r\n

>> [data for field 1]

>> [data for field 2]

>> [data for field 3]

Data type can be "string", "int", "double" or "raw". Data size is the byte count of data sent via the socket. The size of a int field with value 10 will be 2, since the protocol is ascii only.

example_command (<list of supported fields>): explanation

get (key): get the item having the informed key. The key can be returned too if it's different from the informed key (if you access a list using a negative index, you'll receive the positive index)

push_back (value, metadata): add an item to the end of the container

push_front (value, metadata): add an item to the beginning of the container

set (key, value, metadata): change an item value

insert (key, value, metadata): if the container is a list, insert an item at the index key. If it's a map, insert the item or return an error if the item already exists

delete (key): delete the item having the informed key

pop_back: return the last item in the container and deletes it

pop_front: return the first item in the container and deletes it

Examples

>> push_back 1 value string 3

>> abc

answer ok

>> set 1 key string 3 value int 2 metadata double 6

>> abc

>> 10

>> 3.1415

answer ok

>> get 1 key string 3

>> abc

answer ok data key string 3 value int 2 metadata double 6

abc

10

3.1415

>> get 1 key string 3

>> ABC

answer error key not found