API Gateway

moleculer-web npm

The moleculer-web is the official API gateway service for Moleculer framework. Use it to publish your services.

Features

  • support HTTP & HTTPS
  • serve static files
  • multiple routes
  • alias names (with named parameters & REST routes)
  • whitelist
  • multiple body parsers (json, urlencoded)
  • CORS headers
  • Rate limiter
  • before & after call hooks
  • Buffer & Stream handling
  • middleware mode (use as a middleware with Express)
  • support authorization

Install

npm install moleculer-web --save

Usage

Run with default settings

This example uses API Gateway service with default settings.
You can access to all services (including internal $node.) via http://localhost:3000/

let { ServiceBroker } = require("moleculer");
let ApiService = require("moleculer-web");
let broker = new ServiceBroker({ logger: console });
// Load API Gateway
broker.createService(ApiService);
// Start server
broker.start();

Example URLs:

  • Call test.hello action: http://localhost:3000/test/hello
  • Call math.add action with params: http://localhost:3000/math/add?a=25&b=13

  • Get health info of node: http://localhost:3000/~node/health

  • List all actions: http://localhost:3000/~node/actions

Whitelist

If you don’t want to public all actions, you can filter them with whitelist option.
You can use match strings or regexp in list.

broker.createService({
mixins: [ApiService],
settings: {
routes: [{
path: "/api",
whitelist: [
// Access to any actions in 'posts' service
"posts.*",
// Access to call only the `users.list` action
"users.list",
// Access to any actions in 'math' service
/^math\.\w+$/
]
}]
}
});

Aliases

You can use alias names instead of action names. You can also specify the method. Otherwise it will handle every method types.

It is possible to use named parameters in aliases. Named parameters are defined by prefixing a colon to the parameter name (:name).

broker.createService({
mixins: [ApiService],
settings: {
routes: [{
aliases: {
// Call `auth.login` action with `GET /login` or `POST /login`
"login": "auth.login"
// Restrict the request method
"POST users": "users.create",
// The `name` comes from named param.
// You can access it with `ctx.params.name` in action
"GET greeter/:name": "test.greeter",
}
}]
}
});

The named parameter is handled with path-to-regexp module. Therefore you can use optional and repeated parameters as well.

You can also create RESTful APIs.

broker.createService({
mixins: [ApiService],
settings: {
routes: [{
aliases: {
"GET users": "users.list",
"GET users/:id": "users.get",
"POST users": "users.create",
"PUT users/:id": "users.update",
"DELETE users/:id": "users.remove"
}
}]
}
});

For REST routes you can also use this simple shorthand alias:

broker.createService({
mixins: [ApiService],
settings: {
routes: [{
aliases: {
"REST users": "users"
}
}]
}
});

To use this shorthand alias you need to create a service which has list, get, create, update and remove actions.

You can use custom function is aliases:

broker.createService({
mixins: [ApiService],
settings: {
routes: [{
aliases: {
"POST upload"(route, req, res) {
this.parseUploadedFile(route, req, res);
}
}
}]
}
});

Serve static files

It serves assets with the serve-static module like ExpressJS.

broker.createService({
mixins: [ApiService],
settings: {
assets: {
// Root folder of assets
folder: "./assets",
// Further options to `server-static` module
options: {}
}
}
});

Calling options

The route has a callOptions property which is passed to broker.call. So you can set timeout, retryCount or fallbackResponse options for routes. Read more about calling options

broker.createService({
mixins: [ApiService],
settings: {
routes: [{
callOptions: {
timeout: 500,
retryCount: 0,
fallbackResponse(ctx, err) { ... }
}
}]
}
});

Multiple routes

You can create multiple routes with different prefix, whitelist, alias, calling options & authorization.

broker.createService({
mixins: [ApiService],
settings: {
routes: [
{
path: "/admin",
authorization: true,
whitelist: [
"$node.*",
"users.*",
]
},
{
path: "/",
whitelist: [
"posts.*",
"math.*",
]
}
]
}
});

Authorization

You can implement authorization. For this you have to do 2 things.

  1. Set authorization: true in your routes
  2. Define the authorize method in service.

Example authorization

const E = require("moleculer-web").Errors;
broker.createService({
mixins: [ApiService],
settings: {
routes: [{
// First thing
authorization: true
}]
},
methods: {
// Second thing
authorize(ctx, route, req, res) {
// Read the token from header
let auth = req.headers["authorization"];
if (auth && auth.startsWith("Bearer")) {
let token = auth.slice(7);
// Check the token
if (token == "123456") {
// Set the authorized user entity to `ctx.meta`
ctx.meta.user = { id: 1, name: "John Doe" };
return Promise.resolve(ctx);
} else {
// Invalid token
return Promise.reject(new E.UnAuthorizedError(E.ERR_INVALID_TOKEN));
}
} else {
// No token
return Promise.reject(new E.UnAuthorizedError(E.ERR_NO_TOKEN));
}
}
}
}

You can find a more detailed role-based JWT authorization example in full example.

Route hooks

The route has before & after call hooks. You can use it to set ctx.meta, access to req.headers or modify the response data.

broker.createService({
mixins: [ApiService],
settings: {
routes: [
{
path: "/",
onBeforeCall(ctx, route, req, res) {
// Set request headers to context meta
ctx.meta.userAgent = req.headers["user-agent"];
},
onAfterCall(ctx, route, req, res, data) {
// Async function which return with Promise
return doSomething(ctx, res, data);
}
}
]
}
});

CORS headers

You can use CORS headers in Moleculer-Web service.

Usage

const svc = broker.createService({
mixins: [ApiService],
settings: {
// Global CORS settings for all routes
cors: {
// Configures the Access-Control-Allow-Origin CORS header.
origin: "*",
// Configures the Access-Control-Allow-Methods CORS header.
methods: ["GET", "OPTIONS", "POST", "PUT", "DELETE"],
// Configures the Access-Control-Allow-Headers CORS header.
allowedHeaders: [],
// Configures the Access-Control-Expose-Headers CORS header.
exposedHeaders: [],
// Configures the Access-Control-Allow-Credentials CORS header.
credentials: false,
// Configures the Access-Control-Max-Age CORS header.
maxAge: 3600
},
routes: [{
path: "/api",
// Route CORS settings (overwrite global settings)
cors: {
origin: ["http://localhost:3000", "https://localhost:4000"],
methods: ["GET", "OPTIONS", "POST"],
credentials: true
},
}]
}
});

Rate limiter

The Moleculer-Web has a built-in rate limiter with a memory store.

Usage

const svc = broker.createService({
mixins: [ApiService],
settings: {
rateLimit: {
// How long to keep record of requests in memory (in milliseconds).
// Defaults to 60000 (1 min)
window: 60 * 1000,
// Max number of requests during window. Defaults to 30
limit: 30,
// Set rate limit headers to response. Defaults to false
headers: true,
// Function used to generate keys. Defaults to:
key: (req) => {
return req.headers["x-forwarded-for"] ||
req.connection.remoteAddress ||
req.socket.remoteAddress ||
req.connection.socket.remoteAddress;
},
//StoreFactory: CustomStore
}
}
});

Custom Store example

class CustomStore {
constructor(window, opts) {
this.hits = new Map();
this.resetTime = Date.now() + clearPeriod;
setInterval(() => {
this.resetTime = Date.now() + clearPeriod;
this.reset();
}, clearPeriod);
}
/**
* Increment the counter by key
*
* @param {String} key
* @returns {Number}
*/
inc(key) {
let counter = this.hits.get(key) || 0;
counter++;
this.hits.set(key, counter);
return counter;
}
/**
* Reset all counters
*/
reset() {
this.hits.clear();
}
}

ExpressJS middleware usage

You can use Moleculer-Web as a middleware in an ExpressJS application.

Usage

const svc = broker.createService({
mixins: [ApiService],
settings: {
middleware: true
}
});
// Create Express application
const app = express();
// Use ApiGateway as middleware
app.use("/api", svc.express());
// Listening
app.listen(3000);
// Start server
broker.start();

Service settings

List of all settings of Moleculer Web servie

settings: {
// Exposed port
port: 3000,
// Exposed IP
ip: "0.0.0.0",
// HTTPS server with certificate
https: {
key: fs.readFileSync("ssl/key.pem"),
cert: fs.readFileSync("ssl/cert.pem")
},
// Middleware mode (for ExpressJS)
middleware: false,
// Exposed global path prefix
path: "/api",
// Routes
routes: [
{
// Path prefix to this route (full path: /api/admin )
path: "/admin",
// Whitelist of actions (array of string mask or regex)
whitelist: [
"users.get",
"$node.*"
],
// Call the `this.authorize` method before call the action
authorization: true,
// Action aliases
aliases: {
"POST users": "users.create",
"health": "$node.health"
},
// Use bodyparser module
bodyParsers: {
json: true,
urlencoded: { extended: true }
}
},
{
// Path prefix to this route (full path: /api )
path: "",
// Whitelist of actions (array of string mask or regex)
whitelist: [
"posts.*",
"file.*",
/^math\.\w+$/
],
// No authorization
authorization: false,
// Action aliases
aliases: {
"add": "math.add",
"GET sub": "math.sub",
"POST divide": "math.div",
"GET greeter/:name": "test.greeter",
"GET /": "test.hello"
},
// Use bodyparser module
bodyParsers: {
json: false,
urlencoded: { extended: true }
},
// Calling options
callOptions: {
timeout: 3000,
fallbackResponse: "Static fallback response"
},
// Call before `broker.call`
onBeforeCall(ctx, route, req, res) {
ctx.meta.userAgent = req.headers["user-agent"];
},
// Call after `broker.call` and before send back the response
onAfterCall(ctx, route, req, res, data) {
res.setHeader("X-Custom-Header", "123456");
}
}
],
// Folder to server assets (static files)
assets: {
// Root folder of assets
folder: "./examples/www/assets",
// Options to `server-static` module
options: {}
}
}

Examples

  • Simple

    • simple gateway with default settings.
  • SSL server

    • open HTTPS server
    • whitelist handling
  • WWW with assets

    • serve static files from the assets folder
    • whitelist
    • aliases
    • multiple body-parsers
  • Authorization

    • simple authorization demo
    • set the authorized user to Context.meta
  • REST

    • simple server with RESTful aliases
    • example posts service with CRUD actions
  • Express

    • webserver with Express
    • use moleculer-web as a middleware
  • Socket.io

    • start socket.io websocket server
    • call action and send back the response via websocket
    • send Moleculer events to the browser via websocket
  • Full

    • SSL
    • static files
    • multiple routes with different roles
    • role-based authorization with JWT
    • whitelist
    • aliases with named params
    • multiple body-parsers
    • before & after hooks
    • metrics, statistics & validation from Moleculer