@dr.pogodin/react-utils 1.25.6 → 1.26.0

package/src/server/server.ts

@@ -0,0 +1,309 @@
+/**
+ * Creation of standard ExpressJS server for ReactJS apps.
+ */
+
+import { sep } from 'path';
+import { pathToFileURL } from 'url';
+
+import {
+  cloneDeep,
+  mapValues,
+  pick,
+} from 'lodash';
+
+import compression from 'compression';
+import cookieParser from 'cookie-parser';
+import csrf from '@dr.pogodin/csurf';
+
+import express, {
+  type Express,
+  type NextFunction,
+  type Request,
+  type Response,
+} from 'express';
+
+import favicon from 'serve-favicon';
+import helmet, { type HelmetOptions } from 'helmet';
+import loggerMiddleware from 'morgan';
+import requestIp from 'request-ip';
+import { v4 as uuid } from 'uuid';
+import { type Configuration } from 'webpack';
+
+import rendererFactory, {
+  type LoggerI,
+  type OptionsT as RendererOptionsT,
+} from './renderer';
+
+import {
+  CODES,
+  ERRORS,
+  getErrorForCode,
+  newError,
+} from './utils/errors';
+
+export type CspOptionsT =
+Exclude<HelmetOptions['contentSecurityPolicy'], boolean | undefined>;
+
+interface RequestT extends Request {
+  cspNonce: string;
+  nonce: string;
+}
+
+/**
+ * Default Content Security Policy settings.
+ * @ignore
+ */
+const defaultCspSettings = {
+  directives: mapValues(
+    helmet.contentSecurityPolicy.getDefaultDirectives(),
+
+    // 'https:' options (automatic re-write of insecure URLs to secure ones)
+    // is removed to facilitate local development with HTTP server. In cloud
+    // deployments we assume Apache or Nginx server in front of out app takes
+    // care about such re-writes.
+    (array) => (array as string[]).filter((item: string) => item !== 'https:'),
+  ),
+};
+defaultCspSettings.directives['frame-src'] = [
+  "'self'",
+
+  // YouTube domain is whitelisted to allow <YouTubeVideo> component to work
+  // out of box.
+  'https://*.youtube.com',
+];
+defaultCspSettings.directives['script-src'].push("'unsafe-eval'");
+
+// No need for automatic re-writes via Content Security Policy settings:
+// the forefront Apache or Nginx server is supposed to take care of this
+// in production cloud deployments.
+delete defaultCspSettings.directives['upgrade-insecure-requests'];
+
+/**
+ * @category Utilities
+ * @func server/getDefaultCspSettings
+ * @global
+ * @desc
+ * ```js
+ * import { server } from '@dr.pogodin/react-utils';
+ * const { getDefaultCspSettings } from '@dr.pogodin/react-utils';
+ * ```
+ * @return {{
+ *   directives: object
+ * }} A deep copy of default CSP settings object used by `react-utils`,
+ * with the exception of `nonce-xxx` clause in `script-src` directive,
+ * which is added dynamically for each request.
+ */
+export function getDefaultCspSettings() {
+  return cloneDeep(defaultCspSettings);
+}
+
+type ServerT = Express & {
+  logger: LoggerI;
+};
+
+export type OptionsT = RendererOptionsT & {
+  beforeExpressJsError?: (server: ServerT) => Promise<boolean>;
+  beforeExpressJsSetup?: (server: ServerT) => Promise<void>;
+  cspSettingsHook?: (
+    defaultOptions: CspOptionsT,
+    req: Request,
+  ) => CspOptionsT;
+  devMode?: boolean;
+  httpsRedirect?: boolean;
+  onExpressJsSetup?: (server: ServerT) => Promise<void> | void;
+};
+
+export default async function factory(
+  webpackConfig: Configuration,
+  options: OptionsT,
+) {
+  const rendererOps: RendererOptionsT = pick(options, [
+    'Application',
+    'beforeRender',
+    'favicon',
+    'logger',
+    'maxSsrRounds',
+    'noCsp',
+    'ssrTimeout',
+    'staticCacheController',
+    'staticCacheSize',
+  ]);
+  const renderer = rendererFactory(webpackConfig, rendererOps);
+  const { publicPath } = webpackConfig.output!;
+
+  const server = express() as ServerT;
+
+  if (options.beforeExpressJsSetup) {
+    await options.beforeExpressJsSetup(server);
+  }
+
+  if (options.logger) server.logger = options.logger;
+
+  if (options.httpsRedirect) {
+    server.use((req, res, next) => {
+      const schema = req.headers['x-forwarded-proto'];
+      if (schema === 'http') {
+        let url = `https://${req.headers.host}`;
+        if (req.originalUrl !== '/') url += req.originalUrl;
+        return res.redirect(url);
+      }
+      return next();
+    });
+  }
+
+  server.use(compression());
+  server.use(
+    helmet({
+      contentSecurityPolicy: false,
+      crossOriginEmbedderPolicy: false,
+      crossOriginOpenerPolicy: false,
+      crossOriginResourcePolicy: false,
+    }),
+  );
+
+  if (!options.noCsp) {
+    server.use(
+      (req: Request, res: Response, next: NextFunction) => {
+        const req2 = req as RequestT;
+
+        req2.nonce = uuid();
+
+        // TODO: This is deprecated, but it is kept for now for backward
+        // compatibility. Should be removed sometime later.
+        req2.cspNonce = req2.nonce;
+
+        // The deep clone is necessary here to ensure that default value can't be
+        // mutated during request processing.
+        let cspSettings: CspOptionsT = cloneDeep(defaultCspSettings);
+        (cspSettings.directives?.['script-src'] as string[]).push(`'nonce-${req2.nonce}'`);
+        if (options.cspSettingsHook) {
+          cspSettings = options.cspSettingsHook(cspSettings, req);
+        }
+        helmet.contentSecurityPolicy(cspSettings)(req, res, next);
+      },
+    );
+  }
+
+  if (options.favicon) {
+    server.use(favicon(options.favicon));
+  }
+
+  server.use('/robots.txt', (req, res) => res.send('User-agent: *\nDisallow:'));
+
+  server.use(express.json({ limit: '300kb' }));
+  server.use(express.urlencoded({ extended: false }));
+  server.use(cookieParser());
+  server.use(requestIp.mw());
+
+  server.use(csrf({ cookie: true }));
+
+  loggerMiddleware.token(
+    'ip',
+    (req: Request & { clientIp: string }) => req.clientIp,
+  );
+  const FORMAT = ':ip > :status :method :url :response-time ms :res[content-length] :referrer :user-agent';
+  server.use(loggerMiddleware(FORMAT, {
+    stream: {
+      // TODO: This implies the logger is always set. Is it on a higher level?
+      // then mark it as always present.
+      write: options.logger!.info.bind(options.logger),
+    },
+  }));
+
+  // Note: no matter the "public path", we want the service worker, if any,
+  // to be served from the root, to have all web app pages in its scope.
+  // Thus, this setup to serve it. Probably, need some more configuration
+  // for special cases, but this will do for now.
+  server.get('/__service-worker.js', express.static(
+    webpackConfig.output?.path || '',
+    {
+      setHeaders: (res) => res.set('Cache-Control', 'no-cache'),
+    },
+  ));
+
+  /* Setup of Hot Module Reloading for development environment.
+   * These dependencies are not used, nor installed for production use,
+   * hence we should violate some import-related lint rules. */
+  /* eslint-disable global-require */
+  /* eslint-disable import/no-extraneous-dependencies */
+  /* eslint-disable import/no-unresolved */
+  if (options.devMode) {
+    // This is a workaround for SASS bug:
+    // https://github.com/dart-lang/sdk/issues/27979
+    // which manifests itself sometimes when webpack dev middleware is used
+    // (in dev mode), and app modules are imported in some unfortunate ways.
+    if (!global.location) {
+      global.location = {
+        href: `${pathToFileURL(process.cwd()).href}${sep}`,
+      } as Location;
+    }
+
+    const webpack = require('webpack');
+    const webpackDevMiddleware = require('webpack-dev-middleware');
+    const webpackHotMiddleware = require('webpack-hot-middleware');
+    const compiler = webpack(webpackConfig);
+    server.use(webpackDevMiddleware(compiler, {
+      publicPath,
+      serverSideRender: true,
+    }));
+    server.use(webpackHotMiddleware(compiler));
+  }
+  /* eslint-enable global-require */
+  /* eslint-enable import/no-extraneous-dependencies */
+  /* eslint-enable import/no-unresolved */
+
+  server.use(publicPath as string, express.static(webpackConfig.output!.path!));
+
+  if (options.onExpressJsSetup) {
+    await options.onExpressJsSetup(server);
+  }
+  server.use(renderer);
+
+  /* Detects 404 errors, and forwards them to the error handler. */
+  server.use((req, res, next) => {
+    next(newError(ERRORS.NOT_FOUND, CODES.NOT_FOUND));
+  });
+
+  let dontAttachDefaultErrorHandler;
+  if (options.beforeExpressJsError) {
+    dontAttachDefaultErrorHandler = await options.beforeExpressJsError(server);
+  }
+
+  /* Error handler. */
+  if (!dontAttachDefaultErrorHandler) {
+    // TODO: Do we need this error handler at all? It actually seems to do
+    // what the default ExpressJS error handler does anyway, see:
+    // https://expressjs.com/en/guide/error-handling.html
+    //
+    // TODO: It is better to move the default error handler definition
+    // to a stand-alone function at top-level, but the use of options.logger
+    // prevents to do it without some extra refactoring. Should be done sometime
+    // though.
+    server.use((
+      error: any,
+      req: Request,
+      res: Response,
+      next: NextFunction,
+    ) => {
+      // TODO: This is needed to correctly handled any errors thrown after
+      // sending initial response to the client.
+      if (res.headersSent) return next(error);
+
+      const status = error.status || CODES.INTERNAL_SERVER_ERROR;
+      const serverSide = status >= CODES.INTERNAL_SERVER_ERROR;
+
+      // Log server-side errors always, client-side at debug level only.
+      options.logger!.log(serverSide ? 'error' : 'debug', error);
+
+      let message = error.message || getErrorForCode(status);
+      if (serverSide && process.env.NODE_ENV === 'production') {
+        message = ERRORS.INTERNAL_SERVER_ERROR;
+      }
+
+      res.status(status).send(message);
+      return undefined;
+    });
+  }
+
+  return server;
+}

package/src/server/utils/errors.ts

@@ -0,0 +1,135 @@
+/**
+ * @category Utilities
+ * @module server/errors
+ * @desc
+ * ```js
+ * import { server } from '@dr.pogodin/react-utils';
+ * const { errors } = server;
+ * ```
+ * Server-side helpers for error handling.
+ */
+
+import {
+  StatusCodes as CODES,
+  ReasonPhrases as ERRORS,
+  getReasonPhrase as getErrorForCode,
+} from 'http-status-codes';
+
+import joi from 'joi';
+
+/**
+ * @static
+ * @const CODES
+ * @desc An alias for
+ * [StatusCodes object from **http-status-codes** library](https://www.npmjs.com/package/http-status-codes).
+ * It is a map between HTTP status code names and corresponding numeric codes.
+ * @example
+ * import { server } from '@dr.pogodin/react-utils';
+ * const { CODES } = server.errors;
+ * console.log(CODES.BAD_REQUEST); // Prints: 400
+ */
+export { CODES };
+
+/**
+ * @static
+ * @const ERRORS
+ * @desc An alias for
+ * [ReasonPhrases object from **http-status-codes** library](https://www.npmjs.com/package/http-status-codes).
+ * It is a map between HTTP status code names and their pretty-printed forms.
+ * @example
+ * import { server } from '@dr.pogodin/react-utils';
+ * const { ERRORS } = server.errors;
+ * console.log(ERRORS.BAD_REQUEST); // Prints: Bad Request
+ */
+export { ERRORS };
+
+/**
+ * @static
+ * @func getErrorForCode
+ * @desc An alias for
+ * [getReasonPhrase() function from **http-status-codes** library](https://www.npmjs.com/package/http-status-codes).
+ * Given an HTTP code it returns the corresponding error text.
+ * @param {number} code HTTP code.
+ * @return {string} HTTP error text.
+ * @example
+ * import { server } from '@dr.pogodin/react-utils';
+ * console.log(server.errors.getErrorForCode(400)); // Prints: Bad Request
+ */
+export { getErrorForCode };
+
+/**
+ * @static
+ * @const joi
+ * @desc An alias for [Joi library](https://joi.dev/api/?v=17.4.0),
+ * which provides tooling for HTTP request validation. You can use it in any
+ * way you would use that library import.
+ * @example
+ * import { server } from '@dr.pogodin/react-utils';
+ * const { joi } = server.errors;
+ * const requestBodySchema = joi.object({
+ *   sampleKey: joi.string().max(16).required(),
+ * });
+ */
+export { joi };
+
+// TODO: It could accept the status code as a constructor argument.
+class ErrorWithStatus extends Error {
+  status: number = CODES.INTERNAL_SERVER_ERROR;
+}
+
+/**
+ * ```js
+ * import { server } from '@dr.pogodin/react-utils';
+ * const { newError } = server.errors;
+ * ```
+ * Creates a new `Error` object with given message, and HTTP status code
+ * attached as `status` field.
+ * @param {string} message Error message.
+ * @param {number} [statusCode=500] HTTP status code. Defaults to 500 (Internal
+ * Server Error).
+ * @return {Error}
+ */
+export function newError(message: string, statusCode = CODES.INTERNAL_SERVER_ERROR) {
+  const error = new ErrorWithStatus(message);
+  error.status = statusCode;
+  return error;
+}
+
+/**
+ * ```js
+ * import { server } from '@dr.pogodin/react-utils';
+ * const { fail } = server.errors;
+ * ```
+ * Throws an error with given message and HTTP status code.
+ * @param message Error message.
+ * @param [statusCode=500] HTTP error code. Defaults to 500 (Internal
+ * Server Error).
+ */
+export function fail(message: string, statusCode = CODES.INTERNAL_SERVER_ERROR) {
+  throw newError(message, statusCode);
+}
+
+/**
+ * ```js
+ * import { server } from '@dr.pogodin/react-utils';
+ * const { assert } = server.errors;
+ * ```
+ * Validates a value using given Joi schema, and throws an error with given
+ * message and HTTP status code in case of the validation failure.
+ * @param value
+ * @param schema
+ * @param [message] Error message.
+ * @param [statusCode=500] HTTP status code. Defaults to 400 (Bad
+ * Request).
+ */
+export function assert(
+  value: any,
+  schema: joi.AnySchema,
+  message = '',
+  statusCode = CODES.BAD_REQUEST,
+) {
+  const { error } = schema.validate(value, { abortEarly: false });
+  if (error) {
+    fail(message.concat(message ? '\n' : '', error.message), statusCode);
+  }
+}

package/src/server/utils/index.ts

@@ -0,0 +1,3 @@
+// Aggregates utility modules together.
+
+export * as errors from './errors';

package/src/shared/components/Button/index.tsx

@@ -0,0 +1,146 @@
+// The <Button> component implements a standard button / button-like link.
+
+import PT from 'prop-types';
+import { type ReactNode } from 'react';
+
+import Link from 'components/Link';
+
+import themed, { type Theme } from '@dr.pogodin/react-themes';
+
+import defaultTheme from './style.scss';
+
+type PropsT = {
+  active?: boolean;
+  children?: ReactNode;
+  disabled?: boolean;
+  enforceA?: boolean;
+  onClick?: React.MouseEventHandler & React.KeyboardEventHandler;
+  onMouseDown?: React.MouseEventHandler;
+  openNewTab?: boolean;
+  replace?: boolean;
+  theme: Theme & {
+    active?: string;
+    button?: string;
+    disabled?: string;
+  };
+  // TODO: It needs a more precise typing of the object option.
+  to?: object | string;
+};
+
+/* eslint-disable react/function-component-definition */
+const BaseButton: React.FunctionComponent<PropsT> = ({
+  active,
+  children,
+  disabled,
+  enforceA,
+  onClick,
+  onMouseDown,
+  openNewTab,
+  replace,
+  theme,
+  to,
+}) => {
+  let className = theme.button;
+  if (active && theme.active) className += ` ${theme.active}`;
+  if (disabled) {
+    if (theme.disabled) className += ` ${theme.disabled}`;
+    return (
+      <div className={className}>
+        {children}
+      </div>
+    );
+  }
+  if (to) {
+    return (
+      <Link
+        className={className}
+        enforceA={enforceA}
+        onClick={onClick}
+        onMouseDown={onMouseDown}
+        openNewTab={openNewTab}
+        replace={replace}
+        to={to}
+      >
+        {children}
+      </Link>
+    );
+  }
+  return (
+    <div
+      className={className}
+      onClick={onClick}
+      onKeyDown={onClick}
+      onMouseDown={onMouseDown}
+      role="button"
+      tabIndex={0}
+    >
+      {children}
+    </div>
+  );
+};
+
+/**
+ * Button component theme: a map of CSS
+ * class names to append to button elements:
+ * @prop {string} [active] to the root element of active button.
+ * @prop {string} [button] to the root element of any button.
+ * @prop {string} [disabled] to the root element of disabled button.
+ */
+const ThemedButton = themed(BaseButton, 'Button', [
+  'active',
+  'button',
+  'disabled',
+], defaultTheme);
+
+/**
+ * Implements themeable buttons, and button-line links (elements which look
+ * like buttons, but behave as links) in the same uniform manner.
+ * @param {object} [props] Component props.
+ * @param {boolean} [props.active] Set `true` to render the button as
+ * active, even if it is not active otherwise.
+ * @param {boolean} [props.disabled] Set `true` to disable the button.
+ * @param {boolean} [props.enforceA] When the button is rendered as `<Link>`
+ * component, this prop enforces it to be rendered as a simple `<a>` element
+ * (external link), rather than the React router's internal link.
+ * See `<Link>` documentation to learn when links are rendered as `<a>`
+ * by default.
+ * @param {function} [props.onClick] Click event handler.
+ * @param {function} [props.onMouseDown] Mouse down event handler.
+ * @param {boolean} [props.openNewTab] Set `true` to open link in the new tab.
+ * @param {boolean} [props.replace] When the button is rendered as
+ * `<Link>`, and the target URL is internal, this property tells that
+ * the new route should replace the last record in the browser's history,
+ * rather than to be pushed as a new entry into the history stack.
+ * @param {ButtonTheme} [props.theme] _Ad hoc_ button theme.
+ * @param {object|string} [props.to] If specified, the button will be rendered
+ * as `<Link>` (if not disabled), and it will point to the specified location
+ * or URL.
+ * @param {...any} [props....]
+ * [Other properties of themeable components](https://www.npmjs.com/package/@dr.pogodin/react-themes#themed-component-properties)
+ */
+BaseButton.defaultProps = {
+  active: false,
+  children: undefined,
+  disabled: false,
+  enforceA: false,
+  onClick: undefined,
+  onMouseDown: undefined,
+  openNewTab: false,
+  replace: false,
+  to: undefined,
+};
+
+BaseButton.propTypes = {
+  active: PT.bool,
+  children: PT.node,
+  disabled: PT.bool,
+  enforceA: PT.bool,
+  onClick: PT.func,
+  onMouseDown: PT.func,
+  openNewTab: PT.bool,
+  replace: PT.bool,
+  theme: ThemedButton.themeType.isRequired,
+  to: PT.oneOfType([PT.object, PT.string]),
+};
+
+export default ThemedButton;

package/src/shared/components/Button/style.scss

@@ -0,0 +1,53 @@
+/**
+ * The default button theme.
+ */
+
+*,
+.context,
+.ad.hoc {
+  &.button {
+    background-image: linear-gradient(to top, lightgray, white 50%, white);
+    border: solid 1px gray;
+    border-radius: 0.3em;
+    color: inherit;
+    cursor: pointer;
+    display: inline-block;
+    font: inherit;
+    margin: 0.1em;
+    padding: 0.3em 1.2em;
+    text-align: center;
+    text-decoration: none;
+
+    &:visited {
+      color: inherit;
+    }
+
+    &.active,
+    &:active {
+      background-image: linear-gradient(to bottom, lightgray, white 50%, white);
+      box-shadow: inset 0 1px 3px 0 lightgray;
+      border-color: gray;
+    }
+
+    &:focus {
+      box-shadow: 0 0 3px 1px lightblue;
+      border-color: blue;
+      outline: none;
+    }
+  }
+
+  /* Additional styling of disabled buttons. */
+  &.disabled {
+    cursor: not-allowed;
+    opacity: 0.33;
+
+    // Note: this "cancels out" the active state styling of an active button,
+    // which is defined above, thus ensuring a click on disabled button does
+    // not alter its appearance (does not result in visual press).
+    &.active,
+    &:active {
+      background-image: linear-gradient(to top, lightgray, white 50%, white);
+      box-shadow: none;
+    }
+  }
+}