moleculer-web

Official API Gateway for Moleculer framework

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

Features

• support HTTP & HTTPS
• serve static files
• multiple routes
• support global, route, alias middlewares
• support file uploading
• alias names (with named parameters & REST shorthand)
• whitelist
• multiple body parsers (json, urlencoded)
• CORS headers
• ETags
• HTTP2
• Rate limiter
• before & after call hooks
• Buffer & Stream handling
• middleware mode (use as a middleware in ExpressJS Application)
• 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 });

// Create a service
broker.createService({
    name: "test",
    actions: {
        hello() {
            return "Hello API Gateway!"
        }
    }
});

// Load API Gateway
broker.createService(ApiService);

// Start server
broker.start();

Test URLs:

• Call test.hello action: http://localhost:3000/test/hello

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

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

Documentation

Please read our documentation on Moleculer site

Test

$ npm test

In development with watching

$ npm run ci

License

Moleculer-web is available under the MIT license.

Contact

Copyright (c) 2016-2021 MoleculerJS

Changelog

0.10.0 (2021-06-27)

Breaking changes

Avoid array wrapping at file uploading

Many users issued that at file uploading the response always wrapped into an array even single file uploading. This issues is fixed in this version. If you define files: 1 in busboy settings, the response won't be wrapped into array.

Example

const ApiGateway = require("moleculer-web");

module.exports = {
    mixins: [ApiGateway],
    settings: {
        path: "/upload",

        routes: [
            {
                path: "/upload",

                busboyConfig: {
                    limits: {
                        files: 1
                    }
                },
            }
        ]
    }
};

JSON body-parser is the new default.

In early version, if you added multiple routes, you should always set JSON body-parser. As of v0.10, it's the new default, if you don't define bodyParsers in the route options. If you don't want to use any body-parsers just set bodyParsers: false.

Example: disable body parsers

const ApiGateway = require("moleculer-web");

module.exports = {
    mixins: [ApiGateway],
    settings: {
        routes: [
            {
                path: "/api",
                bodyParsers: false
            }
        ]
    }
};

New features

Actions for adding and removing routes

The addRoute and removeRoute methods exposed to service actions, as well. It means, you can add/remove routes from remote nodes, as well.

Adding a new route

broker.call("api.addRoute", {
    route: {
        path: "/api",
        aliases: {
            "hi": "greeter.hello"
        }
    },
    toBottom: true // add this route to the end of the route list.
})

Removing a route

broker.call("api.removeRoute", { path: "/api" });

New logging options

There are two new logging service settings: logRequest, logResponse. You can define the logging level for request & response log messages.

const ApiGateway = require("moleculer-web");

module.exports = {
    mixins: [ApiGateway],
    settings: {
        logRequest: "debug", // Logging with debug level
        logResponse: false, // Disable logging
        //.....
    }
};

New rootCallOptions options

There a new rootCallOptions property in the service settings. Here you can define the root Context calling options. It can be a static Object or a Function. It can be useful to take some data from the req and put them to the calling options (like tracing informations)

Example with static object

const ApiGateway = require("moleculer-web");

module.exports = {
    mixins: [ApiGateway],
    settings: {
        routes: [/*...*/],

        rootCallOptions: {
            timeout: 500
        }
    }
};

Example with Function which takes tracing information from the req and put them to the calling options

const ApiGateway = require("moleculer-web");

module.exports = {
    mixins: [ApiGateway],
    settings: {
        routes: [/*...*/],

        rootCallOptions(options, req, res) {
            if (req.headers["traceparent"]) {
                // More info https://www.w3.org/TR/trace-context/#traceparent-header
                const traceparent = req.headers["traceparent"].toLowerCase();
                if (traceparent.match(/^([0-9a-f]{2})-([0-9a-f]{32})-([0-9a-f]{16})-([0-9a-f]{2})$/)) {
                    const [version, id, parentSpan, flags] = traceparent.split("-");
                    const sampled = (flags & FLAG_SAMPLED) == FLAG_SAMPLED;

                    options.parentSpan = {
                        id: parentSpan,
                        traceID: id,
                        sampled
                    };
                }
            } else {
                // Look for X-B3-Traceid, X-B3-Spanid
                options.parentSpan = {};

                if (req.headers["x-b3-traceid"]) {
                    options.parentSpan.traceID = req.headers["x-b3-traceid"].toLowerCase();
                    options.parentSpan.sampled = true;
                }
                if (req.headers["x-b3-spanid"]) {
                    options.parentSpan.id = req.headers["x-b3-spanid"].toLowerCase();
                }
            }
        }
    }
};

Multiple route aliases

You can define multiple REST aliases in the action definitions.

module.exports = {
    name: "posts",

    settings: {
        rest: ["/posts", "/v1/posts"]
    },

    actions: {
        find: {
            rest: ["GET /", "GET /all"]
            handler(ctx) {}
        }
    }
};

Multipart fields & URL Params

Several issues has been fixed with multipart handling.

• URL parameters (e.g. /api/upload/:tenant/:folder) is available via ctx.meta.$params
• Multipart fields is available via ctx.meta.$multipart
• ctx.params.$params is not available, use ctx.meta.$params
• The target action is called if no uploaded files but has multipart fields. In this case ctx.params is {} and the fields are in ctx.meta.$multipart.

Other changes

• set response header from ctx.meta in case of errors, as well.
• update dependencies.
• update index.d.ts.
• remove deprecated publish: false condition. Use `visibility: "public", instead.

---

<a name="0.9.1"></a>