agent

type DoctorAllowTargets struct {
	// Set は一覧を持っているかどうか。偽なら、server はこのエージェントが届くどの宛先も指せる
	Set bool `json:"set"`
	// List は正規化した一覧。Set が偽なら空
	List string `json:"list,omitempty"`
	// Env は一覧を渡す設定の名前
	Env string `json:"env"`
}

type DoctorBudget struct {
	Proto proto.Proto `json:"proto"`
	// Total は予算 T、InUse は今のフロー数 u である
	Total int `json:"total"`
	InUse int `json:"in_use"`
	// RuleCap はルールが 2 本以上あるときのルール 1 本の上限 C、Reserve はルール 1 本あたりの
	// 隔離予約 q、Rules は今受け付けているルールの数 N である
	RuleCap int `json:"rule_cap"`
	Reserve int `json:"reserve"`
	Rules   int `json:"rules"`
	// Refusals は拒否の累計である。起点は DoctorRuntimeState.RefusalsSince
	Refusals []DoctorRefusal `json:"refusals,omitempty"`
}

type DoctorKernel struct {
	Interface  DoctorKernelInterface  `json:"interface"`
	Table      DoctorKernelTable      `json:"table"`
	Forwarding DoctorKernelForwarding `json:"forwarding"`
}

type DoctorKernelForwarding struct {
	// IPForward は net.ipv4.ip_forward の値である。読めなければ空で、IPForwardError が理由である
	IPForward      string `json:"ip_forward,omitempty"`
	IPForwardError string `json:"ip_forward_error,omitempty"`
	// RPFilterStrict は、rp_filter が 1 の設定の名前(all、default)である
	RPFilterStrict []string `json:"rp_filter_strict,omitempty"`
	// PolicyDrops は、既定でパケットを落とす他のテーブルの forward のチェーンの場所である
	PolicyDrops []string `json:"policy_drops,omitempty"`
	// PolicyError は他のテーブルを読めなかった理由、PolicyNeedsNetAdmin はそれが CAP_NET_ADMIN の
	// 不足によることである
	PolicyError         string `json:"policy_error,omitempty"`
	PolicyNeedsNetAdmin bool   `json:"policy_needs_net_admin,omitempty"`
}

type DoctorKernelInterface struct {
	// Name はインタフェースの名前である
	Name string `json:"name"`
	// ReadError は、リンクそのものを読めなかった理由である。値があるとき、残りの項目は意味を持たない
	ReadError string `json:"read_error,omitempty"`
	// Exists、Kind、Up は権限なしで読める(リンクの属性)。
	Exists bool   `json:"exists"`
	Kind   string `json:"kind,omitempty"`
	Up     bool   `json:"up"`
	// NeedsNetAdmin は、鍵とピアを CAP_NET_ADMIN なしには読めなかったことである。このとき Ownership
	// から下の項目は無い
	NeedsNetAdmin bool `json:"needs_net_admin,omitempty"`
	// DeviceError は、鍵とピアを権限以外の理由で読めなかった理由である
	DeviceError string `json:"device_error,omitempty"`
	// Ownership は KernelOwnership* のどれかである。鍵を読めなかった場合は空になる
	Ownership string             `json:"ownership,omitempty"`
	MTU       int                `json:"mtu,omitempty"`
	Addresses []string           `json:"addresses,omitempty"`
	Peers     []DoctorKernelPeer `json:"peers,omitempty"`

	// Declared は、比べる宣言(全体状態の wg 設定)があったかどうかである。無ければ PeerOK と
	// Differs は意味を持たない
	Declared bool `json:"declared"`
	// ServerAddress は vpsd のトンネルアドレスである。宣言から決まる
	ServerAddress string `json:"server_address,omitempty"`
	// PeerOK は、server の公開鍵を持ち、server のトンネルアドレスを AllowedIPs に含むピアがあることである
	PeerOK bool `json:"peer_ok"`
	// Differs は、宣言と違う点である。30 秒ごとの見直しが食い違いと見るのと同じ関数から来る
	Differs []string `json:"differs,omitempty"`

	// RouteInterface は、server のトンネルアドレスへの経路が向かうインタフェースの名前である。
	// RouteError は経路を読めなかった理由である。どちらも宣言が無ければ無い
	RouteInterface string `json:"route_interface,omitempty"`
	RouteError     string `json:"route_error,omitempty"`
}

type DoctorKernelPeer struct {
	PublicKey  string        `json:"public_key"`
	AllowedIPs []string      `json:"allowed_ips,omitempty"`
	Endpoint   string        `json:"endpoint,omitempty"`
	Keepalive  time.Duration `json:"keepalive,omitempty"`
	// LastHandshake は最終ハンドシェイクである。成立していなければゼロ値の時刻になる
	LastHandshake time.Time `json:"last_handshake"`
	RxBytes       int64     `json:"rx_bytes"`
	TxBytes       int64     `json:"tx_bytes"`
}

type DoctorKernelTable struct {
	// ReadError はテーブルを読めなかった理由である。NeedsNetAdmin は、それが CAP_NET_ADMIN の
	// 不足によることである
	ReadError     string `json:"read_error,omitempty"`
	NeedsNetAdmin bool   `json:"needs_net_admin,omitempty"`
	Present       bool   `json:"present"`
	// Source は比べた材料で、KernelTableFrom* のどれかである。比べる材料が無ければ空になる
	Source string `json:"source,omitempty"`
	// Generation は記録の元にした全体状態の世代である
	Generation uint64 `json:"generation,omitempty"`
	// Missing は、記録から組む表にあって実際の表に無い行、チェーン、DNAT のうち、欠けると転送が止まる
	// ものである。長くなりすぎない
	// ように先頭のいくつかだけを持ち、MissingCount が全体の数である
	Missing      []string `json:"missing,omitempty"`
	MissingCount int      `json:"missing_count,omitempty"`
	// GuardMissing は、記録から組む表にあって実際の表に無いもののうち、欠けても転送が止まらない行と
	// チェーン(守りの行)である。Missing には入らない。GuardMissingCount が全体の数である
	GuardMissing      []string `json:"guard_missing,omitempty"`
	GuardMissingCount int      `json:"guard_missing_count,omitempty"`
	// GuardEffects は、欠けた守りの行の組み合わせによって開きうる面である。値は KernelEffect* である。
	// GuardClosed は、欠けた drop の行の面を残っている行がまだ閉じていることである。値は KernelClosed* である
	GuardEffects []string `json:"guard_effects,omitempty"`
	GuardClosed  []string `json:"guard_closed,omitempty"`
	// Moved は、記録から組む表の行のうち、同じチェーンの別の位置にあるものである。欠けた行には数えない
	// (設計文書 10.2c 節)。MovedCount が全体の数である
	Moved      []string `json:"moved,omitempty"`
	MovedCount int      `json:"moved_count,omitempty"`
	// Unexpected は、記録に無いのに実際の表にある行、チェーン、DNAT である
	Unexpected      []string `json:"unexpected,omitempty"`
	UnexpectedCount int      `json:"unexpected_count,omitempty"`
	// Rules は記録か宣言から読んだルールごとの状態である。稼働中の応答では、ハートビートの状態は
	// DoctorRuntimeState.Rules にあり、こちらは記録が持つ理由である
	Rules []DoctorRule `json:"rules,omitempty"`
}

type DoctorProcess struct {
	// UID は実 uid である。Windows では -1 になる
	UID int `json:"uid"`
	// User は UID の利用者名である。引けなければ空になる。systemd の DynamicUser の利用者は
	// /etc/passwd に無いので、静的なビルドでは引けないことがある
	User string `json:"user,omitempty"`
	// NetAdmin は、プロセスが実効として CAP_NET_ADMIN を持つかどうかである。Linux の外と、読めな
	// かった場合は nil になる
	NetAdmin *bool `json:"cap_net_admin,omitempty"`
}

type DoctorRefusal struct {
	RuleID string `json:"rule_id"`
	// Reason は budget、rule_cap、reserve のいずれか(設計文書 7a.10 節)
	Reason resource.Reason `json:"reason"`
	Count  uint64          `json:"count"`
}

type DoctorResponse struct {
	// Error は応答を組む処理が失敗したことと、その理由である。運用者に何が起きたかを伝えるために
	// 載せる。値があるとき、残りの項目は無い
	Error string `json:"error,omitempty"`

	// AllowTargets は宛先の許可一覧である。起動時に決まって以後変わらず、実行時の排他も要らないので、
	// 排他を取れなかった応答にも載る
	AllowTargets *DoctorAllowTargets `json:"allow_targets,omitempty"`

	// Stream は制御ストリームの観測である。streamMu だけで読めるので、実行時の排他を取れなかった
	// 応答にも載る
	Stream *DoctorStream `json:"stream,omitempty"`

	// Process は稼働中のエージェントのプロセスの実行主体である。実行時の排他を要らないので、排他を
	// 取れなかった応答にも載る(設計文書 10.2c 節の「カーネルモードの制御ソケットの応答」)
	Process *DoctorProcess `json:"process,omitempty"`

	// RuntimeState は実行時の排他の下でしか読めない状態である。排他を期限内に取れなければ無い
	RuntimeState *DoctorRuntimeState `json:"runtime_state,omitempty"`
	// RuntimeStateTimeout は、実行時の排他を取れなかったときに待った期限である。単位はナノ秒。
	// 取れた場合は 0 になる
	RuntimeStateTimeout time.Duration `json:"runtime_state_timeout,omitempty"`
}

type DoctorRule struct {
	ID string `json:"id"`
	// State と Reason はハートビートが組み立てる proto.RuleStatus の値そのものである
	State  string `json:"state"`
	Reason string `json:"reason,omitempty"`
	// Proto は tcp か udp
	Proto proto.Proto `json:"proto,omitempty"`
	// Listeners はこのルールに属するリスナーの数、Listening はそのうち待ち受けを開けている数である
	Listeners int `json:"listeners"`
	Listening int `json:"listening"`
	// BindErrors は待ち受けを開けなかったリスナーの数、BindError はその 1 つの理由である。
	// 開けない原因はポートの衝突を指す
	BindErrors int    `json:"bind_errors"`
	BindError  string `json:"bind_error,omitempty"`
	// TargetErrors は待ち受けは開いていて宛先に届かないリスナーの数、TargetError はその 1 つの
	// 理由である。届かない原因は宛先の機器を指すので、運用者の次の行動が bind の失敗とは違う
	TargetErrors int    `json:"target_errors"`
	TargetError  string `json:"target_error,omitempty"`
	// Sessions は中継が持っている接続の数である。TCP は公開側と宛先側の両方を数えるので、
	// フロー予算の上限の対象とは一致しない。上限の対象の数は Flows である
	Sessions int `json:"sessions"`
	Flows    int `json:"flows"`
	// Ports はルールの宣言のポートの数、DNATPorts はそのうちカーネルモードで DNAT を置いたポートの
	// 数である。カーネルモードのルールだけが持つ。DNAT を置いたまま error を報告するルールと、DNAT を
	// 持たないルールを見分けるためである(設計文書 10.2c 節)
	Ports     int `json:"ports,omitempty"`
	DNATPorts int `json:"dnat_ports,omitempty"`
}

type DoctorRuntimeState struct {
	// Mode は稼働中のエージェントの転送の方式である(kernel か userspace。仕様 11a 節)。旧い版の
	// エージェントは送らないので、空ならユーザー空間モードである
	Mode string `json:"mode,omitempty"`
	// Generation は最後に受け取って処理した全体状態の世代
	Generation uint64       `json:"generation"`
	Tunnel     DoctorTunnel `json:"tunnel"`
	// Rules はルールごとの状態である。リスナー 1 つずつは並べない。ルールを受け付ける資源が無ければ
	// 項目ごと出ない。カーネルモードでは、リスナーの数と中継の数はどれも 0 で、状態と理由だけが意味を持つ
	Rules []DoctorRule `json:"rules,omitempty"`
	// Budgets はプロトコルごとのフロー予算である。中継が無ければ項目ごと出ない
	Budgets []DoctorBudget `json:"budgets,omitempty"`
	// RefusalsSince は Budgets の拒否の累計の起点、つまり今のトンネルを立てた時刻である。
	// フロー予算はトンネルを立て直すたびに中継ごと作り直され、累計はそのたびに 0 に戻る
	// (設計文書 10.2c 節)。中継が無ければゼロ値の時刻になる。項目そのものは必ず出るので、
	// 読み手は IsZero で判定する
	RefusalsSince time.Time `json:"refusals_since"`
	// AgentDisabled は、最後に適用した全体状態の proto.State.AgentDisabled をそのまま写した
	// ものである(仕様 5.1 節)。server がこのエージェントを無効にしていることをエージェント
	// 自身の診断のために示すだけで、守りには使わない。relay.listeners はこの値から SKIPPED を
	// 判定する(設計文書 10.2c 節)
	AgentDisabled bool `json:"agent_disabled"`

	// Kernel はカーネルモードの dataplane を読んだ結果である(設計文書 10.2c 節)。カーネルモードの
	// エージェントだけが持つ。停止中の agent doctor も ReadKernel で同じ形を読む
	Kernel *DoctorKernel `json:"kernel,omitempty"`
	// PublishError は、公開できずに試し直している全体状態の誤りである(7b.3 節の 3 つ目の種類)。
	// 旧いテーブルが残って転送を続けている
	PublishError string `json:"publish_error,omitempty"`
	// CheckError は、カーネルモードの直前の見直しの誤りである。30 秒ごとの見直しと変更の通知の後の
	// 見直しの両方を指す(7b.4 節)
	CheckError string `json:"check_error,omitempty"`
}

type DoctorStream struct {
	Connected bool `json:"connected"`
	// DisconnectedAt と RetryAt、LastPingAt、LastPongAt は、値が無ければゼロ値の時刻になる。
	// encoding/json の omitempty は struct に効かないので、項目そのものは必ず出る。読み手は
	// IsZero で判定する
	DisconnectedAt   time.Time `json:"disconnected_at"`
	DisconnectReason string    `json:"disconnect_reason,omitempty"`
	// PinMismatch は、直近の切断か試みの失敗が、server の証明書と登録のときに固定したハッシュとの
	// 不一致だったことである。旧い版のエージェントは送らない
	PinMismatch bool `json:"pin_mismatch,omitempty"`
	// Backoff は直近に待った再接続の間隔。単位はナノ秒
	Backoff      time.Duration `json:"backoff,omitempty"`
	RetryAt      time.Time     `json:"retry_at"`
	LastPingAt   time.Time     `json:"last_ping_at"`
	LastPongAt   time.Time     `json:"last_pong_at"`
	AwaitingPong bool          `json:"awaiting_pong"`
}

type DoctorTunnel struct {
	// Present はトンネルがあるかどうか。偽なら Reason がその理由を言う
	Present bool `json:"present"`
	// State は ok か error
	State  string `json:"state"`
	Reason string `json:"reason,omitempty"`
	// Endpoint は解決済みのエンドポイント。初回の名前解決に失敗したトンネルは持たない
	Endpoint string `json:"endpoint,omitempty"`
	// LastHandshake は今の device から読んだ最終ハンドシェイクである。watchdog が別に持つ値は
	// トンネルを閉じても消えず、立て直した直後は前のトンネルの値が残るので、そちらは載せない。
	// 成立していなければゼロ値の時刻になる。項目そのものは必ず出るので、読み手は IsZero で判定する
	LastHandshake time.Time `json:"last_handshake"`
	RxBytes       int64     `json:"rx_bytes"`
	TxBytes       int64     `json:"tx_bytes"`
	// StartedAt は今のトンネルを立てた時刻。トンネルが無ければゼロ値の時刻になる
	StartedAt time.Time      `json:"started_at"`
	Watchdog  DoctorWatchdog `json:"watchdog"`
}

type DoctorWatchdog struct {
	// RebuildInterval は判定に使う作り直しの間隔の実効値である。単位はナノ秒
	RebuildInterval time.Duration `json:"rebuild_interval"`
	// RetryAt は、作成に失敗して試し直しを待っている場合の予定の時刻。待っていなければゼロ値の
	// 時刻になる。項目そのものは必ず出るので、読み手は IsZero で判定する
	RetryAt time.Time `json:"retry_at"`
}

type Join struct {
	Endpoint string // host:port(エージェント用 API)
	Token    string // 1 回限りの登録トークン
	Pin      [32]byte
	// contains filtered or unexported fields
}

type Options struct {
	// AllowTargets は接続してよい宛先の許可一覧(仕様 7 節、WGFT_AGENT_ALLOW_TARGETS)。
	// nil なら制限せず、vpsd が配るどの宛先へも接続する
	AllowTargets    *allowtargets.List
	CredentialsPath string          // 認証情報ファイル
	Join            string          // 接続文字列(WGFT_JOIN か --join)。初回登録に使う
	Limits          resource.Limits // 同時フロー数のプロセス全体の予算(仕様 7 節)。ゼロ値は既定値
	Name            string          // エージェント名(WGFT_NAME か --name)。任意。接続文字列の発行時の名前に紐付いているので、与えなければトークンに紐付いた名前で登録される
	Version         string          // 起動ログに出す wgft の版(cmd 側の effectiveVersion())。空なら "dev" として出す

	// Mode は設定の WGFT_MODE の値である(仕様 11a 節)。kernel か userspace で、空なら省略されており
	// userspace を指す。起動時に認証情報ファイルの記録と照合する(mode.go)
	Mode string
	// WGInterface はカーネルモードの WireGuard インタフェースの名前である(WGFT_WG_INTERFACE、既定 wgft0。
	// 仕様 7b.1・11a 節)。ユーザー空間モードでは使わない
	WGInterface string
}

type TeardownOptions struct {
	// CredentialsPath は agent.json のパスである。
	CredentialsPath string
	// Interface は WGFT_WG_INTERFACE の値である。鍵の一致しないリンクをこの名前と作業用の名前で
	// 探して示すために使う。鍵の一致するインタフェースは名前によらず消す。
	Interface string
	// DryRun なら、消すものと手で戻す一覧を示すだけで何も変えない。
	DryRun bool
}