Help us shape the future of Go! Take the 2026 Go Developer Survey

serverapi

package
v1.21.2 Latest Latest
Warning

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

Go to latest
Published: Oct 27, 2026 License: GPL-3.0 Imports: 24 Imported by: 0

Documentation

Overview

Package serverapi is the network module's node-facing server API: the configuration and user lists the nodes pull, cached per server and negotiated with ETags, and the status, online-user and traffic reports they push. Only the module facade may reach it.

Index

Constants

View Source
const (
	ShadowSocks = "shadowsocks"
	Vmess       = "vmess"
	Vless       = "vless"
	Trojan      = "trojan"
	AnyTLS      = "anytls"
	Tuic        = "tuic"
	Hysteria    = "hysteria"
	Nowhere     = "nowhere"
	// Hysteria2 is the former name of Hysteria, which older nodes still ask
	// for.
	Hysteria2 = "hysteria2"
)

Protocol type names the legacy server-config shapes are built for.

Variables

This section is empty.

Functions

This section is empty.

Types

type AccountReader added in v1.21.0

type AccountReader interface {
	FindEnabledUserIDs(ctx context.Context, ids []int64) ([]int64, error)
}

AccountReader reports which of the accounts are enabled.

type AnyTLSNode

type AnyTLSNode struct {
	Port           uint16          `json:"port"`
	SecurityConfig *SecurityConfig `json:"security_config"`
}

type Deps

type Deps struct {
	TrafficUsage subscription.TrafficUsage
	Redis        *redis.Client
	// Config snapshots the runtime-mutable settings per request.
	Config func() Snapshot
	// Multiplier returns the node traffic multiplier in effect at the given
	// time; nil means no multiplier is configured.
	Multiplier func(at time.Time) float32

	// The ports list only what the node API uses of each dependency, so a
	// fake implements exactly that. Servers reads the server rows,
	// Overrides their configuration overrides and Nodes a server's nodes.
	Servers   ServerReader
	Overrides OverrideReader
	Nodes     NodeLister
	// Caches keeps a server's node-facing responses under its cache
	// generation.
	Caches ServerCache
	// Status records the status reports, Online the online users.
	Status StatusRecorder
	Online OnlineRecorder
	// Subscriptions is the subscription read port (the subscription
	// facade): the subscriptions a server's nodes serve.
	Subscriptions SubscriptionReader
	// Accounts is the identity read port: which subscription owners have
	// an enabled account.
	Accounts AccountReader
}

Deps declares the subdomain's dependencies; the module facade forwards them from the composition root.

type Hysteria2Node

type Hysteria2Node struct {
	Port           uint16          `json:"port"`
	HopPorts       string          `json:"hop_ports"`
	HopInterval    int             `json:"hop_interval"`
	ObfsPassword   string          `json:"obfs_password"`
	SecurityConfig *SecurityConfig `json:"security_config"`
}

type NodeLister added in v1.21.0

type NodeLister interface {
	ListNodes(ctx context.Context, params *node.FilterNodeParams) ([]*node.Node, error)
}

NodeLister lists the nodes a filter selects.

type OnlineRecorder added in v1.21.0

type OnlineRecorder interface {
	UpdateOnlineUserSubscribe(ctx context.Context, serverId int64, protocol string, subscribe node.OnlineUserSubscribe) error
	UpdateOnlineUserSubscribeGlobal(ctx context.Context, subscribe node.OnlineUserSubscribe) error
}

OnlineRecorder records the users a server reports online.

type OverrideReader added in v1.21.0

type OverrideReader interface {
	FindServerConfigOverride(ctx context.Context, serverId int64) (*node.ServerConfigOverride, error)
}

OverrideReader reads a server's configuration override; nil means none.

type RequestMeta

type RequestMeta struct {
	// IfNoneMatch is the ETag of the node's cached copy, if any.
	IfNoneMatch string
}

RequestMeta is the conditional-request state a node sends with a pull.

type ResponseMeta

type ResponseMeta struct {
	Headers map[string]string
}

ResponseMeta is the response headers a pull sets, such as the ETag.

func NewResponseMeta

func NewResponseMeta() ResponseMeta

NewResponseMeta returns a ResponseMeta without headers.

func (*ResponseMeta) SetHeader

func (m *ResponseMeta) SetHeader(key, value string)

SetHeader sets the response header key to value.

type SecurityConfig

type SecurityConfig struct {
	SNI                  string `json:"sni"`
	AllowInsecure        *bool  `json:"allow_insecure"`
	Fingerprint          string `json:"fingerprint"`
	RealityServerAddress string `json:"reality_server_addr"`
	RealityServerPort    int    `json:"reality_server_port"`
	RealityPrivateKey    string `json:"reality_private_key"`
	RealityPublicKey     string `json:"reality_public_key"`
	RealityShortId       string `json:"reality_short_id"`
	RealityMldsa65seed   string `json:"reality_mldsa65seed"`
	PaddingScheme        string `json:"padding_scheme"`
}

SecurityConfig is the TLS/REALITY block of the legacy server-config shapes.

type ServerCache added in v1.21.0

type ServerCache interface {
	ServerCacheGeneration(ctx context.Context, serverId int64) (int64, error)
	SetServerCache(ctx context.Context, serverId int64, key string, value any, generation int64) error
}

ServerCache stores a server's node-facing responses only while the cache generation read before building them is still current.

type ServerReader added in v1.21.0

type ServerReader interface {
	FindOneServer(ctx context.Context, id int64) (*node.Server, error)
}

ServerReader reads a server row.

type Service

type Service struct {
	// contains filtered or unexported fields
}

Service is the node-facing API entry point used by the network facade.

func NewService

func NewService(deps Deps) *Service

NewService returns the node API's service over deps.

func (*Service) GetServerConfig

GetServerConfig returns a server protocol's configuration in the legacy shape, from the server's response cache when it holds one. meta carries the node's If-None-Match: a matching ETag returns xerr.ErrNotModified. The returned response metadata holds the headers set before any error.

func (*Service) GetServerUserList

GetServerUserList returns the users a server serves over a protocol, from the server's response cache when it holds one, rebuilding and caching the list otherwise. meta carries the node's If-None-Match: a matching ETag returns xerr.ErrNotModified. The returned response metadata holds the headers set before any error.

func (*Service) PushOnlineUsers

func (s *Service) PushOnlineUsers(ctx context.Context, req *dto.OnlineUsersRequest) error

PushOnlineUsers records the users a server reports online over a protocol, with their IPs, for the server and in the global online count. Only the subscriptions the server serves over the protocol, the users its user list hands it, are recorded; an entry for any other subscription is dropped and logged, as the traffic report does. A report over the entry bound, or with an address that is not an IP, is refused.

func (*Service) QueryServerProtocolConfig

func (s *Service) QueryServerProtocolConfig(ctx context.Context, req *dto.QueryServerConfigRequest) (*dto.QueryServerConfigResponse, error)

QueryServerProtocolConfig returns the configuration a node pulls for its server: the enabled protocols, only the requested ones when the node names any, with the node settings in effect after the server's override.

func (*Service) ServerPushStatus

func (s *Service) ServerPushStatus(ctx context.Context, req *dto.ServerPushStatusRequest) error

ServerPushStatus records a server's status report and heartbeat. A changed certificate pin the node reports for its protocol is stored too, and the server's caches that carry the old pin are dropped.

func (*Service) ServerPushUserTraffic

func (s *Service) ServerPushUserTraffic(ctx context.Context, req *dto.ServerPushUserTrafficRequest) error

ServerPushUserTraffic adds a server's traffic report to the aggregation pipeline, which bills it to the subscriptions in batches.

type ShadowsocksNode

type ShadowsocksNode struct {
	Port      uint16 `json:"port"`
	Cipher    string `json:"method"`
	ServerKey string `json:"server_key"`
}

type Snapshot

type Snapshot struct {
	Node      config.NodeConfig
	Subscribe config.SubscribeConfig
}

Snapshot is the per-request view of the runtime-mutable settings the node API consumes.

type StatusRecorder added in v1.21.0

type StatusRecorder interface {
	UpdateStatusCache(ctx context.Context, serverId int64, status *node.Status) error
	UpdateServerProtocolsIfCurrent(ctx context.Context, id int64, current, updated string) (bool, error)
	ClearServerCache(ctx context.Context, serverId int64) error
}

StatusRecorder records a status report: the reported status, a changed certificate pin, and the invalidation of the server's caches that carry the old pin.

type SubscriptionReader added in v1.21.0

type SubscriptionReader interface {
	ServableSubscriptionsByNodeScope(ctx context.Context, nodeIDs []int64, tags []string) ([]subscription.ServedSubscription, error)
	SubscriptionByID(ctx context.Context, id int64) (*usersub.Subscribe, error)
}

SubscriptionReader is the subscription read port (the subscription facade): the subscriptions the nodes of a scope serve, and one by id.

type TransportConfig

type TransportConfig struct {
	Path                 string `json:"path"`
	Host                 string `json:"host"`
	ServiceName          string `json:"service_name"`
	DisableSNI           bool   `json:"disable_sni"`
	ReduceRtt            bool   `json:"reduce_rtt"`
	UDPRelayMode         string `json:"udp_relay_mode"`
	CongestionController string `json:"congestion_controller"`
}

TransportConfig is the transport block of the legacy server-config shapes.

type TrojanNode

type TrojanNode struct {
	Port            uint16           `json:"port"`
	Network         string           `json:"transport"`
	TransportConfig *TransportConfig `json:"transport_config"`
	Security        string           `json:"security"`
	SecurityConfig  *SecurityConfig  `json:"security_config"`
}

type TuicNode

type TuicNode struct {
	Port           uint16          `json:"port"`
	SecurityConfig *SecurityConfig `json:"security_config"`
}

type VlessNode

type VlessNode struct {
	Port            uint16           `json:"port"`
	Flow            string           `json:"flow"`
	Network         string           `json:"transport"`
	TransportConfig *TransportConfig `json:"transport_config"`
	Security        string           `json:"security"`
	SecurityConfig  *SecurityConfig  `json:"security_config"`
}

VlessNode, VmessNode, ShadowsocksNode, TrojanNode, AnyTLSNode, TuicNode and Hysteria2Node are the legacy server-config shapes of their protocols (GET /v1/server/config).

type VmessNode

type VmessNode struct {
	Port            uint16           `json:"port"`
	Network         string           `json:"transport"`
	TransportConfig *TransportConfig `json:"transport_config"`
	Security        string           `json:"security"`
	SecurityConfig  *SecurityConfig  `json:"security_config"`
}

Jump to

Keyboard shortcuts

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