Documentation
¶
Overview ¶
Package awareness implements bounded, ephemeral presence state for a collaboration group.
Awareness is deliberately separate from durable CRDT state: it must never be checkpointed, included in a replica.Frontier, or used as an authorization decision. Each actor owns a monotonically increasing clock. A removal keeps its clock as an in-memory tombstone so a delayed older update cannot bring a disconnected actor back online.
Index ¶
- Variables
- type Options
- type Store
- func (store *Store) ActiveAt(now time.Time) []Update
- func (store *Store) Apply(update Update, now time.Time) (changed bool, err error)
- func (store *Store) Options() Options
- func (store *Store) Remove(actor string, now time.Time) (Update, error)
- func (store *Store) Set(actor string, state []byte, now time.Time) (Update, error)
- type Update
Constants ¶
This section is empty.
Variables ¶
var ( ErrInvalidOptions = errors.New("awareness: invalid options") ErrInvalidActor = errors.New("awareness: invalid actor") ErrInvalidState = errors.New("awareness: invalid state") ErrInvalidUpdate = errors.New("awareness: invalid update") ErrResourceLimit = errors.New("awareness: resource limit exceeded") ErrStateConflict = errors.New("awareness: conflicting update clock") ErrClockExhausted = errors.New("awareness: actor clock exhausted") )
Functions ¶
This section is empty.
Types ¶
type Options ¶
Options sets the resource and liveness boundaries for one awareness group. MaxStateBytes covers a single JSON object, not the aggregate application session. Timeout is evaluated by ActiveAt; applications should publish a strictly newer heartbeat before it elapses.
func DefaultOptions ¶
func DefaultOptions() Options
DefaultOptions returns conservative limits for UI presence such as names, colours, selections, and small cursor metadata.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store accepts locally created and remotely received updates. It is safe for concurrent UI, timer, and transport goroutines. Its state is intentionally process-local and must not be persisted with CRDT data.
func (*Store) ActiveAt ¶
ActiveAt returns sorted, owned copies of the currently live presence states. Offline tombstones remain retained internally until the application drops the whole ephemeral Store, preventing old packets from reviving an actor.
func (*Store) Apply ¶
Apply installs a newer remote update. Duplicates and stale updates are harmless and return changed=false. A different payload at an equal clock is rejected so arrival order cannot determine a user's displayed presence.
type Update ¶
Update is one actor's complete ephemeral state at Clock. A nil State is a removal. State is an opaque canonical JSON object so the owning application can define fields without making presence a durable document schema.
func Normalize ¶
Normalize returns a copied update whose online JSON state has a deterministic representation. It reserves nil for a removal and rejects every other JSON top-level value, keeping presence fields namespaced beneath an object.
func UnmarshalUpdate ¶
UnmarshalUpdate decodes one exact, bounded awareness-v1 update. It performs all limits and JSON validation before allocating retained state.
func (Update) MarshalBinary ¶
MarshalBinary serializes a self-contained awareness-v1 update using bounded canonical varints. It authenticates nothing; transports must authorize the actor against their authenticated peer before relaying it.
func (Update) MarshalBinaryWithOptions ¶
MarshalBinaryWithOptions serializes update after validating and canonicalizing its actor and optional JSON object.
Source Files