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}