@furystack/rest-service 13.0.0 → 14.1.0

package/src/proxy-runtime.spec.ts

@@ -0,0 +1,50 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { buildProxyServerApi, type ProxyOptions } from './proxy-runtime.js'
+import { ServerTelemetry } from './server-telemetry.js'
+
+const baseOptions: ProxyOptions = {
+  sourceBaseUrl: '/api',
+  sourcePort: 0,
+  targetBaseUrl: 'http://upstream.invalid:8080',
+}
+
+describe('buildProxyServerApi', () => {
+  let telemetry: ServerTelemetry
+
+  beforeEach(() => {
+    telemetry = new ServerTelemetry()
+  })
+  afterEach(() => {
+    telemetry[Symbol.dispose]()
+  })
+
+  it('returns a ServerApi whose shouldExec matches URLs under the sourceBaseUrl', () => {
+    const api = buildProxyServerApi(baseOptions, telemetry)
+    expect(api.shouldExec({ req: { url: '/api/items', method: 'GET' } as never, res: {} as never })).toBe(true)
+    expect(api.shouldExec({ req: { url: '/other', method: 'GET' } as never, res: {} as never })).toBe(false)
+  })
+
+  it('shouldExec rejects requests missing a URL', () => {
+    const api = buildProxyServerApi(baseOptions, telemetry)
+    expect(api.shouldExec({ req: { method: 'GET' } as never, res: {} as never })).toBe(false)
+  })
+
+  it('does not attach onUpgrade unless websockets are explicitly enabled', () => {
+    const apiWithoutWs = buildProxyServerApi(baseOptions, telemetry)
+    const apiWithWs = buildProxyServerApi({ ...baseOptions, enableWebsockets: true }, telemetry)
+    expect(apiWithoutWs.onUpgrade).toBeUndefined()
+    expect(typeof apiWithWs.onUpgrade).toBe('function')
+  })
+
+  it('throws on an invalid targetBaseUrl', () => {
+    expect(() => buildProxyServerApi({ ...baseOptions, targetBaseUrl: 'not-a-url' }, telemetry)).toThrow(
+      /Invalid targetBaseUrl/,
+    )
+  })
+
+  it('throws on non-HTTP(S) targets', () => {
+    expect(() =>
+      buildProxyServerApi({ ...baseOptions, targetBaseUrl: 'ftp://upstream.invalid:21' }, telemetry),
+    ).toThrow(/protocol/i)
+  })
+})

package/src/proxy-runtime.ts

@@ -0,0 +1,75 @@
+import { PathHelper } from '@furystack/utils'
+import type { IncomingMessage, OutgoingHttpHeaders, ServerResponse } from 'http'
+import type { Duplex } from 'stream'
+import { HttpProxyHandler } from './http-proxy-handler.js'
+import type { ServerApi } from './http-server-pool.js'
+import { PathProcessor } from './path-processor.js'
+import type { ServerTelemetry } from './server-telemetry.js'
+import { WebSocketProxyHandler } from './websocket-proxy-handler.js'
+
+/**
+ * Options accepted by {@link buildProxyServerApi} and {@link useProxy}.
+ * Mirrors the original `ProxyOptions` shape from the deleted
+ * `ProxyManager`; see that history for field-by-field documentation.
+ */
+export interface ProxyOptions {
+  sourceBaseUrl: string
+  targetBaseUrl: string
+  pathRewrite?: (sourcePath: string) => string
+  sourceHostName?: string
+  sourcePort: number
+  headers?: (originalHeaders: OutgoingHttpHeaders) => OutgoingHttpHeaders
+  cookies?: (originalCookies: string[]) => string[]
+  responseCookies?: (responseCookies: string[]) => string[]
+  timeout?: number
+  enableWebsockets?: boolean
+}
+
+const createRequestHandler = (options: ProxyOptions, telemetry: ServerTelemetry) => {
+  const handler = new HttpProxyHandler({
+    sourceBaseUrl: options.sourceBaseUrl,
+    targetBaseUrl: options.targetBaseUrl,
+    pathRewrite: options.pathRewrite,
+    headers: options.headers,
+    cookies: options.cookies,
+    responseCookies: options.responseCookies,
+    timeout: options.timeout,
+    onError: (error) => telemetry.emit('onProxyFailed', error),
+  })
+  return async ({ req, res }: { req: IncomingMessage; res: ServerResponse }) => handler.handle(req, res)
+}
+
+const createUpgradeHandler = (options: ProxyOptions, telemetry: ServerTelemetry) => {
+  const handler = new WebSocketProxyHandler({
+    sourceBaseUrl: options.sourceBaseUrl,
+    targetBaseUrl: options.targetBaseUrl,
+    pathRewrite: options.pathRewrite,
+    headers: options.headers,
+    timeout: options.timeout,
+    onError: (error) => telemetry.emit('onWebSocketProxyFailed', error),
+  })
+  return async ({ req, socket, head }: { req: IncomingMessage; socket: Duplex; head: Buffer }) =>
+    handler.handle(req, socket, head)
+}
+
+const shouldExecProxy =
+  (sourceBaseUrl: string) =>
+  ({ req }: { req: Pick<IncomingMessage, 'url' | 'method'> }): boolean =>
+    req.url ? PathHelper.matchesBaseUrl(req.url, sourceBaseUrl) : false
+
+/**
+ * Validates the proxy configuration and returns a {@link ServerApi} that
+ * forwards HTTP (and optionally WebSocket) traffic from
+ * `options.sourceBaseUrl` to `options.targetBaseUrl`.
+ */
+export const buildProxyServerApi = (options: ProxyOptions, telemetry: ServerTelemetry): ServerApi => {
+  const pathProcessor = new PathProcessor()
+  const targetUrl = pathProcessor.validateUrl(options.targetBaseUrl, 'targetBaseUrl')
+  pathProcessor.validateHttpProtocol(targetUrl)
+
+  return {
+    shouldExec: shouldExecProxy(options.sourceBaseUrl),
+    onRequest: createRequestHandler(options, telemetry),
+    ...(options.enableWebsockets ? { onUpgrade: createUpgradeHandler(options, telemetry) } : {}),
+  }
+}

package/src/request-action-implementation.ts

@@ -1,12 +1,17 @@
 import type { Injector } from '@furystack/inject'
 import type { IncomingMessage, ServerResponse } from 'http'
 
+/**
+ * The shape returned by every {@link RequestAction}. Consumed by the runtime
+ * to write the response (`statusCode`, `headers`, serialized `chunk`).
+ */
 export interface ActionResult<T> {
   statusCode: number
   headers: { [K: string]: string }
   chunk: T
 }
 
+/** {@link ActionResult} with `application/json`. Default status 200. */
 export const JsonResult = <T extends object>(chunk: T, statusCode = 200, headers?: { [K: string]: string }) =>
   ({
     statusCode,
@@ -17,6 +22,7 @@ export const JsonResult = <T extends object>(chunk: T, statusCode = 200, headers
     },
   }) as ActionResult<T>
 
+/** {@link ActionResult} with `plain/text`. Default status 200. */
 export const PlainTextResult = (text: string, statusCode = 200, headers?: { [K: string]: string }) =>
   ({
     statusCode,
@@ -27,6 +33,7 @@ export const PlainTextResult = (text: string, statusCode = 200, headers?: { [K:
     },
   }) as ActionResult<string>
 
+/** {@link ActionResult} with `application/xml;charset=utf-8`. Default status 200. */
 export const XmlResult = (text: string, statusCode = 200, headers?: { [K: string]: string }) =>
   ({
     statusCode,
@@ -37,6 +44,7 @@ export const XmlResult = (text: string, statusCode = 200, headers?: { [K: string
     },
   }) as ActionResult<string>
 
+/** {@link ActionResult} with no body. Use for `204 No Content` responses. */
 export const EmptyResult = (statusCode = 200, headers?: { [K: string]: string }) =>
   ({
     statusCode,
@@ -45,11 +53,22 @@ export const EmptyResult = (statusCode = 200, headers?: { [K: string]: string })
     },
   }) as ActionResult<undefined>
 
+/**
+ * Sentinel result that signals "skip this action; let the runtime fall
+ * through to the next matching handler (or 404 if none)". Returned from
+ * an action when it decides not to handle the request after inspection.
+ */
 export const BypassResult = () =>
   ({
     chunk: 'BypassResult',
   }) as ActionResult<'BypassResult'>
 
+/**
+ * Argument shape passed to a {@link RequestAction}. Conditional members
+ * (`getBody`, `getUrlParams`, `getQuery`, `headers`) are present only when
+ * the action's contract declares the corresponding key — keeping unrelated
+ * actions free of unused parser allocations.
+ */
 export type RequestActionOptions<T extends { result: unknown }> = {
   request: IncomingMessage
   response: ServerResponse
@@ -64,6 +83,12 @@ export type RequestActionOptions<T extends { result: unknown }> = {
   (T extends { result: unknown; query: infer U } ? { getQuery: () => U } : unknown) &
   (T extends { result: unknown; headers: infer U } ? { headers: U } : unknown)
 
+/**
+ * Server-side implementation of a typed REST endpoint contract `T` (declared
+ * via `@furystack/rest`). Receives {@link RequestActionOptions} narrowed to
+ * the contract's body/url/query/headers and resolves to an {@link ActionResult}
+ * carrying the contract's `result` shape.
+ */
 export type RequestAction<T extends { result: unknown }> = (
   options: RequestActionOptions<T>,
 ) => Promise<ActionResult<T['result']>>

package/src/rest-api-runtime.spec.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest'
+import { JsonResult } from './request-action-implementation.js'
+import { compileApi, shouldExecRequest, type RestApiImplementation } from './rest-api-runtime.js'
+
+type SampleApi = {
+  GET: {
+    '/items': { result: { items: number[] } }
+    '/items/:id': { url: { id: string }; result: { id: string } }
+  }
+  POST: {
+    '/items': { body: { name: string }; result: { name: string } }
+  }
+}
+
+const buildImplementation = (): RestApiImplementation<SampleApi> => ({
+  GET: {
+    '/items': async () => JsonResult({ items: [1, 2, 3] }),
+    '/items/:id': async ({ getUrlParams }) => JsonResult({ id: getUrlParams().id }),
+  },
+  POST: {
+    '/items': async ({ getBody }) => JsonResult(await getBody()),
+  },
+})
+
+describe('rest-api-runtime', () => {
+  describe('compileApi', () => {
+    it('normalises paths, prefixes the root, and preserves method→route ordering', () => {
+      const compiled = compileApi<SampleApi>(buildImplementation(), '/api')
+      expect(Object.keys(compiled)).toEqual(['GET', 'POST'])
+      const getRoutes = compiled.GET!
+      expect(getRoutes).toHaveLength(2)
+      expect(getRoutes[0].method).toBe('GET')
+      expect(getRoutes[0].fullPath).toBe('/api/items')
+      expect(getRoutes[1].fullPath).toBe('/api/items/:id')
+    })
+
+    it('produces matchers that extract url params', () => {
+      const compiled = compileApi<SampleApi>(buildImplementation(), '/api')
+      const itemById = compiled.GET!.find((r) => r.fullPath === '/api/items/:id')!
+      const result = itemById.matcher('/api/items/42')
+      expect(result && result.params).toEqual({ id: '42' })
+    })
+
+    it('returns false from matchers when the path does not match', () => {
+      const compiled = compileApi<SampleApi>(buildImplementation(), '/api')
+      const itemByIdMatcher = compiled.GET!.find((r) => r.fullPath === '/api/items/:id')!.matcher
+      expect(itemByIdMatcher('/api/items')).toBe(false)
+      expect(itemByIdMatcher('/other')).toBe(false)
+    })
+  })
+
+  describe('shouldExecRequest', () => {
+    const supportedMethods = ['GET', 'POST'] as string[]
+    const rootApiPath = '/api'
+
+    it('accepts supported methods whose URL starts with the root api path', () => {
+      expect(shouldExecRequest({ method: 'GET', url: '/api/items', rootApiPath, supportedMethods })).toBe(true)
+    })
+
+    it('accepts OPTIONS (preflight) even when it is not explicitly in supportedMethods', () => {
+      expect(shouldExecRequest({ method: 'OPTIONS', url: '/api/items', rootApiPath, supportedMethods })).toBe(true)
+    })
+
+    it('rejects unsupported methods', () => {
+      expect(shouldExecRequest({ method: 'DELETE', url: '/api/items', rootApiPath, supportedMethods })).toBe(false)
+    })
+
+    it('rejects URLs that do not match the root api path', () => {
+      expect(shouldExecRequest({ method: 'GET', url: '/other/items', rootApiPath, supportedMethods })).toBe(false)
+    })
+
+    it('rejects requests missing method or url', () => {
+      expect(shouldExecRequest({ method: undefined, url: '/api/items', rootApiPath, supportedMethods })).toBe(false)
+      expect(shouldExecRequest({ method: 'GET', url: undefined, rootApiPath, supportedMethods })).toBe(false)
+    })
+  })
+})

package/src/rest-api-runtime.ts

@@ -0,0 +1,204 @@
+import { IdentityContext, type User } from '@furystack/core'
+import type { Injector } from '@furystack/inject'
+import type { Method, RestApi } from '@furystack/rest'
+import { RequestError, deserializeQueryString } from '@furystack/rest'
+import { PathHelper, usingAsync } from '@furystack/utils'
+import type { MatchFunction } from 'path-to-regexp'
+import { match } from 'path-to-regexp'
+import { ErrorAction } from './actions/error-action.js'
+import { NotFoundAction } from './actions/not-found-action.js'
+import { addCorsHeaders } from './add-cors-header.js'
+import { HttpUserContext } from './http-user-context.js'
+import type { CorsOptions } from './models/cors-options.js'
+import { readPostBody } from './read-post-body.js'
+import type { RequestAction } from './request-action-implementation.js'
+import './server-response-extensions.js'
+import type { OnRequest } from './http-server-pool.js'
+import { DEFAULT_HOST } from './http-server-pool.js'
+
+/**
+ * Concrete runtime representation of an API implementation — the object the
+ * application supplies to `useRestService` gets wrapped in this structure at
+ * registration time. Each method maps to an ordered array of compiled routes.
+ */
+export type RestApiImplementation<T extends RestApi> = {
+  [TMethod in keyof T]: {
+    [TUrl in keyof T[TMethod]]: T[TMethod][TUrl] extends { result: unknown } ? RequestAction<T[TMethod][TUrl]> : never
+  }
+}
+
+/**
+ * Compiled entry representing a single route: the HTTP method, the fully
+ * qualified path, a `path-to-regexp` matcher and the user-supplied
+ * action.
+ */
+export type CompiledApiEntry = {
+  method: Method
+  fullPath: string
+  matcher: MatchFunction<Partial<Record<string, string | string[]>>>
+  action: RequestAction<any>
+}
+
+/**
+ * Grouping of {@link CompiledApiEntry}s keyed by HTTP method. Built once at
+ * setup time and reused for every incoming request.
+ */
+export type CompiledApi = {
+  [K in Method]?: CompiledApiEntry[]
+}
+
+/** Options accepted by {@link onRestApiMessage}. */
+export type OnRestApiMessageOptions = OnRequest & {
+  compiledApi: CompiledApi
+  hostName?: string
+  port: number
+  rootApiPath: string
+  injector: Injector
+  cors?: CorsOptions
+  supportedMethods: string[]
+  deserializeQueryParams?: (param: string) => Record<string, unknown>
+}
+
+/**
+ * Compiles a user-supplied REST API definition into the runtime shape used by
+ * {@link onRestApiMessage}. Each method's route map is transformed into an
+ * array of `{method, fullPath, matcher, action}` entries. The `root` prefix
+ * is prepended to every path.
+ */
+export const compileApi = <T extends RestApi>(api: RestApiImplementation<T>, root: string): CompiledApi => {
+  const supportedMethods = Object.keys(api) as Method[]
+  const compiled: CompiledApi = {}
+  supportedMethods.forEach((method) => {
+    compiled[method] = Object.entries(api[method as keyof typeof api]).map(([path, action]) => {
+      const fullPath = `/${PathHelper.normalize(PathHelper.joinPaths(root, path))}`
+      const matcher = match(fullPath, { decode: decodeURIComponent })
+      return { method, fullPath, matcher, action: action as RequestAction<any> }
+    })
+  })
+  return compiled
+}
+
+/**
+ * Quick eligibility check executed by the server pool before invoking a
+ * {@link ServerApi.onRequest}. Avoids the cost of URL parsing and CORS header
+ * handling for requests this API clearly does not own.
+ */
+export const shouldExecRequest = (options: {
+  method?: Method
+  url?: string
+  rootApiPath: string
+  supportedMethods: string[]
+}): boolean => {
+  if (!options.method || !options.url) {
+    return false
+  }
+  if (!options.supportedMethods.includes(options.method) && options.method !== 'OPTIONS') {
+    return false
+  }
+  return PathHelper.matchesBaseUrl(options.url, options.rootApiPath)
+}
+
+const getActionFromEndpoint = (compiledApi: CompiledApi, fullUrl: URL, method: Method) => {
+  let resolvedParams: unknown
+  const action = compiledApi[method]?.find((route) => {
+    const result = route.matcher(fullUrl.pathname)
+    if (result) {
+      resolvedParams = result.params
+    }
+    return result
+  })
+  return (
+    action && {
+      ...action,
+      params: resolvedParams,
+    }
+  )
+}
+
+const executeAction = async (
+  options: OnRestApiMessageOptions & {
+    fullUrl: URL
+    action: RequestAction<{ body: object; result: object; query: object; url: object; headers: object }>
+    params: unknown
+  },
+): Promise<void> => {
+  const { injector, req, res, fullUrl, action, deserializeQueryParams, params } = options
+  await usingAsync(injector.createScope({ owner: action }), async (scope) => {
+    const httpUserContext = scope.get(HttpUserContext)
+    scope.bind(IdentityContext, () => ({
+      getCurrentUser: <TUser extends User>() => httpUserContext.getCurrentUser(req) as Promise<TUser>,
+      isAuthorized: (...roles) => httpUserContext.isAuthorized(req, ...roles),
+      isAuthenticated: () => httpUserContext.isAuthenticated(req),
+    }))
+    try {
+      const actionResult = await action({
+        request: req,
+        response: res,
+        injector: scope,
+        getBody: () => readPostBody<never>(req),
+        headers: req.headers,
+        getQuery: () =>
+          deserializeQueryParams ? deserializeQueryParams(fullUrl.search) : deserializeQueryString(fullUrl.search),
+        getUrlParams: () => params as object,
+      })
+      res.sendActionResult(actionResult)
+    } catch (error) {
+      const errorActionResult = await ErrorAction({
+        request: req,
+        response: res,
+        injector: scope,
+        getBody: async () => error,
+      })
+      res.sendActionResult(errorActionResult)
+    }
+  })
+}
+
+/**
+ * Handles a single incoming HTTP request matched by a REST API's
+ * {@link ServerApi.shouldExec}. Normalises the URL, applies CORS headers,
+ * short-circuits `OPTIONS` preflights and dispatches to the compiled action.
+ *
+ * Moved out of the deleted `ApiManager.onMessage` verbatim; behaviour is
+ * unchanged apart from injector resolution (`get` instead of `getInstance`).
+ */
+export const onRestApiMessage = async (options: OnRestApiMessageOptions): Promise<void> => {
+  const protocol = 'http://'
+  const host = `${options.hostName ?? DEFAULT_HOST}:${options.port}`
+  const fullUrl = new URL(PathHelper.joinUrl(`${protocol}${host}`, options.req.url as string))
+
+  if (options.cors) {
+    addCorsHeaders(options.cors, options.req, options.res)
+  }
+
+  if (options.req.method === 'OPTIONS') {
+    options.res.writeHead(200)
+    options.res.end()
+    return
+  }
+
+  let action: ReturnType<typeof getActionFromEndpoint>
+  try {
+    action = getActionFromEndpoint(options.compiledApi, fullUrl, options.req.method?.toUpperCase() as Method)
+  } catch (error) {
+    const responseError =
+      error instanceof URIError ? new RequestError('Failed to decode URL path parameter', 400) : (error as Error)
+    const errorActionResult = await ErrorAction({
+      request: options.req,
+      response: options.res,
+      injector: options.injector,
+      getBody: async () => responseError,
+    })
+    options.res.sendActionResult(errorActionResult)
+    return
+  }
+
+  if (action) {
+    await executeAction({ ...options, ...action, fullUrl })
+    return
+  }
+
+  options.res.sendActionResult(
+    await NotFoundAction({ injector: options.injector, request: options.req, response: options.res }),
+  )
+}