holder

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: 33 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// IPCVersion 是本地协议的主版本;不一致时双方都拒绝并给出明确原因。
	IPCVersion = 1

	TIPCOpen        = "ipc_open"
	TIPCHello       = "ipc_hello"
	TIPCList        = "ipc_list"
	TIPCDetachAll   = "ipc_detach_all"
	TIPCShutdown    = "ipc_shutdown"
	TIPCStatus      = "ipc_status"
	TIPCStatusReply = "ipc_status_reply"
	TIPCBye         = "ipc_bye"
)

守护进程与控制端(Agent)之间的本地协议。

数据面完全复用 Agent↔Hub 的帧(open / attach / detach / resize / kill / rename / policy / sessions、 以及二进制的输出 / 输入 / 确认),Agent 只做近乎透明的转发;这里只定义本地独有的几种帧: 握手(ipc_open / ipc_hello)、查询(ipc_list / ipc_status)、通道清场(ipc_detach_all)、 关停(ipc_shutdown)与告别(ipc_bye)。

View Source
const (
	// RoleController 是唯一的控制端(Agent):持有数据通道、接收会话清单推送。同一时刻只有一个,新来的取代旧的。
	RoleController = "controller"
	// RoleAdmin 是只做查询与关停的管理连接(命令行用),不影响控制端。
	RoleAdmin = "admin"
)

连接角色。

View Source
const (
	CapPTY    = "pty"    // 持久伪终端会话
	CapPolicy = "policy" // 策略下发与本地持久化
	CapDrain  = "drain"  // 排空式关停
	CapLost   = "lost"   // 上报「重启后丢失的会话」及原因
	// CapCharset:新建会话时把字符类别钉在 LC_CTYPE 上(见 locale_unix.go 的 ensureUTF8),登录脚本把 LANG 改回 C 也不影响中文输入。
	// 会话是守护进程创建的,而升级只替换 Agent、不会重启守护进程,所以 Hub 靠这个能力位告诉用户「这台主机的守护进程还没带上这项修复」。
	CapCharset = "charset"
	CapExec    = "exec"                 // 模型执行(非交互命令运行,输出保存在本机)
	CapSSH     = termproto.HolderCapSSH // SSH 网关:本机开启了 --ssh-gateway,可替 Hub 连接 SSH 目标
	// CapSSHStore:网关的凭据库可用,目标的登录凭据可以保存在这台网关本机(Hub 不保管)。没有它,Hub 不会把主机登记到这台网关上。
	CapSSHStore = termproto.HolderCapSSHStore
	// CapRecLines:记录引擎支持按行数限高(见 record.Policy.SessionLines)。
	CapRecLines = termproto.HolderCapRecLines
)

能力位:双方各自声明,取交集使用;缺失的能力降级而不是报错(INV-H2)。

View Source
const (
	// ShutdownNow 立即终止全部会话并退出。
	ShutdownNow = "now"
	// ShutdownDrain 不再接受新会话与新命令,等运行中的会话和模型命令都自然结束后退出。
	ShutdownDrain = "drain"
)

关停方式。

View Source
const (
	LostHostReboot    = "host_reboot"    // 主机重启(启动标识变了)
	LostHolderExit    = "holder_exit"    // 守护进程在会话存续期间退出(崩溃或被杀)
	LostHolderStopped = "holder_stopped" // 守护进程被有意停止(停止单元 / 关停命令)
	LostUnknown       = "unknown"
)

会话丢失原因:界面据此给出人能看懂的说明,而不是一个无解释的「会话没了」。

View Source
const (
	ByeSuperseded = "superseded" // 另一个控制端取代了它
	ByeVersion    = "version"    // 主版本不兼容
	ByeShutdown   = "shutdown"   // 守护进程正在关停
	ByeBadRequest = "bad_request"
)

本地协议的 bye 原因。

View Source
const (
	// MaxIPCMessage 是本地连接上单条消息的净荷上限(输出帧 ≤ 32 KiB、控制帧 ≤ 64 KiB,留足余量)。
	MaxIPCMessage = 1 << 20
)

Variables

View Source
var (
	// ErrTerminalDisabled 表示终端功能被策略关闭(总闸关闭)。
	ErrTerminalDisabled = errors.New("terminal is disabled by server policy")
	// ErrSessionLimit 表示已达会话数上限。
	ErrSessionLimit = errors.New("session limit reached")
	// ErrShuttingDown 表示守护进程(或内嵌模式下的 Agent)正在退出。
	ErrShuttingDown = errors.New("holder is shutting down")
	// ErrDraining 表示守护进程正在排空:不再接受新会话,等现有会话自然结束后退出。
	ErrDraining = errors.New("holder is draining, no new sessions")
)
View Source
var (
	// ErrAlreadyRunning 表示套接字已被另一个守护进程占用。
	ErrAlreadyRunning = errors.New("holder is already running")
	// ErrNotRunning 表示连不上守护进程(没启动、已停止或已崩溃)。
	ErrNotRunning = errors.New("holder is not running")
)
View Source
var (

	// ErrConnClosed 表示连接已被本端关闭。
	ErrConnClosed = errors.New("holder ipc: connection closed")
)
View Source
var (
	// ErrHostClosed 表示 Host 已关闭,不再接受连接。
	ErrHostClosed = errors.New("holder host is closed")
)
View Source
var ErrOverwritten = termstate.ErrOverwritten

ErrOverwritten 表示请求的偏移已经被环形缓冲覆盖。

Functions

func DefaultCaps

func DefaultCaps() []string

DefaultCaps 是本实现支持的全部能力位。

func DefaultShell

func DefaultShell(rows, cols uint16) (ptyhost.Spec, error)

DefaultShell 构造运行 Agent 的那个账户的登录 shell 的启动规格。

Agent 通常由 systemd / launchd 以 root 拉起,此时环境变量极其精简(甚至没有 HOME、SHELL), 所以 shell 的选择与基础环境不能依赖继承:优先取 /etc/passwd 里该账户的 shell, 其次 $SHELL,最后回落到系统里确实存在的 shell。

func DescribeLost

func DescribeLost(reason string) string

DescribeLost 把丢失原因翻译成给人看的短句。

func HasCap

func HasCap(caps []string, c string) bool

HasCap 判断能力列表里是否有 c。

func Listen

func Listen(path string, harden func(string) error) (net.Listener, error)

Listen 在 path 上监听本地套接字。路径上已有套接字文件时:能连通说明守护进程已在运行(拒绝重复启动); 连不通就是上次崩溃留下的残余,删除后重建。

func NewPipe

func NewPipe() (Conn, Conn)

NewPipe 返回两个互相连通的进程内 Conn(内嵌模式使用)。

func PurgeState

func PurgeState(dataDir string) []string

PurgeState 删除守护进程在数据目录下留下的状态文件、残留的套接字与(清空后的)目录,返回被删除的路径。 不碰目录里的其他文件。

func RecordDir

func RecordDir(dataDir string) string

RecordDir 返回终端记录的根目录。守护进程(写)与 Agent(读)对同一个数据目录总是算出同一个路径。

func Run

func Run(ctx context.Context, opts RunOptions) error

Run 运行外置守护进程直到 ctx 被取消或收到关停请求。返回前会终止全部会话并保存状态: 守护进程被有意停止就是在结束会话,下次启动会据此报告「守护进程被停止」。

func RunsDir

func RunsDir(dataDir string) string

RunsDir 返回运行输出在数据目录下的位置(与终端记录各自独立,配额与清理互不影响)。

func SSHCredDir

func SSHCredDir(dataDir string) string

SSHCredDir 返回 SSH 网关凭据库的目录(密封保存各 SSH 主机的登录凭据,只存在于这台网关本机)。

func SendControl

func SendControl(ctx context.Context, conn Conn, t string) error

SendControl 向守护进程发送一条无参数的本地控制帧(ipc_list / ipc_detach_all / ipc_status)。

func SendShutdown

func SendShutdown(ctx context.Context, conn Conn, mode string) error

SendShutdown 请求守护进程关停。

func ServeListener

func ServeListener(ctx context.Context, ln net.Listener, host *Host, logf func(string, ...any)) error

ServeListener 在 ln 上接受本地连接,交给 host 服务,直到 ctx 取消或监听出错。 每条连接先核对对端用户,同时在服务的连接数有上限。

func SocketPath

func SocketPath(dataDir string) string

SocketPath 返回守护进程本地套接字的路径。AF_UNIX 路径有长度上限,数据目录很深时 退回到一个由数据目录哈希得出的短路径(运行时目录或临时目录下,权限 0700)。 守护进程与 Agent 对同一个数据目录总是算出同一个路径。

func StateDir

func StateDir(dataDir string) string

StateDir 返回守护进程在数据目录下的工作目录(状态文件、记录等都放这里)。

Types

type ByeError

type ByeError struct{ Reason string }

ByeError 表示守护进程在握手或服务期间明确拒绝 / 结束了连接。

func (*ByeError) Error

func (e *ByeError) Error() string

type Client

type Client struct {
	Conn  Conn
	Hello IPCHello
}

Client 是一条完成握手的本地连接(Agent 或命令行用)。

func Handshake

func Handshake(ctx context.Context, conn Conn, role, clientVersion string) (*Client, error)

Handshake 在一条刚建立的 Conn 上完成 ipc_open → ipc_hello。失败时关闭连接。 守护进程可能在握手阶段回复 ipc_bye(例如版本不兼容),其原因会体现在错误里。

type Conn

type Conn interface {
	Read(ctx context.Context) (MsgType, []byte, error)
	Write(ctx context.Context, typ MsgType, data []byte) error
	Ping(ctx context.Context) error
	Close() error
}

Conn 是一条能收发整帧消息的连接。守护进程与 Agent 之间只有两种实现:本地套接字流与进程内管道。 方法的语义与 WebSocket 连接一致:Read 阻塞到有消息、连接断开或 ctx 取消;Write 可并发调用; Ping 需要对端的读循环在运行才能收到应答。

func Dial

func Dial(ctx context.Context, path string) (Conn, error)

Dial 连接 path 上的守护进程。连接前核对目录的归属,连接后核对对端身份, 避免连到别人在共享目录里预先放好的假守护进程(那样会把用户的键入送给别人)。

func NewStreamConn

func NewStreamConn(nc net.Conn) Conn

NewStreamConn 包装一条 net.Conn 并启动读协程与应答协程。

type ExecManager

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

ExecManager 管理一台主机上正在进行的运行。

func NewExecManager

func NewExecManager(o ExecOptions, logf func(string, ...any), now func() time.Time) *ExecManager

NewExecManager 创建运行管理器。存储目录打不开时记录日志并让运行以 exec_unavailable 失败,而不是让整个守护进程起不来。

func (*ExecManager) Ack

func (m *ExecManager) Ack(id string)

Ack 记录 Hub 已处理该运行的结束事件。

func (*ExecManager) ActiveCount

func (m *ExecManager) ActiveCount() int

ActiveCount 返回正在运行的命令数。

func (*ExecManager) Available

func (m *ExecManager) Available() bool

Available 报告本机能否执行模型命令(有输出目录与 shell;不含一票否决)。

func (*ExecManager) Cancel

func (m *ExecManager) Cancel(id, reason string)

Cancel 取消一次运行(不存在或已结束则忽略)。

func (*ExecManager) Denied

func (m *ExecManager) Denied() bool

Denied 报告本机是否一票否决了模型执行。

func (*ExecManager) Info

func (m *ExecManager) Info() *termproto.ExecInfo

Info 返回运行命令时的 shell / 目录约定(找不到 shell 时为 nil)。

func (*ExecManager) RecoverOrphans

func (m *ExecManager) RecoverOrphans(reason string)

RecoverOrphans 把上次没来得及收尾的运行标记为 lost(reason 说明为什么)。

func (*ExecManager) ServeRead

func (m *ExecManager) ServeRead(s runSink, r termproto.RunRead)

ServeRead 异步服务一次 run_read:按帧把已保存的输出送给请求方。

func (*ExecManager) SetDraining

func (m *ExecManager) SetDraining()

SetDraining 不再接受新的运行(排空式关停时调用);正在进行的运行不受影响。

func (*ExecManager) SetSink

func (m *ExecManager) SetSink(s runSink)

SetSink 设置运行事件的去向;nil 表示当前没有控制端。

func (*ExecManager) Shutdown

func (m *ExecManager) Shutdown(timeout time.Duration)

Shutdown 终止全部运行并停止后台任务;等待至多 timeout 让它们收尾落盘。

func (*ExecManager) Start

func (m *ExecManager) Start()

Start 启动后台任务:定期写出运行中的结尾、清理过期输出、转发实时输出。

func (*ExecManager) StartRun

func (m *ExecManager) StartRun(req termproto.Run) *termproto.RunFailed

StartRun 处理一个 run 请求:成功时发出 run_started,失败时发出 run_failed(并返回它,便于测试)。

func (*ExecManager) Store

func (m *ExecManager) Store() *runlog.Store

Store 返回输出存储(可能为 nil)。

func (*ExecManager) Sync

func (m *ExecManager) Sync()

Sync 向当前控制端发送运行清单,并补报尚未被确认的结束事件。幂等:Hub 对重复的结束事件以确认应答。

type ExecOptions

type ExecOptions struct {
	// Dir 是运行输出的保存目录;为空表示本机无法保存输出,运行一律失败(exec_unavailable)。
	Dir string
	// DenyExec 是「本机一票否决」:为 true 时所有 run 请求都以 denied_by_host 失败。
	DenyExec bool
	// MaxActive / KillGrace / Retention / Quota / HeadBytes / TailBytes 取默认值时填 0。
	MaxActive int
	KillGrace time.Duration
	Retention time.Duration
	Quota     int64
	HeadBytes int
	TailBytes int
	// Harden 收紧目录权限(由 Agent 提供)。
	Harden func(dir string) error
	// Resolve 解析 shell;为空时使用平台默认实现(测试里可替换)。
	Resolve func(name string) (execSpec, error)
}

ExecOptions 是运行管理器的构造参数。

type Host

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

Host 是「会话守护」的核心:持有 Manager,接受控制端连接,并(外置模式下)把状态落盘。

外置守护进程与 Agent 内嵌模式共用它:区别只在于连接的来源(本地套接字或进程内管道) 与是否持久化。因此两种模式走的是同一条代码路径,内嵌模式的测试同时也在验证外置模式。

func NewHost

func NewHost(opts HostOptions) (*Host, error)

NewHost 创建 Host。外置模式下会读取上一次的状态,据此算出「已丢失的会话」并立即写入新的状态。

func (*Host) ApplyPolicy

func (h *Host) ApplyPolicy(p termproto.Policy)

ApplyPolicy 应用并(外置模式下)持久化策略:Hub 离线期间守护进程仍按这份策略计时与回收。

func (*Host) Close

func (h *Host) Close(clean bool)

Close 终止全部会话并释放资源。clean 表示这是有意的停止:先把会话索引连同 clean 标记落盘(再终止), 下次启动时才能告诉用户「守护进程被停止」而不是「意外退出」。幂等。

func (*Host) Draining

func (h *Host) Draining() bool

Draining 报告是否处于排空状态。

func (*Host) Exec

func (h *Host) Exec() *ExecManager

Exec 返回模型执行管理器(未启用时为 nil)。

func (*Host) Hello

func (h *Host) Hello() IPCHello

Hello 返回当前的 ipc_hello 内容。

func (*Host) Manager

func (h *Host) Manager() *Manager

Manager 返回会话管理器(测试与内嵌模式观察用)。

func (*Host) Persistent

func (h *Host) Persistent() bool

Persistent 报告会话是否能挺过 Agent 的重启。

func (*Host) Records

func (h *Host) Records() *record.Store

Records 返回终端记录存储(未启用记录时为 nil)。

func (*Host) RequestShutdown

func (h *Host) RequestShutdown(mode string)

RequestShutdown 请求关停(仅外置守护进程响应)。立即关停由运行循环执行;排空则先停止接受新会话。

func (*Host) RunningWork

func (h *Host) RunningWork() (sessions, runs int)

RunningWork 返回仍在运行的交互会话数与模型命令数。 两者分属 Manager 与 ExecManager:模型命令不在会话表里,所以「还有没有人在用这个守护进程」必须两边都看—— 排空式关停要等这两类都归零,只数会话会在命令还在跑时就把它们终止(holder_stopped)。

func (*Host) Serve

func (h *Host) Serve(ctx context.Context, conn Conn) error

Serve 在一条新连接上完成握手并服务它,直到连接结束。控制端:同一时刻只有一个,新来的取代旧的; 管理端:只能查询与请求关停。

func (*Host) ShutdownRequests

func (h *Host) ShutdownRequests() <-chan string

ShutdownRequests 返回关停请求通道(运行循环消费)。

func (*Host) Start

func (h *Host) Start()

Start 启动周期任务(会话停滞检查与过期回收、状态刷新)。

type HostOptions

type HostOptions struct {
	Manager ManagerOptions
	// Version 是守护进程(内嵌模式下是 Agent)自己的版本,经 ipc_hello 报告。
	Version string
	// Rev 是守护进程二进制的「Agent 侧代码指纹」(见 termproto.ValidAgentRev),经 ipc_hello 报告;空表示非发布构建。
	Rev string
	// Persistent 为 true 表示这是外置守护进程:会话能挺过 Agent 的重启。
	Persistent bool
	// StateDir 非空时把会话索引与策略持久化到该目录(仅外置守护进程使用)。
	StateDir string
	// Record 非 nil 时启用终端记录(终端上显示什么就记录什么,只写在本机)。Dir 必填。
	Record *record.Options
	// Exec 非 nil 时启用模型执行(非交互命令运行)。其中 DenyExec 是本机一票否决。
	Exec *ExecOptions
	Logf func(string, ...any)
	Now  func() time.Time
}

HostOptions 是 Host 的构造参数。

type IPCBye

type IPCBye struct {
	T      string `json:"t"`
	Reason string `json:"reason"`
}

IPCBye 在守护进程主动结束一条连接前给出原因。

type IPCHello

type IPCHello struct {
	T          string   `json:"t"`
	V          int      `json:"v"`
	Holder     string   `json:"holder"`            // 守护进程自己的版本
	Rev        string   `json:"rev,omitempty"`     // 守护进程二进制的 Agent 侧代码指纹(旧版本没有)
	BootID     string   `json:"boot_id,omitempty"` // 主机启动标识(主机重启后变化)
	PID        int      `json:"pid"`               // 守护进程的进程号
	Started    int64    `json:"started"`           // 守护进程启动时间(Unix 秒)
	Persistent bool     `json:"persistent"`        // 会话是否能挺过 Agent 的重启(外置守护进程为 true,内嵌模式为 false)
	Caps       []string `json:"caps,omitempty"`
	Lost       []Lost   `json:"lost,omitempty"`
	// DenyExec 为 true 表示本机用 --deny-model-exec 一票否决了模型执行;Exec 描述运行命令时使用的 shell 与目录约定。
	DenyExec bool                `json:"deny_exec,omitempty"`
	Exec     *termproto.ExecInfo `json:"exec,omitempty"`
}

IPCHello 是守护进程对 ipc_open 的应答,携带版本、启动标识与能力。

type IPCOpen

type IPCOpen struct {
	T      string   `json:"t"`
	V      int      `json:"v"`
	Role   string   `json:"role"`
	Client string   `json:"client,omitempty"` // 客户端(Agent / 命令行)的版本
	Caps   []string `json:"caps,omitempty"`
}

IPCOpen 是客户端连上之后的第一帧。

type IPCShutdown

type IPCShutdown struct {
	T    string `json:"t"`
	Mode string `json:"mode"`
}

IPCShutdown 请求守护进程关停。

type IPCStatusReply

type IPCStatusReply struct {
	T          string                  `json:"t"`
	Hello      IPCHello                `json:"hello"`
	Sessions   []termproto.SessionInfo `json:"sessions"`
	Controller bool                    `json:"controller"` // 当前是否有控制端在连着
	Draining   bool                    `json:"draining,omitempty"`
	// Runs 是正在运行的模型命令数(terminal_exec 发起,由 ExecManager 持有,不在 Sessions 里)。
	// 用指针区分「0 条」与「这个守护进程太旧、没有这个字段」:旧版本的排空也不会等模型命令,命令行要据此提醒。
	Runs *int `json:"runs,omitempty"`
}

IPCStatusReply 是 ipc_status 的应答。

func Status

func Status(ctx context.Context, c *Client) (IPCStatusReply, error)

Status 向守护进程查询状态与会话清单(管理端 / 控制端都可以用)。

type Limits

type Limits struct {
	MaxSessions int // 每主机会话数上限
	RingSize    int // 每会话回放缓冲字节数
	// DetachedTTL 是本机允许的空闲回收上限:会话的生命周期(主机默认或会话单独设置)不得比它更宽松。
	// 0 表示本机不设上限,会话可以永久保持。服务端策略只能把它调得更短。
	DetachedTTL time.Duration
	ExitedTTL   time.Duration // 已退出会话的保留时长(自退出或最近一次断开起算)
}

Limits 是 Agent 强制执行的限额;服务端策略只能把它们调得更严(INV-P4)。

func DefaultLimits

func DefaultLimits() Limits

DefaultLimits 返回默认限额。

type Lost

type Lost struct {
	SID     string `json:"sid"`
	Name    string `json:"name,omitempty"`
	Shell   string `json:"shell,omitempty"`
	Cwd     string `json:"cwd,omitempty"` // 尽力而为:会话消失前最后一次记录到的工作目录
	Created int64  `json:"created,omitempty"`
	Reason  string `json:"reason"`
	At      int64  `json:"at,omitempty"` // 守护进程发现它已消失的时间(Unix 秒)
}

Lost 描述一个已经不存在的会话以及它消失的原因。

type Manager

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

Manager 管理一台主机上的全部会话。它独立于任何网络连接:连接断开、重连都不影响会话存续。 外置模式下它运行在守护进程(holder)里,因此也独立于 Agent 进程;内嵌模式下它随 Agent 进程存亡。

func NewManager

func NewManager(opts ManagerOptions) *Manager

NewManager 创建会话管理器。

func (*Manager) ApplyPolicy

func (m *Manager) ApplyPolicy(p termproto.Policy)

ApplyPolicy 应用服务端下发的策略:取本地默认与策略中更严的一方;终端被关闭时终止全部会话。

func (*Manager) Count

func (m *Manager) Count() int

Count 返回当前会话数(含已退出但尚未回收的)。

func (*Manager) Get

func (m *Manager) Get(sid string) *Session

Get 按 ID 查找会话。

func (*Manager) KillAll

func (m *Manager) KillAll()

KillAll 终止全部会话。

func (*Manager) Open

func (m *Manager) Open(name string, rows, cols uint16) (termproto.SessionInfo, error)

Open 新建会话。

func (*Manager) OpenWith

func (m *Manager) OpenWith(oo OpenOptions) (termproto.SessionInfo, error)

OpenWith 新建一个会话。

func (*Manager) RunningCount

func (m *Manager) RunningCount() int

RunningCount 返回仍在运行的会话数(不含已退出但尚未回收的)。

func (*Manager) SSHEnabled

func (m *Manager) SSHEnabled() bool

SSHEnabled 报告本机是否开启了 SSH 网关。

func (*Manager) SSHOp

func (m *Manager) SSHOp(op termproto.SSHOp) termproto.SSHResult

SSHOp 执行一次性的 SSH 操作(探测主机密钥 / 真实登录检查)。网关未开启时返回 gateway_disabled。

func (*Manager) SSHStoreReady

func (m *Manager) SSHStoreReady() bool

SSHStoreReady 报告网关的凭据库是否可用(可托管目标的登录凭据)。

func (*Manager) SetDraining

func (m *Manager) SetDraining()

SetDraining 进入排空状态:此后不再接受新会话。不可逆。

func (*Manager) SetNotifier

func (m *Manager) SetNotifier(fn func())

SetNotifier 注册「会话集合或状态发生变化」的回调(用于向 Hub 推送会话清单)。 回调在不持有任何锁的情况下被调用,必须快速返回。

func (*Manager) SetObserver

func (m *Manager) SetObserver(fn func())

SetObserver 注册第二个「会话集合或状态发生变化」的回调,供守护进程持久化会话索引。 与 SetNotifier 相互独立:控制端换人不会影响它。回调同样在不持有任何锁的情况下被调用。

func (*Manager) Shutdown

func (m *Manager) Shutdown(timeout time.Duration)

Shutdown 终止全部会话并停止周期任务(守护进程被有意停止、或内嵌模式下 Agent 退出前调用)。

func (*Manager) Snapshot

func (m *Manager) Snapshot() []termproto.SessionInfo

Snapshot 返回全部会话的当前信息(按创建顺序)。

func (*Manager) Start

func (m *Manager) Start()

Start 启动周期任务(停滞检查与过期回收)。重复调用无副作用。

type ManagerOptions

type ManagerOptions struct {
	Spawner ptyhost.Spawner // 默认 ptyhost.NewSpawner()
	Shell   ShellFunc       // 默认 DefaultShell
	Limits  Limits          // 零值字段回落到 DefaultLimits
	// Record 是终端显示内容的本地记录存储;nil 表示不提供录制能力(会话信息里不带录制状态)。
	Record *record.Store
	// RecordFailed 表示记录存储本该启用却打不开:会话照常提供,但信息里标注录制出错。
	RecordFailed bool
	// SSH 非 nil 表示本机开启了 SSH 网关(--ssh-gateway):会话守护进程可以替 Hub 去连接 SSH 目标。
	SSH  *SSHOptions
	Logf func(format string, args ...any)
	Now  func() time.Time
}

ManagerOptions 是 Manager 的构造参数。

type ModeTracker

type ModeTracker = termstate.ModeTracker

ModeTracker 跟踪重新附着时必须恢复的终端模式(见 termstate.ModeTracker)。

func NewModeTracker

func NewModeTracker() *ModeTracker

NewModeTracker 创建处于初始状态的模式跟踪器。

type MsgType

type MsgType uint8

MsgType 区分控制帧(JSON 文本)与数据帧(二进制);与 WebSocket 的两种消息类型一一对应, 这样 Agent 才能把 Hub 的帧原样转发给守护进程,而不必重新编码。

const (
	MsgText   MsgType = 1
	MsgBinary MsgType = 2
)

type OpenOptions

type OpenOptions struct {
	Name       string
	Rows, Cols uint16
	// Incognito 为 true 时本会话不录制,主机上不留任何记录。
	Incognito bool
	// Compact 为 true 时是精简会话:回放缓冲 CompactRingSize、宽度不超过 CompactMaxCols。
	Compact bool
	// IdleSec 是本会话单独设置的空闲回收秒数(0 = 永久保持);nil 沿用主机默认。
	IdleSec *int
	// Cwd 是新会话的启动目录;不是主机上存在的绝对目录时忽略(回落到默认目录)。
	Cwd string
	// SSH 非空表示这是经 SSH 网关的会话(Cwd 对它没有意义)。只接受引用本机凭据库的目标(Stored),凭据由网关自己取用,不会被保存到会话里。
	SSH *termproto.SSHTarget
}

OpenOptions 是新建会话的参数。

type Ring

type Ring = termstate.Ring

Ring 是按累计字节偏移寻址的环形缓冲(见 termstate.Ring)。

func NewRing

func NewRing(size int) *Ring

NewRing 创建容量为 size 字节的环形缓冲。

type RunOptions

type RunOptions struct {
	// DataDir 是 Agent 的数据目录;守护进程的状态与套接字都放在其下的 holder/ 里。
	DataDir string
	// Socket 覆盖默认套接字路径(空则按 DataDir 推算)。
	Socket  string
	Version string
	// Rev 是守护进程二进制的 Agent 侧代码指纹(见 termproto.ValidAgentRev);空表示非发布构建。
	Rev    string
	Limits Limits
	// Record 是终端记录的配置(零值取默认;目录默认为 <DataDir>/records)。Record.Disabled 是本机一票否决。
	Record record.Options
	// Exec 是模型执行的配置(零值取默认;输出目录默认为 <DataDir>/runs)。Exec.DenyExec 是本机一票否决。
	Exec ExecOptions
	// SSH 非 nil 表示开启了 SSH 网关(--ssh-gateway)。
	SSH  *SSHOptions
	Logf func(string, ...any)
	// HardenDir 收紧目录访问权限(Windows 设置 ACL);Unix 为 nil。
	HardenDir func(string) error

	// 以下字段供测试注入。
	Spawner ptyhost.Spawner
	Shell   ShellFunc
	// Ready 在开始监听之后被调用,参数是实际使用的套接字路径。
	Ready func(socket string)
}

RunOptions 是外置守护进程(`holder run`)的运行参数。

type SSHOpenError

type SSHOpenError struct {
	Code string
	Msg  string
}

SSHOpenError 是 SSH 会话 / 操作失败的结构化错误:Code 是稳定的 termproto.SSHCode*,Msg 只含类别说明。

func (*SSHOpenError) Error

func (e *SSHOpenError) Error() string

type SSHOptions

type SSHOptions struct {
	// Allow 是允许连接的目标:CIDR(10.0.0.0/8)、单个 IP、或主机名(可含 * 通配,如 *.corp.example)。
	// 为空表示不限制。
	Allow []string
	// DialTimeout 是单次建连(含握手与认证)的上限;<=0 取默认。
	DialTimeout time.Duration
	// MaxConcurrent 是同时进行的建连 / 管理类 ssh_op 数上限;<=0 取默认。
	MaxConcurrent int
	// ExecConcurrent 是同时进行的 exec 代理数上限(Hub 经网关管理远端作业会很频繁);<=0 取默认。
	ExecConcurrent int
	// CredDir 是凭据库目录(通常是 <数据目录>/ssh-gateway)。为空表示没有可用的凭据库:网关无法保存凭据,
	// 也就不会宣告「可托管凭据」,Hub 不会把主机登记到它上面。
	CredDir string
	// CredKey 是外置的凭据库密封密钥(RELAYMESH_AGENT_SSH_CRED_KEY,至少 16 个字符);为空则使用目录里自动生成的 key 文件。
	CredKey string
	// Harden 收紧凭据库目录的访问权限(Windows 上设置 ACL);nil 表示只依赖文件权限。
	Harden func(dir string) error
}

SSHOptions 是 SSH 网关的本机选项;非 nil 即表示已开启网关能力。

func (*SSHOptions) Validate

func (o *SSHOptions) Validate() error

Validate 校验网关选项(目前是允许名单的格式),供命令行在启动前给出明确的错误。

type Session

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

Session 是 Agent 上的一个终端会话:一个伪终端 + 其中运行的进程 + 回放缓冲。

生命周期与任何网络连接无关(INV-P1):只有进程自身退出、被 kill、TTL 到期或 Agent 进程退出才会结束。 所有可变状态由 mu 保护;cond 用于唤醒等待输出 / 确认 / 状态变化的 goroutine。 持有 mu 时绝不做网络 I/O,也绝不调用可能再次加锁的方法。

type ShellFunc

type ShellFunc func(rows, cols uint16) (ptyhost.Spec, error)

ShellFunc 构造在新会话里运行的 shell 的启动规格。

Jump to

Keyboard shortcuts

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