@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:

export interface MashroomPluginService {
    /**
     * The currently known plugin loaders
     */
    getPluginLoaders(): Readonly<MashroomPluginLoaderMap>;

    /**
     * Get all currently known plugins
     */
    getPlugins(): Readonly<Array<MashroomPlugin>>;

    /**
     * Get all currently known plugin packages
     */
    getPluginPackages(): Readonly<Array<MashroomPluginPackage>>;

    /**
     * Register for the next loaded event of given plugin (fired AFTER the plugin has been loaded).
     */
    onLoadedOnce(pluginName: string, listener: () => void): void;

    /**
     * Register for the next unload event of given plugin (fired BEFORE the plugin is going to be unloaded).
     */
    onUnloadOnce(pluginName: string, listener: () => void): void;
}

MashroomMiddlewareStackService

Accessible through pluginContext.services.core.middlewareStackService

Interface:

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: Request,
        res: Response,
    ): 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:

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:

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 also possible to return handlers in the bootstrap. Currently there is only one:

• upgradeHandler: Handle HTTP Upgrades (e.g. upgrade to WebSocket)

Example:

const bootstrap: MashroomWebAppPluginBootstrapFunction = async () => {
    return {
        expressApp: webapp,
        upgradeHandler: (request: IncomingMessageWithContext, socket: Socket, head: Buffer) => {
            // 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:

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: the weight of the middleware in the stack - the higher it is the later it will be executed (default: 1000)

And the bootstrap just returns the Express middleware:

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:

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;

admin-ui-integration

A simple plugin to register an arbitrary web-app or static plugin as panel in the Admin UI.

To register an admin-ui-integration plugin add this to package.json:

{
    "mashroom": {
        "plugins": [{
            "name": "My Admin Panel Integration",
            "type": "admin-ui-integration",
            "requires": [
                "My Admin Panel"
            ],
            "target": "My Admin Panel",
            "defaultConfig": {
                "menuTitle": "My Admin Panel",
                "path": "/my-admin-panel",
                "height": "80vh",
                "weight": 10000
            }
        }]
    }
}

• target: The actual web-app or static plugin that should be integrated
• defaultConfig.menuTitle: The name that should be appear in the Admin UI menu
• defaultConfig.path: The path in the Admin UI (full path will be /mashroom/admin/ext/<your path>)
• defaultConfig.height: The height of the iframe that will contain the target webapp. If you want that the iframe has the full height of the webapp you have to post the height periodically to the parent, like so

    parent.postMessage({ height: contentHeight + 20 }, "*");
  

• defaultConfig.weight: The weight of the menu entry, the higher the number the lower will be menu entry be.

Changelog

1.7.0 (March 9, 2021)

• Build under windows fixed

• Problems with Node 15.x fixed

• Http Proxy: Fixed encoding of query parameters (already URL encoded parameters were encoded again)

• Portal: Added the possibility to define a default proxy config for Portal Apps. This is useful if you want to enable the permissions header for all Apps

• Moved out some example plugins to the new https://github.com/nonblocking/mashroom-plugin-demos repo

• Renamed mashroom-portal-demo-remote-messaging to mashroom-portal-remote-messaging-app because it's more a test util than a demo, just like the sandbox app

• Admin UI (under /mashroom) polished up

• Added a new plugin type admin-ui-integration to register an arbitrary web-app or static plugin as panel in the Admin UI (will be integrated via iframe)

• Remote App Registry Kubernetes: BREAKING CHANGE: Since it uses ow the new background job scheduler to scan the k8s cluster, you also need to add mashroom-background-jobs to your dependencies, and the configuration slightly changed. Checkout the README in mashroom-portal-remote-app-registry-k8s.

• Remote App Registry: BREAKING CHANGE: Since it uses ow the new background job scheduler to scan for remote apps, you also need to add mashroom-background-jobs to your dependencies, and the configuration slightly changed. Checkout the README in mashroom-portal-remote-app-registry.

• Added a background job plugin (mashroom-background-jobs) that allows it to schedule arbitrary jobs based on cron expressions

• HTTP Proxy: Added a second proxy implementation based on node-http-proxy, since request is deprecated. It can be enabled like this in the config:

  {
    "Mashroom Http Proxy Services": {
      "proxyImpl": "nodeHttpProxy"
    }
  }
  

  Default is still the request based implementation.

• Migration to TypeScript completed (but flow types are still available).

  The type aliases for express (ExpressRequest, ExpressResponse) are no longer required, so you can directly use the express types. E.g. in a middleware plugin:

   import type {Request, Response, NextFunction} from 'express';
   import type {MashroomMiddlewarePluginBootstrapFunction} from '@mashroom/mashroom/type-definitions';
  
   const myMiddleware = (req: Request, res: Response, next: NextFunction) => {
       const logger = req.pluginContext.loggerFactory('my.middleware');
       logger.info('woohoo');
       // TODO
       next();
   };
  
   const bootstrap: MashroomMiddlewarePluginBootstrapFunction = async (pluginName, pluginConfig) => {
       return myMiddleware;
   };
  
   export default bootstrap;
  

• Error Pages: Added the possibility to add default messages if mashroom-i18n is not (yet) available

• LDAP Security Provider: Under all circumstances prevent a login with an empty password since some LDAP servers accept it and allow a simple login

• Portal: Load the JS resources for apps sequentially, because if there is more than one bundle they typically depend on each other

• LDAP Security Provider: Add all roles from the groupToRoleMapping and userToRoleMapping to the known roles to improve the autocomplete in the Admin UI

• Simple Security Provider: Add all roles from users.json to the known roles, to improve the autocomplete in the Admin UI