livewire

type Envelope struct {
	Event string          `json:"event"`
	Data  json.RawMessage `json:"data"`
}

type Options struct {
	// Authorize answers whether this caller may use the socket at all.
	//
	// The only place the library touches your application's idea of identity.
	// Nil accepts every upgrade, which is right behind a gateway that has
	// already authenticated and wrong on the open internet.
	Authorize func(request *http.Request) bool

	// Refusal is what to say before closing a socket that was refused. Said on
	// the socket and not only in a close code: a refusal arriving as a bare
	// disconnection is indistinguishable from a network fault.
	Refusal func(request *http.Request) string

	// Origins allowed to open a socket. Empty means same-origin only.
	Origins []string

	// Logger. Nil uses the default.
	Logger *slog.Logger
}

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

type Row struct {
	ID string `json:"id"`

	// UpdatedAt is the version of this row. It changes whenever anything the
	// row shows changes.
	//
	// Not necessarily a timestamp: a filter entry whose only content is its
	// label uses the label, and a row carrying a value derived from the clock
	// has to fold that value in — otherwise the server believes the row
	// unchanged and never sends it again. See SPEC.md, "Versions".
	UpdatedAt string `json:"updatedAt"`

	// Data is what the row actually shows. Marshalled flat beside ID and
	// UpdatedAt, so the wire carries one object per row rather than a nested
	// one — see MarshalJSON.
	Data map[string]any `json:"-"`
}

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

type Source interface {
	// ReadQuery is the trust boundary: what arrives is JSON off a socket.
	// Clamp it, whitelist it, default it, and hand back something Read can act
	// on without checking again.
	ReadQuery(raw json.RawMessage) (any, error)

	// Key answers what two identical questions share. Two queries with the
	// same key share one read.
	Key(query any) string

	// Wake fires whenever this source may have something new to say. Only the
	// fact of a send is read, never its value.
	//
	// It must not be closed while the source is in use; a source with nothing
	// to follow returns a channel that never sends.
	Wake() <-chan struct{}

	// Read is the window as it stands.
	Read(ctx context.Context, query any) (Window, error)
}

type Window struct {
	Rows []Row

	// Total is the length the window is a page of. Nil when the source does
	// not page.
	Total *int

	// Pivot is an index in the whole list the source points the client at.
	//
	// A number and nothing more — neither side interprets it. A departure
	// board uses it for the boundary between what has left and what has not: a
	// position in the list that a client holding one page of six hundred
	// cannot work out from the rows it happens to have.
	Pivot *int
}