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:packagesThis 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
N.B. Conflicts when publishing
ERR! lifecycle "publish" errored in "@uswitch/koa-access", exiting 1You may see conflicts when publishing all packages caused by@uswitch/koa-access. This will error before@uswitch/koa-coreis published itself You can runnpm publishfrom within the root of each package to publish them individually.
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.15.4 |
 |
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 exampleThis 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