Module: caf_cli/Session

A session object to interact with a CA.

Remote invocations are always serialized. The session locally buffers new requests until the previous ones have been processed.

In case of a system error, the session will try to transparently recover, typically by retrying, or refreshing a token, or redirecting....

If successful, the client just experiences a delay. Otherwise, the session closes, propagating the error in the onclose handler (the onerror handler is for internal use only).

If a client wants parallel requests, it needs to create multiple sessions with its CA. Parallel requests may improve performance with high network latency, but requests are always executed serially by the CA.

The type sessionOptionsType defines the configuration properties for a session:

{token: string, ca: string, from: string, session: string,
 appPublisher: string, appLocalName: string, disableBackchannel: boolean,
 maxRetries: number, retryTimeoutMsec: number, timeoutMsec: number,
 cacheKey: string,
 log: function(string),
 newToken: function(caf.msg, cbType),
 newURL: function(caf.msg, cbType),
 timeAdjuster: TimeAdjuster()} + TokenFactory.options

All options except ca and from (and token with security active) have sensible defaults. Options can be properties in a URL fragment.

Where:

  • token: Authentication token for the from principal.
  • ca: name of the target CA, of the form <caOwner>-<caLocalName>.
  • from: name of the source CA, or equal to ca if the client is the owner. An owner transparently creates a missing CA the first time it tries to access it.
  • session: the logical session id (see external:caf_session).
  • appPublisher: the publisher of this app.
  • appLocalName: the local name of the app. By convention the hostname in the target URL is appPublisher-appLocalName, e.g., https://root-helloworld.cafjs.com.
  • disableBackchannel No notifications are needed, disable the backchannel.
  • maxRetries: Number of error retries before closing a session. If progress, they reset every timeoutMsec.
  • retryTimeoutMsec: Time between retries in miliseconds.
  • timeoutMsec: Max time in miliseconds for a request before assuming an irrecoverable error, and closing the session.
  • cacheKey: custom key to cache server side rendering.
  • log: custom function to log messages.
  • newToken: custom function to negotiate an authentication token.
  • newURL: custom function to redirect the session.
  • timeAdjuster: custom object to synchronize clocks with the cloud.

    see module:caf_cli/TokenFactory for other options.

Source:

Methods

extractSpecFromURL(urlStr) → {specURLType}

Helper function to extract a spec in a URL fragment.

Parameters:
Name Type Description
urlStr string

A serialized URL

Source:
Returns:

Metadata extracted from that URL.

Type
specURLType

extractTokenFromURL(urlStr) → {string|null}

Helper function to extract a token encoded in a URL fragment.

Parameters:
Name Type Description
urlStr string

A serialized URL

Source:
Returns:

A serialized token in that URL.

Type
string | null

getMethodArgs(msg) → {Array.<jsonType>}

Gets original method arguments from message.

Parameters:
Name Type Description
msg msgType

A message

Source:
Throws:

when invalid message.

Type
Error
Returns:

An array with method arguments.

Type
Array.<jsonType>

changeSessionId(newSession) → {string}

Changes the session identifier of future requests on this session.

Parameters:
Name Type Description
newSession string

A new session identifier.

Source:
Returns:

The previous session identifier.

Type
string

close(err)

Close the session.

A session cannot be re-opened, a new one needs to be created.

Parameters:
Name Type Description
err Error

An error to propagate in the handler. If available, the message with the original exception is in err.msg.

Source:

getCacheKey() → {string}

Gets a unique key associated with a cached server-side rendering.

Source:
Returns:

A key associated with a cached server-side rendering.

Type
string

getCrypto() → {Object}

Gets a crypto object to generate DH keys.

Source:
Returns:

A crypto object to generate DH keys.

Type
Object

getEstimatedTimeOffset() → {number}

Returns the estimated time shift in msec between server and client clocks.

Add this value to the current time to match server time, e.g.:

 var now = new Date().getTime();
 now = now + session.getEstimatedTimeOffset();
Source:
Returns:

Time shift in msec between server and client.

Type
number

getPromise() → {Promise}

Invoke the pending method(s) and return a promise with the results.

Source:
Throws:

If there are no pending methods.

Type
Error
Returns:

A promise with the results.

Type
Promise

isClosed() → {boolean}

Whether the session is closed.

A session cannot be re-opened, a new one needs to be created.

Source:
Returns:

True if the session is closed.

Type
boolean

numPending() → {number}

Gets the number of messages in the queue.

Source:
Returns:

The number of queued messages.

Type
number

patchURL(url, props) → {string}

Adds a fragment to a URL with some metadata and, if needed, rewrites the hostname.

The type of caf.cliProps is:

  {caOwner: string, caLocalName: string, appPublisher: string,
   appLocalName: string, token: string, cacheKey: string}
Parameters:
Name Type Description
url string

A URL to patch.

props cliPropsType

Properties to add to the URL fragment.

Source:
Returns:

A patched URL.

Type
string

Session(url, caIdopt, optionsopt) → {Object}

Constructor.

A communication channel to interact with a CA using remote invocations and notifications.

Parameters:
Name Type Attributes Description
url string

A target URL. Properties similar to caf.sessionOptions can be added with a URL fragment; if present, they have priority over the arguments caId and options.

caId string <optional>

A name for the target CA.

options sessionOptionsType <optional>

Configuration for this session.

Source:
Returns:

A session object.

Type
Object