protocol

package
v0.19.0 Latest Latest
Warning

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

 Go to latest Published: Feb 25, 2026 License: MIT Imports: 7 Imported by: 0

Documentation

Overview

CRC: crc-MessageBatcher.md Spec: protocol.md

CRC: crc-ProtocolHandler.md Spec: protocol.md

Package protocol implements the Variable Protocol message handling. CRC: crc-ProtocolHandler.md Spec: protocol.md

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type BackendLookup 

type BackendLookup interface {
	// GetBackendForConnection returns the backend for a connection.
	// Returns nil if connection is not associated with a session.
	GetBackendForConnection(connectionID string) backend.Backend
}

BackendLookup provides per-connection backend lookup. Used by the protocol handler to route watch operations to the correct session's backend.

type BatchWrapper added in v0.16.0 

type BatchWrapper struct {
	UserEvent bool      `json:"userEvent"`
	Messages  []Message `json:"messages"`
}

BatchWrapper wraps a batch of messages with a userEvent flag. Spec: protocol.md - Frontend sends batches with userEvent flag for immediate/debounced response

type CreateMessage 

type CreateMessage struct {
	ID         int64             `json:"id"`
	ParentID   int64             `json:"parentId,omitempty"`
	Value      json.RawMessage   `json:"value,omitempty"`
	Properties map[string]string `json:"properties,omitempty"`
	NoWatch    bool              `json:"nowatch,omitempty"`
	Unbound    bool              `json:"unbound,omitempty"`
}

CreateMessage represents a create variable request. Spec: protocol.md - create(id, parentId, value, properties, nowatch?, unbound?)

type DestroyMessage 

type DestroyMessage struct {
	VarID int64 `json:"varId"`
}

DestroyMessage represents a destroy variable request.

type ErrorMessage 

type ErrorMessage struct {
	VarID       int64  `json:"varId,omitempty"`
	Code        string `json:"code"`        // One-word error code (e.g., "path-failure", "not-found", "unauthorized")
	Description string `json:"description"` // Human-readable error description
}

ErrorMessage represents an error response. Spec: protocol.md - error(varId, code, description)

type GetMessage 

type GetMessage struct {
	VarIDs []int64 `json:"varIds"`
}

GetMessage represents a get variables request.

type GetObjectsMessage 

type GetObjectsMessage struct {
	ObjIDs []int64 `json:"objIds"`
}

GetObjectsMessage represents a get objects by ID request.

type GetObjectsResponse 

type GetObjectsResponse struct {
	Objects []ObjectData `json:"objects"`
}

GetObjectsResponse contains object data.

type GetResponse 

type GetResponse struct {
	Variables []VariableData `json:"variables"`
}

GetResponse contains variable values.

type Handler 

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

Handler processes protocol messages.

func NewHandler 

func NewHandler(cfg *config.Config, sender MessageSender) *Handler

NewHandler creates a new protocol handler.

func (*Handler) HandleMessage 

func (h *Handler) HandleMessage(connectionID string, msg *Message) (*Response, error)

HandleMessage processes an incoming protocol message.

func (*Handler) Log 

func (h *Handler) Log(level int, format string, args ...interface{})

Log logs a message via the config.

func (*Handler) SendError 

func (h *Handler) SendError(connectionID string, varID int64, description string) error

SendError sends an error message to a connection.

func (*Handler) SetBackendLookup 

func (h *Handler) SetBackendLookup(lookup BackendLookup)

SetBackendLookup sets the backend lookup for per-session watch operations.

func (*Handler) SetPathVariableHandler 

func (h *Handler) SetPathVariableHandler(handler PathVariableHandler)

SetPathVariableHandler sets the handler for path-based frontend creates.

func (*Handler) SetPendingQueuer 

func (h *Handler) SetPendingQueuer(pending PendingQueuer)

SetPendingQueuer sets the pending queue manager.

type Message 

type Message struct {
	Type MessageType     `json:"type"`
	Data json.RawMessage `json:"data,omitempty"`
}

Message is the base protocol message structure.

func NewMessage 

func NewMessage(msgType MessageType, data interface{}) (*Message, error)

NewMessage creates a new message with the given type and data.

func ParseMessage 

func ParseMessage(data []byte) (*Message, error)

ParseMessage parses a raw JSON message into a typed message.

func ParseMessages added in v0.9.0 

func ParseMessages(data []byte) ([]*Message, bool, error)

ParseMessages parses raw JSON that may be a single message, batched array, or batch wrapper. Returns messages and userEvent flag (true if user-triggered, false otherwise). Spec: protocol.md - Messages can be sent individually or batched with userEvent flag

func (*Message) Encode 

func (m *Message) Encode() ([]byte, error)

Encode serializes a message to JSON.

type MessageBatcher 

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

MessageBatcher batches protocol messages by priority.

func NewMessageBatcher 

func NewMessageBatcher() *MessageBatcher

NewMessageBatcher creates a new message batcher.

func (*MessageBatcher) Flush 

func (b *MessageBatcher) Flush() []*Message

Flush builds and returns the batched messages, clearing pending state. Returns nil if no changes are pending.

func (*MessageBatcher) FlushJSON 

func (b *MessageBatcher) FlushJSON() ([]byte, error)

FlushJSON returns the batch as a JSON array or single message. Returns nil if no changes are pending.

func (*MessageBatcher) IsEmpty 

func (b *MessageBatcher) IsEmpty() bool

IsEmpty returns true if no changes are pending.

func (*MessageBatcher) QueueProperties 

func (b *MessageBatcher) QueueProperties(varID int64, properties map[string]string)

QueueProperties queues multiple property changes.

func (*MessageBatcher) QueueProperty 

func (b *MessageBatcher) QueueProperty(varID int64, propertyName, value string)

QueueProperty queues a property change. Property name can include priority suffix (e.g., "viewdefs:high").

func (*MessageBatcher) QueueValue 

func (b *MessageBatcher) QueueValue(varID int64, value json.RawMessage, priority Priority)

QueueValue queues a value change with the given priority.

type MessageSender 

type MessageSender interface {
	Send(connectionID string, msg *Message) error
	Broadcast(sessionID string, msg *Message) error
}

MessageSender is an interface for sending messages to a connection.

type MessageType 

type MessageType string

MessageType identifies the type of protocol message. 

const (
	// Relayed messages (frontend <-> UI server <-> backend)
	MsgCreate  MessageType = "create"
	MsgDestroy MessageType = "destroy"
	MsgUpdate  MessageType = "update"
	MsgWatch   MessageType = "watch"
	MsgUnwatch MessageType = "unwatch"

	// Server-response messages
	MsgError MessageType = "error"

	// UI server-handled messages (not relayed)
	MsgGet        MessageType = "get"
	MsgGetObjects MessageType = "getObjects"
	MsgPoll       MessageType = "poll"
)

type ObjectData 

type ObjectData struct {
	ID    int64           `json:"obj"`
	Value json.RawMessage `json:"value"`
}

ObjectData contains an object's data.

type PathVariableHandler 

type PathVariableHandler interface {
	// HandleFrontendCreate handles a path-based variable create from frontend.
	// The id is provided by the frontend (frontend-vended IDs).
	// Returns the resolved value and properties.
	HandleFrontendCreate(sessionID string, id int64, parentID int64, properties map[string]string) error

	// HandleFrontendUpdate handles an update to a path-based variable from frontend.
	// Updates the backend object via the variable's path and returns error if any.
	HandleFrontendUpdate(sessionID string, varID int64, value json.RawMessage, properties map[string]string) error
}

PathVariableHandler handles frontend-created path variables.

type PendingChange 

type PendingChange struct {
	VarID          int64
	Value          json.RawMessage
	ValuePriority  Priority
	HasValue       bool
	Properties     map[string]string   // property name -> value
	PropPriorities map[string]Priority // property name -> priority
}

PendingChange represents a queued change for a variable.

type PendingQueuer 

type PendingQueuer interface {
	Enqueue(connectionID string, msg *Message)
	Poll(connectionID string, wait time.Duration) []*Message
}

PendingQueuer is an interface for pending message queues.

type PollMessage 

type PollMessage struct {
	Wait string `json:"wait,omitempty"` // Duration string for long-polling
}

PollMessage represents a poll for pending responses request.

type Priority 

type Priority int

Priority levels for batching 

const (
	PriorityHigh   Priority = 0
	PriorityMedium Priority = 1
	PriorityLow    Priority = 2
)

func ParsePrioritySuffix 

func ParsePrioritySuffix(propertyName string) (string, Priority)

ParsePrioritySuffix extracts priority from property name suffix. Returns base property name and priority. Examples: "viewdefs:high" -> ("viewdefs", PriorityHigh) 

"name" -> ("name", PriorityMedium)

type Response 

type Response struct {
	Result interface{} `json:"result,omitempty"`
	Error  string      `json:"error,omitempty"`
}

Response wraps handler responses (primarily for error reporting).

type UpdateMessage 

type UpdateMessage struct {
	VarID      int64             `json:"varId"`
	Value      json.RawMessage   `json:"value,omitempty"`
	Properties map[string]string `json:"properties,omitempty"`
}

UpdateMessage represents an update variable request.

type VariableData 

type VariableData struct {
	ID         int64             `json:"id"`
	Value      json.RawMessage   `json:"value,omitempty"`
	Properties map[string]string `json:"properties,omitempty"`
}

VariableData contains a variable's data for get responses.

type WatchMessage 

type WatchMessage struct {
	VarID int64 `json:"varId"`
}

WatchMessage represents a watch/unwatch request.

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.