@cardinalapps/bridge v1.0.4

Bridge.js

To see Bridge.js in action, check out the Cardinal apps.

Bridge.js is an ES6 JavaScript library for client Cardinal apps that enables communication with the rest of the Cardinal systems.

There are three main ways for the Bridge to send and recieve messages: over HTTP, WebSockets, and IPC.

API Reference

A reference of all public Bridge.js methods is available in DOCS.md.

Initialization

After importing Bridge.js, a single instance of Bridge is designed to live in window. It will serve as the overlord for all external communcation for this app, and no app should ever have more than one Bridge instance running at a time.

Your global Bridge instance should then be initialized with each type of communication that needs to be used.

import { Bridge } from 'Bridge.js'

// init singleton
window.Bridge = new Bridge()

// establish IPC connection
await window.Bridge.init('ipc')

// establish HTTP connection
await window.Bridge.init('http', {
  'scheme': 'http://',
  'host': '192.168.0.2',
  'port': 3080
})

// establish WebSocket connection
await window.Bridge.init('ws', {
  'scheme': 'ws://',
  'host': '192.168.0.2',
  'port': 3081
})

If any of the init() calls throw an error, the connection failed and the user should be shown the connection screen. It's usually just because the server isn't running.

The server will always instantly send the client its connection ID over the connection-id channel once a connection is established. The Bridge handles this automatically.

Communicating Over HTTP

The bulk of the data that gets sent between the server and the client is over HTTP. The Cardinal Server app is designed to receive requests at the /api endpoint. The Bridge automatically prepends /api to routes.

Requests can easily be sent with any method, and body data can be added.

// a GET request
let response = await Bridge.httpApi('/playlist/2')

// a POST request
let response = await Bridge.httpApi('/artist/1831', 'POST', {
  'name': 'Bon Iver'
})

The httpApi() method always returns an object with meta about the request itself. Stringified object responses will automatically be converted to an Object.

// example of a successful request
{
  "status": 200,
  "statusRange": 2,
  "response": [String] || [Object],
  "event": [Object]
}

// example of a failed request
{
  "status": 400,
  "statusRange": 4,
  "response": [String] || [Object],
  "event": [Object]
}

Note that at this point, Cardinal apps are designed for local area network usage only, and do not support SSL. Do not run Cardinal Server at a publically accessible location.

Communicating Over WebSockets

The Bridge wraps the native browser WebSocket object with functions that act similarily to how Electron IPC communication works. Notably, it introduces the concept of channels to WebSockets.

// listen on a certain channel (in a web component)
Bridge.wsListen('announce', (payload) => {
  console.log('Server sent data on channel "announce":', payload)
})

// send a message to the server
Bridge.wsSay('heartbeat', {
  'timestamp': Date.now()
  'status': 'OK'
})

Note that there is no WebSocket equivalent for the IPC method Bridge.ipcAsk().

Communicating Over IPC

The Bridge is designed to allow easy communication with the Electron main process using IPC. Of course, the client must be running in an Electron BrowserWindow, and the client can only ever communicate with its main process.

There are many convenient IPC handlers that Cardinal renderers can use, but always use a HTTP or WebSocket approach when possible to avoid features being dependent on Electron.

// get strings from the main process
let strings = await Bridge.ipcAsk('get-i18n')

// write to the database
let updated = await Bridge.ipcAsk('set-option', 'color', 'blue')

// listen for messages from the main process
Bridge.ipcListen('main-to-renderer', (message) => {
  console.log(message)
})

License

Uses the GPLv3 software license.