1use serde::Serialize;
24use std::cell::Cell;
25use std::fs::File;
26use std::io::{Seek, SeekFrom};
27use std::marker::PhantomData;
28use std::os::fd::AsRawFd;
29use std::rc::Rc;
30use std::sync::atomic::{AtomicU64, Ordering};
31
32pub const MAGIC: [u8; 8] = *b"DCLPHEV1";
34pub const SCHEMA_VERSION: u16 = 1;
36pub const RECORD_SIZE: usize = 96;
38pub const MAX_RECORDS: u64 = 16_384;
40const EINTR_RETRIES: u32 = 3;
41
42#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
44#[repr(u8)]
45pub enum EventKind {
46 Header = 1,
48 Enter = 2,
50 Transition = 3,
52 End = 4,
54 Terminal = 5,
56}
57
58#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
60#[repr(u8)]
61pub enum Outcome {
62 None = 0,
64 Ok = 1,
66 Defer = 2,
68 Taint = 3,
70 Eval = 4,
72 Rejected = 5,
74 Incomplete = 6,
76 Unwound = 7,
78 Truncated = 8,
80 Abandoned = 9,
82}
83
84#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
86#[repr(u8)]
87pub enum RootKind {
88 Unknown = 0,
90 Expression = 1,
92 Document = 2,
94}
95
96#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
98pub struct RootIdentity {
99 pub hash: u64,
101 pub utf8_len: u64,
103 pub kind: RootKind,
105}
106impl RootIdentity {
107 pub const NONE: Self = Self {
109 hash: 0,
110 utf8_len: 0,
111 kind: RootKind::Unknown,
112 };
113
114 pub fn new(name: &str, kind: RootKind) -> Self {
117 let mut hash = 14_695_981_039_346_656_037_u64;
118 for byte in name.bytes() {
119 hash ^= u64::from(byte);
120 hash = hash.wrapping_mul(1_099_511_628_211);
121 }
122 Self {
123 hash,
124 utf8_len: name.len() as u64,
125 kind,
126 }
127 }
128}
129
130#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
132#[repr(u8)]
133pub enum StopReason {
134 None = 0,
136 Cap = 1,
138 Clock = 2,
140 Write = 3,
142 ShortWrite = 4,
144 Interrupted = 5,
146 ScopeOrder = 6,
148 Reentrant = 7,
150 Abandoned = 8,
152 OpenScopes = 9,
154 CounterOverflow = 10,
156}
157
158#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize)]
160pub struct Status {
161 pub generation: u64,
163 pub max_records: u64,
165 pub records_written: u64,
167 pub bytes_written: u64,
169 pub last_sequence: u64,
171 pub last_monotonic_ns: u64,
173 pub enabled: bool,
175 pub terminal_written: bool,
177 pub open_scopes: u32,
179 pub stop_reason: StopReason,
182 pub errno: i32,
184}
185
186#[derive(Clone, Copy, Debug, Eq, PartialEq)]
188pub enum InstallError {
189 InvalidLimit,
191 AlreadyInstalled,
193 Busy,
195 ThreadUnavailable,
197 NotEmptyRegularFile,
199 File(i32),
201 GenerationExhausted,
203}
204
205#[derive(Clone, Copy)]
206struct Payload {
207 kind: EventKind,
208 outcome: Outcome,
209 stage: u32,
210 span: u64,
211 parent: u64,
212 ordinal: u64,
213 root: RootIdentity,
214 depth: u32,
215}
216#[derive(Clone, Copy)]
217struct State {
218 fd: i32,
219 pid: u32,
220 status: Status,
221 next_span: u64,
222 current_span: u64,
223}
224struct Local {
225 state: Cell<Option<State>>,
226 busy: Cell<bool>,
227 reentered: Cell<bool>,
228}
229thread_local! {
230 static LOCAL: Local = const { Local {
231 state: Cell::new(None), busy: Cell::new(false), reentered: Cell::new(false),
232 } };
233}
234static NEXT_GENERATION: AtomicU64 = AtomicU64::new(1);
235
236fn os_errno() -> i32 {
237 std::io::Error::last_os_error().raw_os_error().unwrap_or(0)
238}
239fn clock_ns() -> Result<u64, i32> {
240 #[cfg(test)]
241 if test_io::clock_fails() {
242 return Err(libc::EIO);
243 }
244 let mut ts = libc::timespec {
245 tv_sec: 0,
246 tv_nsec: 0,
247 };
248 if unsafe { libc::clock_gettime(libc::CLOCK_MONOTONIC, &mut ts) } != 0 {
250 return Err(os_errno());
251 }
252 if ts.tv_sec < 0 || ts.tv_nsec < 0 || ts.tv_nsec >= 1_000_000_000 {
253 return Err(0);
254 }
255 (ts.tv_sec as u64)
256 .checked_mul(1_000_000_000)
257 .and_then(|v| v.checked_add(ts.tv_nsec as u64))
258 .ok_or(0)
259}
260fn write_record(fd: i32, record: &[u8; RECORD_SIZE]) -> Result<usize, i32> {
261 #[cfg(test)]
262 if let Some(result) = test_io::intercept(fd, record) {
263 return result;
264 }
265 let written = unsafe { libc::write(fd, record.as_ptr().cast(), RECORD_SIZE) };
268 if written < 0 {
269 Err(os_errno())
270 } else {
271 Ok(written as usize)
272 }
273}
274fn encode(state: &State, p: Payload, time: u64) -> [u8; RECORD_SIZE] {
275 let mut out = [0_u8; RECORD_SIZE];
276 out[..8].copy_from_slice(&MAGIC);
277 out[8..10].copy_from_slice(&SCHEMA_VERSION.to_le_bytes());
278 out[10] = p.kind as u8;
279 out[11] = p.outcome as u8;
280 out[12..16].copy_from_slice(&p.stage.to_le_bytes());
281 out[16..24].copy_from_slice(&(state.status.records_written + 1).to_le_bytes());
282 out[24..32].copy_from_slice(&time.to_le_bytes());
283 out[32..40].copy_from_slice(&p.span.to_le_bytes());
284 out[40..48].copy_from_slice(&p.parent.to_le_bytes());
285 out[48..56].copy_from_slice(&p.ordinal.to_le_bytes());
286 out[56..64].copy_from_slice(&p.root.hash.to_le_bytes());
287 out[64..72].copy_from_slice(&p.root.utf8_len.to_le_bytes());
288 out[72..80].copy_from_slice(&state.status.generation.to_le_bytes());
289 out[80..84].copy_from_slice(&state.pid.to_le_bytes());
290 out[84..88].copy_from_slice(&state.status.errno.to_le_bytes());
291 out[88] = p.root.kind as u8;
292 out[89] = state.status.stop_reason as u8;
293 out[92..96].copy_from_slice(&p.depth.to_le_bytes());
294 out
295}
296impl State {
297 fn stop(&mut self, reason: StopReason, errno: i32) {
298 if matches!(
299 self.status.stop_reason,
300 StopReason::None | StopReason::Cap | StopReason::Abandoned | StopReason::OpenScopes
301 ) {
302 self.status.stop_reason = reason;
303 self.status.errno = errno;
304 }
305 self.status.enabled = false;
306 }
307 fn terminal(&self, outcome: Outcome) -> Payload {
308 Payload {
309 kind: EventKind::Terminal,
310 outcome,
311 stage: 0,
312 span: self.current_span,
313 parent: 0,
314 ordinal: 0,
315 root: RootIdentity::NONE,
316 depth: self.status.open_scopes,
317 }
318 }
319 fn publish(&mut self, payload: Payload) -> bool {
320 if !self.status.enabled {
321 return false;
322 }
323 if payload.kind != EventKind::Terminal
324 && self.status.records_written >= self.status.max_records - 1
325 {
326 self.status.stop_reason = StopReason::Cap;
327 self.publish(self.terminal(Outcome::Truncated));
328 self.status.enabled = false;
329 return false;
330 }
331 if self.status.records_written >= self.status.max_records {
332 self.stop(StopReason::Cap, 0);
333 return false;
334 }
335 let time = match clock_ns() {
336 Ok(time) if time >= self.status.last_monotonic_ns => time,
337 Ok(_) => {
338 self.stop(StopReason::Clock, 0);
339 return false;
340 }
341 Err(errno) => {
342 self.stop(StopReason::Clock, errno);
343 return false;
344 }
345 };
346 let record = encode(self, payload, time);
347 let mut retries = 0;
348 loop {
349 match write_record(self.fd, &record) {
350 Ok(bytes) => {
351 self.status.bytes_written += bytes as u64;
352 if bytes != RECORD_SIZE {
353 self.stop(StopReason::ShortWrite, 0);
354 return false;
355 }
356 self.status.records_written += 1;
357 self.status.last_sequence = self.status.records_written;
358 self.status.last_monotonic_ns = time;
359 self.status.terminal_written = payload.kind == EventKind::Terminal;
360 if self.status.terminal_written {
361 self.status.enabled = false;
362 }
363 return true;
364 }
365 Err(errno) if errno == libc::EINTR && retries < EINTR_RETRIES => retries += 1,
366 Err(errno) => {
367 self.stop(
368 if errno == libc::EINTR {
369 StopReason::Interrupted
370 } else {
371 StopReason::Write
372 },
373 errno,
374 );
375 return false;
376 }
377 }
378 }
379 }
380}
381
382fn with_state<T>(generation: Option<u64>, f: impl FnOnce(&mut State) -> T) -> Option<T> {
383 LOCAL
384 .try_with(|local| {
385 if local.busy.replace(true) {
386 local.reentered.set(true);
387 return None;
388 }
389 let result = local.state.get().and_then(|mut state| {
390 if generation.is_some_and(|id| id != state.status.generation) {
391 return None;
392 }
393 let result = f(&mut state);
394 if local.reentered.replace(false) {
395 state.stop(StopReason::Reentrant, 0);
396 }
397 if local
399 .state
400 .get()
401 .is_some_and(|s| s.status.generation == state.status.generation)
402 {
403 local.state.set(Some(state));
404 }
405 Some(result)
406 });
407 local.busy.set(false);
408 result
409 })
410 .ok()
411 .flatten()
412}
413
414pub struct SinkGuard {
417 file: File,
418 generation: u64,
419 last_status: Cell<Status>,
420 attached: Cell<bool>,
421 thread_bound: PhantomData<Rc<()>>,
422}
423
424pub fn install(mut file: File, max_records: u64) -> Result<SinkGuard, InstallError> {
431 if !(2..=MAX_RECORDS).contains(&max_records) {
432 return Err(InstallError::InvalidLimit);
433 }
434 LOCAL
435 .try_with(|local| {
436 if local.busy.get() {
437 return Err(InstallError::Busy);
438 }
439 if local.state.get().is_some() {
440 return Err(InstallError::AlreadyInstalled);
441 }
442 let metadata = file
443 .metadata()
444 .map_err(|e| InstallError::File(e.raw_os_error().unwrap_or(0)))?;
445 if !metadata.is_file() || metadata.len() != 0 {
446 return Err(InstallError::NotEmptyRegularFile);
447 }
448 file.seek(SeekFrom::Start(0))
449 .map_err(|e| InstallError::File(e.raw_os_error().unwrap_or(0)))?;
450 let generation = NEXT_GENERATION
451 .fetch_update(Ordering::Relaxed, Ordering::Relaxed, |v| v.checked_add(1))
452 .map_err(|_| InstallError::GenerationExhausted)?;
453 let status = Status {
454 generation,
455 max_records,
456 records_written: 0,
457 bytes_written: 0,
458 last_sequence: 0,
459 last_monotonic_ns: 0,
460 enabled: true,
461 terminal_written: false,
462 open_scopes: 0,
463 stop_reason: StopReason::None,
464 errno: 0,
465 };
466 let state = State {
467 fd: file.as_raw_fd(),
468 pid: std::process::id(),
469 status,
470 next_span: 1,
471 current_span: 0,
472 };
473 local.state.set(Some(state));
474 let guard = SinkGuard {
475 file,
476 generation,
477 last_status: Cell::new(status),
478 attached: Cell::new(true),
479 thread_bound: PhantomData,
480 };
481 with_state(Some(generation), |s| {
482 s.publish(Payload {
483 kind: EventKind::Header,
484 outcome: Outcome::None,
485 stage: 0,
486 span: 0,
487 parent: 0,
488 ordinal: max_records,
489 root: RootIdentity::NONE,
490 depth: 0,
491 })
492 });
493 Ok(guard)
494 })
495 .unwrap_or(Err(InstallError::ThreadUnavailable))
496}
497impl SinkGuard {
498 pub fn status(&self) -> Status {
500 if let Some(status) = with_state(Some(self.generation), |s| s.status) {
501 self.last_status.set(status);
502 }
503 self.last_status.get()
504 }
505 fn close(&self, explicit: bool) -> Status {
506 if self.attached.replace(false) {
507 with_state(Some(self.generation), |s| {
508 if s.status.enabled {
509 let outcome = if !explicit {
510 s.status.stop_reason = StopReason::Abandoned;
511 if std::thread::panicking() {
512 Outcome::Unwound
513 } else {
514 Outcome::Abandoned
515 }
516 } else if s.status.open_scopes != 0 {
517 s.status.stop_reason = StopReason::OpenScopes;
518 Outcome::Incomplete
519 } else {
520 Outcome::Ok
521 };
522 s.publish(s.terminal(outcome));
523 s.status.enabled = false;
524 }
525 self.last_status.set(s.status);
526 });
527 let _ = LOCAL.try_with(|local| {
528 if local
529 .state
530 .get()
531 .is_some_and(|s| s.status.generation == self.generation)
532 {
533 local.state.set(None);
534 }
535 });
536 }
537 self.last_status.get()
538 }
539 pub fn finish(self) -> Status {
543 self.close(true)
544 }
545}
546impl Drop for SinkGuard {
547 fn drop(&mut self) {
548 self.close(false);
549 let _ = &self.file;
552 }
553}
554
555pub struct EventScope {
558 generation: u64,
559 span: u64,
560 parent: u64,
561 ordinal: u64,
562 root: RootIdentity,
563 stage: Cell<u32>,
564 active: Cell<bool>,
565 thread_bound: PhantomData<Rc<()>>,
566}
567impl EventScope {
568 pub fn begin(stage: u32, ordinal: u64, root: RootIdentity) -> Self {
571 let ids = with_state(None, |s| {
572 if !s.status.enabled {
573 return None;
574 }
575 let Some(next_span) = s.next_span.checked_add(1) else {
576 s.stop(StopReason::CounterOverflow, 0);
577 return None;
578 };
579 let Some(depth) = s.status.open_scopes.checked_add(1) else {
580 s.stop(StopReason::CounterOverflow, 0);
581 return None;
582 };
583 let span = s.next_span;
584 let parent = s.current_span;
585 if !s.publish(Payload {
586 kind: EventKind::Enter,
587 outcome: Outcome::None,
588 stage,
589 span,
590 parent,
591 ordinal,
592 root,
593 depth,
594 }) {
595 return None;
596 }
597 s.next_span = next_span;
598 s.current_span = span;
599 s.status.open_scopes = depth;
600 Some((s.status.generation, span, parent))
601 })
602 .flatten();
603 let (generation, span, parent) = ids.unwrap_or((0, 0, 0));
604 Self {
605 generation,
606 span,
607 parent,
608 ordinal,
609 root,
610 stage: Cell::new(stage),
611 active: Cell::new(ids.is_some()),
612 thread_bound: PhantomData,
613 }
614 }
615 pub fn transition(&self, stage: u32) {
618 if !self.active.get() {
619 return;
620 }
621 let published = with_state(Some(self.generation), |s| {
622 if !s.status.enabled {
623 return false;
624 }
625 if s.current_span != self.span {
626 s.stop(StopReason::ScopeOrder, 0);
627 return false;
628 }
629 s.publish(self.payload(
630 EventKind::Transition,
631 Outcome::None,
632 stage,
633 s.status.open_scopes,
634 ))
635 })
636 .unwrap_or(false);
637 if published {
638 self.stage.set(stage);
639 }
640 }
641 fn payload(&self, kind: EventKind, outcome: Outcome, stage: u32, depth: u32) -> Payload {
642 Payload {
643 kind,
644 outcome,
645 stage,
646 span: self.span,
647 parent: self.parent,
648 ordinal: self.ordinal,
649 root: self.root,
650 depth,
651 }
652 }
653 pub fn finish(&self, outcome: Outcome) {
656 if !self.active.replace(false) {
657 return;
658 }
659 with_state(Some(self.generation), |s| {
660 if !s.status.enabled {
661 return;
662 }
663 if s.current_span != self.span || s.status.open_scopes == 0 {
664 s.stop(StopReason::ScopeOrder, 0);
665 return;
666 }
667 let depth = s.status.open_scopes - 1;
668 if s.publish(self.payload(EventKind::End, outcome, self.stage.get(), depth)) {
669 s.current_span = self.parent;
670 s.status.open_scopes = depth;
671 }
672 });
673 }
674}
675impl Drop for EventScope {
676 fn drop(&mut self) {
677 self.finish(if std::thread::panicking() {
678 Outcome::Unwound
679 } else {
680 Outcome::Incomplete
681 });
682 }
683}
684
685#[cfg(test)]
686#[path = "../tests/private/phase_events_test.rs"]
687mod tests;
688
689#[cfg(test)]
690mod test_io {
691 use super::*;
692 #[derive(Clone, Copy)]
693 pub(super) enum Mode {
694 Real,
695 Short(usize),
696 Error(i32, u32),
697 Reenter,
698 }
699 thread_local! {
700 pub(super) static MODE: Cell<Mode> = const { Cell::new(Mode::Real) };
701 pub(super) static CLOCK_FAIL: Cell<bool> = const { Cell::new(false) };
702 }
703 pub(super) fn clock_fails() -> bool {
704 CLOCK_FAIL.get()
705 }
706 pub(super) fn intercept(fd: i32, record: &[u8; RECORD_SIZE]) -> Option<Result<usize, i32>> {
707 match MODE.get() {
708 Mode::Real => None,
709 Mode::Short(bytes) => {
710 MODE.set(Mode::Real);
711 let bytes = bytes.min(RECORD_SIZE - 1);
712 let n = unsafe { libc::write(fd, record.as_ptr().cast(), bytes) };
715 Some(if n < 0 {
716 Err(os_errno())
717 } else {
718 Ok(n as usize)
719 })
720 }
721 Mode::Error(errno, remaining) => {
722 MODE.set(if remaining <= 1 {
723 Mode::Real
724 } else {
725 Mode::Error(errno, remaining - 1)
726 });
727 Some(Err(errno))
728 }
729 Mode::Reenter => {
730 MODE.set(Mode::Real);
731 let _scope = EventScope::begin(999, 0, RootIdentity::NONE);
732 None
733 }
734 }
735 }
736}