kandev/apps/backend/internal/plugins/webapp/events.go

package webapp

import (
	"context"
	"crypto/rand"
	"encoding/hex"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"net/http"
	"strconv"
	"strings"
	"sync"
	"time"
)

const (
	DefaultEventCapacity              = 1000
	DefaultEventReplayWindow          = 5 * time.Minute
	DefaultEventHistoryTTL            = DefaultEventReplayWindow
	DefaultEventHeartbeatInterval     = 15 * time.Second
	DefaultEventSubscriberQueueSize   = 32
	DefaultEventMaxStreamsPerUser     = 20
	DefaultEventMaxStreamsPerInstance = 2
	DefaultEventMaxPayloadBytes       = 256 << 10
	DefaultEventStreamLifetime        = 15 * time.Minute

	RuntimeResyncRequired = "runtime.resync_required"

	ResyncReasonHistoryGap         = "history_gap"
	ResyncReasonGenerationMismatch = "generation_mismatch"
	ResyncReasonInvalidCursor      = "invalid_cursor"
	ResyncReasonCursorAhead        = "cursor_ahead"
)

var (
	ErrEventHubClosed       = errors.New("webapp: event hub is closed")
	ErrInvalidEvent         = errors.New("webapp: invalid event")
	ErrEventPayloadTooLarge = errors.New("webapp: event payload exceeds limit")
	ErrInvalidSubscription  = errors.New("webapp: invalid event subscription")
	ErrTooManyEventStreams  = errors.New("webapp: too many event streams")
	ErrSlowSubscriber       = errors.New("webapp: slow event subscriber")
)

// EventScope identifies the resources represented by an event. InstanceID is
// always populated by EventHub; the remaining fields are optional and are
// retained as public scope metadata for the web application.
type EventScope struct {
	InstanceID   string `json:"instance_id"`
	WorkspaceID  string `json:"workspace_id,omitempty"`
	TaskID       string `json:"task_id,omitempty"`
	SessionID    string `json:"session_id,omitempty"`
	RepositoryID string `json:"repository_id,omitempty"`
}

// EventInput is the public, bounded input accepted by Publish. Data is
// marshaled before the event is retained, so callers cannot mutate history by
// changing a map or slice after Publish returns.
type EventInput struct {
	Type  string
	Scope EventScope
	Data  any
}

// Event is the immutable public event delivered to subscribers and encoded in
// an SSE data field. ID is generation:sequence and is stable for replay.
type Event struct {
	ID         string          `json:"id,omitempty"`
	Generation string          `json:"generation"`
	Sequence   uint64          `json:"sequence,omitempty"`
	Type       string          `json:"type"`
	Scope      EventScope      `json:"scope"`
	Data       json.RawMessage `json:"data"`
	published  time.Time       `json:"-"`
}

// EventFilter is evaluated for every live and replayed event. A parent
// runtime can close over current grants and scope checks so authorization is
// re-evaluated without making the hub depend on the Service layer.
type EventFilter func(Event) bool

// ResyncInfo is the payload of RuntimeResyncRequired. The empty SSE id sent
// with this event resets the browser's Last-Event-ID cursor.
type ResyncInfo struct {
	Reason     string `json:"reason"`
	Generation string `json:"generation"`
	Reset      bool   `json:"reset"`
}

// EventSubscriptionRequest binds a stream to one authorized user and plugin
// instance. The request is intended to be created by the capability runtime,
// not from browser-supplied scope fields.
type EventSubscriptionRequest struct {
	InstanceID  string
	UserID      string
	LastEventID string
	Filter      EventFilter
}

// EventHubConfig provides bounded operational limits. Zero values use the
// production defaults. Now is injectable for deterministic replay expiry
// tests.
type EventHubConfig struct {
	Generation                string
	MaxEvents                 int
	ReplayWindow              time.Duration
	SubscriberQueueSize       int
	HeartbeatInterval         time.Duration
	StreamLifetime            time.Duration
	MaxStreamsPerUser         int
	MaxStreamsPerUserInstance int
	MaxPayloadBytes           int
	Now                       func() time.Time
}

// EventHub is an in-memory, per-process event transport. Event history is
// partitioned by plugin instance, while the generation identifies this
// process lifetime for reconnect recovery.
type EventHub struct {
	mu                  sync.Mutex
	instances           map[string]*eventInstance
	userStreams         map[string]int
	userInstanceStreams map[eventStreamKey]int
	closed              bool
	generation          string
	config              EventHubConfig
	now                 func() time.Time
}

type eventInstance struct {
	lastSequence uint64
	events       []Event
	subscribers  map[*EventSubscription]struct{}
}

type eventStreamKey struct {
	userID     string
	instanceID string
}

// EventSubscription owns one bounded subscriber queue. Closing the
// subscription is idempotent and safe to race with Publish, Close, and
// request cancellation.
type EventSubscription struct {
	hub        *EventHub
	instanceID string
	userID     string
	filter     EventFilter
	events     chan Event
	done       chan struct{}

	stateMu sync.RWMutex
	closed  bool
	err     error
}

// NewEventHub creates a hub with production defaults. At most one config is
// used; the variadic form permits both NewEventHub() and concise test setup.
func NewEventHub(configs ...EventHubConfig) *EventHub {
	config := EventHubConfig{}
	if len(configs) > 0 {
		config = configs[0]
	}
	applyEventHubDefaults(&config)
	generation := strings.TrimSpace(config.Generation)
	if !validGeneration(generation) {
		generation = newEventGeneration()
	}
	now := config.Now
	if now == nil {
		now = time.Now
	}
	return &EventHub{
		instances:           make(map[string]*eventInstance),
		userStreams:         make(map[string]int),
		userInstanceStreams: make(map[eventStreamKey]int),
		generation:          generation,
		config:              config,
		now:                 now,
	}
}

func applyEventHubDefaults(config *EventHubConfig) {
	if config.MaxEvents <= 0 {
		config.MaxEvents = DefaultEventCapacity
	}
	if config.ReplayWindow <= 0 {
		config.ReplayWindow = DefaultEventReplayWindow
	}
	if config.SubscriberQueueSize <= 0 {
		config.SubscriberQueueSize = DefaultEventSubscriberQueueSize
	}
	if config.HeartbeatInterval <= 0 {
		config.HeartbeatInterval = DefaultEventHeartbeatInterval
	}
	if config.StreamLifetime <= 0 {
		config.StreamLifetime = DefaultEventStreamLifetime
	}
	if config.MaxStreamsPerUser <= 0 {
		config.MaxStreamsPerUser = DefaultEventMaxStreamsPerUser
	}
	if config.MaxStreamsPerUserInstance <= 0 {
		config.MaxStreamsPerUserInstance = DefaultEventMaxStreamsPerInstance
	}
	if config.MaxPayloadBytes <= 0 {
		config.MaxPayloadBytes = DefaultEventMaxPayloadBytes
	}
}

func newEventGeneration() string {
	buf := make([]byte, 16)
	if _, err := rand.Read(buf); err == nil {
		return hex.EncodeToString(buf)
	}
	return strconv.FormatInt(time.Now().UnixNano(), 10)
}

func validGeneration(generation string) bool {
	return generation != "" && !strings.ContainsAny(generation, "\r\n\t ")
}

// Generation returns the process generation used by this hub.
func (h *EventHub) Generation() string {
	if h == nil {
		return ""
	}
	return h.generation
}

// Publish assigns a per-instance monotonic sequence and makes the event
// available to future reconnects. Subscriber delivery is always non-blocking;
// a full subscriber queue is disconnected instead.
func (h *EventHub) Publish(instanceID string, input EventInput) (Event, error) {
	if h == nil {
		return Event{}, ErrEventHubClosed
	}
	instanceID = strings.TrimSpace(instanceID)
	if err := validatePublishedEvent(instanceID, input); err != nil {
		return Event{}, err
	}
	data, err := marshalEventData(input.Data, h.config.MaxPayloadBytes)
	if err != nil {
		return Event{}, err
	}
	scope := input.Scope
	if scope.InstanceID == "" {
		scope.InstanceID = instanceID
	}
	if scope.InstanceID != instanceID {
		return Event{}, fmt.Errorf("%w: event instance does not match publish instance", ErrInvalidEvent)
	}

	now := h.now().UTC()
	h.mu.Lock()
	if h.closed {
		h.mu.Unlock()
		return Event{}, ErrEventHubClosed
	}
	instance := h.instanceLocked(instanceID)
	instance.purgeExpired(now, h.config.ReplayWindow)
	if instance.lastSequence == ^uint64(0) {
		h.mu.Unlock()
		return Event{}, fmt.Errorf("%w: event sequence exhausted", ErrInvalidEvent)
	}
	instance.lastSequence++
	event := Event{
		ID:         formatEventID(h.generation, instance.lastSequence),
		Generation: h.generation,
		Sequence:   instance.lastSequence,
		Type:       strings.TrimSpace(input.Type),
		Scope:      scope,
		Data:       cloneRawMessage(data),
		published:  now,
	}
	instance.events = append(instance.events, event)
	if len(instance.events) > h.config.MaxEvents {
		instance.events = instance.events[len(instance.events)-h.config.MaxEvents:]
	}
	subscribers := make([]*EventSubscription, 0, len(instance.subscribers))
	for subscriber := range instance.subscribers {
		subscribers = append(subscribers, subscriber)
	}
	for _, subscriber := range subscribers {
		candidate := cloneEvent(event)
		if subscriber.filter != nil && !subscriber.filter(candidate) {
			continue
		}
		h.enqueueLocked(subscriber, candidate)
	}
	h.mu.Unlock()

	event.Data = cloneRawMessage(event.Data)
	return event, nil
}

func validatePublishedEvent(instanceID string, input EventInput) error {
	if instanceID == "" || strings.ContainsAny(instanceID, "\r\n") {
		return fmt.Errorf("%w: instance id is required", ErrInvalidEvent)
	}
	typ := strings.TrimSpace(input.Type)
	if typ == "" || strings.ContainsAny(typ, "\r\n") {
		return fmt.Errorf("%w: event type is required", ErrInvalidEvent)
	}
	return nil
}

func marshalEventData(data any, maxBytes int) (json.RawMessage, error) {
	encoded, err := json.Marshal(data)
	if err != nil {
		return nil, fmt.Errorf("%w: marshal data: %v", ErrInvalidEvent, err)
	}
	if len(encoded) > maxBytes {
		return nil, fmt.Errorf("%w: got %d bytes, limit is %d", ErrEventPayloadTooLarge, len(encoded), maxBytes)
	}
	return json.RawMessage(encoded), nil
}

func (h *EventHub) instanceLocked(instanceID string) *eventInstance {
	instance := h.instances[instanceID]
	if instance == nil {
		instance = &eventInstance{subscribers: make(map[*EventSubscription]struct{})}
		h.instances[instanceID] = instance
	}
	return instance
}

func (i *eventInstance) purgeExpired(now time.Time, window time.Duration) {
	cutoff := now.Add(-window)
	index := 0
	for index < len(i.events) && i.events[index].publishedAt().Before(cutoff) {
		index++
	}
	if index > 0 {
		i.events = i.events[index:]
	}
}

func (e Event) publishedAt() time.Time {
	return e.published
}

func (h *EventHub) enqueueLocked(subscriber *EventSubscription, event Event) {
	select {
	case subscriber.events <- event:
	default:
		h.removeSubscriptionLocked(subscriber, ErrSlowSubscriber)
	}
}

// Subscribe creates a bounded stream and queues any complete replay range
// before returning. A cancellable context owns the subscription and releases
// it without requiring a timeout or a separate cleanup call.
func (h *EventHub) Subscribe(ctx context.Context, request EventSubscriptionRequest) (*EventSubscription, error) {
	if h == nil {
		return nil, ErrEventHubClosed
	}
	if ctx == nil {
		ctx = context.Background()
	}
	if err := ctx.Err(); err != nil {
		return nil, err
	}
	request.InstanceID = strings.TrimSpace(request.InstanceID)
	request.UserID = strings.TrimSpace(request.UserID)
	if request.InstanceID == "" || request.UserID == "" || strings.ContainsAny(request.InstanceID+request.UserID, "\r\n") {
		return nil, ErrInvalidSubscription
	}

	h.mu.Lock()
	if h.closed {
		h.mu.Unlock()
		return nil, ErrEventHubClosed
	}
	key := eventStreamKey{userID: request.UserID, instanceID: request.InstanceID}
	if h.userStreams[request.UserID] >= h.config.MaxStreamsPerUser || h.userInstanceStreams[key] >= h.config.MaxStreamsPerUserInstance {
		h.mu.Unlock()
		return nil, ErrTooManyEventStreams
	}
	instance := h.instanceLocked(request.InstanceID)
	instance.purgeExpired(h.now().UTC(), h.config.ReplayWindow)
	replay, resyncReason := h.replayLocked(instance, request)
	queueSize := h.config.SubscriberQueueSize
	initialEvents := len(replay)
	if resyncReason != "" {
		initialEvents++
	}
	if queueSize <= initialEvents {
		queueSize = initialEvents + 1
	}
	subscriber := &EventSubscription{
		hub:        h,
		instanceID: request.InstanceID,
		userID:     request.UserID,
		events:     make(chan Event, queueSize),
		done:       make(chan struct{}),
		filter:     request.Filter,
	}
	instance.subscribers[subscriber] = struct{}{}
	h.userStreams[request.UserID]++
	h.userInstanceStreams[key]++
	if resyncReason != "" {
		h.enqueueLocked(subscriber, newResyncEvent(request.InstanceID, h.generation, resyncReason))
	} else {
		for _, event := range replay {
			h.enqueueLocked(subscriber, event)
		}
	}
	h.mu.Unlock()

	watchSubscriptionContext(ctx, subscriber)
	return subscriber, nil
}

func (h *EventHub) replayLocked(instance *eventInstance, request EventSubscriptionRequest) ([]Event, string) {
	lastID := strings.TrimSpace(request.LastEventID)
	if lastID == "" {
		return nil, ""
	}
	generation, sequence, ok := ParseEventID(lastID)
	if !ok {
		return nil, ResyncReasonInvalidCursor
	}
	if generation != h.generation {
		return nil, ResyncReasonGenerationMismatch
	}
	if sequence > instance.lastSequence {
		return nil, ResyncReasonCursorAhead
	}
	if len(instance.events) == 0 {
		if sequence < instance.lastSequence {
			return nil, ResyncReasonHistoryGap
		}
		return nil, ""
	}
	oldest := instance.events[0].Sequence
	if sequence < oldest-1 {
		return nil, ResyncReasonHistoryGap
	}
	replay := make([]Event, 0, len(instance.events))
	for _, event := range instance.events {
		if event.Sequence <= sequence {
			continue
		}
		candidate := cloneEvent(event)
		if request.Filter == nil || request.Filter(candidate) {
			replay = append(replay, candidate)
		}
	}
	return replay, ""
}

func newResyncEvent(instanceID, generation, reason string) Event {
	data, _ := json.Marshal(ResyncInfo{Reason: reason, Generation: generation, Reset: true})
	return Event{
		Generation: generation,
		Type:       RuntimeResyncRequired,
		Scope:      EventScope{InstanceID: instanceID},
		Data:       data,
	}
}

func watchSubscriptionContext(ctx context.Context, subscriber *EventSubscription) {
	if ctx.Done() == nil {
		return
	}
	go func() {
		select {
		case <-ctx.Done():
			_ = subscriber.closeWithError(ctx.Err())
		case <-subscriber.done:
		}
	}()
}

// Events returns the replay and live event queue. It is closed when the
// subscription is canceled, explicitly closed, the hub closes, or a slow
// consumer is disconnected.
func (s *EventSubscription) Events() <-chan Event {
	if s == nil {
		return nil
	}
	return s.events
}

// Done closes with the event queue and is useful to join cancellation cleanup
// in callers that consume Events directly.
func (s *EventSubscription) Done() <-chan struct{} {
	if s == nil {
		return nil
	}
	return s.done
}

// Err reports why the subscription was closed, if it was closed abnormally.
func (s *EventSubscription) Err() error {
	if s == nil {
		return nil
	}
	s.stateMu.RLock()
	defer s.stateMu.RUnlock()
	return s.err
}

// IsClosed reports whether the subscription no longer accepts events.
func (s *EventSubscription) IsClosed() bool {
	if s == nil {
		return true
	}
	s.stateMu.RLock()
	defer s.stateMu.RUnlock()
	return s.closed
}

// Close releases the subscription. It is safe to call more than once.
func (s *EventSubscription) Close() error {
	return s.closeWithError(nil)
}

// Unsubscribe is an alias for Close for callers that use subscription-style
// terminology.
func (s *EventSubscription) Unsubscribe() error {
	return s.Close()
}

func (s *EventSubscription) closeWithError(err error) error {
	if s == nil || s.hub == nil {
		return nil
	}
	s.hub.mu.Lock()
	s.hub.removeSubscriptionLocked(s, err)
	s.hub.mu.Unlock()
	return nil
}

func (h *EventHub) removeSubscriptionLocked(subscriber *EventSubscription, err error) {
	instance := h.instances[subscriber.instanceID]
	if instance != nil {
		if _, active := instance.subscribers[subscriber]; active {
			delete(instance.subscribers, subscriber)
			key := eventStreamKey{userID: subscriber.userID, instanceID: subscriber.instanceID}
			decrementCount(h.userStreams, subscriber.userID)
			decrementCount(h.userInstanceStreams, key)
		}
	}
	subscriber.closeLocked(err)
}

func decrementCount[K comparable](counts map[K]int, key K) {
	if counts[key] <= 1 {
		delete(counts, key)
		return
	}
	counts[key]--
}

func (s *EventSubscription) closeLocked(err error) {
	s.stateMu.Lock()
	defer s.stateMu.Unlock()
	if s.closed {
		return
	}
	s.closed = true
	s.err = err
	close(s.events)
	close(s.done)
}

// Close terminates the hub and all of its subscriptions. It does not wait on
// consumers or publishers because no hub operation performs a blocking send.
func (h *EventHub) Close() {
	if h == nil {
		return
	}
	h.mu.Lock()
	defer h.mu.Unlock()
	if h.closed {
		return
	}
	h.closed = true
	for _, instance := range h.instances {
		for subscriber := range instance.subscribers {
			subscriber.closeLocked(ErrEventHubClosed)
		}
	}
	h.instances = make(map[string]*eventInstance)
	h.userStreams = make(map[string]int)
	h.userInstanceStreams = make(map[eventStreamKey]int)
}

// Handler binds an authorized instance/user/filter tuple to a standard
// net/http handler. The request's Last-Event-ID header is preferred over the
// bound request value, and no query-token handling is provided here.
func (h *EventHub) Handler(request EventSubscriptionRequest) http.Handler {
	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		h.Serve(w, r, request)
	})
}

// Serve writes one SSE stream for an authorized subscription request.
func (h *EventHub) Serve(w http.ResponseWriter, r *http.Request, request EventSubscriptionRequest) {
	if h == nil {
		writeEventStreamError(w, http.StatusServiceUnavailable, ErrEventHubClosed)
		return
	}
	if !validEventStreamRequest(w, r) {
		return
	}
	flusher, ok := eventStreamFlusher(w)
	if !ok {
		return
	}
	request = eventStreamRequest(r, request)
	subscriber, err := h.Subscribe(r.Context(), request)
	if err != nil {
		writeEventStreamError(w, eventStreamErrorStatus(err), err)
		return
	}
	defer func() { _ = subscriber.Close() }()
	h.stream(w, r, flusher, subscriber)
}

func validEventStreamRequest(w http.ResponseWriter, r *http.Request) bool {
	if r != nil && r.Method == http.MethodGet {
		return true
	}
	if w != nil {
		w.Header().Set("Allow", http.MethodGet)
	}
	writeEventStreamError(w, http.StatusMethodNotAllowed, ErrInvalidSubscription)
	return false
}

func eventStreamFlusher(w http.ResponseWriter) (http.Flusher, bool) {
	flusher, ok := w.(http.Flusher)
	if !ok {
		writeEventStreamError(w, http.StatusInternalServerError, errors.New("webapp: SSE requires response flushing"))
		return nil, false
	}
	return flusher, true
}

func eventStreamRequest(r *http.Request, request EventSubscriptionRequest) EventSubscriptionRequest {
	if headerID := strings.TrimSpace(r.Header.Get("Last-Event-ID")); headerID != "" {
		request.LastEventID = headerID
	}
	return request
}

func (h *EventHub) stream(w http.ResponseWriter, r *http.Request, flusher http.Flusher, subscriber *EventSubscription) {

	w.Header().Set("Content-Type", "text/event-stream")
	w.Header().Set("Cache-Control", "no-cache, no-transform")
	w.Header().Set("Connection", "keep-alive")
	w.Header().Set("X-Accel-Buffering", "no")
	w.WriteHeader(http.StatusOK)
	flusher.Flush()

	ticker := time.NewTicker(h.config.HeartbeatInterval)
	defer ticker.Stop()
	var lifetime <-chan time.Time
	var timer *time.Timer
	if h.config.StreamLifetime > 0 {
		timer = time.NewTimer(h.config.StreamLifetime)
		defer timer.Stop()
		lifetime = timer.C
	}
	for {
		select {
		case event, open := <-subscriber.Events():
			if !open {
				return
			}
			if err := writeSSE(w, event); err != nil {
				return
			}
			flusher.Flush()
		case <-ticker.C:
			if _, err := io.WriteString(w, ": heartbeat\n\n"); err != nil {
				return
			}
			flusher.Flush()
		case <-r.Context().Done():
			return
		case <-lifetime:
			return
		}
	}
}

func writeSSE(w io.Writer, event Event) error {
	data, err := json.Marshal(event)
	if err != nil {
		return err
	}
	var stream strings.Builder
	if event.ID == "" && event.Type == RuntimeResyncRequired {
		stream.WriteString("id:\n")
	} else if event.ID != "" {
		stream.WriteString("id: ")
		stream.WriteString(event.ID)
		stream.WriteByte('\n')
	}
	stream.WriteString("event: ")
	stream.WriteString(event.Type)
	stream.WriteString("\ndata: ")
	stream.Write(data)
	stream.WriteString("\n\n")
	_, err = io.WriteString(w, stream.String())
	return err
}

func eventStreamErrorStatus(err error) int {
	switch {
	case errors.Is(err, ErrEventHubClosed):
		return http.StatusServiceUnavailable
	case errors.Is(err, ErrTooManyEventStreams):
		return http.StatusTooManyRequests
	case errors.Is(err, ErrInvalidSubscription):
		return http.StatusBadRequest
	default:
		return http.StatusInternalServerError
	}
}

func writeEventStreamError(w http.ResponseWriter, status int, err error) {
	if w == nil {
		return
	}
	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
	http.Error(w, err.Error(), status)
}

// ParseEventID decodes the generation and sequence assigned by Publish.
func ParseEventID(id string) (generation string, sequence uint64, ok bool) {
	id = strings.TrimSpace(id)
	separator := strings.LastIndexByte(id, ':')
	if separator <= 0 || separator == len(id)-1 {
		return "", 0, false
	}
	generation = id[:separator]
	sequence, err := strconv.ParseUint(id[separator+1:], 10, 64)
	if err != nil || sequence == 0 || !validGeneration(generation) {
		return "", 0, false
	}
	return generation, sequence, true
}

func formatEventID(generation string, sequence uint64) string {
	return generation + ":" + strconv.FormatUint(sequence, 10)
}

func cloneEvent(event Event) Event {
	event.Data = cloneRawMessage(event.Data)
	return event
}

func cloneRawMessage(data json.RawMessage) json.RawMessage {
	if data == nil {
		return nil
	}
	return append(json.RawMessage(nil), data...)
}