gateway

type Backend interface {
	// Subscribe registers a live query and returns a handle whose Deltas
	// channel carries the snapshot (as OpReset + OpEnter rows) followed by live
	// deltas. The returned Sub MUST be Closed when the client disconnects.
	Subscribe(ctx context.Context, q livequery.LiveQuery) (*Sub, error)
}

type ClientCommand struct {
	Action string               `json:"action"`
	Query  *livequery.LiveQuery `json:"query,omitempty"`  // subscribe
	Cursor *livequery.Cursor    `json:"cursor,omitempty"` // reanchor
	Limit  int                  `json:"limit,omitempty"`  // reanchor
}

type Frame struct {
	Op       string           `json:"op"`
	AggID    string           `json:"agg_id,omitempty"`
	Version  int64            `json:"version,omitempty"`
	Row      json.RawMessage  `json:"row,omitempty"`
	OldIndex int              `json:"old_index"`
	NewIndex int              `json:"new_index"`
	Cursor   livequery.Cursor `json:"cursor,omitempty"`
	StreamID string           `json:"stream_id,omitempty"`
}

type SSEOptions struct {
	// HeartbeatInterval is how often a keep-alive comment is sent on an idle
	// stream. Defaults to 15s.
	HeartbeatInterval time.Duration
	// WriteTimeout bounds a single event write; on a stalled client the write
	// fails and the connection is torn down (the client reconnects to a fresh
	// snapshot). Zero disables the deadline.
	WriteTimeout time.Duration
}

type SSESink interface {
	// WriteEvent emits one event: id = SSE "id:" (resume position),
	// event = the delta op name, v = the JSON payload. It flushes.
	WriteEvent(id, event string, v any) error
	// SetWriteDeadline bounds how long one write may block (backpressure).
	SetWriteDeadline(time.Time) error
	// Heartbeat writes a keep-alive comment.
	Heartbeat() error
}

type Sub struct {
	// ID is the backend's subscription id (logging / client correlation).
	ID string
	// Deltas is the merged snapshot+live stream. It is closed by the backend
	// when the subscription ends.
	Deltas <-chan livequery.LiveDelta
	// contains filtered or unexported fields
}

type WSConn interface {
	// ReadJSON decodes the next client command frame; it errors when the client
	// disconnects or the connection is closed.
	ReadJSON(v any) error
	// WriteJSON sends one server frame to the client.
	WriteJSON(v any) error
	// Close tears the socket down (also used to abort a stalled write).
	Close() error
	// Context is cancelled when the connection ends.
	Context() context.Context
}

type WSOptions struct {
	// WriteTimeout bounds a single frame write. forge.Connection exposes no
	// write deadline, so the bound is enforced with a watchdog: a write that
	// stalls past WriteTimeout closes the connection (the client reconnects to a
	// fresh snapshot). Zero disables the watchdog (the established idiom: rely on
	// the bounded delta buffer and tear down on any write error).
	WriteTimeout time.Duration
}