Pkarr - HackMD

# Relays In UDP-less environments (like web browsers, virtual machines, containers and firewalled networks) clients need to rely on a remote server that can relay their [PUT](#PUT) and [GET](#GET) messages. ## API Public relays need to setup cors headers. ### PUT #### Request ``` PUT /:z-base32-encoded-key HTTP/2 Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, PUT, OPTIONS <body> ``` Body is described at [Payload](#Payload) encoding section. On receiving a PUT request, the relay server should: 1. Encode the `seq` and `v` to a *bencode* message as follows: `3:seqi<sequence>e1:v<v's length>:<v's bytes>` 2. Verify that the `sig` matches the encoded message from step 1, if it is invalid, return a `400 Bad Request` response. 3. Perform the DHT Put request as defined in [BEP0044](https://www.bittorrent.org/beps/bep_0044.html). 4. If the DHT request is successful, return a `200 OK` response, otherwise if any error occured return a `500 Internal Server Error` response. #### Errors - `400 Bad Request` if the public key in the path is invalid, or the payload has invalid signature, or DNS packet. - `413 Payload Too Large` if the payload is larger than 1072 bytes - `429 Too Many Requests` if the server is already publishing a packet for the same key, or if it is rate limiting requests from the same IP. ### GET ``` GET /:z-base32-encoded-key HTTP/2 ``` #### Response ``` HTTP/2 200 OK Access-Control-Allow-Origin: * Access-Control-Allow-Methods: GET, PUT, OPTIONS Content-Type: application/pkarr.org/relays Cache-Control: public, max-age=300 <sig><seq>[<v>] ``` `Cache-Control` header would help browsers reduce their reliance on the relay, the `max-age` should be set to be the minimum `ttl` in the resource records in the packet or some minimum ttl chosen by the relay. Body should consist of: On receiving a GET request, the relay server should: 1. Perform a DHT mutable GET query as defined in [BEP0044](https://www.bittorrent.org/beps/bep_0044.html) 2. Concat the `sig`, big-endian encoded `seq`, and `v`. 3. If no records were found, respond with `404 Not Found`. #### Errors - `400 Bad Request` if the public key in the path is invalid. - `404 Not Found` if the packet is not found. ## Payload Relay payload is encoded as follows: - 64 bytes `signature` - 8 bytes `u64` big-endian `timestamp` - 0-1000 bytes of `encoded DNS packet`. ## Oportunities Relays are only expected to transparently relay messages to an from the DHT, but popular public relays may add caching and other useful features like indexing and search over all the records they have seen, effectively acting as a public phone book without having to crawl the web for Pkarr keys.

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.