@axa-ch/bifrost

Bifröst - a useful AEM integration framework

An integration framework for AEM. It's like a multicolored bridge between SPAs and AEM, hence the name from Nordic mythology. It will provide a localhost dev environment for SPAs and integration interfaces so that they can run inside a multi-SPA enviroment

Detailed documentation can be found here: https://confluence.axa.com/confluence/x/4samCw

Requirements

The client SPAs have to be able to deal with standard ES6 modules.

Authorisation

Bifrost offers three methods used under the hood to provide your POD's SPA with an Access Token:

• <iframe>
• Redirect
• XMLHttpRequest

Iframe

This method does not leave your POD's page, instead an authorization <iframe> is overlaid over the whole page and prompts the user for login.

Redirect

This method leaves your POD's page and redirects to an authorization page to prompt the user for login.

XMLHttpRequest

This method performs an asynchronous network request to authorise you POD.

Dev stuff

To start the mocking API, please run npm run api. The default port is 8080. If you need another port to be served, say port 3000, please run npm run api port=3000

Inactivity detection and auto-logout

Whereas login is used deliberately to provide your POD's SPA with an Access Token, logout sometimes happens involuntarily. This is due to requirements from AXA IT security. A number of user activities (scrolling, resizing, keyboard use, mouse use, touch) counts as user activity. The absence of such user activity for some time triggers inactivity detection. Another direct trigger of inactivity is leaving the active browser tab or window. When inactivity has been detected for some time, an automatic logout is performed, thus revoking the Access Token.

How can a POD be notified on logout

As per the previous section, automatic logout can happen after some time of inactivity. Sometimes a POD needs to react to such automatic logout, e.g. perhaps to invalidate its own legacy session tokens. The idea here is to subscribe to a bifrost store key that is characteristic for logged-in status, and get called back when that key is deleted as a result of logout. A code snippet illustrates this idea, using the key login in namespace common:

const { subscribe } = store; // bifrost store
subscribe(
  "login",
  "common",
  (_oldValue, reason) => {
    // does it look like we were just logged out?
    if (reason === "clean") {
      // yes, invalidate our own legacy session tokens, or similar
    }
  },
  true // true: get called back when that key-namespace combination is cleaned (which happens on logout)
);

Store

Bifrost implements an immutable store for communication between PODs. It is important to know that bifrost creates a deep clone when a new entry is added to the store and also when someone gets an entry from the store. This is important so that consumer and provider can change their value of type object without having object-reference-based side effects.

On every store entry, the entry is persisted to browser session storage. This feature is very handy if a page refresh happens on the store. Be aware that usage of browser local storage on the other hand is highly questionable and has to be double-checked with AXA IT security on a case-by-case basis. For this reason, bifrost does not provide an API persisting to browser local storage. If someone has the OK from security and can use local storage, please make a entry key that is unique, like so: [ANY-HASH]-key-name. Also, there must be an implementation that cleans local storage entries when the user revisits.

When publishing a value under a key:

• scalar and array values are overwritten in-place
• objects values are merged with their in-store value (to be discussed: should we keep this behavior?)

API under POD Menu Manager

The POD Menu Manager uses the bifrost store for communication. The API is described here: https://github.com/axa-ch/pod-menu-manager/blob/develop/DOCUMENTATION.md

Store API

When creating a new POD with the latest create-pod-app a mock store is available. In the devonly.js, which is created dynamically when running create-pod-app, you can mock external PODs. You will find more details in the devonly.js.

Every entry refers to a namespace. The default namespace is "common".

The store that is injected into the POD's options parameter (i.e. arg. 2 of the POD constructor) has the following API:

{
  // gets the value of an entry. if no namespace is passed, it gets it from common
  get ( entry: string [, namespace: string] ) : any,

  // adds a new value for an entry to a namespace in the store and calls all subscribers to the given entry in the same namespace. If persist is passed as "false", session Storage sync will be disabled
  publish ( entry: string, namespace: string, value: any, persist = true: boolean ) : boolean,

  // the callback function cb is called with the value for a given entry  when for the same entry / namespace combination a publish() has been executed
  // (if onClean is truthy, also when a clean() is executed)
  subscribe ( entry: string, namespace: string, cb: Function(value: any), onClean: boolean ) : boolean,

  // deletes the given entry in a namespace and its value from the store
  clean ( entry: string, namespace: string ) : boolean,

  // gets the value of an entry / namespace combination only if and when bifrost initialisation has completed
  getAsync ( entry: string, namespace: string, cb: Function(value: any) ) : boolean
}

Store Reserved Keys

The Bifrost store has provision for reserved keys that are not persisted. Given a store instance store, store.constructor.RESERVED_KEY is an object mapping reserved keys and their namespaces to custom functions. Such keys have their custom function executed upon store.get. Currently, the reserved key in-app in the namespace browser exists. store.get('in-app', 'browser') returns Boolean true iff Bifrost runs inside a Webhub-hosted web page that is configured to be executed in a in-app-browser web view.