Help us shape the future of Go! Take the 2026 Go Developer Survey

ros

package
v0.20.0 Latest Latest
Warning

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

 Go to latest Published: Oct 27, 2026 License: MIT Imports: 10 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	ErrCodeUsageError              = "USAGE_ERROR"
	ErrCodeConfigError             = "CONFIG_ERROR"
	ErrCodeAuthFailed              = "AUTH_FAILED"
	ErrCodeNetworkError            = "NETWORK_ERROR"
	ErrCodeRosExecError            = "ROS_EXEC_ERROR"
	ErrCodeDangerousCommandBlocked = "DANGEROUS_COMMAND_BLOCKED"
	ErrCodeUnsupportedAction       = "UNSUPPORTED_ACTION"
	ErrCodeFileTooLarge            = "FILE_TOO_LARGE"
	ErrCodeFileTransferFailed      = "FILE_TRANSFER_FAILED"
	ErrCodeSchemaUnavailable       = "SCHEMA_UNAVAILABLE"
	ErrCodeInternalError           = "INTERNAL_ERROR"
)

Standard Error Codes matching roswire contract.

View Source 
const MaxScriptSourceBytes = 256 * 1024

MaxScriptSourceBytes is the maximum allowed size for uploaded script source files (256 KB).

Variables

This section is empty.

Functions

func BuildRouterOSCommand 

func BuildRouterOSCommand(req *ROSRequest) string

BuildRouterOSCommand formats the RouterOS CLI command line string to be executed over SSH.

func CommandDiagnostic added in v0.20.0 

func CommandDiagnostic(output string) bool

CommandDiagnostic recognizes device diagnostics, not arbitrary occurrences of the word error in user data. SSH exit status alone is insufficient on RouterOS.

func ParseRouterOSOutput 

func ParseRouterOSOutput(output string) (any, bool)

ParseRouterOSOutput attempts to parse RouterOS output into structured JSON-compatible data. If the output cannot be parsed into structured records, it returns nil and the original string.

func QuoteValue added in v0.20.0 

func QuoteValue(value string) string

QuoteValue encodes one literal RouterOS value, including script source. Raw commands bypass this encoder and retain their caller-owned syntax.

func ReadOnly added in v0.20.0 

func ReadOnly(req *ROSRequest) bool

ReadOnly recognizes only a single print invocation, never compound scripts or expression evaluation. A declaration is not proof of arbitrary raw purity.

func RenderCommandsJSON 

func RenderCommandsJSON() (string, error)

RenderCommandsJSON returns the JSON string for `commands`.

func RenderExplainErrorJSON 

func RenderExplainErrorJSON(code string) (string, error)

RenderExplainErrorJSON returns the JSON explanation for an error code.

func RenderHelpJSON 

func RenderHelpJSON(tokens []string) (string, error)

RenderHelpJSON returns the JSON string for `help` or `help <command>`.

func RenderSchemaJSON 

func RenderSchemaJSON(tokens []string) (string, error)

RenderSchemaJSON returns the JSON string for `schema <command>`.

func RenderWorkflowPlanJSON 

func RenderWorkflowPlanJSON(spec *WorkflowSpec) (string, error)

RenderWorkflowPlanJSON creates a dry-run plan for file/script workflows.

func WaitForRemoteFile 

func WaitForRemoteFile(sftpClient *sftp.Client, remotePath string, timeout time.Duration) error

WaitForRemoteFile polls remote path via SFTP until it exists or deadline is exceeded.

Types

type ActionKind 

type ActionKind string

ActionKind represents the semantic kind of a RouterOS action. 

const (
	ActionPrint  ActionKind = "print"
	ActionAdd    ActionKind = "add"
	ActionSet    ActionKind = "set"
	ActionRemove ActionKind = "remove"
	ActionRaw    ActionKind = "raw-routeros-command" //nolint:misspell // RouterOS domain constant
)

type ArgumentSpec 

type ArgumentSpec struct {
	Name        string `json:"name"`
	Style       string `json:"style"` // "key-value", "flag", "positional"
	Required    bool   `json:"required"`
	Type        string `json:"type"` // "string", "ip", "cidr", "int", "bool", etc.
	Description string `json:"description"`
	Example     string `json:"example,omitempty"`
}

ArgumentSpec defines one argument accepted by a RouterOS command.

type CommandMapping 

type CommandMapping struct {
	CLIPath      []string       `json:"cli_path"`
	Action       string         `json:"action"`
	ActionKind   ActionKind     `json:"action_kind"`
	RouterOSPath string         `json:"routeros_path"` //nolint:misspell // RouterOS domain field
	SideEffects  []string       `json:"side_effects"`
	Idempotency  string         `json:"idempotency"` // "read-only", "idempotent", "not-idempotent"
	Summary      string         `json:"summary"`
	Arguments    []ArgumentSpec `json:"arguments,omitempty"`
	Examples     []string       `json:"examples,omitempty"`
}

CommandMapping specifies the canonical definition of a statically supported RouterOS command.

func AllCommands 

func AllCommands() []CommandMapping

AllCommands returns the complete slice of statically registered commands.

func LookupCommand 

func LookupCommand(path []string, action string) (*CommandMapping, bool)

LookupCommand searches for a matching static command mapping.

func (*CommandMapping) IsRaw 

func (m *CommandMapping) IsRaw() bool

type CommandSummary 

type CommandSummary struct {
	Name    string `json:"name"`
	Summary string `json:"summary"`
	Kind    string `json:"kind"`
}

type CommandsPayload 

type CommandsPayload struct {
	SchemaVersion string           `json:"schema_version"`
	Commands      []CommandSummary `json:"commands"`
}

CommandsPayload mirrors roswire.commands.v1 schema.

type DoctorPayload 

type DoctorPayload struct {
	SchemaVersion    string        `json:"schema_version"`
	Local            LocalDoctor   `json:"local"`
	Remote           *RemoteDoctor `json:"remote,omitempty"`
	SelectedProtocol string        `json:"selected_protocol"`
	RouterOSVersion  string        `json:"routeros_version,omitempty"` //nolint:misspell // RouterOS domain field
	Warnings         []string      `json:"warnings"`
}

DoctorPayload mirrors roswire.doctor.v1 schema.

type ExplainErrorPayload 

type ExplainErrorPayload struct {
	SchemaVersion      string   `json:"schema_version"`
	ErrorCode          string   `json:"error_code"`
	Summary            string   `json:"summary"`
	CommonCauses       []string `json:"common_causes"`
	SuggestedNextSteps []string `json:"suggested_next_steps"`
}

ExplainErrorPayload mirrors roswire.explain_error.v1 schema.

type HelpCommandPayload 

type HelpCommandPayload struct {
	SchemaVersion string         `json:"schema_version"`
	Command       CommandMapping `json:"command"`
}

HelpCommandPayload mirrors roswire.help.command.v1 schema.

type HelpIndexPayload 

type HelpIndexPayload struct {
	SchemaVersion string           `json:"schema_version"`
	GlobalOptions []string         `json:"global_options"`
	Commands      []CommandSummary `json:"commands"`
}

HelpIndexPayload mirrors roswire.help.index.v1 schema.

type LocalDoctor 

type LocalDoctor struct {
	HomeExists    bool              `json:"home_exists"`
	ConfigExists  bool              `json:"config_exists"`
	PermissionsOK bool              `json:"permissions_ok"`
	SSHKeysFound  []string          `json:"ssh_keys_found,omitempty"`
	Dependencies  map[string]string `json:"dependencies"`
	Warnings      []string          `json:"warnings"`
}

type ROSContext 

type ROSContext struct {
	Command      string            `json:"command"`
	Path         []string          `json:"path,omitempty"`
	Action       string            `json:"action,omitempty"`
	Host         string            `json:"host,omitempty"`
	ResolvedArgs map[string]string `json:"resolved_args,omitempty"`
}

ROSContext captures the contextual parameters for structured error reporting.

type ROSErr 

type ROSErr struct {
	ErrorCode string     `json:"error_code"`
	Message   string     `json:"message"`
	Hint      string     `json:"hint,omitempty"`
	Context   ROSContext `json:"context"`
	ExitCode  int        `json:"-"`
}

ROSErr represents a structured RouterOS error adhering to the roswire JSON contract.

func NewConfigError 

func NewConfigError(msg string, hint string) *ROSErr

NewConfigError creates a configuration error.

func NewDangerousCommandError 

func NewDangerousCommandError(command, reason, hint string) *ROSErr

NewDangerousCommandError creates a safety guardrail error.

func NewUsageError 

func NewUsageError(msg string, hint string) *ROSErr

NewUsageError creates a usage-level error.

func ValidateSafety 

func ValidateSafety(req *ROSRequest, allowWrite bool, force bool) *ROSErr

ValidateSafety checks whether a RouterOS command is dangerous or requires mutation confirmation.

func ValidateScriptSource 

func ValidateScriptSource(content []byte, sourcePath string) *ROSErr

ValidateScriptSource checks size and UTF-8 validity of script contents.

func (*ROSErr) Error 

func (e *ROSErr) Error() string

func (*ROSErr) ToJSON 

func (e *ROSErr) ToJSON() string

ToJSON returns the formatted JSON string for the error.

type ROSPlan 

type ROSPlan struct {
	RawCommand         string            `json:"raw_command,omitempty"`
	SchemaVersion      string            `json:"schema_version"`
	DryRun             bool              `json:"dry_run"`
	Command            string            `json:"command"`
	RouterOSPath       string            `json:"routeros_path"` //nolint:misspell // RouterOS domain field
	Action             string            `json:"action"`
	ResolvedArgs       map[string]string `json:"resolved_args"`
	Flags              []string          `json:"flags"`
	SideEffects        []string          `json:"side_effects"`
	Idempotency        string            `json:"idempotency"`
	WillConnect        bool              `json:"will_connect"`
	WillModifyRouterOS bool              `json:"will_modify_routeros"` //nolint:misspell // RouterOS domain field
}

ROSPlan is the execution plan emitted for dry-run preview.

type ROSRequest 

type ROSRequest struct {
	Path         []string          `json:"path"`
	Action       string            `json:"action"`
	Args         map[string]string `json:"args"`
	Flags        []string          `json:"flags"`
	RawCommand   string            `json:"raw_command,omitempty"`
	Mapping      *CommandMapping   `json:"mapping,omitempty"`
	WorkflowName string            `json:"workflow_name,omitempty"`
}

ROSRequest contains the parsed RouterOS command invocation.

func ParseInvocation 

func ParseInvocation(tokens []string) (*ROSRequest, error)

ParseInvocation processes raw CLI tokens into a ROSRequest.

type RemoteDoctor 

type RemoteDoctor struct {
	Status          string   `json:"status"`
	RouterOSVersion string   `json:"routeros_version,omitempty"` //nolint:misspell // RouterOS domain field
	Architecture    string   `json:"architecture,omitempty"`
	BoardName       string   `json:"board_name,omitempty"`
	Uptime          string   `json:"uptime,omitempty"`
	Warnings        []string `json:"warnings"`
}

type SchemaPayload 

type SchemaPayload struct {
	SchemaVersion string         `json:"schema_version"`
	Command       string         `json:"command"`
	Arguments     []ArgumentSpec `json:"arguments"`
}

SchemaPayload mirrors roswire.schema.v1 schema.

type WorkflowSpec 

type WorkflowSpec struct {
	Type       WorkflowType `json:"type"`
	LocalPath  string       `json:"local_path,omitempty"`
	RemotePath string       `json:"remote_path,omitempty"`
	ScriptName string       `json:"script_name,omitempty"`
	BackupName string       `json:"backup_name,omitempty"`
	Compact    bool         `json:"compact,omitempty"`
	Cleanup    bool         `json:"cleanup,omitempty"`
}

WorkflowSpec defines the parameters for a workflow execution.

func ParseWorkflowCommand 

func ParseWorkflowCommand(tokens []string, sourceFlag string) (*WorkflowSpec, bool)

ParseWorkflowCommand detects if the CLI tokens form a workflow command.

type WorkflowType 

type WorkflowType string

WorkflowType identifies the kind of RouterOS file/script workflow. 

const (
	WorkflowFileUpload     WorkflowType = "file_upload"
	WorkflowFileDownload   WorkflowType = "file_download"
	WorkflowFileList       WorkflowType = "file_list"
	WorkflowScriptPut      WorkflowType = "script_put"
	WorkflowImport         WorkflowType = "import"
	WorkflowExportDownload WorkflowType = "export_download"
	WorkflowBackupDownload WorkflowType = "backup_download"
)

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.