pangolin/server/internal/agentd/config.go

// Package agentd implements the Pangolin node agent: a lightweight daemon that
// runs on every acceleration node. It self-enrolls over mTLS, dials the control
// plane (the agent is always the dialer), keeps a long-lived gRPC connection with
// exponential-backoff reconnect, reports heartbeat/usage, and applies the streamed
// command feed by managing the local sing-box user table.
//
// No-state invariant (doc/04 §2, doc/06 §3): the agent persists ONLY the
// credential table (dp_uuid + expires_at) to disk. It keeps zero user identities
// and writes no access logs. A seized node leaks only opaque dp_uuids, never
// accounts.
//
// 例外(私有目的地 ACL):节点本地 acl.json 含一份 dp_uuid 白名单与目的地清单,
// 由运营手工维护、不经控制面。它确实让节点知道「这几个 dp_uuid 享有私有访问权」
// 以及那几个私有域名/端口 —— 这是知情接受的不变式弱化,范围仅限该文件与渲染出的
// route 规则,不涉及账户身份,也不产生任何访问日志。设计见
// docs/private-dest-acl-design.html §12。
package agentd

import (
	"path/filepath"
	"time"
)

// Default tuning values. The intervals match doc/06 (30s heartbeat) and the
// 500ms render debounce that batches bursts of credential changes into a single
// sing-box restart (sing-box has no hot-reload; a restart is a ~1-2s blip).
const (
	DefaultHeartbeatInterval = 30 * time.Second
	DefaultUsageInterval     = 60 * time.Second
	DefaultTTLScanInterval   = 15 * time.Second
	DefaultDebounceWindow    = 500 * time.Millisecond
	DefaultDialTimeout       = 10 * time.Second

	DefaultBackoffMin = 1 * time.Second
	DefaultBackoffMax = 60 * time.Second

	DefaultStateDir   = "/etc/pangolin-agent"
	DefaultSingboxCfg = "/etc/sing-box/config.json"

	// DefaultFlow is the REALITY VLESS flow (doc/02 §3.1).
	// Kept here as an alias; canonical definition is in internal/dpcred.
	DefaultFlow = "xtls-rprx-vision"
)

// Config holds everything the agent needs. Most fields come from cloud-init
// (control-plane address + bootstrap token) or have safe defaults.
type Config struct {
	// ControlPlaneAddr is the control plane gRPC endpoint (host:port).
	ControlPlaneAddr string
	// ServerName overrides the TLS SNI used when dialing (defaults to the host
	// part of ControlPlaneAddr). The control plane cert must match it.
	ServerName string

	// BootstrapToken is the one-time cloud-init token consumed during Enroll.
	// Ignored once the node already holds a certificate.
	BootstrapToken string

	// StateDir holds node.key/node.crt/ca.crt and state.json.
	StateDir string
	// SingboxConfigPath is where the rendered sing-box config is written.
	SingboxConfigPath string

	// WarpConfigPath 指向节点本地的 WARP 分流配置(默认 <StateDir>/warp.json)。
	// 文件不存在 = WARP 未启用。渲染时读取,支持编辑后重启 agent 生效(#29)。
	WarpConfigPath string

	// ACLConfigPath 指向节点本地的私有目的地访问控制表(默认 <StateDir>/acl.json)。
	// 文件不存在 = 该功能未配置。渲染时读取,SIGHUP agent 即可生效。
	ACLConfigPath string

	// DeriveKey keys the Hy2 password derivation (see DeriveHy2Password).
	DeriveKey string

	AgentVersion string

	HeartbeatInterval time.Duration
	UsageInterval     time.Duration
	TTLScanInterval   time.Duration
	DebounceWindow    time.Duration
	DialTimeout       time.Duration
	BackoffMin        time.Duration
	BackoffMax        time.Duration

	// Insecure dials without mTLS. ONLY for local dev / integration tests.
	Insecure bool
}

// withDefaults returns a copy of c with zero-valued tunables filled in.
func (c Config) withDefaults() Config {
	if c.StateDir == "" {
		c.StateDir = DefaultStateDir
	}
	if c.SingboxConfigPath == "" {
		c.SingboxConfigPath = DefaultSingboxCfg
	}
	if c.WarpConfigPath == "" {
		c.WarpConfigPath = filepath.Join(c.StateDir, "warp.json")
	}
	if c.ACLConfigPath == "" {
		c.ACLConfigPath = filepath.Join(c.StateDir, "acl.json")
	}
	if c.HeartbeatInterval == 0 {
		c.HeartbeatInterval = DefaultHeartbeatInterval
	}
	if c.UsageInterval == 0 {
		c.UsageInterval = DefaultUsageInterval
	}
	if c.TTLScanInterval == 0 {
		c.TTLScanInterval = DefaultTTLScanInterval
	}
	if c.DebounceWindow == 0 {
		c.DebounceWindow = DefaultDebounceWindow
	}
	if c.DialTimeout == 0 {
		c.DialTimeout = DefaultDialTimeout
	}
	if c.BackoffMin == 0 {
		c.BackoffMin = DefaultBackoffMin
	}
	if c.BackoffMax == 0 {
		c.BackoffMax = DefaultBackoffMax
	}
	if c.AgentVersion == "" {
		c.AgentVersion = "dev"
	}
	return c
}

// Paths to the on-disk PKI + state material.
func (c Config) KeyPath() string   { return filepath.Join(c.StateDir, "node.key") }
func (c Config) CertPath() string  { return filepath.Join(c.StateDir, "node.crt") }
func (c Config) CAPath() string    { return filepath.Join(c.StateDir, "ca.crt") }
func (c Config) StatePath() string { return filepath.Join(c.StateDir, "state.json") }

// ACLLastGoodPath 是最近一次成功加载的 ACL 快照,供 agent 冷启动时在 acl.json
// 损坏的情况下兜底(fail-closed 跨重启成立的前提)。
func (c Config) ACLLastGoodPath() string { return filepath.Join(c.StateDir, "acl.last-good.json") }