@mashroom/mashroom

Mashroom Server

Mashroom Server is a Node.js based Microfrontend Integration Platform.

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

Changelog

2.5.0 (January 10, 2024)

• PM2 Metric Exporter: Allows it now to grab the OpenTelemetry metrics from PM2 workers via inter-process communication. Works similar to the approach previously implemented in the Prometheus Metric Exporter, only the serialization to Prometheus format is not done automatically

• Prometheus Metric Exporter: BREAKING CHANGE Removed the possibility to fetch prometheus metrics via inter-process communication within a PM2 cluster

• Metrics Collector: Uses now OpenTelemetry to gather and export metrics. Changes:

  • The collector service supports now asynchronous metric gathering via callback
  • It is possible now to directly use the OpenTelemetry API
  • The metrics are more accurate since the get measured during export

  Due to the API structure of OpenTelemetry there are also BREAKING CHANGES if you use the metrics collector service in your custom plugins:

  • Summary metrics are no longer available (use Prometheus histogram_quantile())
  • Aggregation is no longer integrated (use Prometheus aggregations)
  • Histograms: observe() has been renamed to record()
  • Counters exist now as synchronous version with only an inc() method and as an asynchronous version with a set() method
  • Gauges only exists synchronous version with a set() method now
  • Asynchronous metrics can be used in the service.addObservableCallback() callback, like so:

    const collectorService: MashroomMonitoringMetricsCollectorService = pluginContext.services.metrics.service;
  
    collectorService.addObservableCallback((asyncCollectorService) => {
        // ... somehow get the value to measure
        asyncCollectorService.gauge('http_pool_active_connections', 'HTTP Pool Active Connections').set(theValue);
    });
  

• Portal: Added metrics for remote resource requests (mashroom_portal_remote_resources_), like request count, error count and pool stats

• HTTP Proxy: The proxies do no longer automatically add x-forwarded- headers, because if you are using public APIs you might not want to disclose details of your internal network. Added a new config property createForwardedForHeaders to explicitly turn this feature on again. Also fixed the implementation, it takes now existing headers from reverse proxies into consideration and keeps them or extends them (which means x-forwarded-for contains now the IP address of the original client as well if there are reverse proxies).

• HTTP Proxy: Added metrics:

  • mashroom_http_proxy_requests_ws_connection_errors

  BREAKING CHANGE Renamed metrics:

  • mashroom_http_proxy_requests_connection_errors -> mashroom_http_proxy_requests_http_connection_errors
  • mashroom_http_proxy_requests_timeouts -> mashroom_http_proxy_requests_http_timeouts

• HTTP Proxy: The pool properties like poolMaxSocketsPerHost are now only for HTTP requests, WebSockets are handled separately and can be limited by wsMaxConnectionsPerHost

• HTTP Proxy: Added a new implementation based on the Node.js Stream API, which is also the default now. It deliberately does not use any 3rd party libraries, because those available (like request and node-http-server) are either deprecated or unmaintained. It uses the Stream.pipeline API introduced in Node.js 10 which has an improved error handling and cleanup mechanisms compared to the old Readable.pipe used by most libraries. The performance and resource usage characteristics are very similar to the node-http-proxy based implementation. According to our tests you can even expect slightly improved throughput. If you run into to troubles here you can switch back to the previous implementation like this:

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

• HTTP Proxy: Return HTTP 502 (Bad Gateway) instead of 503 if the target does not respond or is not available

• HTTP Proxy: Fixed target URL in metrics (protocol part contained two colons)

• Portal: Fetching and delivering App resources (js/css) improved

  • Fetching resources from remote servers and slow network devices has now a proper timeout set, because non-responding servers could potentially lead to a memory leak due to an increasing number of socket/file handles
  • The content-length header is now always correctly set
  • For remote resource 502 (Bad Gateway) or 504 (Gateway Timeout) is returned instead of just 500 if something goes wrong
  • Properties like timeout and max sockets can now be set like this in the server config:

     "Mashroom Portal WebApp": {
       "resourceFetchConfig": {
         "fetchTimeoutMs": 3000,
         "httpMaxSocketsPerHost": 10,
         "httpRejectUnauthorized": true
       }
     }
    

• mashroom-utils refactoring: Added an index file that should be used exclusively to import utils BREAKING CHANGE: If you have used mashroom-utils in your custom plugins you have to change the imports

• LDAP Security Provider: Fixed escaping of special characters in the DN. Didn't work if the same special character occurred multiple times.

• Dropped support for Node.js 16 - required is now >= 18

• All 3rd party libraries upgrades and switched to npm workspaces for dependency management BREAKING CHANGE: The request.session type no longer accept any property, you have to declare your session properties like this now:

    declare module 'express-session' {
      interface SessionData {
        foo?: string;
      }
    }
  

• File Storage: Performance improvements:

  • It polls for external changes to the DB file every checkExternalChangePeriodMs instead with every access. This will reduce the CPU load slightly. Default value of checkExternalChangePeriodMs is now 100, but you can increase it further if you run a single server, the config is readonly or performance is more important than consistency
  • The DB file will no longer be reloaded periodically, but only if the modified timestamp of the DB file changes

• HTTP Proxy: fixed deprecated API usages