microsandbox 0.6.8

`microsandbox` is the core library for the microsandbox project.
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

//! Sandbox-scoped log handles.
//!
//! A [`SandboxLogger`] is a plain, cheap handle to one sandbox's on-disk
//! log directory, obtained from
//! [`Sandbox::logger`](crate::sandbox::Sandbox::logger). Used directly,
//! it behaves exactly like [`Sandbox::log_stream`] /
//! [`Sandbox::logs`] — each followed stream owns a private watcher.
//!
//! Registering it with a
//! [`LogRegistry`](super::watch::LogRegistry) yields a
//! [`RegisteredSandboxLogger`], whose followed streams share the
//! registry's single watcher instead. Everything else — parsing,
//! cursors, ordering, rotation, the fallback poll — is identical; the
//! registry only changes where the "files may have new bytes" wake
//! comes from.

use std::path::{Path, PathBuf};

use super::watch::LogRegistration;
use super::{LogEntry, LogOptions, LogSnapshot, LogStreamOptions};
use crate::MicrosandboxResult;
use crate::backend::sandbox::LogStream;

//--------------------------------------------------------------------------------------------------
// SandboxLogger
//--------------------------------------------------------------------------------------------------

/// A handle to one sandbox's log directory. Reads and streams delegate
/// to the same engine as the backend log methods; followed streams use
/// a private watcher until the logger is registered with a
/// [`LogRegistry`](super::watch::LogRegistry).
pub struct SandboxLogger {
    name: String,
    log_dir: PathBuf,
}

impl SandboxLogger {
    /// Construct a logger for a named sandbox rooted at `log_dir`.
    pub(crate) fn new(name: String, log_dir: PathBuf) -> Self {
        Self { name, log_dir }
    }

    /// The sandbox name this logger reads.
    pub fn name(&self) -> &str {
        &self.name
    }

    /// The on-disk log directory this logger reads.
    pub fn log_dir(&self) -> &Path {
        &self.log_dir
    }

    /// Read a chronologically sorted log snapshot's entries.
    pub async fn read(&self, opts: &LogOptions) -> MicrosandboxResult<Vec<LogEntry>> {
        Ok(self.read_snapshot(opts).await?.entries)
    }

    /// Read a chronologically sorted log snapshot plus its end cursor.
    pub async fn read_snapshot(&self, opts: &LogOptions) -> MicrosandboxResult<LogSnapshot> {
        super::read_logs_snapshot_from_dir(&self.name, self.log_dir.clone(), opts).await
    }

    /// Stream log entries. When `opts.follow` is set, each stream owns a
    /// private filesystem watcher (the standalone behavior).
    pub async fn stream(&self, opts: &LogStreamOptions) -> MicrosandboxResult<LogStream> {
        let stream = super::log_stream_from_dir(&self.name, self.log_dir.clone(), opts).await?;
        Ok(Box::pin(stream) as LogStream)
    }
}

//--------------------------------------------------------------------------------------------------
// RegisteredSandboxLogger
//--------------------------------------------------------------------------------------------------

/// A [`SandboxLogger`] registered with a
/// [`LogRegistry`](super::watch::LogRegistry). Followed
/// streams share the registry's single watcher; the held
/// [`LogRegistration`] keeps the directory watched, and each stream
/// carries its own registration clone so it stays watched even if this
/// logger is dropped first.
pub struct RegisteredSandboxLogger {
    logger: SandboxLogger,
    registration: LogRegistration,
}

impl RegisteredSandboxLogger {
    pub(crate) fn new(logger: SandboxLogger, registration: LogRegistration) -> Self {
        Self {
            logger,
            registration,
        }
    }

    /// The sandbox name this logger reads.
    pub fn name(&self) -> &str {
        self.logger.name()
    }

    /// The on-disk log directory this logger reads.
    pub fn log_dir(&self) -> &Path {
        self.logger.log_dir()
    }

    /// Read a chronologically sorted log snapshot's entries.
    pub async fn read(&self, opts: &LogOptions) -> MicrosandboxResult<Vec<LogEntry>> {
        self.logger.read(opts).await
    }

    /// Read a chronologically sorted log snapshot plus its end cursor.
    pub async fn read_snapshot(&self, opts: &LogOptions) -> MicrosandboxResult<LogSnapshot> {
        self.logger.read_snapshot(opts).await
    }

    /// Stream log entries. A followed stream subscribes to the registry's
    /// shared watch for this directory — no private watcher — and holds a
    /// registration clone for its lifetime. A non-follow stream needs no
    /// wake source and takes the plain path.
    pub async fn stream(&self, opts: &LogStreamOptions) -> MicrosandboxResult<LogStream> {
        if !opts.follow {
            return self.logger.stream(opts).await;
        }
        let subscription = self.registration.subscribe();
        let stream = super::log_stream_from_dir_registry(
            &self.logger.name,
            self.logger.log_dir.clone(),
            opts,
            subscription,
        )
        .await?;
        Ok(Box::pin(stream) as LogStream)
    }
}