pad/internal/events/bus.go

package events

import (
	"log/slog"
	"sync"
	"sync/atomic"
	"time"
)

// Event types
const (
	DocumentCreated  = "document_created"
	DocumentUpdated  = "document_updated"
	DocumentArchived = "document_archived"
	DocumentRestored = "document_restored"
	WorkspaceUpdated = "workspace_updated"

	// Item events (v2)
	ItemCreated  = "item_created"
	ItemUpdated  = "item_updated"
	ItemArchived = "item_archived"
	ItemRestored = "item_restored"

	// Collection events. Emitted when a collection's own row changes
	// (settings/schema/name/icon, e.g. a quick-action added). Routed by
	// Collection (slug) through the SSE visibility filter so sibling
	// ItemDetails / collection pages refresh their independent Collection
	// snapshot proactively — shrinking the optimistic-concurrency (409)
	// window (BUG-2265).
	CollectionUpdated = "collection_updated"

	// Comment events
	CommentCreated = "comment_created"
	CommentUpdated = "comment_updated"
	CommentDeleted = "comment_deleted"

	// Reaction events
	ReactionAdded   = "reaction_added"
	ReactionRemoved = "reaction_removed"

	// Star events
	ItemStarred   = "item_starred"
	ItemUnstarred = "item_unstarred"

	// Composite events
	ItemUpdatedWithComment = "item_updated_with_comment"

	// Batch events. Emitted once for a whole bulk mutation (TASK-1668)
	// instead of one ItemUpdated/ItemArchived per row — the lane-header
	// bulk actions (archive/move/tag/untag/set-priority/assign all) can
	// touch a whole filtered lane, so per-item fan-out would flood both
	// SSE subscribers and webhooks.
	ItemsBulkUpdated = "items_bulk_updated"
)

// Default replay buffer settings.
const (
	DefaultReplayBufferSize = 1024            // max events to retain per workspace
	DefaultReplayMaxAge     = 5 * time.Minute // discard events older than this
)

// Event represents a real-time event published when state changes occur.
type Event struct {
	ID          int64  `json:"id"`
	Type        string `json:"type"`
	WorkspaceID string `json:"workspace_id"`
	DocumentID  string `json:"document_id,omitempty"`
	ItemID      string `json:"item_id,omitempty"`
	// CollectionID is the STABLE collection identity on a collection_updated
	// event (BUG-2265). Slugs are mutable and reusable and events replay, so a
	// stale rename event's OLD slug could be re-owned by a different collection;
	// clients therefore match these events by CollectionID, not the slug (which
	// stays only for rename-navigation URLs). Empty on non-collection events.
	CollectionID string `json:"collection_id,omitempty"`
	Collection   string `json:"collection,omitempty"`
	// NewSlug carries a collection's NEW slug on a collection_updated event
	// that is a rename (BUG-2265). The event is routed by Collection (the OLD
	// slug, which the sibling tabs still address) so old-slug watchers receive
	// it and can re-target to NewSlug. Empty for non-rename updates.
	NewSlug string `json:"new_slug,omitempty"`
	// ItemsChanged is set on a collection_updated event when a field MIGRATION
	// WAS REQUESTED (a schema change carrying migrations), independent of how
	// many rows actually changed (BUG-2265 Codex round 7). It's a SANITIZED
	// reconcile signal — a bare bool carrying NO per-item data and revealing
	// nothing about hidden item values — so it can be delivered to item-grant
	// subscribers; their client triggers a /items-changes deltaSync
	// (server-filtered to their grants) to pick up the migrated field JSON.
	ItemsChanged bool   `json:"items_changed,omitempty"`
	Title        string `json:"title,omitempty"`
	DocType      string `json:"doc_type,omitempty"`
	Actor        string `json:"actor,omitempty"`
	ActorName    string `json:"actor_name,omitempty"`
	Source       string `json:"source,omitempty"`
	UserID       string `json:"user_id,omitempty"` // For user-scoped events (e.g. star/unstar)
	Timestamp    int64  `json:"timestamp"`
	// Seq is the workspace-scoped monotonic mutation cursor of the
	// item the event references (PLAN-1343 / TASK-1352). Populated
	// for item lifecycle events (created / updated / archived /
	// restored) so the local-first read model (TASK-1358) can apply
	// the change in-place when the seq is contiguous with the
	// client's cursor, or trigger a /items-changes backfill when
	// there's a gap. Zero for non-item events (workspace_updated,
	// comment_*, reaction_*) and for legacy publishers that
	// haven't been upgraded.
	Seq int64 `json:"seq,omitempty"`
	// Op / Count describe a batch event (ItemsBulkUpdated, TASK-1668).
	// Op is the verb applied (archive/move/tag/untag/set-priority/
	// assign); Count is the number of items affected in this event's
	// Collection. Zero/empty for single-item events.
	//
	// A batch event is scoped to ONE Collection (the bulk endpoint emits
	// one per affected collection) so the SSE visibility filter routes
	// it like any collection-scoped event. It deliberately carries NO
	// per-item IDs: a batch can't be item-grant-filtered for guests on a
	// broadcast bus, so IDs would leak. Recipients react by running a
	// /items-changes delta, which IS visibility-filtered server-side;
	// Seq holds the max seq across the batch as the reconcile cursor.
	Op    string `json:"op,omitempty"`
	Count int    `json:"count,omitempty"`
}

// EventBus is the interface for pub/sub event distribution.
// Implementations include MemoryBus (in-process) and RedisBus (cross-instance).
type EventBus interface {
	// Subscribe registers a new subscriber for the given workspace.
	// Returns a buffered channel that will receive events for that workspace.
	Subscribe(workspaceID string) chan Event

	// SubscribeIfAllowed atomically checks the global and per-workspace
	// subscriber limits and, only if both are satisfied, subscribes in the
	// same critical section.  Returns (ch, true) on success or (nil, false)
	// when a limit would be exceeded.  Pass 0 for either limit to disable it.
	SubscribeIfAllowed(workspaceID string, maxGlobal, maxPerWorkspace int) (chan Event, bool)

	// Unsubscribe removes a subscriber and closes its channel.
	Unsubscribe(ch chan Event)

	// Publish sends an event to all subscribers for the event's workspace.
	Publish(event Event)

	// EventsSince returns events for a workspace with IDs greater than sinceID.
	// Used to replay missed events on SSE reconnect (Last-Event-ID).
	// Returns nil if sinceID is too old and has been evicted from the buffer.
	EventsSince(workspaceID string, sinceID int64) []Event

	// Close shuts down the event bus and cleans up resources.
	Close()

	// SubscriberCount returns the number of active local subscribers.
	SubscriberCount() int

	// WorkspaceSubscriberCount returns the number of active subscribers
	// for a specific workspace.
	WorkspaceSubscriberCount(workspaceID string) int
}

// replayBuffer is a bounded ring buffer of recent events for a single workspace.
// It supports efficient append and replay-since-ID queries.
type replayBuffer struct {
	events []Event
	size   int // max capacity
	head   int // next write position
	count  int // current number of events
}

func newReplayBuffer(size int) *replayBuffer {
	return &replayBuffer{
		events: make([]Event, size),
		size:   size,
	}
}

// append adds an event to the ring buffer, evicting the oldest if full.
func (rb *replayBuffer) append(e Event) {
	rb.events[rb.head] = e
	rb.head = (rb.head + 1) % rb.size
	if rb.count < rb.size {
		rb.count++
	}
}

// since returns all buffered events with ID > sinceID, in chronological order.
// Returns nil if sinceID is older than the oldest buffered event AND the buffer
// is full (i.e. events have been evicted), meaning we can't guarantee completeness.
// Returns an empty (non-nil) slice if sinceID is current (no missed events).
// A sinceID of 0 means "give me everything in the buffer".
func (rb *replayBuffer) since(sinceID int64) []Event {
	if rb.count == 0 {
		return []Event{}
	}

	// Find the oldest event in the buffer
	oldest := (rb.head - rb.count + rb.size) % rb.size
	oldestID := rb.events[oldest].ID

	// Find the newest event in the buffer.
	newest := (rb.head - 1 + rb.size) % rb.size
	newestID := rb.events[newest].ID

	// If sinceID is beyond the newest event we have, the ID came from a
	// different sequence (e.g., a different instance in a Redis deployment).
	// We can't determine what was missed — signal a gap.
	if sinceID > newestID {
		return nil
	}

	// If the requested ID is older than our oldest AND the buffer has wrapped
	// (events were evicted), we can't guarantee completeness — signal a gap.
	// But if the buffer hasn't filled up yet, all events are still present.
	if sinceID > 0 && sinceID < oldestID && rb.count == rb.size {
		return nil
	}

	// Collect events with ID > sinceID
	var result []Event
	for i := 0; i < rb.count; i++ {
		idx := (oldest + i) % rb.size
		if rb.events[idx].ID > sinceID {
			result = append(result, rb.events[idx])
		}
	}
	if result == nil {
		result = []Event{}
	}
	return result
}

// subscriber wraps a channel with its workspace filter.
type subscriber struct {
	ch          chan Event
	workspaceID string
}

// MemoryBus is an in-process pub/sub event bus that fans out events
// to all subscribers for a given workspace. Suitable for single-instance deployments.
type MemoryBus struct {
	mu          sync.RWMutex
	subscribers map[chan Event]*subscriber

	// Monotonic sequence counter for event IDs.
	seq atomic.Int64

	// Per-workspace replay buffers for Last-Event-ID support.
	replayMu      sync.RWMutex
	replayBuffers map[string]*replayBuffer
	replaySize    int
	replayMaxAge  time.Duration
}

// New creates a new in-memory EventBus with default replay buffer settings.
func New() *MemoryBus {
	return NewWithReplay(DefaultReplayBufferSize, DefaultReplayMaxAge)
}

// NewWithReplay creates a new in-memory EventBus with custom replay settings.
func NewWithReplay(bufferSize int, maxAge time.Duration) *MemoryBus {
	return &MemoryBus{
		subscribers:   make(map[chan Event]*subscriber),
		replayBuffers: make(map[string]*replayBuffer),
		replaySize:    bufferSize,
		replayMaxAge:  maxAge,
	}
}

// Subscribe registers a new subscriber for the given workspace.
// Returns a buffered channel that will receive events for that workspace.
func (b *MemoryBus) Subscribe(workspaceID string) chan Event {
	b.mu.Lock()
	defer b.mu.Unlock()

	ch := make(chan Event, 64)
	b.subscribers[ch] = &subscriber{
		ch:          ch,
		workspaceID: workspaceID,
	}
	return ch
}

// SubscribeIfAllowed atomically checks limits and subscribes.
func (b *MemoryBus) SubscribeIfAllowed(workspaceID string, maxGlobal, maxPerWorkspace int) (chan Event, bool) {
	b.mu.Lock()
	defer b.mu.Unlock()

	if maxGlobal > 0 && len(b.subscribers) >= maxGlobal {
		return nil, false
	}
	if maxPerWorkspace > 0 {
		count := 0
		for _, sub := range b.subscribers {
			if sub.workspaceID == workspaceID {
				count++
			}
		}
		if count >= maxPerWorkspace {
			return nil, false
		}
	}

	ch := make(chan Event, 64)
	b.subscribers[ch] = &subscriber{
		ch:          ch,
		workspaceID: workspaceID,
	}
	return ch, true
}

// Unsubscribe removes a subscriber and closes its channel.
func (b *MemoryBus) Unsubscribe(ch chan Event) {
	b.mu.Lock()
	defer b.mu.Unlock()

	if _, ok := b.subscribers[ch]; ok {
		delete(b.subscribers, ch)
		close(ch)
	}
}

// Publish sends an event to all subscribers for the event's workspace.
// Non-blocking: if a subscriber's channel is full, the event is dropped
// and a warning is logged. Events are assigned a monotonic sequence ID
// and stored in the replay buffer for Last-Event-ID support.
func (b *MemoryBus) Publish(event Event) {
	if event.Timestamp == 0 {
		event.Timestamp = time.Now().UnixMilli()
	}

	// Assign a monotonic sequence ID.
	event.ID = b.seq.Add(1)

	// Store in replay buffer for reconnect replay.
	b.replayMu.Lock()
	rb, ok := b.replayBuffers[event.WorkspaceID]
	if !ok {
		rb = newReplayBuffer(b.replaySize)
		b.replayBuffers[event.WorkspaceID] = rb
	}
	rb.append(event)
	b.replayMu.Unlock()

	// Fan out to live subscribers.
	b.mu.RLock()
	defer b.mu.RUnlock()

	for _, sub := range b.subscribers {
		if sub.workspaceID != event.WorkspaceID {
			continue
		}
		select {
		case sub.ch <- event:
		default:
			slog.Warn("dropping event for slow subscriber", "type", event.Type, "workspace", event.WorkspaceID)
		}
	}
}

// EventsSince returns buffered events for a workspace with IDs greater than sinceID.
// Returns nil if sinceID has been evicted from the buffer (gap too large).
// Returns an empty slice if the caller is fully caught up.
func (b *MemoryBus) EventsSince(workspaceID string, sinceID int64) []Event {
	b.replayMu.RLock()
	defer b.replayMu.RUnlock()

	rb, ok := b.replayBuffers[workspaceID]
	if !ok {
		// No events ever published for this workspace.
		return []Event{}
	}
	return rb.since(sinceID)
}

// Close shuts down the event bus by closing all subscriber channels.
// SSE handler goroutines will see the channel close and exit cleanly.
func (b *MemoryBus) Close() {
	b.mu.Lock()
	defer b.mu.Unlock()

	for ch := range b.subscribers {
		delete(b.subscribers, ch)
		close(ch)
	}
}

// SubscriberCount returns the number of active subscribers (for testing/debugging).
func (b *MemoryBus) SubscriberCount() int {
	b.mu.RLock()
	defer b.mu.RUnlock()
	return len(b.subscribers)
}

// WorkspaceSubscriberCount returns the number of active subscribers for a workspace.
func (b *MemoryBus) WorkspaceSubscriberCount(workspaceID string) int {
	b.mu.RLock()
	defer b.mu.RUnlock()
	count := 0
	for _, sub := range b.subscribers {
		if sub.workspaceID == workspaceID {
			count++
		}
	}
	return count
}