docs(api): [torrust#163] API documentation on docs.rs

docs/media/mandelbrot_2048x2048_infohash_v1.png.torrent.json

@@ -0,0 +1,10 @@
+{
+    "created by": "qBittorrent v4.4.1",
+    "creation date": 1679674628,
+    "info": {
+        "length": 172204,
+        "name": "mandelbrot_2048x2048.png",
+        "piece length": 16384,
+        "pieces": "<hex>7D 91 71 0D 9D 4D BA 88 9B 54 20 54 D5 26 72 8D 5A 86 3F E1 21 DF 77 C7 F7 BB 6C 77 96 21 66 25 38 C5 D9 CD AB 8B 08 EF 8C 24 9B B2 F5 C4 CD 2A DF 0B C0 0C F0 AD DF 72 90 E5 B6 41 4C 23 6C 47 9B 8E 9F 46 AA 0C 0D 8E D1 97 FF EE 68 8B 5F 34 A3 87 D7 71 C5 A6 F9 8E 2E A6 31 7C BD F0 F9 E2 23 F9 CC 80 AF 54 00 04 F9 85 69 1C 77 89 C1 76 4E D6 AA BF 61 A6 C2 80 99 AB B6 5F 60 2F 40 A8 25 BE 32 A3 3D 9D 07 0C 79 68 98 D4 9D 63 49 AF 20 58 66 26 6F 98 6B 6D 32 34 CD 7D 08 15 5E 1A D0 00 09 57 AB 30 3B 20 60 C1 DC 12 87 D6 F3 E7 45 4F 70 67 09 36 31 55 F2 20 F6 6C A5 15 6F 2C 89 95 69 16 53 81 7D 31 F1 B6 BD 37 42 CC 11 0B B2 FC 2B 49 A5 85 B6 FC 76 74 44 93</hex>"
+    }
+}

project-words.txt

@@ -3,6 +3,7 @@ addrs
 AUTOINCREMENT
 bencode
 bencoded
+Benoit
 binascii
 btih
 chrono
@@ -21,6 +22,7 @@ hexlify
 httpseeds
 imagoodboy
 imdl
+indexadmin
 indexmap
 infohash
 jsonwebtoken
@@ -30,6 +32,7 @@ LEECHERS
 lettre
 luckythelab
 mailcatcher
+mandelbrotset
 metainfo
 nanos
 NCCA
@@ -38,6 +41,7 @@ nocapture
 Oberhachingerstr
 oneshot
 ppassword
+proxied
 reqwest
 Roadmap
 ROADMAP
@@ -54,6 +58,8 @@ tempfile
 thiserror
 torrust
 Torrust
+unban
+Ununauthorized
 upgrader
 Uragqm
 urlencoding

src/cache/image/manager.rs

@@ -153,6 +153,8 @@ impl ImageCacheService {
             .await
             .map_err(|_| Error::UrlIsUnreachable)?;
 
+        // code-review: we could get a HTTP 304 response, which doesn't contain a body (the image bytes).
+
         if let Some(content_type) = res.headers().get("Content-Type") {
             if content_type != "image/jpeg" && content_type != "image/png" {
                 return Err(Error::UrlIsNotAnImage);

src/lib.rs

@@ -1,3 +1,12 @@
+//! Documentation for [Torrust Tracker Index Backend](https://github.com/torrust/torrust-index-backend) API.
+//!
+//! This is the backend API for [Torrust Tracker Index](https://github.com/torrust/torrust-index).
+//!
+//! It is written in Rust and uses the actix-web framework. It is designed to be
+//! used with by the [Torrust Tracker Index Frontend](https://github.com/torrust/torrust-index-frontend).
+//!
+//! If you are looking for information on how to use the API, please see the
+//! [API v1](crate::web::api::v1) section of the documentation.
 pub mod app;
 pub mod auth;
 pub mod bootstrap;
@@ -15,6 +24,7 @@ pub mod tracker;
 pub mod ui;
 pub mod upgrades;
 pub mod utils;
+pub mod web;
 
 trait AsCSV {
     fn as_csv<T>(&self) -> Result<Option<Vec<T>>, ()>

src/web/api/mod.rs

@@ -0,0 +1,6 @@
+//! The Torrust Index Backend API.
+//!
+//! Currently, the API has only one version: `v1`.
+//!
+//! Refer to the [`v1`](crate::web::api::v1) module for more information.
+pub mod v1;

src/web/api/v1/auth.rs

@@ -0,0 +1,80 @@
+//! API authentication.
+//!
+//! The API uses a [bearer token authentication scheme](https://datatracker.ietf.org/doc/html/rfc6750).
+//!
+//! API clients must have an account on the website to be able to use the API.
+//!
+//! # Authentication flow
+//!
+//! - [Registration](#registration)
+//! - [Login](#login)
+//! - [Using the token](#using-the-token)
+//!
+//! ## Registration
+//!
+//! ```bash
+//! curl \
+//!   --header "Content-Type: application/json" \
+//!   --request POST \
+//!   --data '{"username":"indexadmin","email":"indexadmin@torrust.com","password":"BenoitMandelbrot1924","confirm_password":"BenoitMandelbrot1924"}' \
+//!   http://127.0.0.1:3000/v1/user/register
+//! ```
+//!
+//! **NOTICE**: The first user is automatically an administrator. Currently,
+//! there is no way to change this. There is one administrator per instance.
+//! And you cannot delete the administrator account or make another user an
+//! administrator. For testing purposes, you can create a new administrator
+//! account by creating a new user and then manually changing the `administrator`
+//! field in the `torrust_users` table to `1`.
+//!
+//! ## Login
+//!
+//! ```bash
+//! curl \
+//!   --header "Content-Type: application/json" \
+//!   --request POST \
+//!   --data '{"login":"indexadmin","password":"BenoitMandelbrot1924"}' \
+//!   http://127.0.0.1:3000/v1/user/login
+//! ```
+//!
+//! **Response**
+//!
+//! ```json
+//! {
+//!     "data":{
+//!       "token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjp7InVzZXJfaWQiOjEsInVzZXJuYW1lIjoiaW5kZXhhZG1pbiIsImFkbWluaXN0cmF0b3IiOnRydWV9LCJleHAiOjE2ODYyMTU3ODh9.4k8ty27DiWwOk4WVcYEhIrAndhpXMRWnLZ3i_HlJnvI",
+//!       "username":"indexadmin",
+//!       "admin":true
+//!     }
+//!   }
+//! ```
+//!
+//! **NOTICE**: The token is valid for 2 weeks (`1_209_600` seconds). After that,
+//! you will have to renew the token.
+//!
+//! **NOTICE**: The token is associated with the user role. If you change the
+//! user's role, you will have to log in again to get a new token with the new
+//! role.
+//!
+//! ## Using the token
+//!
+//! Some endpoints require authentication. To use the token, you must add the
+//! `Authorization` header to your request. For example, if you want to add a
+//! new category, you must do the following:
+//!
+//! ```bash
+//! curl \
+//!   --header "Content-Type: application/json" \
+//!   --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjp7InVzZXJfaWQiOjEsInVzZXJuYW1lIjoiaW5kZXhhZG1pbiIsImFkbWluaXN0cmF0b3IiOnRydWV9LCJleHAiOjE2ODYyMTU3ODh9.4k8ty27DiWwOk4WVcYEhIrAndhpXMRWnLZ3i_HlJnvI" \
+//!   --request POST \
+//!   --data '{"name":"new category","icon":null}' \
+//!   http://127.0.0.1:3000/v1/category
+//! ```
+//!
+//! **Response**
+//!
+//! ```json
+//! {
+//!   "data": "new category"
+//! }
+//! ```

src/web/api/v1/contexts/about/mod.rs

@@ -0,0 +1,86 @@
+//! API context: `about`.
+//!
+//! This API context is responsible for providing metadata about the API.
+//!
+//! # Endpoints
+//!
+//! - [About](#about)
+//! - [License](#license)
+//!
+//! # About
+//!
+//! `GET /v1/about`
+//!
+//! Returns a html page with information about the API.
+//!
+//!
+//! **Example request**
+//!
+//! ```bash
+//! curl "http://127.0.0.1:3000/v1/about"
+//! ```
+//!
+//! **Example response** `200`
+//!
+//! ```html
+//! <html>
+//!     <head>
+//!         <title>About</title>
+//!     </head>
+//!     <body style="margin-left: auto; margin-right: auto; max-width: 30em;">
+//!         <h1>Torrust Index Backend</h1>
+//!
+//!         <h2>About</h2>
+//!
+//!         <p>Hi! This is a running <a href="https://github.com/torrust/torrust-index-backend">torrust-index-backend</a>.</p>
+//!     </body>
+//!     <footer style="padding: 1.25em 0; border-top: dotted 1px;">
+//!         <a href="/v1/about/license">license</a>
+//!     </footer>
+//! </html>
+//! ```
+//!
+//! # License
+//!
+//! `GET /v1/about/license`
+//!
+//! Returns the API license.
+//!
+//! **Example request**
+//!
+//! ```bash
+//! curl "http://127.0.0.1:3000/v1/about/license"
+//! ```
+//!
+//! **Example response** `200`
+//!
+//! ```html
+//! <html>
+//!     <head>
+//!         <title>Licensing</title>
+//!     </head>
+//!     <body style="margin-left: auto; margin-right: auto; max-width: 30em;">
+//!         <h1>Torrust Index Backend</h1>
+//!
+//!         <h2>Licensing</h2>
+//!
+//!         <h3>Multiple Licenses</h3>
+//!
+//!         <p>
+//!             This repository has multiple licenses depending on the content type, the date of contributions or stemming from external component licenses that were not developed by any of Torrust team members or Torrust repository
+//!             contributors.
+//!         </p>
+//!
+//!         <p>The two main applicable license to most of its content are:</p>
+//!
+//!         <p>- For Code -- <a href="https://github.com/torrust/torrust-index-backend/blob/main/licensing/agpl-3.0.md">agpl-3.0</a></p>
+//!
+//!         <p>- For Media (Images, etc.) -- <a href="https://github.com/torrust/torrust-index-backend/blob/main/licensing/cc-by-sa.md">cc-by-sa</a></p>
+//!
+//!         <p>If you want to read more about all the licenses and how they apply please refer to the <a href="https://github.com/torrust/torrust-index-backend/blob/develop/licensing/contributor_agreement_v01.md">contributor agreement</a>.</p>
+//!     </body>
+//!     <footer style="padding: 1.25em 0; border-top: dotted 1px;">
+//!         <a href="/v1/about">about</a>
+//!     </footer>
+//! </html>
+//! ```

src/web/api/v1/contexts/category/mod.rs

@@ -0,0 +1,140 @@
+//! API context: `category`.
+//!
+//! This API context is responsible for handling torrent categories.
+//!
+//! # Endpoints
+//!
+//! - [Get all categories](#get-all-categories)
+//! - [Add a category](#add-a-category)
+//! - [Delete a category](#delete-a-category)
+//!
+//! **NOTICE**: We don't support multiple languages yet, so the category name
+//! is always in English.
+//!
+//! # Get all categories
+//!
+//! `GET /v1/category`
+//!
+//! Returns all torrent categories.
+//!
+//! **Example request**
+//!
+//! ```bash
+//! curl "http://127.0.0.1:3000/v1/category"
+//! ```
+//!
+//! **Example response** `200`
+//!
+//! ```json
+//! {
+//!   "data": [
+//!     {
+//!       "category_id": 3,
+//!       "name": "games",
+//!       "num_torrents": 0
+//!     },
+//!     {
+//!       "category_id": 1,
+//!       "name": "movies",
+//!       "num_torrents": 0
+//!     },
+//!     {
+//!       "category_id": 4,
+//!       "name": "music",
+//!       "num_torrents": 0
+//!     },
+//!     {
+//!       "category_id": 5,
+//!       "name": "software",
+//!       "num_torrents": 0
+//!     },
+//!     {
+//!       "category_id": 2,
+//!       "name": "tv shows",
+//!       "num_torrents": 0
+//!     }
+//!   ]
+//! }
+//! ```
+//! **Resource**
+//!
+//! Refer to the [`Category`](crate::databases::database::Category)
+//! struct for more information about the response attributes.
+//!
+//! # Add a category
+//!
+//! `POST /v1/category`
+//!
+//! It adds a new category.
+//!
+//! **POST params**
+//!
+//! Name | Type | Description | Required | Example
+//! ---|---|---|---|---
+//! `name` | `String` | The name of the category | Yes | `new category`
+//! `icon` | `Option<String>` | Icon representing the category | No |
+//!
+//! **Notice**: the `icon` field is not implemented yet.
+//!
+//! **Example request**
+//!
+//! ```bash
+//! curl \
+//!   --header "Content-Type: application/json" \
+//!   --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjp7InVzZXJfaWQiOjEsInVzZXJuYW1lIjoiaW5kZXhhZG1pbiIsImFkbWluaXN0cmF0b3IiOnRydWV9LCJleHAiOjE2ODYyMTU3ODh9.4k8ty27DiWwOk4WVcYEhIrAndhpXMRWnLZ3i_HlJnvI" \
+//!   --request POST \
+//!   --data '{"name":"new category","icon":null}' \
+//!   http://127.0.0.1:3000/v1/category
+//! ```
+//!
+//! **Example response** `200`
+//!
+//! ```json
+//! {
+//!   "data": "new category"
+//! }
+//! ```
+//!
+//! **Resource**
+//!
+//! Refer to [`OkResponse`](crate::models::response::OkResponse<T>) for more
+//! information about the response attributes. The response contains only the
+//! name of the newly created category.
+//!
+//! # Delete a category
+//!
+//! `DELETE /v1/category`
+//!
+//! It deletes a category.
+//!
+//! **POST params**
+//!
+//! Name | Type | Description | Required | Example
+//! ---|---|---|---|---
+//! `name` | `String` | The name of the category | Yes | `new category`
+//! `icon` | `Option<String>` | Icon representing the category | No |
+//!
+//! **Example request**
+//!
+//! ```bash
+//! curl \
+//!   --header "Content-Type: application/json" \
+//!   --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjp7InVzZXJfaWQiOjEsInVzZXJuYW1lIjoiaW5kZXhhZG1pbiIsImFkbWluaXN0cmF0b3IiOnRydWV9LCJleHAiOjE2ODYyMTU3ODh9.4k8ty27DiWwOk4WVcYEhIrAndhpXMRWnLZ3i_HlJnvI" \
+//!   --request DELETE \
+//!   --data '{"name":"new category","icon":null}' \
+//!   http://127.0.0.1:3000/v1/category
+//! ```
+//!
+//! **Example response** `200`
+//!
+//! ```json
+//! {
+//!   "data": "new category"
+//! }
+//! ```
+//!
+//! **Resource**
+//!
+//! Refer to [`OkResponse`](crate::models::response::OkResponse<T>) for more
+//! information about the response attributes. The response contains only the
+//! name of the deleted category.