The core that powers uSwitch Koa services.

Overview | Packages | Library | Example

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

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

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

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

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

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.

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

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.

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