@furystack/rest-service 13.0.0 → 14.1.0

package/src/identity-event-bus.ts

@@ -0,0 +1,230 @@
+import { CrossNodeBus, type BusMessage } from '@furystack/cross-node-bus'
+import { defineService, type Token } from '@furystack/inject'
+import { sessionCacheKey } from './identity-cache-keys.js'
+import { UserResolutionCache } from './user-resolution-cache.js'
+
+/**
+ * Wire topic the facade publishes to and subscribes from on the underlying
+ * {@link CrossNodeBus}. A single topic is used for all event types — internal
+ * dispatch happens by `event.type`. Keeping one topic minimises broker
+ * subscriptions on networked adapters (Redis Streams, NATS) and matches the
+ * EventHub-style fan-out apps already use.
+ */
+export const IDENTITY_EVENT_TOPIC = 'identity/events'
+
+/**
+ * Discriminated union of cross-node identity events. Adding a new variant
+ * **must** also extend {@link applyLocalIdentityInvalidation} so the local
+ * cache stays in sync with the published intent.
+ *
+ * - `userLoggedOut` / `sessionInvalidated` invalidate the cache entry for a
+ *   single session id (same shape — `sessionInvalidated` is meant for
+ *   admin / forced flows where a session row is dropped server-side).
+ * - `userRolesChanged` / `userDeleted` / `passwordChanged` invalidate every
+ *   cached entry that resolved to the named user, regardless of which
+ *   session originally populated it.
+ */
+export type IdentityEvent =
+  | { type: 'userLoggedOut'; sessionId: string }
+  | { type: 'sessionInvalidated'; sessionId: string }
+  | { type: 'userRolesChanged'; username: string }
+  | { type: 'userDeleted'; username: string }
+  | { type: 'passwordChanged'; username: string }
+
+/**
+ * Cross-node identity event facade. Bridges the per-process
+ * {@link UserResolutionCache} to the shared {@link CrossNodeBus} so that
+ * logouts, role flips, password resets and account deletions invalidate
+ * cached identities across every node, not just the one that originated
+ * the change.
+ *
+ * Publishing collapses the staleness window from `userCacheTtlMs`
+ * (default 30 s) to bus latency (single-digit ms with Redis pub/sub).
+ *
+ * **Self-delivery contract.** {@link IdentityEventBus.publish} applies the
+ * matching local invalidation and fires local subscribers synchronously
+ * **before** awaiting the bus. Sibling nodes receive the message via a
+ * `subscribeRemoteOnly` bridge — own publishes never round-trip through the
+ * transport, so duplicate work is impossible.
+ *
+ * @example
+ * ```ts
+ * import type { Injector } from '@furystack/inject'
+ * import { IdentityEventBus } from '@furystack/rest-service'
+ *
+ * declare const injector: Injector
+ * const bus = injector.get(IdentityEventBus)
+ *
+ * using sub = bus.subscribe('userRolesChanged', ({ username }) => {
+ *   console.log('roles changed for', username)
+ * })
+ *
+ * await bus.publish({ type: 'userRolesChanged', username: 'alice' })
+ * ```
+ */
+export interface IdentityEventBus extends Disposable {
+  /**
+   * Publishes a typed identity event. Applies the matching local cache
+   * invalidation synchronously, fires local subscribers synchronously, then
+   * awaits the underlying bus broadcast. Resolves once the message has been
+   * accepted by the transport.
+   */
+  publish(event: IdentityEvent): Promise<void>
+
+  /**
+   * Subscribes to a single event type. Local emits and bus-delivered messages
+   * from sibling nodes both fire the handler. Returns a `Disposable` that
+   * removes the listener on dispose.
+   */
+  subscribe<TType extends IdentityEvent['type']>(
+    type: TType,
+    handler: (event: Extract<IdentityEvent, { type: TType }>) => void,
+  ): Disposable
+}
+
+/**
+ * Applies the cache invalidation that corresponds to `event` against
+ * `userCache`. Centralised so the publish path and the remote-receive path
+ * cannot drift — both call this single helper. Exported for the rare
+ * subsystem (e.g. websocket-api logout-driven socket close) that consumes
+ * an {@link IdentityEvent} and needs to mirror the cache effect.
+ */
+export const applyLocalIdentityInvalidation = (event: IdentityEvent, userCache: UserResolutionCache): void => {
+  switch (event.type) {
+    case 'userLoggedOut':
+    case 'sessionInvalidated':
+      userCache.invalidate(sessionCacheKey(event.sessionId))
+      return
+    case 'userRolesChanged':
+    case 'userDeleted':
+    case 'passwordChanged':
+      userCache.invalidateByUser(event.username)
+      return
+    default: {
+      // Exhaustiveness check: every variant of {@link IdentityEvent} above
+      // must be handled. Adding a new variant without updating this switch
+      // will fail to compile.
+      const _exhaustive: never = event
+      void _exhaustive
+    }
+  }
+}
+
+const isIdentityEvent = (value: unknown): value is IdentityEvent => {
+  if (typeof value !== 'object' || value === null) return false
+  const candidate = value as { type?: unknown; sessionId?: unknown; username?: unknown }
+  switch (candidate.type) {
+    case 'userLoggedOut':
+    case 'sessionInvalidated':
+      return typeof candidate.sessionId === 'string'
+    case 'userRolesChanged':
+    case 'userDeleted':
+    case 'passwordChanged':
+      return typeof candidate.username === 'string'
+    default:
+      return false
+  }
+}
+
+type AnyIdentityHandler = (event: IdentityEvent) => void
+
+class IdentityEventBusImpl implements IdentityEventBus {
+  readonly #bus: CrossNodeBus
+  readonly #userCache: UserResolutionCache
+  readonly #handlers: Map<IdentityEvent['type'], Set<AnyIdentityHandler>> = new Map()
+  readonly #busSubscription: Disposable
+  #disposed = false
+
+  constructor(bus: CrossNodeBus, userCache: UserResolutionCache) {
+    this.#bus = bus
+    this.#userCache = userCache
+    // subscribeRemoteOnly: own publishes invalidate locally inline, so we
+    // only handle messages originating on sibling nodes here.
+    this.#busSubscription = bus.subscribeRemoteOnly(IDENTITY_EVENT_TOPIC, (message) => this.#receive(message))
+  }
+
+  public async publish(event: IdentityEvent): Promise<void> {
+    if (this.#disposed) {
+      throw new Error('IdentityEventBus has been disposed')
+    }
+    applyLocalIdentityInvalidation(event, this.#userCache)
+    this.#emit(event)
+    await this.#bus.publish(IDENTITY_EVENT_TOPIC, event)
+  }
+
+  public subscribe<TType extends IdentityEvent['type']>(
+    type: TType,
+    handler: (event: Extract<IdentityEvent, { type: TType }>) => void,
+  ): Disposable {
+    let handlers = this.#handlers.get(type)
+    if (!handlers) {
+      handlers = new Set()
+      this.#handlers.set(type, handlers)
+    }
+    const wrapped: AnyIdentityHandler = (event) => handler(event as Extract<IdentityEvent, { type: TType }>)
+    handlers.add(wrapped)
+    return {
+      [Symbol.dispose]: () => {
+        const current = this.#handlers.get(type)
+        if (!current) return
+        current.delete(wrapped)
+        if (current.size === 0) this.#handlers.delete(type)
+      },
+    }
+  }
+
+  public [Symbol.dispose](): void {
+    if (this.#disposed) return
+    this.#disposed = true
+    this.#busSubscription[Symbol.dispose]()
+    this.#handlers.clear()
+  }
+
+  #receive(message: BusMessage): void {
+    const { payload } = message
+    if (!isIdentityEvent(payload)) {
+      // Foreign or future-version messages are silently ignored — older nodes
+      // see new event types as no-ops, which is the documented dual-accept
+      // behaviour from the cross-node-bus PRD §12.
+      return
+    }
+    applyLocalIdentityInvalidation(payload, this.#userCache)
+    this.#emit(payload)
+  }
+
+  #emit(event: IdentityEvent): void {
+    const handlers = this.#handlers.get(event.type)
+    if (!handlers) return
+    // Snapshot so a handler that disposes its own subscription mid-emit can't
+    // mutate the iterator. Listener errors are isolated per-handler and
+    // logged — one throwing handler must not poison its peers.
+    for (const handler of [...handlers]) {
+      try {
+        handler(event)
+      } catch (error) {
+        console.error('IdentityEventBus listener threw', { type: event.type, error })
+      }
+    }
+  }
+}
+
+/**
+ * Singleton DI token for the {@link IdentityEventBus}. Resolves a facade that
+ * shares the injector's {@link CrossNodeBus} binding — apps that have not
+ * bound a transport adapter run against the in-process default and
+ * single-node deployments work without configuration.
+ */
+export const IdentityEventBus: Token<IdentityEventBus, 'singleton'> = defineService({
+  name: 'furystack/rest-service/IdentityEventBus',
+  lifetime: 'singleton',
+  factory: ({ inject, onDispose }): IdentityEventBus => {
+    const bus = inject(CrossNodeBus)
+    const userCache = inject(UserResolutionCache)
+    const impl = new IdentityEventBusImpl(bus, userCache)
+    onDispose(() => {
+      // eslint-disable-next-line furystack/prefer-using-wrapper -- onDispose is the teardown hook
+      impl[Symbol.dispose]()
+    })
+    return impl
+  },
+})

package/src/index.ts

@@ -1,6 +1,5 @@
 export * from './actions/index.js'
 export * from './add-cors-header.js'
-export * from './api-manager.js'
 export * from './authenticate.js'
 export * from './authentication-providers/index.js'
 export * from './authorize.js'
@@ -8,15 +7,21 @@ export * from './endpoint-generators/index.js'
 export * from './get-schema-from-api.js'
 export * from './helpers.js'
 export * from './http-authentication-settings.js'
+export * from './http-server-pool.js'
 export * from './http-user-context.js'
+export * from './identity-cache-keys.js'
+export * from './identity-event-bus.js'
 export * from './login-response-strategy.js'
 export * from './mime-types.js'
 export * from './models/index.js'
-export * from './proxy-manager.js'
+export * from './proxy-runtime.js'
 export * from './read-post-body.js'
 export * from './request-action-implementation.js'
+export * from './rest-api-runtime.js'
 export * from './schema-validator/index.js'
-export * from './server-manager.js'
 export * from './server-response-extensions.js'
-export * from './static-server-manager.js'
+export * from './server-telemetry.js'
+export * from './static-site-runtime.js'
+export * from './user-resolution-cache.js'
+export * from './user-store.js'
 export * from './validate.js'

package/src/login-response-strategy.spec.ts

@@ -1,25 +1,25 @@
-import { InMemoryStore, User, addStore } from '@furystack/core'
-import { Injector } from '@furystack/inject'
-import { getRepository } from '@furystack/repository'
-import { PasswordCredential, PasswordResetToken, usePasswordPolicy } from '@furystack/security'
+import type { User } from '@furystack/core'
+import { InMemoryStore, User as UserModel, useSystemIdentityContext } from '@furystack/core'
+import { createInjector, type Injector } from '@furystack/inject'
+import {
+  PasswordCredential,
+  PasswordCredentialStore,
+  PasswordResetToken,
+  PasswordResetTokenStore,
+  usePasswordPolicy,
+} from '@furystack/security'
 import { usingAsync } from '@furystack/utils'
 import { describe, expect, it } from 'vitest'
-
 import { useHttpAuthentication } from './helpers.js'
 import { createCookieLoginStrategy } from './login-response-strategy.js'
 import { DefaultSession } from './models/default-session.js'
+import { SessionDataSet, SessionStore, UserStore } from './user-store.js'
 
 const setupInjector = (i: Injector) => {
-  addStore(i, new InMemoryStore({ model: User, primaryKey: 'username' }))
-    .addStore(new InMemoryStore({ model: DefaultSession, primaryKey: 'sessionId' }))
-    .addStore(new InMemoryStore({ model: PasswordCredential, primaryKey: 'userName' }))
-    .addStore(new InMemoryStore({ model: PasswordResetToken, primaryKey: 'token' }))
-
-  const repo = getRepository(i)
-  repo.createDataSet(User, 'username')
-  repo.createDataSet(DefaultSession, 'sessionId')
-  repo.createDataSet(PasswordCredential, 'userName')
-  repo.createDataSet(PasswordResetToken, 'token')
+  i.bind(UserStore, () => new InMemoryStore({ model: UserModel, primaryKey: 'username' }))
+  i.bind(SessionStore, () => new InMemoryStore({ model: DefaultSession, primaryKey: 'sessionId' }))
+  i.bind(PasswordCredentialStore, () => new InMemoryStore({ model: PasswordCredential, primaryKey: 'userName' }))
+  i.bind(PasswordResetTokenStore, () => new InMemoryStore({ model: PasswordResetToken, primaryKey: 'token' }))
 
   usePasswordPolicy(i)
   useHttpAuthentication(i)
@@ -28,8 +28,8 @@ const setupInjector = (i: Injector) => {
 describe('createCookieLoginStrategy', () => {
   const testUser: User = { username: 'testuser', roles: ['admin'] }
 
-  it('Should return the user as the response body', async () => {
-    await usingAsync(new Injector(), async (i) => {
+  it('returns the user as the response body', async () => {
+    await usingAsync(createInjector(), async (i) => {
       setupInjector(i)
       const strategy = createCookieLoginStrategy(i)
       const result = await strategy.createLoginResponse(testUser, i)
@@ -37,8 +37,8 @@ describe('createCookieLoginStrategy', () => {
     })
   })
 
-  it('Should return status code 200', async () => {
-    await usingAsync(new Injector(), async (i) => {
+  it('returns status code 200', async () => {
+    await usingAsync(createInjector(), async (i) => {
       setupInjector(i)
       const strategy = createCookieLoginStrategy(i)
       const result = await strategy.createLoginResponse(testUser, i)
@@ -46,8 +46,8 @@ describe('createCookieLoginStrategy', () => {
     })
   })
 
-  it('Should include a Set-Cookie header with the session ID', async () => {
-    await usingAsync(new Injector(), async (i) => {
+  it('emits a Set-Cookie header with the generated session id', async () => {
+    await usingAsync(createInjector(), async (i) => {
       setupInjector(i)
       const strategy = createCookieLoginStrategy(i)
       const result = await strategy.createLoginResponse(testUser, i)
@@ -59,23 +59,24 @@ describe('createCookieLoginStrategy', () => {
     })
   })
 
-  it('Should persist the session in the DataSet', async () => {
-    await usingAsync(new Injector(), async (i) => {
+  it('persists the session via SessionDataSet', async () => {
+    await usingAsync(createInjector(), async (i) => {
       setupInjector(i)
       const strategy = createCookieLoginStrategy(i)
       await strategy.createLoginResponse(testUser, i)
 
-      const repo = getRepository(i)
-      const sessionDataSet = repo.getDataSetFor(DefaultSession, 'sessionId')
-      const sessions = await sessionDataSet.find(i, { filter: { username: { $eq: 'testuser' } } })
-      expect(sessions).toHaveLength(1)
-      expect(sessions[0].username).toBe('testuser')
-      expect(sessions[0].sessionId).toBeTruthy()
+      await usingAsync(useSystemIdentityContext({ injector: i, username: 'spec' }), async (systemScope) => {
+        const sessionDataSet = systemScope.get(SessionDataSet)
+        const sessions = await sessionDataSet.find(systemScope, { filter: { username: { $eq: 'testuser' } } })
+        expect(sessions).toHaveLength(1)
+        expect(sessions[0].username).toBe('testuser')
+        expect(sessions[0].sessionId).toBeTruthy()
+      })
     })
   })
 
-  it('Should create unique session IDs for each call', async () => {
-    await usingAsync(new Injector(), async (i) => {
+  it('creates unique session ids for each call', async () => {
+    await usingAsync(createInjector(), async (i) => {
       setupInjector(i)
       const strategy = createCookieLoginStrategy(i)
 

package/src/login-response-strategy.ts

@@ -3,20 +3,21 @@ import { useSystemIdentityContext } from '@furystack/core'
 import type { Injector } from '@furystack/inject'
 import { randomBytes } from 'crypto'
 
+import type { createPasswordLoginAction } from './actions/password-login-action.js'
 import { HttpAuthenticationSettings } from './http-authentication-settings.js'
 import type { ActionResult } from './request-action-implementation.js'
 import { JsonResult } from './request-action-implementation.js'
 
 /**
  * A pluggable strategy that turns an authenticated {@link User} into an
- * {@link ActionResult} containing the session/token data for the client.
+ * {@link ActionResult} carrying the session/token payload for the client.
  *
- * Pass a concrete strategy to action factories like
- * {@link createPasswordLoginAction} or `createGoogleLoginAction` to
- * decouple the authentication mechanism from the session/token mechanism.
+ * Pass a concrete strategy to action factories such as
+ * {@link createPasswordLoginAction} or `createGoogleLoginAction` to decouple
+ * the authentication mechanism from the session/token mechanism.
  *
- * @typeParam TResult The shape of the response body (e.g. `User` for cookies,
- *   `{ accessToken: string; refreshToken: string }` for JWT)
+ * @typeParam TResult The shape of the response body — e.g. `User` for
+ *   cookies, `{ accessToken, refreshToken }` for JWT.
  */
 export type LoginResponseStrategy<TResult> = {
   createLoginResponse: (user: User, injector: Injector) => Promise<ActionResult<TResult>>
@@ -25,19 +26,20 @@ export type LoginResponseStrategy<TResult> = {
 /**
  * Creates a cookie-based {@link LoginResponseStrategy}.
  *
- * On each login it generates a random session ID, persists it in the session
- * DataSet, and returns the user with a `Set-Cookie` header.
+ * On each login it generates a random session id, persists it via the
+ * configured session DataSet and returns the user with a `Set-Cookie`
+ * response header.
  *
- * @param injector The root injector (must have {@link HttpAuthenticationSettings} configured)
- * @returns A strategy that returns `ActionResult<User>`
+ * @param injector - The injector scope (typically the root) that carries
+ *   `HttpAuthenticationSettings` and a persistent session store.
  */
 export const createCookieLoginStrategy = (injector: Injector): LoginResponseStrategy<User> => {
-  const settings = injector.getInstance(HttpAuthenticationSettings)
+  const settings = injector.get(HttpAuthenticationSettings)
   const systemInjector = useSystemIdentityContext({ injector, username: 'CookieLoginStrategy' })
+  const sessionDataSet = systemInjector.get(settings.sessionDataSet)
 
   return {
     createLoginResponse: async (user) => {
-      const sessionDataSet = settings.getSessionDataSet(systemInjector)
       const sessionId = randomBytes(32).toString('hex')
       await sessionDataSet.add(systemInjector, { sessionId, username: user.username })
       return JsonResult(user, 200, {

package/src/openapi/generate-openapi-document.spec.ts

@@ -275,7 +275,7 @@ describe('generateOpenApiDocument', () => {
     it('Should use generic object schema when no schemaName', () => {
       const api: ApiEndpointSchema['endpoints'] = {
         GET: {
-          '/test': { path: '/test', isAuthenticated: false, schemaName: '', schema: null as unknown },
+          '/test': { path: '/test', isAuthenticated: false, schemaName: '', schema: null },
         },
       }
 
@@ -300,7 +300,7 @@ describe('generateOpenApiDocument', () => {
     it('Should not add schema to components when schema is falsy', () => {
       const api: ApiEndpointSchema['endpoints'] = {
         GET: {
-          '/test': { path: '/test', isAuthenticated: false, schemaName: 'Empty', schema: null as unknown },
+          '/test': { path: '/test', isAuthenticated: false, schemaName: 'Empty', schema: null },
         },
       }