bitowl
You can send any message with owl, bitowl! Compact communication protocol with version control and data verify.
Methods
let bitowl = require('bitowl');
There is a three sub modules:
bitowl.string
bitowl.data
bitowl.diff
Data
pack
let buffer = bitowl.data.pack(object);
unpack
let json = bitowl.data.unpack(bufferOrHex);
String
pack
let buffer = bitowl.string.pack(object);
unpack
let json = bitowl.string.unpack(bufferOrHex);
create diff
Create stringdiff object difference between string and sourcestring, output can be buffer or empty, by default return json
let json = bitowl.string.create(string, sourcestring, output);
apply diff
Apply diff to string and return new string. Diff can be hex, buffer or json
let str = bitowl.string.apply(diff, string);
Diff
pack
let buffer = bitowl.diff.pack(object);
unpack
Offset define where in buffer starts diff. By default offset is 0.
let json = bitowl.diff.unpack(bufferOrHex, offset);
create Diff
Create diff object difference between object and sourceobject, output can be buffer or empty, by default return json
let json = bitowl.diff.create(object, sourceobject, output);
apply Diff
Apply diff to sourceobject and return new object. Diff can be hex, buffer or json
let obj = bitowl.diff.apply(diff, sourceobject);
toData
This method apply diff to a empty object. It create object from diff. Warning! Can not convert diffstring to a string, so string fields is not apply to object.
Diff can be hex, buffer or json. Return json by default, if output == 'buffer' - return buffer.
let obj = bitowl.diff.toData(diff, output);
BitOwl
get Type
Return byte of version from buffer, hex string or json object of diff. From buffer and hex string read first byte, from json object read field __source_sign (if exist - is diff, else - data). Can return 0x7f and bigger if diff, and smaller when - data.
let versionByte = bitowl.getType(bufferOrJson);
pack
Pack object into buffer. Type can be >= 0x7f
for diff and smaller for data. If type is not defined, use auto define.
let buffer = bitowl.pack(object, type);
unpack
Unpack buffer to object. Returned object:
{
version: 0x1,//version of message, 0x7f and bigger for diff, and smaller for data.
type: 'data', //can be data of diff, based on version byte
value: unpacked_json_object
}
let d = bitowl.unpack(buffer);
create Diff
Create diff object difference between object and sourceobject. If version of sourceobject >= 0x7f (diff object), create object from diff (toData method) and makes diff between diffs. Object and sourceobject can be buffer, string, object
let json = bitowl.createDiff(object, sourceobject);
apply Diff
Apply diff to sourceobject and return new object. If diff object have wrong version, throw Error exception. Diff and sourceobject can be buffer, string, object
let obj = bitowl.applyDiff(diff, sourceobject);
Hex Formats
All types based on bit sequences, var_str, var_int and other is used from library bitPony
Data
Data format is different for each version. Now exist 2 versions: 0x1
- data object and 0x7f
- diff object
for version < 0x7f
:
version(2 bytes, uint16) | payloadsign (4 bytes, uint32) | payload
for version >= 0x7f
version(2 bytes, uint16) | payloadsign (4 bytes, uint32) | sourcedatasign (4 bytes, uint32) | payload
- version can be 0x1 for data, and 0x7f for diff. Version can be upgraded in future, so check version must be not with equal operation:
ver >= 0x7f
andver < 0x7f
. - Sign its first 4 bytes from double sha256 bytes of payload
- sourcedatasign is sign of original source data for diff
- payload is primitive,
byte-object
Primitive
All primitive have this structure:
for version < 0x7f
(data):
item:
type (uint8) | key (var_str) | value
vector:
type (uint8) | key(var_str) | value count(var_int) | value1, value2, ... valueN
For version >= 0x7f
(diff):
item:
type (uint8) | version control flag (uint8) | key (var_str) | value
vector:
type (uint8) | version control flag (uint8) | key(var_str) | value count(var_int) | value1, value2, ... valueN
Primitive byte-object
Type: 0x5
data type(1 byte, uint8) | key (var_str) | primitive count(var_int) | primitive1, primitive2,....primitiveN
Primitive byte-array
Type: 0x6
For array key everytime is empty.
data type(1 byte, uint8) | key (var_str) | primitive count(var_int) | primitive1, primitive2,....primitiveN
NULL-type
Type: 0x0
data type(1 byte, uint8) | key (var_str) | 0(uint8)
Boolean
Type: 0x1
data type(1 byte, uint8) | key (var_str) | value(uint8)
Integer
Type: 0x2
data type(1 byte, uint8) | key (var_str) | value(var_int)
Float
Type: 0x3
data type(1 byte, uint8) | key (var_str) | value(var_str)
String
Type: 0x4
data type(1 byte, uint8) | key (var_str) | value(var_str)
Function
Type: 0x7
data type(1 byte, uint8) | key (var_str) | value(var_str)
Types
Stringdiff
Stringdiff data is contain information about difference between str1 and str2, for example: str1: test12345 str2: tost54312 diff in json format:
Diff string is hex format for json array like this:
[
{ flag: 'A', sequence: 'a', start: 0, length: 1 },
{ flag: 'U', sequence: 'o', start: 2, length: 1 },
{ flag: 'U', sequence: '54', start: 5, length: 2 },
{ flag: 'U', sequence: '12', start: 8, length: 2 },
{ flag: 'D', sequence: '44', start: 10, length: 3 }
]
converted to:
050000010161010201016f010502023534010802023132ff0a03023434
Format is:
count of items (var_int) | strdiff items
format strdiff of hex is:
flag(uint8) | start (var_int) | length (var_int) | sequence (var_str)
- flag is modifier of change, can be
0x0
(A, APPEND),0x1
(U, UPDATE),0xff
(D, DELETE) - start - start of change in string
- length - length of sequence
- sequence - change string
String diff hex is vector of strdiff
Diff
version(2 bytes, uint16) | payloadsign (4 bytes, uint32) | sourcedatasign (4 bytes, uint32) | payload
- version can be 0x1 for data, and 0x7f for diff. Version can be upgraded in future, so check version must be not with equal operation:
ver >= 0x7f
andver < 0x7f
. - Sign its first 4 bytes from double sha256 bytes of payload
- sourcedatasign is sign of original source data for diff
- payload is primitive,
byte-object
primitive:
type (uint8) | version control flag (uint8) | key (var_str) | value
vector:
type (uint8) | version control flag (uint8) | key(var_str) | primitive count(var_int) | primitive1, primitive2, ... primitiveN