session

package

v0.10.13 Latest Latest Go to latest Published: May 7, 2026 License: MIT Imports: 10 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/DocumentDrivenDX/fizeau

Links

Open Source Insights

Documentation ¶

Rendered for

Overview ¶

Package session owns direct PTY process lifecycle and timed raw/input events.

See internal/pty/doc.go for the governing ADR/SPIKE citations that authorize this package boundary.

Index ¶

Variables
func KeyBytes(k Key) ([]byte, error)
type Clock
type Config
type Event
type EventKind
type ExitStatus
type Key
- func CtrlKey(r rune) Key
type Option
type OutputChunk
type Session
- func Start(ctx context.Context, command string, args []string, workdir string, ...) (*Session, error)
type Size

Constants ¶

This section is empty.

Variables ¶

View Source

var (
	// ErrClosed is returned when writing to a closed session.
	ErrClosed = errors.New("pty session closed")
)

Functions ¶

func KeyBytes ¶

func KeyBytes(k Key) ([]byte, error)

KeyBytes encodes a supported key as terminal input bytes.

Types ¶

type Clock ¶

type Clock interface {
	Now() time.Time
}

Clock lets tests inject deterministic timestamps.

type Config ¶

type Config struct {
	Clock      Clock
	Timeout    time.Duration
	BufferSize int
}

Config controls session startup.

type Event ¶

type Event struct {
	Seq    uint64
	Kind   EventKind
	At     time.Time
	TMS    int64
	Offset int64
	Bytes  []byte
	Key    Key
	Size   Size
	Signal string
	Exit   *ExitStatus
	Err    error
}

Event is the narrow timed event shape consumed by follow-on cassette code.

type EventKind ¶

type EventKind string

EventKind identifies cassette-facing session events.

const (
	EventOutput EventKind = "output"
	EventInput  EventKind = "input"
	EventResize EventKind = "resize"
	EventSignal EventKind = "signal"
	EventExit   EventKind = "exit"
)

type ExitStatus ¶

type ExitStatus struct {
	Code     int
	Signal   string
	Exited   bool
	Signaled bool
	Err      error
}

ExitStatus describes process termination.

type Key ¶

type Key string

Key names common terminal inputs.

const (
	KeyEnter     Key = "enter"
	KeyTab       Key = "tab"
	KeyEscape    Key = "escape"
	KeyBackspace Key = "backspace"
	KeyUp        Key = "up"
	KeyDown      Key = "down"
	KeyRight     Key = "right"
	KeyLeft      Key = "left"
)

func CtrlKey ¶

func CtrlKey(r rune) Key

CtrlKey returns a letter control-key input such as Ctrl-C.

type Option ¶

type Option func(*Config)

Option configures Start.

func WithBufferSize ¶

func WithBufferSize(size int) Option

WithBufferSize changes the raw read buffer size.

func WithClock ¶

func WithClock(clock Clock) Option

WithClock injects a deterministic clock.

func WithTimeout ¶

func WithTimeout(timeout time.Duration) Option

WithTimeout applies a wall-clock timeout in addition to ctx cancellation.

type OutputChunk ¶

type OutputChunk struct {
	Seq       uint64
	At        time.Time
	TMS       int64
	Offset    int64
	Bytes     []byte
	ReadError error
	EOF       bool
}

OutputChunk is one timed raw PTY read.

type Session ¶

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

Session is a running PTY-backed process.

func Start ¶

func Start(ctx context.Context, command string, args []string, workdir string, env []string, size Size, opts ...Option) (*Session, error)

Start launches command under a direct PTY with argv, workdir, env, and size. Cancellation is controlled by ctx and WithTimeout.

func (*Session) Close ¶

func (s *Session) Close() error

Close cancels the session context and closes the PTY file descriptor.

func (*Session) Events ¶

func (s *Session) Events() <-chan Event

Events returns timed input/output/resize/signal/exit events.

func (*Session) Kill ¶

func (s *Session) Kill() error

Kill terminates the process group where supported and records a signal event. If the process exits naturally at the same time, the signal event is best effort and may race with the exit event.

func (*Session) Output ¶

func (s *Session) Output() <-chan OutputChunk

Output returns timed raw PTY chunks. The channel closes after the read loop reaches EOF or Close/Kill tears the PTY down.

func (*Session) Resize ¶

func (s *Session) Resize(size Size) error

Resize changes the PTY size and records a resize event.

func (*Session) SendBytes ¶

func (s *Session) SendBytes(b []byte) error

SendBytes writes literal bytes to the PTY and records an input event.

func (*Session) SendKey ¶

func (s *Session) SendKey(k Key) error

SendKey writes a named key sequence to the PTY and records an input event.

func (*Session) Size ¶

func (s *Session) Size() Size

Size returns the last requested terminal size.

func (*Session) Wait ¶

func (s *Session) Wait() ExitStatus

Wait blocks until the process exits and returns its exit status.

type Size ¶

type Size struct {
	Rows uint16
	Cols uint16
}

Size is a terminal rows/columns pair.

Source Files ¶

View all Source files

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL