51Degrees Pipeline for Node.js

Evidence Class Reference

Detailed Description

Storage of evidence on a flowData object.

Examples
usageSharing/usageSharing.js.

Public Member Functions

 constructor (flowData)
 Constructor for evidence.
 add (key, value)
 Add a piece of evidence to flowData.
 addObject (evidenceObject)
 Add a piece of evidence to flowData as an object.
 addFromRequest (request)
 Add evidence to flowData from an HTTP request This helper automatically adds evidence: headers, cookies, session values, protocol, IP, query params and, for a POST with a form body, the form values.
 addFromRequestAsync (request, maxFormBytes=1024 *1024)
 Add evidence to flowData from an HTTP request, first reading a form body from the request when it is a POST with a form body and nothing has read the body already.
 get (key)
 Get a piece of evidence by key, in any letter case.
 getAll ()
 Get all evidence.
 getUnaccepted ()
 Get the evidence no element in the pipeline accepts, which add set aside rather than throwing away.

Member Function Documentation

◆ add()

Evidence::add ( key,
value )
inline

Add a piece of evidence to flowData.

Keys ignore letter case, so a key that differs from one already added only in its letters replaces that value under the letters it was first added with. A key is kept when an element accepts it or keeps it. server.http-request is always kept, apart from the other evidence, because it is the web request rather than a value to process.

Parameters
{string}key evidence key to add
{*}value value of evidence key

◆ addFromRequest()

Evidence::addFromRequest ( request)
inline

Add evidence to flowData from an HTTP request This helper automatically adds evidence: headers, cookies, session values, protocol, IP, query params and, for a POST with a form body, the form values.

Form values are added as query evidence after the query string, so a form value replaces a query string value of the same name. They are read from request.body, which a framework's form parser sets, either as an object or as the body text. A plain Node request has no request.body, so use addFromRequestAsync to read the body from the request instead. The 51Degrees client script sends its values in a form body, so without one or the other they never reach the pipeline.

The web request is also added as server.http-request, whether or not an element accepts it, as a frozen object holding every value read from the request under the key it has as evidence, with the request line as server.request-method, server.request-path and server.request-query. It is there for elements that read the request without accepting evidence, such as the usage sharing element, and so that what the request carried can be used once processing is done, when the request's socket may have closed.

Parameters
{object}request an HTTP request object
Returns
{Evidence} return updated evidence

◆ addFromRequestAsync()

Evidence::addFromRequestAsync ( request,
maxFormBytes = 1024 * 1024 )
inline

Add evidence to flowData from an HTTP request, first reading a form body from the request when it is a POST with a form body and nothing has read the body already.

The body text is kept in request.body, and then addFromRequest adds the evidence. A body larger than maxFormBytes is not read and no form values are added.

Parameters
{object}request an HTTP request object
{number}[maxFormBytes] the largest form body read, one mebibyte unless given
Returns
{Promise<Evidence>} the updated evidence

◆ addObject()

Evidence::addObject ( evidenceObject)
inline

Add a piece of evidence to flowData as an object.

Parameters
{object}evidenceObject key value map of evidence
{string}evidenceObject.key evidencekey
{*}evidenceObject.value evidence value

◆ constructor()

Evidence::constructor ( flowData)
inline

Constructor for evidence.

Parameters
{FlowData}flowData FlowData to add the evidence to

The web request as server.http-request holds it, being every value addFromRequest read from the request, under its evidence key and before any is filtered out, or undefined when evidence was not added from a request.

@type {Readonly<object>|undefined}

◆ get()

Evidence::get ( key)
inline

Get a piece of evidence by key, in any letter case.

Parameters
{string}key evidence key to retreive
Returns
{*} the evidence value, or undefined where there is none

◆ getAll()

Evidence::getAll ( )
inline

Get all evidence.

server.http-request is left out, because it is the web request rather than a value to process, so get it with get.

Returns
{object} all evidence

◆ getUnaccepted()

Evidence::getUnaccepted ( )
inline

Get the evidence no element in the pipeline accepts, which add set aside rather than throwing away.

The Cloud Request Engine sends it along with the accepted evidence, because what the cloud service uses changes over time.

Returns
{object} the evidence set aside, empty where every key was accepted