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
//! [`SimShared`]: the per-sim services every backend, tester and outside controller reaches
//! through one `Arc`, and how a thread finds the sim it runs in.
use std::net::SocketAddr;
use std::sync::atomic::{AtomicBool, AtomicU16, AtomicU64, Ordering};
use std::sync::{Arc, Mutex, OnceLock};
use std::time::Duration;
use snare_interpose::WeakDomain;
use crate::clock::Clock;
use crate::dns::Hosts;
use crate::events::{EventLog, RecordedEvent};
#[cfg(unix)]
use crate::fabric as peer;
use crate::faults::BehaviorTable;
use crate::limits::SysConfig;
use crate::netif::Topology;
use crate::netpolicy::{Policies, TcpPolicy, UdpPolicy};
use crate::netstats::ProtoStats;
use crate::pcapng::Capture;
use crate::signals::SignalTable;
use crate::sockets::SocketTable;
#[cfg(windows)]
use crate::win_net as peer;
/// The low end of the IANA dynamic/private port range 49152–65535 (RFC 6335 §6). It is also the
/// macOS and Windows default: XNU bsd/netinet/in_pcb.c `ipport_firstauto = IPPORT_HIFIRSTAUTO`
/// (bsd/netinet/in.h), and
/// [Microsoft Learn: The default dynamic port range for TCP/IP has changed since Windows Vista](https://learn.microsoft.com/en-us/troubleshoot/windows-server/networking/default-dynamic-port-range-tcpip-chang).
/// Linux defaults to 32768–60999 instead (Documentation/networking/ip-sysctl.rst,
/// `ip_local_port_range`); snare uses the IANA range on every OS so runs match across them.
pub(crate) const EPHEMERAL_FIRST: u16 = 49152;
/// The services one [`Sim`](crate::Sim) shares across its backends, its testers and the threads
/// that control it from outside.
pub(crate) struct SimShared {
/// The sim's seed, from which its policies' randomness derives.
pub(crate) seed: u64,
/// `None` for a sim on the real clock without a virtual host clock.
pub(crate) clock: Option<Arc<Clock>>,
pub(crate) policies: Policies,
#[cfg(target_os = "linux")]
pub(crate) rx_timestamp_startup: crate::tstamp::RxStartup,
pub(crate) events: EventLog,
/// The next port [`ephemeral_port`](Self::ephemeral_port) hands out.
next_ephemeral: AtomicU16,
/// The next [`bind_order`](Self::bind_order).
next_bind: AtomicU64,
/// The sim's domain, set once it is created; weak so the shared state never keeps it alive.
pub(crate) domain: OnceLock<WeakDomain>,
/// [`real_now`](crate::readiness::real_now) when the sim was built: the zero of its timeline
/// with no virtual clock.
real_origin: Duration,
/// An [`Executive`](crate::sched::Executive) owns the clock.
pub(crate) executive: AtomicBool,
pub(crate) sockets: SocketTable,
pub(crate) topology: Mutex<Topology>,
pub(crate) dns: Hosts,
pub(crate) signals: SignalTable,
pub(crate) sys: SysConfig,
/// How each TCP listening address answers connects
/// ([`set_listener_behavior`](crate::faults::set_listener_behavior)).
pub(crate) listener_behavior: BehaviorTable,
/// The pcapng capture, once one is started.
pub(crate) capture: OnceLock<Arc<Capture>>,
/// The host's protocol counters, shared with every socket record.
pub(crate) stats: Arc<ProtoStats>,
/// [`SimBuilder::strict_sockopts`](crate::SimBuilder::strict_sockopts): an option or ioctl the
/// sim does not model fails rather than succeeding without effect. Set before the sim runs.
pub(crate) strict_sockopts: AtomicBool,
/// The first strict refusal was written to stderr.
pub(crate) strict_reported: AtomicBool,
/// The pipes the sim's threads made.
#[cfg(unix)]
pub(crate) pipes: crate::realfd::Pipes,
}
impl SimShared {
/// The shared services of a new sim seeded with `seed`, on `clock` (`None` for the real clock).
pub(crate) fn new(seed: u64, clock: Option<Arc<Clock>>) -> Arc<Self> {
// Initialised outside any domain: a hooked wait inside its lazy initialisation would
// re-enter it from the hook.
crate::readiness::readiness();
Arc::new_cyclic(|me| SimShared {
seed,
clock,
policies: Policies::with_seed(seed),
#[cfg(target_os = "linux")]
rx_timestamp_startup: crate::tstamp::RxStartup::default(),
events: EventLog::new(),
next_ephemeral: AtomicU16::new(EPHEMERAL_FIRST),
next_bind: AtomicU64::new(1),
domain: OnceLock::new(),
real_origin: crate::readiness::real_now(),
executive: AtomicBool::new(false),
sockets: SocketTable::new(),
topology: Mutex::new(Topology::new(me.clone())),
dns: Hosts::default(),
signals: SignalTable::new(),
sys: SysConfig::new(),
listener_behavior: BehaviorTable::default(),
capture: OnceLock::new(),
stats: Arc::default(),
strict_sockopts: AtomicBool::new(false),
strict_reported: AtomicBool::new(false),
#[cfg(unix)]
pipes: crate::realfd::Pipes::default(),
})
}
/// When something happened, on the sim's own timeline: sim time, read without ticking, or real
/// time since the sim was built when it has no virtual clock.
pub(crate) fn stamp(&self) -> Duration {
timeline(self.clock.as_deref(), self.real_origin)
}
/// Real time when the sim was built (see the field).
pub(crate) fn real_origin(&self) -> Duration {
self.real_origin
}
/// Appends `event` to the sim's log. Never charges time, yields, registers a timer or wakes
/// anything, so recording cannot change the run.
pub(crate) fn record(&self, event: RecordedEvent) {
if self.events.enabled() {
self.events.push(|| self.stamp(), event);
}
}
/// As [`record`](Self::record), for an event that happened `ago` before now.
pub(crate) fn record_ago(&self, ago: Duration, event: RecordedEvent) {
if self.events.enabled() {
self.events.push(|| self.stamp().saturating_sub(ago), event);
}
}
/// Changes the UDP policy for `addr` and records the result.
pub(crate) fn update_udp_policy(&self, addr: SocketAddr, change: impl FnOnce(&mut UdpPolicy)) {
let policy = self.policies.update(addr, change);
self.record(RecordedEvent::UdpPolicyChanged { addr, policy });
}
/// Changes the TCP policy for `addr` and records the result.
pub(crate) fn update_tcp_policy(&self, addr: SocketAddr, change: impl FnOnce(&mut TcpPolicy)) {
let policy = self.policies.update_tcp(addr, change);
self.record(RecordedEvent::TcpPolicyChanged { addr, policy });
}
/// Wakes everything that waits on the sim after a change made from any thread: blocked
/// waiters re-check, and a deterministic schedule hands the baton on. Called with no sim lock
/// held.
pub(crate) fn kick(&self) {
snare_interpose::real(|| {
if let Some(clock) = &self.clock {
clock.wake_due();
}
crate::readiness::readiness().bump(self.domain_key());
if let Some(domain) = self.domain.get().and_then(WeakDomain::upgrade) {
domain.kick_after_readiness();
}
});
}
/// As [`kick`](Self::kick) after an unpark of the thread whose park waits on `key`: of the
/// waits outside a deterministic schedule only that park is woken, along with any other whose
/// token is set; a deterministic schedule is kicked as by [`kick`](Self::kick).
pub(crate) fn kick_parked(&self, key: crate::readiness::WakeKey) {
snare_interpose::real(|| {
if let Some(clock) = &self.clock {
clock.wake_due();
}
let domain = self.domain_key();
crate::readiness::readiness().bump_keys_unscheduled(domain, &[key]);
self.kick_schedule(domain);
});
}
/// As [`kick`](Self::kick) after an executive moved the clock: of the waits outside a
/// deterministic schedule only those the clock's reading reached, those every clock move
/// concerns and those already unparked are woken; a deterministic schedule is kicked as by
/// [`kick`](Self::kick).
pub(crate) fn kick_clock(&self) {
snare_interpose::real(|| {
let domain = self.domain_key();
match &self.clock {
Some(clock) => {
clock.wake_due();
crate::readiness::readiness().bump_due_unscheduled(domain, clock.peek());
}
None => crate::readiness::readiness().bump_time_unscheduled(domain),
}
self.kick_schedule(domain);
});
}
/// The deterministic half of [`kick`](Self::kick): the schedule's readiness waits re-check and
/// the domain's layers release what the clock reached.
fn kick_schedule(&self, domain: usize) {
if domain == 0 || domain == snare_interpose::domain_key() {
snare_interpose::det_wake_readiness(snare_interpose::ReadinessWake::All);
}
if let Some(domain) = self.domain.get().and_then(WeakDomain::upgrade) {
domain.kick_after_readiness();
}
}
pub(crate) fn kick_keys(&self, keys: &[crate::readiness::WakeKey]) {
snare_interpose::real(|| {
if let Some(clock) = &self.clock {
clock.wake_due();
}
self.bump_keys(keys);
if let Some(domain) = self.domain.get().and_then(WeakDomain::upgrade) {
domain.kick();
}
});
}
/// The sim's [`Domain::key`](snare_interpose::Domain::key), which every readiness bump for a
/// change to its state names; 0 before the domain is installed, when no thread waits in it
/// and a bump reaches every domain.
pub(crate) fn domain_key(&self) -> usize {
self.domain.get().map_or(0, WeakDomain::key)
}
pub(crate) fn bump_keys(&self, keys: &[crate::readiness::WakeKey]) {
crate::readiness::readiness().bump_keys(self.domain_key(), keys);
}
#[cfg(windows)]
pub(crate) fn bump(&self) {
crate::readiness::readiness().bump(self.domain_key());
}
/// Panics while an executive owns the clock: only it may move time then.
#[track_caller]
pub(crate) fn assert_clock_free(&self) {
assert!(
!self.executive.load(Ordering::Acquire),
"this Sim's clock is owned by an Executive; move time through it"
);
}
/// The next ephemeral TCP port of this sim, for an unbound connect or a bind to port 0,
/// cycling through 49152..=65535 ([`EPHEMERAL_FIRST`]). Sequential rather than randomised, so
/// runs replay.
#[allow(deprecated)]
pub(crate) fn ephemeral_port(&self) -> u16 {
let next = |port: u16| Some(port.checked_add(1).unwrap_or(EPHEMERAL_FIRST));
self.next_ephemeral
.fetch_update(Ordering::Relaxed, Ordering::Relaxed, next)
.unwrap_or(EPHEMERAL_FIRST)
}
/// The next number in the order sockets and testers take addresses in, which decides which of
/// several sharing an address receives ([`crate::netif::Cand::order`]).
pub(crate) fn bind_order(&self) -> u64 {
self.next_bind.fetch_add(1, Ordering::Relaxed)
}
/// A handle to the sim's clock. Panics on a sim without a virtual clock.
#[track_caller]
pub(crate) fn time(self: &Arc<Self>) -> crate::TimeHandle {
let Some(clock) = &self.clock else {
panic!(
"this Sim runs on the real clock (SimBuilder::wall_clock); build it with \
time_rate(1.0) for a controllable clock that tracks real time"
);
};
crate::TimeHandle {
clock: clock.clone(),
shared: self.clone(),
}
}
}
/// A stamp on a sim's timeline: `clock`'s sim time, read without ticking, or real time since
/// `real_origin` without one.
pub(crate) fn timeline(clock: Option<&Clock>, real_origin: Duration) -> Duration {
match clock {
Some(clock) => clock.value(),
None => crate::readiness::real_now().saturating_sub(real_origin),
}
}
/// The shared services of the sim the calling thread runs in. Panics off a sim.
#[track_caller]
pub(crate) fn here() -> Arc<SimShared> {
match try_here() {
Some(shared) => shared,
None => panic!("must be called from a thread running inside Sim::run"),
}
}
/// The shared services of the sim the calling thread runs in, if it runs in one.
pub(crate) fn try_here() -> Option<Arc<SimShared>> {
peer::try_registries_here().map(|regs| regs.shared.clone())
}