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
//! RFC 8785 canonical JSON and the content hash.
//!
//! The hub needs one answer to "are these two records the same?" that does
//! not depend on how the client serialised them. RFC 8785 (JSON
//! Canonicalization Scheme) gives it: object keys sorted by UTF-16 code
//! units, no insignificant whitespace, numbers printed the way ECMAScript
//! prints them (`1` not `1.0`, `1e21` not `1000000000000000000000`), strings
//! escaped minimally. Two records that differ only in key order or
//! formatting produce identical bytes.
//!
//! `content_hash = sha256(canonical_bytes)`, hex-encoded. It is stored on
//! every version and used for two things only:
//!
//! - **Idempotency.** A `POST` whose hash equals the latest version's hash
//! returns that version with `200` instead of creating a duplicate.
//! - **Integrity.** `GET` responses carry the hash so a client can verify
//! the body it received is the body that was stored.
//!
//! It is deliberately *not* an address. Versions are addressed by `@{seq}`
//! or `@{label}`; a hash-addressed API would let two names share a version
//! and make tombstoning ambiguous.
//!
//! # Numbers
//!
//! Canonicalisation requires parsing every number as an IEEE 754 double.
//! An integer outside ±2^53 would lose precision silently, so validation
//! rejects it first (`number_too_large`) and the producer sends it as a
//! string. Non-finite values cannot appear in JSON and are not a case.
//!
//! # Why `serde_json_canonicalizer`
//!
//! It implements RFC 8785 including the ECMAScript number formatting (via
//! `ryu-js`), which the simpler "sort keys and strip whitespace" crates do
//! not. Canonical form is a contract with every client that computes the
//! hash locally, so the number formatting has to be exactly the RFC's.
//!
//! # Tests
//!
//! Fixtures in `fixtures/canonical/` pair an input JSON with its expected
//! canonical bytes and hash, including the RFC's own test vectors. A
//! property test asserts that canonicalising a value, re-parsing it, and
//! canonicalising again is a fixed point.
use fmt;
use FromStr;
use Value;
use ;
/// Failure to produce canonical bytes.
///
/// The only way RFC 8785 serialisation of a `serde_json::Value` fails is
/// through the underlying serialiser (a map with a non-string key cannot
/// occur in a `Value`, so in practice this is unreachable for values parsed
/// from JSON text). It is surfaced rather than unwrapped because the hash of
/// a partially written buffer must never be stored.
/// The sha256 of a record's canonical bytes.
///
/// Thirty-two bytes, shown as sixty-four lower-case hex characters. Used
/// for idempotency and integrity only; never as an address (see the module
/// doc).
;
/// A hex string that is not a sha256 digest.
;
/// Serialise `value` as RFC 8785 canonical JSON.
///
/// Deterministic: the same value in any key order yields the same bytes.
/// Cost is one pass over the value plus a sort of each object's keys.
/// Numbers are printed as ECMAScript prints them (`1` not `1.0`); the
/// caller is responsible for having rejected integers outside ±2^53
/// beforehand (`validate`, M2), because past that point the double they
/// become is not the integer the client sent.
///
/// # Errors
///
/// [`CanonicalError::Serialize`] if the serialiser fails; not expected for
/// a `Value` built from JSON text.
/// sha256 over canonical bytes. Infallible; O(n) in the input.
/// [`canonicalize`] then [`content_hash`], returning both, since every
/// caller that wants the hash also stores the bytes.
///
/// # Errors
///
/// Same as [`canonicalize`].