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
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
//! Adopting an inherited descriptor — this crate's only `unsafe`
//!
//! **Why unsafe here, and nowhere else.** The daemonization contract (spec
//! §3) is that the CLI re-execs itself detached and the child reports
//! `{pid, version}` on an inherited pipe once the socket is bound. Adopting
//! an inherited descriptor is the one operation std offers no safe path
//! for: `OwnedFd`/`File` can only be built from a raw number through
//! `from_raw_fd`, which is unsafe because nothing in the type system proves
//! the number names a descriptor this process owns.
//!
//! **All of it, confined to this file (IR-22).** [`adopt_fd`] is `unsafe
//! fn`, not a safe fn hiding an internal unsafe block: the ordering
//! precondition that makes adoption sound (call this before the process
//! opens anything of its own — see scenario (c) below) is a CALLER
//! obligation this function cannot verify from inside itself, so the type
//! system pushes it out to whoever calls it. [`crate::boot::BootOptions::ready_fd`]
//! is `Option<`[`std::fs::File`]`>`, an already-owned handle — `boot`
//! itself never calls this function and contains no unsafe of its own (see
//! that field's own doc). The crate's actual unsafe surface today, counted
//! honestly: [`adopt_fd`]'s own definition here, plus this file's own
//! test-only call sites exercising it directly against synthetic fds (see
//! below) — every syntactic site lives in this one file. The intended
//! PRODUCTION caller is the CLI's `main` (Phase 3), a different crate, as
//! its literal first fd-touching statement, before a tokio runtime even
//! exists — not written yet, so it adds no site here today. What actually
//! matters for soundness is unaffected by exactly how many test sites this
//! file accumulates: only a real production call's ordering claim has to
//! hold against a genuinely inherited descriptor; every test site adopts a
//! fd it created itself moments earlier in the same test, which is a
//! narrower, locally-checkable obligation, not a widening of the
//! exception.
//!
//! **The second entry point, [`adopt_handover_fd`], is safe on purpose.**
//! It is [`adopt_fd`] for a handover's successor, and its whole doc is the
//! argument for why the ordering obligation is discharged by the situation
//! rather than by the call site: a descriptor inherited across `execve` is
//! open before the new image runs at all, so the kernel can never hand its
//! number to anything this process opens later. That argument holds for
//! handover descriptors and for nothing else, which is why it is a second,
//! narrowly documented function rather than a relaxation of [`adopt_fd`].
//!
//! **Rejected alternative:** have the parent pass a socket path
//! (`SHEP_READY_SOCK`) and let the child connect and write. It is entirely
//! safe and was the first design. Its cost is a second socket in the boot
//! path — one more thing to place inside 0700, unlink, and recover when
//! stale — to replace a five-line adoption, and it puts the readiness
//! handshake on a different mechanism from the one the spec, systemd
//! `Type=notify` integration, and every comparable supervisor use. Not
//! worth it.
//!
//! **Invariant:** the descriptor was inherited across `exec` from our own
//! parent and is not otherwise owned in this process. **Checked, not
//! assumed:** [`adopt_fd`] refuses anything below fd 3 (stdio is owned
//! elsewhere) and calls `fcntl(fd, F_GETFD)` first, so a closed or
//! never-opened number returns [`SysError::BadFd`] instead of being
//! adopted. **Failure scenarios considered:**
//! (a) a hostile `SHEP_READY_FD=1` — refused by the fd-3 floor, so stdout
//! is never closed underneath the logger;
//! (b) a stale number for a descriptor closed since exec — refused by the
//! `fcntl` probe;
//! (c) a number that has been *recycled* into another live descriptor
//! since exec — this is a REAL hazard, not a theoretical one:
//! `F_GETFD` only proves a number is open RIGHT NOW, never who opened
//! it, so it cannot distinguish a genuinely inherited descriptor from a
//! number the daemon's OWN later steps happened to reuse. Concretely:
//! if adoption ran *after* `bind_socket`/`write_pidfile` had already
//! opened (and, for the pidfile's temp file, closed) descriptors of
//! their own, a stale `SHEP_READY_FD` could land on the freshly-bound
//! listener's own fd, and dropping the wrongly-adopted `File` would
//! close that listener out from under `tokio`. This is exactly why
//! [`adopt_fd`] is `unsafe fn`: the precondition that actually closes
//! this hole — call it before this process has opened any descriptor
//! of its own — is a CALLER obligation no amount of internal checking
//! can verify from inside `adopt_fd` itself, so the type system forces
//! every call site to write down its own justification instead of
//! letting the invariant erode silently on a future reorder. `boot`
//! never calls [`adopt_fd`] at all, so it is not possible for anything
//! `boot` itself does — bind a socket, open a tempfile, install signal
//! handlers — to land between adoption and use. The intended
//! PRODUCTION caller is the CLI's `main` (Phase 3), which discharges
//! the ordering precondition by being the literal first fd-touching
//! statement of the whole process, before a tokio runtime — the thing
//! that would make `boot`'s own attempt at this structurally
//! impossible to guarantee, since `boot` is `async` and a runtime with
//! its own live poller fds necessarily exists before `boot` is ever
//! called — even exists. See [`crate::boot::BootOptions::ready_fd`]'s
//! own doc;
//!
//! (d) double adoption — a future production caller (the CLI's `main`,
//! Phase 3) is expected to call [`adopt_fd`] at most once, consuming
//! the number into an owning [`std::fs::File`] that closes it on drop,
//! so a second production adoption of the same fd should not occur; if
//! it somehow did, scenario (b)'s `BadFd` refusal catches it, since the
//! first adoption already closed the number. (This crate's *tests*
//! call `adopt_fd` directly, and more than once across the suite, each
//! time against a fd the test itself just created — a different,
//! lower-stakes situation than production double-adoption, and not
//! what this scenario is about.)
// IR-24 exception: eight sites total, all in this file (`adopt_fd`'s own definition, `adopt_handover_fd`'s block, and 6 test call sites). `boot.rs` has none; see the essay above and `crate::boot::BootOptions::ready_fd`'s doc.
use fmt;
use File;
use ;
/// Lowest fd number this daemon will ever adopt. 0/1/2 are stdio, owned by
/// the logger and inherited-terminal plumbing elsewhere in the process —
/// adopting one of those into an owning [`File`] would silently steal it out
/// from under whatever already holds it.
pub const RESERVED_FD_FLOOR: RawFd = 3;
/// Whether `fd` is a number this process could adopt at all: not stdio, and
/// open right now.
///
/// [`adopt_fd`]'s two checks and nothing else, split out for the one caller
/// that has to ask the question WITHOUT taking ownership. The predecessor in
/// a handover rehearses its successor's adoption before the `execve` — see
/// `handover::adopt::dry_run` — and a rehearsal that closed the descriptors
/// it was checking would be worse than no rehearsal at all. It asks this
/// rather than keeping a second copy of the same two checks: a copy that
/// drifted lax would pass a blob the successor still refuses, and by then
/// there is no image left to refuse back to.
///
/// Safe, unlike [`adopt_fd`], and the reason is that it takes nothing. That
/// function's `# Safety` section is entirely about who owns the number
/// afterwards, and afterwards this owns nothing, so the recycling hazard has
/// nowhere to land. It asks a question about a number rather than making a
/// claim on one.
///
/// # Errors
/// - [`SysError::ReservedFd`]: `fd` is below 3 (stdio is owned elsewhere).
/// - [`SysError::BadFd`]: `fd` names no open descriptor in this process,
/// which is what a blob naming a descriptor that did not survive the exec
/// looks like.
/// Takes ownership of a descriptor inherited across `exec`.
///
/// # Errors
/// - [`SysError::ReservedFd`] — `fd` is below 3 (stdio is owned elsewhere).
/// - [`SysError::BadFd`] — `fd` names no open descriptor in this process.
///
/// # Safety
///
/// The caller must call this before this process opens (or closes) any
/// descriptor of its own — before binding a socket, opening a file,
/// spawning anything that inherits fds. `F_GETFD` (used internally) only
/// proves a number is CURRENTLY open, never who opened it or what it now
/// names, so calling this after the process has touched its own descriptors
/// risks adopting a number the kernel has since recycled into something the
/// process already owns; dropping the returned [`File`] would then close
/// that resource out from under its real owner instead of the intended
/// inherited pipe. See this module's rationale essay, scenario (c), for a
/// worked example of exactly this happening.
///
/// The intended caller is the CLI's `main` (Phase 3, a different crate —
/// not written yet): its literal first fd-touching statement, before a
/// tokio runtime (or anything else) exists. Nothing in `shep-daemon` calls
/// this function in production today; [`crate::boot::boot`] receives an
/// already-adopted [`std::fs::File`] via
/// [`crate::boot::BootOptions::ready_fd`] and never touches a raw fd
/// itself — see that field's own doc for why adoption moved out of `boot`.
pub unsafe
/// Takes ownership of a descriptor a handover blob names, without the
/// caller having to discharge [`adopt_fd`]'s ordering precondition itself.
///
/// This is [`adopt_fd`] for exactly one situation: the process is a
/// handover's successor, and `fd` is a number its own predecessor wrote
/// into the blob at `$SHEP_HOME/run/handover.json` moments before it
/// `execve`d this image. It is safe to call, and the argument for that is
/// specific to that situation rather than general.
///
/// **Why the recycling hazard cannot arise here.** [`adopt_fd`]'s `#
/// Safety` section exists because `F_GETFD` proves only that a number is
/// open right now, never who opened it, so a stale number could name
/// something this process opened for itself. A descriptor genuinely
/// inherited across `execve` is never in that position: it is already open
/// the instant the new image starts, and the kernel allocates the lowest
/// FREE number, so nothing this process opens afterwards can ever be handed
/// one of them. The ordering obligation `adopt_fd` pushes onto its caller is
/// discharged by the inheritance itself, not by where the call sits.
///
/// **What that leaves.** A blob naming a number that was NOT inherited,
/// one left over from a handover that never completed or one an operator
/// edited, could name a descriptor this process opened. The blob is
/// written mode `0600` inside `$SHEP_HOME/run`, which is `0700`, and it is
/// removed both when an exec fails and once a successor has read it, so it
/// is trusted exactly as far as everything else the daemon reads out of its
/// own home. Do not call this on a descriptor number from anywhere else.
///
/// **One number, one owner.** The argument above is about a number naming
/// the wrong object; a blob naming the SAME number twice would instead build
/// two owners of the right one, and the second drop would close a descriptor
/// the first owner, or a later open, is still using.
/// `handover::adopt::adopt` refuses a repeated number before it adopts
/// anything, so every call that reaches here is the only call for its
/// number.
///
/// # Errors
/// - [`SysError::ReservedFd`]: `fd` is below 3 (stdio is owned elsewhere).
/// - [`SysError::BadFd`]: `fd` names no open descriptor in this process,
/// which is what a blob naming a descriptor that did not survive the exec
/// looks like. Refusing is the whole point: a sheep whose stdout read end
/// is missing does not lose its output, it blocks on `write()` once the
/// pipe buffer fills.
/// Errors adopting an inherited descriptor.
///
/// `#[non_exhaustive]`: today's two variants cover a disqualified fd number
/// and one the OS says is not open, and a future adoption check — rejecting
/// an fd that is open but of the wrong kind, not a socket where one is
/// required — would need its own variant rather than stretching
/// [`Self::BadFd`] past what `fcntl` actually told the caller, and
/// shep-daemon is a published library an out-of-tree matcher should not
/// break for (IR-20).