SPB Git

Repository Public

catalog.go 9.1 KB 149 lines go

1package actions23import (4	"regexp"5	"strings"6)78const (9	Low      = "low"10	Medium   = "medium"11	High     = "high"12	Critical = "critical"13)1415// Lock scopes: at most one non-terminal action holds the lock of a target.16const (17	LockNode    = "node"18	LockService = "service"19	LockJob     = "job"20	LockNone    = "none"21)2223// Type is one entry of the catalog (docs/DESIGN-BRIEF.md §4).24type Type struct {25	Name        string26	Title       string27	Description string28	Criticality string29	TargetKinds []string // node | service | job | inference_server30	Params      Spec31	TimeoutS    int // maximum execution time on the agent32	LockScope   string33	// ServerSide types are executed by the orchestrator itself: no agent command is ever issued.34	ServerSide bool35	// Internal types are created by the platform only (job.run is created by POST /jobs).36	Internal bool37	// MaintenanceRelated types are allowed on a node in maintenance mode.38	MaintenanceRelated bool39	ExtraPermissions   []string40	Available          bool41	UnavailableReason  string42}4344// Permission required to request the type: actions.run.<criticality>.45func (t Type) Permission() string { return "actions.run." + t.Criticality }4647// Flags derived from the criticality, exactly as the design brief states:48// high and critical need a step-up; critical also needs a justification, the49// confirmation (target alias typed by the user, compared server-side) and the50// approval of a second person.51func (t Type) RequiresStepUp() bool        { return t.Criticality == High || t.Criticality == Critical }52func (t Type) RequiresJustification() bool { return t.Criticality == Critical }53func (t Type) RequiresConfirmation() bool  { return t.Criticality == Critical }54func (t Type) RequiresApproval() bool      { return t.Criticality == Critical }5556// Capability is what the agent must declare in agents.capabilities for the57// type to be dispatched. Job templates are declared as "job.run:<template>".58func (t Type) Capability(params map[string]any) string {59	if t.Name == "job.run" {60		tpl, _ := params["template"].(string)61		return JobCapability(tpl)62	}63	return t.Name64}6566const jobCapPrefix = "job.run:"6768// JobCapability is the capability string of a job template.69func JobCapability(template string) string { return jobCapPrefix + template }7071// TemplateOf extracts the template name from a capability string.72func TemplateOf(capability string) (string, bool) {73	t, ok := strings.CutPrefix(capability, jobCapPrefix)74	return t, ok && TemplateName.MatchString(t)75}7677var (78	logicalName = regexp.MustCompile(`^[a-z0-9][a-z0-9._-]{0,63}$`)79	// TemplateName is the shape of a job template name.80	TemplateName = regexp.MustCompile(`^[a-z0-9][a-z0-9._-]{0,63}$`)81	modelName    = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._/-]{0,127}$`)82)8384var none = Spec{Props: map[string]Prop{}}8586// Catalog lists every action type, in display order.87var Catalog = []Type{88	{Name: "inventory.refresh", Title: "Refresh inventory", Description: "Asks the agent for an immediate hardware and software inventory.",89		Criticality: Low, TargetKinds: []string{"node"}, Params: none, TimeoutS: 60, LockScope: LockNode, Available: true},90	{Name: "diagnostic.run", Title: "Run diagnostic", Description: "Bounded, read-only diagnostic collection.",91		Criticality: Low, TargetKinds: []string{"node"}, TimeoutS: 120, LockScope: LockNode, Available: true,92		Params: Spec{Props: map[string]Prop{"profile": {Type: "string", Enum: []string{"basic", "network", "disk"}, Description: "Diagnostic profile."}}, Required: []string{"profile"}}},93	{Name: "service.health_check", Title: "Check service health", Description: "Runs the health probe of a managed service.",94		Criticality: Low, TargetKinds: []string{"service"}, Params: none, TimeoutS: 30, LockScope: LockService, Available: true},95	{Name: "service.logs.tail", Title: "Tail service logs", Description: "Bounded, redacted read of the last log lines of a managed service (at most 500 lines and 256 KiB).",96		Criticality: Low, TargetKinds: []string{"service"}, TimeoutS: 30, LockScope: LockNone, Available: true, ExtraPermissions: []string{"logs.read"},97		Params: Spec{Props: map[string]Prop{"lines": {Type: "integer", Min: i64(1), Max: i64(500), Description: "Number of lines (default 200)."}}}},98	{Name: "service.restart", Title: "Restart service", Description: "Restarts a managed service through its manager.",99		Criticality: Medium, TargetKinds: []string{"service"}, Params: none, TimeoutS: 120, LockScope: LockService, Available: true},100	{Name: "service.start", Title: "Start service", Description: "Starts a managed service through its manager.",101		Criticality: Medium, TargetKinds: []string{"service"}, Params: none, TimeoutS: 120, LockScope: LockService, Available: true},102	{Name: "service.stop", Title: "Stop service", Description: "Stops a managed service through its manager.",103		Criticality: High, TargetKinds: []string{"service"}, Params: none, TimeoutS: 120, LockScope: LockService, Available: true},104	{Name: "agent.restart", Title: "Restart agent", Description: "Restarts the agent process on the node.",105		Criticality: Medium, TargetKinds: []string{"node"}, Params: none, TimeoutS: 60, LockScope: LockNode, Available: true},106	{Name: "cache.purge", Title: "Purge cache", Description: "Purges one logical cache from the agent's allowlist (a name, never a path).",107		Criticality: Medium, TargetKinds: []string{"node"}, TimeoutS: 300, LockScope: LockNode, Available: true,108		Params: Spec{Props: map[string]Prop{"cache": {Type: "string", Pattern: logicalName, MaxLen: 64, Description: "Logical cache name."}}, Required: []string{"cache"}}},109	{Name: "node.maintenance.set", Title: "Set maintenance mode", Description: "Turns the maintenance mode of a node on or off. Executed by the server; no command is sent to the agent.",110		Criticality: Medium, TargetKinds: []string{"node"}, TimeoutS: 30, LockScope: LockNode, Available: true, ServerSide: true, MaintenanceRelated: true,111		Params: Spec{Props: map[string]Prop{"enabled": {Type: "boolean", Description: "Target state."},112			"reason": {Type: "string", MaxLen: 500, Description: "Why (shown on the node)."}}, Required: []string{"enabled"}}},113	{Name: "job.run", Title: "Run job", Description: "One run of a job template declared by the agent. Created by POST /jobs only.",114		Criticality: Medium, TargetKinds: []string{"job"}, TimeoutS: 3600, LockScope: LockJob, Available: true, Internal: true,115		Params: Spec{Props: map[string]Prop{"template": {Type: "string", Pattern: TemplateName, MaxLen: 64},116			"params": {Type: "object", MaxBytes: 16 << 10, Description: "Template parameters, validated by the agent."}}, Required: []string{"template"}}},117	{Name: "job.cancel", Title: "Cancel job", Description: "Cancels a job. Executed by the server: a queued job is cancelled at once, a running one is asked to stop cooperatively through its job.run command.",118		Criticality: Medium, TargetKinds: []string{"job"}, Params: none, TimeoutS: 30, LockScope: LockNone, Available: true, ServerSide: true, MaintenanceRelated: true},119	{Name: "model.server.start", Title: "Start model server", Description: "Starts an inference server through the agent's adapter.",120		Criticality: High, TargetKinds: []string{"node"}, TimeoutS: 600, LockScope: LockNode, Available: true,121		Params: Spec{Props: map[string]Prop{"model": {Type: "string", Pattern: modelName, MaxLen: 128, Description: "Model name from the agent's allowlist."},122			"port":      {Type: "integer", Min: i64(1024), Max: i64(65535)},123			"mem_bytes": {Type: "integer", Min: i64(1), Max: i64(1 << 42), Description: "Estimated memory need; when given it is checked against the memory currently free on the node."}},124			Required: []string{"model"}}},125	{Name: "model.server.stop", Title: "Stop model server", Description: "Stops an inference server through the agent's adapter.",126		Criticality: High, TargetKinds: []string{"inference_server"}, Params: none, TimeoutS: 120, LockScope: LockNode, Available: true},127	{Name: "deploy.release", Title: "Deploy release", Description: "Deploys an approved version of a service.",128		Criticality: High, TargetKinds: []string{"service"}, Params: none, TimeoutS: 900, LockScope: LockService, Available: false,129		UnavailableReason: "Not enabled in this version."},130	{Name: "system.update.schedule", Title: "Schedule system update", Description: "Schedules an operating system update.",131		Criticality: High, TargetKinds: []string{"node"}, Params: none, TimeoutS: 300, LockScope: LockNode, Available: false,132		UnavailableReason: "Not enabled in this version."},133	{Name: "system.reboot", Title: "Reboot node", Description: "Reboots the node. Disabled locally on agents by default.",134		Criticality: Critical, TargetKinds: []string{"node"}, Params: none, TimeoutS: 600, LockScope: LockNode, Available: true},135	{Name: "system.shutdown", Title: "Shut down node", Description: "Shuts the node down. Disabled locally on agents by default.",136		Criticality: Critical, TargetKinds: []string{"node"}, Params: none, TimeoutS: 600, LockScope: LockNode, Available: true},137}138139var byName = func() map[string]Type {140	m := make(map[string]Type, len(Catalog))141	for _, t := range Catalog {142		m[t.Name] = t143	}144	return m145}()146147// Lookup returns a catalogued type.148func Lookup(name string) (Type, bool) { t, ok := byName[name]; return t, ok }149
Files main
Menu

Theme