chore: add server entry and dev docker compose

Made-with: Cursor

.env.example

@@ -0,0 +1,45 @@
+# Server
+PORT=3000
+HOST=0.0.0.0
+NODE_ENV=development
+
+# Database
+DATABASE_URL=postgresql://samreshu:samreshu_dev@localhost:5432/samreshu
+
+# Redis
+REDIS_URL=redis://localhost:6379
+
+# Auth
+JWT_SECRET=dev-secret-change-in-production-min-32-chars
+JWT_ACCESS_TTL=15m
+JWT_REFRESH_TTL=7d
+
+# LLM
+LLM_BASE_URL=http://localhost:11434/v1
+LLM_MODEL=qwen2.5:14b
+LLM_API_KEY=
+LLM_TIMEOUT_MS=15000
+LLM_MAX_RETRIES=1
+LLM_TEMPERATURE=0.7
+LLM_MAX_TOKENS=2048
+
+# Rate limits
+RATE_LIMIT_LOGIN=5
+RATE_LIMIT_REGISTER=3
+RATE_LIMIT_FORGOT_PASSWORD=3
+RATE_LIMIT_VERIFY_EMAIL=5
+RATE_LIMIT_API_AUTHED=100
+RATE_LIMIT_API_GUEST=30
+
+# CORS (comma-separated origins)
+CORS_ORIGINS=http://localhost:5173,http://localhost:3000
+
+# Email (dev — mailpit / mailtrap)
+SMTP_HOST=localhost
+SMTP_PORT=1025
+SMTP_USER=
+SMTP_PASS=
+EMAIL_FROM=noreply@samreshu.dev
+
+# Sentry (optional for dev)
+SENTRY_DSN=

docker-compose.dev.yml

@@ -0,0 +1,29 @@
+services:
+  postgres:
+    image: postgres:16-alpine
+    environment:
+      POSTGRES_USER: samreshu
+      POSTGRES_PASSWORD: samreshu_dev
+      POSTGRES_DB: samreshu
+    ports:
+      - "5432:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U samreshu -d samreshu"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  redis:
+    image: redis:7-alpine
+    ports:
+      - "6379:6379"
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+volumes:
+  pgdata:

src/app.ts

@@ -0,0 +1,76 @@
+import Fastify, { FastifyInstance } from 'fastify';
+import { AppError } from './utils/errors.js';
+import databasePlugin from './plugins/database.js';
+import redisPlugin from './plugins/redis.js';
+import securityPlugin from './plugins/security.js';
+import rateLimitPlugin from './plugins/rateLimit.js';
+import { env } from './config/env.js';
+import { randomUUID } from 'node:crypto';
+
+export async function buildApp(): Promise<FastifyInstance> {
+  const isDev = env.NODE_ENV === 'development';
+
+  const app = Fastify({
+    logger: {
+      level: isDev ? 'debug' : 'info',
+      transport:
+        isDev
+          ? {
+              target: 'pino-pretty',
+              options: {
+                translateTime: 'HH:MM:ss Z',
+                ignore: 'pid,hostname',
+              },
+            }
+          : undefined,
+    },
+    requestIdHeader: 'x-request-id',
+    requestIdLogLabel: 'requestId',
+    genReqId: () => randomUUID(),
+  });
+
+  app.setErrorHandler((err: unknown, request, reply) => {
+    const error = err as Error & { statusCode?: number; validation?: unknown };
+    request.log.error({ err }, error.message);
+
+    if (err instanceof AppError) {
+      const statusCode = err.statusCode;
+      const payload = err.toJSON();
+      if (err.code === 'RATE_LIMIT_EXCEEDED' && 'retryAfter' in err) {
+        reply.header('Retry-After', String((err as AppError & { retryAfter?: number }).retryAfter ?? 60));
+      }
+      return reply.status(statusCode).send(payload);
+    }
+
+    if (error.validation) {
+      return reply.status(422).send({
+        error: {
+          code: 'VALIDATION_ERROR',
+          message: 'Validation failed',
+          details: error.validation,
+        },
+      });
+    }
+
+    const statusCode = error.statusCode ?? 500;
+    return reply.status(statusCode).send({
+      error: {
+        code: 'INTERNAL_ERROR',
+        message: env.NODE_ENV === 'production' ? 'Internal server error' : error.message,
+      },
+    });
+  });
+
+  app.addHook('onRequest', async (request, reply) => {
+    reply.header('x-request-id', request.id);
+  });
+
+  await app.register(redisPlugin);
+  await app.register(databasePlugin);
+  await app.register(securityPlugin);
+  await app.register(rateLimitPlugin);
+
+  app.get('/health', async () => ({ status: 'ok', timestamp: new Date().toISOString() }));
+
+  return app;
+}

src/config/env.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+
+const envSchema = z.object({
+  NODE_ENV: z.enum(['development', 'test', 'production']).default('development'),
+  PORT: z.coerce.number().min(1).max(65535).default(3000),
+  HOST: z.string().default('0.0.0.0'),
+
+  DATABASE_URL: z.string().min(1),
+  REDIS_URL: z.string().min(1).default('redis://localhost:6379'),
+
+  JWT_SECRET: z.string().min(32),
+  JWT_ACCESS_TTL: z.string().default('15m'),
+  JWT_REFRESH_TTL: z.string().default('7d'),
+
+  LLM_BASE_URL: z.string().url().default('http://localhost:11434/v1'),
+  LLM_MODEL: z.string().default('qwen2.5:14b'),
+  LLM_API_KEY: z.string().optional(),
+  LLM_TIMEOUT_MS: z.coerce.number().default(15000),
+  LLM_MAX_RETRIES: z.coerce.number().min(0).default(1),
+  LLM_TEMPERATURE: z.coerce.number().min(0).max(2).default(0.7),
+  LLM_MAX_TOKENS: z.coerce.number().default(2048),
+
+  RATE_LIMIT_LOGIN: z.coerce.number().default(5),
+  RATE_LIMIT_REGISTER: z.coerce.number().default(3),
+  RATE_LIMIT_FORGOT_PASSWORD: z.coerce.number().default(3),
+  RATE_LIMIT_VERIFY_EMAIL: z.coerce.number().default(5),
+  RATE_LIMIT_API_AUTHED: z.coerce.number().default(100),
+  RATE_LIMIT_API_GUEST: z.coerce.number().default(30),
+
+  CORS_ORIGINS: z.string().default('http://localhost:5173'),
+  SENTRY_DSN: z.string().optional(),
+});
+
+export type Env = z.infer<typeof envSchema>;
+
+function parseEnv(): Env {
+  const result = envSchema.safeParse(process.env);
+  if (!result.success) {
+    const msg = result.error.flatten().fieldErrors;
+    throw new Error(`Invalid environment: ${JSON.stringify(msg)}`);
+  }
+  return result.data;
+}
+
+export const env = parseEnv();
+
+export function getCorsOrigins(): string[] {
+  return env.CORS_ORIGINS.split(',').map((s) => s.trim()).filter(Boolean);
+}

src/plugins/database.ts

@@ -0,0 +1,32 @@
+import { FastifyInstance, FastifyPluginAsync } from 'fastify';
+import { drizzle } from 'drizzle-orm/node-postgres';
+import pg from 'pg';
+import fp from 'fastify-plugin';
+import { env } from '../config/env.js';
+
+const { Pool } = pg;
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    db: ReturnType<typeof drizzle>;
+  }
+}
+
+const databasePlugin: FastifyPluginAsync = async (app: FastifyInstance) => {
+  const pool = new Pool({
+    connectionString: env.DATABASE_URL,
+    max: 10,
+    idleTimeoutMillis: 30000,
+    connectionTimeoutMillis: 5000,
+  });
+
+  const db = drizzle(pool);
+
+  app.decorate('db', db);
+
+  app.addHook('onClose', async () => {
+    await pool.end();
+  });
+};
+
+export default fp(databasePlugin, { name: 'database' });

src/plugins/rateLimit.ts

@@ -0,0 +1,59 @@
+import { FastifyInstance, FastifyPluginAsync } from 'fastify';
+import rateLimit from '@fastify/rate-limit';
+import fp from 'fastify-plugin';
+import { env } from '../config/env.js';
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    rateLimitOptions: {
+      login: { max: number; timeWindow: string };
+      register: { max: number; timeWindow: string };
+      forgotPassword: { max: number; timeWindow: string };
+      verifyEmail: { max: number; timeWindow: string };
+      apiAuthed: { max: number; timeWindow: string };
+      apiGuest: { max: number; timeWindow: string };
+    };
+  }
+}
+
+const rateLimitPlugin: FastifyPluginAsync = async (app: FastifyInstance) => {
+  const options = {
+    login: { max: env.RATE_LIMIT_LOGIN, timeWindow: '15 minutes' },
+    register: { max: env.RATE_LIMIT_REGISTER, timeWindow: '1 hour' },
+    forgotPassword: { max: env.RATE_LIMIT_FORGOT_PASSWORD, timeWindow: '1 hour' },
+    verifyEmail: { max: env.RATE_LIMIT_VERIFY_EMAIL, timeWindow: '15 minutes' },
+    apiAuthed: { max: env.RATE_LIMIT_API_AUTHED, timeWindow: '1 minute' },
+    apiGuest: { max: env.RATE_LIMIT_API_GUEST, timeWindow: '1 minute' },
+  };
+
+  app.decorate('rateLimitOptions', options);
+
+  await app.register(rateLimit, {
+    max: options.apiGuest.max,
+    timeWindow: options.apiGuest.timeWindow,
+    keyGenerator: (req) => {
+      return (req.ip ?? 'unknown') as string;
+    },
+    redis: app.redis,
+    addHeadersOnExceeding: {
+      'x-ratelimit-limit': true,
+      'x-ratelimit-remaining': true,
+      'x-ratelimit-reset': true,
+    },
+    addHeaders: {
+      'x-ratelimit-limit': true,
+      'x-ratelimit-remaining': true,
+      'x-ratelimit-reset': true,
+      'retry-after': true,
+    },
+    errorResponseBuilder: (_req, context) => ({
+      error: {
+        code: 'RATE_LIMIT_EXCEEDED',
+        message: 'Too many requests, please try again later',
+        retryAfter: context.ttl,
+      },
+    }),
+  });
+};
+
+export default fp(rateLimitPlugin, { name: 'rateLimit', dependencies: ['redis'] });

src/plugins/redis.ts

@@ -0,0 +1,32 @@
+import { FastifyInstance, FastifyPluginAsync } from 'fastify';
+import { Redis } from 'ioredis';
+import fp from 'fastify-plugin';
+import { env } from '../config/env.js';
+
+declare module 'fastify' {
+  interface FastifyInstance {
+    redis: Redis;
+  }
+}
+
+const redisPlugin: FastifyPluginAsync = async (app: FastifyInstance) => {
+  const redis = new Redis(env.REDIS_URL, {
+    maxRetriesPerRequest: 3,
+    retryStrategy(times: number) {
+      const delay = Math.min(times * 100, 3000);
+      return delay;
+    },
+  });
+
+  redis.on('error', (err: Error) => {
+    app.log.error({ err }, 'Redis connection error');
+  });
+
+  app.decorate('redis', redis);
+
+  app.addHook('onClose', async () => {
+    await redis.quit();
+  });
+};
+
+export default fp(redisPlugin, { name: 'redis' });

src/plugins/security.ts

@@ -0,0 +1,21 @@
+import { FastifyInstance, FastifyPluginAsync } from 'fastify';
+import helmet from '@fastify/helmet';
+import cors from '@fastify/cors';
+import fp from 'fastify-plugin';
+import { getCorsOrigins } from '../config/env.js';
+
+const securityPlugin: FastifyPluginAsync = async (app: FastifyInstance) => {
+  await app.register(helmet, {
+    contentSecurityPolicy: false,
+    crossOriginEmbedderPolicy: false,
+  });
+
+  await app.register(cors, {
+    origin: getCorsOrigins(),
+    credentials: true,
+    methods: ['GET', 'POST', 'PATCH', 'DELETE', 'PUT', 'OPTIONS'],
+    allowedHeaders: ['Content-Type', 'Authorization'],
+  });
+};
+
+export default fp(securityPlugin, { name: 'security' });

src/server.ts

@@ -0,0 +1,26 @@
+import 'dotenv/config';
+import { buildApp } from './app.js';
+import { env } from './config/env.js';
+
+async function main() {
+  const app = await buildApp();
+
+  try {
+    await app.listen({ port: env.PORT, host: env.HOST });
+    app.log.info({ port: env.PORT }, 'Server started');
+  } catch (err) {
+    app.log.error(err);
+    process.exit(1);
+  }
+
+  const shutdown = async () => {
+    app.log.info('Shutting down...');
+    await app.close();
+    process.exit(0);
+  };
+
+  process.on('SIGINT', shutdown);
+  process.on('SIGTERM', shutdown);
+}
+
+main();

src/utils/errors.ts

@@ -0,0 +1,88 @@
+export const ERROR_CODES = {
+  BAD_REQUEST: 'BAD_REQUEST',
+  UNAUTHORIZED: 'UNAUTHORIZED',
+  FORBIDDEN: 'FORBIDDEN',
+  NOT_FOUND: 'NOT_FOUND',
+  CONFLICT: 'CONFLICT',
+  VALIDATION_ERROR: 'VALIDATION_ERROR',
+  RATE_LIMIT_EXCEEDED: 'RATE_LIMIT_EXCEEDED',
+  INTERNAL_ERROR: 'INTERNAL_ERROR',
+  INVALID_CREDENTIALS: 'INVALID_CREDENTIALS',
+  ACCOUNT_LOCKED: 'ACCOUNT_LOCKED',
+  EMAIL_TAKEN: 'EMAIL_TAKEN',
+  INVALID_REFRESH_TOKEN: 'INVALID_REFRESH_TOKEN',
+  TOKEN_REUSE_DETECTED: 'TOKEN_REUSE_DETECTED',
+  INVALID_CODE: 'INVALID_CODE',
+  ALREADY_VERIFIED: 'ALREADY_VERIFIED',
+  INVALID_RESET_TOKEN: 'INVALID_RESET_TOKEN',
+  NICKNAME_TAKEN: 'NICKNAME_TAKEN',
+  DAILY_LIMIT_REACHED: 'DAILY_LIMIT_REACHED',
+  EMAIL_NOT_VERIFIED: 'EMAIL_NOT_VERIFIED',
+  QUESTIONS_UNAVAILABLE: 'QUESTIONS_UNAVAILABLE',
+  QUESTION_ALREADY_ANSWERED: 'QUESTION_ALREADY_ANSWERED',
+  WRONG_QUESTION: 'WRONG_QUESTION',
+  TEST_ALREADY_FINISHED: 'TEST_ALREADY_FINISHED',
+  NO_ANSWERS: 'NO_ANSWERS',
+  TEST_NOT_FINISHED: 'TEST_NOT_FINISHED',
+  USER_NOT_FOUND: 'USER_NOT_FOUND',
+} as const;
+
+export type ErrorCode = (typeof ERROR_CODES)[keyof typeof ERROR_CODES];
+
+export class AppError extends Error {
+  constructor(
+    public readonly code: ErrorCode,
+    public readonly message: string,
+    public readonly statusCode: number = 500,
+    public readonly details?: unknown
+  ) {
+    super(message);
+    this.name = 'AppError';
+    Object.setPrototypeOf(this, AppError.prototype);
+  }
+
+  toJSON() {
+    const err: { code: string; message: string; details?: unknown } = {
+      code: this.code,
+      message: this.message,
+    };
+    if (this.details !== undefined) err.details = this.details;
+    return { error: err };
+  }
+}
+
+export function badRequest(message: string, details?: unknown): AppError {
+  return new AppError(ERROR_CODES.BAD_REQUEST, message, 400, details);
+}
+
+export function unauthorized(message: string): AppError {
+  return new AppError(ERROR_CODES.UNAUTHORIZED, message, 401);
+}
+
+export function forbidden(message: string): AppError {
+  return new AppError(ERROR_CODES.FORBIDDEN, message, 403);
+}
+
+export function notFound(message: string): AppError {
+  return new AppError(ERROR_CODES.NOT_FOUND, message, 404);
+}
+
+export function conflict(code: ErrorCode, message: string): AppError {
+  return new AppError(code, message, 409);
+}
+
+export function validationError(message: string, details?: unknown): AppError {
+  return new AppError(ERROR_CODES.VALIDATION_ERROR, message, 422, details);
+}
+
+export function rateLimitExceeded(message: string, retryAfter?: number): AppError {
+  const err = new AppError(ERROR_CODES.RATE_LIMIT_EXCEEDED, message, 429);
+  if (retryAfter !== undefined) {
+    (err as AppError & { retryAfter: number }).retryAfter = retryAfter;
+  }
+  return err;
+}
+
+export function internalError(message: string, cause?: unknown): AppError {
+  return new AppError(ERROR_CODES.INTERNAL_ERROR, message, 500, cause);
+}

src/utils/uuid.ts

@@ -0,0 +1,37 @@
+import { randomBytes } from 'node:crypto';
+
+/**
+ * Generate UUID v7 (time-ordered, sortable).
+ * Simplified implementation: timestamp (48 bit) + random (74 bit).
+ */
+export function uuid7(): string {
+  const timestamp = Date.now();
+  const random = randomBytes(10);
+
+  const high = (timestamp / 0x100000000) >>> 0;
+  const low = timestamp >>> 0;
+
+  const b = new Uint8Array(16);
+  b[0] = (high >> 24) & 0xff;
+  b[1] = (high >> 16) & 0xff;
+  b[2] = (high >> 8) & 0xff;
+  b[3] = high & 0xff;
+  b[4] = (low >> 24) & 0xff;
+  b[5] = (low >> 16) & 0xff;
+  b[6] = ((low >> 8) & 0x3f) | 0x70;
+  b[7] = low & 0xff;
+  b[8] = 0x80 | (random[0] & 0x3f);
+  b[9] = random[1];
+  b[10] = random[2];
+  b[11] = random[3];
+  b[12] = random[4];
+  b[13] = random[5];
+  b[14] = random[6];
+  b[15] = random[7];
+
+  const hex = Array.from(b)
+    .map((x) => x.toString(16).padStart(2, '0'))
+    .join('');
+
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}