@softwaredevelopment/bodhi-library-presence

Valkey-backed connection-presence registry for the bodhi Cat-1 sticky-routing services (bodhi-service-api, bodhi-service-notifications, bodhi-service-notify-v2).

Key shape: bws:conn:${scope}:${audienceKey} → ${podName}, TTL 30s, refreshed every 10s. Used by senders to look up the pod currently holding a given audience's WS/SSE connection.

Usage

import { PresenceModule, PresenceService } from '@softwaredevelopment/bodhi-library-presence';

@Module({
  imports: [PresenceModule.register()],  // reads VALKEY_URL + POD_NAME from env
})
export class AppModule {}

@Injectable()
export class SocketGateway {
  constructor(private readonly presence: PresenceService) {}

  async onConnect(audienceKey: string) {
    // Caller must assert any per-pod RabbitMQ queue BEFORE this register call.
    await this.presence.register('user', audienceKey);
  }

  async onDisconnect(audienceKey: string) {
    await this.presence.unregister('user', audienceKey);
  }
}

// Sender side:
const podName = await presence.lookup('user', audienceKey);
if (podName) {
  await channel.publish('', `events-bodhi-service-api-${podName}`, payload);
}

Required env

• VALKEY_URL — Valkey connection URL.
• POD_NAME — set via Kubernetes downward API fieldRef: metadata.name.

Metrics

• bws_presence_lookup_total{result=hit|miss|error}
• bws_presence_lookup_latency_seconds
• bws_presence_register_total{result=ok|error}
• bws_presence_heartbeat_total{result=ok|error}

Tests

• yarn test — unit tests (uses ioredis-mock; no Docker required)

• Integration tests live in src/__tests__/presence.integration.test.ts and require Docker. Run them with:

  yarn jest --testPathPattern=integration

  The default yarn test excludes *.integration.test.ts via testPathIgnorePatterns in jest.config.js.

Related

• Epic: BSIN-61
• Phase 2 design: ~/Developer/bodhi/docs/2026-06-17-bws-hostname-aks-phase2-design.md
• Phase 2 plan: ~/Developer/bodhi/docs/superpowers/plans/2026-06-17-bws-hostname-aks-phase2-plan.md