libtmux 0.1.0-alpha.1

//! Session handles and their snapshot getters.

use std::ffi::OsString;
use std::fmt;
use std::hash::{Hash, Hasher};
use std::sync::Arc;

use crate::formats::TmuxText;
use crate::internal::core::Core;
use crate::internal::listing::{self, Pushdown as _};
use crate::internal::options;
use crate::pane::Pane;
use crate::query::Filterable;
use crate::snapshot::{SessionFields, SessionInfo};
use crate::target::{ServerIdentity, SessionId};
use crate::window::Window;
use crate::{Command, Error, ObjectKind, OptionValue};

/// One tmux session, together with the snapshot it was discovered with.
///
/// A `Session` is cheap to clone and shares its connection with the [`Server`]
/// that produced it, but owns its snapshot outright. Cloning therefore does
/// not share observed state: refreshing one clone leaves the others as they
/// were.
///
/// Getters are synchronous because they read the owned snapshot. Anything that
/// consults tmux is `async`.
///
/// [`Server`]: crate::Server
#[derive(Clone)]
pub struct Session {
    core: Arc<Core>,
    info: SessionInfo,
}

impl Session {
    /// Build a handle from a hydrated snapshot.
    pub(crate) const fn new(core: Arc<Core>, info: SessionInfo) -> Self {
        Self { core, info }
    }

    /// Find the session this process is running in.
    ///
    /// Resolved through the pane, because `TMUX_PANE` names exactly one pane
    /// while a server's `TMUX` value names the session that was current when
    /// the client attached, which may since have changed.
    ///
    /// `Ok(None)` means tmux no longer has that pane.
    ///
    /// # Errors
    ///
    /// Returns an error when `TMUX_PANE` is absent or is not a pane ID, or
    /// when the listing fails.
    ///
    /// # Examples
    ///
    /// ```
    /// # async fn example(server: &libtmux::Server) -> Result<(), libtmux::Error> {
    /// use libtmux::{Pane, Session};
    ///
    /// let session = server.new_session("locating-session").await?;
    /// let pane = session.try_panes().await?.remove(0);
    ///
    /// // Standing in for the environment tmux gives a process it starts.
    /// let found = Session::from_env_value(server, Some(pane.id().as_ref())).await?;
    ///
    /// assert_eq!(found.expect("the session exists").id(), session.id());
    /// # Ok(())
    /// # }
    /// ```
    pub async fn from_env(server: &crate::Server) -> Result<Option<Self>, Error> {
        Self::from_env_value(server, std::env::var_os("TMUX_PANE")).await
    }

    /// Find a session from an explicit `TMUX_PANE` value.
    ///
    /// # Errors
    ///
    /// Returns an error when the value is absent or is not a pane ID, or when
    /// the listing fails.
    pub async fn from_env_value(
        server: &crate::Server,
        value: Option<impl AsRef<std::ffi::OsStr>>,
    ) -> Result<Option<Self>, Error> {
        let Some(pane) = Pane::from_env_value(server, value).await? else {
            return Ok(None);
        };

        server.session_by_id(pane.session_id()).await
    }

    /// Return the tmux session identity.
    ///
    /// This is the `$`-prefixed id tmux assigns, which is stable across
    /// renames. It is always present.
    ///
    /// # Examples
    ///
    /// ```
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// # let runtime = tokio::runtime::Builder::new_current_thread().enable_all().build()?;
    /// # runtime.block_on(async {
    /// # use libtmux::Command;
    /// # let socket = std::env::temp_dir().join("libtmux-doc-session-id.sock");
    /// let server = libtmux::Server::builder().socket_path(&socket).build()?;
    /// # let _ = server.cmd(Command::new("kill-server")).await;
    /// # server.cmd(Command::new("new-session").arg("-d").arg("sleep 60")).await?;
    /// let session = server.sessions().await.into_iter().next().expect("one session");
    /// assert!(session.id().to_string().starts_with('$'));
    /// # let _ = server.cmd(Command::new("kill-server")).await;
    /// # server.shutdown().await?;
    /// # Ok::<(), Box<dyn std::error::Error>>(())
    /// # })?;
    /// # Ok(())
    /// # }
    /// ```
    #[must_use]
    pub const fn id(&self) -> &SessionId {
        self.info.session_id()
    }

    /// Return the session name.
    ///
    /// Names are byte-preserving: tmux permits bytes that are not valid UTF-8,
    /// so this is [`TmuxText`] rather than `str`.
    #[must_use]
    pub fn name(&self) -> &TmuxText {
        self.info.session_name()
    }

    /// Return the session's working directory.
    #[must_use]
    pub fn path(&self) -> &TmuxText {
        self.info.session_path()
    }

    /// Return how many windows the session contains.
    #[must_use]
    pub fn window_count(&self) -> u32 {
        *self.info.session_windows()
    }

    /// Return how many clients are attached to the session.
    #[must_use]
    pub fn attached_client_count(&self) -> u32 {
        *self.info.session_attached()
    }

    /// Report whether any client is attached.
    ///
    /// A session tmux has never reported on is treated as unattached.
    #[must_use]
    pub fn is_attached(&self) -> bool {
        self.attached_client_count() > 0
    }

    /// Return when the session was created, as a Unix timestamp.
    #[must_use]
    pub fn created(&self) -> i64 {
        *self.info.session_created()
    }

    /// Return when a client last attached, as a Unix timestamp.
    ///
    /// This is `None` for a session that has never been attached, which is the
    /// ordinary state for one started with `new-session -d`.
    #[must_use]
    pub fn last_attached(&self) -> Option<i64> {
        self.info.session_last_attached().copied().available()
    }

    /// Return the identity of the server this session belongs to.
    #[must_use]
    pub(crate) fn server_identity(&self) -> &ServerIdentity {
        self.core.configuration().identity()
    }

    /// List the windows linked into this session, in tmux's own order.
    ///
    /// This is the lenient form; use [`Session::try_windows`] when the reason
    /// for an empty result matters.
    pub async fn windows(&self) -> Vec<Window> {
        self.try_windows().await.unwrap_or_default()
    }

    /// List the windows linked into this session, preserving any failure.
    ///
    /// A window linked into other sessions appears here once, under this
    /// session's own index for it.
    ///
    /// # Errors
    ///
    /// Returns an error when the list command cannot run, or when its output
    /// cannot be decoded into snapshots.
    pub async fn try_windows(&self) -> Result<Vec<Window>, Error> {
        let target = self.id().to_string();
        let projections =
            listing::windows(&self.core, listing::Scope::Target(&target), None).await?;

        Ok(projections
            .into_iter()
            .map(|projection| Window::new(Arc::clone(&self.core), projection))
            .collect())
    }

    /// Return the session's active window.
    ///
    /// # Errors
    ///
    /// Returns an error when the window listing fails. A session always has an
    /// active window, so `Ok(None)` means the session disappeared between the
    /// snapshot and this call.
    pub async fn active_window(&self) -> Result<Option<Window>, Error> {
        Ok(self
            .try_windows()
            .await?
            .into_iter()
            .find(Window::is_active))
    }

    /// List every pane in this session, in tmux's own order.
    ///
    /// This is the lenient form; use [`Session::try_panes`] when the reason
    /// for an empty result matters.
    pub async fn panes(&self) -> Vec<Pane> {
        self.try_panes().await.unwrap_or_default()
    }

    /// List every pane in this session, preserving any failure.
    ///
    /// # Errors
    ///
    /// Returns an error when the list command cannot run, or when its output
    /// cannot be decoded into snapshots.
    pub async fn try_panes(&self) -> Result<Vec<Pane>, Error> {
        let target = self.id().to_string();
        let projections =
            listing::panes(&self.core, listing::Scope::SessionTarget(&target), None).await?;

        Ok(projections
            .into_iter()
            .map(|projection| Pane::new(Arc::clone(&self.core), projection))
            .collect())
    }
    /// Replace this handle's snapshot with the session's current state.
    ///
    /// Only the receiver changes. Clones keep the snapshot they were taken
    /// with, because each handle owns its own.
    ///
    /// # Errors
    ///
    /// Returns [`Error::ObjectGone`] when the session no longer exists, or a
    /// listing error when tmux could not be read.
    pub async fn refresh(&mut self) -> Result<&mut Self, Error> {
        let info = listing::sessions(&self.core, None)
            .await?
            .into_iter()
            .find(|info| info.session_id() == self.id())
            .ok_or_else(|| Error::ObjectGone {
                kind: ObjectKind::Session,
                id: self.id().to_string(),
            })?;

        self.info = info;
        Ok(self)
    }

    /// Return a new handle holding the session's current state.
    ///
    /// # Errors
    ///
    /// Returns [`Error::ObjectGone`] when the session no longer exists, or a
    /// listing error when tmux could not be read.
    pub async fn refreshed(&self) -> Result<Self, Error> {
        let mut refreshed = self.clone();
        refreshed.refresh().await?;
        Ok(refreshed)
    }

    /// Create a window in this session and return it.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux refuses the command or its output cannot be
    /// decoded.
    pub async fn new_window(&self, options: impl Into<NewWindowOptions>) -> Result<Window, Error> {
        let options = options.into();
        let session = self.id().to_string();
        let projection =
            listing::create_window(&self.core, |format| options.into_command(&session, format))
                .await?;

        Ok(Window::new(Arc::clone(&self.core), projection))
    }

    /// Rename the session and update this handle.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux refuses the name, which includes one that
    /// is empty or already taken.
    pub async fn rename(&mut self, name: impl Into<OsString>) -> Result<&mut Self, Error> {
        listing::mutate(
            &self.core,
            "rename-session",
            Command::new("rename-session")
                .arg("-t")
                .arg(self.id().to_string())
                .arg(name.into()),
        )
        .await?;

        self.refresh().await?;
        Ok(self)
    }

    /// Kill the session.
    ///
    /// This consumes the handle: every other handle to the same session is now
    /// stale, and refreshing one reports [`Error::ObjectGone`].
    ///
    /// # Errors
    ///
    /// Returns an error when tmux refuses the command.
    pub async fn kill(self) -> Result<(), Error> {
        listing::mutate(
            &self.core,
            "kill-session",
            Command::new("kill-session")
                .arg("-t")
                .arg(self.id().to_string()),
        )
        .await
    }

    /// Read one option's exact stored value.
    ///
    /// A user option, whose name begins with `@`, exists only while it is
    /// set, so an unset one reports `None`. A built-in option always exists,
    /// so an unset one also reports `None`. An unrecognized built-in name is
    /// an error.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux does not recognize the option name.
    pub async fn get_option(&self, name: &str) -> Result<Option<TmuxText>, Error> {
        let target = self.id().to_string();
        options::get(&self.core, options::Scope::Session(&target), name).await
    }

    /// List the option names set at this session's scope.
    ///
    /// Values are not included: tmux renders them for display with three
    /// different quoting styles, so re-parsing them would be guesswork. Read
    /// each value with [`Self::get_option`], which returns exact bytes.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux refuses the listing.
    pub async fn option_names(&self) -> Result<Vec<String>, Error> {
        let target = self.id().to_string();
        options::names(&self.core, options::Scope::Session(&target)).await
    }

    /// Set one option.
    ///
    /// The value is marked sensitive, so it never reaches `Debug`, an error,
    /// or a tracing span.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux rejects the name or value.
    pub async fn set_option(&self, name: &str, value: impl Into<OsString>) -> Result<(), Error> {
        let target = self.id().to_string();
        options::set(
            &self.core,
            options::Scope::Session(&target),
            name,
            value,
            false,
        )
        .await
    }

    /// Append to one option rather than replacing it.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux rejects the name or value.
    pub async fn append_option(&self, name: &str, value: impl Into<OsString>) -> Result<(), Error> {
        let target = self.id().to_string();
        options::set(
            &self.core,
            options::Scope::Session(&target),
            name,
            value,
            true,
        )
        .await
    }

    /// Remove one option, restoring whatever it inherits.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux rejects the name.
    pub async fn unset_option(&self, name: &str) -> Result<(), Error> {
        let target = self.id().to_string();
        options::unset(&self.core, options::Scope::Session(&target), name).await
    }

    /// Set one hook to a tmux command.
    ///
    /// Hooks live in the same option tables, so a hook is an array option and
    /// [`Self::get_option`] reads it under an indexed name such as
    /// `after-new-window[0]`.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux rejects the hook name or command.
    pub async fn set_hook(&self, name: &str, command: impl Into<OsString>) -> Result<(), Error> {
        let target = self.id().to_string();
        options::set_hook(&self.core, options::Scope::Session(&target), name, command).await
    }

    /// Remove one hook.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux rejects the hook name.
    pub async fn unset_hook(&self, name: &str) -> Result<(), Error> {
        let target = self.id().to_string();
        options::unset_hook(&self.core, options::Scope::Session(&target), name).await
    }

    /// Create a window, run an operation with it, then kill it.
    ///
    /// The window is killed whether the operation succeeded or failed, so a
    /// short-lived task does not leave one behind. A panic still skips
    /// cleanup: `Drop` on these handles is deliberately not destructive.
    ///
    /// Setup and teardown failures convert into the operation's own error
    /// type, so a caller writes one `?` rather than unwrapping twice. When
    /// both the operation and the cleanup fail, the operation's error is
    /// returned, because that is the work the caller was doing; the discarded
    /// cleanup failure is recorded through `tracing` when that feature is on.
    ///
    /// # Errors
    ///
    /// Returns the operation's error, or a converted [`Error`] when the
    /// window could not be created, or could not be killed after the
    /// operation succeeded.
    pub async fn with_window<T, E>(
        &self,
        options: impl Into<NewWindowOptions>,
        operation: impl AsyncFnOnce(&Window) -> Result<T, E>,
    ) -> Result<T, E>
    where
        E: From<Error>,
    {
        let created = self.new_window(options).await?;
        let outcome = operation(&created).await;

        match (outcome, created.kill().await) {
            (outcome, Ok(())) => outcome,
            (Ok(_), Err(error)) => Err(error.into()),
            (Err(outcome), Err(cleanup)) => {
                listing::trace_discarded_cleanup(&cleanup);
                Err(outcome)
            }
        }
    }

    /// Set an environment variable for processes this session starts.
    ///
    /// Existing panes keep the environment they were started with; this
    /// affects what new panes inherit.
    ///
    /// The value is marked sensitive, since an environment carries tokens.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux rejects the name or value.
    pub async fn set_environment(
        &self,
        name: &str,
        value: impl Into<OsString>,
    ) -> Result<(), Error> {
        listing::mutate(
            &self.core,
            "set-environment",
            Command::new("set-environment")
                .arg("-t")
                .arg(self.id().to_string())
                .arg(OsString::from(name))
                .sensitive_arg(value.into()),
        )
        .await
    }

    /// Read one environment variable from the session.
    ///
    /// Returns `None` when the variable is unset, and `Some` holding the exact
    /// bytes otherwise. tmux marks a variable removed rather than absent, so a
    /// removed one also reports `None`.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux cannot be reached.
    pub async fn environment(&self, name: &str) -> Result<Option<TmuxText>, Error> {
        let result = self
            .core
            .execute(
                Command::new("show-environment")
                    .arg("-t")
                    .arg(self.id().to_string())
                    .arg(OsString::from(name)),
            )
            .await?;
        if !result.success() {
            return Ok(None);
        }

        // tmux prints `NAME=value`, or `-NAME` for one it has removed.
        let stdout = result.stdout();
        let line = stdout.strip_suffix(b"\n").unwrap_or(stdout);
        let Some(position) = line.iter().position(|byte| *byte == b'=') else {
            return Ok(None);
        };

        Ok(Some(TmuxText::from(line[position + 1..].to_vec())))
    }

    /// Remove an environment variable from the session.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux rejects the name.
    pub async fn unset_environment(&self, name: &str) -> Result<(), Error> {
        listing::mutate(
            &self.core,
            "set-environment",
            Command::new("set-environment")
                .arg("-t")
                .arg(self.id().to_string())
                .arg("-u")
                .arg(OsString::from(name)),
        )
        .await
    }

    /// Read one option, decoded according to what tmux declares about it.
    ///
    /// A flag comes back as [`OptionValue::Flag`] and a number as
    /// [`OptionValue::Number`], so a caller does not decide for itself that
    /// `on` means one. Everything else, including user options, stays text.
    ///
    /// # Errors
    ///
    /// Returns an error when tmux does not recognize the option name.
    pub async fn typed_option(&self, name: &str) -> Result<Option<OptionValue>, Error> {
        let target = self.id().to_string();
        Ok(
            options::get(&self.core, options::Scope::Session(&target), name)
                .await?
                .map(|value| OptionValue::decode(name, value)),
        )
    }

    /// Find this session's window with the given name.
    ///
    /// Names are compared as bytes. A session can hold several windows with
    /// one name, in which case the first in tmux's order is returned.
    ///
    /// # Errors
    ///
    /// Returns an error when the window listing fails.
    pub async fn window(&self, name: impl AsRef<[u8]>) -> Result<Option<Window>, Error> {
        let name = name.as_ref();

        Ok(self
            .try_windows()
            .await?
            .into_iter()
            .find(|window| window.name() == name))
    }

    /// Find this session's window at the given index.
    ///
    /// # Errors
    ///
    /// Returns an error when the window listing fails.
    pub async fn window_at(&self, index: i32) -> Result<Option<Window>, Error> {
        // An index is an integer, so tmux can match it and return one row.
        let target = self.id().to_string();
        let projections = listing::windows(
            &self.core,
            listing::Scope::Target(&target),
            Some(&index.predicate("window_index")),
        )
        .await?;

        Ok(projections
            .into_iter()
            .next()
            .map(|projection| Window::new(Arc::clone(&self.core), projection)))
    }
}

/// Sessions compare by server endpoint and session id.
///
/// Equal-looking ids on different servers are different sessions, and two
/// handles for the same session remain equal even when their snapshots were
/// taken at different times.
impl PartialEq for Session {
    fn eq(&self, other: &Self) -> bool {
        self.server_identity() == other.server_identity() && self.id() == other.id()
    }
}

impl Eq for Session {}

impl Hash for Session {
    fn hash<H: Hasher>(&self, state: &mut H) {
        self.server_identity().hash(state);
        self.id().hash(state);
    }
}

/// Renders identity only, never snapshot text.
///
/// Session names can carry arbitrary bytes from the user's environment, so
/// they stay out of diagnostics.
impl fmt::Debug for Session {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("Session")
            .field("id", &self.id())
            .finish_non_exhaustive()
    }
}

/// Filtering a session uses the same handles as the snapshot beneath it.
///
/// Matching and validation delegate to that snapshot, so an expression can
/// only name fields the catalog knows. The companion is re-parameterized to
/// [`Session`] so the type a listing returns is the type an expression
/// filters.
impl Filterable for Session {
    type Fields = SessionFields<Self>;

    const FILTER_TARGET: &'static str = <SessionInfo as Filterable>::FILTER_TARGET;

    fn filter_fields() -> Self::Fields {
        Self::Fields::for_target(Self::FILTER_TARGET)
    }

    fn __filter_matches(&self, predicate: &crate::query::__private::Predicate) -> bool {
        self.info.__filter_matches(predicate)
    }

    fn __filter_validate(
        predicate: &crate::query::__private::Predicate,
    ) -> Result<(), crate::query::FilterExpressionError> {
        <SessionInfo as Filterable>::__filter_validate(predicate)
    }
}

/// Options for creating a window in a session.
///
/// A bare name is accepted wherever this is: `session.new_window("editor")`.
#[must_use = "options describe a window but do not create one"]
#[derive(Clone, Debug)]
pub struct NewWindowOptions {
    name: Option<OsString>,
    start_directory: Option<std::path::PathBuf>,
    command: Option<OsString>,
    index: Option<i32>,
    placement: Option<WindowPlacement>,
    environment: Vec<(OsString, OsString)>,
    replace_existing: bool,
    select: bool,
}

/// Where a new window goes, relative to the index it is given.
///
/// Without one, tmux takes the first free index.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
pub enum WindowPlacement {
    /// Insert before the target index, shifting later windows along.
    Before,
    /// Insert after it.
    After,
}

impl NewWindowOptions {
    /// Describe a window with no name, letting tmux choose one.
    pub const fn unnamed() -> Self {
        Self {
            name: None,
            start_directory: None,
            command: None,
            index: None,
            placement: None,
            environment: Vec::new(),
            replace_existing: false,
            select: false,
        }
    }

    /// Describe a window with the given name.
    pub fn new(name: impl Into<OsString>) -> Self {
        Self {
            name: Some(name.into()),
            ..Self::unnamed()
        }
    }

    /// Set the window's working directory.
    pub fn start_directory(mut self, directory: impl Into<std::path::PathBuf>) -> Self {
        self.start_directory = Some(directory.into());
        self
    }

    /// Run a command instead of the default shell.
    pub fn command(mut self, command: impl Into<OsString>) -> Self {
        self.command = Some(command.into());
        self
    }

    /// Place the window at a window index rather than the first free one.
    pub const fn index(mut self, index: i32) -> Self {
        self.index = Some(index);
        self
    }

    /// Insert relative to the index rather than at it.
    ///
    /// Without an index this is relative to the session's current window,
    /// which is what tmux does.
    pub const fn placement(mut self, placement: WindowPlacement) -> Self {
        self.placement = Some(placement);
        self
    }

    /// Set an environment variable for the process the new window starts.
    ///
    /// Call this more than once for more than one variable. tmux applies
    /// these to the new process only, not to the session.
    pub fn environment(mut self, name: impl Into<OsString>, value: impl Into<OsString>) -> Self {
        self.environment.push((name.into(), value.into()));
        self
    }

    /// Replace whatever already occupies the target index.
    ///
    /// Without this, an index that is taken is an error rather than a silent
    /// overwrite.
    pub const fn replace_existing(mut self) -> Self {
        self.replace_existing = true;
        self
    }

    /// Make the new window active in its session.
    ///
    /// Creation does not select by default, so building a workspace does not
    /// leave the session pointing at whichever window happened to be last.
    pub const fn select(mut self) -> Self {
        self.select = true;
        self
    }

    /// Lower these options into a `new-window` command for one session.
    ///
    /// `print_format` is placed with the other flags because tmux stops
    /// parsing flags at the first positional, and the shell command is one.
    fn into_command(self, session: &str, print_format: &str) -> Command {
        let target = self
            .index
            .map_or_else(|| session.to_owned(), |index| format!("{session}:{index}"));
        let mut command = Command::new("new-window")
            .arg("-P")
            .arg("-F")
            .arg(print_format)
            .arg("-t")
            .arg(target);
        if !self.select {
            command = command.arg("-d");
        }
        match self.placement {
            Some(WindowPlacement::Before) => command = command.arg("-b"),
            Some(WindowPlacement::After) => command = command.arg("-a"),
            None => {}
        }
        if self.replace_existing {
            command = command.arg("-k");
        }
        if let Some(name) = self.name {
            command = command.arg("-n").arg(name);
        }
        if let Some(directory) = self.start_directory {
            command = command.arg("-c").arg(directory.into_os_string());
        }
        for (name, value) in self.environment {
            command = command
                .arg("-e")
                .arg(crate::window::assignment(&name, &value));
        }
        if let Some(shell_command) = self.command {
            command = command.arg(shell_command);
        }
        command
    }
}

impl<T: Into<OsString>> From<T> for NewWindowOptions {
    fn from(name: T) -> Self {
        Self::new(name)
    }
}

/// Renders the session id, which is what a tmux target wants.
impl fmt::Display for Session {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(formatter, "{}", self.id())
    }
}