From 0232772be718386ffecd46326f49fcc22a918d0e Mon Sep 17 00:00:00 2001 From: Sayan Nandan Date: Fri, 5 Apr 2024 17:48:28 +0000 Subject: [PATCH] docs: Improve protocol docs --- docs/index.md | 4 ++++ docs/protocol/2.networking.md | 23 ++++++++++++----------- docs/protocol/index.md | 18 +++++++++++++++++- 3 files changed, 33 insertions(+), 12 deletions(-) diff --git a/docs/index.md b/docs/index.md index cdcf379bf..7e279ca7c 100644 --- a/docs/index.md +++ b/docs/index.md @@ -33,6 +33,10 @@ To develop using Skytable and maintain your deployment you will want to learn ab Looking to integrate Skytable in your application? Great! [Find a driver for your language/framework here](libraries). +## Errors + +Hit an error? Check out the [error code index](protocol/errors). If you need further help please check the resources below. + ## Getting help We have a collection of resources [on this page](resources/useful-links). If you need in help in real-time, we recommend that you join our [Discord Community](https://discord.gg/QptWFdx) where you can get help directly from the developers and our community members. diff --git a/docs/protocol/2.networking.md b/docs/protocol/2.networking.md index 2b47e3f6d..d997a49e7 100644 --- a/docs/protocol/2.networking.md +++ b/docs/protocol/2.networking.md @@ -3,21 +3,19 @@ id: networking title: Networking --- -The Skyhash protocol uses a very simple data exchange model. - -:::info This is for version 0.8.0! -This information on networking only corresponds to Skytable 0.8.0 (Octave). If you're using a different version consider looking for the appropriate document. -::: - -We use three connection stages: +The Skyhash protocol uses a very simple data exchange model. It makes use of three connection stages: - **Client handshake**: The client sends a handshake packet - The handshake contains all necessary information to successfully establish a connection - The structure of the client handshake depends on the authentication plugin in use (since authentication data has to be exchanged before the connection can be established) - - For the `pwd` plugin the client handshake looks like this: + - For the `pwd` plugin the client handshake looks like this (split into lines for convenience): ``` - H00000\n\n + H0 + + 000 + \n\n ``` + > For the protocol compatibility code, [see the version matrix](.#version-matrix) - **Server handshake**: - **Accepted:** If the server accepts the handshake information then it will respond with: `H000` - **Rejected**: If the server rejects the handshake information then it will respond with `H01<8-bit error code>`. You can find out what happened using [the error code index](errors) @@ -28,6 +26,9 @@ How to communicate: - Do the handshake (as described above) and handle any errors - Encode queries as described below +:::tip Is my client compatible? +If the server has accepted your connection then you can be sure that the protocol version and other extensions that your client intends to use is supported by the server. If this isn't the case, then the server will respond with a handshake error code indicating why the connection was rejected. [See all the handshake error codes here](errors#handshake-errors). +::: ## Client @@ -49,11 +50,11 @@ Types: A query has three sections: - The metaframe: - Contains metadata about the query - - Encoded as: `\n` (total size of the other two sections) + - Encoded as: `S\n` (total size of the other two sections) - The dataframe header: Encoded as `\n` - The dataframe: - First part contains the query body, encoded as: `` (the query body is simply appended here) - - Second part contains the payload body with all the parameters, encoded as: `\n ...` (repeat for all parameters) + - Second part contains the payload body with all the parameters, encoded end-on as: `...` (repeat for all parameters). See [the data types for parameters above](#data-types). ## Server diff --git a/docs/protocol/index.md b/docs/protocol/index.md index 7288e28f0..b27a358ec 100644 --- a/docs/protocol/index.md +++ b/docs/protocol/index.md @@ -2,6 +2,8 @@ title: 'Skyhash 2: Overview' --- +## Introduction + Skyhash is the protocol used for communication between Skytable clients (client drivers or libraries) and the Skytable server, written on top of TCP. If you're building an application that needs to *talk to* Skytable, you'll usually choose a [client library](/libraries) that works with your programming language and then start building your application. However, if a client driver is not available for your language then you might choose to implement a client driver yourself and while it might sound like a complicated task, we've worked hard to make it as easy for for you to do so. If you've worked with string processing, what you're going to encounter is very similar. @@ -20,4 +22,18 @@ Here are some good to know things, before a deep dive into the various pieces of - If you need help, ask! (on Discord, ping us on Twitter, just reach out!) - If the documentation doesn't seem helpful or you find it confusing, open an issue on the docs repository. We'll fix it. -With all that out of the way, **go ahead and dive in!** +## Protocol revisions and compatibility + +- **What constitutes an incompatible protocol version?** A protocol version is considered incompatible if and only if: + - the queries sent by an older client can't be processed by the server or + - the **same** responses sent by *the server in question* can't be decoded by the older client +- If newer protocol versions introduce newer data types that is *not* considered an incompatible version since as long as the encoding for the types introduced in the earlier protocol(s) remains unchanged + +### Version matrix + +Please note this list is only maintained post 0.8.0. + +| Server version (release tag) | Skyhash Version | Compatibility Code | Notes | +| ---------------------------- | --------------- | ------------------ | ---------------------------- | +| 0.8.0 | 2.0 | `0` | Initial release of Skyhash/2 | +| 0.8.1 | 2.0 | `0` | |