Add Distributor API Documentation
This commit is contained in:
onyinyang
parent
33e24ef5b6
commit
1605b973c9
|
|
@ -0,0 +1,236 @@
|
|||
## API Documentation for Lox Distributor
|
||||
|
||||
|
||||
### Overview
|
||||
|
||||
The Lox distributor receives resources from [rdsys](https://gitlab.torproject.org/tpo/anti-censorship/rdsys) and writes them to [Lox BridgeLines](https://git-crysp.uwaterloo.ca/iang/lox/src/master/src/bridge_table.rs#L42) which are used to populate Lox's bridgetable. The bridgelines are sorted into open entry and hot spare buckets (which can be used to replace blocked bridges or those that are no longer distributed by rdsys). Each time resources are requested from rdsys, the bridgelines received are synced with Lox's existing bridgetable. New resources are appended to the bridgetable and assigned to new ([open entry or](https://gitlab.torproject.org/tpo/anti-censorship/lox/-/blob/main/crates/lox-distributor/src/lox_context.rs?ref_type=heads#L222)) hot spare buckets. Resources with changed information are identified by their fingerprint, and updated in the bridgetable. Concurrently with syncing, the distributor receives and responds to requests from [Lox clients](https://gitlab.torproject.org/tpo/anti-censorship/lox/lox-wasm).
|
||||
|
||||
### Lox client requests
|
||||
|
||||
|
||||
Lox clients make periodic requests to the Lox distributor through `POST` requests to various endpoints:
|
||||
|
||||
#### Headers
|
||||
|
||||
- `Host:` must be set
|
||||
- `Content-Type:` must be set to `application/json`
|
||||
|
||||
#### Client Requests without Data
|
||||
|
||||
#### Reachability Credential
|
||||
|
||||
`Endpoint: /reachability`
|
||||
`Body:` empty
|
||||
|
||||
Reachability credentials are freshness tokens that confirm the bucket in a Lox credential isn't blocked.
|
||||
|
||||
<details>
|
||||
<summary>Example:</summary>
|
||||
|
||||
```
|
||||
POST /reachability HTTP/1.1
|
||||
Host: localhost:8100
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
#### Public Keys
|
||||
|
||||
`Endpoint: /pubkeys`
|
||||
`Body:` empty
|
||||
|
||||
The public keys for each type of Lox credential are bundled together and can be reused until Lox keys are rotated.
|
||||
|
||||
<details>
|
||||
<summary>Example:</summary>
|
||||
|
||||
```
|
||||
POST /pubkeys HTTP/1.1
|
||||
Host: localhost:8100
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
#### Request Invite
|
||||
|
||||
`Endpoint: /invite`
|
||||
`Body:` empty
|
||||
|
||||
Open invitations can be requested by untrusted users to get an initial Lox credential. These will be distributed through a telegram bot that requests through this endpoint.
|
||||
|
||||
<details>
|
||||
<summary>Example:</summary>
|
||||
|
||||
```
|
||||
POST /invite HTTP/1.1
|
||||
Host: localhost:8100
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
#### Client Requests with Data
|
||||
|
||||
Once a user has an open invitation or Lox credential, each client request will be sent with a JSON object to different endpoints corresponding to the correct Lox protocol:
|
||||
|
||||
##### Open Invitation
|
||||
|
||||
`Endpoint: /openreq`
|
||||
`Body:` empty
|
||||
|
||||
<details>
|
||||
<summary>Example:</summary>
|
||||
|
||||
```
|
||||
POST /openreq HTTP/1.1
|
||||
Host: localhost:8100
|
||||
Content-Type: application/json
|
||||
|
||||
{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
##### Trust Promotion
|
||||
|
||||
`Endpoint: /trustpromo`
|
||||
`Body:` empty
|
||||
|
||||
<details>
|
||||
<summary>Example:</summary>
|
||||
|
||||
```
|
||||
POST /trustpromo HTTP/1.1
|
||||
Host: localhost:8100
|
||||
Content-Type: application/json
|
||||
|
||||
{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
##### Trust Migration
|
||||
|
||||
`Endpoint: /trustmig`
|
||||
`Body:` empty
|
||||
|
||||
<details>
|
||||
<summary>Example:</summary>
|
||||
|
||||
```
|
||||
POST /trustmig HTTP/1.1
|
||||
Host: localhost:8100
|
||||
Content-Type: application/json
|
||||
|
||||
{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
##### Level Up
|
||||
|
||||
`Endpoint: /levelup`
|
||||
`Body:` empty
|
||||
|
||||
<details>
|
||||
<summary>Example:</summary>
|
||||
|
||||
```
|
||||
POST /levelup HTTP/1.1
|
||||
Host: localhost:8100
|
||||
Content-Type: application/json
|
||||
|
||||
{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
##### Issue Invitation
|
||||
|
||||
`Endpoint: /issueinvite`
|
||||
`Body:` empty
|
||||
|
||||
<details>
|
||||
<summary>Example:</summary>
|
||||
|
||||
```
|
||||
POST /issueinvite HTTP/1.1
|
||||
Host: localhost:8100
|
||||
Content-Type: application/json
|
||||
|
||||
{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
##### Redeem Invitation
|
||||
|
||||
`Endpoint: /redeeminvite`
|
||||
`Body:` empty
|
||||
|
||||
<details>
|
||||
<summary>Example:</summary>
|
||||
|
||||
```
|
||||
POST /redeem HTTP/1.1
|
||||
Host: localhost:8100
|
||||
Content-Type: application/json
|
||||
|
||||
{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
##### Check Blockage
|
||||
|
||||
`Endpoint: /checkblockage`
|
||||
`Body:` empty
|
||||
|
||||
<details>
|
||||
<summary>Example:</summary>
|
||||
|
||||
```
|
||||
POST /checkblockage HTTP/1.1
|
||||
Host: localhost:8100
|
||||
Content-Type: application/json
|
||||
|
||||
{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
##### Blockage Migration
|
||||
|
||||
`Endpoint: /blockagemigration`
|
||||
`Body:` empty
|
||||
|
||||
<details>
|
||||
<summary>Example:</summary>
|
||||
|
||||
```
|
||||
POST /blockagemigration HTTP/1.1
|
||||
Host: localhost:8100
|
||||
Content-Type: application/json
|
||||
|
||||
{"request_origin":"https","resource_types":["obfs2","scramblesuit"]}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
|
||||
|
||||
### Lox Server responses
|
||||
|
||||
The HTTP response to the `POST` request API call is a chunked transfer encoding of a list of JSON objects that represent all the resources currently allocated to the distributor.
|
||||
|
||||
```
|
||||
[
|
||||
Resource,
|
||||
Resource,
|
||||
...
|
||||
Resource
|
||||
]
|
||||
|
||||
```
|
||||
Loading…
Reference in New Issue