event

package
v1.9.0 Latest Latest
Warning

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

 Go to latest Published: Jul 15, 2026 License: MIT Imports: 21 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func DescribePhase added in v1.4.8 

func DescribePhase(phase string) string

DescribePhase returns the human-readable description for an error_phase, or the raw identifier when the phase is unknown.

func GetCommandOutput added in v1.8.1 

func GetCommandOutput(ac *client.AlpaconClient, cmdID string) (string, error)

GetCommandOutput reconstructs the full command output from its chunks in seq order. Empty when no chunks were produced. Used by non-streaming paths (exec logs, polling fallback) where Result is empty under the chunk contract.

func IsAwaitingApprovalStatus added in v1.7.4 

func IsAwaitingApprovalStatus(status string) bool

IsAwaitingApprovalStatus reports whether status is the server's hold state for a command parked pending out-of-band human approval (HITL). The server exposes this via Command.compute_status when verification_status is "awaiting_approval" and the command has not yet been delivered to the agent.

func IsRunningStatus added in v1.5.0 

func IsRunningStatus(status string) bool

IsRunningStatus reports whether status represents an in-progress (non-terminal) command.

func RunCommandStreaming added in v1.8.1 

func RunCommandStreaming(ac *client.AlpaconClient, serverName, command, username, groupname string, env map[string]string, workSessionID string, out io.Writer) error

RunCommandStreaming runs a command and streams its output to out over the event WebSocket, falling back to polling (runCommandFallback) when WS setup fails.

func StreamApprovedCommand added in v1.8.1 

func StreamApprovedCommand(ac *client.AlpaconClient, cmdID string, out io.Writer, timeout time.Duration) error

StreamApprovedCommand resubscribes to an already-submitted command and streams its output, waiting through the awaiting_approval hold (bounded by timeout) until a reviewer approves it out of band and it runs. Used by --wait after a PendingApprovalError; the parked job produced no output yet, so resubscribing loses nothing.

func SubscribeCommandOutput added in v1.8.1 

func SubscribeCommandOutput(ac *client.AlpaconClient, channelID, commandID string) error

SubscribeCommandOutput subscribes the channel to command_output events for the given command (target_id scopes delivery to that command's chunks).

func SubscribeSudoEvent added in v1.4.0 

func SubscribeSudoEvent(ac *client.AlpaconClient, channelID, sessionID string) error

SubscribeSudoEvent subscribes the given channel to sudo events for a websh session.

Types

type Chunk added in v1.8.1 

type Chunk struct {
	Seq     int    `json:"seq"`
	Content string `json:"content"`
}

Chunk represents a single stdout/stderr chunk produced during command execution.

func GetCommandChunks added in v1.8.1 

func GetCommandChunks(ac *client.AlpaconClient, cmdID string, fromSeq int) ([]Chunk, error)

GetCommandChunks fetches chunks for cmdID with seq >= fromSeq, sorted by seq ascending. The streaming consumers rely on that order, so we sort defensively in case the server does not honor the ordering param.

type ChunkEvent added in v1.8.1 

type ChunkEvent struct {
	Seq     int
	Content string
}

ChunkEvent is a single command_output chunk emitted by the listener.

type ClientTimeoutError added in v1.4.8 

type ClientTimeoutError struct{}

ClientTimeoutError is returned when the CLI gave up polling for the command result before the server reported a terminal status.

func (*ClientTimeoutError) Error added in v1.4.8 

func (*ClientTimeoutError) Error() string

type CommandOutputListener added in v1.8.1 

type CommandOutputListener struct {
	// contains filtered or unexported fields
}

CommandOutputListener subscribes to a single command's chunk stream over the event WebSocket and exposes received chunks via the Chunks() channel.

Lifecycle: NewCommandOutputListener -> Start -> (consume Chunks) -> Stop. Stop is idempotent and safe to call from any goroutine.

func NewCommandOutputListener added in v1.8.1 

func NewCommandOutputListener(ac *client.AlpaconClient, wsURL, commandID string) *CommandOutputListener

NewCommandOutputListener constructs a listener without connecting. ac may be nil (empty header, for tests); commandID may be set later via setCommandID.

func (*CommandOutputListener) Chunks added in v1.8.1 

func (l *CommandOutputListener) Chunks() <-chan ChunkEvent

Chunks returns a receive-only channel of parsed chunk events.

func (*CommandOutputListener) Start added in v1.8.1 

func (l *CommandOutputListener) Start()

Start begins the WebSocket receive loop in a background goroutine. It automatically reconnects with exponential backoff until Stop() is called.

func (*CommandOutputListener) Stop added in v1.8.1 

func (l *CommandOutputListener) Stop()

Stop closes the listener; safe to call multiple times and from any goroutine.

func (*CommandOutputListener) WaitConnected added in v1.8.1 

func (l *CommandOutputListener) WaitConnected(timeout time.Duration) bool

WaitConnected blocks until the first successful WS connection is made or timeout / shutdown intervenes. Returns true on success.

type CommandRequest 

type CommandRequest struct {
	Shell       string            `json:"shell"`
	Line        string            `json:"line"`
	Env         map[string]string `json:"env"`
	Data        string            `json:"data"`
	Username    string            `json:"username"`
	Groupname   string            `json:"groupname"`
	ScheduledAt *time.Time        `json:"scheduled_at"`
	Server      string            `json:"server"`
	RunAfter    []string          `json:"run_after"`
	WorkSession string            `json:"work_session,omitempty"`
}

type CommandResponse 

type CommandResponse struct {
	ID          string              `json:"id"`
	Shell       string              `json:"shell"`
	Line        string              `json:"line"`
	Data        string              `json:"data"`
	Username    string              `json:"username"`
	Groupname   string              `json:"groupname"`
	AddedAt     time.Time           `json:"added_at"`
	ScheduledAt time.Time           `json:"scheduled_at"`
	Server      types.ServerSummary `json:"server"`
	RequestedBy types.UserSummary   `json:"requested_by"`
	RunAfter    []any               `json:"run_after"`
}

func SubmitCommand added in v1.5.0 

func SubmitCommand(ac *client.AlpaconClient, serverName, command string, username, groupname string, env map[string]string, workSessionID string) (CommandResponse, error)

type EventAttributes 

type EventAttributes struct {
	Server      string `json:"server"`
	Shell       string `json:"shell"`
	Command     string `json:"command"`
	Result      string `json:"result"`
	Status      string `json:"status"`
	Operator    string `json:"operator"`
	RequestedAt string `json:"requested_at" table:"Requested At"`
}

func GetEventList 

func GetEventList(ac *client.AlpaconClient, pageSize int, serverName string, userName string) ([]EventAttributes, error)

type EventDetails 

type EventDetails struct {
	ID            string              `json:"id"`
	Shell         string              `json:"shell"`
	Line          string              `json:"line"`
	Success       *bool               `json:"success"`
	ExitCode      *int                `json:"exit_code"`
	ErrorPhase    *string             `json:"error_phase"`
	Result        string              `json:"result"`
	Status        string              `json:"status"`
	Cancellable   bool                `json:"cancellable"`
	ResponseDelay float64             `json:"response_delay"`
	ElapsedTime   float64             `json:"elapsed_time"`
	AddedAt       time.Time           `json:"added_at"`
	Server        types.ServerSummary `json:"server"`
	RequestedBy   types.UserSummary   `json:"requested_by"`
}

func GetCommandByID added in v1.5.0 

func GetCommandByID(ac *client.AlpaconClient, cmdID string) (EventDetails, error)

func PollCommandExecution 

func PollCommandExecution(ac *client.AlpaconClient, cmdId string) (EventDetails, error)

PollCommandExecution polls with default timeout/tick; tests use pollCommandExecution directly.

type EventSessionResponse added in v1.4.0 

type EventSessionResponse struct {
	ID           string `json:"id"`
	WebsocketURL string `json:"websocket_url"`
	ChannelID    string `json:"channel_id"`
}

EventSessionResponse is returned when creating an event session.

func CreateEventSession added in v1.4.0 

func CreateEventSession(ac *client.AlpaconClient) (*EventSessionResponse, error)

CreateEventSession creates a new event session and returns the WebSocket URL and channel ID for subscribing to events.

type EventSubscriptionRequest added in v1.4.0 

type EventSubscriptionRequest struct {
	Channel   string `json:"channel"`
	EventType string `json:"event_type"`
	TargetID  string `json:"target_id"`
}

EventSubscriptionRequest is sent to subscribe to an event type.

type PendingApprovalError added in v1.7.4 

type PendingApprovalError struct {
	CommandID string
}

PendingApprovalError is returned when the server parked a command at the "awaiting_approval" status: the job was accepted but a human must approve it out of band in the Alpacon console before it runs. CommandID identifies the parked job so a --wait caller can poll it to completion—re-submitting would create a duplicate command (and a duplicate approval request).

func (*PendingApprovalError) Error added in v1.7.4 

func (*PendingApprovalError) Error() string

type RemoteCommandError added in v1.4.8 

type RemoteCommandError struct {
	Output     string
	ExitCode   int
	ErrorPhase string
}

RemoteCommandError is returned when the remote command completed but exited with a non-zero status. Callers populate ExitCode from the server response; errorFromDetails falls back to 1 when the server omits exit_code.

func (*RemoteCommandError) Error added in v1.4.8 

func (e *RemoteCommandError) Error() string

type SudoListener added in v1.4.0 

type SudoListener struct {
	// contains filtered or unexported fields
}

SudoListener listens for sudo MFA events on the event WebSocket and handles the browser-based MFA flow.

The AlpaconClient (ac) is shared with the terminal WebSocket goroutines. http.Client is concurrency-safe. Token refresh and grant verification are serialized by mfaMu so only one MFA flow runs at a time.

func NewSudoListener added in v1.4.0 

func NewSudoListener(ac *client.AlpaconClient, wsURL, serverName string) *SudoListener

NewSudoListener creates a SudoListener but does not connect yet.

func (*SudoListener) Start added in v1.4.0 

func (sl *SudoListener) Start()

Start begins listening for sudo MFA events in a background goroutine. It automatically reconnects on disconnection. Call Stop() to shut down.

func (*SudoListener) Stop added in v1.4.0 

func (sl *SudoListener) Stop()

Stop signals the listener to shut down and closes the WebSocket connection to unblock any pending ReadMessage call.

func (*SudoListener) WaitConnected added in v1.4.0 

func (sl *SudoListener) WaitConnected(timeout time.Duration) bool

WaitConnected blocks until the WebSocket connection is established or the timeout expires. Returns true if connected, false on timeout or shutdown.

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.