caf_transport/json_rpc - Documentation

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:

json_rpc.js, line 18

Members

ACCOUNTS_CA_LENGTH :number

Source:

json_rpc.js, line 65

Length of prefix in user characters to compute the accounts CA name.

Type:

number

DEFAULT_FROM :string

Source:

json_rpc.js, line 144

Default source of an external request.

Type:

string

DEFAULT_FROM_ID :string

Source:

json_rpc.js, line 122

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

Type:

string

DEFAULT_FROM_USERNAME :string

Source:

json_rpc.js, line 133

Default username when user is unknown.

Type:

string

DEFAULT_QUOTA_ID :string

Source:

json_rpc.js, line 111

Default ID targeting a quota service.

Type:

string

DEFAULT_REQUEST_ID :string

Source:

json_rpc.js, line 165

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

Type:

string

DEFAULT_SESSION :string

Source:

json_rpc.js, line 155

Default external session.

Type:

string

DUMMY_TOKEN :string

Source:

json_rpc.js, line 175

Default token with no authentication.

Type:

string

ERROR_CODES :Object.<string, number>

Source:

json_rpc.js, line 82

Enum with error codes.

Type:

Object.<string, number>

SYSTEM_FROM :string

Source:

json_rpc.js, line 215

Reserved username_fromid for internal, local sessions.

Type:

string

SYSTEM_FROM_ID :string

Source:

json_rpc.js, line 195

Reserved from id for internal, local sessions.

Type:

string

SYSTEM_SESSION_ID :string

Source:

json_rpc.js, line 185

Session id for internal sessions. We use the DEFAULT_SESSION.

Type:

string

SYSTEM_TOKEN :string

Source:

json_rpc.js, line 225

Reserved token for internal, local sessions.

Type:

string

SYSTEM_USERNAME :string

Source:

json_rpc.js, line 205

Reserved username for internal, local sessions.

Type:

string

Methods

accountFrom(caOwner) → {string}

Source:

json_rpc.js, line 236

Generate a from field to access the accounts service.

Parameters:

Name	Type	Description
`caOwner`	string	The target CA owner.

Returns:

A from field for an accounts service request.

Type: string

accountsURL(msg) → {string|null}

Source:

json_rpc.js, line 675

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

Parameters:

Name	Type	Description
`msg`	msgType	A `notAuthenticated` error message.

Returns:

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

Type: string | null

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

Source:

json_rpc.js, line 698

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.

Returns:

An optional promise to enable async methods.

Type: Promise

getAppReplyData(msg) → {jsonType|undefined}

Source:

json_rpc.js, line 946

Gets data field from application reply message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Returns:

Data in message.

Type: jsonType | undefined

getAppReplyError(msg) → {jsonType|undefined}

Source:

json_rpc.js, line 934

Gets error field from application reply message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Returns:

Error in message.

Type: jsonType | undefined

getFrom(msg) → {string|undefined}

Source:

json_rpc.js, line 920

Gets source CA from meta-data in message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Returns:

From field in message.

Type: string | undefined

getMeta(msg) → {caf.meta}

Source:

json_rpc.js, line 812

Gets meta-data from message.

Parameters:

Name	Type	Description
`msg`	msgType	A message

Throws:

when message invalid.
Type Error

Returns:

Metadata in the message.

Type: caf.meta

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

Source:

json_rpc.js, line 745

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>

getMethodName(msg) → {string}

Source:

json_rpc.js, line 764

Gets the method name from message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Throws:

when message is invalid.
Type Error

Returns:

The name of the method.

Type: string

getSessionId(msg) → {string|undefined}

Source:

json_rpc.js, line 892

Gets session id from meta-data in message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Returns:

Session id in message.

Type: string | undefined

getSystemErrorCode(msg) → {number|undefined}

Source:

json_rpc.js, line 972

Gets system error code from message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Returns:

System error code in message.

Type: number | undefined

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

Source:

json_rpc.js, line 959

Gets system error data from message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Returns:

System error data in message.

Type: caf.json | undefined

getSystemErrorMsg(msg) → {string|undefined}

Source:

json_rpc.js, line 984

Gets system error msg from message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Returns:

System error message in message.

Type: string | undefined

getTo(msg) → {string|undefined}

Source:

json_rpc.js, line 906

Gets target CA from meta-data in message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Returns:

Target CA in message.

Type: string | undefined

getToken(msg) → {string|undefined}

Source:

json_rpc.js, line 878

Gets token from meta-data in message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Returns:

Token in message.

Type: string | undefined

isAppReply(msg) → {boolean}

Source:

json_rpc.js, line 364

Tests if it is an application reply message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Returns:

True if it is an application reply message.

Type: boolean

isErrorRecoverable(msg) → {boolean}

Source:

json_rpc.js, line 521

Checks if it there is a recoverable error in message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Returns:

True if it is a recoverable error.

Type: boolean

isNotAuthenticated(msg) → {boolean}

Source:

json_rpc.js, line 659

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

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Returns:

True if it is a notAuthenticated message

Type: boolean

isNotAuthorized(msg) → {boolean}

Source:

json_rpc.js, line 631

Checks if it is a not authorized message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Returns:

True if it is a not authorized message

Type: boolean

isNotification(msg) → {boolean}

Source:

json_rpc.js, line 262

Tests if it is a notification message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Returns:

True if it is a notification message.

Type: boolean

isQuotaExceeded(msg) → {boolean}

Source:

json_rpc.js, line 644

Checks if it is a quota exceeded message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Returns:

True if it is a quota exceeded message

Type: boolean

isRedirect(msg) → {boolean}

Source:

json_rpc.js, line 600

Tests if it is a redirect message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Returns:

True if it is a redirect message.

Type: boolean

isRequest(msg) → {boolean}

Source:

json_rpc.js, line 304

Tests if it is a request message.

Parameters:

Name	Type	Description
`msg`	msgType	A message

Returns:

True if it is a request message.

Type: boolean

isSystemError(msg) → {boolean}

Source:

json_rpc.js, line 421

Tests if it is a system error message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Returns:

True if it is a system error message.

Type: boolean

joinName(…strings) → {string}

Source:

json_rpc.js, line 1085

Joins partial names using the standard separator

Parameters:

Name	Type	Attributes	Description
`strings`	string	<repeatable>	A var number of strings.

Returns:

A joined name with the standard separator.

Type: string

joinNameArray(args, separatoropt) → {string}

Source:

json_rpc.js, line 1099

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

Returns:

A joined name with the standard separator.

Type: string

metaFreeze(msg)

Source:

json_rpc.js, line 783

Freezes meta-data in message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.

Throws:

if msg is not a proper msgType type.
Type Error

newAppError() → {caf.error}

Source:

json_rpc.js, line 504

Wraps an Error object of type AppError:

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

Returns:

Type: caf.error

newSysError() → {caf.error}

Source:

json_rpc.js, line 483

Wraps an Error object of type SystemError:

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

Returns:

Type: caf.error

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

Source:

json_rpc.js, line 282

Creates notification message.

Parameters:

Name	Type	Attributes
`to`	string
`from`	string
`sessionId`	string
`methodName`	string
`var_args`	any	<repeatable>

Returns:

Type: msgType

patchMeta(msg, data)

Source:

json_rpc.js, line 862

Patches meta-data in message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.
`data`	Object	Metadata object to be merged-in.

Throws:

when message invalid.
Type Error

randomId() → {string}

Source:

json_rpc.js, line 247

Generate a random string.

Returns:

Type: string

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

Source:

json_rpc.js, line 585

Creates a redirect message.

Parameters:

Name	Type	Description
`request`	msgType
`errMsg`	string
`errOrg`	Error

Returns:

Type: msgType

redirectDestination(msg) → {string|null}

Source:

json_rpc.js, line 615

Extracts the destination address of a redirection message.

Parameters:

Name	Type	Description
`msg`	msgType	A redirection message.

Returns:

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

Type: string | null

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

Source:

json_rpc.js, line 567

Creates a reply message.

Parameters:

Name	Type	Description
`error`	caf.err
`request`	msgType
`value`	caf.json

Returns:

Type: msgType

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

Source:

json_rpc.js, line 325

Creates a request message.

Parameters:

Name	Type	Attributes
`token`	string
`to`	string
`from`	string
`sessionId`	string
`methodName`	string
`var_args`	any	<repeatable>

Returns:

Type: msgType

setFrom(msg, from)

Source:

json_rpc.js, line 996

Sets source CA in message meta-data.

Parameters:

Name	Type	Description
`msg`	msgType	A message.
`from`	string	`From` field to set.

setMeta(msg, meta)

Source:

json_rpc.js, line 837

Sets meta-data in message.

Parameters:

Name	Type	Description
`msg`	msgType	A message.
`meta`	caf.meta	Metadata to set.

Throws:

When message invalid.
Type Error

setSessionId(msg, sessionId)

Source:

json_rpc.js, line 1025

Sets session id in message meta-data.

Parameters:

Name	Type	Description
`msg`	msgType	A message.
`sessionId`	string	Session id to set.

setTo(msg, to)

Source:

json_rpc.js, line 1010

Sets target CA in message meta-data.

Parameters:

Name	Type	Description
`msg`	msgType	A message.
`to`	string	`To` field to set.

setToken(msg, token)

Source:

json_rpc.js, line 1040

Sets token in message meta-data.

Parameters:

Name	Type	Description
`msg`	msgType	A message.
`token`	string	Token to set in message.

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

Source:

json_rpc.js, line 1063

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

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}

Source:

json_rpc.js, line 346

Creates a system request message.

Parameters:

Name	Type	Attributes
`to`	string
`methodName`	string
`var_args`	any	<repeatable>

Returns:

Type: msgType