### Mashroom Server Quick Start

Source: https://github.com/nonblocking/mashroom/blob/master/README.md

This snippet provides the commands to clone the Mashroom Portal Quickstart repository, set up dependencies, and start the server. It's the fastest way to get a running Mashroom Server instance.

```bash
git clone https://github.com/nonblocking/mashroom-portal-quickstart
cd mashroom-portal-quickstart
npm run setup
npm start
```

--------------------------------

### Mashroom Server Development Setup

Source: https://github.com/nonblocking/mashroom/blob/master/README.md

Instructions for setting up a development environment for Mashroom Server, including cloning the repository, installing dependencies, and starting a test server. Requires Node.js >= 20.

```bash
git clone <repository_url>
cd <repository_directory>
npm run setup
cd packages/test/test-server1
npm start
```

--------------------------------

### Start Redis Test Server

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-session-provider-redis/test/test-session-redis/README.md

This command initiates the Redis test server environment defined in the docker-compose.yml file. Ensure Docker and Docker Compose are installed and configured.

```bash
docker-compose up
```

--------------------------------

### Start Keycloak with Docker Compose

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-security-provider-openid-connect/test/keycloak/README.md

This snippet shows the command to start the Keycloak service using Docker Compose. Ensure Docker is installed and running.

```bash
docker-compose up
```

--------------------------------

### Start RabbitMQ Test Server

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-session-provider-mongodb/test/test-session-mongodb/README.md

This command starts the RabbitMQ test server and its dependencies as defined in the docker-compose.yml file. Ensure Docker and Docker Compose are installed and configured.

```bash
docker-compose up
```

--------------------------------

### Start Qpid Test Server

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-messaging-external-provider-amqp/test/test-messaging-qpid/README.md

This command starts the Qpid test server using Docker Compose. Ensure Docker and Docker Compose are installed and configured.

```bash
docker-compose up
```

--------------------------------

### Starting Test Server 4

Source: https://github.com/nonblocking/mashroom/blob/master/packages/test/test-server4/README.md

Commands to start the Test Server 4 using Docker Compose and npm.

```bash
docker-compose up
npm start
```

--------------------------------

### Start Mosquitto Test Server

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-messaging-external-provider-mqtt/test/test-messaging-mosqitto/README.md

This snippet shows the command to start the Mosquitto MQTT test server using Docker Compose. Ensure Docker and Docker Compose are installed and the docker-compose.yml file is in the current directory.

```docker-compose
docker-compose up
```

--------------------------------

### Docker Compose Start

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-security-provider-openid-connect/test/openam/README.md

Starts the OpenAM services using Docker Compose. This is the initial step for setting up the environment.

```bash
docker-compose up
```

--------------------------------

### Start Reverse Proxy Script

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-vhost-path-mapper/test/test-proxy/README.md

Shell script to start the reverse proxy. Requires navigating to the test server directory, installing dependencies, and then executing the script.

```bash
cd  <repo-root>/packages/test/test-server1
npm install
npm start

cd <this folder>
./start.sh
```

--------------------------------

### Starting Test Server 5

Source: https://github.com/nonblocking/mashroom/blob/master/packages/test/test-server5/README.md

Commands to start the Test Server 5 project using Docker Compose and npm. This will launch the portal, reverse proxy, and CDN.

```bash
docker-compose up
npm start
```

--------------------------------

### Start RabbitMQ Test Server

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-messaging-external-provider-amqp/test/test-messaging-rabbitmq/README.md

This command starts the RabbitMQ test server and its dependencies as defined in the docker-compose.yml file. Ensure Docker and Docker Compose are installed and configured.

```bash
docker-compose up
```

--------------------------------

### Start Test Server 3

Source: https://github.com/nonblocking/mashroom/blob/master/packages/test/test-server3/README.md

Commands to start the Test Server 3 in development mode. This includes launching Docker Compose for external services and starting the Node.js application.

```bash
docker-compose up
npm start
```

--------------------------------

### Start Test Server 8

Source: https://github.com/nonblocking/mashroom/blob/master/packages/test/test-server8/README.md

Commands to start the test server in development mode. This involves running Docker Compose for external services and then starting the Node.js application.

```bash
docker-compose up
npm start
```

--------------------------------

### Start Grafana and Prometheus

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-monitoring-prometheus-exporter/test/grafana-test/README.md

This command starts the Grafana and Prometheus services using Docker Compose. Ensure you have Docker and Docker Compose installed and configured.

```bash
docker-compose up
```

--------------------------------

### Start Portal IFrame App

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal-iframe-app/src/index.html

Initializes and starts the Portal IFrame App. It waits for the DOM to be fully loaded, then retrieves the application container element and sets up the portal application configuration and services. Finally, it calls the `startPortalIFrameApp` function with the prepared arguments.

```javascript
(function () {
  document.addEventListener("DOMContentLoaded", function () {
    var element = document.getElementById("app-container");
    var portalAppConfig = {
      url: "/test-page.html",
      width: '100%',
      defaultHeight: "80vh"
    };
    var portalAppSetup = {
      lang: 'en',
      appConfig: portalAppConfig
    };
    var portalClientServices = {};
    window.startPortalIFrameApp(element, portalAppSetup, portalClientServices);
  });
})();
```

--------------------------------

### Start Test Server Locally

Source: https://github.com/nonblocking/mashroom/blob/master/packages/test/test-server6/README.md

Command to start the test server locally. Assumes Node.js environment. Opens the portal at http://localhost:5050 and http://localhost:5050/portal.

```bash
npm start
```

--------------------------------

### Get CDN Host Example

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-cdn/README.md

Demonstrates how to use the MashroomCDNService to retrieve a CDN host and construct a resource URL.

```ts
import type {MashroomCDNService} from '@mashroom/mashroom-cdn/type-definitions';

export default async (req: Request, res: Response) => {

    const cdnService: MashroomCDNService = req.pluginContext.services.cdn.service;

    const cdnHost = cdnService.getCDNHost();
    const resourceUrl = `${cdnHost}/<the-actual-path>`;

    // ..
};
```

--------------------------------

### Mashroom Portal Initialization

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal-app-gallery-app/src/index.html

Example of initializing the Mashroom Portal with an App Gallery App, demonstrating the startup process.

```javascript
(() => {
  const element = document.getElementById('mashroom-portal-container');
  const portalAppSetup = {
    // ... portal app setup configuration ...
  };
  const portalClientServices = {
    // ... portal client services configuration ...
  };
  window.startAppGalleryApp(element, portalAppSetup, portalClientServices);
})();
```

--------------------------------

### Complex Configuration Example

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal-remote-app-registry-k8s/README.md

An example showcasing a more complex configuration to select services based on multiple label selectors across namespaces.

```json
{
  "plugins": {
      "Mashroom Portal Remote App Kubernetes Background Job": {
          "k8sNamespacesLabelSelector": ["environment=development,tier=frontend"],
          "k8sNamespaces": null,
          "k8sServiceLabelSelector": ["microfrontend=true,channel!=alpha"]
        }
    }
}
```

--------------------------------

### Mashroom Storage Service Usage Example

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-storage/README.md

Demonstrates how to import and use the MashroomStorageService within a Mashroom Server request handler. It shows how to get a collection and perform find/findOne operations.

```ts
import type {MashroomStorageService} from '@mashroom/mashroom-storage/type-definitions';

export default async (req: Request, res: ExpressResponse) => {
    const storageService: MashroomStorageService = req.pluginContext.services.storage.service;

    const customerCollection = await storageService.getCollection('my-collection');

    const customer = await customerCollection.findOne({customerNr: 1234567});
    const customers = await customerCollection.find({ $and: [{ name: { $regex: 'jo.*' } }, { visits: { $gt: 10 } }], 20, 10, { visits: 'desc' });

    // ...
}
```

--------------------------------

### Start Mashroom Test Server

Source: https://github.com/nonblocking/mashroom/blob/master/packages/test/test-server1/README.md

Starts the Mashroom test server. This command initiates the server process, enabling development mode features like automatic recompilation and reloading.

```bash
npm start
```

--------------------------------

### User and Role Definitions (users.json)

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-security-provider-simple/README.md

Example structure for the users.json file, defining user credentials, roles, and optional data.

```json
{
    "$schema": "https://www.mashroom-server.com/schemas/mashroom-security-simple-provider-users.json",
    "users": [
        {
            "username": "admin",
            "displayName": "Administrator",
            "email": "xxxxx@xxxx.com",
            "pictureUrl": "xxxx",
            "passwordHash": "8c6976e5b5410415bde908bd4dee15dfb167a9c873fc4bb8a81f6f2ab448a918",
            "extraData": {
                "firstName": "John",
                "lastName": "Do"
            },
            "roles": [
                "Administrator"
            ],
            "secrets": {
                "token": "xxxxxxx"
            }
        },
        {
            "username": "john",
            "displayName": "John Do",
            "passwordHash": "96d9632f363564cc3032521409cf22a852f2032eec099ed5967c0d000cec607a",
            "roles": [
                "User",
                "PowerUser"
            ]
        }
    ]
}
```

--------------------------------

### Remote App Configuration Example

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal-remote-app-registry-k8s/README.md

Example of how to define a remote app in the plugin configuration, specifying resource roots and SSR initial HTML paths.

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

--------------------------------

### Start WebSocket Proxy Demo App

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal-demo-websocket-proxy-app/src/index.html

Initializes and starts the WebSocket proxy demo application. It sets up event listeners for DOMContentLoaded, configures WebSocket proxy paths, and initiates the application with provided services.

```javascript
(function () { document.addEventListener("DOMContentLoaded", function () { var element = document.getElementById("demo-app-container"); var portalAppConfig = { }; var portalAppSetup = { lang: 'en', proxyPaths: { 'echo': 'wss://echo.websocket.org/' }, appConfig: portalAppConfig }; var portalClientServices = { }; window.startWebSocketProxyDemoApp(element, portalAppSetup, portalClientServices); }); })();
```

--------------------------------

### Mashroom Portal WebApp JSON Configuration Example

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal/README.md

An example JSON configuration object for the Mashroom Portal WebApp plugin, demonstrating how to set various properties like path, default theme, authentication expiration, resource fetching timeouts, and server-side rendering options.

```json
{
    "plugins": {
        "Mashroom Portal WebApp": {
            "path": "/portal",
            "adminApp": "Mashroom Portal Admin App",
            "defaultTheme": "Mashroom Portal Default Theme",
            "defaultLayout": "Mashroom Portal Default Layouts 1 Column",
            "authenticationExpiration": {
              "warnBeforeExpirationSec": 60,
              "autoExtend": false,
              "onExpiration": {
                "strategy": "reload"
              }
            },
            "ignoreMissingAppsOnPages": false,
            "versionHashSalt": null,
            "resourceFetchConfig": {
                "fetchTimeoutMs": 3000,
                "httpMaxSocketsPerHost": 3,
                "httpRejectUnauthorized": true
            },
            "defaultProxyConfig": {
                "sendPermissionsHeader": false,
                "restrictToRoles": ["ROLE_X"]
            },
            "ssrConfig": {
                "ssrEnable": true,
                "renderTimoutMs": 2000,
                "cacheEnable": true,
                "cacheTTLSec": 300,
                "inlineStyles": true
            },
            "addDemoPages": true
        }
    }
}
```

--------------------------------

### Broker Configuration Examples

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-messaging-external-provider-amqp/README.md

Provides examples of broker-specific topic routing configurations for RabbitMQ, ActiveMQ, and Qpid Broker.

```json
"brokerTopicExchangePrefix": "/topic/",
"brokerTopicMatchAny": "#"
```

```json
"brokerTopicExchangePrefix": "topic://",
"brokerTopicMatchAny": ">"
```

```json
"brokerTopicExchangePrefix": "amq.topic/",
"brokerTopicMatchAny": "#"
```

--------------------------------

### Install Mashroom Portal Demo React App

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal-demo-react-app2/README.md

To use this demo app, you need to install it as a dependency in your Mashroom Server project. Ensure that node_modules/@mashroom is configured as a plugin path.

```bash
npm install @mashroom/mashroom-portal-demo-react-app
# or
yarn add @mashroom/mashroom-portal-demo-react-app
```

--------------------------------

### Load Composite Demo App

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal-demo-composite-app/src/index.html

Initializes and loads the demo composite application when the DOM is ready. It sets up application configuration and client services, then calls the `startCompositeDemoApp` function.

```javascript
(function () {
    document.addEventListener("DOMContentLoaded", function () {
        var element = document.getElementById("demo-composite-app-container");
        var portalAppConfig = { firstName: 'Michael' };
        var portalAppSetup = { lang: 'en', appConfig: portalAppConfig };
        var portalClientServices = {
            messageBus: {
                registerMessageInterceptor: function() {}
            },
            portalAppService: {
                loadedPortalApps: [],
                loadApp: function(hostElementId, name) {
                    document.getElementById(hostElementId).innerHTML = '<div>App loaded: ' + name + '</div>';
                    return Promise.resolve({ id: 'foo' });
                }
            }
        };
        window.startCompositeDemoApp(element, portalAppSetup, portalClientServices);
    });
})();
```

--------------------------------

### Start Test Server in Cluster Mode

Source: https://github.com/nonblocking/mashroom/blob/master/packages/test/test-server2/README.md

This command starts the test server in cluster mode using npm scripts. It requires PM2 to be installed as a prerequisite.

```javascript
npm run start-cluster
```

--------------------------------

### Mashroom Portal Initialization

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal-admin-app/src/index.html

Demonstrates how to initialize the Mashroom Portal application with a given DOM element, setup configuration, and client services.

```javascript
(() => {
    const element = document.getElementById('mashroom-portal-container');
    const portalAppSetup = {
        // Portal setup configuration
    };
    const portalClientServices = {
        getPage: function(pageId) { console.info('Get page called with: ', pageId); return Promise.resolve(); },
        updatePage: function(pageId, pageData) { console.info('Update page called with: ', pageId, pageData); return Promise.resolve(); },
        getPagePermittedRoles: function() { return Promise.resolve([ 'Role 2' ]); },
        updatePagePermittedRoles: function() { console.info('Update page permitted roles called with: ', arguments); return Promise.resolve(); },
        getCurrentSiteId: function() { return 'site1'; },
        getSite: function() { return Promise.resolve({ siteId: 'site1', title: { en: 'Default site' }, path: '/web', virtualHosts: null, defaultTheme: 'Theme 1', defaultLayout: 'Layout 1', pages: [ {pageId: 'page1', title: { en: 'Page 1' }, friendlyUrl: '/page1', hidden: false, subPages: [ {pageId: 'foo', title: { en: 'High Tech', de: 'Hochtechnologie' }, friendlyUrl: '/ht'}, {pageId: 'foo2', title: { en: 'High Tech 2' }, friendlyUrl: '/ht2'} ] }, {pageId: 'page2', title: 'Page 2', friendlyUrl: '/page2'} ] }); },
        addSite: function(site) { console.info('Add site called with: ', arguments); return Promise.resolve(Object.assign({}, site, { siteId: 'sdfsdfdsf' })); },
        updateSite: function() { console.info('Update site called with: ', arguments); return Promise.resolve(); },
        deleteSite: function() { console.info('Delete site called with: ', arguments); return Promise.resolve(); },
        getSitePermittedRoles: function() { return Promise.resolve(); },
        updateSitePermittedRoles: function(roles) { console.info('Update site permitted roles called with: ', arguments); return Promise.resolve(); },
    };
    window.startPortalAdminApp(element, portalAppSetup, portalClientServices);
})();
```

--------------------------------

### Usage Example

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-i18n/README.md

Demonstrates how to use the MashroomI18NService within a Mashroom Server plugin to get the current language and translate messages.

```ts
import type {MashroomI18NService} from '@mashroom/mashroom-i18n/type-definitions';

export default (req: Request, res: Response) => {
    const i18nService: MashroomI18NService = req.pluginContext.services.i18n.service;

    const currentLang = i18nService.getLanguage(req);
    const message =  i18nService.getMessage('username', 'de');
    // message will be 'Benutzernamen'

    // ...
}
```

--------------------------------

### Get CSRF Token Example

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-csrf-protection/README.md

Demonstrates how to retrieve the CSRF token using the MashroomCSRFService within a Mashroom Server plugin.

```typescript
import type {MashroomCacheControlService} from '@mashroom/mashroom-csrf-protection/type-definitions';

export default (req: Request, res: Response) => {

    const csrfService: MashroomCacheControlService = req.pluginContext.services.csrf.service;
    const token = csrfService.getCSRFToken(req);

    // ...
}
```

--------------------------------

### Mashroom Portal App User ExtraData Plugin Configuration

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal-app-user-extradata/README.md

This example shows how to configure the Mashroom Portal App User ExtraData plugin by adding it as a dependency in your Mashroom Server setup. Ensure that the plugin path is correctly configured in your Mashroom Server.

```typescript
import {IMashroomPortalAppUser} from '@mashroom/mashroom-portal/type';

// Assuming @mashroom/mashroom-portal-app-extradata is installed and configured as a plugin path

// In your Mashroom Server configuration (e.g., server.conf.ts):
export default {
  plugins: {
    // ... other plugin configurations
    dependencies: [
      '@mashroom/mashroom-portal-app-user-extradata'
    ]
  }
};

// Example of how the extraData might be available on the server user object
// This is typically handled by a security provider plugin.
interface ServerUserWithExtraData extends IMashroomPortalAppUser {
  extraData?: {
    phoneNumber?: string;
    department?: string;
  };
}

// The plugin will automatically copy properties from serverUser.extraData to portalAppUser.extraData
// For example, if serverUser.extraData.phoneNumber exists, it will be available as portalAppUser.extraData.phoneNumber

```

--------------------------------

### Demo React App 2 Config Editor Initialization

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal-demo-react-app2/test/editor/index.html

Initializes the configuration editor for the Demo React App 2. It sets up event listeners for DOMContentLoaded, defines the application's configuration and update logic, and then starts the editor with the specified container and setup.

```javascript
(function () {
  document.addEventListener("DOMContentLoaded", function () {
    var element = document.getElementById("demo-react-app-container");
    var editorTarget = {
      appId: "xx",
      pluginName: 'Mashroom Portal Demo React App 2',
      appConfig: {
        markdownMessage: 'This is simple React \*SPA\* that supports \*\*SSR\*\* and brings a custom config editor',
        pingButtonLabel: 'Send Ping'
      },
      updateAppConfig: (appConfig) => {
        console.info('New app config:', appConfig);
        alert('appConfig updated!');
      },
      close: () => {
        alert('closing editor!');
      },
    };
    var portalAppSetup = {
      lang: 'en',
      appConfig: {
        editorTarget,
      },
    };
    window.startReactDemoApp2ConfigEditor(element, portalAppSetup);
  });
})();
```

--------------------------------

### Initialize SolidJS Demo App

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal-demo-solidjs-app/src/index.html

This JavaScript code initializes the SolidJS demo application. It waits for the DOM to be fully loaded, sets up the application configuration including a message and button label, and then starts the application by calling `window.startSolidJSDemoApp` with the target element and configuration.

```javascript
(function () {
  document.addEventListener("DOMContentLoaded", function () {
    var element = document.getElementById("demo-solidjs-app-container");
    var portalAppConfig = {
      message: 'This is simple SolidJS based SPA that communicates with other Apps on the page via message bus',
      pingButtonLabel: 'Send Ping'
    };
    var portalAppSetup = {
      lang: 'en',
      appConfig: portalAppConfig
    };
    var portalClientServices = {
      messageBus: {
        publish: function() {},
        subscribe: function() {}
      }
    };
    window.startSolidJSDemoApp(element, portalAppSetup, portalClientServices);
  });
})();
```

--------------------------------

### Portal Admin Service - App Instance Management

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal-admin-app/src/index.html

Provides examples for managing application instances, including adding, updating, removing, and setting permissions for app instances.

```javascript
var portalClientServices = {
    portalAdminService: {
        getAppInstances: function() { return Promise.resolve([]); },
        addAppInstance: function(pluginName) { console.info('Add app instance called with: ', arguments); return Promise.resolve({ pluginName, instanceId: 'sdfsdfdsf' }); },
        updateAppInstance: function() { console.info('updateAppInstance() called with: ', arguments); return Promise.resolve(); },
        removeAppInstance: function() { console.info('Remove app instance called with: ', arguments); return Promise.resolve(); },
        getAppInstancePermittedRoles: function() { return Promise.resolve(['Role 1']); },
        updateAppInstancePermittedRoles: function() { console.info('Update app instance permitted roles called with: ', arguments); return Promise.resolve(); }
    }
};
```

--------------------------------

### Initialize Demo React App 2

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal-demo-react-app2/test/app/index.html

This snippet initializes the Demo React App 2. It waits for the DOM to be fully loaded, sets up the application's configuration including a markdown message and a button label, and then starts the React app using provided client services.

```javascript
(function () {
  document.addEventListener("DOMContentLoaded", function () {
    var element = document.getElementById("demo-react-app-container");
    var portalAppConfig = {
      markdownMessage: 'This is simple React \*SPA\* that supports \*\*SSR\*\* and brings a custom config editor',
      pingButtonLabel: 'Send Ping'
    };
    var portalAppSetup = {
      lang: 'en',
      appConfig: portalAppConfig
    };
    var portalClientServices = {
      messageBus: {
        publish: function() {},
        subscribe: function() {}
      }
    };
    window.startReactDemoApp2(element, portalAppSetup, portalClientServices);
  });
})();
```

--------------------------------

### Remote App Configuration Example

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal-remote-app-registry/README.md

Example of a remote app configuration within Mashroom Portal's plugin definition. It specifies resourcesRoot and ssrInitialHtmlPath for remote applications.

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

--------------------------------

### Kubernetes Prometheus Query Examples for Mashroom

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-monitoring-prometheus-exporter/README.md

Examples of Prometheus queries adapted for Kubernetes environments, showing how to aggregate metrics across pods and display metrics per pod.

```prometheus
sum(rate(mashroom_http_requests_total{namespace="my-namespace"}[5m]))
```

```prometheus
sum by (kubernetes_pod_name) (rate(mashroom_http_requests_total{namespace="my-namespace"}[5m]))
```

```prometheus
mashroom_sessions_total{namespace="my-namespace"} by (kubernetes_pod_name)
```

--------------------------------

### Mashroom Sandbox App Query Parameters

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal-sandbox-app/README.md

This section details the various query parameters supported by the Mashroom Sandbox App for configuring and controlling the loaded Portal App. These parameters allow for automated testing, preselection of apps, and passing specific configurations.

```javascript
sbAutoTest: Enables automated testing mode.
sbPreselectAppName: Preselects an app without starting it.
sbAppName: Specifies the name of the app to start automatically.
sbWidth: Sets the width of the app sandbox (default: 100%).
sbLang: Sets the language code passed to the app.
sbPermissions: Base64 encoded permissions object.
sbAppConfig: Base64 encoded app configuration object.
```

--------------------------------

### Mashroom Portal App Setup Language

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-docs-static/docs/mashroom_documentation.md

Illustrates how client-side portal applications can access the current locale provided during the portal app setup. This is useful for integrating with client-side i18n frameworks.

```ts
const bootstrap: MashroomPortalAppPluginBootstrapFunction = (portalAppHostElement, portalAppSetup, clientServices) => {
    const { lang } = portalAppSetup;
    // lang will be 'en' or 'fr' or whatever
    const { messageBus, portalAppService } = clientServices;
    // ...
};
```

--------------------------------

### Start Test Server (TypeScript)

Source: https://github.com/nonblocking/mashroom/blob/master/packages/test/test-server7/README.md

Commands to start the test server using either ts-node or a specific Node.js version (24.x or newer). This is the primary method for running the server locally.

```bash
npm run startTsNode
```

```bash
npm run startNode24
```

--------------------------------

### Mashroom Portal App Bootstrap with Proxy Usage

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-docs-static/docs/mashroom_documentation.md

Shows an example of a Mashroom Portal App's bootstrap function using the restProxyPaths provided by portalAppSetup to make proxied API calls.

```ts
const bootstrap: MashroomPortalAppPluginBootstrapFunction = (portalAppHostElement, portalAppSetup) => {
    const {lang, restProxyPaths} = portalAppSetup;

    fetch(`${restProxyPaths.myApi}/foo/bar?q=xxx`, {
        credentials: 'same-origin',
    }).then( /* ... */ );

    // ...
};
```

--------------------------------

### MashroomPortalAppSetup Interface

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal/README.md

Defines the structure of the portalAppSetup object passed to the bootstrap function, containing application configuration, proxy paths, language, user information, and more.

```typescript
export type MashroomPortalAppSetup = {
    readonly appId: string;
    readonly title: string | null | undefined;
    readonly proxyPaths: MashroomPortalProxyPaths;
    // Legacy, will be removed in Mashroom v3
    readonly restProxyPaths: MashroomPortalProxyPaths;
    readonly resourcesBasePath: string;
    readonly globalLaunchFunction: string;
    readonly lang: string;
    readonly user: MashroomPortalAppUser;
    readonly appConfig: MashroomPluginConfig;
}
```

--------------------------------

### Mashroom Memory Cache Provider Interface

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-memory-cache/README.md

Defines the interface for custom memory cache providers. This includes methods for core cache operations like get, set, delete, clear, and getting entry counts.

```APIDOC
MashroomMemoryCacheProvider:
  get(region: string, key: CacheKey): Promise<CacheValue | undefined>
    Get a cache entry from given region.
    Parameters:
      region: The cache region name.
      key: The cache key.
    Returns: The cached value or undefined if not found.

  set(region: string, key: CacheKey, value: CacheValue, ttlSec: number): Promise<void>
    Set a cache entry in given region.
    Parameters:
      region: The cache region name.
      key: The cache key.
      value: The value to cache.
      ttlSec: Time-to-live in seconds.

  del(region: string, key: CacheKey): Promise<void>
    Delete an entry in given region.
    Parameters:
      region: The cache region name.
      key: The cache key to delete.

  clear(region: string): Promise<void>
    Clear the entire region.
    Parameters:
      region: The cache region name to clear.

  getEntryCount(region: string): Promise<number | undefined>
    Get the number of entries in this region (if possible).
    Parameters:
      region: The cache region name.
    Returns: The number of entries or undefined if not supported.
```

--------------------------------

### Portal App Service - App Management

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-portal-admin-app/src/index.html

Shows how to retrieve a list of available applications, register listeners for app lifecycle events, and manage app loading/unloading.

```javascript
var portalClientServices = {
    portalAppService: {
        getAvailableApps: function() { return new Promise(function(resolve) { setTimeout(function() { resolve([
            { name: 'Mashroom Portal App 1', category: 'Demo' },
            { name: 'Mashroom Portal App 2', category: 'Category II' },
            { name: 'Mashroom Portal App 3' },
            { name: 'Mashroom Portal App 4', category: 'Demo', description: 'This is the description of App 4 and so on and so on' },
            { name: 'Mashroom Portal App 5', category: 'Demo' },
            { name: 'Mashroom Portal App 6', category: 'Category II', description: 'Another description with <strong>tags</strong> that will be escaped' },
            { name: 'Mashroom Portal App 7', category: 'Category II' },
            { name: 'Mashroom Portal App 8', category: 'Category III', description: 'App with tags', tags: ['findme', 'xxxx'] },
            { name: 'Mashroom Portal App 9' },
            { name: 'Hidden App', category: 'hidden' }
        ]); }, 250); }); },
        registerAppLoadedListener: function() { console.info('registerAppLoadedListener() called with: ', arguments); },
        registerAppAboutToUnloadListener: function() { console.info('registerAppAboutToUnloadListener() called with: ', arguments); },
        loadApp: function() { console.info('loadApp() called with: ', arguments); },
        unloadApp: function() { console.info('unloadApp() called with: ', arguments); },
        reloadApp: function() { console.info('reload() called with: ', arguments); },
        loadedPortalApps: [
            { id: '1000', pluginName: 'App 1', instanceId: 'app1', portalAppAreaId: 'area1', portalAppWrapperElement: document.getElementById("app1"), appConfig: { foo: 'app1' } },
            { id: '1001', pluginName: 'App 2', instanceId: 'app2', portalAppAreaId: 'area2', portalAppWrapperElement: document.getElementById("app2"), appConfig: { foo: 'app2' } },
            { id: '1002', pluginName: 'App 3', instanceId: 'app3', portalAppAreaId: 'area1', portalAppWrapperElement: document.getElementById("app3"), appConfig: { foo: 'app3' }, editorConfig: { editorPortalApp: 'My Custom Editor', } },
            { id: '1003', pluginName: 'Dynamically loaded app', instanceId: null, portalAppAreaId: 'area1', portalAppWrapperElement: document.getElementById("app4") }
        ]
    }
};
```

--------------------------------

### Prometheus Query Examples for Mashroom Metrics

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-monitoring-prometheus-exporter/README.md

A collection of example Prometheus queries to monitor various aspects of a Mashroom Server instance, including request rates, error rates, latency, resource usage, and plugin status.

```prometheus
sum(rate(mashroom_http_requests_total{service="Mashroom"}[5m]))
```

```prometheus
sum(rate(mashroom_http_requests_total{status="500", service="Mashroom"}[5m]))
```

```prometheus
histogram_quantile(0.95, sum(rate(mashroom_http_request_duration_seconds_bucket{service="Mashroom"}[5m])) by (le)) * 1000
```

```prometheus
nodejs_heap_size_total_bytes{service="Mashroom"} / 1024 / 1024
```

```prometheus
nodejs_heap_size_used_bytes{service="Mashroom"} / 1024 / 1024
```

```prometheus
avg(irate(process_cpu_seconds_total{service="Mashroom"}[5m])) * 100
```

```prometheus
histogram_quantile(0.95, sum(rate(nodejs_gc_duration_seconds_bucket[5m])) by (le))
```

```prometheus
mashroom_sessions_total{service="Mashroom"}
```

```prometheus
mashroom_http_proxy_http_pool_connections_active_total{service="Mashroom"}
    mashroom_http_proxy_https_pool_connections_active_total{service="Mashroom"}
    mashroom_http_proxy_ws_connections_active_total{service="Mashroom"}
```

```prometheus
mashroom_http_proxy_http_pool_connections_idle_total{service="Mashroom"}
    mashroom_http_proxy_https_pool_connections_idle_total{service="Mashroom"}
```

```prometheus
mashroom_plugins_total{service="Mashroom"}
```

```prometheus
mashroom_plugins_loaded_total{service="Mashroom"}
```

```prometheus
mashroom_plugins_error_total{service="Mashroom"}
```

```prometheus
mashroom_remote_app_endpoints_total{service="Mashroom"}
```

```prometheus
mashroom_remote_app_endpoints_error_total{service="Mashroom"}
```

```prometheus
mashroom_remote_app_k8s_services_total{service="Mashroom"}
```

```prometheus
mashroom_remote_app_k8s_services_error_total{service="Mashroom"}
```

```prometheus
mashroom_memory_cache_hit_ratio{service="Mashroom"}
```

```prometheus
mashroom_sessions_redis_nodes_connected{service="Mashroom"}
```

```prometheus
mashroom_memory_cache_redis_nodes_connected{service="Mashroom"}
```

```prometheus
mashroom_storage_mongodb_connected{service="Mashroom"}
```

```prometheus
mashroom_messaging_mqtt_connected{service="Mashroom"}
```

--------------------------------

### Mashroom Virtual Host Path Mapping Configuration

Source: https://github.com/nonblocking/mashroom/blob/master/packages/plugin-packages/mashroom-docs-static/docs/mashroom_documentation.md

Provides a JSON configuration example for the mashroom-vhost-path-mapper plugin. It shows how to map virtual hostnames and paths to internal routes.

```json
{
  "plugins": {
       "Mashroom VHost Path Mapper Middleware": {
           "hosts": {
              "www.my-company.com": {
                 "mapping": {
                    "/login": "/login",
                    "/": "/portal/site1"
                 }
              }
          }
       }
    }
}
```