From 60233facf51c29cb2c9ec1816d3876cf9190b1e2 Mon Sep 17 00:00:00 2001 From: Morten Siebuhr Date: Mon, 4 Jun 2018 14:07:15 +0200 Subject: [PATCH 1/2] Docs: Improve protocol description --- protocol.md | 60 +++++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 56 insertions(+), 4 deletions(-) diff --git a/protocol.md b/protocol.md index d00f583..0a601a9 100644 --- a/protocol.md +++ b/protocol.md @@ -1,41 +1,93 @@ # Server Protocol +Version and size numbers are sent back end forth in hex-encoding. Eg. the +version is sent as `000000fe` over the wire (and *not* the binary `000\u00fe`). + +The commentary below is from reading package dumps and some poking at the +unit-tests on the canonical server implementation. + ## Version check + ``` client --- (version ) --> server (using version) client <-- (version ) --- server (echo version if supported or 0) ``` + +The server reads eight bytes of data from the first package received. If the +package contain less than eight bytes, only those are used. Only exception if +getting a one-byte package, in which case it should wait for the next package +in order go get at least two bytes worth of data. + +The only accepted client version is 254 (`0xfe` / `0x000000fe`), to which the +server answers `0x000000fe`. In all other cases the server replies `0x00000000` +and closes the connection. + ## Request cached item ``` +# Binary stuff client --- 'ga' (id <128bit GUID><128bit HASH>) --> server client <-- '+a' (size ) (id <128bit GUID><128bit HASH>) + size bytes --- server (found in cache) client <-- '-a' (id <128bit GUID><128bit HASH>) --- server (not found in cache) +# Info files client --- 'gi' (id <128bit GUID><128bit HASH>) --> server client <-- '+i' (size ) (id <128bit GUID><128bit HASH>) + size bytes --- server (found in cache) client <-- '-i' (id <128bit GUID><128bit HASH>) --- server (not found in cache) +# Resources client --- 'gr' (id <128bit GUID><128bit HASH>) --> server client <-- '+r' (size ) (id <128bit GUID><128bit HASH>) + size bytes --- server (found in cache) client <-- '-r' (id <128bit GUID><128bit HASH>) --- server (not found in cache) ``` -## Start transaction + +Cache miss: + + grUUIDUUIDUUIDUUIDHASHHASHHASHHASH # uuid/hash is sent as 32 bytes + -rUUIDUUIDUUIDUUIDHASHHASHHASHHASH # negative response + +Cache hit: + + grUUIDUUIDUUIDUUIDHASHHASHHASHHASH + +r00000000000000ffUUIDUUIDUUIDUUIDHASHHASHHASHHASH<255 bytes of data> + +Note that the size is sent as 16 bytes encoded as hexadecimal + +## Putting items + +Multiple entries (asset, info and resources) exist for one item in the server, +so they're always uploaded inside a transaction: + ``` client --- 'ts' (id <128bit GUID><128bit HASH>) --> server ``` -## Put cached item +Then one or more put operations for different kinds of assets + ``` client --- 'pa' (size ) + size bytes --> server client --- 'pi' (size ) + size bytes --> server client --- 'pr' (size ) + size bytes --> server ``` -## End transaction (i.e. rename targets to their final names) +And finally the whole thing is finished of (i.e. rename targets to their final names). + ``` client --- 'te' --> server ``` + +An example transaction could be (newlines added for readability) + + ts00000000000000ff00000000000000ee # Start transaction for GUID ff / hash ee (32 bytes in total, raw binary stuff) + pi0000000000000008 # Put eight bytes of info + INFOBLOB # Eight bytes of info + pa0000000000000008 # Put eight bytes of data + DATABLOB # Eight bytes of data + te # End transaction + ## Quit + ``` client --- 'q' --> server -``` \ No newline at end of file +``` + +It should be noted that most clients quit by simply closing the connection. \ No newline at end of file From 708b51211145e90cb2f36ed03486aaa41ef5d566 Mon Sep 17 00:00:00 2001 From: Morten Siebuhr Date: Fri, 8 Jun 2018 21:57:08 +0200 Subject: [PATCH 2/2] Docs: Clean up per review comments --- protocol.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/protocol.md b/protocol.md index 0a601a9..1518ae9 100644 --- a/protocol.md +++ b/protocol.md @@ -3,9 +3,6 @@ Version and size numbers are sent back end forth in hex-encoding. Eg. the version is sent as `000000fe` over the wire (and *not* the binary `000\u00fe`). -The commentary below is from reading package dumps and some poking at the -unit-tests on the canonical server implementation. - ## Version check ``` @@ -24,7 +21,7 @@ and closes the connection. ## Request cached item ``` -# Binary stuff +# Asset binaries client --- 'ga' (id <128bit GUID><128bit HASH>) --> server client <-- '+a' (size ) (id <128bit GUID><128bit HASH>) + size bytes --- server (found in cache) client <-- '-a' (id <128bit GUID><128bit HASH>) --- server (not found in cache)