Skip to main content

objectstore_server/endpoints/
mod.rs

1//! Contains all HTTP endpoint handlers.
2//!
3//! This module documents the request and response shape of every route; see the [crate
4//! documentation](crate) for the layers a request passes through before reaching a handler.
5//!
6//! Scopes are encoded in the URL path using Matrix URI syntax: `org=123;project=456`. An
7//! underscore (`_`) represents empty scopes.
8//!
9//! # Object Endpoints
10//!
11//! All object operations live under the `/v1/` prefix:
12//!
13//! | Method   | Path                                      | Description                  |
14//! |----------|-------------------------------------------|------------------------------|
15//! | `POST`   | `/v1/objects/{usecase}/{scopes}/`         | Insert with server-generated key |
16//! | `GET`    | `/v1/objects/{usecase}/{scopes}/{*key}`   | Retrieve object              |
17//! | `HEAD`   | `/v1/objects/{usecase}/{scopes}/{*key}`   | Retrieve metadata only       |
18//! | `PUT`    | `/v1/objects/{usecase}/{scopes}/{*key}`   | Insert or overwrite with key |
19//! | `PATCH`  | `/v1/objects/{usecase}/{scopes}/{*key}`   | Extend expiry                |
20//! | `DELETE` | `/v1/objects/{usecase}/{scopes}/{*key}`   | Delete object                |
21//! | `POST`   | `/v1/objects:batch/{usecase}/{scopes}/`   | Batch operations (multipart) |
22//!
23//! Object metadata travels in request and response headers; see
24//! [`objectstore_types::metadata`] for the mapping and the separate JSON update contract.
25//!
26//! GET and HEAD accept `response-content-disposition=inline|attachment` (default attachment).
27//! Response options apply only to successful object responses, including ranged GETs. See
28//! [`crate::extractors::response_options`] for validation. The object handlers construct
29//! download headers with browser safeguards and filename formatting.
30//!
31//! # Batch Endpoint
32//!
33//! `POST /v1/objects:batch/{usecase}/{scopes}/` runs up to 1000 get, head, delete and insert
34//! operations from one `multipart/form-data` request. Operations are read one at a time, run
35//! with bounded concurrency, and their results stream back in completion order. Each operation
36//! is authorized, rate limited and validated on its own and reports its own status.
37//! Request-level failures still fail the whole request with a plain HTTP error: a failed
38//! authentication, a rejection by admission control in the extractors, an invalid path, or a
39//! body that cannot be opened as multipart.
40//!
41//! Each operation is a JSON descriptor part named by its index, followed by a payload part for
42//! inserts:
43//!
44//! ```text
45//! --b
46//! Content-Disposition: form-data; name="0"
47//!
48//! {"kind":"insert","key":"a/résumé.png","metadata":{"content_type":"image/png","expiration":"ttl:30d"}}
49//! --b
50//! Content-Disposition: form-data; name="0.payload"; filename="blob"
51//! Content-Type: application/octet-stream
52//!
53//! <bytes>
54//! --b
55//! Content-Disposition: form-data; name="1"
56//!
57//! {"kind":"head","key":"c"}
58//! --b--
59//! ```
60//!
61//! Each result is a part named by the operation index with `Content-Type: application/json`.
62//! It holds `status` (an integer), `kind` and `key` for successful operations,
63//! `metadata` for a successful get or head (see
64//! [`ReadMetadata`](objectstore_types::metadata::ReadMetadata)), and `error` with the
65//! standard error body for failures. A successful get is followed by a `"<i>.payload"` part with
66//! `filename="<i>"` holding the stored bytes, typed `application/octet-stream` when the object
67//! is encoded:
68//!
69//! ```text
70//! --os-boundary-…
71//! Content-Disposition: form-data; name="1"
72//! Content-Type: application/json
73//!
74//! {"status":200,"kind":"head","key":"c","metadata":{"content_type":"text/plain","time_created":"2026-11-10T12:00:00Z","size":12}}
75//! --os-boundary-…
76//! Content-Disposition: form-data; name="0"
77//! Content-Type: application/json
78//!
79//! {"status":201,"kind":"insert","key":"a/résumé.png"}
80//! --os-boundary-…--
81//! ```
82//!
83//! [`crate::extractors::batch`] lists how descriptors and payloads are paired and how malformed
84//! parts are reported. A broken multipart body ends the response early, so clients must treat a
85//! missing result as a failure.
86//!
87//! # Resumable Upload Endpoints
88//!
89//! A resumable upload transfers a single object across several requests.
90//! The client opens a session, declaring the object's total size and metadata upfront, and
91//! then sends the payload as a sequence of chunks at increasing byte offsets.
92//! If a chunk fails, the client can ask the server which offset it holds and continue from there,
93//! so an interrupted transfer resumes where it stopped instead of starting over.
94//! Clients are still encouraged to send the whole payload in a single request, as that's the most
95//! efficient and reliable approach.
96//! The server knows the total size from the session, so it recognizes the chunk carrying the last
97//! byte and completes the upload itself.
98//!
99//! Resumable uploads use the object endpoints above, selected by a query parameter:
100//! `upload_type=resumable` opens a session, and `session=<token>` addresses it from then on.
101//! Session creation returns an opaque token encoded once as unpadded base64url; that value can be
102//! placed directly in the `session` query parameter.
103//! The object is named by the request path as usual, and [`objectstore_types::resumable`]
104//! holds the protocol types.
105//!
106//! | Method   | Path                                                       | Description                                  |
107//! |----------|------------------------------------------------------------|----------------------------------------------|
108//! | `POST`   | `/v1/objects/{usecase}/{scopes}/?upload_type=resumable`    | Create session (server-generated key)        |
109//! | `PUT`    | `/v1/objects/{usecase}/{scopes}/{*key}?upload_type=resumable` | Create session (user-provided key)        |
110//! | `PUT`    | `/v1/objects/{usecase}/{scopes}/{*key}?session=<token>`    | Upload a chunk, or query the offset          |
111//! | `DELETE` | `/v1/objects/{usecase}/{scopes}/{*key}?session=<token>`    | Cancel upload, discarding what was sent      |
112//!
113//! Session creation requires an `Upload-Length` header carrying the total size of the object
114//! in bytes, takes the same metadata headers as a regular upload, and requires an empty body.
115//! It answers `200 OK` with `{"key", "session", "granularity"}`; the session field is the token
116//! to use in subsequent query parameters. `granularity` is this upload's persistence unit in bytes,
117//! or zero when no unit is imposed. Metadata is fixed at this point and does not change afterwards.
118//!
119//! Chunk uploads and offset queries share one request shape, distinguished by the
120//! `Upload-Offset` header: a byte offset submits the body as the chunk starting there, while
121//! the `*` wildcard submits an empty body and asks which offset the server holds. Both answer
122//! `204 No Content` with the authoritative `Upload-Offset` while bytes remain, and
123//! `201 Created` with `{"key"}` once the upload is complete and the object is available through
124//! the normal object endpoints. The session is terminal at that point.
125//! The offset in the response may be lower than the end of the last chunk that was sent.
126//! Backends can e.g. persist only aligned prefixes and discard the remainder, so clients must
127//! always continue from the returned offset.
128//! Non-final chunks shorter than one positive granularity unit are rejected; final chunks are
129//! exempt because they persist the remaining bytes.
130//! Every chunk requires `Content-Length`, even over HTTP/2, while creation and offset queries
131//! must not carry a request body.
132//!
133//! An offset query can finish pending backend publication work, so it requires write permission
134//! despite being read-shaped.
135//! Termination likewise needs write rather than delete permission: it releases an in-progress upload,
136//! not an object.
137//!
138//! | Status | Meaning | Client action |
139//! |--------|---------|---------------|
140//! | `400`  | Malformed session token or one that cannot be decrypted or authenticated, missing `Upload-Length`, nonempty offset query, chunk exceeding the declared length, or non-final chunk shorter than the granularity | Correct the request |
141//! | `404`  | The upload session is unknown or does not belong to this object | Start a new session or correct the request |
142//! | `409`  | A chunk's offset does not match the authoritative offset | Query the offset and continue from there |
143//! | `410`  | The session expired or was canceled | Start a new session |
144//! | `501`  | The server declined the resumable upload session creation for the requested object | Fall back to a regular upload |
145//!
146//! # Internal Endpoints
147//!
148//! Internal endpoints are exempt from authentication, rate limiting, and the web concurrency
149//! limit so they remain available when the server is under load. [`is_internal_route`]
150//! identifies them.
151//!
152//! | Method | Path | Description |
153//! |--------|------|-------------|
154//! | `GET` | `/health` | Liveness probe (always returns 200) |
155//! | `GET` | `/ready` | Readiness probe (remains healthy during shutdown) |
156//! | `GET` | `/keda` | Prometheus text-format gauges for KEDA autoscaling (see [KEDA Metrics](crate#keda-metrics)) |
157//!
158//! # Code Usage
159//!
160//! Use [`routes`] to create a router with all endpoints.
161
162use axum::Router;
163
164use crate::state::ServiceState;
165
166mod batch;
167pub mod common;
168pub mod health;
169mod keda;
170mod objects;
171#[cfg(all(target_os = "linux", feature = "profiling"))]
172mod profiling;
173mod resumable;
174
175/// Returns `true` for internal endpoints that are exempt from metrics and concurrency limits.
176pub fn is_internal_route(route: &str) -> bool {
177    matches!(route, "/health" | "/ready" | "/keda") || route.starts_with("/debug/")
178}
179
180/// Returns a router with all objectstore HTTP endpoints mounted.
181///
182/// Mounts health and KEDA endpoints at the root and all object/batch
183/// endpoints under `/v1/`.
184pub fn routes() -> Router<ServiceState> {
185    let routes_v1 = Router::new()
186        .merge(objects::router())
187        .merge(batch::router());
188
189    let router = Router::new()
190        .merge(health::router())
191        .merge(keda::router())
192        .nest("/v1/", routes_v1);
193
194    std::cfg_select! {
195        all(target_os = "linux", feature = "profiling") => {
196            router.merge(profiling::router())
197        }
198        _ => { router }
199    }
200}