1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
//! Authentication keys API context.
//!
//! Authentication keys are used to authenticate HTTP tracker `announce` and
//! `scrape` requests.
//!
//! When the tracker is running in `private` or `private_listed` mode, the
//! authentication keys are required to announce and scrape torrents.
//!
//! A sample `announce` request **without** authentication key:
//!
//! <http://0.0.0.0:7070/announce?info_hash=12345678901234567890&peer_id=ABCDEFGHIJKLMNOPQRST&ip=255.255.255.255&port=6881&downloaded=1234&left=98765&event=stopped>
//!
//! A sample `announce` request **with** authentication key:
//!
//! <http://0.0.0.0:7070/announce/YZSl4lMZupRuOpSRC3krIKR5BPB14nrJ?info_hash=12345678901234567890&peer_id=ABCDEFGHIJKLMNOPQRST&ip=255.255.255.255&port=6881&downloaded=1234&left=98765&event=stopped>
//!
//! # Endpoints
//!
//! - [Generate a new authentication key](#generate-a-new-authentication-key)
//! - [Delete an authentication key](#delete-an-authentication-key)
//! - [Reload authentication keys](#reload-authentication-keys)
//!
//! # Generate a new authentication key
//!
//! `POST /key/:seconds_valid`
//!
//! It generates a new authentication key.
//!
//! > **NOTICE**: keys expire after a certain amount of time.
//!
//! **Path parameters**
//!
//! Name | Type | Description | Required | Example
//! ---|---|---|---|---
//! `seconds_valid` | positive integer | The number of seconds the key will be valid. | Yes | `3600`
//!
//! **Example request**
//!
//! ```bash
//! curl -X POST "http://127.0.0.1:1212/api/v1/key/120?token=MyAccessToken"
//! ```
//!
//! **Example response** `200`
//!
//! ```json
//! {
//! "key": "xqD6NWH9TcKrOCwDmqcdH5hF5RrbL0A6",
//! "valid_until": 1680009900,
//! "expiry_time": "2023-03-28 13:25:00.058085050 UTC"
//! }
//! ```
//!
//! > **NOTICE**: `valid_until` and `expiry_time` represent the same time.
//! `valid_until` is the number of seconds since the Unix epoch
//! ([timestamp](https://en.wikipedia.org/wiki/Timestamp)), while `expiry_time`
//! is the human-readable time ([ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)).
//!
//! **Resource**
//!
//! Refer to the API [`AuthKey`](crate::servers::apis::v1::context::auth_key::resources::AuthKey)
//! resource for more information about the response attributes.
//!
//! # Delete an authentication key
//!
//! `DELETE /key/:key`
//!
//! It deletes a previously generated authentication key.
//!
//! **Path parameters**
//!
//! Name | Type | Description | Required | Example
//! ---|---|---|---|---
//! `key` | 40-char string | The `key` to remove. | Yes | `xqD6NWH9TcKrOCwDmqcdH5hF5RrbL0A6`
//!
//! **Example request**
//!
//! ```bash
//! curl -X DELETE "http://127.0.0.1:1212/api/v1/key/xqD6NWH9TcKrOCwDmqcdH5hF5RrbL0A6?token=MyAccessToken"
//! ```
//!
//! **Example response** `200`
//!
//! ```json
//! {
//! "status": "ok"
//! }
//! ```
//!
//! It you try to delete a non-existent key, the response will be an error with
//! a `500` status code.
//!
//! **Example error response** `500`
//!
//! ```text
//! Unhandled rejection: Err { reason: "failed to delete key: Failed to remove record from Sqlite3 database, error-code: 0, src/tracker/databases/sqlite.rs:267:27" }
//! ```
//!
//! > **NOTICE**: a `500` status code will be returned and the body is not a
//! valid JSON. It's a text body containing the serialized-to-display error
//! message.
//!
//! # Reload authentication keys
//!
//! `GET /keys/reload`
//!
//! The tracker persists the authentication keys in a database. This endpoint
//! reloads the keys from the database.
//!
//! **Example request**
//!
//! ```bash
//! curl "http://127.0.0.1:1212/api/v1/keys/reload?token=MyAccessToken"
//! ```
//!
//! **Example response** `200`
//!
//! ```json
//! {
//! "status": "ok"
//! }
//! ```