service

package
v1.1.0 Latest Latest
Warning

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

 Go to latest Published: Apr 19, 2026 License: MIT Imports: 26 Imported by: 0

Documentation

Overview

Package service defines service-layer types used by API handlers.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ControlPlaneService 

type ControlPlaneService struct {
	Engine         *state.StateEngine
	Pool           *topology.GlobalNodePool
	SubMgr         *topology.SubscriptionManager
	Scheduler      *topology.SubscriptionScheduler
	Router         *routing.Router
	GeoIP          *geoip.Service
	ProbeMgr       *probe.ProbeManager
	MatcherRuntime *proxy.AccountMatcherRuntime
	RuntimeCfg     *atomic.Pointer[config.RuntimeConfig]
	EnvCfg         *config.EnvConfig
	// contains filtered or unexported fields
}

ControlPlaneService provides all control plane operations. Handlers call its methods; business logic lives here, not in handlers.

func (*ControlPlaneService) CleanupSubscriptionCircuitOpenNodes 

func (s *ControlPlaneService) CleanupSubscriptionCircuitOpenNodes(id string) (int, error)

CleanupSubscriptionCircuitOpenNodes removes problematic nodes from a subscription. It marks nodes as evicted (while keeping managed hashes) for nodes currently circuit-open, and nodes with no outbound while carrying a non-empty last error.

func (*ControlPlaneService) CreatePlatform 

func (s *ControlPlaneService) CreatePlatform(req CreatePlatformRequest) (*PlatformResponse, error)

CreatePlatform creates a new platform.

func (*ControlPlaneService) CreateSubscription 

func (s *ControlPlaneService) CreateSubscription(req CreateSubscriptionRequest) (*SubscriptionResponse, error)

CreateSubscription creates a new subscription.

func (*ControlPlaneService) DeleteAccountHeaderRule 

func (s *ControlPlaneService) DeleteAccountHeaderRule(prefix string) error

DeleteAccountHeaderRule deletes a rule.

func (*ControlPlaneService) DeleteAllLeases 

func (s *ControlPlaneService) DeleteAllLeases(platformID string) error

DeleteAllLeases removes all leases for a platform.

func (*ControlPlaneService) DeleteLease 

func (s *ControlPlaneService) DeleteLease(platformID, account string) error

DeleteLease removes a single lease.

func (*ControlPlaneService) DeletePlatform 

func (s *ControlPlaneService) DeletePlatform(id string) error

DeletePlatform deletes a platform.

func (*ControlPlaneService) DeleteSubscription 

func (s *ControlPlaneService) DeleteSubscription(id string) error

DeleteSubscription deletes a subscription and evicts its nodes.

func (*ControlPlaneService) GetGeoIPStatus 

func (s *ControlPlaneService) GetGeoIPStatus() GeoIPStatus

GetGeoIPStatus returns the current GeoIP status.

func (*ControlPlaneService) GetIPLoad 

func (s *ControlPlaneService) GetIPLoad(platformID string) ([]IPLoadEntry, error)

GetIPLoad returns IP load stats for a platform.

func (*ControlPlaneService) GetLease 

func (s *ControlPlaneService) GetLease(platformID, account string) (*LeaseResponse, error)

GetLease returns a single lease.

func (*ControlPlaneService) GetNode 

func (s *ControlPlaneService) GetNode(hashStr string) (*NodeSummary, error)

GetNode returns a single node by hash.

func (*ControlPlaneService) GetPlatform 

func (s *ControlPlaneService) GetPlatform(id string) (*PlatformResponse, error)

GetPlatform returns a single platform by ID.

func (*ControlPlaneService) GetSubscription 

func (s *ControlPlaneService) GetSubscription(id string) (*SubscriptionResponse, error)

GetSubscription returns a single subscription by ID.

func (*ControlPlaneService) InheritLeaseByPlatformName 

func (s *ControlPlaneService) InheritLeaseByPlatformName(platformName, parentAccount, newAccount string) error

InheritLeaseByPlatformName copies a valid parent lease onto newAccount.

func (*ControlPlaneService) ListAccountHeaderRules 

func (s *ControlPlaneService) ListAccountHeaderRules() ([]RuleResponse, error)

ListAccountHeaderRules returns all rules.

func (*ControlPlaneService) ListLeases 

func (s *ControlPlaneService) ListLeases(platformID string) ([]LeaseResponse, error)

ListLeases returns all leases for a platform.

func (*ControlPlaneService) ListNodes 

func (s *ControlPlaneService) ListNodes(filters NodeFilters) ([]NodeSummary, error)

ListNodes returns nodes from the pool with optional filters.

func (*ControlPlaneService) ListPlatforms 

func (s *ControlPlaneService) ListPlatforms() ([]PlatformResponse, error)

ListPlatforms returns all platforms from the database.

func (*ControlPlaneService) ListSubscriptions 

func (s *ControlPlaneService) ListSubscriptions(enabled *bool) ([]SubscriptionResponse, error)

ListSubscriptions returns all subscriptions, optionally filtered by enabled.

func (*ControlPlaneService) LookupIP 

func (s *ControlPlaneService) LookupIP(ipStr string) (string, error)

LookupIP performs a GeoIP lookup.

func (*ControlPlaneService) PatchRuntimeConfig 

func (s *ControlPlaneService) PatchRuntimeConfig(patchJSON json.RawMessage) (*config.RuntimeConfig, error)

PatchRuntimeConfig applies a constrained partial patch to the runtime config. This is not RFC 7396 JSON Merge Patch: patch must be a non-empty object and null values are rejected. Pipeline: validate → persist → atomic swap.

func (*ControlPlaneService) PreviewFilter 

func (s *ControlPlaneService) PreviewFilter(req PreviewFilterRequest) ([]NodeSummary, error)

PreviewFilter returns nodes matching the given filter spec.

func (*ControlPlaneService) ProbeEgress 

func (s *ControlPlaneService) ProbeEgress(hashStr string) (*probe.EgressProbeResult, error)

ProbeEgress triggers a synchronous egress probe and returns results.

func (*ControlPlaneService) ProbeLatency 

func (s *ControlPlaneService) ProbeLatency(hashStr string) (*probe.LatencyProbeResult, error)

ProbeLatency triggers a synchronous latency probe and returns results.

func (*ControlPlaneService) RebuildPlatformView 

func (s *ControlPlaneService) RebuildPlatformView(id string) error

RebuildPlatformView triggers a full rebuild of the platform's routable view.

func (*ControlPlaneService) RefreshSubscription 

func (s *ControlPlaneService) RefreshSubscription(id string) error

RefreshSubscription triggers an immediate subscription refresh (blocks).

func (*ControlPlaneService) ResetPlatformToDefault 

func (s *ControlPlaneService) ResetPlatformToDefault(id string) (*PlatformResponse, error)

ResetPlatformToDefault resets a platform to env defaults.

func (*ControlPlaneService) ResolveAccountHeaderRule 

func (s *ControlPlaneService) ResolveAccountHeaderRule(rawURL string) (*ResolveResult, error)

ResolveAccountHeaderRule resolves a URL against account header rules.

func (*ControlPlaneService) UpdateGeoIPNow 

func (s *ControlPlaneService) UpdateGeoIPNow() error

UpdateGeoIPNow triggers an immediate GeoIP database update (blocks).

func (*ControlPlaneService) UpdatePlatform 

func (s *ControlPlaneService) UpdatePlatform(id string, patchJSON json.RawMessage) (*PlatformResponse, error)

UpdatePlatform applies a constrained partial patch to a platform. This is not RFC 7396 JSON Merge Patch: patch must be a non-empty object and null values are rejected.

func (*ControlPlaneService) UpdateSubscription 

func (s *ControlPlaneService) UpdateSubscription(id string, patchJSON json.RawMessage) (*SubscriptionResponse, error)

UpdateSubscription applies a constrained partial patch to a subscription. This is not RFC 7396 JSON Merge Patch: patch must be a non-empty object and null values are rejected.

func (*ControlPlaneService) UpsertAccountHeaderRule 

func (s *ControlPlaneService) UpsertAccountHeaderRule(prefix string, headers []string) (*RuleResponse, bool, error)

UpsertAccountHeaderRule creates or updates a rule. Returns (response, created, error).

type CreatePlatformRequest 

type CreatePlatformRequest struct {
	Name                             *string  `json:"name"`
	StickyTTL                        *string  `json:"sticky_ttl"`
	RegexFilters                     []string `json:"regex_filters"`
	RegionFilters                    []string `json:"region_filters"`
	ReverseProxyMissAction           *string  `json:"reverse_proxy_miss_action"`
	ReverseProxyEmptyAccountBehavior *string  `json:"reverse_proxy_empty_account_behavior"`
	ReverseProxyFixedAccountHeader   *string  `json:"reverse_proxy_fixed_account_header"`
	AllocationPolicy                 *string  `json:"allocation_policy"`
}

CreatePlatformRequest holds create platform parameters.

type CreateSubscriptionRequest 

type CreateSubscriptionRequest struct {
	Name                    *string `json:"name"`
	SourceType              *string `json:"source_type"`
	URL                     *string `json:"url"`
	Content                 *string `json:"content"`
	UpdateInterval          *string `json:"update_interval"`
	Enabled                 *bool   `json:"enabled"`
	Ephemeral               *bool   `json:"ephemeral"`
	EphemeralNodeEvictDelay *string `json:"ephemeral_node_evict_delay"`
}

CreateSubscriptionRequest holds create subscription parameters.

type GeoIPStatus 

type GeoIPStatus struct {
	DBMtime             string `json:"db_mtime"`
	NextScheduledUpdate string `json:"next_scheduled_update"`
}

GeoIPStatus is the API response for GeoIP status.

type IPLoadEntry 

type IPLoadEntry struct {
	EgressIP   string `json:"egress_ip"`
	LeaseCount int64  `json:"lease_count"`
}

IPLoadEntry is the API response for IP load stats.

type LeaseResponse 

type LeaseResponse struct {
	PlatformID   string `json:"platform_id"`
	Account      string `json:"account"`
	NodeHash     string `json:"node_hash"`
	NodeTag      string `json:"node_tag"`
	EgressIP     string `json:"egress_ip"`
	Expiry       string `json:"expiry"`
	LastAccessed string `json:"last_accessed"`
}

LeaseResponse is the API response for a lease.

type NodeFilters 

type NodeFilters struct {
	PlatformID     *string
	SubscriptionID *string
	Enabled        *bool
	Region         *string
	CircuitOpen    *bool
	HasOutbound    *bool
	EgressIP       *string
	ProbedSince    *time.Time
	TagKeyword     *string
}

NodeFilters holds query filters for listing nodes.

type NodeSummary 

type NodeSummary struct {
	NodeHash                         string    `json:"node_hash"`
	CreatedAt                        string    `json:"created_at"`
	Enabled                          bool      `json:"enabled"`
	DisplayTag                       string    `json:"display_tag,omitempty"`
	HasOutbound                      bool      `json:"has_outbound"`
	LastError                        string    `json:"last_error,omitempty"`
	CircuitOpenSince                 *string   `json:"circuit_open_since"`
	FailureCount                     int       `json:"failure_count"`
	EgressIP                         string    `json:"egress_ip,omitempty"`
	Region                           string    `json:"region,omitempty"`
	LastEgressUpdate                 string    `json:"last_egress_update,omitempty"`
	LastLatencyProbeAttempt          string    `json:"last_latency_probe_attempt,omitempty"`
	LastAuthorityLatencyProbeAttempt string    `json:"last_authority_latency_probe_attempt,omitempty"`
	ReferenceLatencyMs               *float64  `json:"reference_latency_ms,omitempty"`
	LastEgressUpdateAttempt          string    `json:"last_egress_update_attempt,omitempty"`
	Tags                             []NodeTag `json:"tags"`
}

NodeSummary is the API response for a node.

func (NodeSummary) IsHealthyAndEnabled added in v1.0.1 

func (n NodeSummary) IsHealthyAndEnabled() bool

IsHealthyAndEnabled follows the node-summary health rule used by API/UI aggregates: enabled, outbound-ready, and not circuit-open.

type NodeTag 

type NodeTag struct {
	SubscriptionID          string `json:"subscription_id"`
	SubscriptionName        string `json:"subscription_name"`
	Tag                     string `json:"tag"`
	SubscriptionCreatedAtNs int64  `json:"-"`
}

type PlatformResponse 

type PlatformResponse struct {
	ID                               string   `json:"id"`
	Name                             string   `json:"name"`
	StickyTTL                        string   `json:"sticky_ttl"`
	RegexFilters                     []string `json:"regex_filters"`
	RegionFilters                    []string `json:"region_filters"`
	RoutableNodeCount                int      `json:"routable_node_count"`
	ReverseProxyMissAction           string   `json:"reverse_proxy_miss_action"`
	ReverseProxyEmptyAccountBehavior string   `json:"reverse_proxy_empty_account_behavior"`
	ReverseProxyFixedAccountHeader   string   `json:"reverse_proxy_fixed_account_header"`
	AllocationPolicy                 string   `json:"allocation_policy"`
	UpdatedAt                        string   `json:"updated_at"`
}

PlatformResponse is the API response model for a platform.

type PlatformSpecFilter 

type PlatformSpecFilter struct {
	RegexFilters  []string `json:"regex_filters"`
	RegionFilters []string `json:"region_filters"`
}

type PreviewFilterRequest 

type PreviewFilterRequest struct {
	PlatformID   *string             `json:"platform_id"`
	PlatformSpec *PlatformSpecFilter `json:"platform_spec"`
}

PreviewFilterRequest holds preview filter parameters.

type ResolveResult 

type ResolveResult struct {
	MatchedURLPrefix string   `json:"matched_url_prefix"`
	Headers          []string `json:"headers"`
}

ResolveResult is the API response for rule resolution.

type RuleResponse 

type RuleResponse struct {
	URLPrefix string   `json:"url_prefix"`
	Headers   []string `json:"headers"`
	UpdatedAt string   `json:"updated_at"`
}

RuleResponse is the API response for an account header rule.

type ServiceError 

type ServiceError struct {
	Code    string // INVALID_ARGUMENT, NOT_FOUND, CONFLICT, INTERNAL
	Message string
	Err     error
}

ServiceError wraps an error with a code for API response mapping.

func (*ServiceError) Error 

func (e *ServiceError) Error() string

func (*ServiceError) Unwrap 

func (e *ServiceError) Unwrap() error

type SubscriptionResponse 

type SubscriptionResponse struct {
	ID                      string `json:"id"`
	Name                    string `json:"name"`
	SourceType              string `json:"source_type"`
	URL                     string `json:"url"`
	Content                 string `json:"content"`
	UpdateInterval          string `json:"update_interval"`
	NodeCount               int    `json:"node_count"`
	HealthyNodeCount        int    `json:"healthy_node_count"`
	Ephemeral               bool   `json:"ephemeral"`
	EphemeralNodeEvictDelay string `json:"ephemeral_node_evict_delay"`
	Enabled                 bool   `json:"enabled"`
	CreatedAt               string `json:"created_at"`
	LastChecked             string `json:"last_checked,omitempty"`
	LastUpdated             string `json:"last_updated,omitempty"`
	LastError               string `json:"last_error,omitempty"`
}

SubscriptionResponse is the API response for a subscription.

type SystemInfo 

type SystemInfo struct {
	Version   string    `json:"version"`
	GitCommit string    `json:"git_commit"`
	BuildTime string    `json:"build_time"`
	StartedAt time.Time `json:"started_at"`
}

SystemInfo contains version and runtime information.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.