tastty-driver 0.1.0

use tastty::TerminalSize;

use crate::ExitStatus;

/// Push-style observer for raw I/O and lifecycle events on a [`Session`].
///
/// `on_output` and `on_input` are required; `on_resize` and `on_exit` have
/// empty default implementations so impls can opt in to the lifecycle hooks
/// they care about.
///
/// # Threading
///
/// Callbacks run on driver-internal threads:
///
/// - `on_output` runs on the PTY reader thread, before the screen parser
///   sees the bytes.
/// - `on_input` runs on the PTY writer thread, after the bytes have been
///   written to and flushed through the PTY writer.
/// - `on_resize` runs on the thread that called [`Session::resize`].
/// - `on_exit` runs on the driver's exit-reaper thread.
///
/// # Convention: do not block
///
/// Callbacks must return promptly. Blocking inside `on_output` stalls the
/// PTY reader thread, which in turn stalls every subsequent screen update.
/// The expected pattern is to push the chunk into a channel and return; a
/// dedicated consumer thread or task drains the channel and does any heavy
/// work (file I/O, JSON encoding, ...) off the reader thread.
///
/// [`Session`]: crate::Session
/// [`Session::resize`]: crate::Session::resize
pub trait IoObserver: Send + Sync {
    /// Called once for every PTY output chunk read from the child.
    fn on_output(&self, chunk: &[u8]);

    /// Called once for every input chunk written to the child.
    fn on_input(&self, chunk: &[u8]);

    /// Called after [`Session::resize`](crate::Session::resize) succeeds.
    fn on_resize(&self, _size: TerminalSize) {}

    /// Called once when the child process exit is observed.
    fn on_exit(&self, _status: ExitStatus) {}
}