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
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
//! Escaping for free-form values carried in HTTP headers.
//!
//! HTTP header values carry only visible ASCII, so any value that may contain arbitrary Unicode —
//! an object key, a filename, a custom metadata value — has to be escaped to survive the
//! transport. This module owns that escaping for the whole workspace: it is the only place that
//! depends on [`percent_encoding`], so callers escape by name rather than by assembling a
//! character set of their own.
//!
//! Encoding is a property of the *transport*, never of the value: everything in memory holds the
//! logical string, and [`encode_header_value`] is applied only when writing a header.
use Cow;
use fmt;
use Utf8Error;
use HeaderValue;
use ToStrError;
use ;
/// The characters escaped when a free-form value is written into a header value.
///
/// Non-ASCII bytes are escaped by the encoder itself; this set adds the C0 controls and `DEL`,
/// which a header value cannot carry, plus `%` so that a literal percent sign can never be
/// confused with an escape sequence when decoding.
///
/// Every other visible ASCII character is left alone, which keeps values that are already plain
/// ASCII byte-identical to their logical form on the wire.
const HEADER_ESCAPE: &AsciiSet = &CONTROLS.add;
/// The characters escaped in an [RFC 8187] `ext-value`.
///
/// This is the complement of the spec's `attr-char` production: alphanumerics plus a handful of
/// symbols survive, everything else — including the non-ASCII bytes this exists for — is escaped.
///
/// [RFC 8187]: https://www.rfc-editor.org/rfc/rfc8187
const EXT_VALUE_ESCAPE: &AsciiSet = &NON_ALPHANUMERIC
.remove
.remove
.remove
.remove
.remove
.remove
.remove
.remove
.remove
.remove
.remove
.remove;
/// Escapes a logical string into a header value.
///
/// This is the inverse of [`decode_header_value`]. Escaping cannot fail — the result is always
/// visible ASCII — so this returns the [`HeaderValue`] directly rather than a string a caller has
/// to parse and handle the impossible error of.
///
/// # Examples
///
/// ```
/// use objectstore_types::headers::encode_header_value;
///
/// assert_eq!(encode_header_value("report.pdf"), "report.pdf");
/// assert_eq!(encode_header_value("réport.pdf"), "r%C3%A9port.pdf");
/// assert_eq!(encode_header_value("100% done"), "100%25 done");
/// ```
/// Escapes a logical string for a transport that is not an HTTP header.
///
/// Use this where the escaped form is needed as a string rather than a header — notably GCS object
/// metadata, which is written as JSON but has to match what the `x-goog-meta-*` headers carry.
/// Where the target *is* a header, prefer [`encode_header_value`].
///
/// Values that are already plain ASCII are returned borrowed and unchanged.
///
/// # Examples
///
/// ```
/// use objectstore_types::headers::encode_header_str;
///
/// assert_eq!(encode_header_str("report.pdf"), "report.pdf");
/// assert_eq!(encode_header_str("réport.pdf"), "r%C3%A9port.pdf");
/// ```
/// The reasons a header value can fail to decode into a logical string.
/// Decodes a header value into the logical string it carries.
///
/// This is the inverse of [`encode_header_value`], and the counterpart most callers want: it
/// covers both ways a raw header can fail to be a logical string, so there is no separate
/// [`HeaderValue::to_str`] step to handle. Decoding does not depend on how aggressively the writer
/// escaped, so values written by older peers — or with a different escape set — read back
/// unchanged.
///
/// Callers are expected to wrap the error in one of their own that names the header at fault.
///
/// # Examples
///
/// ```
/// use http::HeaderValue;
/// use objectstore_types::headers::decode_header_value;
///
/// let value = HeaderValue::from_static("r%C3%A9port.pdf");
/// assert_eq!(decode_header_value(&value)?, "réport.pdf");
/// # Ok::<(), objectstore_types::headers::DecodeError>(())
/// ```
/// Decodes an escaped string back into its logical form.
///
/// Use this for escaped values that do not arrive in an actual header — notably GCS object
/// metadata, which is read back as JSON. Where the value *is* a header, prefer
/// [`decode_header_value`], which also rejects raw bytes outside visible ASCII.
///
/// # Examples
///
/// ```
/// use objectstore_types::headers::decode_header_str;
///
/// assert_eq!(decode_header_str("r%C3%A9port.pdf")?, "réport.pdf");
/// assert_eq!(decode_header_str("100%25 done")?, "100% done");
/// assert!(decode_header_str("%FF.pdf").is_err());
/// # Ok::<(), std::str::Utf8Error>(())
/// ```
/// Decodes percent-escapes in a string without ever failing.
///
/// A `%` not followed by two hex digits stays literal, and escaped bytes that are not valid UTF-8
/// become `U+FFFD`. Use [`decode_header_str`] where invalid input should be an error.
///
/// # Examples
///
/// ```
/// use objectstore_types::headers::decode_header_str_lossy;
///
/// assert_eq!(decode_header_str_lossy("a%3Ab"), "a:b");
/// assert_eq!(decode_header_str_lossy("100%"), "100%");
/// assert_eq!(decode_header_str_lossy("a%FFb"), "a\u{FFFD}b");
/// ```
/// A logical string wrapped for use as an [RFC 8187] `ext-value`, in header parameters like
/// `Content-Disposition`'s `filename*`.
///
/// The string is escaped lazily as this is displayed, so a caller can write it straight into a
/// header it is already building instead of allocating an intermediate string. The output includes
/// the charset prefix, so it goes directly after the `=` of a header parameter.
///
/// Unlike [`encode_header_value`], this escapes everything outside a narrow `attr-char` set,
/// because an `ext-value` sits inside a header parameter rather than spanning a whole value.
///
/// [RFC 8187]: https://www.rfc-editor.org/rfc/rfc8187
///
/// # Examples
///
/// ```
/// use objectstore_types::headers::ExtValue;
///
/// assert_eq!(ExtValue("réport.pdf").to_string(), "UTF-8''r%C3%A9port.pdf");
/// ```
;