Documentation
¶
Overview ¶
Package native implements the proxy-node package's v2 routes in the package itself, but for the node channel and three routes that need what no kernel contract offers yet. Legacy handlers and native routes share the rows, so a route can switch between them at any time, and the answers are byte-compatible with the legacy handlers (internal/tests/proxynodecompat).
- The load balancer list, detail, creation, update and deletion work on the kernel's v2_load_balancer table, adopted in place (kernel.storage.adopt). A load balancer's statistics read the forward nodes through kapi_forward_node_v1, and its health check is the kernel's (CheckEndpoints with record_status).
- A node's runtime logs come from the adopted v2_node_log table, which the kernel's agent control writes when nodes report logs.
- The node statistics, and whether a node exists, come from the kernel view kapi_node_status_v1: each node's id, status, last check and traffic counters.
- The node list, detail, deletion and raw configuration work on v2_node, which the package adopts once the node credential split finalized it (a grant the kernel honours only then): its API key, key hash and shared secret hold tombstones, and its raw configuration the placeholder at every secret position. A node's protocols are read through kapi_node_protocol_public_v1. A deletion retires what the kernel holds for the node (RetireNode); a raw configuration is stored by the kernel (PutSecretDocument), its typed secrets as sealed handles the package never resolves. Until the lease grants them, these routes answer from the legacy handler.
- Registration keys are the kernel's: listed through kapi_registration_key_v1 (never a key), issued and revoked through KernelNodeOps, a new key answered as a sealed handle.
The package never reads a node's credentials, and never reads or writes v2_node_protocol, which is protocol-runtime's. The other routes stay in the kernel; packages/proxy-node/control lists why for each.
Index ¶
- Constants
- Variables
- type ForwardNode
- type LoadBalancer
- type NodeLog
- type RegistrationKey
- type Service
- func (s *Service) CreateLoadBalancer(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) DeleteAuthKey(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) DeleteLoadBalancer(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) DeleteNode(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) GenerateAuthKey(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) GetLoadBalancer(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) GetNode(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) GetNodeLogs(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) GetNodeStats(ctx context.Context, _ pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) GetRawConfig(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) Handlers() map[string]pluginhostsdk.NativeHandler
- func (s *Service) InternalGenerateAuthKey(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) ListAuthKeys(ctx context.Context, _ pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) ListLoadBalancers(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) ListNodes(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) LoadBalancerStats(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) RunHealthCheck(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) UpdateLoadBalancer(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) UpdateRawConfig(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
Constants ¶
const ( NodesRouteID = "proxy.admin.nodes.get" NodeRouteID = "proxy.admin.nodes.id.get" DeleteNodeRouteID = "proxy.admin.nodes.id.delete" RawConfigRouteID = "proxy.admin.nodes.id.raw_config.get" UpdateRawConfigRouteID = "proxy.admin.nodes.id.raw_config.put" AuthKeysRouteID = "proxy.admin.auth_keys.get" GenerateAuthKeyRouteID = "proxy.admin.auth_keys.post" DeleteAuthKeyRouteID = "proxy.admin.auth_keys.id.delete" InternalAuthKeyRouteID = "proxy.internal.auth_keys.post" LoadBalancerStatsRouteID = "proxy.loadbalancer.id.stats.get" LoadBalancerCheckRouteID = "proxy.loadbalancer.id.check.post" )
Route ids of the native routes of M3-2.
const NodeSortTiebreaker = "id DESC"
NodeSortTiebreaker orders nodes that share a sorted value, so pages neither repeat nor skip a node.
Variables ¶
var NodeSortColumns = map[string]v2compat.SortColumn{ "id": {Expr: "id", Unique: true}, "name": {Expr: "name"}, "host": {Expr: "host"}, "sort": {Expr: "sort"}, "created_at": {Expr: "created_at"}, "last_check_at": {Expr: "last_check_at", Nullable: true}, "cpu_usage": {Expr: "cpu_usage"}, "online_users": {Expr: "online_users"}, }
NodeSortColumns are the columns the node list sorts by: the keys and the meaning of the kernel's service.NodeSortColumns. "sort" is the administrator's own order weight. A node's shown status is derived from its last check and its protocol count from another table, so neither is sortable; a node that never checked in (NULL last_check_at) sorts last ascending.
Functions ¶
This section is empty.
Types ¶
type ForwardNode ¶ added in v4.2.0
ForwardNode is the part of a kapi_forward_node_v1 row the statistics read.
func (ForwardNode) TableName ¶ added in v4.2.0
func (ForwardNode) TableName() string
TableName is the kernel view.
type LoadBalancer ¶
type LoadBalancer struct {
ID uint `gorm:"primaryKey"`
Name string `gorm:"size:100"`
GroupID uint `gorm:"index"`
Strategy string `gorm:"size:20;default:round-robin"`
HealthCheck bool `gorm:"default:true"`
CheckInterval int `gorm:"default:60"`
CheckTimeout int `gorm:"default:10"`
NodeWeights string `gorm:"type:text"`
Enabled bool `gorm:"default:true"`
CreatedAt time.Time
UpdatedAt time.Time
}
LoadBalancer is a v2_load_balancer row. Its column defaults are the kernel model's: GORM writes them for zero values on create, so a new load balancer always starts with health checks on and enabled.
func (LoadBalancer) TableName ¶
func (LoadBalancer) TableName() string
TableName is the adopted kernel table.
type NodeLog ¶
type NodeLog struct {
ID uint `gorm:"primaryKey"`
NodeID uint
Level string
Source string
Message string
TraceID string
FieldsJSON string
LoggedAt *time.Time
CreatedAt time.Time
UpdatedAt time.Time
}
NodeLog is a v2_node_log row: a runtime log line a node reported.
type RegistrationKey ¶ added in v4.2.0
type RegistrationKey struct {
ID uint
Name string
Used int
ExpireAt *int64
CreatedAt time.Time
UpdatedAt time.Time
HasKey bool
}
RegistrationKey is a row of kapi_registration_key_v1.
func (RegistrationKey) TableName ¶ added in v4.2.0
func (RegistrationKey) TableName() string
TableName is the kernel view.
type Service ¶
type Service struct {
// Open returns the package's storage connection, on which the adopted
// tables and the granted views are visible.
Open func(ctx context.Context) (*gorm.DB, error)
// Leased reports whether the package's storage lease adopts the kernel
// table, or grants the kernel view, called name
// (packagestoresdk.Store.Leased); nil leaves the node and registration
// key routes that need a conditional grant legacy.
Leased func(ctx context.Context, name string) bool
// NodeOps is the kernel's KernelNodeOps; without it the routes that
// need it stay legacy.
NodeOps kernelnodeopsv1.KernelNodeOpsClient
// Now defaults to time.Now.
Now func() time.Time
// NewToken names a request that carries neither an Idempotency-Key nor
// an X-Request-ID, in its operations' request ids; it defaults to a
// random UUID.
NewToken func() string
}
Service holds what the native routes need.
func (*Service) CreateLoadBalancer ¶
func (s *Service) CreateLoadBalancer(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
CreateLoadBalancer is POST /api/v2/admin/loadbalancers.
func (*Service) DeleteAuthKey ¶ added in v4.2.0
func (s *Service) DeleteAuthKey(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
DeleteAuthKey is DELETE /api/v2/admin/auth-keys/:id: the kernel revokes the key (RevokeRegistrationKey); a key that does not exist is nothing to do.
func (*Service) DeleteLoadBalancer ¶
func (s *Service) DeleteLoadBalancer(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
DeleteLoadBalancer is DELETE /api/v2/admin/loadbalancers/:id. Deleting a load balancer that does not exist succeeds, as in the kernel.
func (*Service) DeleteNode ¶ added in v4.2.0
func (s *Service) DeleteNode(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
DeleteNode is DELETE /api/v2/admin/nodes/:id: the kernel retires what goes with the node (RetireNode: its protocols with their peers, links and secrets, its credentials and agent certificates), then the package deletes the row.
func (*Service) GenerateAuthKey ¶ added in v4.2.0
func (s *Service) GenerateAuthKey(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
GenerateAuthKey is POST /api/v2/admin/auth-keys.
func (*Service) GetLoadBalancer ¶
func (s *Service) GetLoadBalancer(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
GetLoadBalancer is GET /api/v2/admin/loadbalancers/:id.
func (*Service) GetNode ¶ added in v4.2.0
func (s *Service) GetNode(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
GetNode is GET /api/v2/admin/nodes/:id: a node with its protocols, masked.
func (*Service) GetNodeLogs ¶
func (s *Service) GetNodeLogs(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
GetNodeLogs is GET /api/v2/admin/nodes/:id/logs: a node's runtime logs, newest first, filtered by level (normalized as the kernel stores it), source and a search in the message, source and trace id.
func (*Service) GetNodeStats ¶
func (s *Service) GetNodeStats(ctx context.Context, _ pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
GetNodeStats is GET /api/v2/admin/nodes/stats. A node is online when it checked in within five minutes, whatever its status; offline is what is neither online nor pending.
func (*Service) GetRawConfig ¶ added in v4.2.0
func (s *Service) GetRawConfig(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
GetRawConfig is GET /api/v2/admin/nodes/:id/raw-config: the node's raw configuration, its secrets masked; one that is not JSON is refused, as it would read as the placeholder alone.
func (*Service) Handlers ¶
func (s *Service) Handlers() map[string]pluginhostsdk.NativeHandler
Handlers returns the native handlers by route id. A host without KernelNodeOps has none for the routes that need it.
func (*Service) InternalGenerateAuthKey ¶ added in v4.2.0
func (s *Service) InternalGenerateAuthKey(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
InternalGenerateAuthKey is POST /api/v2/internal/auth-keys, for automation authenticated by an API token: its answer is not the panel envelope.
func (*Service) ListAuthKeys ¶ added in v4.2.0
func (s *Service) ListAuthKeys(ctx context.Context, _ pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
ListAuthKeys is GET /api/v2/admin/auth-keys: the registration keys, the newest first, each key as the placeholder.
func (*Service) ListLoadBalancers ¶
func (s *Service) ListLoadBalancers(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
ListLoadBalancers is GET /api/v2/admin/loadbalancers.
func (*Service) ListNodes ¶ added in v4.2.0
func (s *Service) ListNodes(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
ListNodes is GET /api/v2/admin/nodes: a page of nodes by sort order (or by the sort and order query, the columns of NodeSortColumns), filtered by status, group and a search in the name and host, each with its protocols, masked; a node's status shows whether it checked in recently, unless it is disabled.
func (*Service) LoadBalancerStats ¶ added in v4.2.0
func (s *Service) LoadBalancerStats(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
LoadBalancerStats is GET /api/v2/admin/loadbalancers/:id/stats: how many forward nodes there are and are online, and the online ones' average load and latency.
func (*Service) RunHealthCheck ¶ added in v4.2.0
func (s *Service) RunHealthCheck(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
RunHealthCheck is POST /api/v2/admin/loadbalancers/:id/check: with the load balancer's health checks on, the kernel checks every forward node's endpoint and records what it found on the node's row (CheckEndpoints with record_status), as the forward node check does.
func (*Service) UpdateLoadBalancer ¶
func (s *Service) UpdateLoadBalancer(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
UpdateLoadBalancer is PUT /api/v2/admin/loadbalancers/:id: the request applied to the stored row, which is then saved whole.
func (*Service) UpdateRawConfig ¶ added in v4.2.0
func (s *Service) UpdateRawConfig(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
UpdateRawConfig is PUT /api/v2/admin/nodes/:id/raw-config. The kernel stores the configuration (PutSecretDocument): the secrets an administrator types arrive as sealed handles, a placeholder keeps the stored secret, the configuration is validated with the secrets it holds, and the kernel's node cache forgets the node. Null clears it.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package model mirrors the kernel model types the node routes answer with: the same type names, fields and JSON tags, in a package of the same name, so the answers are the same bytes.
|
Package model mirrors the kernel model types the node routes answer with: the same type names, fields and JSON tags, in a package of the same name, so the answers are the same bytes. |