Documentation
¶
Overview ¶
Package protocol provides envelope structs and SDK functions for the Sequify WebSocket protocol.
Package protocol provides payload structs for all 10 protocol methods.
Index ¶
- func IsNonPersistent(kind string) bool
- func NeedsMsgID(kind string) bool
- func ValidateRequest(req *Request) error
- func ValidateResponse(resp *Response) error
- func ValidateUpdate(u *Update) error
- func ValidateUpdates(u *Updates) error
- type CancelPayload
- type ConversationMeta
- type CreateConversationPayload
- type DestroyConversationPayload
- type Direction
- type EditMessagePayload
- type FetchUpdatesPayload
- type FetchUpdatesResponse
- type GetMaxSeqPayload
- type GetMaxSeqResponse
- type IntentPayload
- type ListConversationsPayload
- type ListConversationsResponse
- type MaxSeqChannel
- type MethodConfig
- type ParseResult
- type ReadReceiptPayload
- type Request
- type RequestBuilder
- type Response
- type ResponseBuilder
- type ResultPayload
- type Router
- type SwitchConversationPayload
- type ToolCallPayload
- type Update
- func FillGaps(updates []Update, fromSeq, toSeq uint64) []Update
- func NewConversationCreatedUpdate(seq uint64, payload []byte) Update
- func NewConversationDestroyedUpdate(seq uint64, payload []byte) Update
- func NewConversationSwitchedUpdate(seq uint64, payload []byte) Update
- func NewErrorUpdate(seq uint64, payload []byte) Update
- func NewReadReceiptUpdate(seq uint64, payload []byte) Update
- func NewReplyUpdate(seq uint64, payload []byte) Update
- func NewResultUpdate(seq uint64, payload []byte) Update
- func NewRetryUpdate(payload []byte) Update
- func NewStreamingUpdate(payload []byte) Update
- func NewToolCallUpdate(seq uint64, payload []byte) Update
- func NewTypingUpdate(payload []byte) Update
- type Updates
- type UpdatesBuilder
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsNonPersistent ¶
IsNonPersistent reports whether the given update kind is non-persistent (seq=0, skipped during gap fill). Returns true for typing, retry, and streaming. Returns false for all persistent kinds.
func NeedsMsgID ¶
NeedsMsgID reports whether the given update kind requires a message ID for seq allocation. Returns true for tool_call, result, reply, error (persistent updates tied to messages). Returns false for read_receipt, conversation_created, conversation_destroyed, conversation_switched, typing, retry.
func ValidateRequest ¶
ValidateRequest checks that a Request has a non-empty ID (within max length) and a valid method.
func ValidateResponse ¶
ValidateResponse checks that a Response has a non-empty ID, valid code, and non-empty message.
func ValidateUpdate ¶
ValidateUpdate checks that an Update has a valid kind and that non-persistent kinds (typing, retry, streaming) have seq == 0.
func ValidateUpdates ¶
ValidateUpdates checks that an Updates envelope contains at least one Update and does not exceed the maximum batch size.
Types ¶
type CancelPayload ¶
type CancelPayload struct {
ConversationID string `json:"conversation_id" validate:"required"`
}
CancelPayload is the payload for cancel method.
type ConversationMeta ¶
type ConversationMeta struct {
ID string `json:"id"`
Title string `json:"title"`
CreatedAt int64 `json:"created_at"` // milliseconds
LastMessageAt int64 `json:"last_message_at"` // milliseconds
ReadMsgID uint64 `json:"read_msg_id"`
LastMessageID uint64 `json:"last_message_id"`
}
ConversationMeta is a conversation summary for list_conversations response.
type CreateConversationPayload ¶
type CreateConversationPayload struct {
Title string `json:"title,omitempty"`
}
CreateConversationPayload is the payload for create_conversation method.
type DestroyConversationPayload ¶
type DestroyConversationPayload struct {
ConversationID string `json:"conversation_id" validate:"required"`
}
DestroyConversationPayload is the payload for destroy_conversation method.
type Direction ¶
type Direction string
Direction indicates whether a method is initiated by client or server.
type EditMessagePayload ¶
type EditMessagePayload struct {
ConversationID string `json:"conversation_id" validate:"required"`
MessageID uint64 `json:"message_id" validate:"required"`
Content string `json:"content" validate:"required"`
}
EditMessagePayload is the payload for edit_message method.
type FetchUpdatesPayload ¶
type FetchUpdatesPayload struct {
FromSeq uint64 `json:"from_seq" validate:"required"`
ToSeq uint64 `json:"to_seq" validate:"required"`
}
FetchUpdatesPayload is the payload for fetch_updates method.
type FetchUpdatesResponse ¶
type FetchUpdatesResponse struct {
Updates []Update `json:"updates"`
MaxSeq uint64 `json:"max_seq"`
}
FetchUpdatesResponse is the response payload for fetch_updates method.
type GetMaxSeqPayload ¶
type GetMaxSeqPayload struct{}
GetMaxSeqPayload is the payload for get_max_seq method (no request params).
type GetMaxSeqResponse ¶
type GetMaxSeqResponse struct {
Channels []MaxSeqChannel `json:"channels"`
}
GetMaxSeqResponse is the response payload for get_max_seq method.
type IntentPayload ¶
type IntentPayload struct {
ConversationID string `json:"conversation_id" validate:"required"`
Content string `json:"content" validate:"required"`
Context json.RawMessage `json:"context,omitempty"`
IdempotencyKey string `json:"idempotency_key,omitempty"`
}
IntentPayload is the payload for intent method.
type ListConversationsPayload ¶
type ListConversationsPayload struct {
Cursor string `json:"cursor,omitempty"` // composite cursor: "{last_message_at_ms}_{id}"
Limit int `json:"limit,omitempty"` // default 20, max 100
}
ListConversationsPayload is the payload for list_conversations method.
type ListConversationsResponse ¶
type ListConversationsResponse struct {
Conversations []ConversationMeta `json:"conversations"`
NextCursor string `json:"next_cursor,omitempty"` // empty = no more
}
ListConversationsResponse is the response for list_conversations method.
type MaxSeqChannel ¶
MaxSeqChannel represents a channel's current max sequence number.
type MethodConfig ¶
MethodConfig holds metadata for a registered protocol method.
type ParseResult ¶
type ParseResult struct {
// contains filtered or unexported fields
}
ParseResult holds the raw bytes and type of a parsed protocol message. The actual unmarshaling into Request/Response/Updates is deferred until the corresponding As*() method is called.
IMPORTANT: The raw bytes are NOT copied. The caller must ensure that the input data slice remains valid and unmodified for the lifetime of the ParseResult. If the data may be modified or reused, the caller should copy it before passing to Parse().
func Parse ¶
func Parse(data []byte) (*ParseResult, error)
Parse decodes the message type from data without fully unmarshaling the payload. It rejects messages larger than 1MB, invalid JSON, and missing type fields.
Design note: This function performs a lightweight unmarshal to extract only the type and version fields. The full unmarshal is deferred to AsRequest/AsResponse/AsUpdates. This two-phase approach is intentional: it allows early rejection of invalid messages before committing to the full unmarshal cost. The double unmarshal overhead is acceptable because (1) the initial peek only extracts two fields, and (2) it enables streaming scenarios where we need to route messages by type before full parsing.
func (*ParseResult) AsRequest ¶
func (r *ParseResult) AsRequest() (*Request, error)
AsRequest unmarshals the raw data into a Request struct. Returns an error if the message type is not "Request".
func (*ParseResult) AsResponse ¶
func (r *ParseResult) AsResponse() (*Response, error)
AsResponse unmarshals the raw data into a Response struct. Returns an error if the message type is not "Response".
func (*ParseResult) AsUpdates ¶
func (r *ParseResult) AsUpdates() (*Updates, error)
AsUpdates unmarshals the raw data into an Updates struct. Returns an error if the message type is not "Updates".
func (*ParseResult) Type ¶
func (r *ParseResult) Type() string
Type returns the message type string ("Request", "Response", or "Updates").
type ReadReceiptPayload ¶
type ReadReceiptPayload struct {
ConversationID string `json:"conversation_id" validate:"required"`
MessageID uint64 `json:"message_id" validate:"required"`
Timestamp int64 `json:"timestamp"` // server-set, milliseconds
}
ReadReceiptPayload is the payload for read_receipt method.
type Request ¶
type Request struct {
Type string `json:"type"`
Version int `json:"version"`
ID string `json:"id"`
Method string `json:"method"`
Payload json.RawMessage `json:"payload"`
}
Request represents a request message envelope.
type RequestBuilder ¶
type RequestBuilder struct {
// contains filtered or unexported fields
}
RequestBuilder provides a fluent API for constructing Request messages.
func NewRequest ¶
func NewRequest(method string) *RequestBuilder
NewRequest creates a new RequestBuilder for the given method. The default payload is an empty JSON object (not null).
func (*RequestBuilder) Build ¶
func (b *RequestBuilder) Build() *Request
Build returns the constructed Request.
func (*RequestBuilder) ID ¶
func (b *RequestBuilder) ID(id string) *RequestBuilder
ID sets the request ID.
func (*RequestBuilder) Marshal ¶
func (b *RequestBuilder) Marshal() ([]byte, error)
Marshal serializes the Request to JSON bytes.
func (*RequestBuilder) Payload ¶
func (b *RequestBuilder) Payload(p []byte) *RequestBuilder
Payload sets the request payload.
type Response ¶
type Response struct {
Type string `json:"type"`
Version int `json:"version"`
ID string `json:"id"`
Code int `json:"code"`
Message string `json:"message"`
Payload json.RawMessage `json:"payload,omitempty"`
Updates []Update `json:"updates,omitempty"`
}
Response represents a response message envelope.
type ResponseBuilder ¶
type ResponseBuilder struct {
// contains filtered or unexported fields
}
ResponseBuilder provides a fluent API for constructing Response messages.
func NewResponse ¶
func NewResponse(id string, code int, message string) *ResponseBuilder
NewResponse creates a new ResponseBuilder with the given id, code, and message.
func (*ResponseBuilder) Build ¶
func (b *ResponseBuilder) Build() *Response
Build returns the constructed Response.
func (*ResponseBuilder) Marshal ¶
func (b *ResponseBuilder) Marshal() ([]byte, error)
Marshal serializes the Response to JSON bytes.
func (*ResponseBuilder) Payload ¶
func (b *ResponseBuilder) Payload(p []byte) *ResponseBuilder
Payload sets the response payload.
func (*ResponseBuilder) Updates ¶
func (b *ResponseBuilder) Updates(updates []Update) *ResponseBuilder
Updates sets the response updates.
type ResultPayload ¶
type ResultPayload struct {
RequestID string `json:"request_id" validate:"required"`
Result json.RawMessage `json:"result" validate:"required"`
}
ResultPayload is the payload for result method (client -> server).
type Router ¶
type Router struct {
// contains filtered or unexported fields
}
Router maps protocol method strings to their MethodConfig.
func NewRouter ¶
func NewRouter() *Router
NewRouter creates a Router with all 14 protocol methods registered.
func (*Router) Get ¶
func (r *Router) Get(method string) (MethodConfig, bool)
Get returns the MethodConfig for the given method string. Returns false if the method is not registered.
func (*Router) ListByDirection ¶
ListByDirection returns method strings that match the given direction.
func (*Router) PayloadType ¶
PayloadType returns the reflect.Type for the method's payload. Returns nil if the method is not registered.
type SwitchConversationPayload ¶
type SwitchConversationPayload struct {
ConversationID string `json:"conversation_id" validate:"required"`
}
SwitchConversationPayload is the payload for switch_conversation method.
type ToolCallPayload ¶
type ToolCallPayload struct {
RequestID string `json:"request_id" validate:"required"`
Name string `json:"name" validate:"required"`
Arguments json.RawMessage `json:"arguments" validate:"required"`
}
ToolCallPayload is the payload for tool_call method (server -> client).
type Update ¶
type Update struct {
Kind string `json:"kind"`
Seq uint64 `json:"seq"`
Payload json.RawMessage `json:"payload"`
}
Update represents a single update within an Updates envelope.
func FillGaps ¶
FillGaps returns a new slice of Updates covering the range [fromSeq, toSeq] inclusive. For seq values not present in the input, placeholder Updates with Kind="" and Payload=nil are inserted. The input slice is never modified. Returns an empty slice if fromSeq > toSeq.
func NewConversationCreatedUpdate ¶
NewConversationCreatedUpdate creates a persistent conversation_created Update with the given seq and payload.
func NewConversationDestroyedUpdate ¶
NewConversationDestroyedUpdate creates a persistent conversation_destroyed Update with the given seq and payload.
func NewConversationSwitchedUpdate ¶
NewConversationSwitchedUpdate creates a persistent conversation_switched Update with the given seq and payload.
func NewErrorUpdate ¶
NewErrorUpdate creates a persistent error Update with the given seq and payload.
func NewReadReceiptUpdate ¶
NewReadReceiptUpdate creates a persistent read_receipt Update with the given seq and payload.
func NewReplyUpdate ¶
NewReplyUpdate creates a persistent reply Update with the given seq and payload.
func NewResultUpdate ¶
NewResultUpdate creates a persistent result Update with the given seq and payload.
func NewRetryUpdate ¶
NewRetryUpdate creates a non-persistent retry Update with seq=0.
func NewStreamingUpdate ¶
NewStreamingUpdate creates a non-persistent streaming Update with seq=0.
func NewToolCallUpdate ¶
NewToolCallUpdate creates a persistent tool_call Update with the given seq and payload.
func NewTypingUpdate ¶
NewTypingUpdate creates a non-persistent typing Update with seq=0.
type Updates ¶
type Updates struct {
Type string `json:"type"`
Version int `json:"version"`
Updates []Update `json:"updates"`
}
Updates represents an updates message envelope containing multiple Update entries.
type UpdatesBuilder ¶
type UpdatesBuilder struct {
// contains filtered or unexported fields
}
UpdatesBuilder provides a fluent API for constructing Updates messages.
func NewUpdates ¶
func NewUpdates() *UpdatesBuilder
NewUpdates creates a new UpdatesBuilder with an empty (non-nil) updates slice.
func (*UpdatesBuilder) Add ¶
func (b *UpdatesBuilder) Add(u Update) *UpdatesBuilder
Add appends an Update to the builder.
func (*UpdatesBuilder) Build ¶
func (b *UpdatesBuilder) Build() *Updates
Build returns the constructed Updates.
func (*UpdatesBuilder) Marshal ¶
func (b *UpdatesBuilder) Marshal() ([]byte, error)
Marshal serializes the Updates to JSON bytes.
Source Files