feat: setup fastify boilerplate

.github/workflows/node-ci.yml

@@ -68,6 +68,12 @@ jobs:
         working-directory: "."
         run: npm run test
 
+      - name: Code Coverage Report - Base Fastify Server
+        uses: ./.github/actions/coverage-report
+        with:
+          package_name: "Base Fastify Server"
+          filename: "./libs/base-fastify-server/coverage/cobertura-coverage.xml"
+
       - name: Code Coverage Report - Session Manager
         uses: ./.github/actions/coverage-report
         with:

apps/session-manager/Dockerfile

@@ -13,6 +13,10 @@ COPY package*.json .
 
 ARG SRC="session-manager"
 COPY apps/${SRC}/package*.json apps/${SRC}/
+ARG LIB="base-fastify-server"
+COPY libs/${LIB}/package*.json libs/${LIB}/
+ARG LIB="base-schema"
+COPY libs/${LIB}/package*.json libs/${LIB}/
 ARG LIB="session-manager-schema"
 COPY libs/${LIB}/package*.json libs/${LIB}/
 
@@ -23,6 +27,10 @@ COPY tsconfig.base.json .
 
 ARG SRC="session-manager"
 COPY apps/${SRC} apps/${SRC}
+ARG LIB="base-fastify-server"
+COPY libs/${LIB} libs/${LIB}
+ARG LIB="base-schema"
+COPY libs/${LIB} libs/${LIB}
 ARG LIB="session-manager-schema"
 COPY libs/${LIB} libs/${LIB}
 
@@ -39,6 +47,10 @@ COPY package*.json .
 
 ARG SRC="session-manager"
 COPY apps/${SRC}/package*.json apps/${SRC}/
+ARG LIB="base-fastify-server"
+COPY libs/${LIB}/package*.json libs/${LIB}/
+ARG LIB="base-schema"
+COPY libs/${LIB}/package*.json libs/${LIB}/
 ARG LIB="session-manager-schema"
 COPY libs/${LIB}/package*.json libs/${LIB}/
 
@@ -47,9 +59,20 @@ RUN npm ci --omit=dev
 # Copy the build artifacts from build-env container
 ARG SRC="session-manager"
 COPY --from=build-env /app/apps/${SRC}/dist/src/ /app/apps/${SRC}/dist/src/
+ARG LIB="base-fastify-server"
+COPY --from=build-env /app/libs/${LIB}/dist/src/ /app/libs/${LIB}/dist/src/
+ARG LIB="base-schema"
+COPY --from=build-env /app/libs/${LIB}/dist/src/ /app/libs/${LIB}/dist/src/
 ARG LIB="session-manager-schema"
 COPY --from=build-env /app/libs/${LIB}/dist/src/ /app/libs/${LIB}/dist/src/
 
 WORKDIR /app/apps/session-manager
 
+# Ensure server listens on a defined interface and port inside container
+# This docker can map this to a real port on the host
+ENV HOST=0.0.0.0
+ENV PORT=80
+
+HEALTHCHECK --interval=30s --timeout=30s --start-period=5s --start-interval=1s --retries=3 CMD curl -f http://localhost:80/healthcheck || exit 1
+
 CMD ["npm", "start"]

apps/session-manager/package.json

@@ -8,13 +8,21 @@
   "scripts": {
     "build": "tsc --build",
     "start": "node ./dist/src/index.js",
-    "start:dev": "node ./dist/src/index.js --dev",
-    "dev": "nodemon --exec 'npm run build && npm run start:dev' --watch src --watch ../../libs/session-manager-schema/src src/index.ts",
+    "start:dev": "node ./dist/src/index.js --dev | pino-pretty",
+    "dev": "nodemon --exec 'npm run build && npm run start:dev' --watch src --watch ../../libs/base-fastify-server/src --watch ../../libs/base-schema/src --watch ../../libs/session-manager-schema/src src/index.ts",
     "format": "prettier --check ./src ./tests",
     "format:fix": "prettier --write ./src ./tests",
     "lint": "eslint ./src ./tests",
     "lint:fix": "eslint ./src ./tests --fix",
     "test:dev": "vitest --ui --coverage",
     "test": "vitest run"
+  },
+  "dependencies": {
+    "@fastify/awilix": "8.0.0",
+    "@fastify/swagger": "9.5.2",
+    "@fastify/swagger-ui": "5.2.3",
+    "awilix": "12.0.5",
+    "env-schema": "6.1.0",
+    "typebox": "1.0.41"
   }
 }

apps/session-manager/src/app_config/app_config.ts

@@ -0,0 +1,52 @@
+import envSchema from 'env-schema';
+import { Type } from 'typebox';
+import type { Static } from 'typebox';
+
+import { LogLevel } from '@scribear/base-fastify-server';
+
+const CONFIG_SCHEMA = Type.Object({
+  LOG_LEVEL: Type.Enum(LogLevel),
+  PORT: Type.Integer({ minimum: 0, maximum: 65_535 }),
+  HOST: Type.String(),
+});
+
+/**
+ * Class that loads and provides application configuration
+ */
+class AppConfig {
+  private _isDevelopment: boolean;
+  private _logLevel: LogLevel;
+  private _port: number;
+  private _host: string;
+
+  get isDevelopment() {
+    return this._isDevelopment;
+  }
+
+  get logLevel() {
+    return this._logLevel;
+  }
+
+  get port() {
+    return this._port;
+  }
+
+  get host() {
+    return this._host;
+  }
+
+  constructor(path?: string) {
+    this._isDevelopment = process.argv.includes('--dev');
+
+    const env = envSchema<Static<typeof CONFIG_SCHEMA>>({
+      dotenv: path ? { path, quiet: true } : { quiet: true },
+      schema: CONFIG_SCHEMA,
+    });
+
+    this._logLevel = env.LOG_LEVEL;
+    this._port = env.PORT;
+    this._host = env.HOST;
+  }
+}
+
+export default AppConfig;

apps/session-manager/src/index.ts

@@ -1,3 +1,31 @@
-import '@scribear/session-manager-schema';
+import AppConfig from './app_config/app_config.js';
+import createServer from './server/create_server.js';
 
-console.log('Hello from session-manager!');
+/**
+ * Main entrypoint for session manager server
+ */
+async function main() {
+  const config = new AppConfig();
+  const { logger, fastify } = await createServer(config);
+
+  // Handle uncaught exceptions and rejections
+  process.on('uncaughtException', (err) => {
+    logger.fatal({ msg: 'Uncaught exception', err });
+    throw err; // terminate on uncaught errors
+  });
+
+  process.on('unhandledRejection', (reason) => {
+    const err = Error('Unhandled rejection', { cause: reason });
+    logger.fatal({ msg: 'Unhandled rejection', err });
+    throw err; // terminate on uncaught rejection
+  });
+
+  try {
+    await fastify.listen({ port: config.port, host: config.host });
+  } catch (err) {
+    logger.fatal({ msg: 'Failed to start fastify webserver', err });
+    throw err; // terminate if failed to start
+  }
+}
+
+await main();

apps/session-manager/src/server/create_server.ts

@@ -0,0 +1,33 @@
+import { createBaseServer } from '@scribear/base-fastify-server';
+
+import type AppConfig from '../app_config/app_config.js';
+import registerDependencies from './dependency_injection/register_dependencies.js';
+import calculatorRouter from './features/calculator/calculator.router.js';
+import healthcheckRouter from './features/healthcheck/healthcheck.router.js';
+import swagger from './plugins/swagger.js';
+
+/**
+ * Initializes fastify server and registers dependencies
+ * @param config Application config
+ * @returns Initialized fastify server
+ */
+async function createServer(config: AppConfig) {
+  const { logger, dependencyContainer, fastify } = createBaseServer(
+    config.logLevel,
+  );
+
+  // Only include swagger docs if in development mode
+  if (config.isDevelopment) {
+    await fastify.register(swagger);
+  }
+
+  registerDependencies(dependencyContainer, config);
+
+  // Register routes
+  fastify.register(healthcheckRouter);
+  fastify.register(calculatorRouter);
+
+  return { logger, fastify };
+}
+
+export default createServer;

apps/session-manager/src/server/dependency_injection/register_dependencies.ts

@@ -0,0 +1,67 @@
+// Need to import so that declare module '@fastify/awilix' below works
+import '@fastify/awilix';
+import { type AwilixContainer, Lifetime, asClass, asValue } from 'awilix';
+
+import type { BaseDependencies } from '@scribear/base-fastify-server';
+
+import type AppConfig from '../../app_config/app_config.js';
+import CalculatorController from '../features/calculator/calculator.controller.js';
+import CalculatorService from '../features/calculator/calculator.service.js';
+import HealthcheckController from '../features/healthcheck/healthcheck.controller.js';
+
+/**
+ * Define types for entities in dependency container
+ */
+interface AppDependencies extends BaseDependencies {
+  config: AppConfig;
+
+  // Healthcheck
+  healthcheckController: HealthcheckController;
+
+  // Calculator
+  calculatorController: CalculatorController;
+  calculatorService: CalculatorService;
+}
+
+/**
+ * Ensure fastify awilix container is typed correctly
+ * @see https://github.com/fastify/fastify-awilix?tab=readme-ov-file#typescript-usage
+ */
+declare module '@fastify/awilix' {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface Cradle extends AppDependencies {}
+
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface RequestCradle extends AppDependencies {}
+}
+
+/**
+ * Register all controller, service, and repository classes into dependency container
+ * @param dependencyContainer Container to load dependencies into
+ * @param config AppConfig to be registered into dependency controller
+ */
+function registerDependencies(
+  dependencyContainer: AwilixContainer,
+  config: AppConfig,
+) {
+  dependencyContainer.register({
+    // Config
+    config: asValue(config),
+
+    // Healthcheck
+    healthcheckController: asClass(HealthcheckController, {
+      lifetime: Lifetime.SCOPED,
+    }),
+
+    // Calculator
+    calculatorController: asClass(CalculatorController, {
+      lifetime: Lifetime.SCOPED,
+    }),
+    calculatorService: asClass(CalculatorService, {
+      lifetime: Lifetime.SCOPED,
+    }),
+  });
+}
+
+export default registerDependencies;
+export type { AppDependencies };

apps/session-manager/src/server/dependency_injection/resolve_handler.ts

@@ -0,0 +1,44 @@
+import type { FastifyReply, FastifyRequest } from 'fastify';
+
+import type { AppDependencies } from './register_dependencies.js';
+
+/**
+ * Creates a wrapper function around provided controller route handler
+ *  Wrapper function resolves controller from request dependency container scope
+ *  and passes request/reply to handler
+ * @param controller Name of controller to resolve
+ * @param method Name of method on controller to call
+ * @returns Wrapped controller method
+ */
+function resolveHandler<
+  C extends keyof AppDependencies,
+  M extends keyof AppDependencies[C],
+>(controller: C, method: M): AppDependencies[C][M] {
+  const wrapper = async (req: FastifyRequest, res: FastifyReply) => {
+    const routeController = req.diScope.resolve(
+      controller,
+    ) as AppDependencies[C];
+
+    // Throw exception if method is not a function
+    if (
+      !(method in routeController) ||
+      typeof routeController[method] !== 'function'
+    ) {
+      throw new Error(
+        `Failed to resolve handler: Property '${String(method)}' on controller '${controller}' is not a function.`,
+      );
+    }
+
+    const handler = routeController[method].bind(routeController) as (
+      req: FastifyRequest,
+      res: FastifyReply,
+    ) => unknown;
+
+    return await handler(req, res);
+  };
+
+  // Cast the type of the wrapper to be the same as the wrapped handler
+  return wrapper as AppDependencies[C][M];
+}
+
+export default resolveHandler;

apps/session-manager/src/server/features/calculator/calculator.controller.ts

@@ -0,0 +1,43 @@
+import type {
+  BaseFastifyReply,
+  BaseFastifyRequest,
+} from '@scribear/base-fastify-server';
+import {
+  COMPUTE_BINOMIAL_SCHEMA,
+  type COMPUTE_MONOMIAL_SCHEMA,
+} from '@scribear/session-manager-schema';
+
+import type { AppDependencies } from '../../dependency_injection/register_dependencies.js';
+import type CalculatorService from './calculator.service.js';
+
+class CalculatorController {
+  private _calculatorService: CalculatorService;
+
+  constructor(calculatorService: AppDependencies['calculatorService']) {
+    this._calculatorService = calculatorService;
+  }
+
+  binomial(
+    req: BaseFastifyRequest<typeof COMPUTE_BINOMIAL_SCHEMA>,
+    res: BaseFastifyReply<typeof COMPUTE_BINOMIAL_SCHEMA>,
+  ) {
+    const { a, b, op } = req.body;
+
+    const result = this._calculatorService.binomial(a, b, op);
+
+    res.code(200).send({ result, reqId: req.id });
+  }
+
+  monomial(
+    req: BaseFastifyRequest<typeof COMPUTE_MONOMIAL_SCHEMA>,
+    res: BaseFastifyReply<typeof COMPUTE_MONOMIAL_SCHEMA>,
+  ) {
+    const { a, op } = req.body;
+
+    const result = this._calculatorService.monomial(a, op);
+
+    res.code(200).send({ result, reqId: req.id });
+  }
+}
+
+export default CalculatorController;

apps/session-manager/src/server/features/calculator/calculator.router.ts

@@ -0,0 +1,29 @@
+import type { BaseFastifyInstance } from '@scribear/base-fastify-server';
+import {
+  COMPUTE_BINOMIAL_ROUTE,
+  COMPUTE_BINOMIAL_SCHEMA,
+  COMPUTE_MONOMIAL_ROUTE,
+  COMPUTE_MONOMIAL_SCHEMA,
+} from '@scribear/session-manager-schema';
+
+import resolveHandler from '../../dependency_injection/resolve_handler.js';
+
+/**
+ * Registers calculator demo routes
+ * @param fastify Fastify app instance
+ */
+function calculatorRouter(fastify: BaseFastifyInstance) {
+  fastify.route({
+    ...COMPUTE_BINOMIAL_ROUTE,
+    schema: COMPUTE_BINOMIAL_SCHEMA,
+    handler: resolveHandler('calculatorController', 'binomial'),
+  });
+
+  fastify.route({
+    ...COMPUTE_MONOMIAL_ROUTE,
+    schema: COMPUTE_MONOMIAL_SCHEMA,
+    handler: resolveHandler('calculatorController', 'monomial'),
+  });
+}
+
+export default calculatorRouter;