Documentation
¶
Overview ¶
Package servicecatalog owns the shared component, method and permission definitions. It has no database, network or deployment side effects.
Index ¶
- Constants
- func EmbeddedYAML() []byte
- func ParseReachability(value string) (string, bool)
- func ReachabilityName(value string) string
- func ValidHostAddress(address string) bool
- func ValidHostID(id string) bool
- func ValidateSupervisor(supervisor, unit string) error
- type Catalog
- func (c Catalog) Allowed(caller, servicePath, method string) bool
- func (c Catalog) Compile(t Topology, hostID string) (CompiledHost, error)
- func (c Catalog) Component(id string) (Component, bool)
- func (c Catalog) ConsoleService(name, method string) (Service, bool)
- func (c Catalog) HealthPort(port int) bool
- func (c Catalog) LocalRelayPort(port int) bool
- func (c Catalog) MissingGrants(deployed []string) []MissingGrant
- func (c Catalog) PrincipalAllowed(principal, servicePath, method string) bool
- func (c Catalog) ReadOnly(servicePath, method string) bool
- func (c Catalog) RelayHTTPCallers(port int) (callers []string, ok bool)
- func (c Catalog) Retryable(servicePath, method string) bool
- func (c Catalog) Service(path string) (Service, bool)
- func (c Catalog) ValidRelay(r RelayTarget) bool
- func (c Catalog) Validate() error
- func (c Catalog) ValidateTopology(t Topology) error
- type CompiledHost
- type Component
- type Deployment
- type Directory
- type DirectoryHost
- type Doctor
- type Grant
- type Health
- type Host
- type MissingGrant
- type Permission
- type Principal
- type RelayHTTP
- type RelayPort
- type RelayTarget
- type Route
- type Service
- type Topology
Constants ¶
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 )
const ( SupervisorMooxRuntime = "moox_runtime" SupervisorSystemdUser = "systemd_user" )
const HostGatewayRemotePort = 11003
HostGatewayRemotePort 是主机网关的跨主机 TLS 端口。
const ReachabilityDirect = "direct"
ReachabilityDirect 是配置与 Admin 登记里“可直达”的写法,拓扑里对应空值。
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 ¶
ParseReachability 把配置或登记里的可达性(空、direct、outbound)转换成拓扑取值(空或 outbound)。
func ReachabilityName ¶
ReachabilityName 返回拓扑取值在配置与登记里的写法。
func ValidHostAddress ¶
ValidHostAddress accepts a bare IP or DNS host, without a scheme or port.
func ValidHostID ¶
ValidHostID checks the canonical host identity shared by topology and callers.
func ValidateSupervisor ¶
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 LoadEmbedded ¶
func (Catalog) Allowed ¶
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) ConsoleService ¶
Storage exposes Metadata, PrimaryStore and DataView under one browser name. Resolve the pair, checking console permission before choosing the service.
func (Catalog) HealthPort ¶
HealthPort 报告端口是否是服务目录里某个组件的健康端口。
func (Catalog) LocalRelayPort ¶
LocalRelayPort 报告出站主机的网关能否把中转流接到本机这个端口:组件健康端口或外部程序的 relay_http 端口。
func (Catalog) MissingGrants ¶
func (c Catalog) MissingGrants(deployed []string) []MissingGrant
MissingGrants 列出授权服务里没有部署的项。Access 要等全部授权服务都进入服务目录才就绪, 所以这里缺一项,部署时就会卡在 Access 未就绪。
func (Catalog) PrincipalAllowed ¶
func (Catalog) RelayHTTPCallers ¶
RelayHTTPCallers 返回端口作为某个外部程序 relay_http 端口时的中转调用方(排序后);不是时 ok 为假。
func (Catalog) ValidRelay ¶
func (c Catalog) ValidRelay(r RelayTarget) bool
ValidRelay 校验一条中转许可:端口不重复,跨主机端口的调用方是合法 ID 且不重复; 其余端口要么是服务目录里某个组件的健康端口并且只对 Monitor 与 moox-cli 开放, 要么是某个外部程序的 relay_http 端口并且只对它声明的调用方开放。没有 relay_http 端口的许可(旧版 Admin 编译的)照样接受。
func (Catalog) ValidateTopology ¶
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"`
}
type Deployment ¶
type Directory ¶
type Directory struct {
Version string `json:"version"`
Services map[string][]string `json:"services"`
Hosts map[string]DirectoryHost `json:"hosts"`
}
func (Directory) VersionHash ¶
VersionHash hashes the directory contents without its version field, matching the compiler. It does not mutate the supplied directory.
type DirectoryHost ¶
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 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 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 ¶
RelayPort 是允许经中转连接的一个端口与可打开它的调用方:主机网关跨主机端口对能调用该主机任一服务的调用方开放, 组件健康端口只对 Monitor 与 moox-cli 开放,外部程序的 relay_http 端口只对它声明的调用方开放。
type RelayTarget ¶
RelayTarget 是一台出站主机的中转许可。
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 ¶
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. |