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
• alias names (with named parameters & REST shorthand)
• whitelist
• multiple body parsers (json, urlencoded)
• CORS headers
• Rate limiter
• Middlewares
• 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-2017 Ice-Services

Changelog

0.6.0 (2018-01-04)

Breaking changes

Alias custom function arguments is changed

The route first argument is removed. The new signature of function is function(req, res) {}. To access to route use the req.$route property. However you can use an array of Function for aliases. With it you can call middlewares. In this case the third argument is next. I.e.: function(req, res, next) {}.

Other changes

• better error handling. Always returns with JSON error response.
• The charset is UTF-8 for application/json responses.
• logRequestParams setting to log the request parameters. Use log level value i.e. "debug", "info" or null to disable.
• logResponseData setting to log the response data. Use log level value i.e. "debug", "info" or null to disable.
• req.$service & res.$service is pointed to the service instance.
• req.$route & res.$route is pointed to the route definition.
• req.$params is pointed to the resolved parameters (from query string & post body)
• req.$alias is pointed to the alias definition.
• req.$endpoint is pointed to the resolved action endpoint. It contains action and nodeID.

Middlewares

Support middlewares in global, routes & aliases.

broker.createService({
    mixins: [ApiService],
    settings: {
        // Global middlewares. Applied to all routes.
        use: [
            cookieParser(),
            helmet()
        ],

        routes: [
            {
                path: "/",

                // Route-level middlewares.
                use: [
                    compression(),
                    
                    passport.initialize(),
                    passport.session(),

                    serveStatic(path.join(__dirname, "public"))
                ],
                
                aliases: {
                    "GET /secret": [
                        // Alias-level middlewares.
                        auth.isAuthenticated(),
                        auth.hasRole("admin"),
                        "top.secret" // Call the `top.secret` action
                    ]
                }
            }
        ]
    }
});

Custom response headers

It supports custom response headers to define in action definition.

module.exports = {
    name: "export",
    actions: {
        downloadCSV: 
            responseHeaders: {
                "Content-Disposition": "attachment; filename=\"data.csv\"",
                "Content-Type": "text/csv"
            },
            handler() {
                return "...";
            }
        }
    }
}

Error handlers

You can add route & global custom error handlers.

broker.createService({
    mixins: [ApiService],
    settings: {

        routes: [{
            path: "/api",

            // Route error handler
            onError(req, res, err) {
                res.setHeader("Content-Type", "application/json; charset=utf-8");
                res.writeHead(500);
                res.end(JSON.stringify(err));
            }
        }],

        // Global error handler
        onError(req, res, err) {
            res.setHeader("Content-Type", "text/plain");
            res.writeHead(501);
            res.end("Global error: " + err.message);
        }		
    }
}

New examples to serve client-side developing with Webpack

• Webpack - webpack-dev-middleware example
• Webpack & Vue - Webpack, VueJS, HMR example

---

<a name="0.5.2"></a>