futoin-invoker

Stability: 2 - Unstable

WARNING

This project is in active development and is not feature-complete yet, but is already mature enough. The documentation of this specific implementation is not complete either.

FutoIn reference implementation

Reference implementation of:

FTN7: FutoIn Invoker Concept
Version: 1.3

FTN3: FutoIn Interface Definition
Version: 1.1

FTN5: FutoIn HTTP integration
Version: 1.1

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

FTN14: FutoIn Cache
Version: 1.0 (client)

• Spec: FTN7: Interface Invoker Concept v1.x
• Spec: FTN3: FutoIn Interface Definition v1.x
• Spec: FTN5: FutoIn HTTP integration v1.x
• Spec: FTN9: FutoIn Interface - AuditLog v1.x
• Spec: FTN14: FutoIn Cache v1.x

Web Site

About

FutoIn Invoker is a peer which initiates a request - invokes a FutoIn interface method as described in FTN3: FutoIn Interface Definition. It is not necessary a client - e.g. server may initiate request for event delivery to client.

The method can be implemented locally or remotely - it is transparent to invoking code. A similar concept can be found in CORBA and other more heavy request brokers.

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.
• Security enforcement

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

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

Installation for Node.js

Command line:

$ npm install futoin-invoker --save

Installation for Browser

$ bower install futoin-invoker --save

Please note that browser build is available under in dist/ folder in sources generated with pure-sjc. It depends on lodash.

Note: there are the following globals 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

TODO

API documentation

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

#Index

Modules

• futoin-invoker
  • class: futoin-invoker.SimpleCCM
    • new futoin-invoker.SimpleCCM([options])
  • class: futoin-invoker.AdvancedCCM
    • new futoin-invoker.AdvancedCCM()
  • class: futoin-invoker.FutoInError
    • new futoin-invoker.FutoInError()
  • class: futoin-invoker.NativeIface
    • new futoin-invoker.NativeIface()
  • class: futoin-invoker.InterfaceInfo
    • new futoin-invoker.InterfaceInfo()

Classes

• class: CacheFace
  • new CacheFace()
  • CacheFace.ifacespec
  • CacheFace.register()
  • cacheFace.getOrSet(as, key_prefix, callable, params, ttl)
• class: LogFace
  • new LogFace()
  • LogFace.ifacespec
  • LogFace.register()
  • logFace.msg(lvl, txt)
  • logFace.msg(lvl, txt, data)
  • logFace.debug(txt)
  • logFace.info(txt)
  • logFace.warn(txt)
  • logFace.error(txt)
  • logFace.security(txt)
  • const: LogFace.LVL_DEBUG
  • const: LogFace.LVL_INFO
  • const: LogFace.LVL_WARN
  • const: LogFace.LVL_ERROR
  • const: LogFace.LVL_SECURITY
• class: InterfaceInfo
  • new InterfaceInfo()
  • interfaceInfo.name()
  • interfaceInfo.version()
  • interfaceInfo.inherits()
  • interfaceInfo.funcs()
  • interfaceInfo.constraints()
• class: NativeIface
  • new NativeIface()
  • nativeIface.call(as, name, params, upload_data, [download_stream], [timeout])
  • nativeIface.call()
  • nativeIface.bindDerivedKey()
• class: spectools
  • new spectools()
  • spectools.loadIface(as, info, specdirs)
  • spectools.parseIface(as, info, specdirs, raw_spec)
  • spectools.checkConsistency(as, info)
  • spectools.checkType(info, type, val)
  • spectools.checkParameterType(as, info, funcname, varname, value)
  • spectools.checkResultType(as, info, funcname, varname, value)
  • const: spectools.standard_errors

Members

• SimpleCCM
  • SimpleCCM.OPT_COMM_CONFIG_CB
  • const: SimpleCCM.OPT_CALL_TIMEOUT_MS
  • const: SimpleCCM.OPT_PROD_MODE
  • const: SimpleCCM.OPT_SPEC_DIRS
  • const: SimpleCCM.OPT_TARGET_ORIGIN
  • const: SimpleCCM.OPT_RETRY_COUNT
  • const: SimpleCCM.SAFE_PAYLOAD_LIMIT
  • const: SimpleCCM.SVC_RESOLVER
  • const: SimpleCCM.SVC_AUTH
  • const: SimpleCCM.SVC_DEFENSE
  • const: SimpleCCM.SVC_ACL
  • const: SimpleCCM.SVC_LOG
  • const: SimpleCCM.SVC_CACHE_
• AdvancedCCM
  • const: AdvancedCCM.OPT_SPEC_DIRS
• Invoker
• FutoInInvoker

#futoin-invoker Members

• futoin-invoker
  • class: futoin-invoker.SimpleCCM
    • new futoin-invoker.SimpleCCM([options])
  • class: futoin-invoker.AdvancedCCM
    • new futoin-invoker.AdvancedCCM()
  • class: futoin-invoker.FutoInError
    • new futoin-invoker.FutoInError()
  • class: futoin-invoker.NativeIface
    • new futoin-invoker.NativeIface()
  • class: futoin-invoker.InterfaceInfo
    • new futoin-invoker.InterfaceInfo()

##class: futoin-invoker.SimpleCCM Members

• class: futoin-invoker.SimpleCCM
  • new futoin-invoker.SimpleCCM([options])

###new futoin-invoker.SimpleCCM([options]) Simple CCM - Reference Implementation

Params

• [options] object - map of OPT_* named variables

##class: futoin-invoker.AdvancedCCM Members

• class: futoin-invoker.AdvancedCCM
  • new futoin-invoker.AdvancedCCM()

###new futoin-invoker.AdvancedCCM() Advanced CCM - Reference Implementation

##class: futoin-invoker.FutoInError Members

• class: futoin-invoker.FutoInError
  • new futoin-invoker.FutoInError()

###new futoin-invoker.FutoInError() Easy access of futoin-asyncsteps.FutoInError errors, which may be extended in the future

##class: futoin-invoker.NativeIface Members

• class: futoin-invoker.NativeIface
  • new futoin-invoker.NativeIface()

###new futoin-invoker.NativeIface() Useful base for custom implementation of NativeIface

##class: futoin-invoker.InterfaceInfo Members

• class: futoin-invoker.InterfaceInfo
  • new futoin-invoker.InterfaceInfo()

###new futoin-invoker.InterfaceInfo() NativeInterface.ifaceInfo() class for custom implementations of NativeIface

#class: CacheFace Members

• class: CacheFace
  • new CacheFace()
  • CacheFace.ifacespec
  • CacheFace.register()
  • cacheFace.getOrSet(as, key_prefix, callable, params, ttl)

##new CacheFace() Cache Native interface

Register with CacheFace.register()

##CacheFace.ifacespec Embedded spec for FutoIn CacheFace

##CacheFace.register() AuditLog Native interface registration helper

##cacheFace.getOrSet(as, key_prefix, callable, params, ttl) Get or Set cached value

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

Params

• as AsyncSteps
• 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 integer - time to live to use, if value is set on cache miss

#class: LogFace Members

• class: LogFace
  • new LogFace()
  • LogFace.ifacespec
  • LogFace.register()
  • logFace.msg(lvl, txt)
  • logFace.msg(lvl, txt, data)
  • logFace.debug(txt)
  • logFace.info(txt)
  • logFace.warn(txt)
  • logFace.error(txt)
  • logFace.security(txt)
  • const: LogFace.LVL_DEBUG
  • const: LogFace.LVL_INFO
  • const: LogFace.LVL_WARN
  • const: LogFace.LVL_ERROR
  • const: LogFace.LVL_SECURITY

##new LogFace() AuditLog Native interface

Register with LogFace.register()

##LogFace.ifacespec Embedded spec for FutoIn LogFace

##LogFace.register() AuditLog Native interface registration helper

##logFace.msg(lvl, txt) Log message

Params

• lvl string - debug|info|warn|error|security
• txt string - message to log

##logFace.msg(lvl, txt, data) Log message

Params

• lvl string - debug|info|warn|error|security
• txt string - message to log
• data string - raw data

##logFace.debug(txt) Log message in debug level

Params

• txt string - message to log

##logFace.info(txt) Log message in info level

Params

• txt string - message to log

##logFace.warn(txt) Log message in warn level

Params

• txt string - message to log

##logFace.error(txt) Log message in error level

Params

• txt string - message to log

##logFace.security(txt) Log message in security level

Params

• txt string - message to log

##const: LogFace.LVL_DEBUG Debug log level

##const: LogFace.LVL_INFO Info log level

##const: LogFace.LVL_WARN Warn log level

##const: LogFace.LVL_ERROR Error log level

##const: LogFace.LVL_SECURITY Security log level

#class: InterfaceInfo Members

• class: InterfaceInfo
  • new InterfaceInfo()
  • interfaceInfo.name()
  • interfaceInfo.version()
  • interfaceInfo.inherits()
  • interfaceInfo.funcs()
  • interfaceInfo.constraints()

##new InterfaceInfo() FutoIn interface info

##interfaceInfo.name() Get FutoIn interface type

Returns: string
##interfaceInfo.version() Get FutoIn interface version

Returns: string
##interfaceInfo.inherits() Get list of inherited interfaces starting from the most derived, may be null

Returns: object
##interfaceInfo.funcs() Get list of available functions, may be null

Returns: object
##interfaceInfo.constraints() Get list of interface constraints, may be null

Returns: object
#class: NativeIface Members

• class: NativeIface
  • new NativeIface()
  • nativeIface.call(as, name, params, upload_data, [download_stream], [timeout])
  • nativeIface.call()
  • nativeIface.bindDerivedKey()

##new NativeIface() Native Interface for FutoIn ifaces

##nativeIface.call(as, name, params, upload_data, [download_stream], [timeout]) Generic FutoIn function call interface Result is passed through AsyncSteps.success() as a map.

Params

• as AsyncSteps - AsyncSteps object
• name string - FutoIn iface function name
• params object - map of func parameters
• upload_data string | stream.Readable - raw upload data or input stram
• [download_stream] stream.Writable - output stream for raw download data
• [timeout] int - if provided, overrides the default. <=0 - disables timeout

##nativeIface.call() Get interface info

Returns: object
##nativeIface.bindDerivedKey() Results with DerivedKeyAccessor through as.success()

#class: spectools Members

• class: spectools
  • new spectools()
  • spectools.loadIface(as, info, specdirs)
  • spectools.parseIface(as, info, specdirs, raw_spec)
  • spectools.checkConsistency(as, info)
  • spectools.checkType(info, type, val)
  • spectools.checkParameterType(as, info, funcname, varname, value)
  • spectools.checkResultType(as, info, funcname, varname, value)
  • const: spectools.standard_errors

##new spectools() SpecTools

##spectools.loadIface(as, info, specdirs) Load FutoIn iface definition.

NOTE: Browser uses XHR to load specs, Node.js searches in local fs.

Params

• as AsyncSteps
• info Object - destination object with "iface" and "version" fields already set
• specdirs Array - each element - search path/url (string) or raw iface (object)

##spectools.parseIface(as, info, specdirs, raw_spec) Parse raw futoin spec (preloaded)

Params

• as AsyncSteps
• info Object - destination object with "iface" and "version" fields already set
• specdirs Array - each element - search path/url (string) or raw iface (object)
• raw_spec Object - iface definition object

##spectools.checkConsistency(as, info) Deeply check consistency of loaded interface.

NOTE: not yet implemented

Params

• as AsyncSteps
• info Object - previously loaded iface

##spectools.checkType(info, type, val) Check if value matches required type

Params

• info Object - previously loaded iface
• type string - standard or custom iface type
• val * - value to check

Returns: Boolean
##spectools.checkParameterType(as, info, funcname, varname, value) Check if parameter value matches required type

Params

• as AsyncSteps
• info Object - previously loaded iface
• funcname string - function name
• varname string - parameter name
• value * - value to check

##spectools.checkResultType(as, info, funcname, varname, value) Check if result value matches required type

Params

• as AsyncSteps
• info Object - previously loaded iface
• funcname string - function name
• varname string - result variable name
• value * - value to check

##const: spectools.standard_errors Enumeration of standard errors

#SimpleCCM window.SimpleCCM - Browser-only reference to futoin-asyncsteps.SimpleCCM

#AdvancedCCM window.AdvancedCCM - Browser-only reference to futoin-asyncsteps.AdvancedCCM

#Invoker futoin.Invoker - Browser-only reference to futoin-invoker module

#FutoInInvoker window.FutoInInvoker - Browser-only reference to futoin-invoker module

documented by jsdoc-to-markdown.