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
//! The opaque spelling: base64url, no padding.
//!
//! # Why the crate writes it rather than taking one
//!
//! `store::fs` already writes RFC 4648 base32 for the same class of reason — a rendering the crate
//! must be able to state exactly, in both directions, and keep stating the same way for as long as
//! the values it renders are durable. A cursor outlives the process that minted it, so the encoder
//! and the decoder here are one authority and a dependency would be a second one under someone
//! else's release schedule. It is thirty lines.
//!
//! # Base64url and not base64, and no padding
//!
//! RFC 4648 §5's alphabet: `-` and `_` where §4 has `+` and `/`, so a cursor is a URL query
//! parameter, a JSON string and a header value with nothing to escape at any of them. `=` padding
//! is not written — a cursor's length is carried by the string itself — and it is REFUSED coming
//! back rather than tolerated, for the reason the base32 renderer states about its own prefix: two
//! spellings of one cursor is one spelling too many.
//!
//! # This is not the NO-JSON law's exception
//!
//! The law is about the CHANNEL a typed value travels: elements ride typed columns or typed rows,
//! never a JSON text encoding. Base64url is a transfer encoding over the framework's own frame —
//! it re-spells bytes and reads nothing inside them — where a JSON cursor would be a second
//! schema, a second parser and a second set of type coercions between the values and the columns
//! they are compared against.
/// The RFC 4648 §5 alphabet.
const BASE64URL: & = b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
/// `bytes` as base64url with no padding.
pub
/// The bytes `text` spells, or [`None`] where it is not this alphabet, this padding and this
/// grouping.
///
/// # Three refusals, and the third is the one a lenient decoder gets wrong
///
/// A symbol outside the alphabet — `=` included, so padding is refused rather than skipped. A final
/// group of ONE symbol, which no encoding of any byte string produces: six bits is not a byte, and
/// a decoder that dropped them would accept two spellings of the same cursor. And any group whose
/// unused low bits are not zero, for the same reason — `QQ` and `QR` would otherwise both decode to
/// `A`.
pub
/// The six bits `symbol` stands for, or [`None`] where it is not in the alphabet.
///
/// A linear scan of 64 bytes rather than a table: a cursor is decoded once per request and the
/// table would be a second statement of the alphabet, which is the thing that has to be right.