Documentation
¶
Overview ¶
session.go manages remote session state (sessionManager, remoteSession, ConcurrencyLimiter) and provides Conn methods for sending session-related messages to the Server (sendSessionOutput, sendSessionError, sendACK).
session_handler.go handles session_start / session_input / session_cancel messages from the Server and dispatches session execution (inspect, diagnose, chat).
Index ¶
- func InitAlertBuffer(capacity int)
- func NewServerNotifier() notify.Notifier
- func Run(ctx context.Context, startTime time.Time, plugins []string, ...) error
- func RunForever(ctx context.Context, startTime time.Time, plugins []string, ...)
- func SendAlertEvent(event *types.Event)
- func SetChatRunner(r ChatRunner)
- func SetConcurrencyLimiter(l ConcurrencyLimiter)
- func SetDiagnoseRunner(r DiagnoseRunner)
- type ChatHandle
- type ChatRunner
- type ChatSessionOpts
- type ConcurrencyLimiter
- type Conn
- type DiagnoseRunner
- type Message
- type RingBuffer
- type ServerNotifier
- type StreamCallback
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func InitAlertBuffer ¶
func InitAlertBuffer(capacity int)
InitAlertBuffer creates the package-level alert ring buffer. Must be called once before RunForever.
func NewServerNotifier ¶
NewServerNotifier creates a new ServerNotifier instance.
func Run ¶
Run performs a single connection lifecycle: dial → register → ack → loops. Returns nil only when ctx is cancelled (clean shutdown).
func RunForever ¶
RunForever wraps Run with reconnect logic. It blocks until ctx is cancelled. Backoff strategy per proto.md §7:
- Normal disconnect: 1s → 2s → ... → 300s, ±25% jitter
- Auth failure (401): 60s → 120s → ... → 1800s, ±25% jitter
func SendAlertEvent ¶
SendAlertEvent enqueues an alert event into the ring buffer. Safe to call even when the WebSocket connection is down. NOTE: the event pointer is stored as-is; callers must not reuse/mutate the Event after this call. The current engine always creates fresh Events.
func SetChatRunner ¶
func SetChatRunner(r ChatRunner)
SetChatRunner sets the global chat runner for remote chat sessions.
func SetConcurrencyLimiter ¶
func SetConcurrencyLimiter(l ConcurrencyLimiter)
SetConcurrencyLimiter sets the global concurrency limiter for remote sessions. Must be called before any WebSocket connections are established.
func SetDiagnoseRunner ¶
func SetDiagnoseRunner(r DiagnoseRunner)
SetDiagnoseRunner sets the global diagnose runner for remote sessions.
Types ¶
type ChatHandle ¶
type ChatHandle interface {
HandleMessage(ctx context.Context, input string) (reply string, err error)
}
ChatHandle is a handle to an active chat session.
type ChatRunner ¶
type ChatRunner interface {
NewSession(ctx context.Context, opts ChatSessionOpts, cb StreamCallback) (ChatHandle, error)
}
ChatRunner creates and manages remote chat sessions.
type ChatSessionOpts ¶
type ChatSessionOpts struct {
AllowShell bool
}
ChatSessionOpts configures a remote chat session.
type ConcurrencyLimiter ¶
type ConcurrencyLimiter interface {
TrySem() bool
ReleaseSem()
}
ConcurrencyLimiter controls how many concurrent remote sessions can run. Typically implemented by diagnose.DiagnoseEngine (shared semaphore).
type Conn ¶
type Conn struct {
// contains filtered or unexported fields
}
Conn manages one WebSocket connection to catpaw-server.
type DiagnoseRunner ¶
type DiagnoseRunner interface {
RunStreaming(ctx context.Context, mode, plugin, target string, params map[string]any, cb StreamCallback) (report string, err error)
}
DiagnoseRunner executes a streaming diagnosis. Implemented by diagnose.DiagnoseEngine.
type Message ¶
type Message struct {
Type string `json:"type"`
ID string `json:"id"`
RefID string `json:"ref_id,omitempty"`
Payload json.RawMessage `json:"payload,omitempty"`
}
Message is the protocol envelope for all Agent <-> Server communication.
type RingBuffer ¶
type RingBuffer struct {
// contains filtered or unexported fields
}
RingBuffer is a fixed-capacity circular buffer for alert events. When full, the oldest event is overwritten (best-effort semantics). It is safe for concurrent use.
func NewRingBuffer ¶
func NewRingBuffer(capacity int) *RingBuffer
func (*RingBuffer) Drain ¶
func (r *RingBuffer) Drain(maxItems int) []*types.Event
Drain removes and returns up to maxItems events from the buffer in FIFO order. Returns nil if the buffer is empty.
func (*RingBuffer) Len ¶
func (r *RingBuffer) Len() int
Len returns the current number of events in the buffer.
func (*RingBuffer) Push ¶
func (r *RingBuffer) Push(event *types.Event)
Push adds an event to the ring buffer. If the buffer is full, the oldest event is overwritten.
type ServerNotifier ¶
type ServerNotifier struct{}
ServerNotifier forwards alert events to the WebSocket server's ring buffer. Writing to the ring buffer is O(1) and never blocks, so it cannot affect other notifiers or the plugin engine.
func (*ServerNotifier) Name ¶
func (n *ServerNotifier) Name() string
Source Files