Mashroom Portal Remote App Registry

Plugin for Mashroom Server, a Microfrontend Integration Platform.

This plugin adds a remote app registry to Mashroom Portal, which scans periodically a list of remote servers for Portal Apps. It expects the package.json and optionally an external plugin config file (default mashroom.json) to be exposed at /. It also expects a remote config in the plugin definition, like this:

 {
    "name": "My Single Page App",
    "remote": {
        "resourcesRoot": "/public",
         "ssrInitialHtmlPath": "/ssr"
    }
 }

You can find an example remote app here: Mashroom Demo Remote Portal App.

This plugin also comes with an Admin UI extension (/mashroom/admin/ext/remote-portal-apps) and a REST API to add and remote URL's. The Admin UI allows adding a URL temporary only for the current session.

Usage

If node_modules/@mashroom is configured as plugin path just add @mashroom/mashroom-portal-remote-app-registry as dependency.

You can override the default config in your Mashroom config file like this:

{
  "plugins": {
      "Mashroom Portal Remote App Background Job": {
          "cronSchedule": "0/1 * * * *",
          "socketTimeoutSec": 3,
          "registrationRefreshIntervalSec": 600,
          "unregisterAppsAfterScanErrors": -1
      },
      "Mashroom Portal Remote App Registry": {
          "remotePortalAppUrls": "./remotePortalApps.json"
      },
      "Mashroom Portal Remote App Registry Admin Webapp": {
          "showAddRemoteAppForm": true
      }
  }
}

• cronSchedule: The cron schedule for the background job that scans for new apps (Default: every minute)
• socketTimeoutSec: Socket timeout when trying to reach the remote app (Default: 3)
• registrationRefreshIntervalSec: Interval for refreshing known endpoints (Default: 600)
• unregisterAppsAfterScanErrors: Remove registered Apps of an endpoint if it cannot be reached for a number of scan intervals (Default: -1 which means: never remove)
• remotePortalAppUrls: Location of the config file with the remote URLs, relative to the server config (Default: ./remotePortalApps.json)
• showAddRemoteAppForm: Show the Add a new Remote Portal App Endpoint form in the Admin UI

The config file contains just a list of URLs:

{
    "$schema": "https://www.mashroom-server.com/schemas/mashroom-portal-remote-apps.json",
    "remotePortalApps": [
        "http://demo-remote-app.mashroom-server.com"
    ]
}

The Service can be used like this:

import type {MashroomPortalRemoteAppEndpointService} from '@mashroom/mashroom-portal-remote-app-registry/type-definitions';

export default async (req: Request, res: Response) => {
    const remoteAppService: MashroomPortalRemoteAppEndpointService = req.pluginContext.services.remotePortalAppEndpoint.service;

    const remoteApps = await remoteAppService.findAll();

    // ...
}

The REST API can be used like this:

Available at /portal-remote-app-registry/api. Methods:

• GET / : List of current URL's
• POST / : Add a new URL. Request body:

  {
     "url": "http://my-server.com/app1",
     "sessionOnly": false
  }

• DELETE /<url> : Delete given URL

Services

MashroomPortalRemoteAppEndpointService

The exposed service is accessible through pluginContext.services.remotePortalAppEndpoint.service

Interface:

export interface MashroomPortalRemoteAppEndpointService {
    /**
     * Register a new Remote App URL
     */
    registerRemoteAppUrl(url: string): Promise<void>;

    /**
     * Register a Remote App URL only for the current session (useful for testing)
     */
    synchronousRegisterRemoteAppUrlInSession(
        url: string,
        request: Request,
    ): Promise<void>;

    /**
     * Unregister a Remote App
     */
    unregisterRemoteAppUrl(url: string): Promise<void>;

    /**
     * Find Remote App by URL
     */
    findRemotePortalAppByUrl(
        url: string,
    ): Promise<RemotePortalAppEndpoint | null | undefined>;

    /**
     * Return all known Remote App endpoints
     */
    findAll(): Promise<Readonly<Array<RemotePortalAppEndpoint>>>;

    /**
     * Update an existing Remote App endpoint
     */
    updateRemotePortalAppEndpoint(
        remotePortalAppEndpoint: RemotePortalAppEndpoint,
    ): Promise<void>;

    /**
     * Refresh (fetch new metadata) from given endpoint
     */
    refreshEndpointRegistration(
        remotePortalAppEndpoint: RemotePortalAppEndpoint,
    ): Promise<void>;
}