torrust_index_backend/web/api/v1/contexts/proxy/mod.rs
1//! API context: `proxy`.
2//!
3//! This context contains the API routes for the proxy service.
4//!
5//! The torrent descriptions can contain images. These images are proxied
6//! through the backend to:
7//!
8//! - Prevent leaking the user's IP address.
9//! - Avoid storing images on the server.
10//!
11//! The proxy service is a simple cache that stores the images in memory.
12//!
13//! **NOTICE:** For now, it only supports PNG images.
14//!
15//! **NOTICE:** The proxy service is not intended to be used as a general
16//! purpose proxy. It is only intended to be used for the images in the
17//! torrent descriptions.
18//!
19//! **NOTICE:** Ununauthorized users can't see images. They will get an image
20//! with the text "Sign in to see image" instead.
21//!
22//! # Example
23//!
24//! The PNG image:
25//!
26//! <https://raw.githubusercontent.com/torrust/torrust-index-backend/develop/docs/media/torrust_logo.png>
27//!
28//! The percent encoded image URL:
29//!
30//! ```text
31//! https%3A%2F%2Fraw.githubusercontent.com%2Ftorrust%2Ftorrust-index-backend%2Fdevelop%2Fdocs%2Fmedia%2Ftorrust_logo.png
32//! ```
33//!
34//! For unauthenticated clients:
35//!
36//! ```bash
37//! curl \
38//! --header "cache-control: no-cache" \
39//! --header "pragma: no-cache" \
40//! --output mandelbrotset.jpg \
41//! http://0.0.0.0:3001/v1/proxy/image/https%3A%2F%2Fraw.githubusercontent.com%2Ftorrust%2Ftorrust-index-backend%2Fdevelop%2Fdocs%2Fmedia%2Ftorrust_logo.png
42//! ```
43//!
44//! You will receive an image with the text "Sign in to see image" instead.
45//!
46//! For authenticated clients:
47//!
48//! ```bash
49//! curl \
50//! --header "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ1c2VyIjp7InVzZXJfaWQiOjEsInVzZXJuYW1lIjoiaW5kZXhhZG1pbiIsImFkbWluaXN0cmF0b3IiOnRydWV9LCJleHAiOjE2ODYyMTU3ODh9.4k8ty27DiWwOk4WVcYEhIrAndhpXMRWnLZ3i_HlJnvI" \
51//! --header "cache-control: no-cache" \
52//! --header "pragma: no-cache" \
53//! --output mandelbrotset.jpg \
54//! http://0.0.0.0:3001/v1/proxy/image/https%3A%2F%2Fraw.githubusercontent.com%2Ftorrust%2Ftorrust-index-backend%2Fdevelop%2Fdocs%2Fmedia%2Ftorrust_logo.png
55//! ```
56pub mod handlers;
57pub mod responses;
58pub mod routes;