README
Introduction
Window Rivet is a zero-dependency module for transparent bidirectional communication across origins by fastening separate domains together using the Window object.
Documentation
Usage
One-way messaging between a privileged and non-privileged domain:
Domain A
const Rivet = require('@cidekar/rivet')
// New-up an instance if rivet
const rivet = new rivet()
// New-up the dispatcher
const dispatcher = new rivet.dispatcher();
// Dispatch single message from domain A.
dispatcher.message({
event: 'confirm',
message: 'Did you get my message?',
});
Domain B
const Rivet = require('@cidekar/rivet')
// New-up an instance if rivet
const rivet = new rivet()
// New-up the receiver
const receiver = new rivet.receiver();
// Receive a message on domain B.
receiver.listen('confirm', function(event){
//... Handle message
// event.messageEvent.data
});
Bidirectional messaging between a privileged and non-privileged domain:
Domain A
const Rivet = require('@cidekar/rivet')
// New-up an instance if rivet
const rivet = new rivet()
// New-up the dispatcher
const dispatcher = new rivet.dispatcher();
// Receive a message from domain B.
dispatcher.listen('response', function (event) {
//... handle the reply
// event.messageEvent.data
})
// Dispatch a message from domain A.
dispatcher.message({
event: 'confirm',
message: 'Did you get my message?',
});
Domain B
const Rivet = require('@cidekar/rivet')
// New-up an instance of rivet
const rivet = new rivet()
// New-up the receiver
const receiver = new rivet.receiver();
// A Simple reply function
function reply(response, event) {
receiver.message(response, event)
}
// Receive a message from domain A and reply.
receiver.listen('confirm', function(event){
reply({
event: 'response',
message: 'Yes. Thank you for asking!',
})
});
What version should a developer use?
Window Rivet is compiled for use in the browser and Node. To find the right version for your use case take a look at the build files definition table.
API
Configuration
Name | Argument | Default | Description |
---|---|---|---|
Dispatcher Origin | dispatcherOrigin |
["*"] |
The origin of Dispatcher component. |
Receiver Origin | receiverOrigin |
["*"] |
The origin of Receiver component. |
Warning Origin | warningOrigin |
true |
Display configuration waring in console |
Silent | silent |
false |
Display all cross-origin communication between Window objects in console. |
Components
Type | Newable | Description |
---|---|---|
Dispatcher | X | Create, serialize, and transfer messages. |
Receiver | X | Listen, validate, and handel messages. |
Methods
Name | Argument | Description |
---|---|---|
Message | { event: string, message: string, array, or object } |
Send a message to a component. |
Listen | { event: string, message: string, array, or object } |
Listen for a message from a component. |
Hooks
Type | Life Cycle | Description |
---|---|---|
Created | Register and Ready | System startup, prepare to enter, record, and processed a configuration. |
Mounted | Register and Ready | System has completely processed the configuration and ready for communication. |
Dispatcher | Boot, Register, and Ready | The dispatcher is booted, registered into the system, and ready for communication. |
Receiver | Boot, Register, and Ready | The dispatcher is booted, registered into the system, and ready for communication. |
System Life Cycle
- Kernel is loaded executing a thin bootloader layer initializing the system.
- System hooks are created, components set into a ready state, and system is mounted to a domain.
- A new instance of the Dispatcher and Receiver are created returning methods for bidirectional communication bound to each domain Window object.
- A Dispatcher message is serialized and sent to a Receiver.
- The Receiver receives the message and validates the origin and shape.
- Authorized messages are synchronously dispatched to the Window firing a callback function with the message from the Dispatcher.
- The Receiver sends a reply to the Dispatcher with a serialized message.
Documentation
View our documentation by running the TypeDoc generator:
$ yarn docs
License
Copyright 2019 Cidekar, LLC. All rights reserved.