Formal terrapipe query/result implementation
parent
3740b53efd
commit
e84c58d4ad
@ -1,102 +0,0 @@
|
||||
# Terrapipe
|
||||
|
||||
> Date: 2<sup>nd</sup> July, 2020<br>Copyright © 2020 Sayan Nandan
|
||||
|
||||
Terrapipe is a protocol that is used by Terrabase for data transfer. It is an application layer
|
||||
protocol that builds on top of TCP. Just like HTTP's request/response action, Terrapipe (i.e tp://)
|
||||
also makes use of a query/result action.
|
||||
From now on, I will refer to Terrapipe as _TP_ or _tp_.
|
||||
|
||||
TP makes use of two packets:
|
||||
|
||||
1. **The `Q` uery packet**: This is sent by the client
|
||||
2. **The `R` esult packet**: This is sent by the server
|
||||
|
||||
## The `Q` uery packet
|
||||
|
||||
The `Q` uery packet has the following structure:
|
||||
|
||||
```
|
||||
TP/<VERSION>/Q/<QTYPE>
|
||||
--------------- DATA ----------
|
||||
```
|
||||
|
||||
**Note:** The first line, is followed by a line break, and then the subsequent lines.
|
||||
|
||||
### Line 1: Meta frame
|
||||
|
||||
The first line is called the meta frame. The `<VALUES>` and their corresponding meanings are as follows:
|
||||
|
||||
* **`VERSION`**: The version of the protocol, in semver form, i.e `major.minor.patch` .
|
||||
|
||||
An example can be: `0.1.0`
|
||||
|
||||
* **`QTYPE`**: This is the type of query. It can have the following values:
|
||||
- `GET` : For `GET` operations
|
||||
- `SET` : For `SET` operations
|
||||
- `UPDATE` : For `UDPATE` operations
|
||||
- `DEL` : For `DEL` operations
|
||||
|
||||
#### Example meta frame
|
||||
|
||||
```
|
||||
TP/0.1.0/Q/GET
|
||||
```
|
||||
|
||||
### Line 2 and subsequent lines: Data frame
|
||||
|
||||
The data frame doesn't have any defined format. It can be anything that can be transferred over TCP - that is, well, anything: letters, numbers or vaguely bytes.
|
||||
|
||||
## The `R` esult packet
|
||||
|
||||
The `R` esult packet has the following structure:
|
||||
|
||||
```
|
||||
TP/<VERSION>/R/<RESPONSECODE>/<LENGTH>
|
||||
--------------------- DATA -------------------
|
||||
```
|
||||
|
||||
**Note:** The first line is followed by a line break, and then the subsequent lines.
|
||||
|
||||
### Line 1: Meta frame
|
||||
|
||||
Just like the `Q` uery packet, the first line is called the meta frame.
|
||||
The `<VALUES>` and their corresponding meanings are as follows:
|
||||
|
||||
* **`VERSION`**: The version of the protocol, in semver form, i.e `major.minor.patch` .
|
||||
|
||||
An example can be: `0.1.0`
|
||||
|
||||
* **`RESPONSECODE`**: This is the outcome of the query. It can have the following values:
|
||||
- 0: Okay
|
||||
- 1: Not found
|
||||
- 2: Method not allowed
|
||||
- 3: Server error
|
||||
- 4: Corrupt byte
|
||||
- 5: Protocol version mismatch
|
||||
* **`LENGTH`**: The number of bytes that are being transmitted. This is useful for preallocating buffers for copying the data.
|
||||
|
||||
#### Example data frame
|
||||
|
||||
```
|
||||
sayan is writing a protocol
|
||||
```
|
||||
|
||||
## An example of a query/result
|
||||
|
||||
Let us assume a key called `sayan` with a value of '17' exists on the database.
|
||||
Our client, uses `0.1.0` version of tp and sends a `GET` request for the key to our server which also uses version `0.1.0` of tp.
|
||||
|
||||
### The `Q` uery packet
|
||||
|
||||
```
|
||||
TP/0.1.0/Q/GET
|
||||
sayan
|
||||
```
|
||||
|
||||
### The `R` esult packet
|
||||
|
||||
```
|
||||
TP/0.1.0/R/0/2
|
||||
17
|
||||
```
|
Loading…
Reference in New Issue