@openapi-typescript-infra/service 1.0.0

package/.eslintignore

@@ -0,0 +1,7 @@
+build/
+coverage
+jest.config.js
+.eslintrc.js
+coconfig.?s
+src/generated
+node_modules

package/.eslintrc.js

@@ -0,0 +1,14 @@
+/**
+ * This file is generated by coconfig. Do not edit it directly.
+ * Instead, edit the coconfig.js or coconfig.ts file in your project root.
+ *
+ * See https://github.com/gas-buddy/coconfig for more information.
+ * @version coconfig@0.10.1
+ */
+const configModule = require('@openapi-typescript-infra/coconfig');
+
+const configItem = configModule.default || configModule.config || configModule;
+const { configuration } = configItem && configItem['.eslintrc.js'];
+const resolved = typeof configuration === 'function' ? configuration() : configuration;
+
+module.exports = resolved;

package/.github/workflows/codeql-analysis.yml

@@ -0,0 +1,74 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+#
+# ******** NOTE ********
+# We have attempted to detect the languages in your repository. Please check
+# the `language` matrix defined below to confirm you have the correct set of
+# supported CodeQL languages.
+#
+name: "CodeQL"
+
+on:
+  push:
+    branches: [ "main" ]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [ "main" ]
+  schedule:
+    - cron: '38 16 * * 6'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+    permissions:
+      actions: read
+      contents: read
+      security-events: write
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: [ 'javascript' ]
+        # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby' ]
+        # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v3
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v2
+      with:
+        languages: ${{ matrix.language }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file.
+        # Prefix the list here with "+" to use these queries and those in the config file.
+        
+        # Details on CodeQL's query packs refer to : https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs
+        # queries: security-extended,security-and-quality
+
+        
+    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+    # If this step fails, then you should remove it and run the build manually (see below)
+    - name: Autobuild
+      uses: github/codeql-action/autobuild@v2
+
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun
+
+    #   If the Autobuild fails above, remove it and uncomment the following three lines. 
+    #   modify them (or add more) to build your code if your project, please refer to the EXAMPLE below for guidance.
+
+    # - run: |
+    #   echo "Run, Build Application using script"
+    #   ./location_of_script_within_repo/buildscript.sh
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v2
+      with:
+        category: "/language:${{matrix.language}}"

package/.github/workflows/nodejs.yml

@@ -0,0 +1,23 @@
+name: Node CI
+
+on: [push]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v1
+    - name: Use Node.js 18
+      uses: actions/setup-node@v3
+      with:
+        node-version: 18
+    - name: npm install, lint, build, and test
+      run: |
+        yarn install --immutable
+        yarn lint
+        yarn build
+        yarn test
+      env:
+        CI: true

package/.github/workflows/npmpublish.yml

@@ -0,0 +1,35 @@
+name: Node.js Package
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+      - run: yarn install --immutable
+      - run: yarn lint
+      - run: yarn test
+      - run: yarn build
+
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 18
+          registry-url: https://registry.npmjs.org/
+      - run: yarn install --immutable
+      - run: yarn build
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.npm_token}}
+

package/.husky/pre-commit

@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+. "$(dirname -- "$0")/_/husky.sh"
+
+yarn lint-staged
+yarn build
+yarn test

package/.prettierrc.js

@@ -0,0 +1,14 @@
+/**
+ * This file is generated by coconfig. Do not edit it directly.
+ * Instead, edit the coconfig.js or coconfig.ts file in your project root.
+ *
+ * See https://github.com/gas-buddy/coconfig for more information.
+ * @version coconfig@0.10.1
+ */
+const configModule = require('@openapi-typescript-infra/coconfig');
+
+const configItem = configModule.default || configModule.config || configModule;
+const { configuration } = configItem && configItem['.prettierrc.js'];
+const resolved = typeof configuration === 'function' ? configuration() : configuration;
+
+module.exports = resolved;

package/@types/config.d.ts

@@ -0,0 +1,56 @@
+/* eslint-disable import/no-default-export */
+declare module 'shortstop-handlers' {
+  export function require(module: string): ReturnType<NodeRequire>;
+  export function env(): (envVarName: string) => string | undefined;
+  export function base64(): (blob: string) => Buffer;
+  export function path(baseDir?: string): (relativePath: string) => string;
+  export function file(baseDir?: string): (relativePath: string) => Buffer | string;
+}
+
+declare module 'shortstop-yaml' {
+  export default function yaml<T>(
+    basepath: string,
+  ): (path: string, callback: (error?: Error, result?: T) => void) => void;
+}
+
+declare module 'shortstop-dns' {
+  export default function dns(opts?: {
+    family?: number;
+    all?: boolean;
+  }): (address: string, callback: (error?: Error, result?: string[]) => void) => void;
+}
+
+declare module '@gasbuddy/confit' {
+  type Json = ReturnType<typeof JSON.parse>
+
+  export type ProtocolFn<CallbackType> = (value: Json, callback?: (error?: Error, result?: CallbackType) => void) => void;
+
+  interface ProtocolsSetPrivate<C> {
+    [protocol: string]: ProtocolFn<C> | ProtocolFn<C>[];
+  }
+
+  interface ConfigStore {
+    get<T>(name: string): T | undefined;
+    set<T>(name: string, newValue: T): T;
+    use(newSettings: unknown): void;
+  }
+
+  type Options<C> = {
+    basedir: string;
+    protocols: ProtocolsSetPrivate<C>;
+  };
+
+  interface ConfigFactory {
+    create(callback: (err: Error, config: ConfigStore) => unknown): void;
+    addOverride(filepathOrSettingsObj: string | object): this;
+    addDefault(filepathOrSettingsObj: string | object): this;
+  }
+
+  function confit<C>(optionsOrBaseDir: Options<C> | string): ConfigFactory;
+
+  namespace confit {
+    export type ProtocolsSet<C> = ProtocolsSetPrivate<C>
+  }
+
+  export default confit;
+}

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+1.0.0
+=====
+
+* Migrated from @gas-buddy organization to openapi-typescript-infra
+* Reworked some GB specific wording

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2016 GasBuddy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,28 @@
+@gasbuddy/service
+=================
+
+[![Node CI](https://github.com/openapi-typescript-infra/openapi-typescript-service/actions/workflows/nodejs.yml/badge.svg)](https://github.com/openapi-typescript-infra/openapi-typescript-service/actions/workflows/nodejs.yml)
+
+An opinionated framework for building high scale services - web, api, or job. Uses OpenAPI, pino, express, confit, Typescript and jest.
+
+This module creates an environment that makes it simpler to host a REST service
+(less repetition, more enterprise grade features). Wherever possible, we use off
+the shelf infrastructure (OpenAPI, Express@5, Terminus are examples). The goal is to allow
+you to enjoy a high level of type safety with a low tax in type construction in a
+microservice environment.
+
+The module takes care of configuration-driven:
+
+* body logging
+* json parsing
+* error handling
+* hosted OpenAPI documents/handlers
+* traditional routing
+* graceful shutdown
+* health checks
+* Telemetry and instrumentation
+
+services built with this module use Typescript with Node 18, which involves transpilation.
+This module takes that into account across the development and production experience.
+
+This needs lots more documentation... Just a start.

package/SECURITY.md

@@ -0,0 +1,12 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 11.0.x   | :white_check_mark: |
+| < 11.0   | :x:                |
+
+## Reporting a Vulnerability
+
+File an issue win this repo and you can expect a response within 1 business day. @djMax is the primary contact.

package/__tests__/config.test.ts

@@ -0,0 +1,31 @@
+import path from 'path';
+
+import { insertConfigurationBefore, loadConfiguration } from '../src/config';
+
+describe('configuration loader', () => {
+  test('overrides and shortstops', async () => {
+    const rootDirectory = path.resolve(__dirname, './fake-serv');
+    const config = await loadConfiguration({
+      name: 'fake-serv',
+      rootDirectory,
+      configurationDirectories: [path.resolve(rootDirectory, './config')],
+    });
+    expect(config.get('logging:level')).toEqual('debug');
+    expect(config.get('google')).toBeTruthy();
+    expect(config.get('google')).not.toEqual('google.com');
+
+    expect(config.get('envswitchoff')).toBeFalsy();
+    expect(config.get('envswitchon')).toBeTruthy();
+
+    expect(config.get('servicetype')).toBeTruthy();
+    expect(config.get('notservicetype')).toBeFalsy();
+
+    const orig = ['a', 'b', 'd'];
+    const withC = insertConfigurationBefore(orig, 'c', 'd');
+    expect(withC).toEqual(['a', 'b', 'c', 'd']);
+    const withE = insertConfigurationBefore(orig, 'e', 'q');
+    expect(withE).toEqual(['a', 'b', 'd', 'e', 'q']);
+    expect(insertConfigurationBefore(undefined, 'a', 'b')).toEqual(['a', 'b']);
+    expect(insertConfigurationBefore([], 'a', 'b')).toEqual(['a', 'b']);
+  });
+});

package/__tests__/fake-serv/api/fake-serv.yaml

@@ -0,0 +1,48 @@
+openapi: 3.0.0
+info:
+  title: Fake Service
+  version: 1.0.0
+paths:
+  /hello:
+    get:
+      description: Get a greeting
+      parameters:
+        - name: greeting
+          in: query
+          required: false
+          schema:
+            type: string
+        - name: number
+          in: query
+          required: false
+          schema:
+            type: number
+        - name: break_things
+          in: query
+          required: false
+          schema:
+            type: boolean
+      responses:
+        200:
+          description: We responded
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  greeting:
+                    type: string
+    post:
+      description: Test body conversion
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                number:
+                  type: number
+        required: true
+      responses:
+        204:
+          description: I heard you

package/__tests__/fake-serv/config/config.json

@@ -0,0 +1,15 @@
+{
+  "logging": {
+    "level": "debug"
+  },
+  "google": "dns:google.com",
+  "envswitchoff": "env_switch:ENV_VAR_DOESNT_EXIST",
+  "envswitchon": "env_switch:!ENV_VAR_DOESNT_EXIST",
+  "servicetype": "servicetype:serv",
+  "notservicetype": "servicetype:api",
+  "server": {
+    "metrics": {
+      "enabled": true
+    }
+  }
+}

package/__tests__/fake-serv/src/handlers/hello.ts

@@ -0,0 +1,10 @@
+import { ServiceHandler } from '../../../../src/index';
+import { FakeServLocals } from '../index';
+
+export const get: ServiceHandler<FakeServLocals> = async (req, res) => {
+  res.json({ greeting: req.query.greeting || 'Hello World' });
+};
+
+export const post: ServiceHandler<FakeServLocals> = async (req, res) => {
+  res.sendStatus(204);
+};

package/__tests__/fake-serv/src/index.ts

@@ -0,0 +1,29 @@
+import { RestApiErrorResponse, RestApiSuccessResponse } from 'rest-api-support';
+
+import type { Service, ServiceLocals } from '../../../src/types';
+
+export interface FakeServLocals extends ServiceLocals {
+  services: {
+    fakeServ: {
+      get_something(): RestApiSuccessResponse<{ things: string[] }> | RestApiErrorResponse;
+    }
+  }
+}
+
+export function service(): Service<FakeServLocals> {
+  return {
+    start(app) {
+      app.locals.services.fakeServ = {
+        get_something() { throw new Error('Should not be called.'); },
+      };
+    },
+    onRequest(req, res) {
+      res.locals.rawBody = true;
+    },
+    async healthy() {
+      return new Promise((accept) => {
+        setTimeout(accept, 1000);
+      });
+    },
+  };
+}

package/__tests__/fake-serv/src/routes/error.ts

@@ -0,0 +1,13 @@
+import { ServiceRouter } from '../../../../src/index';
+import { ServiceError } from '../../../../src/error';
+
+export function route(router: ServiceRouter) {
+  router.get('/sync', (req) => {
+    throw new ServiceError(req.app, 'Synchronous error', { code: 'SyncError' });
+  });
+
+  router.get('/async', async (req) => {
+    await new Promise((accept) => { setTimeout(accept, 100); })
+      .then(() => { throw new ServiceError(req.app, 'Async error', { code: 'AsyncError' }); });
+  });
+}

package/__tests__/fake-serv/src/routes/index.ts

@@ -0,0 +1,22 @@
+import type { ServiceExpress, ServiceRouter } from '../../../../src';
+import { FakeServLocals } from '../index';
+
+export function route(
+  router: ServiceRouter<FakeServLocals>,
+  app: ServiceExpress<FakeServLocals>,
+) {
+  const worldRequests = app.locals.meter.createCounter('world_requests', {
+    description: 'Metrics about requests to world',
+  });
+
+  router.get('/world', (req, res) => {
+    worldRequests.add(1, { method: 'get' });
+    res.json({ hello: 'world' });
+  });
+
+  router.post('/world', async (req, res) => {
+    await app.locals.services.fakeServ.get_something();
+    worldRequests.add(1);
+    res.sendStatus(204);
+  });
+}

package/__tests__/fake-serv/src/routes/other/world.ts

@@ -0,0 +1,7 @@
+import type { Router } from 'express';
+
+export function route(router: Router) {
+  router.get('/', (req, res) => {
+    res.json({ hello: 'jupiter' });
+  });
+}

package/__tests__/fake-serv.test.ts

@@ -0,0 +1,74 @@
+import path from 'path';
+
+import request from 'supertest';
+
+import {
+  listen, ServiceStartOptions, shutdownApp, startApp,
+} from '../src/index';
+
+import { FakeServLocals, service } from './fake-serv/src/index';
+
+describe('fake-serv', () => {
+  test('basic service functionality', async () => {
+    const options: ServiceStartOptions<FakeServLocals> = {
+      service,
+      name: 'fake-serv',
+      rootDirectory: path.resolve(__dirname, './fake-serv'),
+      codepath: 'src',
+    };
+    const app = await startApp(options).catch((error) => {
+      console.error(error);
+      throw error;
+    });
+    expect(app).toBeTruthy();
+
+    let { body } = await request(app).get('/world').timeout(500).expect(200);
+    expect(body.hello).toEqual('world');
+
+    ({ body } = await request(app).get('/other/world').timeout(500).expect(200));
+    expect(body.hello).toEqual('jupiter');
+
+    ({ body } = await request(app).get('/hello').query({ greeting: 'Hello Pluto!', number: '6', break_things: true }).expect(200));
+    expect(body.greeting).toEqual('Hello Pluto!');
+
+    // Can't convert green to a number
+    await request(app).get('/hello').query({ greeting: 'Hello Pluto!', number: 'green' }).expect(400);
+
+    // Make sure body paramater conversion works
+    await request(app).post('/hello').send({ number: 'green' }).expect(400);
+    await request(app).post('/hello').send({ number: '6' }).expect(204);
+    await request(app).post('/hello').send({ number: 6 }).expect(204);
+
+    ({ body } = await request(app).get('/error/sync').timeout(1000).expect(500));
+    expect(body.code).toEqual('SyncError');
+
+    ({ body } = await request(app).get('/error/async').timeout(1000).expect(500));
+    expect(body.code).toEqual('AsyncError');
+
+    // Mocking
+    await request(app).post('/world').expect(500);
+
+    // Clean shutdown
+    await expect(shutdownApp(app)).resolves.toBeUndefined();
+    const secondApp = await startApp(options);
+
+    // Make sure we can listen
+    const server = await listen(secondApp);
+
+    // Call metrics
+    await request(secondApp).get('/world').expect(200);
+    await request(secondApp.locals.internalApp).get('/metrics')
+      .expect(200)
+      .expect((res) => expect(res.text).toMatch(/world_requests_total{method="get"} 1/));
+
+    await new Promise<void>((accept, reject) => {
+      server.close((e) => {
+        if (e) {
+          reject(e);
+        } else {
+          accept();
+        }
+      });
+    });
+  });
+});

package/build/bin/start-service.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/bin/start-service.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const minimist_1 = __importDefault(require("minimist"));
+const repl_1 = require("../development/repl");
+const env_1 = require("../env");
+const bootstrap_1 = require("../bootstrap");
+/**
+ * built - forces the use of the build directory. Defaults to true in stage/prod, not in dev
+ * repl - launch the REPL (defaults to disabling telemetry)
+ * telemetry - whether to use OpenTelemetry. Defaults to false in dev or with repl
+ * nobind - do not listen on http port or expose metrics
+ */
+const argv = (0, minimist_1.default)(process.argv.slice(2), {
+    boolean: ['built', 'repl', 'telemetry', 'nobind'],
+});
+const noTelemetry = (argv.repl || (0, env_1.isDev)()) && !argv.telemetry;
+(0, bootstrap_1.bootstrap)({
+    ...argv,
+    telemetry: !noTelemetry,
+}).then(({ app, server }) => {
+    if (argv.repl) {
+        (0, repl_1.serviceRepl)(app, () => {
+            server?.close();
+        });
+    }
+});
+//# sourceMappingURL=start-service.js.map

package/build/bin/start-service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"start-service.js","sourceRoot":"","sources":["../../src/bin/start-service.ts"],"names":[],"mappings":";;;;;;AACA,wDAAgC;AAEhC,8CAAkD;AAClD,gCAA+B;AAC/B,4CAAyC;AAEzC;;;;;GAKG;AACH,MAAM,IAAI,GAAG,IAAA,kBAAQ,EAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE;IAC3C,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,CAAC;CAClD,CAAC,CAAC;AAEH,MAAM,WAAW,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,IAAA,WAAK,GAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC;AAC9D,IAAA,qBAAS,EAAC;IACR,GAAG,IAAI;IACP,SAAS,EAAE,CAAC,WAAW;CACxB,CAAC,CAAC,IAAI,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE;IAC1B,IAAI,IAAI,CAAC,IAAI,EAAE;QACb,IAAA,kBAAW,EAAC,GAAG,EAAE,GAAG,EAAE;YACpB,MAAM,EAAE,KAAK,EAAE,CAAC;QAClB,CAAC,CAAC,CAAC;KACJ;AACH,CAAC,CAAC,CAAC"}

package/build/bootstrap.d.ts

@@ -0,0 +1,16 @@
+/// <reference types="node" />
+import type { RequestLocals, ServiceLocals } from './types';
+interface BootstrapArguments {
+    name?: string;
+    main?: string;
+    root?: string;
+    built?: boolean;
+    packageDir?: string;
+    telemetry?: boolean;
+    nobind?: boolean;
+}
+export declare function bootstrap<SLocals extends ServiceLocals = ServiceLocals, RLocals extends RequestLocals = RequestLocals>(argv?: BootstrapArguments): Promise<{
+    server: import("http").Server<typeof import("http").IncomingMessage, typeof import("http").ServerResponse> | undefined;
+    app: import("./types").ServiceExpress<SLocals>;
+}>;
+export {};