Feature/api_client

jest/__mocks__/ky.js

@@ -0,0 +1,2 @@
+// use ky-universal instead of ky, which is only meant to be used in the browser
+module.exports = require('ky-universal');

jest/jest.config.js

@@ -3,10 +3,13 @@
 
 // Some vendors publish their sources without transpiling. You need to say
 // jest to transpile such files
-const esModules = ['common-tags'];
+const esModules = ['common-tags', 'ky'];
 
 module.exports = {
-  roots: ['<rootDir>/src'],
+  roots: [
+    '<rootDir>/src',
+    '<rootDir>/jest' // allow putting the mocks folder lower down than root https://github.com/facebook/jest/issues/2726#issuecomment-390625860
+  ],
   testMatch: [
     '**/__tests__/**/*.+(ts|tsx|js)',
     '**/?(*.)+(unit|integration).+(spec|test).+(ts|tsx|js)'
@@ -40,9 +43,7 @@ module.exports = {
       '<rootDir>/jest/mocks/fileMock.js',
     'images/hbi-stop-icons': '<rootDir>/jest/mocks/fileMock.js',
     // handle webpack aliases
-    '^~/(.*)$': '<rootDir>/src/$1',
-    // handle ky, see https://github.com/sindresorhus/ky/issues/170
-    '^ky$': require.resolve('ky').replace('index.js', 'umd.js')
+    '^~/(.*)$': '<rootDir>/src/$1'
   },
 
   // The root directory that Jest should scan for tests and modules within
@@ -54,5 +55,5 @@ module.exports = {
 
   // An array of regexp pattern strings that are matched against all source
   // file paths, matched files will skip transformation
-  transformIgnorePatterns: [`<rootDir>/node_modules/(?!${esModules})`]
+  transformIgnorePatterns: [`<rootDir>/node_modules/(?!${esModules.join('|')})`]
 };

package.json

@@ -38,6 +38,7 @@
     "@storybook/react": "^5.3.14",
     "@types/fetch-mock": "^7.3.2",
     "@types/jest": "^24.9.1",
+    "@types/node-fetch": "^2.5.5",
     "@types/prop-types": "^15.7.3",
     "@types/react": "^16.9.32",
     "@types/react-redux": "^7.1.7",
@@ -108,6 +109,7 @@
     "@turf/boolean-within": "^6.0.1",
     "@turf/helpers": "^6.1.4",
     "@turf/length": "^6.0.2",
+    "@types/debug": "^4.1.5",
     "@types/geojson": "^7946.0.7",
     "@types/mapbox-gl": "^1.11.1",
     "@types/node": "^13.11.0",
@@ -129,7 +131,7 @@
     "iframe-resizer-react": "^1.0.3",
     "intersection-observer": "^0.10.0",
     "jsonschema": "^1.2.6",
-    "ky": "^0.17.0",
+    "ky": "^0.19.0",
     "ky-universal": "^0.5.0",
     "lodash.debounce": "^4.0.8",
     "lodash.isequal": "^4.5.0",

src/history.js

@@ -4,19 +4,40 @@ import { createBrowserHistory } from 'history';
 import config from '~/config';
 
 const piwikSiteId = config.piwik.siteId[config.region] || 1;
-const piwik = new ReactPiwik({
-  url: config.piwik.url,
-  siteId: piwikSiteId,
-  ...config.piwik.options
+
+const browserHistory = createBrowserHistory({
+  basename: process.env.BASE_NAME
 });
 
-const history = piwik.connectToHistory(
-  createBrowserHistory({ basename: process.env.BASE_NAME })
-);
+// piwik-react-router has an open issue where it will try and attach a
+// script tag in the dom, which doesn't work in a Jest environment.
+// As a workaround, the resulting error is caught here.
+// See https://github.com/joernroeder/piwik-react-router/issues/48
+
+let history;
+try {
+  const piwik = new ReactPiwik({
+    url: config.piwik.url,
+    siteId: piwikSiteId,
+    ...config.piwik.options
+  });
+
+  history = piwik.connectToHistory(browserHistory);
+} catch (e) {
+  if (e.message === "Cannot read property 'parentNode' of undefined") {
+    history = browserHistory;
+  } else {
+    throw e;
+  }
+}
 
 // used in integration tests
 if (window.Cypress) {
   window.appHistory = history;
 }
 
-export default history;
+// Export history as a constant, even though it was mutable before
+// to handle exception
+const constHistory = history;
+
+export default constHistory;

src/pages/User/UserState.js

@@ -233,3 +233,8 @@ export default function MapStateReducer(state = initialState, action = {}) {
       return state;
   }
 }
+
+// selectors
+export const selectors = {
+  getToken: (state) => state.UserState.token
+};

src/services/api/errors.ts

@@ -0,0 +1,42 @@
+//  TODO: use functions instead of classes to respect eslint, see  https://dev.to/damxipo/custom-exceptions-with-js-3aoc
+
+/**
+ * The api has answered with an error description.
+ */
+class ApiError extends Error {
+  public code: number;
+
+  constructor(message, statusCode = 500) {
+    super(message);
+    this.name = 'ApiError';
+    this.code = statusCode;
+    Object.setPrototypeOf(this, ApiError.prototype);
+  }
+}
+
+/**
+ * Indicates a Read Timeout (it took to long after the last byte has been sent)
+ * or a Connection Timeout (the server never responded)
+ */
+class TimeoutError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'TimeoutError';
+    Object.setPrototypeOf(this, TimeoutError.prototype);
+  }
+}
+
+/**
+ * Communication with the api has failed, usually if
+ * "when a network error is encountered or CORS is misconfigured on the server-side",
+ * see https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
+ */
+class NetworkError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'NetworkError';
+    Object.setPrototypeOf(this, NetworkError.prototype);
+  }
+}
+
+export { ApiError, TimeoutError, NetworkError };

src/services/api/index.ts

@@ -0,0 +1,13 @@
+import request from './request';
+import { get, post, patch } from './shorthands';
+import { ApiError, TimeoutError, NetworkError } from './errors';
+
+export default {
+  request,
+  get,
+  post,
+  patch,
+  ApiError,
+  TimeoutError,
+  NetworkError
+};

src/services/api/mapError.ts

@@ -0,0 +1,71 @@
+import ky from 'ky-universal';
+import debug from 'debug';
+import { ApiError, NetworkError, TimeoutError } from './errors';
+import { FMCError, JSONValue, JSONObject } from './types';
+
+const log = debug('fmc:api:mapError');
+
+/**
+ * Translate errors reported by ky/fetch to a set of custom exceptions
+ * which we can later on use to make decisions on how to handle specific errors.
+ */
+export default async function mapError(e: FMCError): Promise<FMCError> {
+  let errorMessage: string;
+  let statusCode: number;
+
+  // handle network errors (misspelled URL, flaky or no network or CORS problems)
+  if (e.message === 'Failed to fetch') {
+    return new NetworkError(e.message);
+  }
+
+  // handle all other errors
+  switch (e.constructor) {
+    case ky.HTTPError: // a non 2xx error code was found
+      errorMessage = await parseErrorResponse(e.response);
+      statusCode = e.response.status;
+      return new ApiError(errorMessage, statusCode);
+    case ky.TimeoutError:
+      return new TimeoutError(e.message);
+    default:
+      // any other error, just forward it
+      return e;
+  }
+}
+
+/**
+ * Try parsing an error response as JSON or fallback to returning as text
+ *
+ * If a JSON error response contains a field `detail` of string type, its
+ * content is returned as raw text
+ *
+ * @param errorResponse API return value
+ */
+async function parseErrorResponse(
+  errorResponse: Response
+): Promise<string | null> {
+  let errorJson: JSONValue;
+  let errorText: string;
+
+  // try parse error as text and then as JSON to not rely on content-type
+  // definitions response headers
+  try {
+    errorText = await errorResponse.text();
+  } catch (e) {
+    log(e);
+    throw new TypeError('Only JSON and text error responses can be handled');
+  }
+
+  try {
+    errorJson = JSON.parse(errorText);
+  } catch (e) {
+    log('found error response encoded as raw text');
+    return errorText;
+  }
+
+  if (typeof (errorJson as JSONObject)?.detail === 'string') {
+    log('found `detail` field in json response');
+    return (errorJson as JSONObject)?.detail.toString();
+  }
+  log('found json-encoded error response', errorJson);
+  return null;
+}

src/services/api/request.ts

@@ -0,0 +1,113 @@
+/**
+ * Facilitates http request creation by
+ * - offering helper methods with simplified interfaces
+ * - allowing to hook into before/after a request is made or if an error occurs
+ * - doing  preparatory work for network error request handling
+ */
+import ky from 'ky-universal';
+import debug from 'debug';
+import config from '~/config';
+import store from '~/store';
+import { RequestOptions } from './types';
+import { selectors as UserStateSelectors } from '~/pages/User/UserState';
+import mapError from './mapError';
+
+const log = debug('fmc:api:request()');
+
+// setup ky
+
+const configuredKy = ky.create({
+  prefixUrl: config.apiUrl,
+  hooks: {
+    beforeRequest: [
+      // Set authorization headers
+      (req: Request) => {
+        const stateRoot = store.getState();
+        const token = UserStateSelectors.getToken(stateRoot);
+        if (token) {
+          req.headers.set('Authorization', `JWT ${token}`);
+        }
+      }
+    ]
+  }
+});
+
+// Generic Request Handler
+
+const defaultOptions: RequestOptions = {
+  accept: 'json',
+  method: 'get',
+  timeout: 30 * 1000,
+  slowResponseTimeout: 5 * 1000
+};
+
+/**
+ * Send requests with convenience callbacks, FMC auth header, raising fmcErrors
+ *
+ * @example
+ * // Handle server error responses
+ * try {
+ *  const response = await api.request('https://fixmyberlin.de/api/v1/')
+ * } catch (err) {
+ *  if(err instanceof api.ApiError) {
+ *    console.log(err.code)
+ *    // 500
+ *    console.log(err.message)
+ *    // parsed from json or text response body
+ *   }
+ *   throw(error)
+ * }
+ *
+ * @example
+ * // Use callbacks
+ * await api.request(url, {
+ *   onSubmit: () => dispatch(setLoading(true)),
+ *   onFinish: () => dispatch(setLoading(false)),
+ *   onSlowRequest: () => dispatch(setSlowRequestNotice(true))
+ * })
+ *
+ * @param route URL to request
+ * @param options object with options, extending ky's options
+ * @param options.accept expected response body type, either `string` or `json`
+ * @param options.onSubmit function to call before making request
+ * @param options.onFinish function to call after request finishes (successful or not)
+ * @param options.onSlowResponse function to call when request is slow
+ * @param options.slowResponseTimeout value in milliseconds to wait before
+ *  calling onSlowResponse, defaults to 5000
+ */
+export default async function request(
+  route: string,
+  options: RequestOptions = defaultOptions
+): Promise<Response> {
+  let response;
+
+  const {
+    accept = defaultOptions.accept,
+    slowResponseTimeout = defaultOptions.slowResponseTimeout,
+    onSubmit,
+    onFinish,
+    onSlowResponse,
+    ...kyOptions
+  } = options;
+
+  const timeout = setTimeout(() => {
+    if (onSlowResponse) {
+      log('calling slow request handler');
+      onSlowResponse(slowResponseTimeout);
+    }
+  }, slowResponseTimeout);
+
+  if (onSubmit) onSubmit();
+  try {
+    log('sending request', { route, options, accept });
+    response = await configuredKy(route, kyOptions)[accept]();
+  } catch (e) {
+    log('mapping error type', { error: e });
+    throw await mapError(e);
+  } finally {
+    log('finished request');
+    if (onFinish) onFinish();
+    clearTimeout(timeout);
+  }
+  return response;
+}