Module: caf_transport/json_rpc

Functions to generate messages with JSON-RPC 2.0 format.

CAF uses a subset of this spec and, for example, RPC arguments are never passed by name, using instead an array.

CAF always adds a first argument to requests/notifications containing metadata:

   {
      "token": string, // security token for authentication
      "sessionId": string,// logical session name
      "to": string, // target CA
      "from": string // source CA
   }

We also add the same metadata to replies, but the json-rpc reply message format complicates things:

  • Application-level errors: Return an array with 3 elements [meta, error, data] with the error term using a falsy if everything went fine. We never use the JSON-RPC error response object for propagating application errors.

  • System-level errors: Use the error response object with exports.ERROR_CODES. In that case we use an array in the data field to add the metadata, i.e., { "error": {"data": [meta, extraData]}}.

It is recommended to use the getters and setters in this library to hide this complexity.

Source:

Members

DEFAULT_FROM :string

Default source of an external request.

Type:
  • string
Source:

DEFAULT_FROM_ID :string

Default ID in requests that come from entities that have no proper id.

Type:
  • string
Source:

DEFAULT_FROM_USERNAME :string

Default username when user is unknown.

Type:
  • string
Source:

DEFAULT_REQUEST_ID :string

Default id for a response to an invalid request with no id.

Type:
  • string
Source:

DEFAULT_SESSION :string

Default external session.

Type:
  • string
Source:

DUMMY_TOKEN :string

Default token with no authentication.

Type:
  • string
Source:

ERROR_CODES :Object.<string, number>

Enum with error codes.

Type:
  • Object.<string, number>
Source:

SYSTEM_FROM :string

Reserved username_fromid for internal, local sessions.

Type:
  • string
Source:

SYSTEM_FROM_ID :string

Reserved from id for internal, local sessions.

Type:
  • string
Source:

SYSTEM_SESSION_ID :string

Session id for internal sessions. We use the DEFAULT_SESSION.

Type:
  • string
Source:

SYSTEM_TOKEN :string

Reserved token for internal, local sessions.

Type:
  • string
Source:

SYSTEM_USERNAME :string

Reserved username for internal, local sessions.

Type:
  • string
Source:

Methods

accountsURL(msg) → {string|null}

Extracts the URL of a service for user authenticaton from a notAuthenticated error message.

Parameters:
Name Type Description
msg msgType

A notAuthenticated error message.

Source:
Returns:

A url for an authentication service or null if not a valid redirection message.

Type
string | null

call(msg, target, cb) → {Promise}

Executes an asynchronous method in a target CA using arguments in an RPC request message.

Parameters:
Name Type Description
msg msgType

A message.

target Object

Target CA.

cb cbType

Returns in first argument an optional error of type caf.error (System or App error) or, in the second argument, the result of the method invocation.

Source:
Returns:

An optional promise to enable async methods.

Type
Promise

getAppReplyData(msg) → {jsonType|undefined}

Gets data field from application reply message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Returns:

Data in message.

Type
jsonType | undefined

getAppReplyError(msg) → {jsonType|undefined}

Gets error field from application reply message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Returns:

Error in message.

Type
jsonType | undefined

getFrom(msg) → {string|undefined}

Gets source CA from meta-data in message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Returns:

From field in message.

Type
string | undefined

getMeta(msg) → {caf.meta}

Gets meta-data from message.

Parameters:
Name Type Description
msg msgType

A message

Source:
Throws:

when message invalid.

Type
Error
Returns:

Metadata in the message.

Type
caf.meta

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>

getMethodName(msg) → {string}

Gets the method name from message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Throws:

when message is invalid.

Type
Error
Returns:

The name of the method.

Type
string

getSessionId(msg) → {string|undefined}

Gets session id from meta-data in message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Returns:

Session id in message.

Type
string | undefined

getSystemErrorCode(msg) → {number|undefined}

Gets system error code from message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Returns:

System error code in message.

Type
number | undefined

getSystemErrorData(msg) → {caf.json|undefined}

Gets system error data from message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Returns:

System error data in message.

Type
caf.json | undefined

getSystemErrorMsg(msg) → {string|undefined}

Gets system error msg from message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Returns:

System error message in message.

Type
string | undefined

getTo(msg) → {string|undefined}

Gets target CA from meta-data in message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Returns:

Target CA in message.

Type
string | undefined

getToken(msg) → {string|undefined}

Gets token from meta-data in message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Returns:

Token in message.

Type
string | undefined

isAppReply(msg) → {boolean}

Tests if it is an application reply message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Returns:

True if it is an application reply message.

Type
boolean

isErrorRecoverable(msg) → {boolean}

Checks if it there is a recoverable error in message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Returns:

True if it is a recoverable error.

Type
boolean

isNotAuthenticated(msg) → {boolean}

Checks if it is a "principal not authenticated" message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Returns:

True if it is a notAuthenticated message

Type
boolean

isNotAuthorized(msg) → {boolean}

Checks if it is a not authorized message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Returns:

True if it is a not authorized message

Type
boolean

isNotification(msg) → {boolean}

Tests if it is a notification message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Returns:

True if it is a notification message.

Type
boolean

isRedirect(msg) → {boolean}

Tests if it is a redirect message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Returns:

True if it is a redirect message.

Type
boolean

isRequest(msg) → {boolean}

Tests if it is a request message.

Parameters:
Name Type Description
msg msgType

A message

Source:
Returns:

True if it is a request message.

Type
boolean

isSystemError(msg) → {boolean}

Tests if it is a system error message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Returns:

True if it is a system error message.

Type
boolean

joinName(…strings) → {string}

Joins partial names using the standard separator

Parameters:
Name Type Attributes Description
strings string <repeatable>

A var number of strings.

Source:
Returns:

A joined name with the standard separator.

Type
string

joinNameArray(args, separatoropt) → {string}

Joins partial names using a separator

Parameters:
Name Type Attributes Description
args Array.<string>

A var number of strings in an array.

separator string <optional>

Optional separator to override '-'.

Source:
Returns:

A joined name with the standard separator.

Type
string

metaFreeze(msg)

Freezes meta-data in message.

Parameters:
Name Type Description
msg msgType

A message.

Source:
Throws:

if msg is not a proper msgType type.

Type
Error

newAppError() → {caf.error}

Wraps an Error object of type AppError:

{name: 'AppError', msg: msgType, errorStr: string, error: Error}

Source:
Returns:
Type
caf.error

newSysError() → {caf.error}

Wraps an Error object of type SystemError:

{name: 'SystemError', msg: msgType, code: number, errorStr: string, error: Error}

Source:
Returns:
Type
caf.error

notification(to, from, sessionId, methodName, …var_args) → {msgType}

Creates notification message.

Parameters:
Name Type Attributes Description
to string
from string
sessionId string
methodName string
var_args any <repeatable>
Source:
Returns:
Type
msgType

patchMeta(msg, data)

Patches meta-data in message.

Parameters:
Name Type Description
msg msgType

A message.

data Object

Metadata object to be merged-in.

Source:
Throws:

when message invalid.

Type
Error

randomId() → {string}

Generate a random string.

Source:
Returns:
Type
string

redirect(request, errMsg, errOrg) → {msgType}

Creates a redirect message.

Parameters:
Name Type Description
request msgType
errMsg string
errOrg Error
Source:
Returns:
Type
msgType

redirectDestination(msg) → {string|null}

Extracts the destination address of a redirection message.

Parameters:
Name Type Description
msg msgType

A redirection message.

Source:
Returns:

A redirection address or null if not a valid redirection message.

Type
string | null

reply(error, request, value) → {msgType}

Creates a reply message.

Parameters:
Name Type Description
error caf.err
request msgType
value caf.json
Source:
Returns:
Type
msgType

request(token, to, from, sessionId, methodName, …var_args) → {msgType}

Creates a request message.

Parameters:
Name Type Attributes Description
token string
to string
from string
sessionId string
methodName string
var_args any <repeatable>
Source:
Returns:
Type
msgType

setFrom(msg, from)

Sets source CA in message meta-data.

Parameters:
Name Type Description
msg msgType

A message.

from string

From field to set.

Source:

setMeta(msg, meta)

Sets meta-data in message.

Parameters:
Name Type Description
msg msgType

A message.

meta caf.meta

Metadata to set.

Source:
Throws:

When message invalid.

Type
Error

setSessionId(msg, sessionId)

Sets session id in message meta-data.

Parameters:
Name Type Description
msg msgType

A message.

sessionId string

Session id to set.

Source:

setTo(msg, to)

Sets target CA in message meta-data.

Parameters:
Name Type Description
msg msgType

A message.

to string

To field to set.

Source:

setToken(msg, token)

Sets token in message meta-data.

Parameters:
Name Type Description
msg msgType

A message.

token string

Token to set in message.

Source:

splitName(name, separatoropt) → {Array.<string>}

Splits a compound name into namespace root and local name. The convention is to use the character '-' to separate them.

Parameters:
Name Type Attributes Description
name string

A name to split.

separator string <optional>

Optional separator to override '-'.

Source:
Throws:

Invalid compound name.

Type
Error
Returns:

An array with two elements: namespace root and local name, or three if it also has a map name, or four if fully qualified CA name ,i.e., appPublisher-appLocalName-caOwner-caLocalName.

Type
Array.<string>

systemRequest(to, methodName, …var_args) → {msgType}

Creates a system request message.

Parameters:
Name Type Attributes Description
to string
methodName string
var_args any <repeatable>
Source:
Returns:
Type
msgType