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 ¶ added in v0.1.2
func InitAlertBuffer(capacity int)
InitAlertBuffer creates the package-level alert ring buffer. Must be called once before RunForever.
func NewServerNotifier ¶ added in v0.1.2
NewServerNotifier creates a new ServerNotifier instance.
func Run ¶ added in v0.1.2
Run performs a single connection lifecycle: dial → register → ack → loops. Returns nil only when ctx is cancelled (clean shutdown).
func RunForever ¶ added in v0.1.2
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.1.2
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.1.2
func SetChatRunner(r ChatRunner)
SetChatRunner sets the global chat runner for remote chat sessions.
func SetConcurrencyLimiter ¶ added in v0.1.2
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.1.2
func SetDiagnoseRunner(r DiagnoseRunner)
SetDiagnoseRunner sets the global diagnose runner for remote sessions.
Types ¶
type ChatHandle ¶ added in v0.1.2
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.1.2
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.1.2
type ChatSessionOpts struct {
AllowShell bool
}
ChatSessionOpts configures a remote chat session.
type ConcurrencyLimiter ¶ added in v0.1.2
type ConcurrencyLimiter interface {
TrySem() bool
ReleaseSem()
}
ConcurrencyLimiter controls how many concurrent remote sessions can run. Typically implemented by diagnose.DiagnoseEngine (shared semaphore).
type Conn ¶ added in v0.1.2
type Conn struct {
// contains filtered or unexported fields
}
Conn manages one WebSocket connection to catpaw-server.
type DiagnoseRunner ¶ added in v0.1.2
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 ¶ added in v0.1.2
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.1.2
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.1.2
func NewRingBuffer(capacity int) *RingBuffer
func (*RingBuffer) Drain ¶ added in v0.1.2
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.1.2
func (r *RingBuffer) Len() int
Len returns the current number of events in the buffer.
func (*RingBuffer) Push ¶ added in v0.1.2
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 ¶ added in v0.1.2
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) Forward ¶ added in v0.1.2
func (n *ServerNotifier) Forward(event *types.Event) bool
func (*ServerNotifier) Name ¶ added in v0.1.2
func (n *ServerNotifier) Name() string
Source Files