HttpProxy
Middleware proxy between HttpAgent implementations and the Fetch API, providing a Promise-oriented API for sending requests.
Kind: global class
- HttpProxy
- new HttpProxy(transformer, window)
- instance
- ._transformer :
UrlTransformer
- ._window :
Window
- ._defaultHeaders :
Map.<string, string>
- .request(method, url, data, [options]) ⇒
Promise.<HttpAgent~Response>
- .setDefaultHeader(header, value)
- .clearDefaultHeaders()
- .getErrorParams(method, url, data, options, status, body, cause) ⇒
ErrorParams
- .haveToSetCookiesManually() ⇒
boolean
- ._processResponse(requestParams, response, responseBody) ⇒
HttpAgent~Response
- ._headersToPlainObject(headers) ⇒
Object.<string, string>
- ._processError(fetchError, requestParams) ⇒
GenericError
- ._createError(cause, requestParams, status, responseBody) ⇒
GenericError
- ._getFetchApi() ⇒
function
- ._composeRequestParams(method, url, data, options) ⇒
RequestParams
- ._composeRequestInit(method, data, options) ⇒
RequestInit
- ._getContentType(method, data, options) ⇒
string
- ._composeRequestUrl(url, data) ⇒
string
- ._shouldRequestHaveBody(method, data) ⇒
boolean
- ._transformer :
- inner
- ~RequestParams :
Object
- ~ErrorParams :
Object
- ~RequestParams :
new HttpProxy(transformer, window)
Initializes the HTTP proxy.
Param | Type | Description |
---|---|---|
transformer | UrlTransformer |
A transformer of URLs to which requests are made. |
window | Window |
Helper for manipulating the global object window regardless of the client/server-side environment. |
httpProxy._transformer : UrlTransformer
A transformer of URLs to which requests are made.
Kind: instance property of HttpProxy
httpProxy._window : Window
Helper for manipulating the global object window
regardless of the
client/server-side environment.
Kind: instance property of HttpProxy
httpProxy._defaultHeaders : Map.<string, string>
The default HTTP headers to include with the HTTP requests, unless overridden.
Kind: instance property of HttpProxy
httpProxy.request(method, url, data, [options]) ⇒ Promise.<HttpAgent~Response>
Executes a HTTP request to the specified URL using the specified HTTP method, carrying the provided data.
Kind: instance method of HttpProxy
Returns: Promise.<HttpAgent~Response>
- A promise that resolves to the server
response.
Param | Type | Description |
---|---|---|
method | string |
The HTTP method to use. |
url | string |
The URL to which the request should be made. |
data | Object.<string, (boolean\|number\|string\|Date)> |
The data to be send to the server. The data will be included as query parameters if the request method is GET or HEAD , and as a request body for any other request method. |
[options] | HttpAgent~RequestOptions |
Optional request options. |
httpProxy.setDefaultHeader(header, value)
Sets the specified default HTTP header. The header will be sent with all subsequent HTTP requests unless reconfigured using this method, overridden by request options, or cleared by clearDefaultHeaders method.
Kind: instance method of HttpProxy
Param | Type | Description |
---|---|---|
header | string |
A header name. |
value | string |
A header value. |
httpProxy.clearDefaultHeaders()
Clears all defaults headers sent with all requests.
Kind: instance method of HttpProxy
httpProxy.getErrorParams(method, url, data, options, status, body, cause) ⇒ ErrorParams
Gets an object that describes a failed HTTP request, providing information about both the failure reported by the server and how the request has been sent to the server.
Kind: instance method of HttpProxy
Returns: ErrorParams
- An object containing both the details of
the error and the request that lead to it.
Param | Type | Description |
---|---|---|
method | string |
The HTTP method used to make the request. |
url | string |
The URL to which the request has been made. |
data | Object.<string, (boolean\|number\|string\|Date)> |
The data sent with the request. |
options | HttpAgent~RequestOptions |
Optional request options. |
status | number |
The HTTP response status code send by the server. |
body | object |
The body of HTTP error response (detailed information). |
cause | Error |
The low-level cause error. |
httpProxy.haveToSetCookiesManually() ⇒ boolean
Returns true
if cookies have to be processed manually by setting
Cookie
HTTP header on requests and parsing the Set-Cookie
HTTP
response header.
The result of this method depends on the current application
environment, the client-side usually handles cookie processing
automatically, leading this method returning false
.
At the client-side, the method tests whether the client has cookies
enabled (which results in cookies being automatically processed by the
browser), and returns true
or false
accordingly.
Kind: instance method of HttpProxy
Returns: boolean
- true
if cookies are not processed automatically by
the environment and have to be handled manually by parsing
response headers and setting request headers, otherwise false
.
httpProxy._processResponse(requestParams, response, responseBody) ⇒ HttpAgent~Response
Processes the response received from the server.
Kind: instance method of HttpProxy
Returns: HttpAgent~Response
- The server’s response along with all related
metadata.
Param | Type | Description |
---|---|---|
requestParams | RequestParams |
The original request’s parameters. |
response | Response |
The Fetch API’s Response object representing the server’s response. |
responseBody | \* |
The server’s response body. |
httpProxy._headersToPlainObject(headers) ⇒ Object.<string, string>
Converts the provided Fetch API’s Headers
object to a plain object.
Kind: instance method of HttpProxy
Returns: Object.<string, string>
- Converted headers.
Param | Type | Description |
---|---|---|
headers | Headers |
The headers to convert. |
httpProxy._processError(fetchError, requestParams) ⇒ GenericError
Processes the provided Fetch API or internal error and creates an error to expose to the calling API.
Kind: instance method of HttpProxy
Returns: GenericError
- The error to provide to the calling API.
Param | Type | Description |
---|---|---|
fetchError | Error |
The internal error to process. |
requestParams | RequestParams |
An object representing the complete request parameters used to create and send the HTTP request. |
httpProxy._createError(cause, requestParams, status, responseBody) ⇒ GenericError
Creates an error that represents a failed HTTP request.
Kind: instance method of HttpProxy
Returns: GenericError
- The error representing a failed HTTP request.
Param | Type | Default | Description |
---|---|---|---|
cause | Error |
The error’s message. | |
requestParams | RequestParams |
An object representing the complete request parameters used to create and send the HTTP request. | |
status | number |
Server’s response HTTP status code. | |
responseBody | \* |
|
The body of the server’s response, if any. |
httpProxy._getFetchApi() ⇒ function
Returns window.fetch compatible API to use, depending on the method being used at the server (polyfill) or client (native/polyfill) side.
Kind: instance method of HttpProxy
Returns: function
- An
implementation of the Fetch API to use.
httpProxy._composeRequestParams(method, url, data, options) ⇒ RequestParams
Composes an object representing the HTTP request parameters from the provided arguments.
Kind: instance method of HttpProxy
Returns: RequestParams
- An object
representing the complete request parameters used to create and
send the HTTP request.
Param | Type | Description |
---|---|---|
method | string |
The HTTP method to use. |
url | string |
The URL to which the request should be sent. |
data | Object.<string, (boolean\|number\|string\|Date)> |
The data to send with the request. |
options | HttpAgent~RequestOptions |
Optional request options. |
httpProxy._composeRequestInit(method, data, options) ⇒ RequestInit
Composes an init object, which can be used as a second argument of
window.fetch
method.
Kind: instance method of HttpProxy
Returns: RequestInit
- A RequestInit
object of the Fetch API.
Param | Type | Description |
---|---|---|
method | string |
The HTTP method to use. |
data | Object.<string, (boolean\|number\|string\|Date)> |
The data to be send with a request. |
options | HttpAgent~RequestOptions |
Options provided by the HTTP agent. |
httpProxy._getContentType(method, data, options) ⇒ string
Gets a Content-Type
header value for defined method, data and options.
Kind: instance method of HttpProxy
Returns: string
- A Content-Type
header value.
Param | Type | Description |
---|---|---|
method | string |
The HTTP method to use. |
data | Object.<string, (boolean\|number\|string\|Date)> |
The data to be send with a request. |
options | HttpAgent~RequestOptions |
Options provided by the HTTP agent. |
httpProxy._composeRequestUrl(url, data) ⇒ string
Transforms the provided URL using the current URL transformer and adds the provided data to the URL’s query string.
Kind: instance method of HttpProxy
Returns: string
- The transformed URL with the provided data attached to
its query string.
Param | Type | Description |
---|---|---|
url | string |
The URL to prepare for use with the fetch API. |
data | Object.<string, (boolean\|number\|string\|Date)> |
The data to be attached to the query string. |
httpProxy._shouldRequestHaveBody(method, data) ⇒ boolean
Checks if a request should have a body (GET
and HEAD
requests don’t
have a body).
Kind: instance method of HttpProxy
Returns: boolean
- true
if a request has a body, otherwise false
.
Param | Type | Description |
---|---|---|
method | string |
The HTTP method. |
data | Object.<string, (boolean\|number\|string\|Date)> |
The data to be send with a request. |
HttpProxy~RequestParams : Object
An object representing the complete request parameters used to create and send the HTTP request.
Kind: inner typedef of HttpProxy
Properties
Name | Type | Description |
---|---|---|
method | string |
The HTTP method. |
url | string |
The original URL to which to make the request. |
transformedUrl | string |
The actual URL to which to make the request, created by applying the URL transformer to the original URL. |
data | Object.<string, (boolean\|number\|string\|Date)> |
The request data, sent as query or body. |
options | HttpAgent~RequestOptions |
The high-level request options provided by the HTTP agent. |
HttpProxy~ErrorParams : Object
An object that describes a failed HTTP request, providing information about both the failure reported by the server and how the request has been sent to the server.
Kind: inner typedef of HttpProxy
Properties
Name | Type | Description |
---|---|---|
errorName | string |
An error name. |
status | number |
The HTTP response status code send by the server. |
body | object |
The body of HTTP error response (detailed information). |
cause | Error |
The low-level cause error. |
params | RequestParams |
An object representing the complete request parameters used to create and send the HTTP request. |