A useful superclass for microservices
npm install @authkeys/microserviceThis is a fork of great fuzzy-ai-microservice. We removed databanks dependency and switched from callbacks to promises (async/await)
This is the microservice class we use for authkeys.io. The goal is to avoid
re-writing a lot of boilerplate needed to set up an HTTP server.
It has a couple of nice characteristics that make this useful for
us.
- It's configured using environment variables.
- It uses express for the web interface.
- It uses Bunyan for logging.
We use Docker, so it dumps out its logs to stdout.
Copyright 2016 Fuzzy.ai
Copyright 2019 AuthKeys srl
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
You should be able to write pretty small microservice servers. Here's an
example.
``coffeescript
Microservice = require '@authkeys/microservice'
class BasicServer extends Microservice
# Override setupRoutes to add routes to your expressjs server
setupRoutes: (exp) ->
exp.get '/version', (req, res, next) ->
res.json {version: '0.1.0'}
# This one uses the built-in app authentication
exp.get '/who-am-i', @appAuthc, (req, res, next) ->
res.json {appName: req.appName}
server = new BasicServer()
server.start (err) ->
if err
console.error(err)
else
console.log("Server started.")
`
Note that you probably shouldn't invoke Microservice directly; you should use
a sub-class. Here are the methods that you should use:
- constructor(environment). Takes an environment as a parameter. If none is
provided, uses process.env. The environment variables are changed into
configuration options.
- start(). Start the microservice. It returns a promise
- stop(). Stop the microservice. It returns a promise
These are methods that sub-classes of Microservice should overload.
- setupMiddleware(exp). If you have any custom middleware to set up for theexp
express server , do it here.
- setupParams(exp). Any custom params would go here. Good place forexp.param()
statements.
- setupRoutes(app, express). All your routes should go here.
- startCustom(). If you need to have something happen after starting
the server, do it here. This is a good time for ensuring databank items, for
example. It returns a promise
- stopCustom(). If you need to do something before stopping (what?),
do it here. It returns a promise
- environmentToConfig(env). Convert the environment to a config object.
These ones might be useful to overload if they're not working correctly.
- getName(). Return the name of the microservice. Used for error reportingnpm run start
and the like. Default implementation guesses from environment variables, so if
you use for your microservice, you should be fine.
- getVersion(). Ditto, but for the version.
These are some useful methods for microservice sub-classes to use.
- envInt(env, key, def): Return the environment variable from env at key
as an integer, or if the variable doesn't exist.
- envJSON(env, key, def): Return the environment variable from env atkey
, parsed as JSON, or def if the variable doesn't exist.
- envBool(env, key, def): Return the environment variable from env atkey
, interpreted as a boolean, or def if the variable doesn't exist.true
Case-insensitive variables that match "true", "yes", "on", or "1" are boolean
; ones that match "false", "no", "off", or "0" are boolean false.
Anything else gives an error.
- appAuthc(req, res, next): Middleware for checking the bearer token of a
request against the configured app keys (see below). Will give the correct
authorization error if none is allowed. Use this in your routes!
- slackMessage(type, message, icon, callback). Notification method for
sending updates to Slack. Errors are sent to Slack by default, but you can
send other notifications if you need to. You can send things to different
hooks using the 'type' modifier. If there is no specific hook for that type
(see SLACK_HOOK_SOMETHING below for how to do that), it will be sent via the
default hook.
- dontLog(req, res, next). Middleware to use when you don't want to have
a route logged. Useful for e.g. health-check URLs.
The system uses environment variables for configuration. This is great if you
use Docker. We use Docker Compose, so that's even more great.
Here are the variables it uses by default.
- PORT: The port to listen on. Defaults to 443 if KEY is set (see
below), otherwise 80.
- ADDRESS: IP address to listen on. Defaults to '0.0.0.0', meaning all
addresses.
- HOSTNAME: hostname to use. Use address instead, usually.
- KEY: SSL key to use. This is the full key, not the name of a file.
- CERT: SSL cert to use. This is the full cert, not the name of a file.
- LOG_LEVEL: Bunyan log level. Defaults to 'info'.
- APP_KEY_SOMETHING: The app key that app 'something' will use to access
this server. Supported by internal appAuthc.
- MAX_UPLOAD_SIZE: Maximum size of an upload. Use a string with 'mb', 'gb'
or 'kb' to define a size in bytes. Defaults to '50mb'.
- SLACK_HOOK: A Webhook from
Slack for posting messages.
- SLACK_HOOK_SOMETHING: Hook for sending 'something' messages to Slack.
This lets you specialise your Slack messages. By default, the error handler
will use the 'error' hook, or it will fall back to the default. Note that
hook 'SLACK_HOOK_SOMETHING' will get lowercased to 'something' when you need
to send a slack message.
You can have a microservice grab more environment variables by overloading
environmentToConfig.
`coffeescript``
environmentToConfig: (environment) ->
cfg = super environment
cfg.foo = environment.FOO
cfg