@sima-land/isomorph 11.0.0-alpha.4 → 11.0.0-alpha.40

package/src/preset/isomorphic/utils/index.ts

@@ -0,0 +1,349 @@
+import { SeverityLevel } from '@sentry/browser';
+import Axios, { AxiosRequestConfig } from 'axios';
+import type { Middleware } from 'middleware-axios';
+import type { StrictMap } from '../types';
+import type { ConfigSource } from '../../../config/types';
+import { Logger, Breadcrumb, DetailedError } from '../../../log';
+import {
+  SharedData,
+  DoneSharedData,
+  FailSharedData,
+  LogMiddlewareHandler,
+} from '../../../utils/axios/middleware/log';
+import { applyAxiosDefaults } from '../../../utils/axios/utils';
+import {
+  SagaErrorInfo,
+  SagaInterruptInfo,
+  SagaMiddlewareHandler,
+} from '../../../utils/redux-saga/types';
+
+/** Реализация пула хостов. */
+export class HttpApiHostPool<Key extends string> implements StrictMap<Key> {
+  private map: Record<Key, string>;
+  private source: ConfigSource;
+
+  /**
+   * Конструктор.
+   * @param map Карта "Название api >> Название переменной среды с хостом api".
+   * @param source Источник конфигурации.
+   */
+  constructor(map: Record<Key, string>, source: ConfigSource) {
+    this.map = map;
+    this.source = source;
+  }
+
+  /** @inheritDoc */
+  get(key: Key): string {
+    const variableName = this.map[key];
+
+    if (!variableName) {
+      throw Error(`Known HTTP API not found by key "${key}"`);
+    }
+
+    // "лениво" берём переменную, именно в момент вызова (чтобы не заставлять указывать в сервисах все переменные разом)
+    return this.source.require(variableName);
+  }
+}
+
+/**
+ * Возвращает уровень на основе статуса ответа.
+ * @param status Статус HTTP-ответа.
+ * @return Уровень.
+ */
+export function severityFromStatus(status: unknown): SeverityLevel {
+  let result: SeverityLevel;
+
+  if (typeof status === 'number') {
+    switch (true) {
+      case status >= 200 && status <= 299:
+        result = 'info';
+        break;
+      case status >= 300 && status <= 499:
+        result = 'warning';
+        break;
+      default:
+        result = 'error';
+    }
+  } else {
+    result = 'error';
+  }
+
+  return result;
+}
+
+/**
+ * Обработчик для промежуточного слоя логирования исходящих http-запросов.
+ * Отправляет хлебные крошки и данные ошибки, пригодные для Sentry.
+ */
+export class HttpClientLogging implements LogMiddlewareHandler {
+  protected logger: Logger;
+
+  protected readonly requestInfo: ReturnType<typeof applyAxiosDefaults> & {
+    readyURL: string;
+  };
+
+  /**
+   * Конструктор.
+   * @param logger Logger.
+   * @param data Данные запроса.
+   */
+  constructor(logger: Logger, data: SharedData) {
+    const config = applyAxiosDefaults(data.config, data.defaults);
+
+    this.logger = logger;
+
+    this.requestInfo = {
+      ...config,
+      readyURL: displayUrl(config.baseURL, config.url),
+    };
+  }
+
+  /**
+   * Отправит хлебные крошки перед запросом.
+   */
+  beforeRequest() {
+    const { readyURL, method, params } = this.requestInfo;
+
+    this.logger.info(
+      new Breadcrumb({
+        category: 'http.request',
+        type: 'http',
+        data: {
+          url: readyURL,
+          method,
+          params,
+        },
+        level: 'info',
+      }),
+    );
+  }
+
+  /**
+   * Отправит хлебные крошки после запроса.
+   * @param data Данные ответа.
+   */
+  afterResponse({ response }: DoneSharedData) {
+    const { readyURL, method, params } = this.requestInfo;
+
+    this.logger.info(
+      new Breadcrumb({
+        category: 'http.response',
+        type: 'http',
+        data: {
+          url: readyURL,
+          method,
+          status_code: response.status,
+          params,
+        },
+        level: 'info',
+      }),
+    );
+  }
+
+  /**
+   * Отправит данные ошибки при перехвате.
+   * @param data Данные запроса.
+   */
+  onCatch({ error }: FailSharedData) {
+    if (Axios.isAxiosError(error)) {
+      const { requestInfo } = this;
+      const statusCode = error.response?.status || 'UNKNOWN';
+
+      // @todo выяснить: нужно ли нам отправлять ответы с кодом <500 в Sentry на уровне всех команд
+      // если да то можно добавить метод в духе errorStatusFilter(s => s !== 422)
+      this.logger.error(
+        new DetailedError(
+          `HTTP request failed, status code: ${statusCode}, error message: ${error.message}`,
+          {
+            level: severityFromStatus(error.response?.status),
+            context: [
+              {
+                key: 'Request details',
+                data: {
+                  url: requestInfo.url,
+                  baseURL: requestInfo.baseURL,
+                  method: requestInfo.method,
+                  headers: requestInfo.headers,
+                  data: requestInfo.data,
+                  params: requestInfo.params,
+                },
+              },
+              {
+                key: 'Response details',
+                data: {
+                  data: error.response?.data,
+
+                  // копируем так как в Sentry падает ошибка: **non-serializable** (TypeError: Object.getPrototypeOf(...) is null)
+                  headers: { ...error.response?.headers },
+
+                  error: error.toJSON(),
+                },
+              },
+            ],
+          },
+        ),
+      );
+
+      if (typeof statusCode === 'number') {
+        this.logger.info(
+          new Breadcrumb({
+            category: 'http.response',
+            type: 'http',
+            data: {
+              url: requestInfo.readyURL,
+              method: requestInfo.method,
+              status_code: statusCode,
+              params: requestInfo.params,
+            },
+            level: 'error',
+          }),
+        );
+      }
+    } else {
+      this.logger.error(error);
+    }
+  }
+}
+
+/**
+ * Лог событий запуска и выполнения redux-saga.
+ */
+export class SagaLogging implements SagaMiddlewareHandler {
+  protected logger: Logger;
+
+  /**
+   * @param logger Logger.
+   */
+  constructor(logger: Logger) {
+    this.logger = logger;
+  }
+
+  /**
+   * При получении ошибки выполнения саги передаст ее логгеру ее с данными стека в extra.
+   * @param error Ошибка.
+   * @param info Инфо выполнения саги.
+   */
+  onSagaError(error: Error, info: SagaErrorInfo) {
+    this.logger.error(
+      new DetailedError(error.message, {
+        extra: {
+          key: 'Saga stack',
+          data: info.sagaStack,
+        },
+      }),
+    );
+  }
+
+  /**
+   * При получении ошибки запуска саги передаст ее логгеру.
+   * @param error Ошибка.
+   */
+  onConfigError(error: Error) {
+    this.logger.error(error);
+  }
+
+  /**
+   * При прерывании саги передаст информацию логгеру как ошибку.
+   * @param info Инфо прерывания саги.
+   */
+  onTimeoutInterrupt({ timeout }: SagaInterruptInfo) {
+    this.logger.error(
+      new DetailedError(`Сага прервана по таймауту (${timeout}мс)`, {
+        level: 'warning',
+      }),
+    );
+  }
+}
+
+/** Работа с HTTP-статусами по соглашению. */
+export abstract class HttpStatus {
+  /**
+   * Определяет, является ли переданный статус успешным.
+   * @param status Статус.
+   * @return Признак.
+   */
+  static isOk(status: unknown): boolean {
+    return typeof status === 'number' && status === 200;
+  }
+
+  /**
+   * Определяет, является ли переданный статус успешным POST.
+   * @param status Статус.
+   * @return Признак.
+   */
+  static isPostOk(status: unknown): boolean {
+    return typeof status === 'number' && status === 201;
+  }
+
+  /**
+   * Определяет, является ли переданный статус успешным DELETE.
+   * @param status Статус.
+   * @return Признак.
+   */
+  static isDeleteOk(status: unknown): boolean {
+    return typeof status === 'number' && (status === 204 || status === 200);
+  }
+
+  /**
+   * Возвращает новый промежуточный слой для валидации статуса HTTP-ответа.
+   * Валидация применяется только если в конфиге запроса не указан validateStatus.
+   * @return Промежуточный слой.
+   */
+  static axiosMiddleware(): Middleware<unknown> {
+    return async (config, next, defaults) => {
+      if (config.validateStatus !== undefined || defaults.validateStatus !== undefined) {
+        // если validateStatus указан явно то не применяем валидацию по умолчанию
+        await next(config);
+      } else {
+        let validateStatus: AxiosRequestConfig['validateStatus'] = null;
+
+        switch (config.method?.toLowerCase()) {
+          case 'get':
+          case 'put':
+          case undefined:
+            validateStatus = HttpStatus.isOk;
+            break;
+          case 'post':
+            validateStatus = HttpStatus.isPostOk;
+            break;
+          case 'delete':
+            validateStatus = HttpStatus.isDeleteOk;
+            break;
+        }
+
+        await next({ ...config, validateStatus });
+      }
+    };
+  }
+}
+
+/**
+ * Объединяет значения опций baseURL и url (axios) в одну строку для логирования.
+ * @param baseURL Опция baseURL.
+ * @param url Опция url.
+ * @return Отображение. Не является валидным URL.
+ */
+export function displayUrl(
+  baseURL: AxiosRequestConfig['baseURL'] = '',
+  url: AxiosRequestConfig['url'] = '',
+) {
+  let result: string;
+
+  switch (true) {
+    case Boolean(baseURL && url):
+      result = `${baseURL.replace(/\/$/, '')}/${url.replace(/^\//, '')}`;
+      break;
+    case Boolean(baseURL) && !url:
+      result = baseURL;
+      break;
+    case !baseURL && Boolean(url):
+      result = url;
+      break;
+    case !baseURL && !url:
+    default:
+      result = '[empty]';
+      break;
+  }
+
+  return result;
+}

package/src/preset/node/handler/index.ts

@@ -0,0 +1,46 @@
+import { Preset, createPreset } from '../../../di';
+import { KnownToken } from '../../../tokens';
+import { provideSagaMiddleware, provideHttpClientLogHandler } from '../../isomorphic/providers';
+import { PresetTuner } from '../../isomorphic/types';
+import {
+  provideHttpClientFactory,
+  provideHandlerMain,
+  provideSpecificParams,
+  providePageHelmet,
+  providePageRender,
+} from './providers';
+import { SpecificExtras } from './utils';
+
+/**
+ * Возвращает preset с зависимостями по умолчанию для работы в рамках ответа на http-запрос.
+ * @param customize Получит функцию с помощью которой можно переопределить предустановленные провайдеры.
+ * @todo Возможно стоит переименовать в PresetPageHandler.
+ * @return Preset.
+ */
+export function PresetHandler(customize?: PresetTuner): Preset {
+  // ВАЖНО: используем .set() вместо аргумента defaults функции createPreset из-за скорости
+  const preset = createPreset();
+
+  // saga
+  preset.set(KnownToken.sagaMiddleware, provideSagaMiddleware);
+
+  // http client
+  preset.set(KnownToken.Http.Client.factory, provideHttpClientFactory);
+  preset.set(KnownToken.Http.Client.Middleware.Log.handler, provideHttpClientLogHandler);
+
+  // http handler
+  preset.set(KnownToken.Http.Handler.main, provideHandlerMain);
+  preset.set(KnownToken.Http.Handler.Request.specificParams, provideSpecificParams);
+  preset.set(KnownToken.Http.Handler.Response.specificExtras, () => new SpecificExtras());
+  preset.set(KnownToken.Http.Handler.Page.assets, () => ({ js: '', css: '' }));
+  preset.set(KnownToken.Http.Handler.Page.helmet, providePageHelmet);
+  preset.set(KnownToken.Http.Handler.Page.render, providePageRender);
+
+  if (customize) {
+    customize({ override: preset.set.bind(preset) });
+  }
+
+  return preset;
+}
+
+export { HandlerProvider } from './utils';

package/src/preset/node/handler/providers/index.tsx

@@ -0,0 +1,214 @@
+import { ResponseError, createCookieStore } from '../../../../http';
+import { Resolve } from '../../../../di';
+import { KnownToken } from '../../../../tokens';
+import { getRequestHeaders, tracingMiddleware } from '../../node/utils/http-client';
+import { CreateAxiosDefaults } from 'axios';
+import { create } from 'middleware-axios';
+import { HttpStatus } from '../../../isomorphic/utils';
+import { cookieMiddleware, logMiddleware } from '../../../../utils/axios';
+import { RESPONSE_EVENT_TYPE } from '../../../isomorphic/constants';
+import { ConventionalJson } from '../../../isomorphic/types';
+import { Fragment } from 'react';
+import { HelmetContext, RegularHelmet, getResponseFormat } from '../utils';
+import { renderToString } from 'react-dom/server';
+
+/**
+ * Провайдер фабрики http-клиентов.
+ * @param resolve Функция для получения зависимости по токену.
+ * @return Фабрика.
+ */
+export function provideHttpClientFactory(resolve: Resolve) {
+  // @todo а что если привести все зависимости к виду:
+  // const getAppConfig = resolve.lazy(KnownToken.Config.base);
+
+  const appConfig = resolve(KnownToken.Config.base);
+  const tracer = resolve(KnownToken.Tracing.tracer);
+  const context = resolve(KnownToken.Http.Handler.context);
+  const logHandler = resolve(KnownToken.Http.Client.Middleware.Log.handler);
+
+  // @todo добавить при необходимости (но тогда в логе будет значительно больше ошибок)
+  // можно не отсылать ошибки из клиента если ответ от сервера уже ушел (writableEnded)
+  // const controller = new AbortController();
+  // context.res.on('finish', () => {
+  //   controller.abort();
+  // });
+
+  // ВАЖНО: для всех клиентов в рамках обработчика должно быть одно хранилище cookie
+  const cookieStore = createCookieStore(context.req.header('cookie'));
+
+  cookieStore.subscribe(() => {
+    if (!context.res.writableEnded) {
+      context.res.setHeader('cookie', cookieStore.getCookies());
+    }
+  });
+
+  const defaultHeaders = getRequestHeaders(appConfig, context.req);
+
+  return (config: CreateAxiosDefaults = {}) => {
+    const client = create({
+      ...config,
+      headers: {
+        ...defaultHeaders,
+
+        // @todo убрать as any
+        ...(config.headers as any),
+      },
+    });
+
+    client.use(HttpStatus.axiosMiddleware());
+    client.use(tracingMiddleware(tracer, context.res.locals.tracing.rootContext));
+    client.use(logMiddleware(logHandler));
+    client.use(cookieMiddleware(cookieStore));
+
+    return client;
+  };
+}
+
+/**
+ * Провайдер главной функции обработчика входящего http-запроса.
+ * @param resolve Функция для получения зависимости по токену.
+ * @return Главная функция.
+ */
+export function provideHandlerMain(resolve: Resolve): VoidFunction {
+  const config = resolve(KnownToken.Config.base);
+  const logger = resolve(KnownToken.logger);
+  const assetsInit = resolve(KnownToken.Http.Handler.Page.assets);
+  const render = resolve(KnownToken.Http.Handler.Page.render);
+  const extras = resolve(KnownToken.Http.Handler.Response.specificExtras);
+  const Helmet = resolve(KnownToken.Http.Handler.Page.helmet);
+  const { req, res } = resolve(KnownToken.Http.Handler.context);
+
+  const getAssets = typeof assetsInit === 'function' ? assetsInit : () => assetsInit;
+
+  /**
+   * Рендер JSX-элемента в строку.
+   * @param element Элемент.
+   * @return Строка.
+   */
+  const elementToString = (element: JSX.Element) => {
+    res.emit(RESPONSE_EVENT_TYPE.renderStart);
+    const result = renderToString(element);
+    res.emit(RESPONSE_EVENT_TYPE.renderFinish);
+
+    return result;
+  };
+
+  return async () => {
+    try {
+      const assets = await getAssets();
+      const meta = extras.getMeta();
+
+      const jsx = (
+        <HelmetContext.Provider value={{ title: config.appName, assets }}>
+          <Helmet>{await render()}</Helmet>
+        </HelmetContext.Provider>
+      );
+
+      switch (getResponseFormat(req)) {
+        case 'html': {
+          res.setHeader('simaland-bundle-js', assets.js);
+          res.setHeader('simaland-bundle-css', assets.css);
+
+          if (assets.criticalJs) {
+            res.setHeader('simaland-critical-js', assets.criticalJs);
+          }
+
+          if (assets.criticalCss) {
+            res.setHeader('simaland-critical-css', assets.criticalCss);
+          }
+
+          if (meta) {
+            res.setHeader('simaland-meta', JSON.stringify(meta));
+          }
+
+          // ВАЖНО: DOCTYPE обязательно нужен так как влияет на то как браузер будет парсить html/css
+          // ВАЖНО: DOCTYPE нужен только когда отдаем полноценную страницу
+          if (config.env === 'development') {
+            res.send(`<!DOCTYPE html>${elementToString(jsx)}`);
+          } else {
+            res.send(elementToString(jsx));
+          }
+          break;
+        }
+
+        case 'json': {
+          res.json({
+            markup: elementToString(jsx),
+            bundle_js: assets.js,
+            bundle_css: assets.css,
+            critical_js: assets.criticalJs,
+            critical_css: assets.criticalCss,
+            meta,
+          } satisfies ConventionalJson);
+          break;
+        }
+      }
+    } catch (error) {
+      let message;
+      let statusCode = 500; // по умолчанию, если на этапе подготовки страницы что-то не так, отдаем 500
+
+      if (error instanceof Error) {
+        message = error.message;
+
+        if (error instanceof ResponseError) {
+          statusCode = error.statusCode;
+        }
+      } else {
+        message = String(error);
+      }
+
+      res.status(statusCode).send(message);
+      logger.error(error);
+    }
+  };
+}
+
+/**
+ * Провайдер render-функции.
+ * @return Render-Функция.
+ */
+export function providePageRender() {
+  return () => (
+    <>
+      <h1>Hello, world!</h1>
+      <p>This is a stub page. Define the render component in your handler</p>
+    </>
+  );
+}
+
+/**
+ * Провайдер helmet-компонента. Этот компонент является контейнером для результата render-функции.
+ * @param resolve Функция для получения зависимости по токену.
+ * @return Helmet-компонент.
+ */
+export function providePageHelmet(resolve: Resolve) {
+  const config = resolve(KnownToken.Config.base);
+  const { req } = resolve(KnownToken.Http.Handler.context);
+
+  return config.env === 'development' && getResponseFormat(req) === 'html'
+    ? RegularHelmet
+    : Fragment;
+}
+
+/**
+ * Провайдер специфичных параметров, которые frontend-микросервис будет получать в запросе.
+ * @param resolve Функция для получения зависимости по токену.
+ * @return Параметры.
+ */
+export function provideSpecificParams(resolve: Resolve): Record<string, unknown> {
+  const context = resolve(KnownToken.Http.Handler.context);
+
+  try {
+    const headerValue = context.req.header('simaland-params');
+
+    /**
+     * Node.js переводит в ASCII.
+     * @see {https://github.com/nodejs/node/issues/17390}
+     */
+    const processedValue = headerValue ? Buffer.from(headerValue, 'binary').toString('utf8') : '';
+
+    return processedValue ? JSON.parse(processedValue) : {};
+  } catch {
+    return {};
+  }
+}