Bidchuck-api NPM

Bidchuck Rest API

Introduction

bidchuck rest api project

Getting Started

Required Minimum Dependencies

Node 16.x (recommended use of nvm or nvm-windows)
Mongo 4.x download
Doppler CLI docs

Local Development

First Run.

Setup doppler

run this so that doppler will pickup the base developer config

# authenticate with doppler.  this can be done anywhere
doppler login

# tell doppler to use the default config in the project for local development
doppler setup

if you need to branch from the base config because you need to change a couple values, you can create a branch in the web ui or use the cli. docs

Node and dependencies

if you have installed nvm you should be able to run the following command to install and use the version preferred for this project.

nvm install && nvm use

after nvm has finished you can install the dependencies

npm ci

if you get an error from husky, run npm install.

Start the application

open a new terminal at the project folder and run

npm run start:containers

open another new terminal at the project folder and run

npm run dev

stopping the application

You can kill terminal process for npm run dev using CTRL + C.

to stop the containers

npm run stop:containers

Project Contribution

Web Framework

This project uses hapi as the web framework. There are a number of tutorials on the documentation site for hapi to bring you up to speed on the basics.

Security

This application uses two authentication strategies. The first is jwt, and the second is hmac. The hmac authentication at this time is limited to third parties used by the application in order for the third party to interact with the bidchuck api. Example. The identity provider used in the application calls the rest api with an hmac key in order to get a user's roles so they can be included in the JWT created during login.

Adding a route

This service uses hapi-auto-route. Routes are read from src/routes folder. To add a new endpoint, create a new typescript file under src/routes that defines a hapi route object and exports it.

Best Practices

Add the 'api' tag to each route so that it will receive swagger documents. There is a plugin that looks for this tag
Keep route files atomic. File should handle one combination of path and http verb only
Routes must have request and response validation in order for swagger to document properly
Request validation should accept unknown parameters. Response validation should not.

ORM

Currently the project is using typegoose for an ORM to connect to mongodb. typegoose models are located in src/models

best practices

set the type of the items in an array type. prop({ type: String }) for an array of strings

repository layer

This project implements the repository pattern to add a layer of abstraction between the controller and ORM. Repositories are grouped by logical entities. Use the respository layer to interact with ORM instead of doing this directly in the controller or other layer.

Testing

This project uses Jest for a unit testing library.

Testing with Docker

npm run test:docker -- --build-arg NPM_TOKEN=<base64 PAT> --build-arg TEST_FILE=<relative path of test file>

best practices

use the injection mechanism when testing route handlers
use jest mongodb when testing repositories
do not mock transformers

use this pattern when mocking dependencies to get types working correctly

jest.mock('../../../../../repositories/api-key-respository');
import * as apiKeyRepo from '../../../../../repositories/api-key-respository';
const apiKeyRepoMock = apiKeyRepo as jest.Mocked<typeof import('../../../../../repositories/api-key-respository')>;

backfill scripts

before running backfill scripts, backup the database.

First, open a terminal and connect to the mongo shell

Second, retrieve the bidCHUCK db connection string from mongo atlas by clicking "connect" and selecting the option to connect via shell. The connection string should begin with mongodb+srv://

Finally, backup the bidChuck database by entering the following command:

mongodump "<db connection string>" --username dbUser -o ./dump -d bidchuck-db

this will dump the database into a dump folder in the current directory

Alternatively, you can export collections using the Mongo Compass GUI.

API Documentation

The service will generate swagger documenation upon successful startup. This can be accessed at http://localhost:5001/documentation

Troubleshooting

`Unable to fetch secrets from the Doppler API`

try logging in to doppler again and running setup

doppler login

doppler setup

Mongo port in use

There is an active mongo daemon running on your machine that is listening on the default mongo port of 27017. on mac and linux, you can use lsof | grep 27017

Mac and Linux

use lsof to find the process id so that you can kill it if you do not know where it is running. The process id is the second column in the results.

$ lsof | grep 27017

mongod    38310 michaels    8u     IPv4 0xda3fe9374673d897         0t0                 TCP localhost:27017 (LISTEN)

# the process id here is 38310

kill 38310

Windows

In powershell you can use Get-Process to find the process id, and then track it down in task manager to kill it. For powershell there should be a clearly marked column with the process id.

Get-Process -Id (Get-NetTCPConnection -LocalPort 27017).OwningProcess