@mashroom/mashroom

Mashroom Server

Mashroom Server is a Node.js based Integration Platform for Microfrontends.

This package contains the core of Mashroom Server. It contains core services for managing plugins and default plugin loaders for Express middleware, Express webapps and shared code as services. It also provides a common logging infrastructure.

From a technical point of view this is s a plugin loader that scans npm packages (package.json) for plugin definitions and loads them at runtime. Such a plugin could be an Express webapp or a SPA or more generally all kind of code it knows how to load, which is determined by the available plugin loaders. Plugin loaders itself are also just plugins so it is possible to extend the list of known plugin types.

Usage

The easiest way to start is to clone one of the quickstart repositories:

• mashroom-quickstart
• mashroom-portal-quickstart

You can find a full documentation with a setup and configuration guide here: https://www.mashroom-server.com/documentation

Services

MashroomPluginService

Accessible through pluginContext.services.core.pluginService

Interface:

 /**
  * Mashroom plugin service
  */
 export interface MashroomPluginService {
     /**
      * The currently known plugin loaders
      */
     getPluginLoaders(): MashroomPluginLoaderMap;
     /**
      * Get all currently known plugins
      */
     getPlugins(): Array<MashroomPlugin>;
     /**
      * Get all currently known plugin packages
      */
     getPluginPackages(): Array<MashroomPluginPackage>;
 }   

MashroomMiddlewareStackService

Accessible through pluginContext.services.core.middlewareStackService

Interface:

/**
 * A service to access and introspect the middleware stack
 */
export interface MashroomMiddlewareStackService {
    /**
     * Check if the stack has given plugin
     */
    has(pluginName: string): boolean;
    /**
     * Execute the given middleware.
     * Throws an exception if it doesn't exists
     */
    apply(pluginName: string, req: ExpressRequest, res: ExpressResponse): Promise<void>;
    /**
     * Get the ordered list of middleware plugin (first in the list is executed first)
     */
    getStack(): Array<{ pluginName: string, order: number }>;
} 

Plugin Types

plugin-loader

A plugin-loader plugin adds support for a custom plugin type.

To register a new plugin-loader add this to package.json:

{
    "mashroom": {     
        "plugins": [
            {
                "name": "My Custom Plugin Loader",
                "type": "plugin-loader",
                "bootstrap": "./dist/mashroom-bootstrap",
                "loads": "my-custom-type",
                "defaultConfig": {
                   "myProperty": "foo"
                }
            }
        ]
    }
}

• loads: The plugin type this loader can handle

After that all plugins of type my-custom-type will be passed to your custom loader instantiated by the bootstrap script:

// @flow

import type {
    MashroomPluginLoader, MashroomPlugin, MashroomPluginConfig, MashroomPluginContext, 
    MashroomPluginLoaderPluginBootstrapFunction
} from 'mashroom/type-definitions';

class MyPluginLoader implements MashroomPluginLoader {

    get name(): string {
        return 'My Plugin Loader';
    }

    generateMinimumConfig(plugin: MashroomPlugin) {
        return {};
    }

    async load(plugin: MashroomPlugin, config: MashroomPluginConfig, context: MashroomPluginContext) {
        // TODO
    }

    async unload(plugin: MashroomPlugin) {
        // TODO
    }
}

const myPluginLoaderPlugin: MashroomPluginLoaderPluginBootstrapFunction = (pluginName, pluginConfig, pluginContextHolder) => {
    return new MyPluginLoader();
};

export default myPluginLoaderPlugin;

web-app

Registers a Express webapp that will be available at a given path.

To register a web-app plugin add this to package.json:

{
     "mashroom": {
        "plugins": [
            {
                "name": "My Webapp",
                "type": "web-app",
                "bootstrap": "./dist/mashroom-bootstrap.js",
                "defaultConfig": {
                    "path": "/my/webapp",
                    "myProperty": "foo"
                }
            }
        ]
     }
}

• defaultConfig.path: The default path where the webapp will be available

And the bootstrap just returns the Express webapp:

// @flow

import webapp from './webapp';

import type {MashroomWebAppPluginBootstrapFunction} from '@mashroom/mashroom/type-definitions';

const bootstrap: MashroomWebAppPluginBootstrapFunction = async () => {
    return webapp;
};

export default bootstrap;

** Additional handlers **

It is possible to return handlers in the bootstrap as well. Currently there a two additional handlers:

• upgradeHandler: Handle HTTP Upgrades (e.g. upgrade to WebSocket)
• onUnload: Called when the webapp is unloaded or reloaded

Example:

const bootstrap: MashroomWebAppPluginBootstrapFunction = async () => {
    return {
        expressApp: webapp,
        upgradeHandler: (request: HttpServerRequest, socket: net$Socket, head: Buffer) => {
            // TODO
        },
        onUnload: () => {
            // TODO
        }    
    };
};

api

Registers a Express Router (a REST API) and makes it available at a given path.

To register a API plugin add this to package.json:

{
     "mashroom": {
        "plugins": [
            {
                "name": "My REST API",
                "type": "api",
                "bootstrap": "./dist/mashroom-bootstrap.js",
                "defaultConfig": {
                    "path": "/my/api",
                    "myProperty": "foo"
                }
            }
        ]
    }
}

• defaultConfig.path: The default path where the api will be available

And the bootstrap just returns the Express router:

// @flow

const express = require('express');
const router = express.Router();

router.get('/', (req, res) => {
  // ...
});

import type {MashroomApiPluginBootstrapFunction} from '@mashroom/mashroom/type-definitions';

const bootstrap: MashroomApiPluginBootstrapFunction = async () => {
    return router;
};

export default bootstrap;

middleware

Registers a Express middleware and adds it to the global middleware stack.

To register a middleware plugin add this to package.json:

{
    "mashroom": {
        "plugins": [{
            "name": "My Middleware",
            "type": "middleware",
            "bootstrap": "./dist/mashroom-bootstrap.js",
            "defaultConfig": {
                "order": 500,
                "myProperty": "foo"
            }
        }]
    }
}

• defaultConfig.order: he weight of the middleware in the stack - the higher it is the later it will be executed

And the bootstrap just returns the Express middleware:

// @flow

import MyMiddleware from './MyMiddleware';

import type {MashroomMiddlewarePluginBootstrapFunction} from '@mashroom/mashroom/type-definitions';

const bootstrap: MashroomMiddlewarePluginBootstrapFunction = async (pluginName, pluginConfig, pluginContextHolder) => {
    const pluginContext = pluginContextHolder.getPluginContext();
    const middleware = new MyMiddleware(pluginConfig.myProperty, pluginContext.loggerFactory);
    return middleware.middleware();
};

export default bootstrap;

static

Registers some static resources and exposes it at a given path (via Express static).

To register a static plugin add this to package.json:

{
    "mashroom": {
        "plugins": [{
            "name": "My Documents",
            "type": "static",
            "documentRoot": "./my-documents",
            "defaultConfig": {
                "path": "/my/docs"
            }
        }]
    }
}

• documentRoot: Defines the local root path of the documents
• defaultConfig.path: The default path where the documents will be available

services

Used to load arbitrary shared code that can be loaded via pluginContext.

To register a service plugin add this to package.json:

{
    "mashroom": {
        "plugins": [{
            "name": "My services Services",
            "type": "services",
            "namespace": "myNamespace",
            "bootstrap": "./dist/mashroom-bootstrap.js",
            "defaultConfig": {
            }
        }]
    }
}

• namespace: Defines the path to the services. In this case MyService will be accessible through pluginContext.services.myNamespace.service

The bootstrap will just return an object with a bunch of services:

// @flow

import MyService from './MyService';

import type {MashroomServicesPluginBootstrapFunction} from '@mashroom/mashroom/type-definitions';

const bootstrap: MashroomServicesPluginBootstrapFunction = async (pluginName, pluginConfig, pluginContextHolder) => {
    const pluginContext = pluginContextHolder.getPluginContext();
    const service = new MyService(pluginContext.loggerFactory);

    return {
        service,
    };
};

export default bootstrap;

Changelog

1.1.4 (October 23, 2019)

• Core: Logger instances created via req.pluginContext.loggerFactory('category') share now the context with all other loggers created from the same request. This can for example be used to output tracing information with each log entry. The following context properties will be added automatically to each request:
  • clientIP
  • browser (e.g. Chrome, Firefox)
  • browserVersion
  • os (e.g. Windows)
  • sessionID (if a session is available)
  • portalAppName (if the request is related to a portal app)
  • portalAppVersion (if the request is related to a portal app) To add additional properties to the logger context use the new logger.addContext() method (e.g. within a middleware). If you want to output context properties with the log entries you could configure the log4js appender like this:

  "console": {
      "type": "console",
      "layout": {
          "type": "pattern",
          "pattern": "%d %p %X{sessionID} %X{browser} %X{browserVersion} %X{username} %X{portalAppName} %X{portalAppVersion} %c - %m"
      }
  }
  

• HTTP Proxy: White listed Jaeger, OpenZipkin and W3C Trace Context HTTP headers by default
• HTTP Proxy: Fixed the problem that all requests headers got forwarded to the target, even cookie and other security relevant ones