ABRequestAPI.md

ABRequestAPI

a default set of data/utilities for our api request. This request is established in the Sails api_sails service and is used to verify and send jobs to various micro services.

Kind: global class

• ABRequestAPI
  • new ABRequestAPI(req, res, [config])
  • .tenantID : string
  • .user : obj
  • .userReal : obj
  • .isSwitcherood() ⇒ boolean
  • .switcherooToUser(user)
  • .userDefaults() ⇒ obj
  • .tenantSet() ⇒ bool
  • .log(...args)
  • .param(key) ⇒ string
  • .serviceResponder(key, handler) ⇒ ABServiceResponder
  • .serviceSubscribe(key, handler) ⇒ ABServiceSubscriber
  • .socketKey(key) ⇒ string
  • .spanCreateChild(key, attributes) ⇒ object
  • .spanRequest(key, attributes) ⇒ object
  • .spanEnd(key)
  • .validateParameters(description, [autoRespond], [params]) ⇒ bool
  • .validationReset()
  • .validRoles(roleIDs) ⇒ bool
  • .validBuilder([autoRespond]) ⇒ bool
  • .validSwitcheroo([autoRespond]) ⇒ bool
  • .validUser([autoRespond]) ⇒ bool
  • .notify(domain, error, [info])
    • .builder(error, [info])
    • .developer(error, [info])
  • .servicePublish(key, data)
  • .serviceRequest(key, data, [options], [cb]) ⇒ Promise

new ABRequestAPI(req, res, [config])

Param	Type	Default
req	Object
res	Object
[config]	Object	{}

req.tenantID : string

tenant's id

Kind: instance property of ABRequestAPI

req.user : obj

ABUser

Kind: instance property of ABRequestAPI

req.userReal : obj

The actual user when using Switcheroo

Kind: instance property of ABRequestAPI

req.isSwitcherood() ⇒ boolean

Kind: instance method of ABRequestAPI

req.switcherooToUser(user)

allow the current user to impersonate the provided user.

Kind: instance method of ABRequestAPI

Param	Type
user	json:SiteUser

req.userDefaults() ⇒ obj

return a data structure used by our ABModel.find() .create() .update() .delete() operations that needs credentials for the current User driving this request.

Kind: instance method of ABRequestAPI
Returns: obj - .languageCode: {string} the default language code of the user .usernam: {string} the .username of the user for Identification.

req.tenantSet() ⇒ bool

Kind: instance method of ABRequestAPI
Returns: bool - value if the tenantID is set.

req.log(...args)

format our output logs to include our jobID with our message.

Kind: instance method of ABRequestAPI

Param	Type	Description
...args	*	anything to log (will be stringified)

req.param(key) ⇒ string

An interface to return the requested input value. If that value has already been processed by our .validateParameters() we pull that value from there. Otherwise we ask the provided req object for the value.

Kind: instance method of ABRequestAPI

Param	Type	Description
key	string	The identifying parameter key

req.serviceResponder(key, handler) ⇒ ABServiceResponder

Create a Cote service responder that can parse our data interchange format.

Kind: instance method of ABRequestAPI

Param	Type	Description
key	string	the service handler's key we are responding to.
handler	function	a function to handle the incoming request. See ABServiceResponder constructor for details

req.serviceSubscribe(key, handler) ⇒ ABServiceSubscriber

Create a Cote service subscriber that can parse our data interchange format.

Kind: instance method of ABRequestAPI

Param	Type	Description
key	string	the service handler's key we are responding to.
handler	function	a function to handle the incoming request. See ABServiceSubscriber constructor for details

req.socketKey(key) ⇒ string

make sure any socket related key is prefixed by our tenantID

Kind: instance method of ABRequestAPI

Param	Type	Description
key	string	The socket key we are wanting to reference.

req.spanCreateChild(key, attributes) ⇒ object

Creates a telemetry child span based on the active span

Kind: instance method of ABRequestAPI
Returns: object - the span

Param	Type	Description
key	string	identifier for the span
attributes	object	any data to add to the span

req.spanRequest(key, attributes) ⇒ object

Creates or gets the telemetry span for the current Request

Kind: instance method of ABRequestAPI
Returns: object - the span

Param	Type	Description
key	string	identifier for the span
attributes	object	any data to add to the span

req.spanEnd(key)

Ends the given telemetry span

Kind: instance method of ABRequestAPI

Param	Type	Description
key	string	identifier for the span

req.validateParameters(description, [autoRespond], [params]) ⇒ bool

Parse the description object and determine if the current req instance passes the tests provided.

Will first use the description to build a joi validator, and then evaluate the parameters using it.

Any missed validation rules will be stored internally and an error can be retrieved using .errorValidation().

Kind: instance method of ABRequestAPI
Returns: bool - true if all checks pass, otherwise false.

Param	Type	Default	Description
description	hash		An object hash describing the validation checks to use. At the top level the Hash is: { [paramName] : {ruleHash} }
[autoRespond]	bool	true	if true will auto respond on errors with res.ab.error()
[params]	hash		the parameters to evaluate in the format { "param" : {values} } hash. If not provided, then will use req.allParams() to evaluate against all parameters.

Example ( Each {ruleHash} follows this format: )

       "parameterName" : {
          {joi.fn}  : true,  // performs: joi.{fn}();
           {joi.fn} : {
             {joi.fn1} : true,   // performs: joi.{fn}().{fn1}();
             {joi.fn2} : { options } // performs: joi.{fn}().{fn2}({options})
           }
           // examples:
           "required" : {bool},  // default = false

           // custom:
           "validate" : {fn} a function(value, {allValues hash}) that
                          returns { error:{null || {new Error("Error Message")} }, value: {normalize(value)}}
        }

req.validationReset()

Kind: instance method of ABRequestAPI
Depreciated:

req.validRoles(roleIDs) ⇒ bool

Verify if the current user has one of the provided roleIDs assigned.

Kind: instance method of ABRequestAPI

Param	Type	Description
roleIDs	Array.<string>	array containing the uuids of the roles to verify.

req.validBuilder([autoRespond]) ⇒ bool

Verify if the current user has one of the default Builder Roles assigned

Kind: instance method of ABRequestAPI

Param	Type	Default	Description
[autoRespond]	bool	true	do we auto res.ab.error() on a negative result see validUser.

req.validSwitcheroo([autoRespond]) ⇒ bool

Verify if the current user has the Switcheroo Role assigned

Kind: instance method of ABRequestAPI

Param	Type	Default	Description
[autoRespond]	bool	true	do we auto res.ab.error() on a negative result see validUser.

req.validUser([autoRespond]) ⇒ bool

returns true if there is a valid .user set on the request, otherwise false

By default, this function will return a "E_REAUTH" error back as the response. If you want to externally handle this situation then need to pass false for autoRespond.

Kind: instance method of ABRequestAPI

Param	Type	Default	Description
[autoRespond]	bool	true	will auto respond on errors with the res object.

req.notify(domain, error, [info])

Kind: instance method of ABRequestAPI

Param	Type	Default	Description
domain	string		Normally "builder" or "developer"
error	Error | Array.<Error> | string | object
[info]	object	{}

• .notify(domain, error, [info])
  • .builder(error, [info])
  • .developer(error, [info])

notify.builder(error, [info])

A shortcut method for notifying builders of configuration errors.

Kind: static method of notify

Param	Type	Default
error	Error
[info]	object	{}

notify.developer(error, [info])

A shortcut method for notifying developer of operational errors.

Kind: static method of notify

Param	Type	Default
error	Error
[info]	object	{}

req.servicePublish(key, data)

Publish an update to other subscribed services.

Kind: instance method of ABRequestAPI

Param	Type	Description
key	string	the channel we are updating.
data	json	the data packet to send to the subscribers.

req.serviceRequest(key, data, [options], [cb]) ⇒ Promise

Send a request to another micro-service using the cote protocol. Accept an optional callback, but also returns a promise.

Kind: instance method of ABRequestAPI
Returns: Promise - resolves with the response from the service

Param	Type	Default	Description
key	string		the service handler's key we are sending a request to.
data	json		the data packet to send to the service.
[options]	object		optional options
[options.timeout]	number	5000	ms to wait before timing out
[options.maxAttempts]	number	5	how many times to try the request if it fails
[options.longRequest]	boolean	false	timeout after 90 seconds, will be ignored if timeout was set
[options.stringResult]	boolean	false	Return the results as a string data type.
[cb]	function		optional node.js style callback(err, result) for when the response is received.

Example

// async/await
try {
   let result = await request(key, data);
} catch (err) {}
// promise
request(key, data, opts).then((result) => {}).catch((err) => {})
// callback
request(key, data, opts, (err, result) => {})
// or
request(key, data, (err, result) => {})