ptyhost

package
v2.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

Documentation

Overview

Package ptyhost 把「伪终端 + 子进程」的平台细节隔离在一个窄接口之后。

Agent 的会话、缓冲、流控与协议逻辑只依赖这里的接口,因此:

  • 单元测试可以用内存里的假终端驱动(见 fake.go),不依赖真实 PTY;
  • 如果日后需要替换底层 PTY 库(体积、依赖或平台兼容性问题),只改这一个包。

Index

Constants

This section is empty.

Variables

View Source
var ErrUnsupported = errors.New("ptyhost: unsupported on this platform")

ErrUnsupported 表示当前平台不支持请求的操作。

Functions

func DefaultSize

func DefaultSize(rows, cols uint16) (uint16, uint16)

DefaultSize 把 0 值尺寸规整为 24×80。

Types

type ExitStatus

type ExitStatus struct {
	// Code 是退出码;被信号终止时为 -1。
	Code int
	// Signal 是终止进程的信号名(如 "hangup"、"killed"),正常退出为空。
	Signal string
}

ExitStatus 是子进程的退出信息。

type FakeSpawner

type FakeSpawner struct {

	// Err 非空时 Spawn 返回该错误。
	Err error
	// HoldTTY 为 true 时,进程退出后读端不会自动 EOF——模拟「后台进程仍握着终端」的场景。
	HoldTTY bool
	// contains filtered or unexported fields
}

FakeSpawner 是内存里的假终端工厂,供单元测试驱动会话逻辑(不依赖真实 PTY 与子进程)。 生产代码不使用它。

func (*FakeSpawner) Spawn

func (f *FakeSpawner) Spawn(spec Spec) (Terminal, error)

Spawn 实现 Spawner。

func (*FakeSpawner) Terminals

func (f *FakeSpawner) Terminals() []*FakeTerminal

Terminals 返回迄今创建的全部假终端(按创建顺序)。

type FakeTerminal

type FakeTerminal struct {
	Spec Spec
	// contains filtered or unexported fields
}

FakeTerminal 是 Terminal 的内存实现。测试通过 Emit 制造输出、Exit 结束进程、Input 检查收到的输入。

func (*FakeTerminal) Close

func (t *FakeTerminal) Close() error

func (*FakeTerminal) Emit

func (t *FakeTerminal) Emit(data []byte)

Emit 模拟子进程向终端输出数据。

func (*FakeTerminal) Exit

func (t *FakeTerminal) Exit(st ExitStatus)

Exit 模拟子进程退出。

func (*FakeTerminal) Input

func (t *FakeTerminal) Input() []byte

Input 返回迄今写入终端的全部输入。

func (*FakeTerminal) IsClosed

func (t *FakeTerminal) IsClosed() bool

IsClosed 返回 Close 是否已被调用。

func (*FakeTerminal) Kill

func (t *FakeTerminal) Kill()

Kill 模拟被信号终止。

func (*FakeTerminal) KillCount

func (t *FakeTerminal) KillCount() int

KillCount 返回 Kill 被调用的次数。

func (*FakeTerminal) Pid

func (t *FakeTerminal) Pid() int

func (*FakeTerminal) Read

func (t *FakeTerminal) Read(b []byte) (int, error)

func (*FakeTerminal) Resize

func (t *FakeTerminal) Resize(rows, cols uint16) error

func (*FakeTerminal) Resizes

func (t *FakeTerminal) Resizes() [][2]uint16

Resizes 返回全部 Resize 调用记录(行、列)。

func (*FakeTerminal) SetReadDeadline

func (t *FakeTerminal) SetReadDeadline(tm time.Time) error

func (*FakeTerminal) Size

func (t *FakeTerminal) Size() (rows, cols uint16)

Size 返回当前尺寸。

func (*FakeTerminal) Wait

func (t *FakeTerminal) Wait() ExitStatus

func (*FakeTerminal) Write

func (t *FakeTerminal) Write(b []byte) (int, error)

type Spawner

type Spawner interface {
	Spawn(spec Spec) (Terminal, error)
}

Spawner 创建伪终端会话。

func NewSpawner

func NewSpawner() Spawner

NewSpawner 返回基于 go-pty 的真实伪终端实现(Unix 使用 PTY,Windows 使用 ConPTY)。

type Spec

type Spec struct {
	Path string   // 可执行文件路径
	Args []string // 参数(不含 argv[0])
	Env  []string // 完整环境(KEY=VALUE);nil 表示继承当前进程环境
	Dir  string   // 工作目录;空表示继承
	Rows uint16   // 初始尺寸,0 表示 24×80
	Cols uint16
}

Spec 描述要在伪终端里启动的进程。

type Terminal

type Terminal interface {
	// Read 读取子进程输出;Write 向子进程写入输入。
	io.ReadWriter

	// Resize 调整终端尺寸(行、列)。
	Resize(rows, cols uint16) error

	// Pid 返回子进程号(供展示)。
	Pid() int

	// Wait 阻塞到子进程退出。
	Wait() ExitStatus

	// Kill 尽力终止子进程及其进程树:先礼貌地挂断,仍未退出则强制结束。不阻塞。
	Kill()

	// SetReadDeadline 为 Read 设置期限,用于进程退出后有界地排空残余输出。
	// 平台不支持时返回错误,调用方应改用 Close 来解除阻塞的 Read。
	SetReadDeadline(t time.Time) error

	// Close 释放伪终端资源并解除阻塞中的 Read / Write(幂等)。
	Close() error
}

Terminal 是一个已经启动了子进程的伪终端(主端视角)。

并发约定:Read / Write / Resize / Kill / SetReadDeadline 可以来自不同的 goroutine; Wait 可被多次调用,均在进程退出后返回同一结果。

Jump to

Keyboard shortcuts

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