protocol

package

v0.6.4 Latest Latest Go to latest Published: May 23, 2026 License: MIT Imports: 1 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/smitt14ua/zeus

Links

Open Source Insights

Documentation ¶

Overview ¶

Package protocol defines the WebSocket message types shared between the zeus agent and any compatible web server implementation. It has no internal dependencies and can be extracted into its own module.

Index ¶

Constants
Variables
func Encode(msgType, id string, payload any) ([]byte, error)
func ResolveScopes(scopes []string) map[string]bool
type Command
type Envelope
type Event
type Heartbeat
type Hello
type ProfileStatus
type Result
type Stream

Constants ¶

View Source

const (
	TypeHello     = "hello"
	TypeHeartbeat = "heartbeat"
	TypeCommand   = "command"
	TypeStream    = "stream"
	TypeResult    = "result"
	TypeEvent     = "event"
	TypePing      = "ping"
	TypePong      = "pong"
)

Message types (Envelope.Type).

View Source

const (
	CmdProfileNew   = "profile.new"
	CmdProfileAdd   = "profile.add"
	CmdProfileList  = "profile.list"
	CmdProfileInfo  = "profile.info"
	CmdProfileStart = "profile.start"
	CmdProfileStop  = "profile.stop"
	CmdProfileRm    = "profile.rm"
	CmdMissionsPull = "missions.pull"
	CmdUpdate       = "update"
)

Command names (Command.Cmd).

View Source

const (
	EventProfileStarted = "profile.started"
	EventProfileStopped = "profile.stopped"
)

Event names (Event.Event).

View Source

const (
	FDStdout = "stdout"
	FDStderr = "stderr"
)

FD labels for Stream messages.

View Source

const (
	ScopeView    = "view"    // profile.list, profile.info (read-only)
	ScopeControl = "control" // profile.start, profile.stop
	ScopeManage  = "manage"  // profile.new, profile.add, profile.rm, missions.pull, profile.info (write operations)
	ScopeUpdate  = "update"  // update
	ScopeAll     = "all"     // no restrictions (default)
)

Scope names for the --allow flag on zeus agent. Scopes restrict which commands the agent will accept and execute.

Variables ¶

View Source

var AllScopes = []string{ScopeView, ScopeControl, ScopeManage, ScopeUpdate}

AllScopes is the ordered list of all named scopes (excluding "all").

Functions ¶

func Encode ¶

func Encode(msgType, id string, payload any) ([]byte, error)

Encode marshals a payload into an Envelope ready for sending.

func ResolveScopes ¶

func ResolveScopes(scopes []string) map[string]bool

ResolveScopes returns a set of allowed command names for the given scope list. Returns nil (allow everything) if scopes is empty or contains ScopeAll.

Types ¶

type Command ¶

type Command struct {
	Cmd  string         `json:"cmd"`
	Args map[string]any `json:"args,omitempty"`
}

Command is the payload for TypeCommand messages (server → agent).

type Envelope ¶

type Envelope struct {
	ID      string          `json:"id,omitempty"`
	Type    string          `json:"type"`
	Payload json.RawMessage `json:"payload"`
}

Envelope is the top-level wrapper for every message in both directions.

type Event ¶

type Event struct {
	Event  string `json:"event"`
	Name   string `json:"name,omitempty"`
	PID    int    `json:"pid,omitempty"`
	Reason string `json:"reason,omitempty"`
}

Event is the payload for TypeEvent messages (agent → server, spontaneous).

type Heartbeat ¶

type Heartbeat struct {
	Agent         string          `json:"agent"`
	ZeusVersion   string          `json:"zeus_version"`
	Profiles      []ProfileStatus `json:"profiles"`
	AllowedScopes []string        `json:"allowed_scopes,omitempty"` // nil/absent = all commands allowed
}

Heartbeat is the payload for TypeHeartbeat messages (agent → server, periodic).

type Hello ¶

type Hello struct {
	Agent         string   `json:"agent"`
	ZeusVersion   string   `json:"zeus_version"`
	AllowedScopes []string `json:"allowed_scopes,omitempty"` // nil/absent = all commands allowed
}

Hello is the payload for TypeHello messages (agent → server, sent on connect).

type ProfileStatus ¶

type ProfileStatus struct {
	Name    string `json:"name"`
	Running bool   `json:"running"`
	PID     int    `json:"pid,omitempty"`
}

ProfileStatus is the per-profile snapshot inside Heartbeat.

type Result ¶

type Result struct {
	Success  bool   `json:"success"`
	ExitCode int    `json:"exit_code"`
	Error    string `json:"error,omitempty"`
}

Result is the payload for TypeResult messages (agent → server). Sent once when a command finishes.

type Stream ¶

type Stream struct {
	Line string `json:"line"`
	FD   string `json:"fd"` // FDStdout or FDStderr
}

Stream is the payload for TypeStream messages (agent → server). One message per output line while a command is running.

Source Files ¶

View all Source files

messages.go

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