futoin-invoker

v2.4.9

Published

2 years ago

Transparently, efficiently and securely invoke remote or local service methods with strict API definition for Node and Browser

Downloads

0High
0Medium
0Low

andvgal

futoin async rpc orb communication distributed browser webpack

Stability: 3 - Stable

About

Documentation --> FutoIn Guide.

FutoIn Invoker is request initiating part in FutoIn microservice concept. It invokes a FutoIn interface method as described in FTN3: FutoIn Interface Definition. Invoker is not necessary a client - e.g. server may initiate request for callback to client.

Unlike HTTP REST API, FutoIn perfectly fits for "all-in-one" process model with efficient internal calls. Invoker is heavily optimized to reliably process input and output data checks.

Strict FutoIn interface (iface) definition and transport protocol is defined in FTN3 spec mentioned above. As it is based on JSON, both client and server can be implemented in a few minutes almost in any technology. However, Invoker and Executor concept provide significant benefits for efficiency, reliability and error control.

The core of invoker is CCM - Connection and Credentials Manager. It has the following advantages:

A single place to configure & hold sensitive data (like credentials)
Transparent connection management (no need for special connect/request/response/disconnect logic)
Efficient use of communications (keep-alive, persistent WebSockets channels, channel-based instead of message-based security, etc.)
Inversion of Control / Dependency Injection - implementations are referenced by static names like "mymodule.some.service" in code. The rest is hidden in CCM configuration.
Easy HMAC-based message signature and user authentication
Security enforcement
CCM-wide request limit zones with both requests/period and max simultaneous limits

The primary communication channel is WebSockets. Large raw data upload and download is also supported through automatic fallback to HTTP(S).

SimpleCCM - a light version without heavy processing of iface definition (ideal for browser).
AdvancedCCM - full featured CCM (extends SimpleCCM).

Communication methods:

HTTP/HTTPS - remote calls
WS/WSS - WebSockets remote calls with bi-directional sockets
HTML5 Web Messaging - same- and cross-origin local calls inside Browser through window.postMessage() API
Same Process - optimized for single instance deployment

Message coding formats:

JSON - default and mandatory
MessagePack (MPCK) - default for interfaces with BinaryData constraint
CBOR - also available, but shows 10x worse performance compared to MessagePack

Note: Invoker and Executor are platform/technology-neutral concepts. The implementation is already available in JS and PHP.

Reference implementation of:

FTN7: FutoIn Invoker Concept
Version: 1.7

FTN3: FutoIn Interface Definition
Version: 1.9

FTN3.1: FutoIn Interface - Common Types
Version: 1.0

FTN5: FutoIn HTTP integration
Version: 1.3

FTN9: FutoIn Interface - AuditLog
Version: 1.0 (client)

FTN14: FutoIn Cache
Version: 1.0 (client)

FTN4: FutoIn Interface - Ping-Pong
Version: 1.0 (client)

Spec: FTN7: Interface Invoker Concept v1.x
Spec: FTN3: FutoIn Interface Definition v1.x
Spec: FTN3.1: FutoIn Interface - Common Types v1.x
Spec: FTN5: FutoIn HTTP integration v1.x
Spec: FTN9: FutoIn Interface - AuditLog v1.x
Spec: FTN14: FutoIn Cache v1.x
Spec: FTN4: FutoIn Interface - Ping-Pong v1.x

Author: Andrey Galkin

Documentation --> FutoIn Guide

Installation for Node.js

Command line:

$ npm install futoin-invoker --save

$ yarn add futoin-invoker

Hint: checkout FutoIn CID for all tools setup.

All public classes can be accessed through module:

const AdvancedCCM = require('futoin-invoker').AdvancedCCM;

or included modular way, e.g.:

const AdvancedCCM = require('futoin-invoker/AdvancedCCM');

Browser installation

Pre-built ES5 CJS modules are available under es5/. These modules can be used with webpack without transpiler - default "browser" entry point points to ES5 version.

Webpack dists are also available under dist/ folder, but their usage should be limited to sites without build process.

Warning: check AsyncSteps and AsyncEvent polyfill for older browsers.

The following globals are available:

SimpleCCM - global reference to futoin-invoker.SimpleCCM class
AdvancedCCM - global reference to futoin-invoker.AdvancedCCM class
futoin.Invoker - global reference to futoin-invoker module

Examples

NOTE: more complex examples should be found in futoin-executor

Call remote function with SimpleCCM

var async_steps = require( 'futoin-asyncsteps' );
var SimpleCCM = require( 'futoin-invoker/SimpleCCM' );

// Initalize CCM, no configuration is required
var ccm = new SimpleCCM();

async_steps()
.add(
    function( as ){
        // Register interfaces without loading their specs
        ccm.register( as, 'localone', 'some.iface:1.0',
                      'https://localhost/some/path' );
        ccm.register( as, 'localtwo', 'other.iface:1.0',
                      'https://localhost/some/path',
                      'user:pass' ); // optional credentials

        as.add( function( as ){
            // Get NativeIface representation of remote interface
            // after registration is complete
            var localone = ccm.iface( 'localone' );
            var localtwo = ccm.iface( 'localtwo' );
            
            // SimpleCCM is not aware of available functions.
            // It is the only way to perform a call.
            localone.call( as, 'somefunc', {
                arg1 : 1,
                arg2 : 'abc',
                arg3 : true,
            } );
            
            as.add( function( as, res ){
                // As function prototype is not know
                // all invalid HTTP 200 responses may
                // get returned as "raw data" in res
                // parameter.
                console.log( res.result1, res.result2 );
            } );
        } );
    },
    function( as, err )
    {
        console.log( err + ': ' + as.state.error_info );
        console.log( as.state.last_exception.stack );
    }
)
.execute();

Call remote function with AdvancedCCM

var async_steps = require( 'futoin-asyncsteps' );
var invoker = require( 'futoin-invoker' );

// Define interface, which should normally be put into 
// file named "some.iface-1.0-iface.json" and put into
// a folder added to the "specDirs" option.
var some_iface_v1_0 = {
    "iface" : "some.iface",
    "version" : "1.0",
    "ftn3rev" : "1.1",
    "funcs" : {
        "somefunc" : {
            "params" : {
                "arg1" : {
                    "type" : "integer"
                },
                "arg2" : {
                    "type" : "string"
                },
                "arg3" : {
                    "type" : "boolean"
                }
            },
            "result" : {
                "result1" : {
                    "type" : "number"
                },
                "result2" : {
                    "type" : "any"
                }
            },
            "throws" : [
                "MyError"
            ]
        }
    },
    "requires" : [
        "SecureChannel",
        "AllowAnonymous"
    ]
};

var other_iface_v1_0 = {
    "iface" : "other.iface",
    "version" : "1.0",
    "ftn3rev" : "1.1"
}

// Initialize CCM. We provide interface definitions directly
var ccm = new invoker.AdvancedCCM({
    specDirs : [ __dirname + '/specs', some_iface_v1_0, other_iface_v1_0 ]
});

// AsyncSteps processing is required
async_steps()
.add(
    function( as ){
        // Register interfaces - it is done only once
        ccm.register( as, 'localone',
                      'some.iface:1.0', 'https://localhost/some/path' );
        ccm.register( as, 'localtwo',
                      'other.iface:1.0', 'https://localhost/some/path',
                      'user:pass' ); // optional credentials

        as.add( function( as ){
            // Get NativeIface representation of remote interface
            // after registration is complete
            var localone = ccm.iface( 'localone' );
            var localtwo = ccm.iface( 'localtwo' );
            
            localone.somefunc( as, 1, 'abc', true );
            
            as.add( function( as, res ){
                console.log( res.result1, res.result2 );
            } );
        } );
    },
    function( as, err )
    {
        console.log( err + ': ' + as.state.error_info );
        console.log( as.state.last_exception.stack );
    }
)
.execute();

API documentation

The concept is described in FutoIn specification: FTN7: Interface Invoker Concept v1.x

Modules

Classes

Members

futoin-invoker

AdvancedCCM ⇐ SimpleCCM

Advanced CCM - Reference Implementation

Kind: global class
Extends: SimpleCCM
See

FTN7: FutoIn Invoker Concept
AdvancedCCMOptions

AdvancedCCM ⇐ SimpleCCM
- new AdvancedCCM(options)
- .register(as, name, ifacever, endpoint, [credentials], [options])
- .iface(name) ⇒ NativeInterface
- .unRegister(name)
- .defense() ⇒ object
- .log() ⇒ object
- .cache([bucket]) ⇒ object
- .assertIface(name, ifacever)
- .alias(name, alias)
- .close()
- .limitZone(name, options)
- "register"
- "unregister"
- "close"

new AdvancedCCM(options)

| Param | Type | Description | | --- | --- | --- | | options | object | see AdvancedCCMOptions |

advancedCCM.register(as, name, ifacever, endpoint, [credentials], [options])

Kind: instance method of AdvancedCCM
Overrides: register
Emits: register

| Param | Type | Description | | --- | --- | --- | | as | AsyncSteps | AsyncSteps instance as registration may be waiting for external resources | | name | string | unique identifier in scope of CCM instance | | ifacever | string | interface identifier and its version separated by colon | | endpoint | string | URI OR any other resource identifier of function( ccmimpl, info ) returning iface implementing peer, accepted by CCM implementation OR instance of Executor | | [credentials] | string | optional, authentication credentials: 'master' - enable MasterService authentication logic (Advanced CCM only) '{user}:{clear-text-password}' - send as is in the 'sec' section NOTE: some more reserved words and/or patterns can appear in the future | | [options] | object | fine tune global CCM options per endpoint |

advancedCCM.iface(name) ⇒ NativeInterface

Get native interface wrapper for invocation of iface methods

Kind: instance method of AdvancedCCM
Overrides: iface
Returns: NativeInterface - - native interface

| Param | Type | Description | | --- | --- | --- | | name | string | see register() |

advancedCCM.unRegister(name)

Unregister previously registered interface (should not be used, unless really needed)

Kind: instance method of AdvancedCCM
Overrides: unRegister
Emits: unregister

| Param | Type | Description | | --- | --- | --- | | name | string | see register() |

advancedCCM.defense() ⇒ object

Shortcut to iface( "#defense" )

Kind: instance method of AdvancedCCM
Overrides: defense
Returns: object - native defense interface

advancedCCM.log() ⇒ object

Returns extended API interface as defined in FTN9 IF AuditLogService

Kind: instance method of AdvancedCCM
Overrides: log
Returns: object - FTN9 native face

advancedCCM.cache([bucket]) ⇒ object

Returns extended API interface as defined in [FTN14 Cache][]

Kind: instance method of AdvancedCCM
Overrides: cache
Returns: object - FTN14 native face

| Param | Type | Default | Description | | --- | --- | --- | --- | | [bucket] | string | "default" | cache bucket name |

advancedCCM.assertIface(name, ifacever)

Assert that interface registered by name matches major version and minor is not less than required. This function must generate fatal error and forbid any further execution

Kind: instance method of AdvancedCCM
Overrides: assertIface

| Param | Type | Description | | --- | --- | --- | | name | string | unique identifier in scope of CCM instance | | ifacever | string | interface identifier and its version separated by colon |

advancedCCM.alias(name, alias)

Alias interface name with another name

Kind: instance method of AdvancedCCM
Overrides: alias
Emits: register

| Param | Type | Description | | --- | --- | --- | | name | string | unique identifier in scope of CCM instance | | alias | string | alternative name for registered interface |

advancedCCM.close()

Shutdown CCM (close all active comms)

Kind: instance method of AdvancedCCM
Overrides: close
Emits: close

advancedCCM.limitZone(name, options)

Configure named AsyncSteps Limiter instance

Kind: instance method of AdvancedCCM
Overrides: limitZone

| Param | Type | Description | | --- | --- | --- | | name | string | zone name | | options | object | options to pass to Limiter c-tor |

"register"

CCM regiser event. Fired on new interface registration. ( name, ifacever, info )

Kind: event emitted by AdvancedCCM
Overrides: register

"unregister"

CCM regiser event. Fired on interface unregistration. ( name, info )

Kind: event emitted by AdvancedCCM
Overrides: unregister

"close"

CCM close event. Fired on CCM shutdown.

Kind: event emitted by AdvancedCCM
Overrides: close

CacheFace ⇐ NativeIface

Cache Native interface

NOTE: it is not directly available in Invoker module interface, include separately

Kind: global class
Extends: NativeIface

CacheFace ⇐ NativeIface

new CacheFace(_ccm, info)

| Param | Type | Description | | --- | --- | --- | | _ccm | SimpleCCM | CCM instance | | info | object | internal info |

cacheFace.getOrSet(as, key_prefix, callable, params, ttl_ms)

Get or Set cached value

NOTE: the actual cache key is formed with concatenation of key_prefix and join of params values

Kind: instance method of CacheFace

| Param | Type | Description | | --- | --- | --- | | as | AsyncSteps | step interface | | key_prefix | string | unique key prefix | | callable | function | func( as, params.. ) - a callable which is called to generated value on cache miss | | params | Array | parameters to be passed to callable | | ttl_ms | integer | time to live in ms to use, if value is set on cache miss |

cacheFace.ifaceInfo() ⇒ InterfaceInfo

Get interface info

Kind: instance method of CacheFace
Overrides: ifaceInfo
Returns: InterfaceInfo - - interface info

cacheFace.bindDerivedKey(as)

Results with DerivedKeyAccessor through as.success()

Kind: instance method of CacheFace
Overrides: bindDerivedKey

| Param | Type | Description | | --- | --- | --- | | as | AsyncSteps | step interface |

"connect"

Fired when interface establishes connection.

Kind: event emitted by CacheFace
Overrides: connect

"disconnect"

Fired when interface connection is closed.

Kind: event emitted by CacheFace
Overrides: disconnect

"close"

Interface close event. Fired on interface unregistration.

Kind: event emitted by CacheFace
Overrides: close

"commError"

Interface communication error. Fired during call processing. ( error_info, rawreq )

Kind: event emitted by CacheFace
Overrides: commError

CacheFace.register(as, ccm, name, endpoint, [credentials], [options])

Cache Native interface registration helper

Kind: static method of CacheFace

| Param | Type | Default | Description | | --- | --- | --- | --- | | as | AsyncSteps | | step interface | | ccm | AdvancedCCM | | CCM instance | | name | string | | registration name for CCM | | endpoint | string | | endpoint URL | | [credentials] | * | | see CCM register() | | [options] | object | {} | registration options | | [options.version] | string | "1.0" | iface version | | [options.ttl_ms] | integer | 1000 | default TTL |

InterfaceInfo

FutoIn interface info

Kind: global class

InterfaceInfo
- new InterfaceInfo(raw_info)
- .name() ⇒ string
- .version() ⇒ string
- .inherits() ⇒ string
- .funcs() ⇒ object
- .constraints() ⇒ array

new InterfaceInfo(raw_info)

| Param | Type | Description | | --- | --- | --- | | raw_info | object | futoin spec as is |

interfaceInfo.name() ⇒ string

Get FutoIn interface name

Kind: instance method of InterfaceInfo
Returns: string - name

interfaceInfo.version() ⇒ string

Get FutoIn interface version

Kind: instance method of InterfaceInfo
Returns: string - version

interfaceInfo.inherits() ⇒ string

Get list of inherited interfaces starting from the most derived, may be null

Kind: instance method of InterfaceInfo
Returns: string - inherited interface name-ver

interfaceInfo.funcs() ⇒ object

Get list of available functions, may be null

Kind: instance method of InterfaceInfo
Returns: object - list of functions

interfaceInfo.constraints() ⇒ array

Get list of interface constraints, may be null

Kind: instance method of InterfaceInfo
Returns: array - list of constraints

LogFace ⇐ NativeIface

AuditLog Native interface

NOTE: it is not directly available Invoker module interface, include separately

Kind: global class
Extends: NativeIface

LogFace ⇐ NativeIface
- instance
- static