Skip to main content

ash_jsonapi/
extract.rs

1//! Getting a request's body into your own types.
2//!
3//! A handler should receive one [`Context`] carrying everything the request
4//! turned into, not a widening tuple of extractors. [`FromRequest`] is where
5//! you say how that happens: read the body however you like, produce your
6//! type, and the generated routes attach it to the context for you.
7//!
8//! ```text
9//! impl FromRequest<App> for NewTodo {
10//!     async fn from_request(req: Request, app: &App, ctx: &Context) -> Result<Self, Errors> {
11//!         // The JSON:API path: validate against the resource's schema, then
12//!         // map the document. `validated` does the first half.
13//!         let doc = validated(req, ctx, app.validator("todo")).await?;
14//!         Ok(NewTodo { message: doc["data"]["attributes"]["message"].as_str()… })
15//!     }
16//! }
17//! ```
18//!
19//! Nothing here assumes JSON. A resource whose create body is multipart, or
20//! form-encoded, or a raw upload, implements the same trait and reads the
21//! request its own way.
22
23use axum::extract::Request;
24
25use crate::context::Context;
26use crate::document::MEDIA_TYPE;
27use crate::error::{ErrorCode, JsonApiError};
28use crate::response::Errors;
29
30/// Build `Self` from a request.
31///
32/// Implemented on the type a handler wants — the parsed body, an
33/// authenticated actor, a resolved tenant. Whatever it produces is attached
34/// to the [`Context`] with [`Context::with`], so downstream code reads it
35/// back with [`Context::extract`] rather than threading a parameter.
36///
37/// The `Context` passed in is the request's own, so errors can carry the
38/// correlation id: build them with [`JsonApiError::invalid`] and friends.
39pub trait FromRequest<S>: Sized + Send + Sync + 'static {
40    /// Read the request into `Self`.
41    ///
42    /// Consumes the request, since reading a body is a one-shot operation.
43    /// `state` is your application state, so an implementation can reach the
44    /// validator, a connection pool, or anything else it needs.
45    fn from_request(
46        request: Request,
47        state: &S,
48        ctx: &Context,
49    ) -> impl Future<Output = Result<Self, Errors>> + Send;
50}
51
52/// Check that a request carries a JSON:API body.
53///
54/// JSON:API requires `application/vnd.api+json` on a request with a document,
55/// and `415` when it is absent, so a body sent as `application/json` is
56/// refused rather than guessed at. Parameters after the media type are
57/// allowed through, since a charset is common in the wild.
58///
59/// Called by [`body_text`], so every implementation built on it gets the
60/// check. Call it directly only in a `FromRequest` that reads the body some
61/// other way.
62pub fn check_media_type(request: &Request, ctx: &Context) -> Result<(), Errors> {
63    let content_type = request
64        .headers()
65        .get(axum::http::header::CONTENT_TYPE)
66        .and_then(|value| value.to_str().ok())
67        .unwrap_or_default();
68
69    // `application/vnd.api+json; charset=utf-8` is the same media type.
70    let media_type = content_type.split(';').next().unwrap_or_default().trim();
71
72    if media_type.eq_ignore_ascii_case(MEDIA_TYPE) {
73        return Ok(());
74    }
75
76    Err(
77        JsonApiError::in_request(ErrorCode::UnsupportedMediaType, ctx)
78            .detail(format!(
79                "requests with a body must be sent as `{MEDIA_TYPE}`, not `{media_type}`"
80            ))
81            .into(),
82    )
83}
84
85/// Read a request body as UTF-8 text.
86///
87/// The starting point for most implementations. The media type is checked
88/// first — a body that is not `application/vnd.api+json` is a `415` — and a
89/// body that is not valid UTF-8 is a `422`, both before any parsing.
90pub async fn body_text(request: Request, ctx: &Context) -> Result<String, Errors> {
91    check_media_type(&request, ctx)?;
92
93    let bytes = axum::body::to_bytes(request.into_body(), MAX_BODY)
94        .await
95        .map_err(|err| {
96            // A body that cannot be read is the client's problem — a
97            // disconnect, or one larger than the cap below.
98            JsonApiError::invalid(ctx, format!("could not read the request body: {err}"), "")
99        })?;
100
101    String::from_utf8(bytes.to_vec())
102        .map_err(|_| JsonApiError::invalid(ctx, "the request body is not valid UTF-8", "").into())
103}
104
105/// The largest body [`body_text`] will read: 2 MiB.
106///
107/// A cap is required — without one a client can ask the server to buffer
108/// until it dies. Read the body yourself if a resource legitimately needs
109/// more.
110pub const MAX_BODY: usize = 2 * 1024 * 1024;
111
112/// Read a body and check it against a resource's request schema.
113///
114/// The JSON:API half of [`FromRequest`]: the body is parsed as JSON and
115/// validated against the [`DocumentValidator`](crate::validation::DocumentValidator)
116/// registered for `resource`, so
117/// every structural failure — a missing member, a wrong `type`, an attribute
118/// of the wrong type, malformed linkage — comes back as a complete error
119/// document with a JSON Pointer at each cause.
120///
121/// What is left for the caller is the part a schema cannot express: mapping
122/// the validated document onto its own type.
123///
124/// ```ignore
125/// impl FromRequest<App> for NewTodo {
126///     async fn from_request(req: Request, app: &App, ctx: &Context) -> Result<Self, Errors> {
127///         let doc = validated(req, ctx, app.validator("todo")).await?;
128///         Ok(NewTodo { message: doc["data"]["attributes"]["message"].as_str().unwrap().into() })
129///     }
130/// }
131/// ```
132#[cfg(feature = "validation")]
133#[cfg_attr(docsrs, doc(cfg(feature = "validation")))]
134pub async fn validated(
135    request: Request,
136    ctx: &Context,
137    validator: &crate::validation::DocumentValidator,
138) -> Result<serde_json::Value, Errors> {
139    let body = body_text(request, ctx).await?;
140    validator.parse(&body, ctx).map_err(Errors)
141}
142
143/// The `id` a document addresses, from the request path.
144///
145/// A `PATCH` addresses a row that already exists, and the path's id is
146/// authoritative over anything the body says — so this is what an update's
147/// [`FromRequest`] should use rather than reading `data.id`.
148pub fn path_id(request: &Request) -> Option<&str> {
149    request
150        .extensions()
151        .get::<axum::extract::Path<String>>()
152        .map(|axum::extract::Path(id)| id.as_str())
153}
154
155/// A raw request body — an uploaded file, rather than a JSON:API document.
156///
157/// The counterpart of [`Download`](crate::response::Download) on the way in.
158/// Use it as a resource's [`Create`](crate::crud::Resource::Create) input
159/// when the body *is* the file:
160///
161/// ```ignore
162/// impl Resource<App> for Doc {
163///     type Create = Upload;
164///     type Update = Upload;
165///     // …
166/// }
167///
168/// impl Create<Doc> for App {
169///     async fn create(&self, input: Upload, ctx: &Context) -> Result<Doc, Self::Error> {
170///         Ok(self.store(input.content_type, input.bytes))
171///     }
172/// }
173/// ```
174///
175/// # Limits
176///
177/// The default cap is [`MAX_UPLOAD`], not [`MAX_BODY`]: a file is expected to
178/// be larger than a document. Both exist because an unbounded read is a
179/// denial of service written in one line — a client that can make the server
180/// buffer without limit does not need any other exploit.
181///
182/// Raise or lower it per resource with [`Upload::limited`], and restrict what
183/// may be sent with [`Upload::accepting`].
184#[derive(Debug, Clone)]
185pub struct Upload {
186    /// The bytes, as sent.
187    pub bytes: Vec<u8>,
188    /// The `Content-Type` the client declared.
189    ///
190    /// Taken at the client's word and never sniffed — but see
191    /// [`Upload::accepting`], and note that
192    /// [`Download`](crate::response::Download) sends `nosniff` so a lie here
193    /// cannot become active content in your origin.
194    pub content_type: String,
195}
196
197/// The largest [`Upload`] read by default: 10 MiB.
198pub const MAX_UPLOAD: usize = 10 * 1024 * 1024;
199
200/// The type assumed when a request declares none.
201const DEFAULT_CONTENT_TYPE: &str = "application/octet-stream";
202
203impl Upload {
204    /// Read a request body as an upload, capped at `limit` bytes.
205    ///
206    /// The building block behind the [`FromRequest`] impl; call it directly
207    /// from your own impl to use a different limit:
208    ///
209    /// ```ignore
210    /// impl FromRequest<App> for Avatar {
211    ///     async fn from_request(req: Request, _s: &App, ctx: &Context) -> Result<Self, Errors> {
212    ///         let upload = Upload::limited(req, ctx, 256 * 1024).await?;
213    ///         Ok(Avatar(upload))
214    ///     }
215    /// }
216    /// ```
217    pub async fn limited(request: Request, ctx: &Context, limit: usize) -> Result<Self, Errors> {
218        let content_type = request
219            .headers()
220            .get(axum::http::header::CONTENT_TYPE)
221            .and_then(|value| value.to_str().ok())
222            .unwrap_or(DEFAULT_CONTENT_TYPE)
223            .to_string();
224
225        let bytes = axum::body::to_bytes(request.into_body(), limit)
226            .await
227            .map_err(|_| {
228                // Almost always the cap: `to_bytes` refuses a body over the
229                // limit, and saying so names the actual problem instead of
230                // reporting a generic read failure.
231                JsonApiError::in_request(ErrorCode::InvalidAttribute, ctx).detail(format!(
232                    "the uploaded body could not be read, or exceeds the {limit}-byte limit"
233                ))
234            })?;
235
236        Ok(Self {
237            bytes: bytes.to_vec(),
238            content_type,
239        })
240    }
241
242    /// Read an upload, refusing a media type not in `accepted`.
243    ///
244    /// The check a file endpoint should not be without: an avatar route that
245    /// accepts `text/html` is a stored-XSS vector waiting for someone to
246    /// serve it back inline. Compared against the type alone, so
247    /// `image/png; charset=…` still matches `image/png`.
248    pub async fn accepting(
249        request: Request,
250        ctx: &Context,
251        limit: usize,
252        accepted: &[&str],
253    ) -> Result<Self, Errors> {
254        let upload = Self::limited(request, ctx, limit).await?;
255
256        // Parameters after `;` are not part of the type.
257        let kind = upload
258            .content_type
259            .split(';')
260            .next()
261            .unwrap_or_default()
262            .trim();
263
264        if !accepted
265            .iter()
266            .any(|allowed| allowed.eq_ignore_ascii_case(kind))
267        {
268            return Err(
269                JsonApiError::in_request(ErrorCode::UnsupportedMediaType, ctx)
270                    .detail(format!(
271                        "`{kind}` is not accepted here; send one of {}",
272                        accepted
273                            .iter()
274                            .map(|allowed| format!("`{allowed}`"))
275                            .collect::<Vec<_>>()
276                            .join(", ")
277                    ))
278                    .into(),
279            );
280        }
281
282        Ok(upload)
283    }
284
285    /// How many bytes were uploaded.
286    pub fn len(&self) -> usize {
287        self.bytes.len()
288    }
289
290    /// Whether the body was empty.
291    pub fn is_empty(&self) -> bool {
292        self.bytes.is_empty()
293    }
294}
295
296/// Reads any request body as an upload, capped at [`MAX_UPLOAD`].
297///
298/// Deliberately does *not* check the media type — an upload is not a JSON:API
299/// document, so the JSON:API media-type check would reject every real file. Use
300/// [`Upload::accepting`] from your own impl when the endpoint should only
301/// take certain types.
302impl<S: Sync> FromRequest<S> for Upload {
303    async fn from_request(request: Request, _state: &S, ctx: &Context) -> Result<Self, Errors> {
304        Self::limited(request, ctx, MAX_UPLOAD).await
305    }
306}
307
308/// The largest single line [`JsonlLines`] will read: 1 MiB.
309///
310/// The cap that matters for an ingest. The *body* is deliberately unbounded —
311/// that is the point of streaming one — so the only thing standing between a
312/// client and unbounded buffering is a limit on how much may arrive with no
313/// newline in it. Without this, `{"a":` repeated forever is a memory
314/// exhaustion attack written in one line.
315#[cfg(feature = "streaming")]
316pub const MAX_LINE: usize = 1024 * 1024;
317
318/// A request body, split into lines as it arrives.
319///
320/// The ingest counterpart of [`Streamed`](crate::response::Streamed): that
321/// writes one resource per line, this reads one document per line. Neither
322/// holds more than a line at a time, so a batch of a million rows costs a
323/// line of memory rather than a million.
324///
325/// Yields the 1-based line number alongside each line, because a per-line
326/// result is only actionable if the client can map it back onto its input —
327/// see [`LINE_MEMBER`](crate::jsonl::LINE_MEMBER).
328///
329/// Blank lines are skipped rather than reported: a trailing newline is how
330/// every JSONL writer ends a file, and calling that a parse error would fail
331/// almost every well-formed batch.
332///
333/// # Failing
334///
335/// Two failures end the stream, both before any row is written: a transport
336/// error, and a line over [`MAX_LINE`]. Both arrive as an `Err` item carrying
337/// the line number, so the handler can render it as that line's result.
338#[cfg(feature = "streaming")]
339#[cfg_attr(docsrs, doc(cfg(feature = "streaming")))]
340pub struct JsonlLines {
341    body: axum::body::BodyDataStream,
342    /// Bytes read but not yet terminated by a newline.
343    buffer: Vec<u8>,
344    /// How many lines have been yielded, so the next carries the right number.
345    line: usize,
346    limit: usize,
347    ctx: Context,
348    done: bool,
349}
350
351#[cfg(feature = "streaming")]
352impl JsonlLines {
353    /// Read a request body as lines, capped at [`MAX_LINE`] per line.
354    pub fn new(request: Request, ctx: &Context) -> Self {
355        Self::limited(request, ctx, MAX_LINE)
356    }
357
358    /// Read a request body as lines, capped at `limit` bytes per line.
359    pub fn limited(request: Request, ctx: &Context, limit: usize) -> Self {
360        Self {
361            body: request.into_body().into_data_stream(),
362            buffer: Vec::new(),
363            line: 0,
364            limit,
365            ctx: ctx.clone(),
366            done: false,
367        }
368    }
369
370    /// Take the next complete line out of the buffer, if there is one.
371    fn take_line(&mut self) -> Option<Vec<u8>> {
372        let newline = self.buffer.iter().position(|byte| *byte == b'\n')?;
373
374        // `drain` leaves the remainder in place, so a frame carrying several
375        // lines is split without reallocating the tail each time.
376        let mut line: Vec<u8> = self.buffer.drain(..=newline).collect();
377        line.pop();
378        // A CRLF writer leaves the carriage return behind.
379        if line.last() == Some(&b'\r') {
380            line.pop();
381        }
382        Some(line)
383    }
384
385    /// The error for a line that exceeded the cap.
386    fn too_long(&self, line: usize) -> JsonApiError {
387        JsonApiError::in_request(ErrorCode::InvalidAttribute, &self.ctx)
388            .detail(format!(
389                "line {line} exceeds the {} -byte limit",
390                self.limit
391            ))
392            .pointer("")
393    }
394}
395
396#[cfg(feature = "streaming")]
397impl futures_core::Stream for JsonlLines {
398    /// The line number, and either its bytes or why it could not be read.
399    type Item = (usize, Result<Vec<u8>, JsonApiError>);
400
401    fn poll_next(
402        mut self: std::pin::Pin<&mut Self>,
403        cx: &mut std::task::Context<'_>,
404    ) -> std::task::Poll<Option<Self::Item>> {
405        use std::task::Poll;
406
407        loop {
408            if self.done {
409                return Poll::Ready(None);
410            }
411
412            // A complete line already buffered is yielded without touching
413            // the body: one frame often carries many lines.
414            if let Some(line) = self.take_line() {
415                self.line += 1;
416                let number = self.line;
417
418                // Blank lines are structural, not data — skip and continue.
419                if line.iter().all(u8::is_ascii_whitespace) {
420                    continue;
421                }
422                return Poll::Ready(Some((number, Ok(line))));
423            }
424
425            // Nothing buffered is a whole line, so the partial one must not
426            // be allowed to grow without bound.
427            if self.buffer.len() > self.limit {
428                self.done = true;
429                let number = self.line + 1;
430                let error = self.too_long(number);
431                return Poll::Ready(Some((number, Err(error))));
432            }
433
434            match std::pin::Pin::new(&mut self.body).poll_next(cx) {
435                Poll::Pending => return Poll::Pending,
436                Poll::Ready(Some(Ok(frame))) => self.buffer.extend_from_slice(&frame),
437                Poll::Ready(Some(Err(_))) => {
438                    // The client went away, or the body was truncated. There
439                    // is no line to blame, so the next one is named.
440                    self.done = true;
441                    self.line += 1;
442                    let number = self.line;
443                    let error = JsonApiError::in_request(ErrorCode::InvalidAttribute, &self.ctx)
444                        .detail("the request body could not be read to the end")
445                        .pointer("");
446                    return Poll::Ready(Some((number, Err(error))));
447                }
448                Poll::Ready(None) => {
449                    self.done = true;
450
451                    // A final line with no trailing newline is still a line.
452                    let rest = std::mem::take(&mut self.buffer);
453                    if rest.iter().all(u8::is_ascii_whitespace) {
454                        return Poll::Ready(None);
455                    }
456                    self.line += 1;
457                    return Poll::Ready(Some((self.line, Ok(rest))));
458                }
459            }
460        }
461    }
462}