caf_cli/Session - Documentation

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, initUser: boolean, maxQueueLength: boolean,
 log: function(string),
 newToken: function(caf.msg, cbType),
 newUser: function(url: string, options: sessionOptionsType, 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.
initUser: Whether the owner in from is a new user that has to be registered.
maxQueueLength: The maximum queue length of non-started requests.
log: custom function to log messages.
newToken: custom function to negotiate an authentication token.
newURL: custom function to redirect the session.
newUser: custom function to initialize a new user.
timeAdjuster: custom object to synchronize clocks with the cloud.

see module:caf_cli/TokenFactory for other options.

Source:

Session.js, line 20

Methods

deleteTokenFromURL(urlStr) → {string}

Source:

Session.js, line 776

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

Parameters:

Name	Type	Description
`urlStr`	string	A serialized URL

Returns:

A serialized URL without a token in its fragment.

Type: string

extractSpecFromURL(urlStr) → {specURLType}

Source:

Session.js, line 798

Helper function to extract a spec in a URL fragment.

Parameters:

Name	Type	Description
`urlStr`	string	A serialized URL

Returns:

Metadata extracted from that URL.

Type: specURLType

extractTokenFromURL(urlStr) → {string|null}

Source:

Session.js, line 753

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

Parameters:

Name	Type	Description
`urlStr`	string	A serialized URL

Returns:

A serialized token in that URL.

Type: string | null

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

Source:

Session.js, line 838

Gets original method arguments from message.

Parameters:

Name	Type	Description
`msg`	msgType	A message

Throws:

when invalid message.
Type Error

Returns:

An array with method arguments.

Type: Array.<jsonType>

changeSessionId(newSession) → {string}

Source:

Session.js, line 703

Changes the session identifier of future requests on this session.

Parameters:

Name	Type	Description
`newSession`	string	A new session identifier.

Returns:

The previous session identifier.

Type: string

close(err)

Source:

Session.js, line 619

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`.

getCacheKey() → {string}

Source:

Session.js, line 656

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

Returns:

A key associated with a cached server-side rendering.

Type: string

getCrypto() → {Object}

Source:

Session.js, line 669

Gets a crypto object to generate DH keys.

Returns:

A crypto object to generate DH keys.

Type: Object

getEstimatedTimeOffset() → {number}

Source:

Session.js, line 690

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.:

 const now = new Date().getTime();
 now = now + session.getEstimatedTimeOffset();

Returns:

Time shift in msec between server and client.

Type: number

getPromise() → {Promise}

Source:

Session.js, line 361

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

Throws:

If there are no pending methods.
Type Error

Returns:

A promise with the results.

Type: Promise

isClosed() → {boolean}

Source:

Session.js, line 293

Whether the session is closed.

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

Returns:

True if the session is closed.

Type: boolean

numPending() → {number}

Source:

Session.js, line 641

Gets the number of messages in the queue.

Returns:

The number of queued messages.

Type: number

patchURL(url, props) → {string}

Source:

Session.js, line 877

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

The definition of cliPropsType is in types.js.

Parameters:

Name	Type	Description
`url`	string	A URL to patch.
`props`	cliPropsType	Properties to add to the URL fragment.

Returns:

A patched URL.

Type: string

randomString(len) → {string}

Source:

Session.js, line 852

Returns a random string with capital letters and digits.

Parameters:

Name	Type	Description
`len`	number	The number of characters in the string.

Returns:

The new string.

Type: string

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

Source:

Session.js, line 130

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.

Returns:

A session object.

Type: Object