@furystack/rest-service 13.0.0 → 14.0.0

package/src/static-server-manager.spec.ts

@@ -1,224 +1,137 @@
-import { Injector } from '@furystack/inject'
-import { sleepAsync, usingAsync } from '@furystack/utils'
-import { ServerManager } from './server-manager.js'
-import { StaticServerManager } from './static-server-manager.js'
-import { describe, it, expect, vi } from 'vitest'
 import { getPort } from '@furystack/core/port-generator'
+import { createInjector } from '@furystack/inject'
+import { sleepAsync, usingAsync } from '@furystack/utils'
+import { describe, expect, it, vi } from 'vitest'
+import { useStaticFiles } from './helpers.js'
+import { HttpServerPoolToken } from './http-server-pool.js'
+import { buildStaticSiteServerApi } from './static-site-runtime.js'
 
-describe('StaticServerManager', () => {
+describe('useStaticFiles / buildStaticSiteServerApi', () => {
   describe('Top level routing', () => {
-    it('Should return a 404 without fallback', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
+    it('responds 404 without a fallback', async () => {
+      await usingAsync(createInjector(), async (i) => {
         const port = getPort()
-        await staticServerManager.addStaticSite({
-          baseUrl: '/',
-          path: '.',
-          port,
-        })
+        await useStaticFiles({ injector: i, baseUrl: '/', path: '.', port })
 
         const result = await fetch(`http://127.0.0.1:${port}/not-found.html`)
         expect(result.ok).toBe(false)
         expect(result.status).toBe(404)
-        expect(result?.headers.get('content-type')).toBe('text/plain')
-        const body = await result.text()
-        expect(body).toBe('Not found')
+        expect(result.headers.get('content-type')).toBe('text/plain')
+        expect(await result.text()).toBe('Not found')
       })
     })
 
-    it('Should return a fallback', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
+    it('falls back to the configured file and returns its content-type', async () => {
+      await usingAsync(createInjector(), async (i) => {
         const port = getPort()
-
-        await staticServerManager.addStaticSite({
+        await useStaticFiles({
+          injector: i,
           baseUrl: '/',
           path: '.',
           fallback: 'package.json',
           port,
-          headers: {
-            'custom-header': 'custom-value',
-          },
+          headers: { 'custom-header': 'custom-value' },
         })
 
         const result = await fetch(`http://localhost:${port}/not-found.html`)
-
         expect(result.headers.get('content-type')).toBe('application/json')
         expect(result.headers.get('custom-header')).toBe('custom-value')
       })
     })
 
-    it('Should return a fallback for root files', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
+    it('falls back for the root url when no index exists', async () => {
+      await usingAsync(createInjector(), async (i) => {
         const port = getPort()
-
-        await staticServerManager.addStaticSite({
+        await useStaticFiles({
+          injector: i,
           baseUrl: '/',
           path: '.',
           fallback: 'package.json',
           port,
-          headers: {
-            'custom-header': 'custom-value',
-          },
+          headers: { 'custom-header': 'custom-value' },
         })
 
         const result = await fetch(`http://localhost:${port}`)
-
         expect(result.headers.get('content-type')).toBe('application/json')
         expect(result.headers.get('custom-header')).toBe('custom-value')
       })
     })
 
-    it('Should return a defined file from a root directory', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
+    it('serves an existing file from the root directory', async () => {
+      await usingAsync(createInjector(), async (i) => {
         const port = getPort()
-
-        await staticServerManager.addStaticSite({
-          baseUrl: '/',
-          path: '.',
-          port,
-          headers: {
-            'custom-header': 'custom-value',
-          },
-        })
-
+        await useStaticFiles({ injector: i, baseUrl: '/', path: '.', port })
         const result = await fetch(`http://localhost:${port}/README.md`)
-
         expect(result.headers.get('content-type')).toBe('text/markdown')
-        expect(result.headers.get('custom-header')).toBe('custom-value')
       })
     })
 
-    it('Should return a defined file from a subdirectory', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
+    it('serves files from subdirectories', async () => {
+      await usingAsync(createInjector(), async (i) => {
         const port = getPort()
-
-        await staticServerManager.addStaticSite({
-          baseUrl: '/',
-          path: '.',
-          port,
-        })
-
+        await useStaticFiles({ injector: i, baseUrl: '/', path: '.', port })
         const result = await fetch(`http://localhost:${port}/packages/utils/README.md`)
-
         expect(result.headers.get('content-type')).toBe('text/markdown')
       })
     })
   })
 
   describe('Non-top level routing', () => {
-    it('Should not handle a request when the path is not matching', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
+    it('leaves requests outside the base url to the next api in the chain', async () => {
+      await usingAsync(createInjector(), async (i) => {
         const port = getPort()
+        const serverApi = await useStaticFiles({ injector: i, baseUrl: '/bundle', path: '.', port })
 
-        await staticServerManager.addStaticSite({
-          baseUrl: '/bundle',
-          path: '.',
-          port,
-        })
-
-        const server = [...injector.getInstance(ServerManager).servers.values()][0]
-
-        server.apis[0].onRequest = vi.fn()
+        const record = await i.get(HttpServerPoolToken).acquire({ port })
+        const onRequest = vi.fn()
+        // Swap in a spy to observe non-matching requests never reach the handler.
+        serverApi.onRequest = onRequest
+        record.apis[0] = serverApi
 
         fetch(`http://localhost:${port}/bundleToAnotherFolder/not-found.html`).catch(() => {
-          /** should fall, ignore */
+          // Expected to fail: the server has no matching API and drops the socket.
         })
-
         await sleepAsync(100)
-
-        expect(server.apis[0].onRequest).not.toHaveBeenCalled()
+        expect(onRequest).not.toHaveBeenCalled()
       })
     })
 
-    it('Should return a 404 without fallback', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
+    it('returns 404 under a sub-base url when the file is missing and no fallback is set', async () => {
+      await usingAsync(createInjector(), async (i) => {
         const port = getPort()
-
-        await staticServerManager.addStaticSite({
-          baseUrl: '/bundle',
-          path: '.',
-          port,
-        })
+        await useStaticFiles({ injector: i, baseUrl: '/bundle', path: '.', port })
 
         const result = await fetch(`http://localhost:${port}/bundle/not-found.html`)
         expect(result.ok).toBe(false)
         expect(result.status).toBe(404)
         expect(result.headers.get('content-type')).toBe('text/plain')
-        const body = await result.text()
-        expect(body).toBe('Not found')
+        expect(await result.text()).toBe('Not found')
       })
     })
 
-    it('Should return a fallback', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
+    it('serves the configured fallback under a sub-base url', async () => {
+      await usingAsync(createInjector(), async (i) => {
         const port = getPort()
-
-        await staticServerManager.addStaticSite({
-          baseUrl: '/bundle',
-          path: '.',
-          fallback: 'package.json',
-          port,
-        })
+        await useStaticFiles({ injector: i, baseUrl: '/bundle', path: '.', fallback: 'package.json', port })
 
         const result = await fetch(`http://localhost:${port}/bundle/not-found.html`)
-
         expect(result.headers.get('content-type')).toBe('application/json')
       })
     })
-
-    it('Should return a defined file from a root directory', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
-        const port = getPort()
-
-        await staticServerManager.addStaticSite({
-          baseUrl: '/',
-          path: '.',
-          port,
-        })
-
-        const result = await fetch(`http://localhost:${port}/README.md`)
-
-        expect(result.headers.get('content-type')).toBe('text/markdown')
-      })
-    })
-
-    it('Should return a defined file from a subdirectory', async () => {
-      await usingAsync(new Injector(), async (injector) => {
-        const staticServerManager = injector.getInstance(StaticServerManager)
-        const port = getPort()
-
-        await staticServerManager.addStaticSite({
-          baseUrl: '/',
-          path: '.',
-          port,
-        })
-
-        const result = await fetch(`http://localhost:${port}/packages/utils/README.md`)
-
-        expect(result.headers.get('content-type')).toBe('text/markdown')
-      })
-    })
   })
 
   describe('shouldExec', () => {
-    it('Should NOT match for requests with not defined method', () => {
-      const staticServerManager = new StaticServerManager()
-      expect(staticServerManager.shouldExec('/')({ req: { url: '/' } })).toBe(false)
+    const api = (baseUrl: string) => buildStaticSiteServerApi({ baseUrl, path: '.', port: 0 })
+
+    it('does not match when the request method is missing', () => {
+      expect(api('/').shouldExec({ req: { url: '/' } as never, res: {} as never })).toBe(false)
     })
 
-    it('Should NOT match for non-GET requests', () => {
-      const staticServerManager = new StaticServerManager()
-      expect(staticServerManager.shouldExec('/')({ req: { method: 'POST', url: '/' } })).toBe(false)
+    it('does not match non-GET methods', () => {
+      expect(api('/').shouldExec({ req: { method: 'POST', url: '/' } as never, res: {} as never })).toBe(false)
     })
-    ;[
+
+    const positiveCases: Array<[string, string]> = [
       ['/', '/'],
       ['/', '/index.html'],
       ['/', '/subdir'],
@@ -228,22 +141,21 @@ describe('StaticServerManager', () => {
       ['/subdir', '/subdir/'],
       ['/subdir', '/subdir/file.js'],
       ['/subdir', '/subdir/s2/file.js'],
-    ].forEach(([root, url]) =>
-      it(`Should match for '${root}' root and '${url}' url`, () => {
-        const staticServerManager = new StaticServerManager()
-        const shouldExec = staticServerManager.shouldExec(root)({ req: { method: 'GET', url } })
-        expect(shouldExec).toBe(true)
+    ]
+    positiveCases.forEach(([baseUrl, url]) =>
+      it(`matches GET '${url}' against base '${baseUrl}'`, () => {
+        expect(api(baseUrl).shouldExec({ req: { method: 'GET', url } as never, res: {} as never })).toBe(true)
       }),
     )
 
-    it('Should not exec different paths for non-top level root directory', () => {
-      const staticServerManager = new StaticServerManager()
-      expect(staticServerManager.shouldExec('/subdir')({ req: { method: 'GET', url: '/' } })).toBe(false)
-      expect(staticServerManager.shouldExec('/subdir')({ req: { method: 'GET', url: '/other/index.html' } })).toBe(
+    it('does not match unrelated urls under a non-root base', () => {
+      const subdir = api('/subdir')
+      expect(subdir.shouldExec({ req: { method: 'GET', url: '/' } as never, res: {} as never })).toBe(false)
+      expect(subdir.shouldExec({ req: { method: 'GET', url: '/other/index.html' } as never, res: {} as never })).toBe(
         false,
       )
-      expect(staticServerManager.shouldExec('/subdir')({ req: { method: 'GET', url: '/subdir2' } })).toBe(false)
-      expect(staticServerManager.shouldExec('/subdir')({ req: { method: 'GET', url: '/subdir2/index.html' } })).toBe(
+      expect(subdir.shouldExec({ req: { method: 'GET', url: '/subdir2' } as never, res: {} as never })).toBe(false)
+      expect(subdir.shouldExec({ req: { method: 'GET', url: '/subdir2/index.html' } as never, res: {} as never })).toBe(
         false,
       )
     })

package/src/static-site-runtime.spec.ts

@@ -0,0 +1,39 @@
+import type { IncomingMessage, ServerResponse } from 'http'
+import { describe, expect, it } from 'vitest'
+import { buildStaticSiteServerApi } from './static-site-runtime.js'
+
+const makeRequest = (url: string | undefined, method: string | undefined = 'GET'): IncomingMessage =>
+  ({ url, method, headers: {} }) as unknown as IncomingMessage
+
+// Full onRequest / sendFile behaviour (streaming, fallback, 404) is covered
+// end-to-end via `static-server-manager.spec.ts` which drives the real HTTP
+// pool. These tests cover the pure-function `shouldExec` gate which is
+// exercised by the server pool before any request is handed to the API.
+describe('buildStaticSiteServerApi / shouldExec', () => {
+  const api = buildStaticSiteServerApi({ baseUrl: '/static', path: '/tmp', port: 0 })
+
+  it('matches GET requests under the baseUrl', () => {
+    expect(api.shouldExec({ req: makeRequest('/static/index.html'), res: {} as ServerResponse })).toBe(true)
+  })
+
+  it('is case-insensitive about the method (GET only)', () => {
+    expect(api.shouldExec({ req: makeRequest('/static/a.html', 'get'), res: {} as ServerResponse })).toBe(true)
+  })
+
+  it('rejects non-GET methods', () => {
+    expect(api.shouldExec({ req: makeRequest('/static/index.html', 'POST'), res: {} as ServerResponse })).toBe(false)
+    expect(api.shouldExec({ req: makeRequest('/static/index.html', 'DELETE'), res: {} as ServerResponse })).toBe(false)
+  })
+
+  it('rejects URLs that do not match the baseUrl', () => {
+    expect(api.shouldExec({ req: makeRequest('/other/index.html'), res: {} as ServerResponse })).toBe(false)
+  })
+
+  it('rejects requests without a URL', () => {
+    expect(api.shouldExec({ req: makeRequest(undefined), res: {} as ServerResponse })).toBe(false)
+  })
+
+  it('never exposes an onUpgrade hook (static sites do not handle upgrades)', () => {
+    expect(api.onUpgrade).toBeUndefined()
+  })
+})

package/src/static-site-runtime.ts

@@ -0,0 +1,75 @@
+import { PathHelper } from '@furystack/utils'
+import { createReadStream } from 'fs'
+import { access, stat } from 'fs/promises'
+import type { IncomingMessage, OutgoingHttpHeaders, ServerResponse } from 'http'
+import { join, normalize, sep } from 'path'
+import type { ServerApi } from './http-server-pool.js'
+import { getMimeForFile } from './mime-types.js'
+
+/**
+ * Options accepted by {@link buildStaticSiteServerApi} and
+ * {@link useStaticFiles}.
+ */
+export interface StaticServerOptions {
+  baseUrl: string
+  path: string
+  hostName?: string
+  port: number
+  fallback?: string
+  headers?: OutgoingHttpHeaders
+}
+
+const sendFile = async ({
+  fullPath,
+  headers,
+  res,
+}: {
+  fullPath: string
+  res: ServerResponse
+  headers?: OutgoingHttpHeaders
+}): Promise<void> => {
+  const { size } = await stat(fullPath)
+  await access(fullPath)
+  const head = {
+    ...headers,
+    'Content-Length': size,
+    'Content-Type': getMimeForFile(fullPath),
+  }
+  Object.entries(head).forEach(([key, value]) => res.setHeader(key, value))
+  await new Promise<void>((resolve, reject) =>
+    createReadStream(fullPath, { autoClose: true }).once('finish', resolve).once('error', reject).pipe(res),
+  )
+}
+
+/**
+ * Builds a {@link ServerApi} that serves files under `options.path` for every
+ * GET request whose URL matches `options.baseUrl`. Falls back to
+ * `options.fallback` (if set) for missing files, otherwise responds with 404.
+ */
+export const buildStaticSiteServerApi = (options: StaticServerOptions): ServerApi => {
+  const onRequest = async ({ req, res }: { req: IncomingMessage; res: ServerResponse }): Promise<void> => {
+    const extractedPath = PathHelper.extractPath(req.url as string, options.baseUrl)
+    const filePath = (extractedPath || '/').replaceAll('/', sep)
+    const fullPath = normalize(join(options.path, filePath))
+    try {
+      await sendFile({ fullPath, res, headers: options.headers })
+    } catch {
+      if (options.fallback) {
+        await sendFile({ fullPath: normalize(join(options.path, options.fallback)), res, headers: options.headers })
+        return
+      }
+      res.writeHead(404, { 'Content-Type': 'text/plain' })
+      res.end('Not found')
+    }
+  }
+
+  return {
+    shouldExec: ({ req }) =>
+      req.url !== undefined &&
+      req.method?.toUpperCase() === 'GET' &&
+      PathHelper.matchesBaseUrl(req.url, options.baseUrl)
+        ? true
+        : false,
+    onRequest,
+  }
+}

package/src/user-store.spec.ts

@@ -0,0 +1,86 @@
+import { InMemoryStore, User } from '@furystack/core'
+import { createInjector } from '@furystack/inject'
+import { usingAsync } from '@furystack/utils'
+import { describe, expect, it } from 'vitest'
+import { DefaultSession } from './models/default-session.js'
+import {
+  HttpAuthenticationStoreNotConfiguredError,
+  SessionDataSet,
+  SessionStore,
+  UserDataSet,
+  UserStore,
+} from './user-store.js'
+
+describe('UserStore', () => {
+  it('exposes the User model and username primary key on the token', () => {
+    expect(UserStore.model).toBe(User)
+    expect(UserStore.primaryKey).toBe('username')
+    expect(UserStore.lifetime).toBe('singleton')
+  })
+
+  it('throws HttpAuthenticationStoreNotConfiguredError when resolved without an override', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      expect(() => injector.get(UserStore)).toThrow(HttpAuthenticationStoreNotConfiguredError)
+      expect(() => injector.get(UserStore)).toThrow(/UserStore.*not been configured/)
+    })
+  })
+
+  it('returns the bound implementation after rebinding the token', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      const impl = new InMemoryStore({ model: User, primaryKey: 'username' })
+      injector.bind(UserStore, () => impl)
+      expect(injector.get(UserStore)).toBe(impl)
+    })
+  })
+})
+
+describe('SessionStore', () => {
+  it('exposes the DefaultSession model and sessionId primary key on the token', () => {
+    expect(SessionStore.model).toBe(DefaultSession)
+    expect(SessionStore.primaryKey).toBe('sessionId')
+    expect(SessionStore.lifetime).toBe('singleton')
+  })
+
+  it('throws HttpAuthenticationStoreNotConfiguredError when resolved without an override', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      expect(() => injector.get(SessionStore)).toThrow(HttpAuthenticationStoreNotConfiguredError)
+      expect(() => injector.get(SessionStore)).toThrow(/SessionStore.*not been configured/)
+    })
+  })
+
+  it('returns the bound implementation after rebinding the token', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      const impl = new InMemoryStore({ model: DefaultSession, primaryKey: 'sessionId' })
+      injector.bind(SessionStore, () => impl)
+      expect(injector.get(SessionStore)).toBe(impl)
+    })
+  })
+})
+
+describe('UserDataSet / SessionDataSet', () => {
+  it('mirror the backing store metadata onto the data-set token', () => {
+    expect(UserDataSet.model).toBe(User)
+    expect(UserDataSet.primaryKey).toBe('username')
+    expect(SessionDataSet.model).toBe(DefaultSession)
+    expect(SessionDataSet.primaryKey).toBe('sessionId')
+  })
+
+  it('resolves through the bound store implementation', async () => {
+    await usingAsync(createInjector(), async (injector) => {
+      injector.bind(UserStore, () => new InMemoryStore({ model: User, primaryKey: 'username' }))
+      const dataSet = injector.get(UserDataSet)
+      await dataSet.add(injector, { username: 'alice', roles: [] })
+      const result = await dataSet.get(injector, 'alice')
+      expect(result?.username).toBe('alice')
+    })
+  })
+})
+
+describe('HttpAuthenticationStoreNotConfiguredError', () => {
+  it('embeds the store name in the message and sets the error name', () => {
+    const error = new HttpAuthenticationStoreNotConfiguredError('SomeStore')
+    expect(error.name).toBe('HttpAuthenticationStoreNotConfiguredError')
+    expect(error.message).toContain("'SomeStore'")
+    expect(error).toBeInstanceOf(Error)
+  })
+})

package/src/user-store.ts

@@ -0,0 +1,68 @@
+import { defineStore, type StoreToken, User } from '@furystack/core'
+import { defineDataSet, type DataSetToken } from '@furystack/repository'
+import { DefaultSession } from './models/default-session.js'
+
+/**
+ * Error thrown by the default factories of {@link UserStore} and
+ * {@link SessionStore} when they are resolved without a caller-provided
+ * override. Users and sessions must outlive a process restart, so the
+ * rest-service refuses to silently fall back to an in-memory store.
+ */
+export class HttpAuthenticationStoreNotConfiguredError extends Error {
+  constructor(storeName: string) {
+    super(
+      `HTTP authentication store '${storeName}' has not been configured. Bind a persistent PhysicalStore before resolving the HttpUserContext.`,
+    )
+    this.name = 'HttpAuthenticationStoreNotConfiguredError'
+  }
+}
+
+/**
+ * Store token for persisted {@link User} records. Applications must bind
+ * this token to a persistent implementation before resolving
+ * {@link HttpUserContext} (or any service that derives from it).
+ *
+ * @example
+ * ```ts
+ * injector.bind(UserStore, () => myPersistentUserStore)
+ * ```
+ */
+export const UserStore: StoreToken<User, 'username'> = defineStore({
+  name: 'furystack/rest-service/UserStore',
+  model: User,
+  primaryKey: 'username',
+  factory: () => {
+    throw new HttpAuthenticationStoreNotConfiguredError('UserStore')
+  },
+})
+
+/**
+ * Store token for persisted {@link DefaultSession} records. Shares the
+ * throw-by-default contract with {@link UserStore}.
+ */
+export const SessionStore: StoreToken<DefaultSession, 'sessionId'> = defineStore({
+  name: 'furystack/rest-service/SessionStore',
+  model: DefaultSession,
+  primaryKey: 'sessionId',
+  factory: () => {
+    throw new HttpAuthenticationStoreNotConfiguredError('SessionStore')
+  },
+})
+
+/**
+ * Data set token over {@link UserStore}. Consumers of the authentication
+ * subsystem (cookie login, JWT authentication plugins, `HttpUserContext`)
+ * route all user I/O through this dataset.
+ */
+export const UserDataSet: DataSetToken<User, 'username'> = defineDataSet({
+  name: 'furystack/rest-service/UserDataSet',
+  store: UserStore,
+})
+
+/**
+ * Data set token over {@link SessionStore}.
+ */
+export const SessionDataSet: DataSetToken<DefaultSession, 'sessionId'> = defineDataSet({
+  name: 'furystack/rest-service/SessionDataSet',
+  store: SessionStore,
+})