@furystack/rest-service 13.0.0 → 14.0.0

package/src/rest-service.integration.spec.ts

@@ -1,44 +1,51 @@
-import { InMemoryStore, User, addStore } from '@furystack/core'
+import { InMemoryStore, User as UserModel } from '@furystack/core'
 import { getPort } from '@furystack/core/port-generator'
-import { Injector } from '@furystack/inject'
-import { getRepository } from '@furystack/repository'
+import { createInjector } from '@furystack/inject'
 import type { RestApi } from '@furystack/rest'
 import { serializeValue } from '@furystack/rest'
+import {
+  PasswordCredential,
+  PasswordCredentialStore,
+  PasswordResetToken,
+  PasswordResetTokenStore,
+  usePasswordPolicy,
+} from '@furystack/security'
 import { PathHelper, usingAsync } from '@furystack/utils'
 import { describe, expect, it, vi } from 'vitest'
 import { GetCurrentUser, IsAuthenticated, LogoutAction, createPasswordLoginAction } from './actions/index.js'
-import './helpers.js'
 import { useHttpAuthentication, useRestService } from './helpers.js'
+import { HttpServerPoolToken } from './http-server-pool.js'
 import { createCookieLoginStrategy } from './login-response-strategy.js'
 import { DefaultSession } from './models/default-session.js'
-import { ServerManager } from './server-manager.js'
 import { JsonResult } from './request-action-implementation.js'
+import { ServerTelemetryToken } from './server-telemetry.js'
+import { SessionStore, UserStore } from './user-store.js'
 
 interface IntegrationTestApi extends RestApi {
   GET: {
     '/isAuthenticated': { result: { isAuthenticated: boolean } }
-    '/currentUser': { result: User }
+    '/currentUser': { result: UserModel }
     '/testQuery': { query: { param1: string }; result: { param1Value: string } }
     '/testUrlParams/:urlParam': { url: { urlParam: string }; result: { urlParamValue: string } }
   }
   POST: {
-    '/login': { result: User; body: { username: string; password: string } }
+    '/login': { result: UserModel; body: { username: string; password: string } }
     '/logout': { result: unknown }
     '/testPostBody': { body: { value: string }; result: { bodyValue: string } }
   }
 }
 
 const createIntegrationApi = async () => {
-  const i = new Injector()
+  const i = createInjector()
   const port = getPort()
   const root = 'test-api'
 
-  addStore(i, new InMemoryStore({ model: User, primaryKey: 'username' })).addStore(
-    new InMemoryStore({ model: DefaultSession, primaryKey: 'sessionId' }),
-  )
-  const repo = getRepository(i)
-  repo.createDataSet(User, 'username')
-  repo.createDataSet(DefaultSession, 'sessionId')
+  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)
   await useRestService<IntegrationTestApi>({
     injector: i,
@@ -71,20 +78,19 @@ const createIntegrationApi = async () => {
   return {
     apiUrl: `http://127.0.0.1:${port}/${root}`,
     port,
+    injector: i,
     [Symbol.asyncDispose]: i[Symbol.asyncDispose].bind(i),
   }
 }
 
-describe('@furystack/rest-service inregration tests', () => {
-  it('Should be started and disposed', async () => {
+describe('@furystack/rest-service integration tests', () => {
+  it('starts and disposes cleanly', async () => {
     await usingAsync(await createIntegrationApi(), async () => {})
   })
 
-  it('Should respond with 404 when a route is not found', async () => {
+  it('responds 404 for unknown routes', async () => {
     await usingAsync(await createIntegrationApi(), async ({ apiUrl }) => {
-      const result = await fetch(PathHelper.joinPaths(apiUrl, 'some-route-that-does-not-exists'), {
-        method: 'GET',
-      })
+      const result = await fetch(PathHelper.joinPaths(apiUrl, 'some-route-that-does-not-exist'))
       expect(result.ok).toBe(false)
       expect(result.status).toBe(404)
       const response = (await result.json()) as { error: string }
@@ -92,7 +98,7 @@ describe('@furystack/rest-service inregration tests', () => {
     })
   })
 
-  it('Should respond with 401 for unauthorized request errors', async () => {
+  it('responds 401 for authenticated routes hit anonymously', async () => {
     await usingAsync(await createIntegrationApi(), async ({ apiUrl }) => {
       const result = await fetch(PathHelper.joinPaths(apiUrl, 'currentUser'))
       expect(result.ok).toBe(false)
@@ -102,17 +108,7 @@ describe('@furystack/rest-service inregration tests', () => {
     })
   })
 
-  it('Should respond with 401 for unauthorized request errors', async () => {
-    await usingAsync(await createIntegrationApi(), async ({ apiUrl }) => {
-      const result = await fetch(PathHelper.joinPaths(apiUrl, 'currentUser'))
-      expect(result.ok).toBe(false)
-      expect(result.status).toBe(401)
-      const response = (await result.json()) as { error: string }
-      expect(response).toEqual({ error: 'unauthorized' })
-    })
-  })
-
-  it('Should respond with the correct result body', async () => {
+  it('returns JSON bodies from async actions', async () => {
     await usingAsync(await createIntegrationApi(), async ({ apiUrl }) => {
       const response = await fetch(PathHelper.joinPaths(apiUrl, 'isAuthenticated'))
       expect(response.status).toBe(200)
@@ -121,9 +117,8 @@ describe('@furystack/rest-service inregration tests', () => {
     })
   })
 
-  it('Should be able to read query parameters', async () => {
+  it('deserialises query parameters', async () => {
     await usingAsync(await createIntegrationApi(), async ({ apiUrl }) => {
-      console.log('apiUrl', apiUrl)
       const response = await fetch(PathHelper.joinPaths(apiUrl, `testQuery?param1=${serializeValue('foo')}`))
       expect(response.status).toBe(200)
       const result = (await response.json()) as { param1Value: string }
@@ -131,7 +126,7 @@ describe('@furystack/rest-service inregration tests', () => {
     })
   })
 
-  it('Should be able to read url parameters', async () => {
+  it('extracts url parameters', async () => {
     await usingAsync(await createIntegrationApi(), async ({ apiUrl }) => {
       const response = await fetch(PathHelper.joinPaths(apiUrl, 'testUrlParams/bar'))
       expect(response.status).toBe(200)
@@ -140,7 +135,7 @@ describe('@furystack/rest-service inregration tests', () => {
     })
   })
 
-  it('Should be able to read post body', async () => {
+  it('reads the POST body once and memoises subsequent reads', async () => {
     await usingAsync(await createIntegrationApi(), async ({ apiUrl }) => {
       const response = await fetch(PathHelper.joinPaths(apiUrl, 'testPostBody'), {
         method: 'POST',
@@ -152,19 +147,14 @@ describe('@furystack/rest-service inregration tests', () => {
     })
   })
 
-  it('Should respond with OK to OPTIONS requests', async () => {
+  it('responds 200 to OPTIONS preflight requests', async () => {
     await usingAsync(await createIntegrationApi(), async ({ apiUrl }) => {
-      const response = await fetch(PathHelper.joinPaths(apiUrl, 'testPostBody'), {
-        method: 'OPTIONS',
-      }).catch((e) => {
-        console.log(e)
-        throw e
-      })
+      const response = await fetch(PathHelper.joinPaths(apiUrl, 'testPostBody'), { method: 'OPTIONS' })
       expect(response.status).toBe(200)
     })
   })
 
-  it('Should reject requests outside of the API Root', async () => {
+  it('rejects requests outside the API root with a dropped socket', async () => {
     await usingAsync(await createIntegrationApi(), async ({ port }) => {
       await expect(fetch(PathHelper.joinPaths(`http://127.0.0.1:${port}`, 'not-my-api-root'))).rejects.toThrowError(
         'fetch failed',
@@ -172,7 +162,7 @@ describe('@furystack/rest-service inregration tests', () => {
     })
   })
 
-  it('Should respond with 400 for malformed query parameter values', async () => {
+  it('responds 400 for malformed query-parameter values', async () => {
     await usingAsync(await createIntegrationApi(), async ({ apiUrl }) => {
       const response = await fetch(PathHelper.joinPaths(apiUrl, 'testQuery?param1=not-valid-base64!!!'))
       expect(response.status).toBe(400)
@@ -181,7 +171,7 @@ describe('@furystack/rest-service inregration tests', () => {
     })
   })
 
-  it('Should respond with 400 for malformed percent-encoded path parameters', async () => {
+  it('responds 400 for malformed percent-encoded path parameters', async () => {
     await usingAsync(await createIntegrationApi(), async ({ apiUrl }) => {
       const response = await fetch(`${apiUrl}/testUrlParams/%E0%A4%A`)
       expect(response.status).toBe(400)
@@ -191,68 +181,58 @@ describe('@furystack/rest-service inregration tests', () => {
   })
 })
 
-describe('ServerManager events', () => {
-  it('Should emit onServerListening when a server is created', async () => {
-    await usingAsync(new Injector(), async (i) => {
-      const serverManager = i.getInstance(ServerManager)
+describe('HttpServerPool telemetry', () => {
+  it('emits onServerListening with the url / port / host for newly-opened servers', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const telemetry = i.get(ServerTelemetryToken)
       const handler = vi.fn()
-      serverManager.addListener('onServerListening', handler)
+      telemetry.addListener('onServerListening', handler)
 
       const port = getPort()
-      await serverManager.getOrCreate({ port })
+      await i.get(HttpServerPoolToken).acquire({ port })
 
       expect(handler).toHaveBeenCalledTimes(1)
-      expect(handler).toHaveBeenCalledWith({
-        url: `http://localhost:${port}`,
-        port,
-        hostName: undefined,
-      })
+      expect(handler).toHaveBeenCalledWith({ url: `http://localhost:${port}`, port, hostName: undefined })
     })
   })
 
-  it('Should emit onServerListening with hostName when provided', async () => {
-    await usingAsync(new Injector(), async (i) => {
-      const serverManager = i.getInstance(ServerManager)
+  it('forwards the configured host name into the emitted event', async () => {
+    await usingAsync(createInjector(), async (i) => {
+      const telemetry = i.get(ServerTelemetryToken)
       const handler = vi.fn()
-      serverManager.addListener('onServerListening', handler)
+      telemetry.addListener('onServerListening', handler)
 
       const port = getPort()
-      await serverManager.getOrCreate({ port, hostName: '127.0.0.1' })
+      await i.get(HttpServerPoolToken).acquire({ port, hostName: '127.0.0.1' })
 
-      expect(handler).toHaveBeenCalledWith({
-        url: `http://127.0.0.1:${port}`,
-        port,
-        hostName: '127.0.0.1',
-      })
+      expect(handler).toHaveBeenCalledWith({ url: `http://127.0.0.1:${port}`, port, hostName: '127.0.0.1' })
     })
   })
 
-  it('Should emit onServerClosed when the server manager is disposed', async () => {
-    await usingAsync(new Injector(), async (i) => {
-      const serverManager = i.getInstance(ServerManager)
-      const handler = vi.fn()
-      serverManager.addListener('onServerClosed', handler)
-
-      const port = getPort()
-      await serverManager.getOrCreate({ port })
+  it('emits onServerClosed when the pool is disposed', async () => {
+    const i = createInjector()
+    const telemetry = i.get(ServerTelemetryToken)
+    const handler = vi.fn()
+    telemetry.addListener('onServerClosed', handler)
 
-      await serverManager[Symbol.asyncDispose]()
+    const port = getPort()
+    await i.get(HttpServerPoolToken).acquire({ port })
+    await i[Symbol.asyncDispose]()
 
-      expect(handler).toHaveBeenCalledTimes(1)
-      expect(handler).toHaveBeenCalledWith({ url: `http://localhost:${port}` })
-    })
+    expect(handler).toHaveBeenCalledTimes(1)
+    expect(handler).toHaveBeenCalledWith({ url: `http://localhost:${port}` })
   })
 
-  it('Should not emit onServerListening for an existing server', async () => {
-    await usingAsync(new Injector(), async (i) => {
-      const serverManager = i.getInstance(ServerManager)
+  it('does not emit onServerListening a second time for the same url', async () => {
+    await usingAsync(createInjector(), async (i) => {
       const port = getPort()
-      await serverManager.getOrCreate({ port })
+      await i.get(HttpServerPoolToken).acquire({ port })
 
+      const telemetry = i.get(ServerTelemetryToken)
       const handler = vi.fn()
-      serverManager.addListener('onServerListening', handler)
+      telemetry.addListener('onServerListening', handler)
 
-      await serverManager.getOrCreate({ port })
+      await i.get(HttpServerPoolToken).acquire({ port })
 
       expect(handler).not.toHaveBeenCalled()
     })

package/src/rest.integration.test.ts

@@ -1,5 +1,5 @@
 import { getPort } from '@furystack/core/port-generator'
-import { Injector } from '@furystack/inject'
+import { createInjector } from '@furystack/inject'
 import type { RestApi } from '@furystack/rest'
 import { createClient } from '@furystack/rest-client-fetch'
 import { usingAsync } from '@furystack/utils'
@@ -32,7 +32,7 @@ export interface EchoApi extends RestApi {
 const createEchoApiServer = async () => {
   const port = getPort()
   const root = '/api'
-  const injector = new Injector()
+  const injector = createInjector()
   await useRestService<EchoApi>({
     injector,
     port,
@@ -67,122 +67,62 @@ const createEchoApiServer = async () => {
 }
 
 describe('REST Integration tests with FETCH client', () => {
-  it('Should execute a single parameterless GET query', async () => {
+  it('executes a parameterless GET request', async () => {
     await usingAsync(await createEchoApiServer(), async ({ client }) => {
-      const result = await client({
-        method: 'GET',
-        action: '/plain',
-      })
+      const result = await client({ method: 'GET', action: '/plain' })
       expect(result.response.status).toBe(200)
       expect(result.result).toEqual({})
     })
   })
 
-  it('Should execute a request with headers', async () => {
+  it('passes headers through', async () => {
     await usingAsync(await createEchoApiServer(), async ({ client }) => {
-      const value = 'value'
-      const result = await client({
-        method: 'GET',
-        action: '/headers',
-        headers: {
-          value,
-        },
-      })
+      const result = await client({ method: 'GET', action: '/headers', headers: { value: 'hello' } })
       expect(result.response.status).toBe(200)
-      expect(result.result.headers.value).toEqual(value)
+      expect(result.result.headers.value).toBe('hello')
     })
   })
 
-  it('Should execute a request with query', async () => {
+  it('serialises url params', async () => {
     await usingAsync(await createEchoApiServer(), async ({ client }) => {
-      const value = 'value2'
-      const result = await client({
-        method: 'GET',
-        action: '/query',
-        query: {
-          someObject: {
-            foo: value,
-          },
-        },
-      })
-      expect(result.response.status).toBe(200)
-      expect(result.result.query.someObject.foo).toEqual(value)
-    })
-  })
-
-  it('Should execute a request with URL parameters', async () => {
-    await usingAsync(await createEchoApiServer(), async ({ client }) => {
-      const value = 'value3'
-      const result = await client({
-        method: 'GET',
-        action: '/urlParams/:id',
-        url: {
-          id: value,
-        },
-      })
-      expect(result.response.status).toBe(200)
-      expect(result.result.url.id).toEqual(value)
+      const result = await client({ method: 'GET', action: '/urlParams/:id', url: { id: '42' } })
+      expect(result.result.url.id).toBe('42')
     })
   })
 
-  it('should execute a request for a segment', async () => {
+  it('serialises a structured query', async () => {
     await usingAsync(await createEchoApiServer(), async ({ client }) => {
       const result = await client({
         method: 'GET',
-        action: '/segment',
-      })
-      expect(result.response.status).toBe(200)
-      expect(result.result.name).toEqual('segment')
-    })
-  })
-
-  it('should execute a request for a subsegment', async () => {
-    await usingAsync(await createEchoApiServer(), async ({ client }) => {
-      const result = await client({
-        method: 'GET',
-        action: '/segment/subsegment',
+        action: '/query',
+        query: { someObject: { foo: 'bar' } },
       })
-      expect(result.response.status).toBe(200)
-      expect(result.result.name).toEqual('segment-subsegment')
+      expect(result.result.query.someObject.foo).toBe('bar')
     })
   })
 
-  it('should execute a request for a subsegment with URL parameters', async () => {
+  it('dispatches plain and multi-segment URLs correctly', async () => {
     await usingAsync(await createEchoApiServer(), async ({ client }) => {
-      const value = 'value4'
-      const result = await client({
+      expect((await client({ method: 'GET', action: '/segment' })).result.name).toBe('segment')
+      expect((await client({ method: 'GET', action: '/segment/subsegment' })).result.name).toBe('segment-subsegment')
+      const subsegment = await client({
         method: 'GET',
         action: '/segment/:id/subsegment',
-        url: {
-          id: value,
-        },
+        url: { id: 'abc' },
       })
-      expect(result.response.status).toBe(200)
-      expect(result.result.url.id).toEqual(value)
-      expect(result.result.url.name).toEqual('segment-subsegment')
+      expect(subsegment.result.url.id).toBe('abc')
+      expect(subsegment.result.url.name).toBe('segment-subsegment')
     })
   })
-  it('should evaluate optional parameters in the URL', async () => {
+
+  it('forwards POST bodies', async () => {
     await usingAsync(await createEchoApiServer(), async ({ client }) => {
       const result = await client({
-        method: 'GET',
-        action: '/segment{/:optionalId}?/optionalSubsegment/',
-        url: {},
-      })
-      expect(result.response.status).toBe(200)
-      expect(result.result.url.optionalId).toBeUndefined()
-      expect(result.result.name).toEqual('optional-id')
-
-      const result2 = await client({
-        method: 'GET',
-        action: '/segment{/:optionalId}?/optionalSubsegment/',
-        url: {
-          optionalId: 'value',
-        },
+        method: 'POST',
+        action: '/body',
+        body: { foo: 'hi', bar: 42 },
       })
-      expect(result2.response.status).toBe(200)
-      expect(result2.result.url.optionalId).toEqual('value')
-      expect(result2.result.name).toEqual('optional-id')
+      expect(result.result.body).toEqual({ foo: 'hi', bar: 42 })
     })
   })
 })

package/src/server-telemetry.spec.ts

@@ -0,0 +1,56 @@
+import { createInjector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
+import { describe, expect, it, vi } from 'vitest'
+import { ServerTelemetry, ServerTelemetryToken } from './server-telemetry.js'
+
+describe('ServerTelemetry', () => {
+  it('ServerTelemetryToken resolves to a ServerTelemetry EventHub and is cached per scope', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      const a = injector.get(ServerTelemetryToken)
+      const b = injector.get(ServerTelemetryToken)
+      expect(a).toBe(b)
+      expect(a).toBeInstanceOf(ServerTelemetry)
+    })
+  })
+
+  it('Emitted events are dispatched to subscribers', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      const telemetry = injector.get(ServerTelemetryToken)
+      const onListening = vi.fn()
+      telemetry.subscribe('onServerListening', onListening)
+      telemetry.emit('onServerListening', { url: 'http://localhost:1', port: 1 })
+      expect(onListening).toHaveBeenCalledWith({ url: 'http://localhost:1', port: 1 })
+    })
+  })
+
+  it('Disposes cleanly with the injector and stops routing events', async () => {
+    const injector = createInjector()
+    const telemetry = injector.get(ServerTelemetryToken)
+    const onClosed = vi.fn()
+    telemetry.subscribe('onServerClosed', onClosed)
+
+    await injector[Symbol.asyncDispose]()
+
+    // After the owning injector is disposed, emit on the captured reference
+    // should still work (the EventHub is disposed separately via onDispose,
+    // but listeners are cleared). The key guarantee: previously-attached
+    // listeners receive nothing new after dispose.
+    telemetry.emit('onServerClosed', { url: 'http://localhost:2' })
+    expect(onClosed).not.toHaveBeenCalled()
+  })
+
+  it('Scopes have isolated telemetry instances', async () => {
+    await usingAsync(createInjector(), async (root) => {
+      const scope1 = root.createScope()
+      const scope2 = root.createScope()
+      try {
+        const t1 = scope1.get(ServerTelemetryToken)
+        const t2 = scope2.get(ServerTelemetryToken)
+        expect(t1).not.toBe(t2)
+      } finally {
+        await scope1[Symbol.asyncDispose]()
+        await scope2[Symbol.asyncDispose]()
+      }
+    })
+  })
+})

package/src/server-telemetry.ts

@@ -0,0 +1,51 @@
+import { defineService, type Token } from '@furystack/inject'
+import { EventHub, type ListenerErrorPayload } from '@furystack/utils'
+import type { IncomingMessage, ServerResponse } from 'http'
+import type { Data, WebSocket } from 'ws'
+
+/**
+ * Union of every server-lifecycle event the rest-service runtime emits. Replaces
+ * the `EventHub`s that used to live on the deleted `ServerManager`,
+ * `ProxyManager` and `WebSocketApi` classes — consumers subscribe once to the
+ * telemetry singleton and receive events from every source.
+ */
+export type ServerTelemetryEvents = {
+  /** Emitted when the pool successfully opens an HTTP listener. */
+  onServerListening: { url: string; port: number; hostName?: string }
+  /** Emitted when the pool closes an HTTP listener during disposal. */
+  onServerClosed: { url: string }
+  /** Emitted when an API's `onRequest` rejects. Tuple matches the original `ServerManager` payload. */
+  onRequestFailed: [unknown, IncomingMessage, ServerResponse<IncomingMessage>]
+  /** Emitted when an HTTP proxy round-trip fails. */
+  onProxyFailed: { from: string; to: string; error: unknown }
+  /** Emitted when a WebSocket proxy upgrade fails. */
+  onWebSocketProxyFailed: { from: string; to: string; error: unknown }
+  /** Emitted when a WebSocket API action fails during lookup or execution. */
+  onWebSocketActionFailed: { error: unknown; data?: Data; socket?: WebSocket }
+  /** Emitted when a listener registered on this telemetry hub throws. */
+  onListenerError: ListenerErrorPayload
+}
+
+/**
+ * Telemetry surface exposed to applications. Extending {@link EventHub}
+ * gives subscribers the same `addListener` / `subscribe` / `emit` API they
+ * were using on the pre-migration managers.
+ */
+export class ServerTelemetry extends EventHub<ServerTelemetryEvents> {}
+
+/**
+ * DI token for the shared {@link ServerTelemetry} instance. Scoped so each
+ * injector tree (in particular, each test) gets an isolated event stream.
+ */
+export const ServerTelemetryToken: Token<ServerTelemetry, 'scoped'> = defineService({
+  name: 'furystack/rest-service/ServerTelemetry',
+  lifetime: 'scoped',
+  factory: ({ onDispose }) => {
+    const telemetry = new ServerTelemetry()
+    // Disposal is delegated to the injector via `onDispose`; the telemetry
+    // outlives this factory invocation and is torn down on scope teardown.
+    // eslint-disable-next-line furystack/prefer-using-wrapper
+    onDispose(() => telemetry[Symbol.dispose]())
+    return telemetry
+  },
+})