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