Бэкенд на Fastify

import type { FastifyError, FastifySchemaValidationError } from 'fastify'
import type { SchemaErrorDataVar } from 'fastify/types/schema.js'
import { Type as T, type Static } from '@sinclair/typebox'

// Этот модуль собирает переиспользуемые типы и схемы, которые нужны маршрутам Fastify и плагинам.

/**
 * Обёртка над стандартной ошибкой Fastify для случаев, когда схема запроса не проходит валидацию.
 * Мы расширяем Error, чтобы получить сообщение и stack trace, и одновременно реализуем FastifyError,
 * чтобы Fastify понимал код ошибки и корректно возвращал ответ клиенту.
 */
export class ValidationProblem extends Error implements FastifyError {
  public readonly name = 'ValidationError'
  public readonly code = 'FST_ERR_VALIDATION'
  public readonly statusCode = 400
  public readonly validation: FastifySchemaValidationError[]
  public readonly validationContext: SchemaErrorDataVar

  constructor(
    message: string,
    errs: FastifySchemaValidationError[],
    ctx: SchemaErrorDataVar,
    options?: ErrorOptions
  ) {
    super(message, options)
    this.validation = errs
    this.validationContext = ctx
  }
}

// Схема ответа в формате RFC 9457 / Problem Details — единый JSON-формат для сообщений об ошибках (ранее RFC 7807, заменён на 9457).
export const ProblemDetails = T.Object(
  {
    type: T.String({ description: 'URI с подробным описанием ошибки (по умолчанию about:blank)' }),
    title: T.String({ description: 'Короткое человекочитаемое резюме проблемы' }),
    status: T.Integer({ minimum: 100, maximum: 599, description: 'HTTP-статус, с которым был отправлен ответ' }),
    detail: T.Optional(T.String({ description: 'Дополнительные сведения о том, что пошло не так' })),
    instance: T.Optional(T.String({ description: 'URI запроса, в котором возникла проблема' })),
    errorsText: T.Optional(T.String({ description: 'Сводное описание всех ошибок, собранных валидацией Fastify' })),
  },
  { additionalProperties: true }
)
export type ProblemDetails = Static<typeof ProblemDetails>

// Схема и тип пользователя, которые используются и в валидаторах, и в ответах API.
export const User = T.Object({
  id: T.String({ description: 'Уникальный идентификатор пользователя' }),
  email: T.String({ format: 'email', description: 'Адрес электронной почты' }),
})
export type User = Static<typeof User>

// Минимальная схема для health-check запроса.
export const Health = T.Object({
  ok: T.Boolean({ description: 'Флаг готовности сервиса' }),
})
export type Health = Static<typeof Health>

import Fastify, { type FastifyError } from 'fastify'
import helmet from '@fastify/helmet'
import cors from '@fastify/cors'
import rateLimit from '@fastify/rate-limit'
import swagger from '@fastify/swagger'
import { STATUS_CODES } from 'node:http'
import { Type as T } from '@sinclair/typebox'
import type { TypeBoxTypeProvider } from '@fastify/type-provider-typebox'
import { ValidationProblem, ProblemDetails, User, Health } from './types.js'

// Этот модуль собирает все настройки Fastify: плагины инфраструктуры, обработчики ошибок и маршруты API.

/**
 * Временное in-memory хранилище. На следующей лабе оно уедет в Postgres + Prisma,
 * а пока этого достаточно, чтобы научиться писать маршруты и схемы.
 */
const users: User[] = [
  { id: 'u-1', email: 'alice@example.com' },
  { id: 'u-2', email: 'bob@example.com' },
]

export async function buildApp() {
  const app = Fastify({
    logger: true,
    trustProxy: true,
    schemaErrorFormatter(errors, dataVar) {
      const msg = errors.map((e) => e.message).filter(Boolean).join('; ') || 'Validation failed'
      return new ValidationProblem(msg, errors, dataVar)
    },
  }).withTypeProvider<TypeBoxTypeProvider>()

  // === Инфраструктурные плагины ===

  await app.register(helmet)

  // CORS: для dev открываем localhost фронтенда, чтобы запросы из браузера проходили.
  // В лабораторной про CI/CD мы расширим этот список.
  await app.register(cors, {
    origin: [/^http:\/\/localhost:\d+$/],
    credentials: false,
  })

  await app.register(rateLimit, {
    max: 100,
    timeWindow: '1 minute',
    enableDraftSpec: true,
    addHeaders: {
      'x-ratelimit-limit': true,
      'x-ratelimit-remaining': true,
      'x-ratelimit-reset': true,
      'retry-after': true,
    },
    errorResponseBuilder(request, ctx) {
      const seconds = Math.ceil(ctx.ttl / 1000)
      return {
        type: 'about:blank',
        title: 'Too Many Requests',
        status: 429,
        detail: `Rate limit exceeded. Retry in ${seconds} seconds.`,
        instance: request.url,
      } satisfies ProblemDetails
    },
  })

  await app.register(swagger, {
    openapi: {
      openapi: '3.1.0',
      info: {
        title: 'Rooms API',
        version: '1.0.0',
        description: 'HTTP-API, совместимый с RFC 9457 (Problem Details).',
      },
      servers: [{ url: 'http://localhost:3000' }],
      tags: [
        { name: 'Users', description: 'Маршруты для управления пользователями' },
        { name: 'System', description: 'Служебные эндпоинты' },
      ],
    },
  })

  // === Глобальные обработчики ошибок ===

  app.setErrorHandler<FastifyError | ValidationProblem>((err, req, reply) => {
    const status = typeof err.statusCode === 'number' ? err.statusCode : 500
    const isValidation = err instanceof ValidationProblem

    const problem = {
      type: 'about:blank',
      title: STATUS_CODES[status] ?? 'Error',
      status,
      detail: err.message || 'Unexpected error',
      instance: req.url,
      ...(isValidation ? { errorsText: err.message } : {}),
    }

    reply.code(status).type('application/problem+json').send(problem)
  })

  app.setNotFoundHandler((request, reply) => {
    reply.code(404).type('application/problem+json').send({
      type: 'about:blank',
      title: 'Not Found',
      status: 404,
      detail: `Route ${request.method} ${request.url} not found`,
      instance: request.url,
    } satisfies ProblemDetails)
  })

  // === Маршруты API ===

  app.get(
    '/api/users',
    {
      schema: {
        operationId: 'listUsers',
        tags: ['Users'],
        summary: 'Возвращает список пользователей',
        response: {
          200: {
            description: 'Список пользователей',
            content: { 'application/json': { schema: T.Array(User) } },
          },
          429: {
            description: 'Too Many Requests',
            content: { 'application/problem+json': { schema: ProblemDetails } },
          },
          500: {
            description: 'Internal Server Error',
            content: { 'application/problem+json': { schema: ProblemDetails } },
          },
        },
      },
    },
    async () => users
  )

  app.get(
    '/api/health',
    {
      schema: {
        operationId: 'health',
        tags: ['System'],
        summary: 'Проверка работоспособности процесса',
        response: {
          200: { description: 'Ready', content: { 'application/json': { schema: Health } } },
          500: { description: 'Internal Server Error', content: { 'application/problem+json': { schema: ProblemDetails } } },
        },
      },
    },
    async () => ({ ok: true } as Health)
  )

  // Служебный маршрут: возвращает OpenAPI-спецификацию.
  app.get(
    '/openapi.json',
    { schema: { hide: true, tags: ['Internal'] } },
    async (_req, reply) => {
      reply.type('application/json').send(app.swagger())
    }
  )

  return app
}

import { inspect } from 'node:util'

type BuildApp = typeof import('./app.js').buildApp
type AppInstance = Awaited<ReturnType<BuildApp>>

function describeError(err: unknown) {
  if (err instanceof Error) {
    const meta: Record<string, unknown> = {}
    const nodeErr = err as NodeJS.ErrnoException & { cause?: unknown }

    if (nodeErr.code !== undefined) meta.code = nodeErr.code
    if (nodeErr.errno !== undefined) meta.errno = nodeErr.errno
    if (nodeErr.syscall !== undefined) meta.syscall = nodeErr.syscall
    if (nodeErr.cause !== undefined) meta.cause = nodeErr.cause

    return { error: err, meta: Object.keys(meta).length ? meta : undefined }
  }

  const preview = inspect(err, { depth: 6 })
  return {
    error: new Error(`Non-Error thrown: ${preview}`),
    meta: { thrownType: typeof err, thrownPreview: preview },
  }
}

async function main() {
  let app: AppInstance | undefined

  try {
    const { buildApp } = await import('./app.js')
    app = await buildApp()

    const port = Number(process.env.PORT ?? 3000)
    const host = process.env.HOST ?? '0.0.0.0'

    let closing = false
    const shutdown = async (reason: string, err?: unknown) => {
      if (closing) return
      closing = true

      if (app) {
        if (err) {
          const { error, meta } = describeError(err)
          app.log.fatal({ err: error, meta }, `fatal: ${reason}`)
        } else app.log.info({ reason }, 'Shutting down...')

        try {
          // Fastify аккуратно завершает все активные запросы и вызывает onClose-хуки.
          await app.close()
        } finally {
          process.exit(err ? 1 : 0)
        }
      } else {
        process.exit(1)
      }
    }
    process.once('SIGINT',  () => void shutdown('SIGINT'))
    process.once('SIGTERM', () => void shutdown('SIGTERM'))
    process.once('unhandledRejection', (reason) => void shutdown('unhandledRejection', reason))
    process.once('uncaughtException',  (error)  => void shutdown('uncaughtException', error))

    await app.listen({ port, host })
  } catch (err) {
    const { error, meta } = describeError(err)
    console.error('Failed to start application:', error)
    if (meta) console.error('Error details:', meta)
    process.exit(1)
  }
}

void main()