Developing Node Server

Resources

Core Technologies

• Docker: https://docs.docker.com/
• Fastify: https://fastify.dev/
• NodeJS: https://nodejs.org/docs/latest/api/
• TypeScript: https://www.typescriptlang.org/docs/handbook/intro.html

Tools

• Eslint: https://eslint.org/docs/latest/
• Git: https://git-scm.com/
• Github Actions: https://docs.github.com/en/actions
• NPM: https://docs.npmjs.com
• Prettier: https://prettier.io/docs/
• Vitest: https://vitest.dev/

Other

• Google Typescript Style Guide: https://google.github.io/styleguide/tsguide.html

Setup

1. Ensure Node.js and npm are installed on your computer.
   • Download from: https://nodejs.org/en.
     • Note: Node server was developed with Node version 20 and up in mind.
   • Node comes with npm (Node Package Manager), which we will use for managing our dependencies.
   • The commands node -v and npm -v will return the version numbers of Node and npm respectively.
     • Make sure both commands run successfully. If they don't, make sure node and npm are in your system path configuration.
2. Ensure Git is installed on your computer. See: https://git-scm.com/
3. Clone the repository

   git clone https://github.com/scribear/ScribeAR-NodeServer
   

4. Move into the node-server directory

   cd ./ScribeAR-NodeServer/node-server
   

5. Install dependencies

   npm install
   

6. Make a copy of template.env and name it .env
7. Edit .env to configure node server.
   • The template already contains sensible defaults. A good place to start is to leave every thing except WHISPER_SERVICE_ENDPOINT and SOURCE_TOKEN default.
   • See Configuring Node Server for details about each option.
8. Start up your local instance. This will start the development server and automatically restart the app when you make changes.

   npm run dev
   

Building

• To build the app for production, run

  npm run build
  

• The build will be placed in the build folder.

Unit Testing

Node server is unit tested using Vitest. These are used to check that individual components are working as expected in isolation.

• To run tests

  npm run test:dev
  

• A web UI will be available for browsing test cases. In addition, you can view the test code coverage report generated by istanbul by clicking on the coverage icon in the top right of the sidebar.
• To create new tests, create file ending with .test.ts in the same folder as the function/object you want to test.
  • The names of the test file should correspond to the name of the file containing the thing you are testing.
    • Try to avoid writing tests that involve multiple files. If you find yourself doing so, it might be a sign that the scope of your function is too big.
  • See https://vitest.dev/guide/ to learn how to use Vitest

Code Style

Node server uses eslint and prettier is analyze code to catch potential issues and ensure a consistent code style. eslint is configured to follow Google Typescript Style Guide (https://google.github.io/styleguide/tsguide.html) with some tweaks.

• To run the linter

  npm run lint
  

• To attempt to automatically fix linter issues

  npm run lint:fix
  

Containerization

1. Ensure you have Docker installed. See: https://www.docker.com/
2. Build container

   docker build -t node-server -f ./Dockerfile .
   

3. Make a copy of template.env and name it .env
4. Edit .env to configure container. See Configuring Docker Containers for details.
5. Run container (listens on port 8080)

   docker run --env-file .env -p 8080:80 node-server:latest
   

Dependencies

When modifying dependencies:

• Ensure that the changes are reflected in package.json and package-lock.json (typically done by npm automatically) and ensure they are commited to Git.
• Separate dependencies only needed for developing the app (e.g. eslint, typescript) and dependencies needed to run the app (e.g. fastify).
  • Use npm install --save-dev <dependencies> to save dev dependencies
  • Use npm install --save <dependencies> to save non dev dependencies
  • https://docs.npmjs.com/specifying-dependencies-and-devdependencies-in-a-package-json-file

File Structure

• src/
  • Contains source code, including test definitions.
  • server/
    • Contains code that defines the Fastify web server
    • hooks/
      • Contains Fastify hooks.
      • Used to define functions that run on certain events like when a request is received, before an event it sent, when an error is thrown, etc.
      • https://fastify.dev/docs/latest/Reference/Hooks/
    • routes/
      • Contains Fastify route handlers as plugins.
      • The functions here take in a Fastify instance and register new routes onto it. This is how we define the functions to handle different web requests (e.g. GET /healthcheck)
      • Handlers here should avoid managing business logic and instead call methods on various services. This is to isolate business logic to make testing easier.
      • https://fastify.dev/docs/latest/Reference/Routes/
      • https://fastify.dev/docs/latest/Reference/Plugins/
    • services/
      • Contains services that handle the business logic of the web server.
      • These services are instantiated in create_server.ts and the Fastify instance is decorated with them. This way, routes and hooks can access them. (e.g. fastify.tokenService to access the Token Service)
    • create_server.ts
      • This function takes in the app configuration object and logger and returns a Fastify instance.
      • Services are instantiated and the Fastify instance is decorated here.
      • Plugins and routes are registered as well.
  • shared/
    • config/
      • config_schema.ts
        • This file defines the schema for the configuration file.
        • Typebox is used to generate a JSON Schema definition that is used to enforce the app's .env config.
        • This can be used to require certain fields to be filled, set defaults, require fields to have certain constraints, etc.
        • This file also defines ConfigType which is the Typescript definition for the config object used throughout the app.
        • https://github.com/sinclairzx81/typebox
        • https://json-schema.org/
      • load_config.ts
        • This function loads the .env file and checks that it satisfies the schema defined in config_schema.ts.
        • It then creates the ConfigType object and returns it.
    • logger/
      • logger.ts
        • Creates a logger instance used to log important information about what the app is doing, errors, warnings, and debugging information.
  • index.ts
    • This is the entrypoint into our application, the first thing that is run.
    • It loads the configuration, creates the logger, creates the Fastify server, and starts the server.
• test/
  • Contains helpful mocks and utilities for used in unit tests.
• .dockerignore
  • Defines files to be excluded in Docker image
  • https://docs.docker.com/reference/dockerfile/#dockerignore-file
• .gitignore
  • Defines files to be excluded from Git tracking
  • https://git-scm.com/docs/gitignore
• .npmrc
  • Configures npm
  • https://docs.npmjs.com/cli/v9/configuring-npm/npmrc
  • https://docs.npmjs.com/cli/v9/using-npm/config
• .prettierrc.cjs
  • Configures prettier
  • https://prettier.io/docs/configuration
• Dockerfile
  • Defines the Docker image for node server
  • https://docs.docker.com/reference/dockerfile/
• eslint.config.mjs
  • Configures eslint
  • https://eslint.org/docs/latest/use/configure/configuration-files
• package-lock.json
  • Used by npm to "lock" the dependencies to ensure every install uses the exact same version (even if a newer version matchines package.json)
  • This is automatically managed by npm, so avoid changing it manually.
  • https://docs.npmjs.com/cli/v9/configuring-npm/package-lock-json
• package.json
  • Defines dependencies for npm, aliases for common commands (e.g. dev, lint, test), and describes metadata about the project (e.g. name, author, version)
  • The dependency lists are automatically managed by npm, but can be modified manually (just run npm install after).
  • https://docs.npmjs.com/cli/v11/configuring-npm/package-json
  • https://docs.npmjs.com/specifying-dependencies-and-devdependencies-in-a-package-json-file
• template.env
  • Contains a template version of the .env file used to configure the app
  • See Configuring Node Server for details

Github Actions

The Github Actions definitions for node server can be found in .github/workflows/node-server-ci.yml.

• Triggers:
  • On demand
  • Pull request
  • Push to the main or staging branch containing changes to the node-server folder
• https://docs.github.com/en/actions

The following jobs are defined:

• build-test-lint-node-server

  • Runs npm run build, npm run test:ci, and npm run lint to ensure that code builds, passes unit tests, and has no code style errors.
  • If any of these commands fail, the job is failed.

• build-container-node-server

  • Builds the scribear-node-server Docker container and pushes to Dockerhub
  • Images are tagged with pull request id, branch, and Github tags.
  • Runs after build-test-lint-node-server finishes successfully

Additional Documentation

Additional documentation can be found in Documentation.