@ackee/create-node-app 1.0.0

package/starter/cloudrun/src/view/rest/util/openapi.util.ts

@@ -0,0 +1,310 @@
+import express from 'express'
+import bodyParser from 'body-parser'
+import { operations, paths, operationPaths } from '../spec/openapi.js'
+import { RequestContext } from '../../../context.js'
+
+export type OpenApiRouteResponseBodyMethod<
+  T,
+  TMethod extends string = 'get',
+  TDefault = unknown
+> = T extends {
+  [key in TMethod]: {
+    responses: { 200: { content: { 'application/json': infer U } } }
+  }
+}
+  ? U
+  : TDefault
+
+export type OpenApiRouteResponseBody<
+  T,
+  TMethod extends string = 'get'
+> = OpenApiRouteResponseBodyMethod<
+  T,
+  TMethod,
+  OpenApiRouteResponseBodyMethod<
+    T,
+    'post',
+    OpenApiRouteResponseBodyMethod<
+      T,
+      'put',
+      OpenApiRouteResponseBodyMethod<T, 'delete'>
+    >
+  >
+>
+
+type LowercaseKeys<T extends Record<keyof any, any>> = {
+  [key in keyof T as key extends string ? Lowercase<key> : key]: T[key]
+}
+
+export type OpenApiRoutePathParam<T> = T extends {
+  get: { parameters: { path: infer U } }
+}
+  ? U
+  : T extends { post: { parameters: { path: infer U } } }
+  ? U
+  : T extends { put: { parameters: { path: infer U } } }
+  ? U
+  : unknown
+
+export type OpenApiRouteQueryParam<T> = T extends {
+  get: { parameters: { query: infer U } }
+}
+  ? U
+  : T extends { post: { parameters: { query: infer U } } }
+  ? U
+  : unknown
+
+export type OpenApiRouteHeaderParam<T> = T extends {
+  get: {
+    parameters: {
+      header: infer U extends Record<string | number | symbol, any>
+    }
+  }
+}
+  ? LowercaseKeys<U>
+  : T extends {
+      post: {
+        parameters: {
+          header: infer U extends Record<string | number | symbol, any>
+        }
+      }
+    }
+  ? LowercaseKeys<U>
+  : unknown
+
+export type OpenApiRouteParam<T> = OpenApiRoutePathParam<T> &
+  OpenApiRouteQueryParam<T> &
+  OpenApiRouteHeaderParam<T>
+
+export type OpenApiRouteRequestBodyMethod<
+  T,
+  TMethod extends string = 'post',
+  TDefault = unknown
+> = T extends {
+  [key in TMethod]: {
+    requestBody: {
+      content:
+        | { 'application/json': infer U }
+        | { 'multipart/form-data': infer U }
+    }
+  }
+}
+  ? U
+  : TDefault
+
+export type OpenApiRouteRequestBody<
+  T,
+  TMethod extends string = 'post'
+> = OpenApiRouteRequestBodyMethod<
+  T,
+  TMethod,
+  OpenApiRouteRequestBodyMethod<
+    T,
+    'put',
+    OpenApiRouteRequestBodyMethod<
+      T,
+      'delete',
+      OpenApiRouteRequestBodyMethod<T, 'patch'>
+    >
+  >
+>
+
+/**
+ * pipeMiddleware takes multiple middlewares and creates and merges them into
+ * one using express Router.
+ */
+export const pipeMiddleware = (...middlewares: express.RequestHandler[]) => {
+  const router = express.Router({ mergeParams: true })
+  middlewares.forEach(m => router.use(m))
+  return router
+}
+
+export type ApiHandler<TRes> = (
+  ctx: Readonly<RequestContext>,
+  req: express.Request,
+  res: express.Response
+) => TRes | Promise<TRes>
+
+const asyncHandler =
+  <TRes>(fn: ApiHandler<TRes>): express.Handler =>
+  async (req, res, next) => {
+    try {
+      const result = await fn(req.context, req, res)
+      res.json(result)
+    } catch (error: unknown) {
+      next(error)
+    }
+  }
+
+export type OperationIds = keyof operations
+
+type ApiMimeTypes = string
+
+type Content = {
+  content: any
+}
+
+type MimeContent<MimeType extends string> = {
+  content: { [key in MimeType]?: any }
+}
+
+type MimeContentValue<
+  MimeType extends ApiMimeTypes,
+  T extends MimeContent<MimeType>
+> = {
+  [K in keyof T['content']]: T['content'][K]
+}[keyof T['content']]
+
+type OpenApiContentTypes<OpenApiContent extends Record<number, any>> = {
+  [K in keyof OpenApiContent]: OpenApiContent[K] extends Content
+    ? MimeContentValue<ApiMimeTypes, OpenApiContent[K]>
+    : never
+}[keyof OpenApiContent]
+
+export type OperationParams<OperationId extends OperationIds> =
+  operations[OperationId]['parameters']['path']
+
+export type OperationQuery<OperationId extends OperationIds> =
+  operations[OperationId]['parameters']['query']
+
+export type OperationResponse<OperationId extends OperationIds> =
+  OpenApiContentTypes<operations[OperationId]['responses']>
+
+export type OperationBody<OperationId extends OperationIds> =
+  operations[OperationId] extends never
+    ? never
+    : MimeContentValue<ApiMimeTypes, operations[OperationId]['requestBody']>
+
+export type OpenApiHandler<OperationId extends OperationIds> =
+  express.RequestHandler<
+    OperationParams<OperationId>,
+    OperationResponse<OperationId>,
+    OperationBody<OperationId>,
+    OperationQuery<OperationId>
+  >
+
+export type OperationHandler<OperationId extends keyof operations> = (
+  ctx: RequestContext,
+  req: Parameters<OpenApiHandler<OperationId>>[0],
+  res: Parameters<OpenApiHandler<OperationId>>[1]
+) => Promise<OperationResponse<OperationId>>
+
+type RouteHandlers<SubsetOperationIds extends OperationIds> = {
+  [Key in SubsetOperationIds]: OperationHandler<Key>
+}
+
+export type RestApiController<
+  SubsetOperationIds extends OperationIds = OperationIds
+> = {
+  [Key in SubsetOperationIds]: OpenApiHandler<Key>
+}
+
+const handleOperationAsync = <OperationId extends OperationIds>(
+  fn: OperationHandler<OperationId>
+): OpenApiHandler<OperationId> => asyncHandler(fn as any) as any
+
+const createRestController = <SubsetOperationIds extends OperationIds>(
+  def: RouteHandlers<SubsetOperationIds>
+): RestApiController<SubsetOperationIds> => {
+  return Object.entries(def).reduce((ctrl, [operationId, handler]) => {
+    if (!handler) {
+      return ctrl
+    }
+    ctrl[operationId as SubsetOperationIds] = handleOperationAsync(
+      handler as any
+    ) as any
+    return ctrl
+  }, {} as RestApiController<SubsetOperationIds>)
+}
+
+export const openApiRouter = (
+  router: express.Router,
+  { removePrefix }: { removePrefix: string } = { removePrefix: '' }
+) => ({
+  express: router,
+  route: <
+    Method extends keyof paths[Path],
+    Path extends keyof paths,
+    OperationId extends OperationIds
+  >(
+    method: Method,
+    path: Path,
+    handler: OpenApiHandler<OperationId>
+  ) => {
+    const route = path
+      .toString()
+      .replaceAll('}', '')
+      .replaceAll('{', ':')
+      // eslint-disable-next-line security/detect-non-literal-regexp
+      .replace(new RegExp(`^${removePrefix}`), '')
+
+    switch (method) {
+      case 'get':
+        router.get(route, handler)
+        break
+      case 'post':
+        router.post(route, handler)
+        break
+      case 'patch':
+        router.patch(route, handler)
+        break
+      case 'delete':
+        router.delete(route, handler)
+        break
+      case 'head':
+        router.head(route, handler)
+        break
+      case 'trace':
+        router.trace(route, handler)
+        break
+      case 'options':
+        router.options(route, handler)
+        break
+      default:
+        throw new Error(
+          `The OpenApi router received invalid HTTP method to be registered: ${method.toString()}`
+        )
+    }
+  },
+})
+
+export const registerOpenApiRoutes = <SomeOperationIds extends OperationIds>(
+  router: ReturnType<typeof openApiRouter>,
+  controller: Partial<RestApiController<SomeOperationIds>>
+) => {
+  const operations = Object.keys(controller) as SomeOperationIds[]
+  operations.forEach(operation => {
+    if (!controller[operation]) {
+      return
+    }
+
+    router.route(
+      operationPaths[operation].method,
+      operationPaths[operation].path,
+      controller[operation]
+    )
+  })
+}
+
+/**
+ * ctrl is a scoped object for controller functions
+ */
+export const ctrl = {
+  json: pipeMiddleware(
+    bodyParser.json(),
+    // Monkeypatch res.json to assign the body to res.out first in order
+    // to log it by pino
+    (_req, res: any, next) => {
+      const resJson = res.json.bind(res)
+      res.json = (body?: any) => {
+        res.out = body
+        return resJson(body)
+      }
+      next()
+    }
+  ),
+  asyncHandler,
+  createRestController,
+  openApiRouter,
+  registerOpenApiRoutes,
+}

package/starter/cloudrun/src/view/server.ts

@@ -0,0 +1,25 @@
+import express from 'express'
+import { createRequestLogger } from './rest/middleware/request-logger.js'
+import { Container } from '../container.js'
+import { config } from '../config.js'
+import { createErrorHandler } from './rest/middleware/error-handler.js'
+import { routes } from './rest/routes.js'
+import { createContextMiddleware } from './rest/middleware/context-middleware.js'
+
+export const createServer = (appContainer: Container) => {
+  const { logger } = appContainer
+
+  const server = express()
+  const errorHandler = createErrorHandler(config.server)
+  const requestLogger = createRequestLogger(logger)
+  const contextMiddleware = createContextMiddleware(appContainer)
+
+  server.disable('x-powered-by')
+
+  server.use(requestLogger)
+  server.use(contextMiddleware)
+  server.use('/api/v1/', routes.api)
+  server.use(errorHandler)
+
+  return server
+}

package/starter/cloudrun-graphql/.env.jsonc

@@ -0,0 +1,12 @@
+{
+    // Server will run on this port
+    "SERVER_PORT": 3000,
+    // Logging level, see https://github.com/pinojs/pino/blob/master/docs/api.md#logger-level
+    "LOGGER_DEFAULT_LEVEL": "debug",
+    // Enable/disable logging object multiline formatted logging https://github.com/pinojs/pino/blob/master/docs/api.md#prettyprint-boolean--object
+    "LOGGER_PRETTY": false,
+    // Response development errors for debugging
+    "SERVER_ALLOW_RESPONSE_ERRORS": false,
+    // Enable GraphQL introspection
+    "SERVER_ENABLE_INTROSPECTION": true
+}

package/starter/cloudrun-graphql/.eslint.tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "./tsconfig.json",
+  "exclude": ["src/generated/**/*"]
+}

package/starter/cloudrun-graphql/.eslintrc.cjs

@@ -0,0 +1,43 @@
+const { omit } = require('lodash')
+const defaultConfig = {
+  ...require('@ackee/styleguide-backend-config/eslint'),
+}
+
+module.exports = {
+  root: true,
+  ignorePatterns: ['dist', 'docs', 'src/generated'],
+  overrides: [
+    {
+      ...omit(defaultConfig, ['ignorePatterns']),
+      files: ['*.ts', '*.js'],
+      parserOptions: {
+        project: '.eslint.tsconfig.json',
+      },
+      rules: {
+        ...defaultConfig['rules'],
+        '@typescript-eslint/strict-boolean-expressions': 0,
+        '@typescript-eslint/no-misused-promises': 'warn',
+      },
+    },
+    {
+      files: ['**/*.graphql'],
+      extends: 'plugin:@graphql-eslint/schema-recommended',
+      parserOptions: {
+        graphQLConfig: {
+          schema: './src/view/graphql/schema/*.graphql',
+        },
+      },
+      rules: {
+        '@graphql-eslint/strict-id-in-types': 0,
+        '@graphql-eslint/require-description': [
+          'warn',
+          {
+            types: true,
+            DirectiveDefinition: true,
+          },
+        ],
+        '@graphql-eslint/no-unreachable-types': 'warn',
+      },
+    },
+  ],
+}

package/starter/cloudrun-graphql/README.md

@@ -0,0 +1,53 @@
+# GraphQL Cloudrun Starter
+
+Node.js project scaffolded with Cloudrun and GraphQL
+
+## 🎉 Initialize project
+
+Run `create-node-app cloudrun-graphql` to init your project. By default project is created in `../node-app` folder.
+
+You can pass `destination` argument into the command as well.
+Example:
+
+- `create-node-app cloudrun-graphql /Users/foo/Documents/bar `
+
+## 👷 Continuous Integration
+
+### Environment variables
+
+Make sure you replace all the variable values containing `REPLACEME` in `ci-branch-config` files.
+
+The following variables must be set for each branch in `ci-branch-config` directory.
+
+- `GCP_PROJECT_ID` - GCP project identifier
+- `ENVIRONMENT` - e.g. `development`
+
+Optional variables:
+
+- `ALLOCATED_MEMORY` - Memory allocated at Cloudrun, default is 384Mi
+- `CLOUD_RUN_SERVICE_ACCOUNT` - CloudRun service account
+- `ENV_SECRETS` - Secret variables of the deployment, format is: `KEY=[NAME OF SECRET IN SECRET MANAGER:VERSION],...`
+- `ENV_VARS` - Environment variables of the deployment, format is: `KEY=VALUE,...`
+- `GCP_SA_KEY` - We use different service accounts for different environments. So we have to overwrite `GCP_SA_KEY` variable e.g.`GCP_SA_KEY=$SECRET_GCP_SA_KEY_DEVELOPMENT` Variable `SECRET_GCP_SA_KEY_<environment>` should be set in `GitLab CI secret variables`
+- `GCP_SECRET_NAME` - Name of secret in Google Secret Manager
+- `MAX_INSTANCES` - Maximum instance count in Cloudrun, default is 8
+- `MIN_INSTANCES` - Minimum instance count in Cloudrun, default is 0
+- `SECRET_PATH` - CloudRun volume where secrets will be injected e.g. `/config/secrets.json` can't be the same path ass app work dir e.g. `/usr/src/app` deploy will fail cause secret protection. But have to be identical with ENV `CFG_JSON_PATH` in Dockerfile
+- `SKIP_AUDIT` - Skip NPM Audit, defaults to `false`
+- `SKIP_LINT` - Skip lint, defaults to `false`
+- `SKIP_TESTS` - Skip tests, defaults to `false`
+- `SQL_INSTANCE_NAME` - SQL instance name
+- `VPC_CONNECTOR_NAME` - serverless connector name, has to be in the same region
+- `DOCKER_REGISTRY_TYPE` - whenever to push Docker image into Container Registry or Artifacts Registry, default is
+  `container`
+- `DOCKER_REGISTRY_URL` - hostname of Docker Registry, defaults to `eu.gcr.io`
+- `ANY_ADDITIONAL_CLOUDRUN_ARGS` - any argument required by Cloud Run, eg `--concurrency=1000 --clear-labels ...`
+
+Common variables:
+
+- `GCP_TEST_SECRET_PROJECT_ID` - GCP project identifier for test secrets
+- `GCP_SECRET_TEST_NAME` - Name of test secret in Google Secret Manager
+
+## 📄 Additional Resources
+
+- [Google Cloudrun docs](https://cloud.google.com/run/docs)

package/starter/cloudrun-graphql/codegen.yml

@@ -0,0 +1,11 @@
+schema: './src/view/graphql/schema/schema.graphql'
+overwrite: true
+generates:
+  src/generated/graphql.ts:
+    config:
+      useIndexSignature: true
+      scalars:
+      mappers:
+    plugins:
+      - 'typescript'
+      - 'typescript-resolvers'

package/starter/cloudrun-graphql/src/adapters/pino.logger.ts

@@ -0,0 +1,44 @@
+import { pino as pinoLogger } from 'pino'
+import { LoggerFactoryPort } from '../domain/ports/logger.d.js'
+
+// https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity
+const PinoLevelToSeverityLookup: Record<string, string> = {
+  trace: 'DEBUG',
+  debug: 'DEBUG',
+  info: 'INFO',
+  warn: 'WARNING',
+  error: 'ERROR',
+  fatal: 'CRITICAL',
+} as const
+
+const defaultPinoConf = (defaultLevel: string) => ({
+  messageKey: 'message',
+  formatters: {
+    messageKey: 'message',
+    level: (label: string, num: number) => {
+      return {
+        severity:
+          PinoLevelToSeverityLookup[label] ??
+          PinoLevelToSeverityLookup[defaultLevel],
+        level: num,
+      }
+    },
+  },
+})
+
+export const pinoLoggerFactory: LoggerFactoryPort = {
+  create: config => {
+    return pinoLogger({
+      ...defaultPinoConf(config.defaultLevel),
+      transport: config.enablePrettyPrint
+        ? {
+            target: 'pino-pretty',
+            options: {
+              colorize: true,
+            },
+          }
+        : undefined,
+      level: config.defaultLevel,
+    })
+  },
+}

package/starter/cloudrun-graphql/src/config.ts

@@ -0,0 +1,21 @@
+import { createLoader, maskedValues, values } from 'configuru'
+import { Level } from 'pino'
+
+const loader = createLoader({
+  defaultConfigPath: '.env.jsonc',
+})
+
+const configSchema = {
+  server: {
+    port: loader.number('SERVER_PORT'),
+    allowResponseErrors: loader.bool('SERVER_ALLOW_RESPONSE_ERRORS'),
+    enableIntrospection: loader.bool('SERVER_ENABLE_INTROSPECTION'),
+  },
+  logger: {
+    defaultLevel: loader.custom(x => x as any as Level)('LOGGER_DEFAULT_LEVEL'),
+    pretty: loader.bool('LOGGER_PRETTY'),
+  },
+}
+
+export const config = values(configSchema)
+export const safeConfig = maskedValues(configSchema)

package/starter/cloudrun-graphql/src/container.ts

@@ -0,0 +1,15 @@
+import { config } from './config.js'
+import { pinoLoggerFactory } from './adapters/pino.logger.js'
+import { LoggerPort } from './domain/ports/logger.d.js'
+
+export interface Container {
+  logger: LoggerPort
+}
+
+export const createContainer = (): Container => {
+  const logger = pinoLoggerFactory.create(config.logger)
+
+  return {
+    logger,
+  }
+}

package/starter/cloudrun-graphql/src/context.ts

@@ -0,0 +1,39 @@
+import { Container } from './container.js'
+
+interface BaseContext {
+  container: Container
+  note?: string
+}
+
+export interface ApiUserRequestContext extends BaseContext {
+  type: 'api-user'
+  user: null // Add UserContext if Auth is implemented
+}
+
+export interface ServerRequestContext extends BaseContext {
+  type: 'server'
+}
+
+/**
+ * Defines context in which current application runs.
+ * Context should be created with every external call (user request, cli input, ...)
+ */
+export type RequestContext = ApiUserRequestContext | ServerRequestContext
+
+/**
+ * Creator of the context for the App. Every API layer is responsible for
+ * creating the context based on the Api parameters (http headers, protocol settings etc...)
+ */
+export type RequestContextFactory<Params extends any[]> = (
+  container: Readonly<Container>,
+  ...params: Params
+) => Promise<RequestContext>
+
+/**
+ * Creator of the server context that should be used only in executions that are invoked
+ * on server, f.e. CLI, server start up etc.
+ */
+export type ServerRequestContextFactory<Params extends any[]> = (
+  container: Readonly<Container>,
+  ...params: Params
+) => Promise<ServerRequestContext>

package/starter/cloudrun-graphql/src/domain/errors/codes.ts

@@ -0,0 +1,9 @@
+export enum ErrorCode {
+  UNKNOWN = 0,
+  VALIDATION = 1000,
+}
+
+export const errorMessages = {
+  [ErrorCode.UNKNOWN]: 'Unknown error',
+  [ErrorCode.VALIDATION]: 'Validation error',
+}

package/starter/cloudrun-graphql/src/domain/errors/errors.ts

@@ -0,0 +1,25 @@
+import { ErrorCode, errorMessages } from './codes.js'
+
+export class DomainError<AdditionalData = any> extends Error {
+  constructor(
+    public readonly code: ErrorCode,
+    public readonly message: string = errorMessages[code],
+    public readonly data?: AdditionalData
+  ) {
+    super(message)
+  }
+}
+
+export type ValidationErrorData =
+  | Array<{ field: string; message: string }>
+  | { field: string; message: string }
+
+export class ValidationError extends DomainError<ValidationErrorData> {
+  constructor(errors: ValidationErrorData) {
+    super(
+      ErrorCode.VALIDATION,
+      errorMessages[ErrorCode.VALIDATION],
+      Array.isArray(errors) ? errors : [errors]
+    )
+  }
+}

package/starter/cloudrun-graphql/src/domain/ports/logger.d.ts

@@ -0,0 +1,21 @@
+export interface LoggerConfig {
+  defaultLevel: string
+  enablePrettyPrint?: boolean
+}
+
+type BaseLoggerFn = (object: any, message?: string) => void
+
+export interface LoggerPort {
+  level: string
+  debug: BaseLoggerFn
+  info: BaseLoggerFn
+  warn: BaseLoggerFn
+  error: BaseLoggerFn
+  fatal: BaseLoggerFn
+  trace: BaseLoggerFn
+  silent: BaseLoggerFn
+}
+
+export interface LoggerFactoryPort {
+  create: (config: LoggerConfig) => LoggerPort
+}

package/starter/cloudrun-graphql/src/index.ts

@@ -0,0 +1,11 @@
+import { safeConfig } from './config.js'
+import { createAppServer, startServer } from './view/server.js'
+import { createContainer } from './container.js'
+
+const appContainer = createContainer()
+const { logger } = appContainer
+
+logger.info({ config: safeConfig }, 'Loaded config')
+
+const appServer = createAppServer()
+void startServer({ ...appServer, container: appContainer })

package/starter/cloudrun-graphql/src/test/helloWorld.test.ts

@@ -0,0 +1,23 @@
+import assert from 'node:assert'
+import { describe, it } from 'mocha'
+import { createAppServer } from '../view/server.js'
+import { gql } from 'graphql-tag'
+
+describe('Hello world', () => {
+  it('should return greeting', async () => {
+    const query = gql`
+      query Hello {
+        greeting
+      }
+    `
+    const { server } = createAppServer()
+    const res = await server.executeOperation({ query })
+
+    assert(res.body.kind === 'single')
+    assert.deepStrictEqual(res.body.singleResult.errors, undefined)
+    assert.deepStrictEqual(
+      res.body.singleResult.data?.greeting,
+      'Hello, world! 🎉'
+    )
+  })
+})