attach

type Cause struct {
	Kind CauseKind
	// For CauseSignaled, the daemon's name for the signal: the SSH name
	// without "SIG" ("TERM"), or the number of one with no name ("40").
	Signal string
}

type CauseKind int

type Client struct {
	Socket  string
	Stdin   io.Reader
	Stdout  io.Writer
	Pty     *Pty
	Resizes <-chan termsize.Size
	Escape  byte
	Logger  *slog.Logger

	// HostKeys is the daemon's public keys, from the session record: a record
	// from a current daemon carries exactly one entry, the session host key
	// it generated for that run; a record written by an older daemon may
	// carry several, which is why this is a slice. Run refuses to attach
	// without at least one: a client that accepted any key would hand its
	// terminal to whatever bound the socket.
	HostKeys []ssh.PublicKey

	// Suspend is the Terminal's: see Terminal.Suspend.
	Suspend func() (size termsize.Size, owned bool)

	// Status is the Terminal's: see Terminal.Status.
	Status func(ctx context.Context) []string
	// contains filtered or unexported fields
}

type EscapeAction int

type EscapeFilter struct {
	// contains filtered or unexported fields
}

type EscapeOption func(*EscapeFilter)

type Pty struct {
	Term string
	Size termsize.Size
}

type Reason int

type Result struct {
	Reason Reason
	Status int
	// Cause is why the daemon ended the session, ahead of the status: the
	// status alone cannot say, and for 0 it says nothing at all.
	Cause Cause

	// Released closes once no write from this session to Stdout is in
	// flight: the output copy has returned, and so has every mode write and
	// every status write ~? made. It is already closed when Terminal.Run
	// returns, except after a drain or a mode write that timed out, or with
	// a status write still parked, whose write is still in flight.
	Released <-chan struct{}
	// Unrestored is the mode restore left unwritten because the output was
	// abandoned with the terminal in the session's modes: the drain timed
	// out, a suspend could not take the output from a write parked on the
	// terminal, the write that put the modes back after a suspend did not
	// finish, or the restore could not take the output from a status write
	// parked on the terminal. Empty otherwise: the restore was written or
	// attempted, the process came back without the terminal, or there is no
	// pty and so no modes.
	Unrestored []byte
}

type Terminal struct {
	Stdin   io.Reader
	Stdout  io.Writer
	Pty     *Pty
	Resizes <-chan termsize.Size
	Escape  byte

	// Suspend stops the process this client runs in and returns once it is
	// running again, with the terminal's size and whether the terminal is
	// this client's again — for a local terminal: restore the terminal,
	// SIGTSTP, re-enter raw mode if still the foreground, measure. owned is
	// false after bg: the terminal is the foreground job's, and the
	// attachment ends there, writing nothing more to it. Nil disables the ~^Z
	// sequence, and the bytes reach the session instead.
	//
	// It is the embedder's because what "suspend" means is the terminal's
	// business, not the protocol's: this package never touches termios and
	// never signals its own process.
	Suspend func() (size termsize.Size, owned bool)

	// DeclareInteractive sends upterm.AttachInteractiveEnvVar, which says
	// this client displays on a terminal and forwards its keystrokes, so it
	// can answer the terminal queries a primary is sent. Declared, because
	// the daemon cannot tell a terminal from a pipe on the far side of an SSH
	// channel — and a pty viewer that does not read its terminal would leave
	// the terminal's replies in the foreground shell as junk. Only the attach
	// socket reads it.
	DeclareInteractive bool

	// OnReady runs once, after the shell request is confirmed and before the
	// first byte of output is written to Stdout. Nil does nothing.
	OnReady func()

	// Status returns the lines ~? prints into this terminal, never into the
	// session: the session's status and the keys, each without its line
	// ending. It runs on a goroutine of its own, so the input is never held
	// up by it, and is given a context that ends with the attachment; it
	// should be bounded all the same, since lines that come late are lines
	// nobody is waiting for. nil leaves ~? as ordinary input, which is what
	// join wants. It is offered only when the terminal's modes are tracked
	// (Pty set): without them there is no telling whether text written now
	// would land inside the session's own escape sequence.
	Status func(ctx context.Context) []string

	Logger *slog.Logger
	// contains filtered or unexported fields
}