Socket Event Listener

Anti-patterns

• Adding the listener in :infra:socket:impl. Don't. Socket impl is generic plumbing only; the only listener that lives there is the universal SocketEventLogger.

  // ❌ DON'T: infra/socket/impl/.../MyFeatureListener.kt

• Implementing Scoped and rolling your own collect. This was the pre-dispatcher pattern. With the dispatcher, it duplicates work and creates a second collector subscribed to the same SharedFlow.

  // ❌ DON'T
  @ContributesIntoSet(UserScope::class, binding = binding<Scoped>())
  class MyFeatureListener(
    private val socketManager: SocketManager,
    @ForScope(UserScope::class) private val scopeHolder: CoroutineScopeHolder,
    private val repo: MyRepo,
  ) : Scoped {
    override suspend fun onCreate() {
      scopeHolder.get().launch {
        socketManager.events.filterIsInstance<MyEvent>().collect { repo.upsert(it) }
      }
    }
  }

• Injecting SocketManager directly. The point of the dispatcher is that listeners never see the socket — they get events handed to them. Injecting it means you're about to bypass the dispatcher.

• One listener per event type. Five Removed events from the library family don't need five listener classes. One LibraryCacheInvalidator : SocketEventListener with a when block covering all of them is clearer and bundles related cache invalidation into one place.

  // ✅ Preferred — one listener, multi-event when
  override suspend fun handle(event: SocketEvent) {
    when (event) {
      is ItemAdded, is ItemUpdated, is ItemRemoved,
      is ItemsAdded, is ItemsUpdated -> libraryStore.invalidate()
      is LibraryAdded, is LibraryUpdated, is LibraryRemoved -> libraryListStore.invalidate()
      else -> Unit
    }
  }

• Throwing as a signal. throw IgnoreEvent() to skip an event is wrong — just return/Unit. Throws go to the dispatcher's error log.

• Mutating shared state without synchronization. Multiple listeners run in parallel coroutines. If two listeners write to the same in-memory cache, you need a Mutex or atomic primitives. Most repos / Stores already handle this internally — but if you're rolling your own, beware.

Concurrency model (so you don't get surprised)

• One long-lived coroutine per listener, launched at UserScope creation, cancelled at logout.
• Each listener has its own socketManager.events.collect. Events flow into all listeners concurrently.
• Within a listener, handle() calls are sequential — event N must finish before event N+1 starts for that listener.
• The underlying MutableSharedFlow has extraBufferCapacity = 64. If your listener falls behind by >64 events, tryEmit upstream starts returning false and events get dropped at the source for all listeners. In practice this never happens for socket events, but don't do anything in handle() that takes seconds.

When to apply

• Authoring a class that reacts to ABS socket events → use this pattern.
• User asks "wire <feature> to react to <event> updates" → drop a SocketEventListener impl in the feature's impl module.
• Reviewing a PR that touches :infra:socket:impl to add feature-specific reactions → push back; that work belongs in the feature module.
• Migrating an existing manual events.filterIsInstance<X>().collect { ... } subscriber (if any exist) → consolidate it into a SocketEventListener.

Auditing the codebase

# Find all socket consumers
rg -l ': SocketEventListener' --type kt -g '!*/build/*'

# Find manual subscribers that should be migrated to the dispatcher
rg 'socketManager\.events' --type kt -g '!*/build/*' -g '!*/infra/socket/*'

The latter should return zero hits outside :infra:socket:impl (the dispatcher itself) and the test module. Any hit elsewhere is a pre-dispatcher subscriber that should be refactored to a SocketEventListener.