2017.04.01 Under Construction
The Hrequest package leverages the ARCcore.filter library to to provide data validation
and normalization of HTTP request and response data messages in derived application-layer code.
Hrequest package exports two filter factory functions that allow developers to construct Node.js and browser client-specific
variants of Hrequest filters.
The back-end Hrequest variant wraps the popular request library package.
And, the front-end Hrequest variant wraps the browser's
Constructing an Hrequest instance builds three ARCcore.filter objects:
- The main Hrequest filter that your application calls to initiate an asynchronous HTTP request.
- A result filter that wraps your asynchronous result handler callback function.
- An error filter that wraps your asynchronous error callback function handler.
The library implementation validates and normalizes your request data using
a filter specification and then delegates to either
on execution context.
When the HTTP request completes, Hrequest examines the response and delegates to either the result or error filters
that wrap the result and error callback functions you provide at construction.
Not all successful HTTP requests return correct or expected information. For example, even small changes
to the implementation of the remote HTTP server may invalidate some assumption that your application code
relies on for correct operation.
So, if Hrequest has trouble validating and normalizing a successful HTTP response it is considered an
application-level error and the error filter is called instead of the result filter.
Hrequest was designed primarily for use with the Holism application server that uses
similar patterns based on the ARCcore.filter library to enforce API message contracts.
But there's no reason that you cannot use Hrequest outside of this context as well.
The main use cases for Hrequest are product stability, security, and developer experience.
Hrequest catches and reports bugs and subtle problems (e.g. mismatched client / server versions) quickly
allowing developers to diagnose and correct the issue(s) in their development environment. And, this is
always significantly less time consuming and stressful than dealing with a broken production deployment.
The last and perhaps most interesting use case for Hrequest involves publishing or making available via
API's the filter specification documents used to enforce critical internal
messaging and external-facing API contracts.