agent

Documentation

Overview

Package agent provides a Go SDK for interacting with the Orris Agent API.

Index

• Variables
• type Client
  • func NewClient(baseURL, token string, nodeID int, opts ...Option) *Client
  • func (c *Client) GetConfig(ctx context.Context) (*NodeConfig, error)
  • func (c *Client) GetSubscriptions(ctx context.Context) ([]Subscription, error)
  • func (c *Client) ReportTraffic(ctx context.Context, reports []TrafficReport) (*TrafficReportResult, error)
  • func (c *Client) UpdateOnlineSubscriptions(ctx context.Context, subscriptions []OnlineSubscription) (*OnlineSubscriptionsResult, error)
  • func (c *Client) UpdateStatus(ctx context.Context, status *NodeStatus) error
• type NodeConfig
  • func (c *NodeConfig) IsShadowsocks() bool
  • func (c *NodeConfig) IsTrojan() bool
• type NodeStatus
• type OnlineSubscription
• type OnlineSubscriptionsResult
• type Option
  • func WithHTTPClient(c *http.Client) Option
  • func WithTimeout(d time.Duration) Option
• type Subscription
• type TrafficReport
• type TrafficReportResult

Variables

var ErrUnauthorized = errors.New("unauthorized: invalid or expired node token")

ErrUnauthorized is returned when the API returns a 401 status code. This typically means the node token is invalid or expired.

Types

type Client

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

Client is the Agent API client.

func NewClient

func NewClient(baseURL, token string, nodeID int, opts ...Option) *Client

NewClient creates a new Agent API client.

Parameters:

• baseURL: The API base URL (e.g., "https://api.example.com")
• token: The node authentication token (e.g., "node_xxx")
• nodeID: The node ID assigned by the server

func (*Client) GetConfig

func (c *Client) GetConfig(ctx context.Context) (*NodeConfig, error)

GetConfig retrieves the node configuration.

func (*Client) GetSubscriptions

func (c *Client) GetSubscriptions(ctx context.Context) ([]Subscription, error)

GetSubscriptions retrieves the list of active subscriptions for this node.

func (*Client) ReportTraffic

func (c *Client) ReportTraffic(ctx context.Context, reports []TrafficReport) (*TrafficReportResult, error)

ReportTraffic reports subscription traffic data.

func (*Client) UpdateOnlineSubscriptions

func (c *Client) UpdateOnlineSubscriptions(ctx context.Context, subscriptions []OnlineSubscription) (*OnlineSubscriptionsResult, error)

UpdateOnlineSubscriptions updates the list of online subscriptions.

func (*Client) UpdateStatus

func (c *Client) UpdateStatus(ctx context.Context, status *NodeStatus) error

UpdateStatus updates the node system status.

type NodeConfig

type NodeConfig struct {
	NodeID            int    `json:"node_id"`
	Protocol          string `json:"protocol"`                    // shadowsocks or trojan
	ServerHost        string `json:"server_host"`                 // Server hostname or IP address
	ServerPort        int    `json:"server_port"`                 // Server port number
	EncryptionMethod  string `json:"encryption_method,omitempty"` // Encryption method for Shadowsocks
	ServerKey         string `json:"server_key,omitempty"`        // Server password for SS
	TransportProtocol string `json:"transport_protocol"`          // Transport protocol (tcp, ws, grpc)
	Host              string `json:"host,omitempty"`              // WebSocket host header
	Path              string `json:"path,omitempty"`              // WebSocket path
	ServiceName       string `json:"service_name,omitempty"`      // gRPC service name
	SNI               string `json:"sni,omitempty"`               // TLS Server Name Indication
	AllowInsecure     bool   `json:"allow_insecure"`              // Allow insecure TLS connection
	EnableVless       bool   `json:"enable_vless"`
	EnableXTLS        bool   `json:"enable_xtls"`
	SpeedLimit        uint64 `json:"speed_limit"`
	DeviceLimit       int    `json:"device_limit"`
	RuleListPath      string `json:"rule_list_path,omitempty"`
}

NodeConfig represents the node configuration returned by the API. Compatible with sing-box inbound configuration.

func (*NodeConfig) IsShadowsocks

func (c *NodeConfig) IsShadowsocks() bool

IsShadowsocks returns true if the node is configured for Shadowsocks protocol.

func (*NodeConfig) IsTrojan

func (c *NodeConfig) IsTrojan() bool

IsTrojan returns true if the node is configured for Trojan protocol.

type NodeStatus

type NodeStatus struct {
	CPU        string `json:"CPU"`
	Mem        string `json:"Mem"`
	Disk       string `json:"Disk"`
	Uptime     int    `json:"Uptime"`
	PublicIPv4 string `json:"public_ipv4,omitempty"` // Public IPv4 address
	PublicIPv6 string `json:"public_ipv6,omitempty"` // Public IPv6 address
}

NodeStatus represents the system status of a node.

type OnlineSubscription

type OnlineSubscription struct {
	SubscriptionID int    `json:"subscription_id"`
	IP             string `json:"ip"`
}

OnlineSubscription represents an online subscription connection.

type OnlineSubscriptionsResult

type OnlineSubscriptionsResult struct {
	OnlineCount int `json:"online_count"`
}

OnlineSubscriptionsResult represents the result of updating online subscriptions.

type Option

type Option func(*Client)

Option is a function that configures the Client.

func WithHTTPClient

func WithHTTPClient(c *http.Client) Option

WithHTTPClient sets a custom HTTP client.

func WithTimeout

func WithTimeout(d time.Duration) Option

WithTimeout sets the HTTP client timeout.

type Subscription

type Subscription struct {
	SubscriptionID int    `json:"subscription_id"`
	Password       string `json:"password"`
	Name           string `json:"name"`
	SpeedLimit     uint64 `json:"speed_limit"`
	DeviceLimit    int    `json:"device_limit"`
	ExpireTime     int64  `json:"expire_time"`
}

Subscription represents an individual subscription authorized for the node.

type TrafficReport

type TrafficReport struct {
	SubscriptionID int   `json:"subscription_id"`
	Upload         int64 `json:"upload"`
	Download       int64 `json:"download"`
}

TrafficReport represents traffic data for a single subscription.

type TrafficReportResult

type TrafficReportResult struct {
	SubscriptionsUpdated int `json:"subscriptions_updated"`
}

TrafficReportResult represents the result of a traffic report.