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.

Apache License 2.0