protocol

package
v1.0.2 Latest Latest
Warning

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

Go to latest
Published: Oct 14, 2026 License: MPL-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package protocol defines the master/agent WebSocket v1 contract.

Index

Constants

View Source
const MaxFrameBytes = 16 << 20
View Source
const Version = 1

Variables

View Source
var CommandNames = []string{"connections.list", "connections.close", "users.active_ips", "ips.control", "metrics.get", "jobs.list", "firewall.status", "firewall.confirm", "firewall.apply", "speedtest", "update.check", "update.install", "update.rollback", "runtime.reload", "geodata.refresh", "ddns.run", "certificates.get", "traffic.flush", "config.validate"}
View Source
var MasterMessageTypes = []string{"state.sync", "config.apply", "users.sync", "users.delta", "user.controls", "traffic.ack", "command", "command.cancel"}

Functions

func Clone

func Clone[T any](value T) T

func Decode

func Decode(b []byte, out any) error

func PublicProxyAddress added in v1.0.2

func PublicProxyAddress(raw string) bool

PublicProxyAddress admits literal public addresses only, preventing node DNS rebinding.

func Schema

func Schema(value any) map[string]any

func Schemas

func Schemas() map[string]any

func UserEmail

func UserEmail(u User, tag string) string

UserEmail binds authenticated transports to the current credential generation. A revoked mux transport cannot authenticate new leaf streams using only a stable user ID.

func ValidName

func ValidName(s string) bool

func ValidateMemberOutbounds added in v1.0.2

func ValidateMemberOutbounds(raw json.RawMessage, tags []string) error

ValidateMemberOutbounds guards master-generated member proxies independently on the agent.

func ValidateUsers

func ValidateUsers(users []User) error

Types

type AgentHello added in v1.0.2

type AgentHello struct {
	AgentID        string   `json:"agent_id"`
	BootID         string   `json:"boot_id"`
	Version        string   `json:"version"`
	XrayVersion    string   `json:"xray_version"`
	ConfigRevision uint64   `json:"config_revision"`
	Ready          bool     `json:"ready"`
	Capabilities   []string `json:"capabilities"`
	UpgradePending bool     `json:"upgrade_pending,omitempty"`
	BinarySHA256   string   `json:"binary_sha256,omitempty"`
	Platform       string   `json:"platform,omitempty"`
}

type Certificate

type Certificate struct {
	Provider string            `json:"provider,omitempty"`
	Config   config.CertConfig `json:"config"`
}

type Config

type Config struct {
	Xray                json.RawMessage        `json:"xray"`
	Users               []User                 `json:"users"`
	Providers           map[string]Provider    `json:"providers,omitempty"`
	Certificates        map[string]Certificate `json:"certificates,omitempty"`
	InboundCertificates map[string]string      `json:"inbound_certificates,omitempty"`
	DDNS                []DDNSJob              `json:"ddns,omitempty"`
	DNS                 DNSPolicy              `json:"dns,omitempty"`
	Firewall            FirewallPolicy         `json:"firewall,omitempty"`
	BlockedPorts        []PortRange            `json:"blocked_ports,omitempty"`
	AssetHashes         map[string]string      `json:"asset_hashes,omitempty"`
	Updates             UpdatePolicy           `json:"updates,omitempty"`
	Telemetry           TelemetryPolicy        `json:"telemetry,omitempty"`
	Torrent             TorrentPolicy          `json:"torrent,omitempty"`
	MemberOutbounds     []string               `json:"member_outbounds,omitempty"`
}

func ParseConfig

func ParseConfig(b []byte) (Config, error)

func (Config) BanDuration

func (c Config) BanDuration() time.Duration

func (Config) ReportInterval

func (c Config) ReportInterval() time.Duration

func (Config) SampleInterval

func (c Config) SampleInterval() time.Duration

func (Config) Validate

func (c Config) Validate() error

type DDNSJob

type DDNSJob struct {
	ID              string `json:"id"`
	Provider        string `json:"provider"`
	Zone            string `json:"zone"`
	Name            string `json:"name"`
	IPv4            string `json:"ipv4,omitempty"`
	IPv6            string `json:"ipv6,omitempty"`
	Interface       string `json:"interface,omitempty"`
	IPv4URL         string `json:"ipv4_url,omitempty"`
	IPv6URL         string `json:"ipv6_url,omitempty"`
	TTLSeconds      int    `json:"ttl_seconds,omitempty"`
	IntervalSeconds int    `json:"interval_seconds,omitempty"`
}

type DNSPolicy

type DNSPolicy struct {
	Mode      string   `json:"mode,omitempty"`
	Redirect  bool     `json:"redirect,omitempty"`
	Upstreams []string `json:"upstreams,omitempty"`
}

type FirewallPolicy

type FirewallPolicy struct {
	Enabled       bool      `json:"enabled"`
	Protect       bool      `json:"protect"`
	TCPPorts      []int     `json:"tcp_ports,omitempty"`
	UDPPorts      []int     `json:"udp_ports,omitempty"`
	SSHPorts      []int     `json:"ssh_ports,omitempty"`
	AllowPrefixes []string  `json:"allow_prefixes,omitempty"`
	Forward       []Forward `json:"forward,omitempty"`
}

type Forward

type Forward struct {
	ListenIP   string `json:"listen_ip,omitempty"`
	Port       int    `json:"port"`
	TargetIP   string `json:"target_ip"`
	TargetPort int    `json:"target_port"`
	Network    string `json:"network"`
}

type IPBlock

type IPBlock struct {
	SourceIP string    `json:"source_ip"`
	UserID   int       `json:"user_id,omitempty"`
	Until    time.Time `json:"until"`
}

type IPControl

type IPControl struct {
	SourceIP     string `json:"source_ip"`
	UserID       int    `json:"user_id,omitempty"`
	Drop         bool   `json:"drop,omitempty"`
	BlockSeconds int    `json:"block_seconds,omitempty"`
	Unblock      bool   `json:"unblock,omitempty"`
}

type Message

type Message struct {
	V            int             `json:"v"`
	Type         string          `json:"type"`
	ID           string          `json:"id,omitempty"`
	Revision     uint64          `json:"revision,omitempty"`
	BaseRevision uint64          `json:"base_revision,omitempty"`
	Data         json.RawMessage `json:"data,omitempty"`
}

func New

func New(typ, id string, revision uint64, data any) Message

func Parse

func Parse(b []byte) (Message, error)

type PortRange

type PortRange struct {
	From    int    `json:"from"`
	To      int    `json:"to"`
	Network string `json:"network,omitempty"`
}

type Provider

type Provider struct {
	Type        string            `json:"type"`
	Credentials map[string]string `json:"credentials"`
}

type TelemetryPolicy

type TelemetryPolicy struct {
	IncludeActiveIPs bool `json:"include_active_ips,omitempty"`
	SampleSeconds    int  `json:"sample_seconds,omitempty"`
	ReportSeconds    int  `json:"report_seconds,omitempty"`
}

type TelemetryReport added in v1.0.2

type TelemetryReport struct {
	AgentID          string          `json:"agent_id"`
	BootID           string          `json:"boot_id"`
	Time             time.Time       `json:"time"`
	Connected        bool            `json:"connected"`
	Liveness         bool            `json:"liveness"`
	Ready            bool            `json:"ready"`
	Synchronized     bool            `json:"synchronized"`
	ConfigRevision   uint64          `json:"config_revision"`
	Users            UserMetrics     `json:"users"`
	Machine          json.RawMessage `json:"machine"`
	Certificates     json.RawMessage `json:"certificates"`
	TransportDropped uint64          `json:"transport_dropped"`
}

type TorrentPolicy

type TorrentPolicy struct {
	Enabled    bool `json:"enabled"`
	BanSeconds int  `json:"ban_seconds,omitempty"`
}

type Traffic added in v1.0.2

type Traffic map[int][2]uint64

Traffic contains raw uploaded and downloaded payload bytes, in that order.

type TrafficBarrier added in v1.0.2

type TrafficBarrier struct {
	AgentID          string    `json:"agent_id"`
	Sequence         uint64    `json:"sequence"`
	Through          time.Time `json:"through"`
	Quiesced         bool      `json:"quiesced"`
	AccountingPeriod string    `json:"accounting_period,omitempty"`
}

TrafficBarrier identifies the journal sequence covering a serialized capture.

type TrafficFlush added in v1.0.2

type TrafficFlush struct {
	UserID           int    `json:"user_id,omitempty"`
	Quiesce          bool   `json:"quiesce,omitempty"`
	AccountingPeriod string `json:"accounting_period,omitempty"`
}

type TrafficReport added in v1.0.2

type TrafficReport struct {
	ID      string          `json:"id"`
	Traffic Traffic         `json:"traffic"`
	Samples []TrafficSample `json:"samples,omitempty"`
}

TrafficReport is an immutable journal batch. Samples replace legacy totals for billing.

type TrafficSample added in v1.0.2

type TrafficSample struct {
	UserID           int       `json:"user_id"`
	AccountingPeriod string    `json:"accounting_period"`
	From             time.Time `json:"from"`
	Through          time.Time `json:"through"`
	UploadBytes      uint64    `json:"upload_bytes"`
	DownloadBytes    uint64    `json:"download_bytes"`
}

TrafficSample remains bound to its authorization accounting period across replay.

type UpdatePolicy

type UpdatePolicy struct {
	Enabled bool   `json:"enabled"`
	Version string `json:"version,omitempty"`
}

type User

type User struct {
	ID   int    `json:"id"`
	UUID string `json:"uuid,omitempty"`
	// Native client/account properties, keyed by inbound tag. Email and level are managed.
	Credentials            map[string]json.RawMessage `json:"credentials,omitempty"`
	InboundTags            []string                   `json:"inbound_tags"`
	ActiveIPLimit          int                        `json:"active_ip_limit,omitempty"`
	ConnectionLimit        int                        `json:"connection_limit,omitempty"`
	SpeedLimitMbps         int                        `json:"speed_limit_mbps,omitempty"`
	BurstSpeedLimitMbps    int                        `json:"burst_speed_limit_mbps,omitempty"`
	SpeedLimitAfterSeconds int                        `json:"speed_limit_after_seconds,omitempty"`
	SpeedLimitResetSeconds int                        `json:"speed_limit_reset_seconds,omitempty"`
	BlockNew               bool                       `json:"block_new,omitempty"`
	AccountingPeriod       string                     `json:"accounting_period,omitempty"`
	ValidUntil             *time.Time                 `json:"valid_until,omitempty"`
}

type UserControl

type UserControl struct {
	ID       int  `json:"id"`
	BlockNew bool `json:"block_new"`
}

func (*UserControl) UnmarshalJSON

func (u *UserControl) UnmarshalJSON(b []byte) error

type UserControls

type UserControls struct {
	Users []UserControl `json:"users"`
}

type UserLimitStatus added in v1.0.2

type UserLimitStatus struct {
	UserID  int    `json:"user_id"`
	Limited bool   `json:"limited"`
	Reason  string `json:"reason,omitempty"`
	Scope   string `json:"scope"`
}

type UserMetrics added in v1.0.2

type UserMetrics struct {
	Connections map[int]int             `json:"connections"`
	ActiveIPs   map[int][]string        `json:"active_ips,omitempty"`
	Rejections  map[string]uint64       `json:"rejections"`
	Status      map[int]UserLimitStatus `json:"status"`
	Speed       map[int]UserSpeedStatus `json:"speed"`
	Rates       map[int]UserRate        `json:"rates,omitempty"`
}

type UserRate added in v1.0.2

type UserRate struct {
	UploadBytesPerSecond   float64 `json:"upload_bytes_per_second"`
	DownloadBytesPerSecond float64 `json:"download_bytes_per_second"`
	SampleSeconds          float64 `json:"sample_seconds"`
}

UserRate is measured payload throughput; it is independent of configured speed caps.

type UserSpeedStatus added in v1.0.2

type UserSpeedStatus struct {
	NormalMbps int  `json:"normal_mbps"`
	BurstMbps  int  `json:"burst_mbps"`
	Limited    bool `json:"limited"`
	ActiveMbps int  `json:"active_mbps"`
}

type UsersDelta

type UsersDelta struct {
	Upsert []User `json:"upsert,omitempty"`
	Remove []int  `json:"remove,omitempty"`
}

type UsersSync

type UsersSync struct {
	Users *[]User `json:"users"`
}

Jump to

Keyboard shortcuts

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