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 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 StreamCallback
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func InitAlertBuffer ¶ added in v0.12.0
func InitAlertBuffer(capacity int)
InitAlertBuffer creates the package-level alert ring buffer. Must be called once before RunForever.
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 ¶ added in v0.12.0
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 ¶ added in v0.13.0
func SetChatRunner(r ChatRunner)
SetChatRunner sets the global chat runner for remote chat sessions.
func SetConcurrencyLimiter ¶ added in v0.13.0
func SetConcurrencyLimiter(l ConcurrencyLimiter)
SetConcurrencyLimiter sets the global concurrency limiter for remote sessions. Must be called before any WebSocket connections are established.
func SetDiagnoseRunner ¶ added in v0.13.0
func SetDiagnoseRunner(r DiagnoseRunner)
SetDiagnoseRunner sets the global diagnose runner for remote sessions.
Types ¶
type ChatHandle ¶ added in v0.13.0
type ChatHandle interface {
HandleMessage(ctx context.Context, input string) (reply string, err error)
}
ChatHandle is a handle to an active chat session.
type ChatRunner ¶ added in v0.13.0
type ChatRunner interface {
NewSession(ctx context.Context, opts ChatSessionOpts, cb StreamCallback) (ChatHandle, error)
}
ChatRunner creates and manages remote chat sessions.
type ChatSessionOpts ¶ added in v0.13.0
type ChatSessionOpts struct {
AllowShell bool
}
ChatSessionOpts configures a remote chat session.
type ConcurrencyLimiter ¶ added in v0.13.0
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 ¶ added in v0.13.0
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 ¶ added in v0.12.0
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 ¶ added in v0.12.0
func NewRingBuffer(capacity int) *RingBuffer
func (*RingBuffer) Drain ¶ added in v0.12.0
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 ¶ added in v0.12.0
func (r *RingBuffer) Len() int
Len returns the current number of events in the buffer.
func (*RingBuffer) Push ¶ added in v0.12.0
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.
Source Files