🎾 Koa Core

The core that powers uSwitch Koa services.

Overview | Packages | Library | Example

Overview

Koa Core is a lerna monorepo housing all of uSwitch's koa packages.

This repo acts both as a helper library for wiring together the @uswitch/koa- packages as well as a master list of open sources koa libraries that we depend on.

This means we have a single point of truth for which packages we use and the versions we depend on.

npm install @uswitch/koa-core

Making changes

All of our koa libraries can be found in packages. Any changes should be made to them individually. Commits should ideally be namespaced to the package you're changing.

e.g. [access] Making changes to koa access or [core] Making changes to core.

Or, better yet, with emojis

• 🎾 for core
• 👌 for access
• 🕵️‍♀️ for tracer
• 🚦 for signal
• 🌡️ for prometheus
• ⏰ for timeout
• 🤐 for zipkin

Once changes have been committed, we use lerna to manage the bumping and publishing.

# Make sure you're on a branch because of tag push permissions!!

npm run publish:packages

This will publish the individual libraries followed by performing updating dependencies and generating the documentation for core .

This publishes to both the NPM and Github Packages Registries

Node Version

You can see which version of node koa-core supports by looking in .nvmrc.

Packages

@uswitch packages

Package	Version	Dependencies	Description
@uswitch/koa-access			👌 A Koa middleware for logging JSON access logs consistently, similar to morgan
@uswitch/koa-cookie			🍪 Koa cookie parser middleware
@uswitch/koa-prometheus			🌡️ A configurable Prometheus data collector with Koa middleware
@uswitch/koa-signal			🚦 Hackable and configurable output rendering for loggers
@uswitch/koa-timeout			⏰ A Koa middleware to handle timeouts correctly
@uswitch/koa-tracer			🕵️‍♀️ A koa.js middleware to add namespaced tracing throughout a requests lifecycle
@uswitch/koa-zipkin			🕵️‍♀️ A koa.js middleware to add Zipkin tracing to requests

koa packages

Package	Version	Latest
koa	^2.6.2
koa-bodyparser	^4.2.1
koa-compose	^4.1.0
koa-helmet	^4.0.0
koa-requestid	^2.0.1
koa-router	^7.4.0
koa-static	^5.0.0

Library

koa-core can also be used as a boilerplate library to quickly set upo a new Koa server in the same was as the Koa library itself.

Usage

import Koa from '@uswitch/koa-core'

const { app, logger } = new Koa()
app.listen(3000, () => logger.info('Applications started on port 3000'))

N.B. koa-core returns an app and a logger

Importing dependencies

All of the koa packages we have are available to import in your project via the following;

/* ES6 Import */
import koaLibrary from '@uswitch/koa-core/koa-library'

/* Require */
const koaLibrary = require('@uswitch/koa-core/koa-library')

See packages for a list of available koa libraries through koa-core.

Example

This project also comes with an Example server and some example routes which shows how we use the @uswitch/koa libraries.

npm install
NODE_ENV=development npm run example
NODE_ENV=production npm run example

This will start the server on port http://localhost:3000 and you can try hitting the following routes to see how it works;

curl http://localhost:3000/hello         // 200 string body
curl http://localhost:3000/hello/world

// Test different status codes
curl http://localhost:3000/status/200
curl http://localhost:3000/status/404
curl http://localhost:3000/status/503

// Test tracing errors as they happen
curl http://localhost:3000/error         // Fatal error
curl http://localhost:3000/multi-errors  // Multiple errors non fatal

// Test tracing behaviour
curl http://localhost:3000/trace/150     // Trace either side of 150ms async
curl http://localhost:3000/scope/name    // Trace message to scope NAME

// See all types of koa-signal message
curl http://localhost:3000/signal/all

// See how zipkin tracing works
curl http://locahost:3000/zipkin