native

package
v4.2.1 Latest Latest
Warning

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

Go to latest
Published: Oct 12, 2026 License: MIT Imports: 21 Imported by: 0

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

View Source
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

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

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

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

ExecuteCommand is POST /api/v2/admin/agent/execute: CreateTask for a diagnostic action, without a type.

func (*Service) GetAgentControl added in v4.2.0

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

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

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

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

ProtocolTemplates is GET /api/v2/admin/protocol-templates.

func (*Service) SyncNode added in v4.2.0

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

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.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL