servicecatalog

package module
v0.0.0-...-2d4ef54 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 16 Imported by: 2

README

组件目录与权限

catalog.yaml 内嵌定义组件、公开 tRPC 服务、逐方法 ACL、外部调用方白名单和 Doctor 元数据。当前有 21 个组件、5 个外部调用方;组件数不等于主机数或进程副本数。目录不包含部署地址、签名密钥或其他凭据。

LoadEmbedded / Decode 严格加载并校验目录。ValidateTopology 整体校验主机与部署的端口、范围、副本数、受保护组件和自动维护的主机组件,不修改输入。Compile 生成指定主机的 loopback 路由、全局服务目录和校验密钥的调用方范围,输出与输入顺序无关。

  • 控制台使用 ConsoleService(name, method),再以 console 身份校验。Storage 的三个服务共用 storage 名称,通过方法区分;同名同方法的歧义被拒绝。
  • Allowed 供控制台与主机网关共用;外部接入使用 PrincipalAllowed。外部调用方身份不能直接进入主机网关,白名单涉及的方法会自动授予 access。
  • ReadOnly 识别只读方法;Retryable 还包含 idempotent_methods 中的幂等写方法,当前是 PrimaryStore.CommitTimeSeriesBatch。是否实际重试还受客户端错误分类与剩余预算约束。
  • 路由按单个 service path / method 编译,保留原 ACL 方法与调用方的对应关系。
  • host-gateway@* 只允许用于 GatewayControl,编译时展开为已登记主机;控制服务仍须校验调用方主机与请求中的主机一致。
  • CompiledHost.Hash 是路由定义哈希。GatewayControl 应把实际下发的校验密钥及 KeyID 加入最终快照哈希,保证密钥轮换能触发更新。

SysDeploy v2、GatewayControl、调用方密钥管理、原生初始化、Doctor、主机网关、Access 与业务调用方均已使用此目录;出口代理已有运行入口和服务实现。目录是源码契约,不能单独证明某个部署环境已运行或通过验收。

hostgatewayconfig 子包定义原生部署与主机网关运行端共用的配置格式。Default 生成发布目录中的相对路径和 control 的直连配置;Decode 严格校验有界单份 YAML,Load 另将路径解析为相对于配置文件的绝对路径。该层只校验结构,实际 TLS 证书、私有 CA 与签名文件由运行端检查。安装器、网关运行端与内部调用方均已接入。

Documentation

Overview

Package servicecatalog owns the shared component, method and permission definitions. It has no database, network or deployment side effects.

Index

Constants

View Source
const (
	ScopeHost                 = "host"
	ScopeControl              = "control"
	ScopeAny                  = "any"
	Single                    = "single"
	Multi                     = "multi"
	Enabled                   = "enabled"
	Disabled                  = "disabled"
	GatewayControlPath        = "trpc.moox.admin.GatewayControl"
	DefaultTimeoutMS    int64 = 5000
	DefaultMaxBodyBytes int64 = 4 << 20
)
View Source
const (
	SupervisorMooxRuntime = "moox_runtime"
	SupervisorSystemdUser = "systemd_user"
)
View Source
const HostGatewayRemotePort = 11003

HostGatewayRemotePort 是主机网关的跨主机 TLS 端口。

View Source
const ReachabilityDirect = "direct"

ReachabilityDirect 是配置与 Admin 登记里“可直达”的写法,拓扑里对应空值。

View Source
const ReachabilityOutbound = "outbound"

ReachabilityOutbound 标记只能出站的主机:它的网关主动与 control 网关保持反向连接。

Variables

This section is empty.

Functions

func EmbeddedYAML

func EmbeddedYAML() []byte

EmbeddedYAML returns an owned copy for release identity checks. Mutating it does not change the catalog loaded by this package.

func ParseReachability

func ParseReachability(value string) (string, bool)

ParseReachability 把配置或登记里的可达性(空、direct、outbound)转换成拓扑取值(空或 outbound)。

func ReachabilityName

func ReachabilityName(value string) string

ReachabilityName 返回拓扑取值在配置与登记里的写法。

func ValidHostAddress

func ValidHostAddress(address string) bool

ValidHostAddress accepts a bare IP or DNS host, without a scheme or port.

func ValidHostID

func ValidHostID(id string) bool

ValidHostID checks the canonical host identity shared by topology and callers.

func ValidateSupervisor

func ValidateSupervisor(supervisor, unit string) error

ValidateSupervisor 校验进程托管方式与单元名的组合:systemd_user 必须带合法的单元名,其余托管方式不能带单元名。

Types

type Catalog

type Catalog struct {
	Version    int         `yaml:"version" json:"version"`
	Components []Component `yaml:"components" json:"components"`
	Principals []Principal `yaml:"principals" json:"principals"`
}

func Decode

func Decode(r io.Reader) (Catalog, error)

func LoadEmbedded

func LoadEmbedded() (Catalog, error)

func (Catalog) Allowed

func (c Catalog) Allowed(caller, servicePath, method string) bool

Allowed is shared by the console and host gateways. External principal IDs never authenticate to a host gateway: only access may forward their requests.

func (Catalog) Compile

func (c Catalog) Compile(t Topology, hostID string) (CompiledHost, error)

func (Catalog) Component

func (c Catalog) Component(id string) (Component, bool)

func (Catalog) ConsoleService

func (c Catalog) ConsoleService(name, method string) (Service, bool)

Storage exposes Metadata, PrimaryStore and DataView under one browser name. Resolve the pair, checking console permission before choosing the service.

func (Catalog) HealthPort

func (c Catalog) HealthPort(port int) bool

HealthPort 报告端口是否是服务目录里某个组件的健康端口。

func (Catalog) LocalRelayPort

func (c Catalog) LocalRelayPort(port int) bool

LocalRelayPort 报告出站主机的网关能否把中转流接到本机这个端口:组件健康端口或外部程序的 relay_http 端口。

func (Catalog) MissingGrants

func (c Catalog) MissingGrants(deployed []string) []MissingGrant

MissingGrants 列出授权服务里没有部署的项。Access 要等全部授权服务都进入服务目录才就绪, 所以这里缺一项,部署时就会卡在 Access 未就绪。

func (Catalog) PrincipalAllowed

func (c Catalog) PrincipalAllowed(principal, servicePath, method string) bool

func (Catalog) ReadOnly

func (c Catalog) ReadOnly(servicePath, method string) bool

func (Catalog) RelayHTTPCallers

func (c Catalog) RelayHTTPCallers(port int) (callers []string, ok bool)

RelayHTTPCallers 返回端口作为某个外部程序 relay_http 端口时的中转调用方(排序后);不是时 ok 为假。

func (Catalog) Retryable

func (c Catalog) Retryable(servicePath, method string) bool

Retryable 判断方法在请求可能已发出的网络失败后能否安全重发:只读方法,或声明为幂等的写方法。

func (Catalog) Service

func (c Catalog) Service(path string) (Service, bool)

func (Catalog) ValidRelay

func (c Catalog) ValidRelay(r RelayTarget) bool

ValidRelay 校验一条中转许可:端口不重复,跨主机端口的调用方是合法 ID 且不重复; 其余端口要么是服务目录里某个组件的健康端口并且只对 Monitor 与 moox-cli 开放, 要么是某个外部程序的 relay_http 端口并且只对它声明的调用方开放。没有 relay_http 端口的许可(旧版 Admin 编译的)照样接受。

func (Catalog) Validate

func (c Catalog) Validate() error

func (Catalog) ValidateTopology

func (c Catalog) ValidateTopology(t Topology) error

type CompiledHost

type CompiledHost struct {
	HostID              string    `json:"host_id"`
	Disabled            bool      `json:"disabled"`
	Routes              []Route   `json:"routes"`
	Directory           Directory `json:"directory"`
	VerificationCallers []string  `json:"verification_callers"`
	// Relays 只出现在 control 的快照里:每台已启用的出站主机允许打开中转流的端口与调用方。没有出站主机时为空、不参与序列化。
	Relays []RelayTarget `json:"relays,omitempty"`
	Hash   string        `json:"hash"`
}

CompiledHost is a definition, not the final signed-key snapshot. The control plane must hash the actual verification key IDs/material along with this definition so a key rotation changes the snapshot even without route changes.

type Component

type Component struct {
	ID        string `yaml:"id" json:"id"`
	Name      string `yaml:"name" json:"name"`
	Binary    string `yaml:"binary" json:"binary"`
	Scope     string `yaml:"scope" json:"scope"`
	Replicas  string `yaml:"replicas" json:"replicas"`
	Protected bool   `yaml:"protected" json:"protected"`
	// Ports reserves listeners which are not forwarded RPC services, such as
	// the browser entrypoint, NATS and Storage's private runtime endpoints.
	Ports    []int     `yaml:"ports,omitempty" json:"ports,omitempty"`
	Health   Health    `yaml:"health" json:"health"`
	Services []Service `yaml:"services,omitempty" json:"services,omitempty"`
	Doctor   Doctor    `yaml:"doctor" json:"doctor"`
	// ExternalProgram 标记运行在登记主机上、但不经主机网关路由的外部程序(因子引擎、归档 worker):
	// 它以同名外部身份(Principal)经 Access 访问系统,没有自己的服务,只有一个健康端口与可选的 RelayHTTP 端口。
	ExternalProgram bool `yaml:"external_program,omitempty" json:"external_program,omitempty"`
	// RelayHTTP 是外部程序只听回环地址的 HTTP 端口:装在只出站主机上时,声明的调用方可经 control 中转连接它
	// (归档 worker 的下载与预览)。端口本身不验签,由 control 的中转按调用方白名单放行。
	RelayHTTP *RelayHTTP `yaml:"relay_http,omitempty" json:"relay_http,omitempty"`
}

func (Component) AllPorts

func (c Component) AllPorts() []int

AllPorts 返回组件占用的全部监听端口。

type Deployment

type Deployment struct {
	HostID      string `json:"host_id"`
	ComponentID string `json:"component_id"`
	Status      string `json:"status"`
}

type Directory

type Directory struct {
	Version  string                   `json:"version"`
	Services map[string][]string      `json:"services"`
	Hosts    map[string]DirectoryHost `json:"hosts"`
}

func (Directory) Clone

func (d Directory) Clone() Directory

func (Directory) Validate

func (d Directory) Validate() error

func (Directory) VersionHash

func (d Directory) VersionHash() (string, error)

VersionHash hashes the directory contents without its version field, matching the compiler. It does not mutate the supplied directory.

type DirectoryHost

type DirectoryHost struct {
	Address        string `json:"address"`
	PrivateAddress string `json:"private_address,omitempty"`
	Region         string `json:"region,omitempty"`
	// Relay 非空时该主机只能出站,调用方要经这台主机(control)的网关打开中转流再连接它。
	Relay string `json:"relay,omitempty"`
}

type Doctor

type Doctor struct {
	Role                     string   `yaml:"role" json:"role"`
	Description              string   `yaml:"description" json:"description"`
	Duties                   []string `yaml:"duties" json:"duties"`
	Inputs                   []string `yaml:"inputs" json:"inputs"`
	Outputs                  []string `yaml:"outputs" json:"outputs"`
	Dependencies             []string `yaml:"dependencies" json:"dependencies"`
	Transport                string   `yaml:"transport" json:"transport"`
	FunctionalObservability  string   `yaml:"functional_observability" json:"functional_observability"`
	ConfigPaths              []string `yaml:"config_paths" json:"config_paths"`
	WritablePaths            []string `yaml:"writable_paths" json:"writable_paths"`
	RecoveryActionIDs        []string `yaml:"recovery_action_ids" json:"recovery_action_ids"`
	RequiredInDefaultProfile bool     `yaml:"required_in_default_profile" json:"required_in_default_profile"`
	// Supervisor 是进程的托管方式:moox_runtime(默认,由 moox-runtime 看护)或 systemd_user(systemd 用户服务)。
	Supervisor string `yaml:"supervisor,omitempty" json:"supervisor,omitempty"`
	// Unit 是 systemd 用户服务的单元名,只有 systemd_user 托管的组件才有。
	Unit string `yaml:"unit,omitempty" json:"unit,omitempty"`
}

Doctor keeps the diagnostics metadata in the same source of truth without making this package depend on Doctor or a service implementation.

type Grant

type Grant struct {
	Methods []string `yaml:"methods" json:"methods"`
	Callers []string `yaml:"callers" json:"callers"`
}

type Health

type Health struct {
	Kind      string `yaml:"kind" json:"kind"`
	Port      int    `yaml:"port,omitempty" json:"port,omitempty"`
	Loopback  bool   `yaml:"loopback,omitempty" json:"loopback,omitempty"`
	ReadyBody string `yaml:"ready_body,omitempty" json:"ready_body,omitempty"`
}

type Host

type Host struct {
	ID             string `json:"id"`
	Address        string `json:"address"`
	PrivateAddress string `json:"private_address,omitempty"`
	Region         string `json:"region,omitempty"`
	Status         string `json:"status"`
	// Reachability 为空表示可直达;ReachabilityOutbound 表示只能出站(家庭网络等),进入它的连接经 control 网关中转。
	Reachability string `json:"reachability,omitempty"`
}

type MissingGrant

type MissingGrant struct {
	Principal string `json:"principal"`
	Service   string `json:"service"`
	Component string `json:"component"`
}

MissingGrant 是一项授权服务没有部署:调用方的授权指向了它,但提供它的组件不在部署里。

type Permission

type Permission struct {
	Service string   `yaml:"service" json:"service"`
	Methods []string `yaml:"methods" json:"methods"`
}

type Principal

type Principal struct {
	ID    string       `yaml:"id" json:"id"`
	Allow []Permission `yaml:"allow" json:"allow"`
}

type RelayHTTP

type RelayHTTP struct {
	Port    int      `yaml:"port" json:"port"`
	Callers []string `yaml:"callers" json:"callers"`
}

RelayHTTP 是可经中转连接的本机 HTTP 端口与允许打开它的内置调用方。

type RelayPort

type RelayPort struct {
	Port    int      `json:"port"`
	Callers []string `json:"callers"`
}

RelayPort 是允许经中转连接的一个端口与可打开它的调用方:主机网关跨主机端口对能调用该主机任一服务的调用方开放, 组件健康端口只对 Monitor 与 moox-cli 开放,外部程序的 relay_http 端口只对它声明的调用方开放。

type RelayTarget

type RelayTarget struct {
	HostID string      `json:"host_id"`
	Ports  []RelayPort `json:"ports"`
}

RelayTarget 是一台出站主机的中转许可。

func (RelayTarget) Allowed

func (r RelayTarget) Allowed(caller string, port int) bool

Allowed 报告调用方能否经中转连接出站主机的指定端口。

type Route

type Route struct {
	ComponentID  string   `json:"component_id"`
	ServicePath  string   `json:"service_path"`
	Method       string   `json:"method"`
	Address      string   `json:"address"`
	TimeoutMS    int64    `json:"timeout_ms"`
	MaxBodyBytes int64    `json:"max_body_bytes"`
	ReadOnly     bool     `json:"read_only"`
	Callers      []string `json:"callers"`
}

Route grants callers to exactly one service and method. Merging ACL groups into separate method/caller sets would accidentally widen permissions.

type Service

type Service struct {
	Path        string `yaml:"path" json:"path"`
	Port        int    `yaml:"port" json:"port"`
	ConsoleName string `yaml:"console_name,omitempty" json:"console_name,omitempty"`
	TimeoutMS   int64  `yaml:"timeout_ms,omitempty" json:"timeout_ms,omitempty"`
	// MethodTimeoutsMS 覆盖个别长等待方法的超时,未列出的方法使用 TimeoutMS。
	MethodTimeoutsMS map[string]int64 `yaml:"method_timeouts_ms,omitempty" json:"method_timeouts_ms,omitempty"`
	MaxBodyBytes     int64            `yaml:"max_body_bytes,omitempty" json:"max_body_bytes,omitempty"`
	Methods          []string         `yaml:"methods" json:"methods"`
	ReadOnlyMethods  []string         `yaml:"read_only_methods,omitempty" json:"read_only_methods,omitempty"`
	// IdempotentMethods 是写方法中重复提交同一请求不会产生额外副作用的方法:请求可能已发出的网络失败后,
	// 网关客户端可以像只读方法一样换连接重试一次。必须由服务端语义保证幂等,不得与只读方法重复声明。
	IdempotentMethods []string `yaml:"idempotent_methods,omitempty" json:"idempotent_methods,omitempty"`
	ACL               []Grant  `yaml:"acl" json:"acl"`
}

func (Service) TimeoutFor

func (s Service) TimeoutFor(method string) int64

TimeoutFor 返回方法的路由超时(毫秒):方法级覆盖优先,其次服务级,最后默认值。

type Topology

type Topology struct {
	ControlHostID string       `json:"control_host_id"`
	Hosts         []Host       `json:"hosts"`
	Deployments   []Deployment `json:"deployments"`
}

Directories

Path Synopsis
Package hostbundle defines the public metadata of issued host identity material.
Package hostbundle defines the public metadata of issued host identity material.
Package hostgatewayconfig defines the deployment and runtime configuration contract for a host gateway.
Package hostgatewayconfig defines the deployment and runtime configuration contract for a host gateway.

Jump to

Keyboard shortcuts

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