dbgflow_core/
lib.rs

1//! Core runtime for the `dbgflow` graph debugger.
2//!
3//! This crate contains the in-memory session model, event collector, session
4//! persistence helpers, and the embedded local UI server.
5//!
6//! # Module Structure
7//!
8//! - [`session`]: Core data types for sessions, nodes, edges, and events
9//! - [`runtime`]: Runtime state management and event recording
10//! - [`server`]: Embedded HTTP server for the debugger UI
11//! - [`ui`]: Embedded UI assets
12//!
13//! # Quick Start
14//!
15//! ```ignore
16//! use dbgflow_core::{reset_session, current_session, serve_session};
17//!
18//! reset_session("My Debug Session");
19//! // ... run instrumented code ...
20//! serve_session(current_session(), "127.0.0.1", 3000)?;
21//! ```
22#![warn(missing_docs)]
23
24mod internal_runtime;
25mod server;
26mod session;
27mod ui;
28
29use std::path::{Path, PathBuf};
30
31// ---------------------------------------------------------------------------
32// Public re-exports from session module
33// ---------------------------------------------------------------------------
34
35pub use session::{
36    Edge, EdgeKind, Event, EventKind, FunctionMeta, Node, NodeKind, Session, TypeMeta, ValueSlot,
37};
38
39// ---------------------------------------------------------------------------
40// Public re-exports from internal_runtime module
41// ---------------------------------------------------------------------------
42
43pub use internal_runtime::{UiDebugValue, current_session, reset_session, runtime, type_preview};
44
45// ---------------------------------------------------------------------------
46// Public re-exports from server module
47// ---------------------------------------------------------------------------
48
49pub use server::{serve_session, serve_session_with_rerun};
50
51// ---------------------------------------------------------------------------
52// Session persistence (convenience wrappers)
53// ---------------------------------------------------------------------------
54
55/// Writes the current session to a JSON file.
56pub fn write_session_json(path: impl AsRef<Path>) -> std::io::Result<()> {
57    let sess = current_session();
58    session::write_session_json(&sess, path)
59}
60
61/// Reads a session from a JSON file.
62pub fn read_session_json(path: impl AsRef<Path>) -> std::io::Result<Session> {
63    session::read_session_json(path)
64}
65
66/// Writes the current session into a directory using a sanitized file name.
67pub fn write_session_snapshot_in_dir(
68    dir: impl AsRef<Path>,
69    label: impl AsRef<str>,
70) -> std::io::Result<PathBuf> {
71    let sess = current_session();
72    session::write_session_snapshot_in_dir(&sess, dir, label)
73}
74
75/// Writes the current session into the directory pointed to by `DBG_SESSION_DIR`.
76///
77/// Returns `Ok(None)` if the environment variable is not set.
78pub fn write_session_snapshot_from_env(label: impl AsRef<str>) -> std::io::Result<Option<PathBuf>> {
79    let sess = current_session();
80    session::write_session_snapshot_from_env(&sess, label)
81}
82
83// ---------------------------------------------------------------------------
84// Convenience capture functions
85// ---------------------------------------------------------------------------
86
87/// Runs a closure inside a fresh in-memory capture session.
88///
89/// This resets the global session state, runs the provided closure, and returns
90/// its result. Use [`current_session`] to retrieve the captured session afterward.
91pub fn capture_session<T>(title: impl Into<String>, run: impl FnOnce() -> T) -> T {
92    reset_session(title);
93    run()
94}
95
96/// Runs a closure, then writes the captured session to a JSON file.
97///
98/// This is a convenience function that combines [`capture_session`] with
99/// [`write_session_json`].
100pub fn capture_session_to_path<T>(
101    title: impl Into<String>,
102    path: impl AsRef<Path>,
103    run: impl FnOnce() -> T,
104) -> std::io::Result<T> {
105    reset_session(title);
106    let result = run();
107    write_session_json(path)?;
108    Ok(result)
109}
110
111/// Runs a closure, then serves the captured session over the local UI server.
112///
113/// This is a convenience function that combines [`capture_session`] with
114/// [`serve_session`].
115pub fn capture_session_and_serve<T>(
116    title: impl Into<String>,
117    host: &str,
118    port: u16,
119    run: impl FnOnce() -> T,
120) -> std::io::Result<T> {
121    reset_session(title);
122    let result = run();
123    serve_session(current_session(), host, port)?;
124    Ok(result)
125}
dbgflow_core/lib.rs

dbgflow_core/
lib.rs
