Skip to content

Latest commit

 

History

History
574 lines (420 loc) · 26.3 KB

ABRequestService.md

File metadata and controls

574 lines (420 loc) · 26.3 KB
Raw

ABRequestService

Kind: global class

new ABRequestService(req, controller)

Param Type
req object
controller ABServiceController

req.broadcast(packets, cb)

An interface for communicating real time data updates to our clients.

Kind: instance method of ABRequestService

Param Type Description
packets Array.<object> An array of broadcast packets to post to our clients.
packets[].room string A unique identifier of the group of clients to receive the notifications. Usually this is a multi-tenant identified id, generated by: req.socketKey(id)
packets[].event string a unique "key" that tells the client what data they are receiving.
packets[].data json the data delivery for the .event
cb fn a node style callback(error, results) can be provided to notify when the packet has been sent.

broadcast.inboxCreate(users, roles, item, [cb]) ⇒ Promise

A shortcut method to post our "ab.inbox.create" messages to our Clients.

Kind: static method of broadcast

Param Type Description
users Array.<string> | Array.<SiteUser> An array of SiteUser.uuid(s) that should receive this message. Can also work with [{SiteUser}] objects.
roles Array.<string> | Array.<Role> An array of Role.uuid(s) that should receive this message. Can also work with [{Role}] objects.
item obj The newly created Inbox Item definition.
[cb] fn (optional) for legacy code api, a node style callback(error) can be provided for the response.

broadcast.inboxUpdate(users, roles, item, [cb]) ⇒ Promise

A shortcut method to post our "ab.inbox.update" messages to our Clients.

Kind: static method of broadcast

Param Type Description
users Array.<string> | Array.<SiteUser> An array of SiteUser.uuid(s) that should receive this message. Can also work with [{SiteUser}] objects.
roles Array.<string> | Array.<Role> An array of Role.uuid(s) that should receive this message. Can also work with [{Role}] objects.
item obj The newly created Inbox Item definition.
[cb] fn (optional) for legacy code api, a node style callback(error) can be provided for the response.

broadcast.dcCreate(id, newItem, [key], [cb]) ⇒ Promise

A shortcut method for posting our "ab.datacollection.create" messages to our Clients.

Kind: static method of broadcast

Param Type Default Description
id string The {ABObject.id} of the ABObject definition that we are going to post an update for. The incoming newItem should be data managed by this ABObject.
newItem obj The row data of the new Item that was created. Usually fully populated so the clients can work with them as usual.
[key] string "broadcast.dc.create.id" a specific internal performance marker key for tracking how long this broadcast operation took.
[cb] function (optional) for legacy code api, a node style callback(error) can be provided for the response.

broadcast.dcDelete(id, itemID, [key], [cb]) ⇒ Promise

A shortcut method for posting our "ab.datacollection.delete" messages to our Clients.

Kind: static method of broadcast

Param Type Default Description
id string The {ABObject.id} of the ABObject definition that we are going to post a delete for. The deleted item should be data managed by this ABObject.
itemID string The uuid of the row being deleted.
[key] string "broadcast.dc.delete.id" a specific internal performance marker key for tracking how long this broadcast operation took.
[cb] function for legacy code api, a node style callback(error) can be provided for the response.

broadcast.dcUpdate(id, updatedItem, [key], [cb]) ⇒ Promise

A shortcut method for posting our "ab.datacollection.update" messages to our Clients.

Kind: static method of broadcast
King: function

Param Type Default Description
id string The {ABObject.id} of the ABObject definition that we are going to post an update for. The incoming newItem should be data managed by this ABObject.
updatedItem obj The row data of the new Item that was updated. Can be fully populated, or just the updated values.
[key] string "broadcast.dc.update.id" a specific internal performance marker key for tracking how long this broadcast operation took.
[cb] function for legacy code api, a node style callback(error) can be provided for the response.

req.config() ⇒ object

Kind: instance method of ABRequestService
Returns: object - config from the controller

req.configDB()

return the proper DB connection data for the current request. If the request HAS a tenantID, we return the 'appbuilder' connection, If no tenantID, then we return the 'site' connection.

Kind: instance method of ABRequestService

req.connections() ⇒ object

Kind: instance method of ABRequestService
Returns: object - connections from the controller

req.dbConnection(create, isolate) ⇒ Mysql.conn | null

return a connection to our mysql DB for the current request

Kind: instance method of ABRequestService

Param Type Default Description
create bool true create a new DB connection if we are not currently connected.
isolate bool false return a unique DB connection not shared by other requests.

req.languageCode() ⇒ string

return the current language settings for this request.

Kind: instance method of ABRequestService

req.log(...args)

print out a log entry for the current request

Kind: instance method of ABRequestService

Param Type Description
...args * array of possible log entries

log.verbose(...args)

A shortcut method for logging "verbose" messages. There needs to be a .verbose = true in the config.local entry for the current service in order for these messages to be displayed.

Now get ready to eat up all kinds of disk space with needless information to the console!

Kind: static method of log

Param Type Description
...args * anything to log

req.logError(message, error)

Kind: instance method of ABRequestService

Param Type
message string
error Error

req.model(name) ⇒ Model | null

Return a Model() instance from the model/name.js definition

Kind: instance method of ABRequestService

Param Type Description
name string name of the model/[name].js definition to return a Model for.

req.param(key) ⇒ * | undefined

return the parameter value specified by the provided key

Kind: instance method of ABRequestService

Param Type Description
key string name of the req.param[key] value to return

req.allParams(...params) ⇒ object

Kind: instance method of ABRequestService
Returns: object - { paramName: value }

Param Type Description
...params string any number of parameters to ignore

req.params([ignoreList]) ⇒ object

Kind: instance method of ABRequestService
Returns: object - { paramName: value }

Param Type Default Description
[ignoreList] Array.<string> [] parameters to ignore

req.query(query, values, cb, [dbConn])

perform an sql query directly on our dbConn.

Kind: instance method of ABRequestService

Param Type Description
query string the sql query to perform. Use "?" for placeholders.
values array the array of values that correspond to the placeholders in the sql
cb fn a node style callback with 3 paramaters (error, results, fields) these are the same values as returned by the mysql library .query()
[dbConn] MySQL the DB Connection to use for this request. If not provided the common dbConnection() will be used.

req.queryIsolate(query, values, cb)

Perform a query on it's own DB Connection. Not shared with other requests.

Kind: instance method of ABRequestService

Param Type Description
query string the sql query to perform. Use "?" for placeholders.
values array the array of values that correspond to the placeholders in the sql
cb fn a node style callback with 3 paramaters (error, results, fields) these are the same values as returned by the mysql library .query()

req.queryIsolateClose()

Ensure the temporary isolated db connection is closed out properly. This method is intended to be used after all your desired queryIsolate() actions are performed.

Kind: instance method of ABRequestService

req.queryTenantDB(reject) ⇒ false | string

return the tenantDB value for this req object. this is a helper function that simplifies the error handling if no tenantDB is found.

Kind: instance method of ABRequestService
Returns: false | string - false if tenantDB not found, otherwise the tenantDB name (string).

Param Type Description
reject Promise.reject a reject() handler to be called if a tenantDB is not found.

req.queryWhereCondition(cond) ⇒ obj

evaluate a given {cond} hash and generate an SQL condition string from it. This fn() returns both the sql condition string, and an array of values that correspond to the proper ordering of the condition

Kind: instance method of ABRequestService
Returns: obj -
.condition {string} the proper sql "WHERE ${condition}"
.values {array} the values to fill in the condition placeholders

Param Type Description
cond obj a value hash of the desired condition.

req.retry(fn) ⇒ Promise

Attempt to retry the provided fn() if it results in an interrupted Network operation error.

The provided fn() needs to return a {Promise} that resolves() with the expected return data, and rejects() with the Network errors.

Kind: instance method of ABRequestService

Param Type Description
fn function The promise based network operation

req.shouldRetry(error)

Kind: instance method of ABRequestService

Param Type
error Error

req.spanCreateChild(key, attributes) ⇒ object

Creates a telemetry child span based on the req._telemetrySpan

Kind: instance method of ABRequestService
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 ABRequestService
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 ABRequestService

Param Type Description
key string identifier for the span

req.serviceSubscribe(key, handler) ⇒ ABServiceSubscriber

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

Kind: instance method of ABRequestService

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 ABRequestService

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

req.tenantDB() ⇒ string

return the database reference for the current Tenant

Kind: instance method of ABRequestService

req.tenantID() ⇒ string

return the tenantID of the current request

Kind: instance method of ABRequestService

req.toABFactoryReq() ⇒ ABRequestService

Kind: instance method of ABRequestService
Returns: ABRequestService - new instance

req.toObj() ⇒ obj

return a simplified {obj} hash of this request's data.

Kind: instance method of ABRequestService

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 ABRequestService
Returns: obj -
.languageCode: {string} the default language code of the user
.username: {string} the .username of the user for Identification.

req.username() ⇒ string

Kind: instance method of ABRequestService
Returns: string - the req user's username or "system"

req.usernameReal() ⇒ string | null

Kind: instance method of ABRequestService
Returns: string | null - the req userReal's username or null

req.validateData(description) ⇒ undefined | Error

validate the req data and return any errors

Kind: instance method of ABRequestService
Returns: undefined | Error - see ABRequestValidation.errors

Param Type Description
description object see ABRequestValidation.validate

req.worker(fn, params) ⇒ any

Split threads to perform blocking tasks.

Kind: instance method of ABRequestService
Returns: any - Any values.

Param Type Description
fn function The logic function for any blocking event loop tasks.
params Array Array of any values.

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

Kind: instance method of ABRequestService

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

notify.builder(...params)

A shortcut method for notifying builders of configuration errors.

Kind: static method of notify

Param Type Description
...params * see ABRequestService.notify

notify.developer(...params)

A shortcut method for notifying developer of operational errors.

Kind: static method of notify

Param Type Description
...params * see ABRequestService.notify

req.servicePublish(key, data)

Publish an update to other subscribed services.

Kind: instance method of ABRequestService

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 ABRequestService
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) => {})