Documentation
¶
Overview ¶
Package native implements every protocol-runtime route but the agent channel in the package itself. Responses are byte-compatible with the legacy handlers (internal/tests/protocolruntimecompat).
- The protocol templates (static data), and the administrator's diagnostic task history and task detail on the kernel's v2_agent_diagnostic_task table, adopted in place (kernel.storage.adopt:v2_agent_diagnostic_task). The kernel keeps writing that table (creating a task, the agents' polls and results).
- A node's protocols, their creation, update and deletion, on v2_node_protocol, adopted once the node credential split finalized it (kernel.storage.adopt:v2_node_protocol, a grant the kernel honours only then): its secret positions hold the placeholder and the secrets are the kernel's. The secrets an administrator types reach the package as sealed handles, which it passes to the kernel (PutSecretDocument); the kernel validates and stores them. A deletion retires what the kernel holds for the protocol (RetireProtocol). Until the lease adopts the table, these routes answer from the legacy handler.
- Node synchronization, Agent Control status and operations, and the administrator's agent list, monitoring data, task creation and command execution, through the kernel's KernelNodeOps (node.sync, agent.operation, agent.diagnostic and the agent session RPCs): the agents' connections are the kernel's. Without KernelNodeOps they stay legacy.
The agent channel (registration, heartbeat, task poll, result, monitor and the WebSocket) is kernel-owned: node credentials checked in the kernel, connections and reports in its memory (packages/protocol-runtime/control/service.go).
Index ¶
- Constants
- type AgentDiagnosticTask
- type CreateTaskRequest
- type ExecuteCommandRequest
- type ProtocolTemplate
- type Service
- func (s *Service) CreateProtocol(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) CreateTask(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) DeleteProtocol(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) DispatchAgentControlOperation(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) ExecuteCommand(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) GetAgentControl(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) GetDiagnosticTask(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) GetMonitor(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) GetProtocols(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) Handlers() map[string]pluginhostsdk.NativeHandler
- func (s *Service) ListAgents(ctx context.Context, _ pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) ListDiagnosticTasks(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) ProtocolTemplates(context.Context, pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) SyncNode(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
- func (s *Service) UpdateProtocol(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
Constants ¶
const ( ProtocolsRouteID = "protocol.admin.nodes.id.protocols.get" CreateProtocolRouteID = "protocol.admin.nodes.id.protocols.post" UpdateProtocolRouteID = "protocol.admin.nodes.id.protocols.protocol_id.put" DeleteProtocolRouteID = "protocol.admin.nodes.id.protocols.protocol_id.delete" SyncRouteID = "protocol.admin.nodes.id.sync.post" AgentControlRouteID = "protocol.admin.nodes.id.agent_control.get" AgentControlOpsRouteID = "protocol.admin.nodes.id.agent_control.operations.post" AgentListRouteID = "protocol.admin.agent.list.get" AgentMonitorRouteID = "protocol.admin.agent.monitor.get" AgentTasksCreateRouteID = "protocol.admin.agent.tasks.post" AgentExecuteRouteID = "protocol.admin.agent.execute.post" )
Route ids of the routes that need KernelNodeOps.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type AgentDiagnosticTask ¶
type AgentDiagnosticTask struct {
ID uint `gorm:"primaryKey" json:"id"`
TaskID string `gorm:"size:80;uniqueIndex" json:"task_id"`
NodeID uint `gorm:"index" json:"node_id"`
Action string `gorm:"size:40" json:"action"`
Params string `gorm:"type:text" json:"params,omitempty"`
Status string `gorm:"size:20;index" json:"status"`
Success bool `json:"success"`
Output string `gorm:"type:text" json:"output,omitempty"`
Error string `gorm:"type:text" json:"error,omitempty"`
DurationMS int64 `json:"duration_ms"`
CreatedAt time.Time `json:"created_at"`
UpdatedAt time.Time `json:"timestamp"`
}
AgentDiagnosticTask is a v2_agent_diagnostic_task row, as the kernel model declares it: a whitelisted diagnostic action an administrator sent to a node's agent, and the result the agent reported.
func (AgentDiagnosticTask) TableName ¶
func (AgentDiagnosticTask) TableName() string
TableName is the adopted kernel table.
type CreateTaskRequest ¶ added in v4.2.0
type CreateTaskRequest struct {
NodeID uint `json:"node_id" binding:"required"`
Type string `json:"type" binding:"required"`
Action string `json:"action" binding:"required"`
Params map[string]any `json:"params"`
Timeout int `json:"timeout"`
}
CreateTaskRequest is the kernel's handler.CreateTaskRequest; its name appears in binding errors.
type ExecuteCommandRequest ¶ added in v4.2.0
type ExecuteCommandRequest struct {
NodeID uint `json:"node_id" binding:"required"`
Action string `json:"action" binding:"required"`
Params map[string]any `json:"params"`
Timeout int `json:"timeout"`
}
ExecuteCommandRequest is the kernel's handler.ExecuteCommandRequest.
type ProtocolTemplate ¶
type ProtocolTemplate struct {
Type string `json:"type"`
Name string `json:"name"`
Description string `json:"description"`
DefaultPort int `json:"default_port"`
Settings string `json:"settings"`
TLS int `json:"tls"`
TLSSettings string `json:"tls_settings"`
Transport string `json:"transport"`
Reality string `json:"reality_settings"`
}
ProtocolTemplate is a quick-add protocol template, as the kernel's model.ProtocolTemplate declares it.
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 protocol routes
// legacy.
Leased func(ctx context.Context, name string) bool
// NodeOps is the kernel's KernelNodeOps; without it the routes that
// write protocols or reach agents 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) CreateProtocol ¶ added in v4.2.0
func (s *Service) CreateProtocol(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
CreateProtocol is POST /api/v2/admin/nodes/:id/protocols. The protocol is validated as the kernel validates it, inserted with its secret columns masked, and each column that carries a typed secret is stored by the kernel. A placeholder stands for nothing yet, so it is stored empty. A write that fails takes the protocol out again.
func (*Service) CreateTask ¶ added in v4.2.0
func (s *Service) CreateTask(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
CreateTask is POST /api/v2/admin/agent/tasks: one whitelisted diagnostic action for a node's agent (agent.diagnostic); the answer is the agent's acknowledgement and the task's row.
func (*Service) DeleteProtocol ¶ added in v4.2.0
func (s *Service) DeleteProtocol(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
DeleteProtocol is DELETE /api/v2/admin/nodes/:id/protocols/:protocol_id: the kernel retires what goes with the protocol (RetireProtocol), then the package deletes the row.
func (*Service) DispatchAgentControlOperation ¶ added in v4.2.0
func (s *Service) DispatchAgentControlOperation(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
DispatchAgentControlOperation is POST /api/v2/admin/nodes/:id/agent-control/operations: one bounded operation on the node's Agent Control stream (agent.operation); the answer is the operation sent and the agent's acknowledgement.
func (*Service) ExecuteCommand ¶ added in v4.2.0
func (s *Service) ExecuteCommand(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
ExecuteCommand is POST /api/v2/admin/agent/execute: CreateTask for a diagnostic action, without a type.
func (*Service) GetAgentControl ¶ added in v4.2.0
func (s *Service) GetAgentControl(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
GetAgentControl is GET /api/v2/admin/nodes/:id/agent-control: the node's Agent Control session and the last state its agent reported.
func (*Service) GetDiagnosticTask ¶
func (s *Service) GetDiagnosticTask(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
GetDiagnosticTask is GET /api/v2/admin/agent/tasks/:task_id.
func (*Service) GetMonitor ¶ added in v4.2.0
func (s *Service) GetMonitor(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
GetMonitor is GET /api/v2/admin/agent/monitor: the last monitor snapshot a node's WebSocket agent posted.
func (*Service) GetProtocols ¶ added in v4.2.0
func (s *Service) GetProtocols(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
GetProtocols is GET /api/v2/admin/nodes/:id/protocols: a node's protocols by sort order, their secrets masked.
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) ListAgents ¶ added in v4.2.0
func (s *Service) ListAgents(ctx context.Context, _ pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
ListAgents is GET /api/v2/admin/agent/list: the agents connected on the legacy WebSocket, as the kernel renders them.
func (*Service) ListDiagnosticTasks ¶
func (s *Service) ListDiagnosticTasks(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
ListDiagnosticTasks is GET /api/v2/admin/agent/tasks: the newest tasks, optionally of one node. node_id and limit are read as the legacy handler reads them, strconv.Atoi with errors as 0.
func (*Service) ProtocolTemplates ¶
func (s *Service) ProtocolTemplates(context.Context, pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
ProtocolTemplates is GET /api/v2/admin/protocol-templates.
func (*Service) SyncNode ¶ added in v4.2.0
func (s *Service) SyncNode(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
SyncNode is POST /api/v2/admin/nodes/:id/sync: the kernel rebuilds the node's desired configuration and pushes it to the node's agent on the Agent Control stream (node.sync, forced); the answer is the agent's acknowledgement, or, for a node on the legacy transports, that its next pull reads the configuration.
func (*Service) UpdateProtocol ¶ added in v4.2.0
func (s *Service) UpdateProtocol(ctx context.Context, request pluginhostsdk.NativeRequest) (pluginhostsdk.NativeResponse, error)
UpdateProtocol is PUT /api/v2/admin/nodes/:id/protocols/:protocol_id. The update is checked as the kernel checks it: its keys resolved to columns, the protocol's id and node never changed, the merged protocol validated. Its columns without secrets are written first; then each secret column it names is stored by the kernel, the settings validated with the typed secrets. A refusal there puts the columns back.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package model mirrors the kernel model types the protocol routes bind request bodies to, write and answer with: the same type names, fields and tags, in a package of the same name.
|
Package model mirrors the kernel model types the protocol routes bind request bodies to, write and answer with: the same type names, fields and tags, in a package of the same name. |