README
🎾 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
koa-core
was built using Node v10 so you should run the
following when developing it.
nvm use
Packages
packages @uswitch
| 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 |
packages koa
| 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