Reference for Sessionstream packages, core types, schema rules, transport semantics, and development commands.
This reference summarizes the public pieces of the sessionstream repository. Use it when you know the concept and need names, packages, commands, or contracts.
github.com/go-go-golems/sessionstream
Core import path:
import sessionstream "github.com/go-go-golems/sessionstream/pkg/sessionstream"
Embedded documentation import path:
import sessionstreamdoc "github.com/go-go-golems/sessionstream/pkg/doc"
| Path | Purpose |
|---|---|
pkg/sessionstream | Core framework APIs: hub, commands, events, projections, hydration interfaces. |
pkg/sessionstream/hydration/sqlite | SQLite hydration store implementation. |
pkg/sessionstream/transport/ws | WebSocket transport adapter. |
pkg/sessionstream/pb/proto/sessionstream/v1 | Generated Go bindings for transport frames. |
proto/sessionstream/v1/transport.proto | WebSocket transport protobuf schema. |
pkg/analysis/sessionstreamschema | Go analyzer that rejects top-level Struct schema registrations. |
cmd/sessionstream-lint | Vettool command for the schema analyzer. |
pkg/doc | Embedded Glazed help entries for downstream CLIs. |
cmd/sessionstream-systemlab | Browser-based lab/reference application. |
examples/chatdemo | Small runnable chat-style example. |
ttmp | Design docs, tickets, and implementation diaries. |
The Hub is the command/event/projection coordinator.
Important functions and options:
func NewHub(opts ...HubOption) (*Hub, error)
func WithSchemaRegistry(r *SchemaRegistry) HubOption
func WithHydrationStore(s HydrationStore) HubOption
func WithUIFanout(f UIFanout) HubOption
func WithProjectionPolicies(p ProjectionPolicies) HubOption
func (h *Hub) RegisterCommand(name string, handler CommandHandler) error
func (h *Hub) RegisterUIProjection(p UIProjection) error
func (h *Hub) RegisterTimelineProjection(p TimelineProjection) error
func (h *Hub) Submit(ctx context.Context, sid SessionId, name string, payload proto.Message) error
func (h *Hub) Snapshot(ctx context.Context, sid SessionId) (Snapshot, error)
type CommandHandler func(
ctx context.Context,
cmd Command,
sess *Session,
pub EventPublisher,
) error
Handlers publish backend events through EventPublisher. They should not return UI state directly.
type EventPublisher interface {
Publish(ctx context.Context, ev Event) error
}
The publisher validates event payload types, assigns ordinals, applies projections, stores timeline state, and fans out UI events according to hub configuration.
type Event struct {
Name string
Payload proto.Message
SessionId SessionId
Ordinal uint64
}
Backend events are canonical records. Projections derive other views from them.
type UIEvent struct {
Name string
Payload proto.Message
}
UI events are live client-facing projected events.
type TimelineEntity struct {
Kind string
Id string
CreatedOrdinal uint64
LastEventOrdinal uint64
Payload proto.Message
Tombstone bool
}
Timeline entities are durable projected state. Hydration stores use them to build snapshots.
type TimelineView interface {
Get(kind, id string) (TimelineEntity, bool)
List(kind string) []TimelineEntity
Ordinal() uint64
}
Projections receive a read-only timeline view so they can update existing entities instead of blindly replacing state.
func NewSchemaRegistry() *SchemaRegistry
func (r *SchemaRegistry) RegisterCommand(name string, msg proto.Message) error
func (r *SchemaRegistry) RegisterEvent(name string, msg proto.Message) error
func (r *SchemaRegistry) RegisterUIEvent(name string, msg proto.Message) error
func (r *SchemaRegistry) RegisterTimelineEntity(kind string, msg proto.Message) error
Rules:
*structpb.Struct registrations.google.protobuf.Struct fields are allowed when intentionally scoped inside a concrete message.type UIProjection interface {
Project(ctx context.Context, ev Event, sess *Session, view TimelineView) ([]UIEvent, error)
}
type TimelineProjection interface {
Project(ctx context.Context, ev Event, sess *Session, view TimelineView) ([]TimelineEntity, error)
}
Function adapters are available:
sessionstream.UIProjectionFunc(func(ctx context.Context, ev sessionstream.Event, sess *sessionstream.Session, view sessionstream.TimelineView) ([]sessionstream.UIEvent, error) {
return nil, nil
})
sessionstream.TimelineProjectionFunc(func(ctx context.Context, ev sessionstream.Event, sess *sessionstream.Session, view sessionstream.TimelineView) ([]sessionstream.TimelineEntity, error) {
return nil, nil
})
Transport schemas live in:
proto/sessionstream/v1/transport.proto
Important frame types:
| Frame | Direction | Purpose |
|---|---|---|
ClientFrame.subscribe | client -> server | Subscribe to a session. |
ClientFrame.unsubscribe | client -> server | Stop receiving a session. |
ClientFrame.ping | client -> server | Keepalive. |
ServerFrame.hello | server -> client | Connection greeting. |
ServerFrame.snapshot | server -> client | Current hydrated timeline state. |
ServerFrame.uiEvent | server -> client | Live UI event derived from a backend event. |
ServerFrame.error | server -> client | Transport or subscription error. |
Payloads are encoded as protobuf JSON. Snapshot and UI payloads use google.protobuf.Any; clients need matching application schema knowledge to unpack or interpret them.
| Field | Meaning |
|---|---|
Backend event Ordinal | Order assigned to a canonical backend event. |
Snapshot.snapshotOrdinal | Highest timeline ordinal represented by the snapshot. |
SnapshotEntity.createdOrdinal | Ordinal that created the entity. |
SnapshotEntity.lastEventOrdinal | Latest event ordinal that updated the entity. |
UiEventFrame.eventOrdinal | Backend event ordinal that produced the live UI event. |
Protojson renders uint64 values as strings. Browser code should not force them through JavaScript number if precision matters.
Build the schema vettool:
go build -o /tmp/sessionstream-lint ./cmd/sessionstream-lint
Run it through go vet:
go vet -vettool=/tmp/sessionstream-lint ./pkg/analysis/sessionstreamschema ./cmd/sessionstream-lint
Downstream workspace usage:
go build -o /tmp/sessionstream-lint ../sessionstream/cmd/sessionstream-lint
go vet -vettool=/tmp/sessionstream-lint ./cmd/... ./pkg/...
Run the browser-based lab app:
make systemlab-run
# or directly:
go run ./cmd/sessionstream-systemlab serve --addr :8091
Browse embedded CLI help entries:
go run ./cmd/sessionstream-systemlab help sessionstream-user-guide
go run ./cmd/sessionstream-systemlab help sessionstream-reference
Default URL:
http://localhost:8091/
Embedded help docs are served by Systemlab under:
http://localhost:8091/docs/
make test
make build
make lint
make schema-vet
make systemlab-build
make systemlab-run
make boundary-check
Most repository Makefile targets use GOWORK=off so the module is tested as an external consumer would see it.
Downstream CLIs can load Sessionstream help entries into a Glazed help system:
helpSystem := help.NewHelpSystem()
if err := sessionstreamdoc.AddDocToHelpSystem(helpSystem); err != nil {
return err
}
The package also exposes the embedded filesystem:
docsFS := sessionstreamdoc.FS()
sessionstream-user-guide for the architecture narrative.sessionstream-getting-started for a first app walkthrough.sessionstream-schema-vet-playbook for vettool operation.examples/chatdemo/chat.go for runnable application code.proto/sessionstream/v1/transport.proto for websocket schema details.