ngx-network-error

An automatic interceptor to handle HTTP errors and show a dialogs to be nice to the user. Special handling for IBM Analytics (aka Cognos) usecases.

It could also be understood as a general purpose XHR wrapper: sending requests and configurable reacting on result-codes, mime-types and contentChecks.

Usecase(s):

• Send XHR to Server and react on "401 - not Authorized" with reload, Popup-Msg, ...
• Send XHR to Server, results in "200 - ok" then parses the result to contain certain regexed content, e.g. searching for Xml-Key words, CSV headers, ...
• Send XHR to Server and try to fetch some updates, results in "503 - server error", silently retry in the future ... as this update request is not so important

How to video (Spanish) on how to install & use: https://www.youtube.com/watch?v=U8wEdgJwUgA&feature=youtu.be

Installation

npm install -S ngx-network-error

Make sure you are importing HttpClientModule and BrowserAnimationsModule in your application:

import { BrowserAnimationsModule } from '@angular/platform-browser/animations';
import { HttpClientModule } from '@angular/common/http';

@NgModule({
  ...,
  imports: [
    ...,
    BrowserAnimationsModule,
    HttpClientModule
    ...
  ],
  ...
})
export class AppModule { }

Usage

In your app.module.ts import NgxNetworkErrorModule like

import { NgxNetworkErrorModule } from 'ngx-network-error';

@NgModule({
  ...,
  imports: [
    ...,
    BrowserAnimationsModule,
    HttpClientModule,
    NgxNetworkErrorModule.forRoot(),
    ...
  ],
  ...
})
export class AppModule { }

Module options (NgxNetworkErrorConfiguration)

• debug: Enable debugging of plugin
• authType: Default authentication on the application used, it is useful to the call to action, provide 'custom' to provide custom implementation using ErrorStream
• cognosNamespace: Namespace to use in case of Cognos Authentication
• contacts: Contacts information (multiple)¡
• reporting: Reporting information, who or where to report the errors
• silent: If silent is provided true, all failing requests won't show any error dialog or console error
• retry: Provide custom configuration for retrying requests
• language: Provide language for error or login dialogs, can be changed using the utility service and it's English by default
• version: If provided, the version used will be used to for controlling versioned files in disk. It helps refresh files if the version is updated
• customData: Provide custom data

Request options (RequestParams)

You can also provide some parameters at request level, it is needed to change the params key of your HttpClient requests to use the InterceptorParams constructor of our package, this constructor accepts two parameters:

• InterceptorParams: There you can configure which parameters to send to our error handling interceptor.
• HttpParams: There goes the request params you would pass to any HttpClient request.

Example:

import { InterceptorParams } from 'ngx-network-error';
...
getData() {
    return this.http.get(`${myApi}/posts`, {
        params: new InterceptorParams({
            retry: {
              count: 3,
              delay: 1000,
              increment: 500
            },
            contentChecks: {
                headers: {
                    'Content-Type': 'application/json'
                },
                shouldMatchContentType: true
            }
        }, {
            id: 23 // posts?id=23
        })
    })
}
...

Sanity check (ContentChecks)

You can also provide rules in each request to check if the response is valid even when the status code is 200.

Available content checks:

• headers: Object containing headers to compare the response with.
• match: Regex expression or string to check with the body of the response.
• shouldMatchContentType: Can contain any value, if provided the response body will be tried to be parsed as the response header Content-Type. At this moment only these types are supported:
  • application/json
  • application/xml
  • application/csv
  • text/html
  • text/csv

NetworkErrorService

A utitlity service is exposed for the developer to be able to:

• View dictionary of languages
• View the current language used
• Set a language dynamically
• An ErrorStream which emits every error (useful when authType is set to custom)

Interfaces

interface NgxNetworkErrorConfiguration {
    /** Enable debugging of plugin */
    debug?: boolean;
    /** Default authentication on the application used, it is useful to the call to action, provide 'custom' to provide custom implementation using ErrorStream */
    authType?: 'basic' | 'openid' | 'cognos' | 'custom';
    /** Namespace to use in case of Cognos Authentication */
    cognosNamespace?: string;
    /** Contacts information (multiple) */
    contacts?: NetworkErrorContact[];
    /** Reporting information, who or where to report the errors */
    reporting?: NetworkErrorReporting;
    /** If silent is provided true, all failing requests won't show any error dialog or console error */
    silent?: boolean;
    /** Provide custom configuration for retrying requests */
    retry?: NetworkRetry;
    /** Provide language for error or login dialogs, can be changed using the utility service and it's English by default */
    language?: Languages;
    /** Provide any custom data */
    customData?: any;
}
  
interface NetworkRetry {
    /** How many times should the request be retried successfully */
    count?: number;
    /** How many time (milliseconds) to many until next retry */
    delay?: number;
    /** If set to greater than 0 will be added on each retry */
    increment?: number;
}
  
// Contact interface for the developers
// Example: Used in the error dialog
interface NetworkErrorContact {
    /** Email address of the contact */
    email?: string;
    /** Full name of the contact */
    name?: string;
    /** Telephone of the contact (better with country prefix) */
    telephone?: string;
}
  
// Reporting interface for the user
// Example: Used in the interceptor
interface NetworkErrorReporting {
    /** Sentry URL to report the error to */
    sentryDSN?: string;
    /** Email address to report the error to */
    email?: string;
}

/** All the params the developer can tell to the interceptor */
interface RequestParams {
    /** If set true the Error Handling Interceptor won't be used */
    skipInterceptor?: boolean;
    /** Provide configuration for retrying this request, only used if also property important is set to true */
    retry?: NetworkRetry;
    /** If silent is provided true, this request won't show any error dialog or console error */
    silent?: boolean;
    /** Object containing all content checks which should be performed against the response */
    contentChecks?: ContentParams;
    /** If true Disk Cache will be bypassed by adding random parameter to request */
    ignoreDiskCache?: boolean;
    /** If true Service Worker cache will be bypassed by adding ngsw-bypass header */
    ignoreServiceWorkerCache?: boolean;
    /** If true Backend Proxy cache will be bypassed using Cache-Control header */
    ignoreProxyCache?: boolean;
    /** If set true and request fails, it will be retried. Works in combination of retry parameter */
    important?: boolean;
}