terminal

type Terminal interface {
	// GetInfo 返回命令信息；结束前只有启动时的字段和 running。
	GetInfo() TerminalInfo
	// ReadOutput 返回 cursor 之后的输出：已有就立即返回，否则等新输出、命令结束或 wait 到期；只取消这次等待，不影响命令。
	ReadOutput(ctx context.Context, cursor uint64, wait time.Duration) (TerminalOutput, error)
	// WriteInput 把 chars 原样写进 PTY，返回实际写入的字节数；非 PTY 命令返回 ErrInputUnavailable，命令已结束返回 ErrTerminalFinished。
	// PTY 里的程序不读输入且 chars 超出 PTY 缓冲时，一直等到程序读走或写入失败；ctx 结束时立即返回 ctx 错误，
	// 已开始的写入留在后台，到程序读走或命令结束关闭终端时结束。
	WriteInput(ctx context.Context, chars string) (int, error)
	// Stop 终止进程组并等到收尾完成，返回最终信息；已结束时直接返回。调用方取消等待不撤回已接受的停止。
	Stop(ctx context.Context) (TerminalInfo, error)
}

type TerminalInfo struct {
	ID            string
	EnvironmentID string
	Command       string
	Directory     string
	// Interactive 是否用 PTY 启动命令？
	Interactive bool
	Status      TerminalStatus
	// ExitCode 只有 exited 有；被信号终止时为 -1。
	ExitCode   *int
	StopReason TerminalStopReason
	// Err 是 failed 的原因，例如 SSH 断开后无法确认远端已停止。
	Err error
}

type TerminalManager interface {
	// Run 阻塞到 ctx 结束；之后不再接受新命令，停止并等待全部 Terminal 后返回。只能调用一次。
	Run(ctx context.Context) error
	// StartTerminal 启动一条命令；进程启动成功才返回 Terminal，失败时不返回编号。命令不随 ctx 取消。
	StartTerminal(ctx context.Context, request *TerminalRequest) (Terminal, error)
	// GetTerminal 按编号查 environmentID 上启动成功、还没淘汰的命令；否则返回 ErrTerminalNotFound。
	GetTerminal(environmentID, terminalID string) (Terminal, error)
	// ListTerminals 按启动先后返回 environmentID 上启动成功、还没淘汰的命令。
	ListTerminals(environmentID string) []Terminal
	// IsBusy 是否还有没结束的命令？正在启动的也算。
	IsBusy() bool
}

type TerminalManagerOpt struct {
	// MaxTerminals 是一个 Session 最多保留的命令数，所有环境合计；正在启动、启动失败和已结束未淘汰的都算。
	MaxTerminals int
	// MaxOutputBytes 是每条命令保留的输出末尾。
	MaxOutputBytes int
}

type TerminalOutput struct {
	Info TerminalInfo
	// Text 从实际起点起最多 64 KiB，不切断 UTF-8 字符。
	Text       string
	NextCursor uint64
	// HasMore 读取时还有保留的输出没返回？
	HasMore bool
	// Truncated 请求的 cursor 已被丢弃，Text 从保留的最早位置开始？
	Truncated bool
}

type TerminalRequest struct {
	EnvironmentID string
	Workspace     workspace.Workspace
	Command       string
	// Directory 是工作目录，绝对路径，由工具按工作区根目录算好。
	Directory string
	// Interactive 是否用 PTY 启动命令？是时 stdout 和 stderr 合并成一条输出流，之后可以写入输入。
	Interactive bool
	// Timeout 是从启动成功起的总运行时限，0 表示不限。
	Timeout time.Duration
}

type TerminalStatus string

type TerminalStopReason string