serverapi

package
v1.21.3 Latest Latest
Warning

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

Go to latest
Published: Nov 1, 2026 License: GPL-3.0 Imports: 28 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) ClaimServerDevice added in v1.21.3

func (*Service) GetServerAliveList added in v1.21.3

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