Skip to main content

ash_jsonapi/
jsonl.rs

1//! JSON Lines: one resource per line, streamed as rows arrive.
2//!
3//! A JSON:API collection document is a single value: the closing bracket
4//! cannot be written until the last row is known, so the whole page is held
5//! in memory and the client waits for all of it. That is the right trade for
6//! a page of twenty-five. It is the wrong one for an export of a million
7//! rows, where the document never fits in memory on either end.
8//!
9//! JSONL inverts it. Each line is a complete resource object, so the server
10//! writes a row and forgets it, and the client parses a row and acts on it —
11//! neither holds more than one at a time, and the first row arrives in
12//! milliseconds rather than after the last one is found.
13//!
14//! ```text
15//! {"type":"todo","id":"t_1","attributes":{"message":"buy milk"}}
16//! {"type":"todo","id":"t_2","attributes":{"message":"write docs"}}
17//! ```
18//!
19//! # Asking for it
20//!
21//! `Accept: application/jsonl` on the ordinary collection URL. There is no
22//! second route: the collection is one resource, and how it is rendered is
23//! what `Accept` is for — so a cache keyed on `Vary: Accept` already knows
24//! these are two representations of one thing.
25//!
26//! Anything else — including no `Accept` at all — gets the JSON:API document,
27//! so this cannot change what an existing client receives.
28//!
29//! # What is lost
30//!
31//! A JSONL response carries no `links`, no `meta` and no `included`: there is
32//! no document to hang them on. It is a row stream, not a document, and a
33//! client that needs pagination links should ask for the document instead.
34//! Errors are the exception — see [`ERROR_LINE`].
35
36/// The media type: `application/jsonl`.
37///
38/// `application/x-ndjson` is the other name in the wild and is accepted on
39/// the way in, but this is what is sent back.
40pub const MEDIA_TYPE: &str = "application/jsonl";
41
42/// The other spelling clients use for the same thing.
43pub const MEDIA_TYPE_NDJSON: &str = "application/x-ndjson";
44
45/// Whether an `Accept` header asks for JSONL.
46///
47/// True when JSONL is named *and* is at least as preferred as any JSON:API
48/// alternative in the same header. A client that sends
49/// `application/vnd.api+json, application/jsonl;q=0.5` prefers the document
50/// and gets it; one that sends only `application/jsonl` gets lines.
51///
52/// ```
53/// use ash_jsonapi::jsonl::wants_jsonl;
54///
55/// assert!(wants_jsonl(Some("application/jsonl")));
56/// assert!(wants_jsonl(Some("application/x-ndjson")));
57///
58/// // The document is the default, in every ambiguous case.
59/// assert!(!wants_jsonl(None));
60/// assert!(!wants_jsonl(Some("*/*")));
61/// assert!(!wants_jsonl(Some("application/vnd.api+json")));
62///
63/// // Explicit `q` decides when both are named.
64/// assert!(!wants_jsonl(Some("application/vnd.api+json, application/jsonl;q=0.5")));
65/// assert!(wants_jsonl(Some("application/vnd.api+json;q=0.2, application/jsonl")));
66/// ```
67pub fn wants_jsonl(accept: Option<&str>) -> bool {
68    let Some(accept) = accept else {
69        return false;
70    };
71
72    let mut jsonl = None::<f32>;
73    let mut document = None::<f32>;
74
75    for entry in accept.split(',') {
76        let mut parts = entry.split(';');
77        let Some(kind) = parts.next().map(str::trim) else {
78            continue;
79        };
80
81        let quality = parts
82            .find_map(|part| part.trim().strip_prefix("q=")?.trim().parse::<f32>().ok())
83            .unwrap_or(1.0);
84
85        // `q=0` means "not acceptable", so it never selects anything.
86        if quality <= 0.0 {
87            continue;
88        }
89
90        let slot = if kind.eq_ignore_ascii_case(MEDIA_TYPE)
91            || kind.eq_ignore_ascii_case(MEDIA_TYPE_NDJSON)
92        {
93            &mut jsonl
94        } else if kind.eq_ignore_ascii_case(crate::document::MEDIA_TYPE) {
95            &mut document
96        } else {
97            // `*/*` and everything else leave the default alone: a client
98            // that expresses no preference gets the document.
99            continue;
100        };
101
102        if slot.is_none_or(|best| quality > best) {
103            *slot = Some(quality);
104        }
105    }
106
107    match (jsonl, document) {
108        (None, _) => false,
109        // Named alone, or preferred over the document. Ties go to JSONL,
110        // since naming it at all is a deliberate act.
111        (Some(lines), None) => lines > 0.0,
112        (Some(lines), Some(doc)) => lines >= doc,
113    }
114}
115
116/// Whether a request body is JSONL, from its `Content-Type`.
117///
118/// The ingest-side counterpart of [`wants_jsonl`]: that one reads `Accept`
119/// and decides how to *render* a collection, this one reads `Content-Type`
120/// and decides how to *read* a body. Both spellings are accepted, and
121/// parameters after the type are ignored, so `application/jsonl;
122/// charset=utf-8` is the same media type.
123///
124/// A `POST` that is not JSONL is an ordinary single-resource create — which
125/// is what keeps [`INGEST`](crate::api!) additive: routing it cannot change
126/// what an existing client sends.
127///
128/// ```
129/// use ash_jsonapi::jsonl::is_jsonl_request;
130///
131/// assert!(is_jsonl_request(Some("application/jsonl")));
132/// assert!(is_jsonl_request(Some("application/x-ndjson")));
133/// assert!(is_jsonl_request(Some("application/jsonl; charset=utf-8")));
134///
135/// // Anything else is a single create, including the JSON:API media type.
136/// assert!(!is_jsonl_request(None));
137/// assert!(!is_jsonl_request(Some("application/vnd.api+json")));
138/// ```
139pub fn is_jsonl_request(content_type: Option<&str>) -> bool {
140    let Some(content_type) = content_type else {
141        return false;
142    };
143
144    let media_type = content_type.split(';').next().unwrap_or_default().trim();
145
146    media_type.eq_ignore_ascii_case(MEDIA_TYPE)
147        || media_type.eq_ignore_ascii_case(MEDIA_TYPE_NDJSON)
148}
149
150/// The member carrying an input line's 1-based number on a result line.
151///
152/// A batch of a hundred thousand lines that reports a failure without saying
153/// *which* line failed is not actionable: the client cannot map the error
154/// back onto its input. Every error line an ingest emits carries this under
155/// the error object's `meta`, so a client can retry exactly the rows that did
156/// not land.
157///
158/// ```text
159/// {"errors":[{"status":"422","code":"invalid_attribute","meta":{"line":2}}]}
160/// ```
161pub const LINE_MEMBER: &str = "line";
162
163/// The shape of a failure that happens *after* the first line is sent.
164///
165/// A streamed response commits to `200 OK` with its first byte, so a row that
166/// fails halfway through cannot change the status — the client has already
167/// been told the request succeeded. Truncating silently would leave a partial
168/// export indistinguishable from a complete one, which is the worst outcome:
169/// the client keeps data it believes is whole.
170///
171/// So the stream ends with one line carrying this member, and a client must
172/// treat its presence as failure however many rows preceded it:
173///
174/// ```text
175/// {"type":"todo","id":"t_1",…}
176/// {"errors":[{"status":"500","code":"internal","title":"Internal server error"}]}
177/// ```
178///
179/// This is why the last line has to be checked rather than the status.
180pub const ERROR_LINE: &str = "errors";