model

package
v0.2.1 Latest Latest
Warning

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

 Go to latest Published: Jun 17, 2026 License: MIT Imports: 1 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	TaskQueued   = "queued"
	TaskLeased   = "leased"
	TaskFinished = "finished"
	TaskFailed   = "failed"

	ApprovalPending  = "pending"
	ApprovalApproved = "approved"
	ApprovalRejected = "rejected"
	ApprovalApplied  = "applied"

	PluginStatusVerified  = "verified"
	PluginStatusInstalled = "installed"
	PluginStatusActive    = "active"
	PluginStatusDisabled  = "disabled"
)
View Source 
const (
	RenewalCycleMonthly    = "monthly"
	RenewalCycleQuarterly  = "quarterly"
	RenewalCycleSemiannual = "semiannual"
	RenewalCycleAnnual     = "annual"
	RenewalCycleCustomDays = "custom_days"
)
View Source 
const (
	DNSEngineCoreDNS = "coredns"

	DNSExposureMesh   = "mesh"
	DNSExposurePublic = "public"

	DNSZoneForward = "forward"
	DNSZoneStatic  = "static"
	DNSZoneBlock   = "block"

	DNSStatusPending  = "pending"
	DNSStatusApplying = "applying"
	DNSStatusRunning  = "running"
	DNSStatusFailed   = "failed"
	DNSStatusDisabled = "disabled"
)
View Source 
const (
	GeoRoutingStrategyGeoIP      = "geoip"
	GeoRoutingStrategyAllHealthy = "all-healthy"
)
View Source 
const (
	NetRuleAllow = "allow"
	NetRuleDeny  = "deny"

	NetDirEgress  = "egress"
	NetDirIngress = "ingress"

	NetProtoTCP = "tcp"
	NetProtoUDP = "udp"
	NetProtoAny = "any"

	NetRefNode   = "node"
	NetRefCIDR   = "cidr"
	NetRefDomain = "domain"
	NetRefAny    = "any"
)
View Source 
const (
	ProxyCoreSingbox = "sing-box"
	ProxyCoreXray    = "xray"

	ProxyProtocolVLESS       = "vless"
	ProxyProtocolVMess       = "vmess"
	ProxyProtocolTrojan      = "trojan"
	ProxyProtocolShadowsocks = "shadowsocks"
	ProxyProtocolHysteria2   = "hysteria2"

	ProxyTransportTCP   = "tcp"
	ProxyTransportWS    = "ws"
	ProxyTransportGRPC  = "grpc"
	ProxyTransportHTTP2 = "http2"
	ProxyTransportQUIC  = "quic"

	ProxySecurityNone    = "none"
	ProxySecurityTLS     = "tls"
	ProxySecurityReality = "reality"

	ProxyUserStatusActive    = "active"
	ProxyUserStatusExpired   = "expired"
	ProxyUserStatusOverQuota = "over_quota"
	ProxyUserStatusDisabled  = "disabled"

	ProxyUsageCollectorStatusOK    = "ok"
	ProxyUsageCollectorStatusError = "error"
)
View Source 
const (
	APIErrorBadRequest       = "bad_request"
	APIErrorUnauthorized     = "unauthorized"
	APIErrorForbidden        = "forbidden"
	APIErrorNotFound         = "not_found"
	APIErrorMethodNotAllowed = "method_not_allowed"
	APIErrorRateLimited      = "rate_limited"
	APIErrorBadGateway       = "bad_gateway"
	APIErrorInternal         = "internal_error"
	APIErrorRequestFailed    = "request_failed"

	APIErrorCapabilityDenied        = "capability_denied"
	APIErrorInvalidNodeToken        = "invalid_node_token"
	APIErrorInvalidTaskLease        = "invalid_task_lease"
	APIErrorTaskOutputLimitExceeded = "task_output_limit_exceeded"
)
View Source 
const (
	StorageKindKV     = "kv"
	StorageKindStatic = "static"

	StorageAccessAdmin = "admin"
	StorageAccessRead  = "read"
	StorageAccessWrite = "write"
)
View Source 
const (
	DDNSProviderCloudflare = "cloudflare"
	DDNSProviderWebhook    = "webhook"
)
View Source 
const (
	MonitorTypeTCP  = "tcp"
	MonitorTypeHTTP = "http"
	MonitorTypeICMP = "icmp"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type APIError added in v0.2.0 

type APIError struct {
	Code      string `json:"code"`
	Message   string `json:"message"`
	RequestID string `json:"request_id"`
}

APIError is the stable machine-readable error shape shared by server, dashboard, agents and plugins. Messages are user-facing; callers should make authorization and retry decisions from Code.

type APIErrorResponse added in v0.2.0 

type APIErrorResponse struct {
	Error APIError `json:"error"`
}

type AgentConfig added in v0.2.1 

type AgentConfig struct {
	Debug AgentDebugConfig `json:"debug"`
}

type AgentDebugBatch added in v0.2.1 

type AgentDebugBatch struct {
	NodeID     string    `json:"node_id"`
	Lines      []string  `json:"lines"`
	CapturedAt time.Time `json:"captured_at"`
}

AgentDebugBatch carries locally emitted agent diagnostics to the server log store when server-side collection is enabled for the node.

type AgentDebugConfig added in v0.2.1 

type AgentDebugConfig struct {
	Enabled       bool `json:"enabled"`
	Collect       bool `json:"collect"`
	MaxLineBytes  int  `json:"max_line_bytes,omitempty"`
	MaxBatchLines int  `json:"max_batch_lines,omitempty"`
}

AgentDebugConfig is the runtime policy an agent polls from the server. It is intentionally small and non-secret so older agents can ignore it safely.

type AgentDebugPolicy added in v0.2.1 

type AgentDebugPolicy struct {
	Enabled   bool      `json:"enabled"`
	Collect   bool      `json:"collect"`
	UpdatedAt time.Time `json:"updated_at,omitempty"`
}

AgentDebugPolicy is the operator-owned diagnostic mode for a node-agent. When Enabled is true the agent emits verbose non-secret diagnostics locally on the node. Collect controls whether those diagnostics are also shipped back to the server log store. Server-managed debug collection defaults to true when enabled, but operators may keep local node debug output without central collection by setting Collect=false.

type AgentUpdatePolicy added in v0.2.0 

type AgentUpdatePolicy struct {
	NodeID             string    `json:"node_id"`
	Enabled            bool      `json:"enabled"`
	AutoPlan           bool      `json:"auto_plan"`
	TargetVersion      string    `json:"target_version"`
	BinaryURL          string    `json:"binary_url"`
	SHA256             string    `json:"sha256"`
	InstallPath        string    `json:"install_path"`
	ServiceName        string    `json:"service_name"`
	LastPlannedVersion string    `json:"last_planned_version,omitempty"`
	LastPlannedAt      time.Time `json:"last_planned_at,omitempty"`
	LastAppliedVersion string    `json:"last_applied_version,omitempty"`
	LastAppliedAt      time.Time `json:"last_applied_at,omitempty"`
	LastError          string    `json:"last_error,omitempty"`
	CreatedAt          time.Time `json:"created_at"`
	UpdatedAt          time.Time `json:"updated_at"`
}

AgentUpdatePolicy is a server-owned node-agent update intent. It carries no secrets: operators provide a public HTTPS binary URL plus the expected SHA-256 digest, and the server turns that into a reviewed, plan-hash-bound update task. AutoPlan never mutates a node directly; it only creates a pending approval when the node reports a different AgentVersion and no equivalent pending/approved update is already open.

type Approval 

type Approval struct {
	ID         string    `json:"id"`
	NodeID     string    `json:"node_id"`
	Plugin     string    `json:"plugin"`
	Action     string    `json:"action"`
	Plan       string    `json:"plan"`
	Status     string    `json:"status"`
	ActorID    string    `json:"actor_id"`
	ApprovedBy string    `json:"approved_by,omitempty"`
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`
}

type AuditEvent 

type AuditEvent struct {
	ID            string            `json:"id"`
	At            time.Time         `json:"at"`
	ActorID       string            `json:"actor_id"`
	TokenID       string            `json:"token_id"`
	NodeID        string            `json:"node_id"`
	Action        string            `json:"action"`
	Scope         string            `json:"scope"`
	Decision      string            `json:"decision"`
	Reason        string            `json:"reason"`
	CorrelationID string            `json:"correlation_id"`
	Metadata      map[string]string `json:"metadata,omitempty"`
}

type DDNSProfile added in v0.2.0 

type DDNSProfile struct {
	ID         string   `json:"id"`
	Name       string   `json:"name"`
	NodeID     string   `json:"node_id"`
	Provider   string   `json:"provider"`
	Domains    []string `json:"domains"`
	EnableIPv4 bool     `json:"enable_ipv4"`
	EnableIPv6 bool     `json:"enable_ipv6"`
	MaxRetries int      `json:"max_retries"`
	TTL        int      `json:"ttl"`

	// Cloudflare provider
	CFAPIToken string `json:"cf_api_token,omitempty"`

	// Webhook provider. Body/URL support the templates #ip#, #domain#, #type#.
	WebhookURL     string `json:"webhook_url,omitempty"`
	WebhookMethod  string `json:"webhook_method,omitempty"`
	WebhookBody    string `json:"webhook_body,omitempty"`
	WebhookHeaders string `json:"webhook_headers,omitempty"`

	// Status (updated by the server after each run).
	LastIPv4  string    `json:"last_ipv4,omitempty"`
	LastIPv6  string    `json:"last_ipv6,omitempty"`
	LastRunAt time.Time `json:"last_run_at,omitempty"`
	LastError string    `json:"last_error,omitempty"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

DDNSProfile describes how a node's public IP should be published to DNS. It is bound to a node; when that node's observed public IP changes, the bound profiles' records are updated.

type DNSDeployment added in v0.2.0 

type DNSDeployment struct {
	ID     string `json:"id"`
	Name   string `json:"name"`
	NodeID string `json:"node_id"`
	Engine string `json:"engine"`

	ListenPort int    `json:"listen_port"`
	EnableUDP  bool   `json:"enable_udp"`
	EnableTCP  bool   `json:"enable_tcp"`
	Exposure   string `json:"exposure"`

	Zones []DNSZone `json:"zones"`

	Hostname      string `json:"hostname,omitempty"`
	PublishIPv4   bool   `json:"publish_ipv4"`
	PublishIPv6   bool   `json:"publish_ipv6"`
	RecordTTL     int    `json:"record_ttl,omitempty"`
	CFAPIToken    string `json:"cf_api_token,omitempty"`
	DDNSProfileID string `json:"ddns_profile_id,omitempty"`

	Status           string    `json:"status"`
	EngineVersion    string    `json:"engine_version,omitempty"`
	LastIPv4         string    `json:"last_ipv4,omitempty"`
	LastIPv6         string    `json:"last_ipv6,omitempty"`
	LastAppliedAt    time.Time `json:"last_applied_at,omitempty"`
	LastError        string    `json:"last_error,omitempty"`
	LastPublishedAt  time.Time `json:"last_published_at,omitempty"`
	LastPublishError string    `json:"last_publish_error,omitempty"`
	Disabled         bool      `json:"disabled,omitempty"`
	CreatedAt        time.Time `json:"created_at"`
	UpdatedAt        time.Time `json:"updated_at"`
}

DNSDeployment is the control-plane intent for a self-hosted DNS service on a node. CFAPIToken is a server-side secret and must never appear in read views or agent payloads.

type DNSRecord added in v0.2.0 

type DNSRecord struct {
	Name  string `json:"name"`
	Type  string `json:"type"`
	Value string `json:"value"`
	TTL   int    `json:"ttl,omitempty"`
}

DNSRecord is a static authoritative record for a DNSZoneStatic zone.

type DNSZone added in v0.2.0 

type DNSZone struct {
	Suffix    string      `json:"suffix"`
	Mode      string      `json:"mode"`
	Upstreams []string    `json:"upstreams,omitempty"`
	Records   []DNSRecord `json:"records,omitempty"`
}

DNSZone is one served block in a self-hosted resolver configuration. It is server-owned intent; the agent only receives the rendered, approved artifact.

type GeoRouting added in v0.2.0 

type GeoRouting struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	Hostname    string   `json:"hostname"`     // the geo apex, e.g. dns.roobli.org
	NodeIDs     []string `json:"node_ids"`     // participating targets (need NodeGeo + IP)
	DNSNodeIDs  []string `json:"dns_node_ids"` // authoritative DNS nodes (run self-host DNS)
	TTL         int      `json:"ttl,omitempty"`
	Strategy    string   `json:"strategy"`                // "geoip" | "all-healthy"
	GeoIPDBPath string   `json:"geoip_db_path,omitempty"` // GeoLite2 path on the node

	// Parent-zone NS delegation reuses the referenced DDNSProfile's CF token.
	PublishNS     bool   `json:"publish_ns,omitempty"`
	DDNSProfileID string `json:"ddns_profile_id,omitempty"`

	LastRenderedSHA string    `json:"last_rendered_sha,omitempty"`
	Status          string    `json:"status,omitempty"`
	LastAppliedAt   time.Time `json:"last_applied_at,omitempty"`
	LastDelegatedAt time.Time `json:"last_delegated_at,omitempty"`
	LastError       string    `json:"last_error,omitempty"`
	CreatedAt       time.Time `json:"created_at"`
	UpdatedAt       time.Time `json:"updated_at"`
}

GeoRouting answers one apex hostname (e.g. dns.roobli.org) with the nearest healthy participating node, served by Lattice's own DNS nodes (Design 06, Path B). It carries no secrets: the NS-delegation token is reused from the referenced DDNSProfile.

type HostFacts added in v0.2.0 

type HostFacts struct {
	Hostname        string    `json:"hostname,omitempty"`
	OS              string    `json:"os,omitempty"`
	Platform        string    `json:"platform,omitempty"`
	PlatformVersion string    `json:"platform_version,omitempty"`
	KernelVersion   string    `json:"kernel_version,omitempty"`
	Arch            string    `json:"arch,omitempty"`
	CPUCores        int       `json:"cpu_cores,omitempty"`
	CPUModel        string    `json:"cpu_model,omitempty"`
	MemoryTotal     uint64    `json:"memory_total,omitempty"`
	SwapTotal       uint64    `json:"swap_total,omitempty"`
	Virtualization  string    `json:"virtualization,omitempty"`
	BootTime        time.Time `json:"boot_time,omitempty"`
	ReportedAt      time.Time `json:"reported_at,omitempty"`
}

HostFacts are auto-detected, slow-changing machine facts reported by the node-agent. They are advisory low-trust telemetry: useful for display, inventory and map planning, but never for authorization decisions.

type KVEntry 

type KVEntry struct {
	Bucket    string    `json:"bucket"`
	Key       string    `json:"key"`
	Value     string    `json:"value"`
	UpdatedAt time.Time `json:"updated_at"`
}

type LogBatch added in v0.2.0 

type LogBatch struct {
	SourceID   string    `json:"source_id"`
	Path       string    `json:"path"`      // echoed for server cross-check vs the source record
	RotID      string    `json:"rot_id"`    // opaque per-file-incarnation id (inode/ctime)
	FirstOff   uint64    `json:"first_off"` // offset before the first line in this batch
	LastOff    uint64    `json:"last_off"`  // offset after the last line (== agent checkpoint)
	Dropped    uint64    `json:"dropped"`   // lines the agent dropped (backpressure) since last batch
	Lines      []string  `json:"lines"`     // raw lines, ordered, no trailing newline
	CapturedAt time.Time `json:"captured_at"`
}

LogBatch is the agent -> server ingest envelope (one source per batch).

type LogLine added in v0.2.0 

type LogLine struct {
	SourceID  string    `json:"source_id"`
	NodeID    string    `json:"node_id"`
	Path      string    `json:"path"`
	Seq       uint64    `json:"seq"`
	Offset    uint64    `json:"offset"`
	At        time.Time `json:"at"`
	Line      string    `json:"line"`
	Truncated bool      `json:"truncated,omitempty"`
}

LogLine is one ingested line as persisted/queried. Seq is the server-assigned monotonic per-source ingest sequence (the query cursor); Offset is the agent's byte offset after this line in the (rotation-scoped) source file.

type LogSource added in v0.2.0 

type LogSource struct {
	ID            string    `json:"id"`
	Name          string    `json:"name"`
	NodeID        string    `json:"node_id"`
	Path          string    `json:"path"`
	Enabled       bool      `json:"enabled"`
	MaxLineBytes  int       `json:"max_line_bytes"`  // truncate longer lines (server default 16384)
	MaxBatchLines int       `json:"max_batch_lines"` // agent batch cap (server default 500)
	CreatedAt     time.Time `json:"created_at"`
	UpdatedAt     time.Time `json:"updated_at"`
}

LogSource declares a file on a node whose appended lines are tailed by the assigned agent and shipped to the server. It is assignment-driven like Monitor: exactly one node owns a source (a path is node-local), identified by NodeID. LogSource carries no secrets.

type MachineProfile added in v0.2.0 

type MachineProfile struct {
	ID     string `json:"id"`
	NodeID string `json:"node_id"`
	Label  string `json:"label,omitempty"`

	Vendor     string `json:"vendor,omitempty"`
	ConsoleURL string `json:"console_url,omitempty"`
	DetailURL  string `json:"detail_url,omitempty"`
	Region     string `json:"region,omitempty"`
	Notes      string `json:"notes,omitempty"`

	PriceCents int64  `json:"price_cents,omitempty"`
	Currency   string `json:"currency,omitempty"`

	RenewalCycle string    `json:"renewal_cycle,omitempty"`
	CycleDays    int       `json:"cycle_days,omitempty"`
	NextRenewal  time.Time `json:"next_renewal,omitempty"`
	AutoRoll     bool      `json:"auto_roll"`

	RemindDaysBefore []int  `json:"remind_days_before,omitempty"`
	RemindersEnabled bool   `json:"reminders_enabled"`
	LastRemindedKey  string `json:"last_reminded_key,omitempty"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

MachineProfile is operator-authored inventory, cost, and renewal metadata for a node. It is server-only control-plane state: it must never be sent to an agent or used by an agent. ConsoleURL and DetailURL may carry account-specific or signed links and are encrypted at rest by lattice-server.

type Metrics 

type Metrics struct {
	CPUPercent    float64   `json:"cpu_percent"`
	Load1         float64   `json:"load1"`
	MemoryUsed    uint64    `json:"memory_used"`
	MemoryTotal   uint64    `json:"memory_total"`
	DiskUsed      uint64    `json:"disk_used"`
	DiskTotal     uint64    `json:"disk_total"`
	NetRxBytes    uint64    `json:"net_rx_bytes"`
	NetTxBytes    uint64    `json:"net_tx_bytes"`
	UptimeSeconds uint64    `json:"uptime_seconds"`
	CollectedAt   time.Time `json:"collected_at"`
}

type Monitor added in v0.2.0 

type Monitor struct {
	ID          string    `json:"id"`
	Name        string    `json:"name"`
	Type        string    `json:"type"`
	Target      string    `json:"target"`
	IntervalSec int       `json:"interval_sec"`
	TimeoutSec  int       `json:"timeout_sec"`
	AssignAll   bool      `json:"assign_all"`
	NodeIDs     []string  `json:"node_ids,omitempty"`
	Enabled     bool      `json:"enabled"`
	CreatedAt   time.Time `json:"created_at"`
	UpdatedAt   time.Time `json:"updated_at"`
}

Monitor is a periodic reachability/latency probe executed by assigned agents. Targets are host:port for tcp/icmp probes and a URL for http probes. A monitor runs on every node when AssignAll is set, otherwise on the nodes in NodeIDs — this is how a group's members continuously measure their group leader.

type MonitorResult added in v0.2.0 

type MonitorResult struct {
	MonitorID string    `json:"monitor_id"`
	NodeID    string    `json:"node_id"`
	At        time.Time `json:"at"`
	Success   bool      `json:"success"`
	LatencyMs float64   `json:"latency_ms"`
	Error     string    `json:"error,omitempty"`
}

MonitorResult is a single probe outcome reported by an agent.

type NFTInputs added in v0.2.0 

type NFTInputs struct {
	ID     string `json:"id"`
	NodeID string `json:"node_id"`

	InterfaceName string `json:"interface_name,omitempty"`
	WireGuardCIDR string `json:"wireguard_cidr,omitempty"`

	PublicTCP    []int `json:"public_tcp,omitempty"`
	PublicUDP    []int `json:"public_udp,omitempty"`
	WireGuardTCP []int `json:"wireguard_tcp,omitempty"`
	WireGuardUDP []int `json:"wireguard_udp,omitempty"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

NFTInputs are the authoritative, server-owned baseline nftables inputs for a single node. Other core providers (DNS, per-node ACL, proxy cores) compose their required ports/rules into this shape before rendering the one lattice_guard table; they must not create competing nft tables.

type NetEndpoint added in v0.2.0 

type NetEndpoint struct {
	Kind   string `json:"kind"`
	NodeID string `json:"node_id,omitempty"`
	CIDR   string `json:"cidr,omitempty"`
	Domain string `json:"domain,omitempty"`
}

NetEndpoint describes the non-target side of a policy rule. Node refs are resolved by the server at validation/graph/compile time. Domain refs are egress-only and compile to named nft sets that the node refreshes through the agent's DNS updater; they are not accepted as ingress identity.

type NetPolicy added in v0.2.0 

type NetPolicy struct {
	ID            string    `json:"id"`
	TargetNodeID  string    `json:"target_node_id"`
	Rules         []NetRule `json:"rules"`
	Enabled       bool      `json:"enabled"`
	LastPlanSHA   string    `json:"last_plan_sha,omitempty"`
	LastAppliedAt time.Time `json:"last_applied_at,omitempty"`
	LastError     string    `json:"last_error,omitempty"`
	CreatedAt     time.Time `json:"created_at"`
	UpdatedAt     time.Time `json:"updated_at"`
}

NetPolicy is the per-node network intent document. It is control-plane state only: the agent does not receive it directly. A later iteration compiles this policy into nft with dead-man rollback.

type NetRule added in v0.2.0 

type NetRule struct {
	ID        string      `json:"id"`
	Comment   string      `json:"comment,omitempty"`
	Action    string      `json:"action"`
	Direction string      `json:"direction"`
	Protocol  string      `json:"protocol"`
	Ports     []int       `json:"ports,omitempty"`
	Remote    NetEndpoint `json:"remote"`
	Disabled  bool        `json:"disabled,omitempty"`
}

NetRule is an ordered operator-authored L3/L4 policy rule evaluated on the target node. Empty Ports means all ports for the selected protocol.

type Node 

type Node struct {
	ID                 string           `json:"id"`
	Name               string           `json:"name"`
	TokenHash          string           `json:"token_hash"`
	Tags               []string         `json:"tags"`
	Role               string           `json:"role"`
	WireGuardIP        string           `json:"wireguard_ip"`
	WireGuardPublicKey string           `json:"wireguard_public_key,omitempty"`
	WireGuardEndpoint  string           `json:"wireguard_endpoint,omitempty"`
	WireGuardPort      int              `json:"wireguard_port,omitempty"`
	PublicIP           string           `json:"public_ip"`
	PublicIPv6         string           `json:"public_ipv6,omitempty"`
	AgentVersion       string           `json:"agent_version"`
	Online             bool             `json:"online"`
	Disabled           bool             `json:"disabled,omitempty"`
	LastSeen           time.Time        `json:"last_seen"`
	Metrics            Metrics          `json:"metrics"`
	HostFacts          HostFacts        `json:"host_facts"`
	Geo                *NodeGeo         `json:"geo,omitempty"`
	AgentDebug         AgentDebugPolicy `json:"agent_debug"`
	CreatedAt          time.Time        `json:"created_at"`
}

type NodeGeo added in v0.2.0 

type NodeGeo struct {
	Country   string    `json:"country,omitempty"`
	City      string    `json:"city,omitempty"`
	Lat       float64   `json:"lat,omitempty"`
	Lon       float64   `json:"lon,omitempty"`
	ASN       int       `json:"asn,omitempty"`
	ASOrg     string    `json:"as_org,omitempty"`
	Provider  string    `json:"provider,omitempty"`
	UpdatedAt time.Time `json:"updated_at,omitempty"`
}

NodeGeo is operator-supplied map metadata for a node. Agent-reported geo, if ever accepted, is low-trust and must not overwrite operator-entered values.

type NotifyChannel added in v0.2.0 

type NotifyChannel struct {
	ID        string            `json:"id"`
	Name      string            `json:"name"`
	Kind      string            `json:"kind"`
	Config    map[string]string `json:"config,omitempty"`
	Enabled   bool              `json:"enabled"`
	CreatedAt time.Time         `json:"created_at"`
	UpdatedAt time.Time         `json:"updated_at"`
}

NotifyChannel is a persisted notification destination. Config holds provider-specific fields (e.g. token, chat_id, webhook_url); its values are secret and never serialized back to clients.

type NotifyRule added in v0.2.1 

type NotifyRule struct {
	ID            string    `json:"id"`
	Name          string    `json:"name"`
	EventTypes    []string  `json:"event_types,omitempty"`
	ChannelIDs    []string  `json:"channel_ids,omitempty"`
	TitleTemplate string    `json:"title_template,omitempty"`
	BodyTemplate  string    `json:"body_template,omitempty"`
	Enabled       bool      `json:"enabled"`
	CreatedAt     time.Time `json:"created_at"`
	UpdatedAt     time.Time `json:"updated_at"`
}

NotifyRule routes notification events to one or more destinations. EventTypes uses stable server event ids such as monitor.down or ssh.login; "*" matches all notification events. Templates are intentionally small string templates expanded by the server with event_type, title, and body variables.

type OIDCIdentity added in v0.2.0 

type OIDCIdentity struct {
	ProviderID string    `json:"provider_id"`
	Issuer     string    `json:"issuer"`
	Subject    string    `json:"subject"`
	UserID     string    `json:"user_id"`
	Email      string    `json:"email,omitempty"`
	CreatedAt  time.Time `json:"created_at"`
}

OIDCIdentity is the durable link between an external subject and a local user. Keyed in the store by (ProviderID, Subject): the trust anchor is the admin-vetted provider record, not the bare issuer string, so a second provider that happens to share an issuer cannot reuse another provider's links. Subject is the stable identifier; Email/Issuer are reference only.

type OIDCProvider added in v0.2.0 

type OIDCProvider struct {
	ID             string    `json:"id"`
	DisplayName    string    `json:"display_name"`
	Issuer         string    `json:"issuer"`
	ClientID       string    `json:"client_id"`
	ClientSecret   string    `json:"client_secret,omitempty"`
	Scopes         []string  `json:"scopes,omitempty"`
	AllowedDomains []string  `json:"allowed_domains,omitempty"`
	Enabled        bool      `json:"enabled"`
	CreatedAt      time.Time `json:"created_at"`
	UpdatedAt      time.Time `json:"updated_at"`
}

OIDCProvider is an admin-configured external identity provider for SSO login. ClientSecret is a secret-at-rest field (encrypted by the store boundary) and is never returned by the API.

type PluginInstallation added in v0.2.0 

type PluginInstallation struct {
	ID             string    `json:"id"`
	Name           string    `json:"name"`
	Type           string    `json:"type"`
	Version        string    `json:"version,omitempty"`
	Entrypoint     string    `json:"entrypoint,omitempty"`
	Publisher      string    `json:"publisher,omitempty"`
	Capabilities   []string  `json:"capabilities"`
	ArtifactSHA256 string    `json:"artifact_sha256,omitempty"`
	BundlePath     string    `json:"bundle_path,omitempty"`
	Status         string    `json:"status"`
	VerifiedAt     time.Time `json:"verified_at,omitempty"`
	InstalledAt    time.Time `json:"installed_at,omitempty"`
	ActivatedAt    time.Time `json:"activated_at,omitempty"`
	DisabledAt     time.Time `json:"disabled_at,omitempty"`
	CreatedAt      time.Time `json:"created_at"`
	UpdatedAt      time.Time `json:"updated_at"`
}

PluginInstallation is the persisted lifecycle record for a verified plugin bundle. It is intentionally metadata-only: artifacts and runtime handles stay outside the shared API model.

type ProxyInbound added in v0.2.0 

type ProxyInbound struct {
	ID       string `json:"id"`
	Name     string `json:"name"`
	Core     string `json:"core"`
	Protocol string `json:"protocol"`
	Listen   string `json:"listen,omitempty"`
	Port     int    `json:"port"`

	Transport string `json:"transport,omitempty"`
	Path      string `json:"path,omitempty"`
	Host      string `json:"host,omitempty"`

	Security    string   `json:"security,omitempty"`
	SNI         string   `json:"sni,omitempty"`
	ALPN        []string `json:"alpn,omitempty"`
	Fingerprint string   `json:"fingerprint,omitempty"`

	CertPath string `json:"cert_path,omitempty"`
	KeyPath  string `json:"key_path,omitempty"`

	RealityPrivateKey string   `json:"reality_private_key,omitempty"`
	RealityPublicKey  string   `json:"reality_public_key,omitempty"`
	RealityShortIDs   []string `json:"reality_short_ids,omitempty"`
	RealityDest       string   `json:"reality_dest,omitempty"`

	SSMethod string `json:"ss_method,omitempty"`

	Enabled   bool      `json:"enabled"`
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

ProxyInbound is the central protocol/transport template that the server renders into node-local sing-box/xray config. RealityPrivateKey is a server-side secret and must never appear in API views or agent payloads.

type ProxyNodeProfile added in v0.2.0 

type ProxyNodeProfile struct {
	ID         string   `json:"id"`
	NodeID     string   `json:"node_id"`
	Core       string   `json:"core"`
	InboundIDs []string `json:"inbound_ids"`
	Hostname   string   `json:"hostname,omitempty"`
	ListenIP   string   `json:"listen_ip,omitempty"`

	ConfigPath string `json:"config_path,omitempty"`
	StatsAPI   string `json:"stats_api,omitempty"`

	AppliedSHA256 string    `json:"applied_sha256,omitempty"`
	LastApplyAt   time.Time `json:"last_apply_at,omitempty"`
	LastError     string    `json:"last_error,omitempty"`

	// Usage collector health is agent-reported and server persisted for
	// operator visibility. It is not client-editable policy and must not affect
	// the server's monotonic usage accounting.
	UsageCollectorSource      string    `json:"usage_collector_source,omitempty"`
	UsageCollectorStatus      string    `json:"usage_collector_status,omitempty"`
	UsageCollectorCheckedAt   time.Time `json:"usage_collector_checked_at,omitempty"`
	UsageCollectorLastOKAt    time.Time `json:"usage_collector_last_ok_at,omitempty"`
	UsageCollectorLastError   string    `json:"usage_collector_last_error,omitempty"`
	UsageCollectorLastErrorAt time.Time `json:"usage_collector_last_error_at,omitempty"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

ProxyNodeProfile binds the central proxy model to a single node. One profile exists per node; it is the unit rendered into a reviewed plan/apply task.

type ProxyUsageSnapshot added in v0.2.0 

type ProxyUsageSnapshot struct {
	NodeID        string           `json:"node_id"`
	At            time.Time        `json:"at"`
	CoreUptimeSec uint64           `json:"core_uptime_sec"`
	UserBytes     map[string]int64 `json:"user_bytes"`

	// Collector fields describe this collection attempt. They let the agent
	// report local collector errors without overwriting the previous accounting
	// baseline on the server.
	CollectorSource    string    `json:"collector_source,omitempty"` // file | http | future core transport
	CollectorStatus    string    `json:"collector_status,omitempty"` // ok | error
	CollectorError     string    `json:"collector_error,omitempty"`
	CollectorCheckedAt time.Time `json:"collector_checked_at,omitempty"`
}

ProxyUsageSnapshot is the last node-reported accounting snapshot. The server later diffs successive snapshots to advance ProxyUser.UsedBytes monotonically.

type ProxyUser added in v0.2.0 

type ProxyUser struct {
	ID      string `json:"id"`
	Name    string `json:"name"`
	Enabled bool   `json:"enabled"`

	UUID     string `json:"uuid,omitempty"`
	Password string `json:"password,omitempty"`
	SubToken string `json:"sub_token,omitempty"`

	InboundIDs        []string  `json:"inbound_ids,omitempty"`
	TrafficLimitBytes int64     `json:"traffic_limit_bytes,omitempty"`
	ExpiresAt         time.Time `json:"expires_at,omitempty"`

	UsedBytes  int64     `json:"used_bytes"`
	LastSeenAt time.Time `json:"last_seen_at,omitempty"`
	Status     string    `json:"status"`

	// Server-managed notification cursors. They prevent repeated quota/expiry
	// alerts after the operator has already been notified for the current limit
	// or expiry date.
	LastQuotaNotifiedKey  string `json:"last_quota_notified_key,omitempty"`
	LastExpiryNotifiedKey string `json:"last_expiry_notified_key,omitempty"`

	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
}

ProxyUser is a central subscriber identity. UUID, Password and SubToken are bearer credential material; they are encrypted at rest and only surfaced through one-time/admin rotation flows, never through list/read views.

type StaticObject 

type StaticObject struct {
	Bucket      string    `json:"bucket"`
	Path        string    `json:"path"`
	Content     string    `json:"content"`
	ContentType string    `json:"content_type"`
	Size        int       `json:"size"`
	UpdatedAt   time.Time `json:"updated_at"`
}

type StorageAccessToken added in v0.2.1 

type StorageAccessToken struct {
	ID         string    `json:"id"`
	Name       string    `json:"name"`
	TokenHash  string    `json:"token_hash,omitempty"`
	Kind       string    `json:"kind"`
	Access     string    `json:"access"`
	Buckets    []string  `json:"buckets,omitempty"`
	RevokedAt  time.Time `json:"revoked_at,omitempty"`
	LastUsedAt time.Time `json:"last_used_at,omitempty"`
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`
}

type StorageBinding added in v0.2.1 

type StorageBinding struct {
	ID         string    `json:"id"`
	Kind       string    `json:"kind"`
	Bucket     string    `json:"bucket"`
	Hostname   string    `json:"hostname"`
	PathPrefix string    `json:"path_prefix,omitempty"`
	Enabled    bool      `json:"enabled"`
	CreatedAt  time.Time `json:"created_at"`
	UpdatedAt  time.Time `json:"updated_at"`
}

type StorageBucket added in v0.2.1 

type StorageBucket struct {
	ID               string    `json:"id"`
	Kind             string    `json:"kind"`
	Name             string    `json:"name"`
	DisplayName      string    `json:"display_name,omitempty"`
	Description      string    `json:"description,omitempty"`
	IndexDocument    string    `json:"index_document,omitempty"`
	NotFoundDocument string    `json:"not_found_document,omitempty"`
	CreatedAt        time.Time `json:"created_at"`
	UpdatedAt        time.Time `json:"updated_at"`
}

type Task 

type Task struct {
	ID          string    `json:"id"`
	ApprovalID  string    `json:"approval_id,omitempty"`
	ActorID     string    `json:"actor_id"`
	TokenID     string    `json:"token_id"`
	Targets     []string  `json:"targets"`
	Interpreter string    `json:"interpreter"`
	Script      string    `json:"script"`
	TimeoutSec  int       `json:"timeout_sec"`
	OutputLimit int       `json:"output_limit"`
	Status      string    `json:"status"`
	LeaseID     string    `json:"lease_id,omitempty"`
	LeasedBy    string    `json:"leased_by,omitempty"`
	CreatedAt   time.Time `json:"created_at"`
	StartedAt   time.Time `json:"started_at,omitempty"`
	FinishedAt  time.Time `json:"finished_at,omitempty"`
}

type TaskResult 

type TaskResult struct {
	TaskID     string    `json:"task_id"`
	LeaseID    string    `json:"lease_id,omitempty"`
	NodeID     string    `json:"node_id"`
	ExitCode   int       `json:"exit_code"`
	Stdout     string    `json:"stdout"`
	Stderr     string    `json:"stderr"`
	Error      string    `json:"error"`
	StartedAt  time.Time `json:"started_at"`
	FinishedAt time.Time `json:"finished_at"`
}

type Token 

type Token struct {
	ID              string    `json:"id"`
	Name            string    `json:"name"`
	TokenHash       string    `json:"token_hash"`
	ActorID         string    `json:"actor_id"`
	Scopes          []string  `json:"scopes"`
	ServerAllowlist []string  `json:"server_allowlist"`
	RevokedAt       time.Time `json:"revoked_at,omitempty"`
	CreatedAt       time.Time `json:"created_at"`
}

type TunnelIngress added in v0.2.0 

type TunnelIngress struct {
	Hostname string `json:"hostname"`
	Service  string `json:"service"`
	Path     string `json:"path,omitempty"`
}

TunnelIngress maps a public hostname to a node-local service for a Cloudflare Tunnel. Service is a cloudflared service URL, e.g. http://localhost:8088, ssh://localhost:22, or the literal http_status:404.

type TunnelProfile added in v0.2.0 

type TunnelProfile struct {
	ID              string          `json:"id"`
	Name            string          `json:"name"`
	NodeID          string          `json:"node_id"`
	TunnelID        string          `json:"tunnel_id"`
	CredentialsFile string          `json:"credentials_file,omitempty"`
	Ingress         []TunnelIngress `json:"ingress"`
	CreatedAt       time.Time       `json:"created_at"`
	UpdatedAt       time.Time       `json:"updated_at"`
}

TunnelProfile describes a Cloudflare Tunnel deployed on a node. Credentials are node-local (CredentialsFile path); the server only stores the topology.

type User 

type User struct {
	ID                 string   `json:"id"`
	Username           string   `json:"username"`
	PasswordHash       string   `json:"password_hash"`
	Scopes             []string `json:"scopes"`
	TOTPEnabled        bool     `json:"totp_enabled"`
	TOTPSecret         string   `json:"totp_secret,omitempty"`
	RecoveryCodeHashes []string `json:"recovery_code_hashes,omitempty"`
	// LastTOTPStep is the highest RFC-6238 counter accepted for this user. A
	// successful verification must present a strictly greater step, which makes
	// each code single-use and prevents replay within the validity window.
	LastTOTPStep uint64 `json:"last_totp_step,omitempty"`
	// SecurityEpoch is bumped on password change, 2FA disable, or admin revoke.
	// Sessions carry the epoch at which they were minted; a session whose epoch
	// is older than the user's current epoch is rejected, so privilege-reducing
	// events invalidate all existing sessions.
	SecurityEpoch uint64    `json:"security_epoch,omitempty"`
	CreatedAt     time.Time `json:"created_at"`
}

type WorkerScript 

type WorkerScript struct {
	ID           string    `json:"id"`
	Name         string    `json:"name"`
	Source       string    `json:"source"`
	Capabilities []string  `json:"capabilities"`
	Public       bool      `json:"public"`
	UpdatedAt    time.Time `json:"updated_at"`
}

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.