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
//! The `DogConfig` derive, and nothing else.
//!
//! A dog (a plugin process the shepherd supervises) publishes a JSON Schema
//! for its own config so shep can render a settings pane for it. One kind of
//! field needs marking: a credential, such as the webhook URL in a bark sink,
//! which a pane shows as `<set>` rather than as its value.
//!
//! `schemars` can express that by hand, with
//! `#[schemars(extend("x-shep-secret" = true))]`. This crate exists because
//! `x-shep-secret` is then a string the author types: transpose two of its
//! letters and it compiles, the schema validates, the field is not marked,
//! and the credential is painted on screen. Nothing fails and nothing warns.
//! It cannot be linted either, because `schemars` takes a string literal for
//! the extension key, so no exported constant can go in that position. The
//! derive is what turns that into a compile error.
//!
//! Depend on `shep-client`, not on this crate directly. It re-exports the
//! derive next to the `DogConfig` trait the derive implements, so a dog takes
//! one dependency.
use TokenStream;
use TokenStream as TokenStream2;
use quote;
use ;
/// The attribute this derive claims. Only `#[shep(secret)]` is spelled with
/// it today.
const ATTR: &str = "shep";
/// The one option `#[shep(...)]` accepts.
const SECRET: &str = "secret";
/// Marks which of a dog's config fields are credentials, so shep can redact
/// them without the dog author ever typing the extension key that says so.
///
/// Derive it on the type a dog deserializes its config into, alongside
/// `schemars::JsonSchema`, and mark each credential field with
/// `#[shep(secret)]`. A struct and an enum both work, and the enum matters:
/// a bark sink is one, tagged by kind, with a webhook URL in every variant.
///
/// ```rust
/// use shep_client::dogs::DogConfig;
///
/// #[derive(serde::Deserialize, schemars::JsonSchema, DogConfig)]
/// #[serde(tag = "kind", rename_all = "snake_case")]
/// enum Sink {
/// Discord {
/// #[shep(secret)]
/// url: String,
/// },
/// Slack {
/// #[shep(secret)]
/// url: String,
/// },
/// }
///
/// // One name, not two: see below.
/// assert_eq!(Sink::SECRET_FIELDS, ["url"]);
/// ```
///
/// That example runs, which needs `shep-client` as a dev-dependency of this
/// crate: a cycle on paper, allowed because dev-dependencies sit outside the
/// library build graph. The derive's behaviour is tested in `shep-client`,
/// where the marking happens and where a real schema can be looked at.
///
/// # What it expands to
///
/// An `impl shep_client::dogs::DogConfig`, carrying the names of the marked
/// fields and the extension key that marks them. The key comes from
/// `shep_core::dogs::SECRET_KEY` by way of `shep_client`'s re-export, so it is
/// never spelled out here or in the dog:
///
/// ```rust,ignore
/// impl ::shep_client::dogs::DogConfig for Sink {
/// const SECRET_KEY: &'static str = ::shep_client::dogs::SECRET_KEY;
/// const SECRET_FIELDS: &'static [&'static str] = &["url"];
/// }
/// ```
///
/// One `"url"`, not two, for the two variants above: the list is names, and a
/// name repeated across variants is one name. The schema `schemars` builds
/// for a tagged enum is a `oneOf` of one object per variant, each with its own
/// `properties`, so whatever marks a field has to reach every occurrence of
/// the name rather than a single top-level property.
///
/// # Renames
///
/// A field is named here by its Rust identifier. A `#[serde(rename)]` on a
/// marked field changes what the schema calls it, and the marker would then
/// have no property to land on. That is caught where the marking happens, in
/// `shep_client`, which refuses a name it cannot find rather than passing an
/// unmarked credential on.
///
/// A `#[serde(rename_all)]` on a tagged enum renames the VARIANTS, not their
/// fields, so a `url` inside one stays `url`. Measured against `schemars`
/// 1.2.2 rather than assumed.
///
/// # Compile errors
///
/// Deliberate refusals, each with its own message:
///
/// - `#[shep(secret)]` on a field with no name, in a tuple struct or a tuple
/// variant, where a schema has no named property for it to mark;
/// - `#[shep(...)]` on the type or on a variant, neither of which is a field;
/// - a union, which has no serde representation to build a schema from;
/// - any option other than `secret`, which is the misspelling this crate is
/// here to catch.
///
/// Everything else is accepted and simply carries no marks: a struct or a
/// variant with no fields, an unmarked tuple, an enum of plain unit variants.
/// A dog whose config holds no credential still wants the impl.
/// The derive's whole body, in a form that can return an error instead of
/// a token stream.
/// Every field the type has, a struct's directly and an enum's gathered from
/// its variants.
///
/// Shapes that cannot hold a named field are not refused here, only left
/// empty. A unit variant has nothing to mark, and an unmarked tuple is a
/// config type someone wrote for other reasons. What is refused is a mark
/// that cannot land, and [`expand`] does that once it knows which fields
/// carry one, so the rule stays the same wherever the field came from.
/// Whether a field carries `#[shep(secret)]`.
///
/// Repeating the attribute on one field is accepted and marks it once. It is
/// redundant rather than wrong, and a second error message for it would be
/// noise next to the one that matters, which is a misspelled option.
/// The first `#[shep(...)]` in a list, for the places one does not belong.