apps/libtmux_erlang/src/tmux_session.erl

Source at 4d73c9795adca3e49eea74d1d2cbbbbdcbea0b6c

SHA-256: 150217b8d739092eded788198c86e0d82d6e7e81453ab8c3423c53ea8d4280d0

-module(tmux_session).
-moduledoc """
Create and observe sessions, or act on a session's registered stable ID.

`create/2` accepts name, window_name, width, height, cwd, env,
launch and detach. Creation defaults to detached with tmux's configured
shell/command. launch is default_shell, an argv map, or an explicit shell map.
env augments tmux's inherited environment. tmux supplies PATH, SHELL, PWD and
TMUX_PANE after that merge, so those entries may be replaced. Names and cwd
are literal format values; tmux's stored name rules still apply. Creation
never adopts an existing session by name.

An empty shell command can exit immediately and remove its session. It does
not request the empty-pane behavior of split-window. Use a running program
when later operations require the session to remain alive.

`create/2` and `get/2` explicitly read the
new/current row through several one-shot commands. These reads are not atomic.
If creation succeeds but observation fails, the error retains mutation =
completed and the original command result. `rename/2` and
`kill/1` return command results without refreshing the input
record. Detached rows require `tmux_server:bind/2` before actions.
`rename_command/2` builds a reusable value without tmux I/O; the other calls
perform I/O after validation.

`select/2` switches one explicitly named attached client to a session. It
never attaches a client or infers the current client. Use
`tmux_window_link:select/1` to select a session's window membership instead.
""".
-export([create/2, get/2, rename/2, rename_command/2, select/2, select/3, kill/1]).

-export_type([create_options/0, select_options/0]).
-doc "Session creation options. Launch defaults to the configured shell; creation defaults to detached.".
-type create_options() :: #{name => binary(), window_name => binary(),
    width => 1..65535, height => 1..65535, cwd => binary(),
    env => #{binary() => binary()}, launch => tmux_command:launch_spec(), detach => boolean()}.

-doc "Session selection options. update_environment defaults to false, preserving the destination environment.".
-type select_options() :: #{update_environment => boolean()}.

-doc """
Create a detached session by default and explicitly observe the returned row.
Options include name, window_name, dimensions, cwd, env and launch. Performs
I/O; an observation failure after successful creation retains mutation =
completed and the original command result. Existing names are not adopted.
""".
-spec create(tmux_server:t(), create_options()) -> {ok, tmux_model:session()} | {error, map()}.
create(Server, Options) ->
    maybe
        {ok, Flags, Launch} ?= tmux_args:launch_options(Options,
            [{name, text_format, <<"-s">>}, {window_name, text_format, <<"-n">>},
             {width, dimension, <<"-x">>}, {height, dimension, <<"-y">>}]),
        {ok, Result} ?= tmux_target:run(Server, <<"new-session">>,
            [<<"-P">>, <<"-F">>, <<"#{session_id}">>] ++ Flags ++ [<<"--">> | Launch]),
        tmux_observe:created(Server, session, Result)
    end.

-doc """
Read fresh session fields through explicit one-shot commands. The session ID
is stable within the observed server incarnation. Returns target_gone when
tmux no longer has that session; it never refreshes an existing record.
""".
-spec get(tmux_server:t(), tmux_model:session_id()) -> {ok, tmux_model:session()} | {error, map()}.
get(Server, Id) -> tmux_observe:get(Server, session, Id).

-doc """
Rename the registered session using a literal name and return the command
result. Performs I/O. Previously captured records keep their old names;
detached or stale references fail validation before the action.
""".
-spec rename(tmux_model:session(), binary()) -> {ok, map()} | {error, map()}.
rename(Session, Name) ->
    maybe
        {ok, Command} ?= rename_command(Session, Name),
        tmux_target:execute(Command)
    end.

-doc """
Build a literal rename command without tmux I/O. Validates the row and keeps
its captured origin; endpoint liveness is checked during execution. Submit
the value to `tmux_server:command/3` or `tmux_operation:start/3` with its original
endpoint. Existing session records retain their captured name.

Detached rows require `tmux_server:bind/2` first. Building a command does not
execute it or make a repeated mutation safe.

```erlang
1> tmux_session:rename_command(invalid_row, <<"work">>).
{error,#{code => invalid_row,path => []}}
```
""".
-spec rename_command(tmux_model:session(), binary()) -> {ok, tmux_command:t()} | {error, map()}.
rename_command(Session, Name) ->
    maybe
        {ok, [_, Literal]} ?= tmux_args:options(#{name => Name}, [{name, text_format, <<"-n">>}]),
        {ok, Origin, Target} ?= tmux_target:captured_target(session, Session),
        tmux_command:generated(session_rename, Origin, [<<"-t">>, Target, <<"--">>, Literal])
    end.

-doc """
Switch an explicitly named attached client to this registered session,
preserving the session environment. Performs I/O. See `select/3` for client
lookup, environment updates and disconnection races.

An empty client name cannot select an implicit current client:

```erlang
1> tmux_session:select(invalid_session, <<>>).
{error,#{code => invalid_client,path => [client]}}
```
""".
-spec select(tmux_model:session(), binary()) -> {ok, map()} | {error, map()}.
select(Session, Client) -> select(Session, Client, #{}).

-doc """
Switch one attached client, selected by its literal native client name or TTY
path, to the session's registered stable ID. Performs I/O and returns the
command result; existing rows remain captured values. Obtain the name from
the caller's own client context, such as tmux's `client_name` format. There
is no default client and this call never attaches one.

`update_environment` defaults to false (`switch-client -E`). When true, tmux
updates the destination session environment using its `update-environment`
option and that client's environment; listed variables absent from the client
can be marked for removal. Running pane processes retain their environment.

Names are nonempty NUL-free binaries of at most 32 KiB. Trailing-colon aliases
are rejected. Native lookup matches an exact name or TTY path, including its
`/dev/`-relative alias; there is no prefix or pattern matching. A disconnected
name returns `client_not_found`. Names and TTY paths can be reused by a later
connection; this API does not identify a client incarnation atomically. A
missing destination returns `target_gone`. See `tmux_server:bind/2` for detached
session rows and `tmux_window_link:select/1` for window selection.
""".
-spec select(tmux_model:session(), binary(), select_options()) ->
    {ok, map()} | {error, map()}.
select(Session, Client, Options) ->
    maybe
        ok ?= client_name(Client),
        {ok, []} ?= tmux_args:options(Options,
            [{update_environment, boolean, <<>>}]),
        {ok, Server, Target} ?= tmux_target:resolve(session, Session),
        Flags = case maps:get(update_environment, Options, false) of
            true -> [];
            false -> [<<"-E">>]
        end,
        case tmux_target:run(Server, <<"switch-client">>,
            Flags ++ [<<"-c">>, Client, <<"-t">>, Target]) of
            {error, #{code := command_error,
                      stderr := <<"can't find client: ", _/binary>>} = Error} ->
                {error, Error#{code => client_not_found}};
            Result -> Result
        end
    end.

client_name(Name) when is_binary(Name), byte_size(Name) > 0,
                       byte_size(Name) =< 32768 ->
    case binary:last(Name) =/= $: andalso binary:match(Name, <<0>>) =:= nomatch of
        true -> ok;
        false -> {error, #{code => invalid_client, path => [client]}}
    end;
client_name(_) -> {error, #{code => invalid_client, path => [client]}}.

-doc """
Destroy this registered session. Performs I/O and returns the command result;
this is a destructive session action, not endpoint cleanup. References must
belong to a live registered owner.
""".
-spec kill(tmux_model:session()) -> {ok, map()} | {error, map()}.
kill(Session) -> tmux_target:act(session, Session, <<"kill-session">>, []).