FTN6: FutoIn Executor Concept
Version: 1.0
Date: 2014-09-30
Copyright: 2014 FutoIn Project (http://futoin.org)
Authors: Andrey Galkin


This specification IS NOT mandatory. It is just a reference model. Any implementation IS ALLOWED to provide own architecture with drawback of breaking easy migration from one to another.

1. Concept

There must be a generic object type, which can represent both request and response message data and/or communication channels.

There must be a wrapper, which holds current request-response info and potentially a set of standard utilities.

There must be a generic request Executor, which knows all registered interfaces and their implementations.

Executor implementation is not limited in internal behavior, but should have standardized interface even for helper tools, like FutoIn interface compilers and/or converters.

Executor is responsible for (actions are done in AsyncSteps):

  1. converting request from transport-level representation to internal message format
  2. gathering basic request-response info
  3. checking interface constraints
  4. checking message security (HMAC) or authenticating user by credentials
  5. passing control to implementation of specific interfaces with required major version
  6. catching exceptions or normal result
  7. converting response to transport-level representation
  8. maintaining persistent communication channel, if needed
    Client          ||  Executor           Implementation
       .            || [Register]                 .
       .            ||      |                     .
       |----- Request ----->|                     .
       |            ||  [Unpack]                  .
       |            ||   [Info]                   .
       |            || [Constraints]              .
       |            ||  [Security]                .
       |            ||      |---- Invoke -------->|
       |            ||      |<-- Except/Result ---|
       |            ||   [Pack]                   .
       |<---- Response -----|                     .
       .            ||      |                     .
       .            ||      |                     .

Executor should be tighly integrated with MasterService implementation, if supported. General FutoIn message verification should be based on HMAC checking.

Executor should also integrate with AuthService as consumer, if real human users expected to use the service.

Note: Executor is allowed to pass control to implementation only if requested major version of interfaces exactly matches implemented version and minor version is greater than or equal to requested minor version.

All actions are implemented through AsyncSteps interface (FTN12: Async API). For backward compatibility with pre-FutoIn code and/or complex logic, it is possible to make blocking implementation. Such implementations run in dedicated worker threads/processes and receive only RequestInfo object reference.

All true asynchronous implementations must implement special FutoIn AsyncImplementation interface to clearly distinguish more advanced one.

Method signatures:

void AsyncMethod( AsyncSteps as, RequestInfo reqinfo );
Result BlockingMethod( RequestInfo reqinfo );

Note: if BlockingMethod or AsyncMethod returns result then its fields are added to already existing result fields in reqinfo object.

1.1. FutoIn interfaces

Interfaces must get converted according to language/platform-specific convention into native interfaces, which can depend only on standard runtime and native language/platform-specific interfaces of Executor and related objects.

2. Native Executor interface requirements

Language/platform should support runtime introspection and exceptions. For other cases, platform/language-specific workarounds are assumed.

2.1. FutoIn interface

  1. Each FutoIn interfaces is represented as simple native interface type with only abstract methods for each FutoIn interface function
  2. Each abstract method must return no value and take exactly one Request Info object as argument for blocking implementation. Or AsyncSteps and RequestInfo objects as arguments for asynchronous implementation.
  3. Implementation method can assume that all request parameters defined in spec can be accessed from request data
  4. Access to unexpected request and/or response parameters should raise InternalError
  5. Throw of unexpected error should raise InternalError
  6. Each implementation method should have public access
  7. There must be no public method which is not part of the specific FutoIn interface definition
  8. All native interfaces should inherit from single native interface with no public abstract methods

2.2. Request Info

  1. constants:
  2. params() - return reference to request parameter map
  3. result() - return reference to response parameter map
  4. info() - return reference to info parameter map, keys (defined as const with INFO_ prefix):
  5. rawInput() - return raw input stream or null, if FutoIn request comes in that stream
  6. rawOutput() - return raw output stream (no result variables are expected)
  7. context() - get reference to Executor
  8. ignoreInvokerAbort( [bool=true] ) - [un]mark request as ready to be canceled on Invoker abort (disconnect)
  9. Language-specic get accessor for info properties

2.3. User info

  1. localID() - get user ID as seen by trusted AuthService (string)
  2. globalID() - get globally unique user ID (string)
  3. details( AsyncSteps as, array user_field_identifiers )

2.4. Source Address

  1. host() - numeric, no name lookup
  2. port()
  3. type() - IPv4, IPv6
  4. asString() "Type:Host:Port"

2.5. Derived Key

  1. baseID()
  2. sequenceID()
  3. encrypt( AsyncSteps as, data ) - return Base64 data
  4. decrypt( AsyncSteps as, data ) - decrypt Base64 data

2.6. General Async Step interface

See FTN12 Async API

2.7. Async completion interface

There is little use of extended AsyncSteps to provide additional API. Instead, by convention, "reqinfo" AsyncSteps state field must point to associated RequestInfo instance.

2.8. Executor

  1. ccm() - get reference to Invoker CCM, if any
  2. register( AsyncSteps as, ifacever, impl ) - add interface implementation
  3. process( AsyncSteps as ) - do full cycle of request processing, including all security checks
  4. checkAccess( AsyncSteps as, acd ) - shortcut to check access through #acl interface
  5. initFromCache( AsyncSteps as )
  6. cacheInit( AsyncSteps as )

2.9. Interface Implementation

No public members

3. Language/Platform-specific notes

3.1. native JVM (Java, Groovy, etc.)

3.2. Python

3.3. PHP

3.4. C++