Documentation
¶
Overview ¶
Package edge 是 Cloudpath 边缘代理运行时：串口设备监督（热插拔自愈）、 轮询/对时调度、状态上报与命令执行（WS 持久连接）。
Index ¶
- Constants
- func PortRequired(adapterName string) bool
- func Run(ctx context.Context, cfg *Config, version string, opts ...RunOption) error
- func SanitizeDetail(s string) string
- type Config
- type DeviceCfg
- type Edge
- type PluginHost
- type PluginHostCfg
- type PortOptionalAdapter
- type ResultSender
- type RunOption
Constants ¶
const ( DefaultPollCommand = "dump" // 触发一次状态读取 DefaultSyncCommand = "sync" // 触发一次设备侧时间/基准对齐 )
生命周期命令名：edge 在设备打开后与每个轮询拍尝试下发。
核心**设备无关**：这两个名字只是缺省约定，是否真的下发由适配器命令白名单决定 （不在白名单内则静默跳过，不报错、不刷日志），并可用 DeviceCfg.PollCommand / SyncCommand 按设备覆盖。这样无硬件参考设备（examples/demo）不会因为核心 硬编码真实板子的对时命令而在每次打开/每个对时周期报错。
const DetailLimit = plugincontrol.DetailLimit
DetailLimit 是 command_ack.detail 的长度上限（与插件控制面共用同一上限）。
Variables ¶
This section is empty.
Functions ¶
func Run ¶
Run 启动 edge 并阻塞至 ctx 取消（信号停机由 main 负责）。 启用外部 Driver Plugin Host 时：先装载/启动 host，再运行内置 device supervisor； ctx 取消时两者都收敛，host 在 CloseTimeout 内优雅关闭（不留孤儿）。
func SanitizeDetail ¶
SanitizeDetail 把适配器给出的命令执行摘要收敛成可安全上报的单行事实。
实现只有一份，在 internal/plugincontrol（Edge 的设备面与插件面共用同一条上报 红线，不各造一套脱敏规则）；本包保留同名薄封装，让设备命令路径读起来是本地语义。
红线：不含明文 secret / 访问令牌 / 本机绝对路径 / 进程 stdout、stderr 原文； 端口名（COM3、/dev/ttyUSB0）是公开的设备元数据，刻意保留。
Types ¶
type Config ¶
type Config struct {
Server string `yaml:"server"` // ws://host:port/ws/edge
Token string `yaml:"token"` // 支持 ${ENV} 展开
EdgeID string `yaml:"edge_id"` // 缺省用主机名
PollIntervalS int `yaml:"poll_interval_s"` // 转储轮询（默认 5）
SyncIntervalS int `yaml:"sync_interval_s"` // 对时周期（默认 600）
ReportIntervalS int `yaml:"report_interval_s"` // 状态心跳兜底（默认 30）
Devices []DeviceCfg `yaml:"devices"`
PluginHost PluginHostCfg `yaml:"plugin_host"`
}
Config 是 edge 配置（edge.yaml，本地私有不入库）。
func LoadConfig ¶
LoadConfig 读取并校验配置。Token 等字段支持 ${ENV_VAR} 展开（凭据不落盘）。
type DeviceCfg ¶
type DeviceCfg struct {
ID string `yaml:"id"`
Adapter string `yaml:"adapter"` // 设备适配器名（如 stcb / demo）
Name string `yaml:"name"`
Port string `yaml:"port"` // Windows: COM3；Linux: /dev/ttyUSB0；无硬件适配器可省略
Baud int `yaml:"baud"` // 默认 9600
// Extra 是适配器自定义参数，原样传给 driverkit.Config.Extra
// （例如 demo 的 tick_interval_s）。核心不解释其中任何键。
Extra map[string]string `yaml:"extra"`
// PollCommand / SyncCommand 覆盖生命周期命令名（缺省 dump / sync）。
// 无论叫什么，都只在适配器命令白名单内才会真正下发。
PollCommand string `yaml:"poll_command"`
SyncCommand string `yaml:"sync_command"`
}
DeviceCfg 是单台设备配置。
type Edge ¶
type Edge struct {
// contains filtered or unexported fields
}
Edge 是边缘代理运行时：N 台设备监督协程 + 1 条 server 长连接。
type PluginHost ¶
type PluginHost interface {
Start(ctx context.Context) error
Run(ctx context.Context) error
DriverIDs() ([]string, error)
DriverClient(driverID string) (driver.DriverClient, error)
}
PluginHost 是进程内外部 Driver Plugin Host 的生命周期接口。 由 edgedriverhost.Host 实现；测试注入 fake，不启动真实第三方插件。
type PluginHostCfg ¶
type PluginHostCfg struct {
Enabled bool `yaml:"enabled"` // false=不启用外部 host（默认）
Root string `yaml:"root"` // 插件安装根目录（如 plugins.d）
StateDir string `yaml:"state_dir"` // 插件实例 desired-state 目录
Tenant string `yaml:"tenant"` // 外部 driver 实例租户（缺省 default）
Required bool `yaml:"required"` // true=host 失败则 edge 启动失败；false=optional(DEGRADED)
Lock string `yaml:"lock"` // plugins.lock 路径（缺省 <root>/plugins.lock）
CloseTimeoutS int `yaml:"close_timeout_s"` // host 优雅关闭 deadline（秒，默认 10）
// SyncState 是插件控制面本地 applied cache 路径（缺省 <state_dir>/applied.json）：
// 保存最近成功应用的 revision + server 下发的规范化摘要 + 每实例结果，
// 进程重启后据此拒绝旧 revision（control-plane-sync.md §3.2）。
SyncState string `yaml:"sync_state"`
// SecretDir 是本地 secret provider 根目录（缺省 <state_dir>/secrets）：
// 明文只存在于 <dir>/<tenant>/<instance>/<name>，永不进 WS/日志/cache（§7）。
SecretDir string `yaml:"secret_dir"`
}
PluginHostCfg 配置可选的进程内外部 Driver Plugin Host。默认不启用，保持 纯内置 adapter 行为；启用时按 desired-state + lockfile 启动外部 driver 实例。
type PortOptionalAdapter ¶
type PortOptionalAdapter interface{ PortRequired() bool }
PortOptionalAdapter 由无硬件适配器可选实现：PortRequired() == false 表示 该适配器不需要真实端口，配置校验放宽 port 必填。
这是**结构性约定**而不是 driverkit 契约：examples/* 有「不得 import internal/*」 的拆仓红线，因此约定同时写在本包与适配器包（examples/demo）的文档里，靠方法名 与签名对齐。未实现该接口的适配器（如 stcb）一律 port 必填——校验强度不被削弱； 适配器未注册时同样按必填处理（fail-closed）。
type ResultSender ¶
type ResultSender interface {
SendWithResult(ctx context.Context, c device.Command) (result string, err error)
}
ResultSender 由适配器设备可选实现：Send 的「带执行结果摘要」版本。
为什么是 internal/edge 内的结构性约定而不是 driverkit 契约：
- examples/* 有「不得 import internal/*」的拆仓红线；
- driverkit.Device.Send 的签名是已发布 SDK 契约，加方法会破坏全部外部适配器。
因此约定写在两侧文档里（本包 + examples/demo），靠方法名与签名 对齐。未实现时 edge 回落 Device.Send + fallbackResult。
红线：返回的摘要必须是**短的非敏感事实**——不含明文 secret / 访问令牌 / 本机绝对路径 / 进程 stdout、stderr 原文。edge 出网前再统一过 SanitizeDetail。
type RunOption ¶
type RunOption func(*runOptions)
RunOption 调整 Run 行为（上层注入外部 Driver Plugin Host）。
func WithPluginHost ¶
func WithPluginHost(h PluginHost) RunOption
WithPluginHost 注入外部 Driver Plugin Host；nil 等价于未启用。
func WithPluginSync ¶
func WithPluginSync(s *plugincontrol.Syncer) RunOption
WithPluginSync 注入插件控制面收敛器（control-plane-sync.md §3.2/§4/§7/§8）。 nil 等价于本 Edge 不承载插件面：plugin_desired 被忽略并记 debug，不断连。
Source Files