@furystack/rest-service 13.0.0 → 14.1.0

package/src/api-manager.ts

@@ -1,304 +0,0 @@
-import type { User } from '@furystack/core'
-import { IdentityContext } from '@furystack/core'
-import type { Injector } from '@furystack/inject'
-import { Injectable, Injected } 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 { CreateGetSchemaAction } from './endpoint-generators/create-get-schema-action.js'
-import { CreateGetOpenApiDocumentAction } from './endpoint-generators/create-get-openapi-document-action.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 type { OnRequest, ServerApi } from './server-manager.js'
-import { ServerManager } from './server-manager.js'
-import './server-response-extensions.js'
-
-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
-  }
-}
-
-export interface ImplementApiOptions<T extends RestApi> {
-  /**
-   * The structure of the implemented API.
-   */
-  api: RestApiImplementation<T>
-  /**
-   * The Injector instance to use for dependency injection in the API actions.
-   */
-  injector: Injector
-  /**
-   * The host name for the API Server. If not provided, the default host (ServerManager.DEFAULT_HOST) will be used.
-   */
-  hostName?: string
-  /**
-   * The root path for the API. This will be prepended to all API paths.
-   */
-  root: string
-  /**
-   * The port on which the API server will listen.
-   */
-  port: number
-  /**
-   * CORS options to configure Cross-Origin Resource Sharing for the API.
-   */
-  cors?: CorsOptions
-  /**
-   * An optional function to deserialize query parameters from the URL.
-   * This function should take a query string (e.g., "?key=value") and return an object with the parsed parameters.
-   * If not provided, the default deserialization will be used.
-   */
-  deserializeQueryParams?: (param: string) => any
-  /**
-   * Adds an additional 'GET /schema' endpoint that returns the schema definitions of the API.
-   * Also adds a 'GET /openapi.json' endpoint that returns the API schema in OpenAPI 3.1 format.
-   */
-  enableGetSchema?: boolean
-
-  /**
-   * Optional name for the API, used in the generated schema.
-   * This can be useful for documentation or identification purposes.
-   */
-  name?: string
-  /**
-   * Optional description for the API, used in the generated schema.
-   * This can provide additional context or information about the API's purpose.
-   */
-  description?: string
-  /**
-   * Optional version for the API, used in the generated schema.
-   * This can help in versioning the API and tracking changes over time.
-   */
-  version?: string
-}
-
-export type NewCompiledApiEntry = {
-  method: Method
-  fullPath: string
-  matcher: MatchFunction<Partial<Record<string, string | string[]>>>
-  action: RequestAction<any>
-}
-
-export type NewCompiledApi = {
-  [K in Method]?: NewCompiledApiEntry[]
-}
-
-export type OnRequestOptions = OnRequest & {
-  compiledApi: NewCompiledApi
-  hostName?: string
-  port: number
-  rootApiPath: string
-  injector: Injector
-  cors?: CorsOptions
-  supportedMethods: string[]
-  deserializeQueryParams?: (param: string) => Record<string, unknown>
-}
-
-@Injectable({ lifetime: 'singleton' })
-export class ApiManager {
-  private getSuportedMethods(api: RestApiImplementation<RestApi>): Method[] {
-    return Object.keys(api) as Method[]
-  }
-
-  private compileApi<T extends RestApi>(api: RestApiImplementation<T>, root: string) {
-    const supportedMethods = this.getSuportedMethods(api)
-
-    const compiledApi: NewCompiledApi = {}
-    supportedMethods.forEach((method: Method) => {
-      compiledApi[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 compiledApi
-  }
-
-  public async addApi<T extends RestApi>({
-    api,
-    hostName,
-    port,
-    root,
-    cors,
-    injector,
-    deserializeQueryParams,
-    enableGetSchema,
-    name,
-    description,
-    version,
-  }: ImplementApiOptions<T>) {
-    const extendedApi: typeof api = enableGetSchema
-      ? {
-          ...api,
-          GET: {
-            ...api.GET,
-            '/schema': CreateGetSchemaAction(api, name, description, version),
-            '/openapi.json': CreateGetOpenApiDocumentAction(api, name, description, version),
-          },
-        }
-      : api
-
-    const supportedMethods = this.getSuportedMethods(extendedApi)
-    const rootApiPath = PathHelper.normalize(root)
-    const server = await this.serverManager.getOrCreate({ hostName, port })
-    const compiledApi = this.compileApi(extendedApi, root)
-    const serverApi = {
-      shouldExec: (msg) =>
-        this.shouldExecRequest({
-          ...msg,
-          method: msg.req.method?.toUpperCase() as Method,
-          rootApiPath,
-          supportedMethods,
-          url: PathHelper.normalize(msg.req.url || ''),
-        }),
-      onRequest: (msg) =>
-        this.onMessage({
-          ...msg,
-          compiledApi,
-          rootApiPath,
-          port,
-          supportedMethods,
-          cors,
-          injector,
-          hostName,
-          deserializeQueryParams,
-        }),
-    } satisfies ServerApi
-    server.apis.push(serverApi)
-    return serverApi
-  }
-
-  public shouldExecRequest(options: {
-    method?: Method
-    url?: string
-    rootApiPath: string
-    supportedMethods: Method[]
-  }): boolean {
-    return options.method &&
-      options.url &&
-      (options.supportedMethods.includes(options.method) || options.method === 'OPTIONS') &&
-      PathHelper.matchesBaseUrl(options.url, options.rootApiPath)
-      ? true
-      : false
-  }
-
-  private getActionFromEndpoint(compiledEndpoint: NewCompiledApi, fullUrl: URL, method: Method) {
-    let resolvedParams: unknown
-    const action = compiledEndpoint[method]?.find((route) => {
-      const result = route.matcher(fullUrl.pathname)
-      if (result) {
-        resolvedParams = result.params
-      }
-      return result
-    })
-    return (
-      action && {
-        ...action,
-        params: resolvedParams,
-      }
-    )
-  }
-
-  private async executeAction({
-    injector,
-    req,
-    res,
-    fullUrl,
-    action,
-    deserializeQueryParams,
-    params,
-  }: OnRequestOptions & {
-    fullUrl: URL
-    action: RequestAction<{ body: object; result: object; query: object; url: object; headers: object }>
-    params: unknown
-  }) {
-    await usingAsync(injector.createChild({ owner: action }), async (i) => {
-      const httpUserContext = i.getInstance(HttpUserContext)
-      i.setExplicitInstance<IdentityContext>(
-        {
-          getCurrentUser: <TUser extends User>() => httpUserContext.getCurrentUser(req) as Promise<TUser>,
-          isAuthorized: (...roles) => httpUserContext.isAuthorized(req, ...roles),
-          isAuthenticated: () => httpUserContext.isAuthenticated(req),
-        },
-        IdentityContext,
-      )
-      try {
-        const actionResult = await action({
-          request: req,
-          response: res,
-          injector: i,
-          getBody: () => readPostBody<any>(req),
-          headers: req.headers,
-          getQuery: () =>
-            deserializeQueryParams ? deserializeQueryParams(fullUrl.search) : deserializeQueryString(fullUrl.search),
-          getUrlParams: () => {
-            return params as object
-          },
-        })
-        res.sendActionResult(actionResult)
-      } catch (error) {
-        const errorActionResult = await ErrorAction({
-          request: req,
-          response: res,
-          injector: i,
-          getBody: async () => error,
-        })
-        res.sendActionResult(errorActionResult)
-      }
-      return
-    })
-  }
-
-  private async onMessage(options: OnRequestOptions) {
-    const protocol = 'http://'
-    const host = `${options.hostName || ServerManager.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 this.getActionFromEndpoint>
-    try {
-      action = this.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 this.executeAction({ ...options, ...action, fullUrl })
-    } else {
-      options.res.sendActionResult(
-        await NotFoundAction({ injector: options.injector, request: options.req, response: options.res }),
-      )
-    }
-  }
-
-  @Injected(ServerManager)
-  declare private readonly serverManager: ServerManager
-}

package/src/proxy-manager.ts

@@ -1,102 +0,0 @@
-import { Injectable, Injected } from '@furystack/inject'
-import { EventHub, PathHelper, type ListenerErrorPayload } from '@furystack/utils'
-import type { IncomingMessage, OutgoingHttpHeaders, ServerResponse } from 'http'
-import type { Duplex } from 'stream'
-import { HttpProxyHandler } from './http-proxy-handler.js'
-import { PathProcessor } from './path-processor.js'
-import { ServerManager } from './server-manager.js'
-import { WebSocketProxyHandler } from './websocket-proxy-handler.js'
-
-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
-}
-
-/**
- * Manages HTTP and WebSocket proxy configurations and routing
- */
-@Injectable({ lifetime: 'singleton' })
-export class ProxyManager extends EventHub<{
-  onProxyFailed: { from: string; to: string; error: unknown }
-  onWebSocketProxyFailed: { from: string; to: string; error: unknown }
-  onListenerError: ListenerErrorPayload
-}> {
-  @Injected(ServerManager)
-  declare private readonly serverManager: ServerManager
-
-  private readonly pathProcessor = new PathProcessor()
-
-  /**
-   * Creates a function that determines if a request should be handled by this proxy
-   */
-  public shouldExec =
-    (sourceBaseUrl: string) =>
-    ({ req }: { req: Pick<IncomingMessage, 'url' | 'method'> }) =>
-      req.url ? PathHelper.matchesBaseUrl(req.url, sourceBaseUrl) : false
-
-  /**
-   * Creates an HTTP request handler for the proxy
-   */
-  private createRequestHandler(options: ProxyOptions) {
-    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) => this.emit('onProxyFailed', error),
-    })
-
-    return async ({ req, res }: { req: IncomingMessage; res: ServerResponse }) => {
-      await handler.handle(req, res)
-    }
-  }
-
-  /**
-   * Creates a WebSocket upgrade handler for the proxy
-   */
-  private createUpgradeHandler(options: ProxyOptions) {
-    const handler = new WebSocketProxyHandler({
-      sourceBaseUrl: options.sourceBaseUrl,
-      targetBaseUrl: options.targetBaseUrl,
-      pathRewrite: options.pathRewrite,
-      headers: options.headers,
-      timeout: options.timeout,
-      onError: (error) => this.emit('onWebSocketProxyFailed', error),
-    })
-
-    return async ({ req, socket, head }: { req: IncomingMessage; socket: Duplex; head: Buffer }) => {
-      await handler.handle(req, socket, head)
-    }
-  }
-
-  /**
-   * Adds a new proxy configuration
-   * @throws Error if targetBaseUrl is invalid or uses non-HTTP/HTTPS protocol
-   */
-  public async addProxy(options: ProxyOptions): Promise<void> {
-    // Validate targetBaseUrl format
-    const url = this.pathProcessor.validateUrl(options.targetBaseUrl, 'targetBaseUrl')
-    this.pathProcessor.validateHttpProtocol(url)
-
-    const server = await this.serverManager.getOrCreate({ hostName: options.sourceHostName, port: options.sourcePort })
-
-    const api = {
-      shouldExec: this.shouldExec(options.sourceBaseUrl),
-      onRequest: this.createRequestHandler(options),
-      ...(options.enableWebsockets ? { onUpgrade: this.createUpgradeHandler(options) } : {}),
-    }
-
-    server.apis.push(api)
-  }
-}

package/src/server-manager.ts

@@ -1,135 +0,0 @@
-import { Injectable } from '@furystack/inject'
-import { EventHub, type ListenerErrorPayload } from '@furystack/utils'
-import type { IncomingMessage, Server, ServerResponse } from 'http'
-import { createServer } from 'http'
-import type { Socket } from 'net'
-import type { Duplex } from 'stream'
-
-export interface ServerOptions {
-  hostName?: string
-  port: number
-}
-
-export interface OnRequest {
-  req: IncomingMessage
-  res: ServerResponse
-}
-
-export interface OnUpgrade {
-  req: IncomingMessage
-  socket: Duplex
-  head: Buffer
-}
-
-export interface ServerApi {
-  shouldExec: (options: OnRequest) => boolean
-  onRequest: (options: OnRequest) => Promise<void>
-  onUpgrade?: (options: OnUpgrade) => Promise<void>
-}
-
-export interface ServerRecord {
-  server: Server
-  apis: ServerApi[]
-}
-
-@Injectable({ lifetime: 'singleton' })
-export class ServerManager
-  extends EventHub<{
-    onRequestFailed: [unknown, IncomingMessage, ServerResponse<IncomingMessage>]
-    onServerListening: { url: string; port: number; hostName?: string }
-    onServerClosed: { url: string }
-    onListenerError: ListenerErrorPayload
-  }>
-  implements AsyncDisposable
-{
-  public static DEFAULT_HOST = 'localhost'
-  public servers = new Map<string, ServerRecord>()
-  private openedSockets = new Set<Socket>()
-  private readonly pendingCreates = new Map<string, Promise<ServerRecord>>()
-  private getHostUrl = (options: ServerOptions) =>
-    `http://${options.hostName || ServerManager.DEFAULT_HOST}:${options.port}`
-
-  private onConnection = (socket: Socket) => {
-    this.openedSockets.add(socket)
-    socket.once('close', () => this.openedSockets.delete(socket))
-  }
-  public async [Symbol.asyncDispose]() {
-    await Promise.allSettled([...this.pendingCreates.values()])
-    this.openedSockets.forEach((s) => s.destroy())
-    await Promise.allSettled(
-      [...this.servers.entries()].map(
-        ([url, s]) =>
-          new Promise<void>((resolve, reject) => {
-            s.server.close((err) => {
-              if (err) {
-                reject(err)
-              } else {
-                this.emit('onServerClosed', { url })
-                resolve()
-              }
-            })
-            s.server.off('connection', this.onConnection)
-          }),
-      ),
-    )
-    this.servers.clear()
-    super[Symbol.dispose]?.()
-  }
-
-  public async getOrCreate(options: ServerOptions): Promise<ServerRecord> {
-    const url = this.getHostUrl(options)
-
-    const existing = this.servers.get(url)
-    if (existing) {
-      return existing
-    }
-
-    const pending = this.pendingCreates.get(url)
-    if (pending) {
-      return pending
-    }
-
-    const createPromise = this.createServer(url, options)
-    this.pendingCreates.set(url, createPromise)
-    return createPromise
-  }
-
-  private async createServer(url: string, options: ServerOptions): Promise<ServerRecord> {
-    const apis: ServerRecord['apis'] = []
-    const server = createServer((req, res) => {
-      const apiMatch = apis.find((api) => api.shouldExec({ req, res }))
-      if (apiMatch) {
-        apiMatch.onRequest({ req, res }).catch((error) => {
-          this.emit('onRequestFailed', [error, req, res])
-        })
-      } else {
-        res.destroy()
-      }
-    })
-    server.on('upgrade', (req, socket, head) => {
-      const apiMatch = apis.find((api) => api.shouldExec({ req, res: {} as ServerResponse }))
-      if (apiMatch?.onUpgrade) {
-        apiMatch.onUpgrade({ req, socket, head }).catch((error) => {
-          this.emit('onRequestFailed', [error, req, {} as ServerResponse])
-          socket.destroy()
-        })
-      } else {
-        socket.destroy()
-      }
-    })
-    server.on('connection', this.onConnection)
-    try {
-      await new Promise<void>((resolve, reject) => {
-        server.on('listening', () => resolve())
-        server.on('error', (err) => reject(err))
-        server.listen(options.port, options.hostName)
-      })
-      const record: ServerRecord = { server, apis }
-      this.servers.set(url, record)
-      this.emit('onServerListening', { url, port: options.port, hostName: options.hostName })
-      return record
-    } finally {
-      this.pendingCreates.delete(url)
-    }
-  }
-}

package/src/static-server-manager.ts

@@ -1,90 +0,0 @@
-import { Injectable, Injected } from '@furystack/inject'
-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 { getMimeForFile } from './mime-types.js'
-import { ServerManager } from './server-manager.js'
-
-export interface StaticServerOptions {
-  baseUrl: string
-  path: string
-  hostName?: string
-  port: number
-  fallback?: string
-  headers?: OutgoingHttpHeaders
-}
-
-@Injectable({ lifetime: 'singleton' })
-export class StaticServerManager {
-  @Injected(ServerManager)
-  declare private readonly serverManager: ServerManager
-
-  private async sendFile({
-    fullPath,
-    headers,
-    res,
-  }: {
-    fullPath: string
-    res: ServerResponse
-    headers?: OutgoingHttpHeaders
-  }) {
-    const { size } = await stat(fullPath)
-
-    await access(fullPath)
-
-    const head = {
-      ...headers,
-      'Content-Length': size,
-      'Content-Type': getMimeForFile(fullPath),
-    }
-    Object.entries(head).map(([key, value]) => res.setHeader(key, value))
-    await new Promise<void>((resolve, reject) =>
-      createReadStream(fullPath, { autoClose: true }).once('finish', resolve).once('error', reject).pipe(res),
-    )
-  }
-
-  public shouldExec =
-    (baseUrl: string) =>
-    ({ req }: { req: Pick<IncomingMessage, 'url' | 'method'> }) =>
-      req.url && req.method?.toUpperCase() === 'GET' && PathHelper.matchesBaseUrl(req.url, baseUrl) ? true : false
-
-  private onRequest = ({
-    path,
-    baseUrl,
-    fallback,
-    headers,
-  }: {
-    path: string
-    baseUrl: string
-    fallback?: string
-    headers?: OutgoingHttpHeaders
-  }) => {
-    return async ({ req, res }: { req: IncomingMessage; res: ServerResponse }) => {
-      const extractedPath = PathHelper.extractPath(req.url as string, baseUrl)
-      const filePath = (extractedPath || '/').replaceAll('/', sep)
-      const fullPath = normalize(join(path, filePath))
-
-      try {
-        await this.sendFile({ fullPath, res, headers })
-      } catch (error) {
-        if (fallback) {
-          await this.sendFile({ fullPath: normalize(join(path, fallback)), res, headers })
-        } else {
-          res.writeHead(404, { 'Content-Type': 'text/plain' })
-          res.end('Not found')
-        }
-      }
-    }
-  }
-
-  public async addStaticSite(options: StaticServerOptions) {
-    const server = await this.serverManager.getOrCreate({ hostName: options.hostName, port: options.port })
-
-    server.apis.push({
-      shouldExec: this.shouldExec(options.baseUrl),
-      onRequest: this.onRequest({ ...options }),
-    })
-  }
-}