@advinans/belt-service

Opinionated GraphQL service running on Koa

This package provides an easy to use koa GraphQL service prepared with access logging, graceful shutdown, error handling and general logging.

Usage

import '@advinans/belt-service/bootstrap';
import { createGraphQLApp } from '@advinans/belt-service';
import JWT from '@advinans/belt-jwt';
import { Logger } from '@advinans/belt-log';
import { executableSchema, createContext } from '../graphql';

const log = new Logger();
const jwt = new JWT();

export const app = createGraphQLApp({
  graphql: {
    schema: executableSchema,
    addToContext: createContext,
  },
  log,
  jwt,
});

const port = process.env.PORT || 8080;

app.listen(port, () => {
  log.notice(`Server is up and running on ${port}`);
});

It is recommended to look over this more detailed example that will help explain more about how a GraphQL service should be structured. It's a simple implementation, but it has both queries and mutations. o

Bootstrap

Included in this package is a 'bootstrap', that will read .env files to load environment variables, start gcloud request tracing, and enable sourcemap support. You can use it by including this, as the FIRST line of your application.

import '@advinans/belt-service/bootstrap';

Logging

The koa instance returned by createApp has an @advinans/belt-log logger attached to it (app.log) that can be used for general non-request logging. The default context is also decorated with a child instance of @advinans/belt-log that will attach a traceId to the output making it ideal to use when logging within resolvers.

Exposing errors to users

Whenever a GraphQL-query throws an error, we will search through the error-stack for an instance of ExposedError as vendored by @advinans/belt-error, to determine what message to return. We do NOT respect the .expose-flag in those instances for reasons outlined here.

For any other endpoint, we will return with a json-object of type

interface ErrorResponse {
  errors: Array<{ message: string, extenstions: { status: number } & { [key: string]: any }}>
}

If the .expose-property on the caught error is truthy, then the message of the response will be set to the message of the caught error. Otherwise it will get the message based on the status code, as vendored by statuses, defaulting to status code 500.

Please note the difference between what the server exposes on a /graphql-endpoint versus any other endpoint.