realtime

type Access struct {
	SessionID string // the session's id (its document key)
	UserID    string
	KeyID     string // an API key's document key (its hash)
	Orgs      []string
	// Fingerprint summarizes what the caller's access depends on (roles, memberships, second
	// factor, consents). Resume tokens carry it: replaying history made while the access was
	// different would show states the caller couldn't see then.
	Fingerprint string
	// UsesConfig says a subscribed collection's rules read the app configuration, so a change of
	// the configuration changes what is visible.
	UsesConfig bool
	// Expires is when the credential stops being good; zero: never.
	Expires time.Time
	// Reload reads the caller's access again and returns what each subscription (by id) shows
	// now. Ended means the credential is no longer valid.
	Reload func(ctx context.Context) (Reloaded, error)
}

type Frame struct {
	ID    string // a resume token; set on the last frame of a change
	Event string
	Data  []byte
}

type Hub struct {
	// Feed is the instance's shared consumer; every stream is a handler of it.
	Feed *changefeed.Lazy
	// Replay makes a consumer that reads from a resume position, over the same set the Feed
	// reads. Nil disables resuming: a token is taken as expired history.
	Replay func() *changefeed.Consumer
	// ReloadJitter spreads the reads of access after a change (up to this long, per stream; default
	// 250ms, negative for none) and ReloadConcurrency bounds how many run at once (default 16).
	ReloadJitter time.Duration
	// RefreshEvery is how often an open stream reads its caller's access again with nothing having
	// changed: access that ends by the clock (a role window, a rule on `now`) has no event.
	// Default 5 minutes; negative disables it.
	RefreshEvery      time.Duration
	ReloadConcurrency int
	Limits            Limits
	Observer          Observer
	Now               func() time.Time
	// contains filtered or unexported fields
}

type Key struct {
	Field  string
	Values []any
}

type Limits struct {
	SubscriptionsPerStream int
	StreamsPerUser         int
	Streams                int // per instance
	BufferBytes            int // per stream
	BufferEvents           int // per stream
	Memory                 int64
	Heartbeat              time.Duration
	// OpenInterval is the least time between two streams opened by one principal.
	OpenInterval time.Duration
	// ResumeMaxAge is how old a resume token may be before the history is taken as gone.
	ResumeMaxAge time.Duration
}

type Observer interface {
	StreamOpened(realm string)
	StreamClosed(realm string)
	Event(realm, event string)
	Reset(realm, reason string)
	Refused(realm, reason string)
	// Checks counts the subscriptions a change was evaluated against: kind "indexed" (found by
	// document id or key) or "scanned" (no key: asked on every change).
	Checks(realm, kind string, n int)
}

type Reloaded struct {
	Ended       bool
	Fingerprint string
	Orgs        []string
	Expires     time.Time
	Subs        map[string]Visibility
}

type Request struct {
	Realm string
	// Principal names who the stream is for ("user:u_1", "key:ci", "anon:<ip>"); streams per
	// caller and resume tokens are counted and bound by it.
	Principal     string
	Key           []byte // the realm's resume key
	Subscriptions []*Subscription
	Resume        string // a token, or ""
	// Limits lower the instance's: per stream subscriptions and streams per user, from the realm.
	MaxStreamsPerUser int
	// Access ties the stream to its caller's session, user or key, so that changes of them
	// reach it; nil for anonymous callers and realms without authentication.
	Access *Access
}

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

type Subscription struct {
	ID string
	// DB and Coll name what a change reports: the MongoDB database and the collection.
	DB, Coll string
	Doc      string // a document id; "" follows the collection
	Visible  func(doc map[string]any) (bool, error)
	// Render turns a stored document into what a read returns.
	Render func(doc map[string]any) map[string]any
	// Keys are the equalities the subscription can only be visible under (KeysOf of its
	// resolved filter): they let a change find it without asking every subscription.
	Keys []Key
	// contains filtered or unexported fields
}

type Token struct {
	Pos       []byte `json:"p"`
	Realm     string `json:"r"`
	Principal string `json:"u"`
	Issued    int64  `json:"t"` // unix seconds
	// Access fingerprints what the caller could see when the token was issued; a resume under
	// another one (a role or membership changed meanwhile) reloads instead of replaying.
	Access string `json:"a,omitempty"`
}

type Visibility struct {
	// Changed says the caller's effective access to the subscription differs from before.
	Changed bool
	Visible func(doc map[string]any) (bool, error)
	Keys    []Key
}