Micro โ Asynchronous HTTP microservices
- Easy: Designed for usage with
async
andawait
(more) - Fast: Ultra-high performance (even JSON parsing is opt-in)
- Micro: The whole project is ~260 lines of code
- Agile: Super easy deployment and containerization
- Simple: Oriented for single purpose modules (function)
- Standard: Just HTTP!
- Explicit: No middleware - modules declare all dependencies
- Lightweight: With all dependencies, the package weighs less than a megabyte
Important: Micro is only meant to be used in production. In development, you should use micro-dev, which provides you with a tool belt specifically tailored for developing microservices.
To prepare your microservice for running in the production environment, firstly install micro
:
npm install --save micro
Then create an index.js
file and populate it with function, that accepts standard http.IncomingMessage and http.ServerResponse objects:
module.exports = (req, res) => {
res.end('Welcome to Micro')
}
Micro provides useful helpers but also handles return values โ so you can write it even shorter!
module.exports = () => 'Welcome to Micro'
Next, ensure that the main
property inside package.json
points to your microservice (which is inside index.js
in this example case) and add a start
script:
{
"main": "index.js",
"scripts": {
"start": "micro"
}
}
Once all of that is done, the server can be started like this:
npm start
And go to this URL: http://localhost:3000
- ๐
Examples
Micro is built for usage with async/await. You can read more about async / await here
const sleep = require('then-sleep')
module.exports = async (req, res) => {
await sleep(500)
return 'Ready!'
}
The package takes advantage of native support for async
and await
, which is always as of Node.js 8.0.0! In turn, we suggest either using at least this version both in development and production (if possible), or transpiling the code using async-to-gen, if you can't use the latest Node.js version.
In order to do that, you firstly need to install it:
npm install --save async-to-gen
And then add the transpilation command to the scripts.build
property inside package.json
:
{
"scripts": {
"build": "async-to-gen input.js > output.js"
}
}
Once these two steps are done, you can transpile the code by running this command:
npm run build
That's all it takes to transpile by yourself. But just to be clear: Only do this if you can't use Node.js 8.0.0! If you can, async
and await
will just work right out of the box.
When you want to set the port using an environment variable you can use:
micro -p $PORT
Optionally you can add a default if it suits your use case:
micro -p ${PORT:-3000}
${PORT:-3000}
will allow a fallback to port 3000
when $PORT
is not defined.
For parsing the incoming request body we included an async functions buffer
, text
and json
const {buffer, text, json} = require('micro')
module.exports = async (req, res) => {
const buf = await buffer(req)
console.log(buf)
// <Buffer 7b 22 70 72 69 63 65 22 3a 20 39 2e 39 39 7d>
const txt = await text(req)
console.log(txt)
// '{"price": 9.99}'
const js = await json(req)
console.log(js.price)
// 9.99
return ''
}
- Buffers and parses the incoming body and returns it.
- Exposes an
async
function that can be run withawait
. - Can be called multiple times, as it caches the raw request body the first time.
limit
is how much data is aggregated before parsing at max. Otherwise, anError
is thrown withstatusCode
set to413
(see Error Handling). It can be aNumber
of bytes or a string like'1mb'
.- If JSON parsing fails, an
Error
is thrown withstatusCode
set to400
(see Error Handling)
For other types of data check the examples
So far we have used return
to send data to the client. return 'Hello World'
is the equivalent of send(res, 200, 'Hello World')
.
const {send} = require('micro')
module.exports = async (req, res) => {
const statusCode = 400
const data = { error: 'Custom error message' }
send(res, statusCode, data)
}
- Use
require('micro').send
. statusCode
is aNumber
with the HTTP status code, and must always be supplied.- If
data
is supplied it is sent in the response. Different input types are processed appropriately, andContent-Type
andContent-Length
are automatically set.Stream
:data
is piped as anoctet-stream
. Note: it is your responsibility to handle theerror
event in this case (usually, simply logging the error and aborting the response is enough).Buffer
:data
is written as anoctet-stream
.object
:data
is serialized as JSON.string
:data
is written as-is.
- If JSON serialization fails (for example, if a cyclical reference is found), a
400
error is thrown. See Error Handling.
You can use Micro programmatically by requiring Micro directly:
const micro = require('micro')
const sleep = require('then-sleep')
const server = micro(async (req, res) => {
await sleep(500)
return 'Hello world'
})
server.listen(3000)
- This function is exposed as the
default
export. - Use
require('micro')
. - Returns a
http.Server
that uses the providedfunction
as the request handler. - The supplied function is run with
await
. So it can beasync
- Use
require('micro').sendError
. - Used as the default handler for errors thrown.
- Automatically sets the status code of the response based on
error.statusCode
. - Sends the
error.message
as the body. - Stacks are printed out with
console.error
and during development (whenNODE_ENV
is set to'development'
) also sent in responses. - Usually, you don't need to invoke this method yourself, as you can use the built-in error handling flow with
throw
.
- Use
require('micro').createError
. - Creates an error object with a
statusCode
. - Useful for easily throwing errors with HTTP status codes, which are interpreted by the built-in error handling.
orig
setserror.originalError
which identifies the original error (if any).
Micro allows you to write robust microservices. This is accomplished primarily by bringing sanity back to error handling and avoiding callback soup.
If an error is thrown and not caught by you, the response will automatically be 500
. Important: Error stacks will be printed as console.error
and during development mode (if the env variable NODE_ENV
is 'development'
), they will also be included in the responses.
If the Error
object that's thrown contains a statusCode
property, that's used as the HTTP code to be sent. Let's say you want to write a rate limiting module:
const rateLimit = require('my-rate-limit')
module.exports = async (req, res) => {
await rateLimit(req)
// ... your code
}
If the API endpoint is abused, it can throw an error with createError
like so:
if (tooMany) {
throw createError(429, 'Rate limit exceeded')
}
Alternatively you can create the Error
object yourself
if (tooMany) {
const err = new Error('Rate limit exceeded')
err.statusCode = 429
throw err
}
The nice thing about this model is that the statusCode
is merely a suggestion. The user can override it:
try {
await rateLimit(req)
} catch (err) {
if (429 == err.statusCode) {
// perhaps send 500 instead?
send(res, 500)
}
}
If the error is based on another error that Micro caught, like a JSON.parse
exception, then originalError
will point to it. If a generic error is caught, the status will be set to 500
.
In order to set up your own error handling mechanism, you can use composition in your handler:
const {send} = require('micro')
const handleErrors = fn => async (req, res) => {
try {
return await fn(req, res)
} catch (err) {
console.log(err.stack)
send(res, 500, 'My custom error!')
}
}
module.exports = handleErrors(async (req, res) => {
throw new Error('What happened here?')
})
Micro makes tests compact and a pleasure to read and write. We recommend ava, a highly parallel Micro test framework with built-in support for async tests:
const micro = require('micro')
const test = require('ava')
const listen = require('test-listen')
const request = require('request-promise')
test('my endpoint', async t => {
const service = micro(async (req, res) => {
micro.send(res, 200, {
test: 'woot'
})
})
const url = await listen(service)
const body = await request(url)
t.deepEqual(JSON.parse(body).test, 'woot')
service.close()
})
Look at test-listen for a function that returns a URL with an ephemeral port every time it's called.
- Fork this repository to your own GitHub account and then clone it to your local device
- Link the package to the global module directory:
npm link
- Within the module you want to test your local development instance of Micro, just link it to the dependencies:
npm link micro
. Instead of the default one from npm, node will now use your clone of Micro!
As always, you can run the AVA and ESLint tests using: npm test
Thanks to Tom Yandell and Richard Hodgson for donating the name "micro" on npm!
- Guillermo Rauch (@rauchg) - ZEIT
- Leo Lamprecht (@notquiteleo) - ZEIT
- Tim Neutkens (@timneutkens) - ZEIT