sleepy-serv 0.6.2 → 0.8.0

package/src/{index.js → index.ts}

@@ -4,7 +4,7 @@ import querystring from 'querystring'
 import readline from 'node:readline'
 
 import { stdin, stdout } from 'node:process'
-import { toSegments, executeMiddlewareChain } from './utils'
+import { StatusCode, toSegments, executeMiddlewareChain } from './utils'
 
 import {
   buildSocketState,
@@ -14,10 +14,27 @@ import {
 } from './socket'
 
 import {
+  RequestError,
   NotFoundError,
   MethodNotAllowedError,
 } from './errors'
 
+import type { BunRequest } from 'bun'
+
+import type {
+  HttpMethod,
+  Middleware,
+  EndpointRequest,
+  AppOptions,
+  Server,
+} from './utils'
+
+import type {
+  SocketRoute,
+  SocketState,
+  SocketCommands,
+} from './socket'
+
 export * from './errors'
 
 export {
@@ -26,6 +43,81 @@ export {
   validateSchemas,
 } from './middleware'
 
+export { HttpMethod, StatusCode } from './utils'
+
+export type {
+  AppOptions,
+  EndpointRequest,
+  FormattedError,
+  Middleware,
+  NextFn,
+  Request,
+  Server,
+  SocketOptions,
+  WebSocketRequest,
+} from './utils'
+
+export type {
+  FormatterField,
+  FormatterSchema,
+  ValidationSchemas,
+} from './middleware'
+
+export type { SocketCommands } from './socket'
+
+type OutputRoutes = Record<string, string[]>
+type ServerRoutes = Record<string, Record<string, EndpointHandler>>
+
+type EndpointHandler = (
+  bunReq: BunRequest,
+  server: Server,
+) => Promise<Response>
+
+type DirEntry = {
+  path: string
+  stat: fs.Stats
+}
+
+type RoutePath = {
+  method: HttpMethod
+  path: string
+  metaMiddlewarePath: string[]
+  modulePath: string
+}
+
+type ChainRoute = {
+  method: HttpMethod
+  path: string
+  chain: Middleware[]
+}
+
+type ModuleRoute = {
+  method: HttpMethod
+  path: string
+  handler: EndpointHandler
+}
+
+type RoutingOptions = {
+  basePath: string
+  mountPath: string
+  metadata: string[]
+}
+
+type AppRoutes = {
+  server: ServerRoutes
+  output: OutputRoutes
+  socket: SocketRoute[]
+}
+
+type CloseFn = (force?: boolean) => Promise<void>
+
+export type App = {
+  server: Server
+  commands: SocketCommands
+  routes: OutputRoutes
+  close: CloseFn
+}
+
 const ALLOWED_FILES_META = ['meta.js', 'meta.ts']
 
 const ALLOWED_FILES_METHODS = [
@@ -43,21 +135,11 @@ const ALLOWED_FILES_METHODS = [
   'delete.ts',
 ]
 
-/* istanbul ignore if */
-if (process.stdin.isTTY) {
-  process.stdin.setRawMode(true)
-}
-
-const rl = readline.createInterface({
-  input: stdin,
-  output: stdout,
-})
-
-function methodNotAllowedHandler (_req) {
+function methodNotAllowedHandler (_req: unknown): never {
   throw new MethodNotAllowedError()
 }
 
-function defaultMethodMap () {
+function defaultMethodMap (): Record<string, EndpointHandler> {
   return {
     HEAD: methodNotAllowedHandler,
     GET: methodNotAllowedHandler,
@@ -68,13 +150,16 @@ function defaultMethodMap () {
   }
 }
 
-function buildBunRequest (bunReq, server) {
+function buildEndpointRequest (
+  bunReq: BunRequest,
+  server: Server,
+): EndpointRequest {
   const url = new URL(bunReq.url)
   const qs = url.search.replace('?', '')
   const json = () => bunReq.json()
 
   return {
-    method: bunReq.method,
+    method: bunReq.method as HttpMethod,
     route: url.pathname,
     headers: bunReq.headers,
     params: bunReq.params ?? {},
@@ -85,7 +170,11 @@ function buildBunRequest (bunReq, server) {
   }
 }
 
-function validateLeafDirectory (targetPath, filenames, entries) {
+function validateLeafDirectory (
+  targetPath: string,
+  filenames: string[],
+  entries: DirEntry[],
+): void {
   const hasDirectories = entries.some(entry => entry.stat.isDirectory())
 
   if (!hasDirectories) {
@@ -102,7 +191,7 @@ ${targetPath}
   }
 }
 
-function validateDirectory (targetPath, entries) {
+function validateDirectory (targetPath: string, entries: DirEntry[]): void {
   const filenames = entries
     .filter(entry => entry.stat.isFile())
     .map(entry => path.basename(entry.path))
@@ -110,7 +199,7 @@ function validateDirectory (targetPath, entries) {
   validateLeafDirectory(targetPath, filenames, entries)
 }
 
-function getAllFilePathsRec (targetPath, paths) {
+function getAllFilePathsRec (targetPath: string, paths: string[]): string[] {
   const entries = fs.readdirSync(targetPath)
 
   const children = entries.map(item => {
@@ -124,7 +213,7 @@ function getAllFilePathsRec (targetPath, paths) {
 
   validateDirectory(targetPath, children)
 
-  return children.reduce((accum, curr) => {
+  return children.reduce<string[]>((accum, curr) => {
     const result = curr.stat.isDirectory()
       ? getAllFilePathsRec(curr.path, paths)
       : [curr.path]
@@ -133,7 +222,10 @@ function getAllFilePathsRec (targetPath, paths) {
   }, [])
 }
 
-function getFilteredFilePaths (targetPath, allowedFiles) {
+function getFilteredFilePaths (
+  targetPath: string,
+  allowedFiles: string[],
+): string[] {
   const allPaths = getAllFilePathsRec(targetPath, [])
 
   return allPaths.filter(item =>
@@ -141,21 +233,23 @@ function getFilteredFilePaths (targetPath, allowedFiles) {
   )
 }
 
-function getMethodFilePaths (targetPath) {
+function getMethodFilePaths (targetPath: string): string[] {
   return getFilteredFilePaths(targetPath, ALLOWED_FILES_METHODS)
 }
 
-function getMetaFilePaths (targetPath) {
+function getMetaFilePaths (targetPath: string): string[] {
   return getFilteredFilePaths(targetPath, ALLOWED_FILES_META)
 }
 
-function selectMetaPaths (metadata, modulePath) {
+function selectMetaPaths (metadata: string[], modulePath: string): string[] {
   return metadata
     .filter(metaPath => modulePath.startsWith(path.dirname(metaPath)))
     .sort((a, b) => a.length - b.length)
 }
 
-async function resolveMetaMiddleware (metaPaths) {
+async function resolveMetaMiddleware (
+  metaPaths: string[],
+): Promise<Middleware[]> {
   const modules = await Promise.all(metaPaths.map(item => import(item)))
 
   return modules
@@ -166,7 +260,11 @@ async function resolveMetaMiddleware (metaPaths) {
     ], [])
 }
 
-function buildRoutePaths (rootPath, mountPath, metadata) {
+function buildRoutePaths (
+  rootPath: string,
+  mountPath: string,
+  metadata: string[],
+): RoutePath[] {
   const paths = getMethodFilePaths(rootPath)
 
   return paths.map(modulePath => {
@@ -182,7 +280,7 @@ function buildRoutePaths (rootPath, mountPath, metadata) {
     const metaMiddlewarePath = selectMetaPaths(metadata, modulePath)
 
     return {
-      method: segments[lastIndex].toUpperCase(),
+      method: segments[lastIndex].toUpperCase() as HttpMethod,
       path: joinedPath,
       metaMiddlewarePath,
       modulePath,
@@ -190,7 +288,10 @@ function buildRoutePaths (rootPath, mountPath, metadata) {
   })
 }
 
-async function buildChain (route, rootMiddleware) {
+async function buildChain (
+  route: RoutePath,
+  rootMiddleware: Middleware[],
+): Promise<ChainRoute> {
   const module = await import(route.modulePath)
   const metaMiddleware = await resolveMetaMiddleware(route.metaMiddlewarePath)
 
@@ -216,13 +317,21 @@ ${route.modulePath}
   }
 }
 
-function buildNormalRoutes (routePaths, rootMiddleware) {
+function buildNormalRoutes (
+  routePaths: RoutePath[],
+  rootMiddleware: Middleware[],
+): Promise<ChainRoute[]> {
   return Promise.all(
     routePaths.map(route => buildChain(route, rootMiddleware)),
   )
 }
 
-async function buildMergedRoutes (routePaths, middleware, state, opts) {
+async function buildMergedRoutes (
+  routePaths: ChainRoute[],
+  middleware: Middleware[],
+  state: SocketState,
+  opts: RoutingOptions,
+): Promise<ChainRoute[]> {
   const { basePath, mountPath, metadata } = opts
   const socketRoutes = buildSocketHandlers(state)
 
@@ -259,17 +368,17 @@ async function buildMergedRoutes (routePaths, middleware, state, opts) {
   return routePaths
 }
 
-function  buildSocketRoutes (mergedRoutes) {
+function buildSocketRoutes (mergedRoutes: ChainRoute[]): SocketRoute[] {
   return mergedRoutes.map(route => ({
     ...route,
     segments: toSegments(route.path),
   }))
 }
 
-function buildModuleRoutes (routePaths) {
-  return routePaths.map(route => {
-    const handler = async (bunReq, server) => {
-      const req = buildBunRequest(bunReq, server)
+function buildModuleRoutes (socketRoutes: SocketRoute[]): ModuleRoute[] {
+  return socketRoutes.map(route => {
+    const handler: EndpointHandler = async (bunReq, server) => {
+      const req = buildEndpointRequest(bunReq, server)
 
       return executeMiddlewareChain(req, route.chain)
     }
@@ -282,20 +391,21 @@ function buildModuleRoutes (routePaths) {
   })
 }
 
-function buildServerRoutes (moduleRoutes) {
-  return moduleRoutes.reduce((accum, curr) => {
-    if (!accum[curr.path]) {
-      accum[curr.path] = defaultMethodMap()
-    }
+function buildServerRoutes (moduleRoutes: ModuleRoute[]): ServerRoutes {
+  return moduleRoutes.reduce<ServerRoutes>(
+    (accum, curr) => {
+      if (!accum[curr.path]) {
+        accum[curr.path] = defaultMethodMap()
+      }
 
-    accum[curr.path][curr.method] = curr.handler
+      accum[curr.path][curr.method] = curr.handler
 
-    return accum
-  }, {})
+      return accum
+    }, {})
 }
 
-function buildOutputRoutes (moduleRoutes) {
-  return moduleRoutes.reduce((accum, curr) => {
+function buildOutputRoutes (moduleRoutes: ModuleRoute[]): OutputRoutes {
+  return moduleRoutes.reduce<OutputRoutes>((accum, curr) => {
     accum[curr.path] = accum[curr.path] || []
     accum[curr.path].push(curr.method)
 
@@ -303,7 +413,11 @@ function buildOutputRoutes (moduleRoutes) {
   }, {})
 }
 
-async function buildRoutes (rootPath, state, opts) {
+async function buildRoutes (
+  rootPath: string,
+  state: SocketState,
+  opts: AppOptions,
+): Promise<AppRoutes> {
   const basePath = `${rootPath}/api`
   const mountPath = opts.mountPath || ''
   const middleware = opts.middleware || []
@@ -336,7 +450,12 @@ async function buildRoutes (rootPath, state, opts) {
   }
 }
 
-function buildServer (port, routes, state, opts) {
+function buildServer (
+  port: number,
+  routes: AppRoutes,
+  state: SocketState,
+  opts: AppOptions,
+): Server {
   const hostname = opts.hostname || '0.0.0.0'
   const websocketServer = buildSocketServer(routes.socket, state)
 
@@ -351,42 +470,79 @@ function buildServer (port, routes, state, opts) {
     error (err) {
       console.error(err)
 
-      const status = err.constructor.status ?? 500
+      if (err instanceof RequestError) {
+        const ctor = err.constructor as typeof RequestError
 
-      return err.output !== undefined
-        ? Response.json(err.output, { status })
-        : new Response(err.message, { status })
+        return Response.json(err.output, { status: ctor.status })
+      }
+
+      return new Response(err.message, {
+        status: StatusCode.InternalServerError,
+      })
     },
   })
 }
 
-function processIO (port, server, opts) {
-  const onClose = opts.onClose || (() => { })
+function processIO (
+  port: number,
+  server: Server,
+  opts: AppOptions,
+): CloseFn {
+  const onClose = opts.onClose || (() => {})
 
   console.info(`Running on port: ${port}`)
   console.info('')
   console.info('Press Ctrl+D to gracefully shutdown')
   console.info('')
 
-  /* istanbul ignore next */
-  rl.on('close', async () => {
-    await server.stop()
+  const shutdown = async (force = false): Promise<void> => {
+    await server.stop(force)
     await onClose()
-    process.exit(0)
+  }
+
+  if (!stdin.isTTY) {
+    return shutdown
+  }
+
+  stdin.setRawMode(true)
+
+  const rl = readline.createInterface({
+    input: stdin,
+    output: stdout,
   })
+
+  /* istanbul ignore next */
+  const handleClose = async (): Promise<void> => {
+    await shutdown()
+    process.exit(0)
+  }
+
+  rl.on('close', handleClose)
+
+  return async (force = false) => {
+    rl.off('close', handleClose)
+    rl.close()
+    stdin.setRawMode(false)
+
+    await shutdown(force)
+  }
 }
 
-export async function createApp (port, rootPath, opts = {}) {
+export async function createApp (
+  port: number,
+  rootPath: string,
+  opts: AppOptions = {},
+): Promise<App> {
   const state = buildSocketState(opts)
   const routes = await buildRoutes(rootPath, state, opts)
   const server = buildServer(port, routes, state, opts)
   const commands = buildSocketCommands(state)
-
-  processIO(port, server, opts)
+  const close = processIO(port, server, opts)
 
   return {
     routes: routes.output,
     server,
     commands,
+    close,
   }
 }

package/src/messages.ts

@@ -0,0 +1,237 @@
+import Ajv from 'ajv'
+import addFormats from 'ajv-formats'
+import crypto from 'node:crypto'
+import { formatError } from './utils'
+import { UnprocessableContentError } from './errors'
+
+import type { ValidateFunction } from 'ajv'
+import type { HttpMethod } from './utils'
+
+export const MessageType = {
+  Request: 'request',
+  Response: 'response',
+  Welcome: 'welcome',
+  Heartbeat: 'heartbeat',
+  Notification: 'notification',
+} as const
+
+export type MessageType = typeof MessageType[keyof typeof MessageType]
+
+export const RECEIVED_MESSAGE_TYPES: string[] = [
+  MessageType.Heartbeat,
+  MessageType.Request,
+]
+
+export type BaseMessage = {
+  id: string
+  clientId: string
+  type: MessageType
+  timestamp: string
+}
+
+export type HeartbeatMessage = BaseMessage & {
+  type: typeof MessageType.Heartbeat
+}
+
+export type RequestMessage = BaseMessage & {
+  type: typeof MessageType.Request
+  method: HttpMethod
+  route: string
+  headers: Bun.HeadersInit
+  query: Record<string, unknown>
+  body: unknown
+}
+
+export type ResponseMessage = BaseMessage & {
+  type: typeof MessageType.Response
+  status: number
+  headers: Headers
+  body: unknown
+}
+
+export type WelcomeMessage = BaseMessage & {
+  type: typeof MessageType.Welcome
+  headers: Headers
+  body: {
+    heartbeatInterval: number
+    token: string
+  }
+}
+
+export type NotificationMessage = BaseMessage & {
+  type: typeof MessageType.Notification
+  event: string
+  headers: Headers
+  body: unknown
+}
+
+export type Message =
+  | HeartbeatMessage
+  | RequestMessage
+  | ResponseMessage
+  | WelcomeMessage
+  | NotificationMessage
+
+export type RawMessage = {
+  type?: string
+  [key: string]: unknown
+}
+
+export type IncomingMessage = HeartbeatMessage | RequestMessage
+
+export type MessageContent<T extends MessageType = MessageType> =
+  Partial<Pick<Extract<Message, { type: T }>, 'id'>>
+    & Omit<Extract<Message, { type: T }>, keyof BaseMessage>
+
+const ajv = new Ajv({
+  allErrors: true,
+  removeAdditional: 'all',
+})
+
+addFormats(ajv)
+
+const SCHEMA_BASE = {
+  type: 'object',
+  properties: {
+    id: {
+      type: 'string',
+      format: 'uuid',
+    },
+    clientId: {
+      type: 'string',
+      format: 'uuid',
+    },
+    type: {
+      type: 'string',
+      enum: RECEIVED_MESSAGE_TYPES,
+    },
+    timestamp: {
+      type: 'string',
+      format: 'date-time',
+    },
+  },
+  required: [
+    'id',
+    'clientId',
+    'type',
+    'timestamp',
+  ],
+}
+
+const validateHeartbeat = ajv.compile({
+  type: 'object',
+  properties: {
+    ...SCHEMA_BASE.properties,
+    type: {
+      type: 'string',
+      const: MessageType.Heartbeat,
+    },
+  },
+  required: SCHEMA_BASE.required,
+})
+
+const validateRequest = ajv.compile({
+  type: 'object',
+  properties: {
+    ...SCHEMA_BASE.properties,
+    type: {
+      type: 'string',
+      const: MessageType.Request,
+    },
+    method: {
+      type: 'string',
+      enum: [
+        'HEAD',
+        'GET',
+        'PUT',
+        'POST',
+        'PATCH',
+        'DELETE',
+      ],
+    },
+    route: {
+      type: 'string',
+      format: 'uri-reference',
+    },
+    headers: {
+      type: 'object',
+    },
+    query: {
+      type: 'object',
+    },
+    body: {
+      type: [
+        'boolean',
+        'number',
+        'string',
+        'object',
+        'array',
+        'null',
+      ],
+    },
+  },
+  required: [
+    ...SCHEMA_BASE.required,
+    'method',
+    'route',
+    'headers',
+    'query',
+    'body',
+  ],
+})
+
+const TYPE_VALIDATORS: Record<string, ValidateFunction> = {
+  [MessageType.Heartbeat]: validateHeartbeat,
+  [MessageType.Request]: validateRequest,
+}
+
+export function createMessage<T extends MessageType> (
+  clientId: string,
+  type: T,
+  content: MessageContent<T>,
+): Extract<Message, { type: T }> {
+  const id = content.id ?? crypto.randomUUID()
+  const timestamp = new Date().toISOString()
+
+  const base = {
+    id,
+    clientId,
+    type,
+    timestamp,
+  }
+
+  return {
+    ...content,
+    ...base,
+  } as Extract<Message, { type: T }>
+}
+
+export function validateMessage (message: RawMessage): IncomingMessage {
+  if (message.type === undefined) {
+    throw new UnprocessableContentError([
+      {
+        path: '',
+        message: `must have required property 'type'`,
+      },
+    ])
+  }
+
+  if (!RECEIVED_MESSAGE_TYPES.includes(message.type)) {
+    throw new UnprocessableContentError([
+      {
+        path: 'type',
+        message: `must be one of: ${RECEIVED_MESSAGE_TYPES}`,
+      },
+    ])
+  }
+
+  const validate = TYPE_VALIDATORS[message.type]
+
+  if (!validate(message)) {
+    const errors = validate.errors!.map(item => formatError('', item))
+
+    throw new UnprocessableContentError(errors)
+  }
+
+  return message as IncomingMessage
+}