@sima-land/isomorph 9.0.7 → 11.0.0-alpha.0

package/src/http-server/middleware/tracing.ts

@@ -0,0 +1,35 @@
+import { RESPONSE_EVENT } from '../constants';
+import { propagation, ROOT_CONTEXT } from '@opentelemetry/api';
+import type { Tracer } from '../../tracer/types';
+import type { Handler } from 'express';
+
+/**
+ * Возвращает новый middleware для трассировки стадий входящего запроса.
+ * @param tracer Tracer.
+ * @return Middleware.
+ */
+export function tracingMiddleware(tracer: Tracer): Handler {
+  return (req, res, next) => {
+    const rootContext = propagation.extract(ROOT_CONTEXT, req.headers);
+    const rootSpan = tracer.startSpan('response', undefined, rootContext);
+
+    res.locals.tracing = {
+      rootSpan,
+      rootContext,
+    };
+
+    res.once(RESPONSE_EVENT.renderStart, () => {
+      res.locals.tracing.renderSpan = tracer.startSpan('render', undefined, rootContext);
+    });
+
+    res.once(RESPONSE_EVENT.renderFinish, () => {
+      res.locals.tracing.renderSpan.end();
+    });
+
+    res.once('finish', () => {
+      rootSpan.end();
+    });
+
+    next();
+  };
+}

package/src/http-server/types.ts

@@ -0,0 +1,29 @@
+import type { Request, Response, NextFunction, Handler, ErrorRequestHandler } from 'express';
+
+export interface ResponseContext {
+  req: Request;
+  res: Response;
+  next: NextFunction;
+}
+
+export interface PageAssets {
+  js: string;
+  css: string;
+}
+
+export interface ConventionalJson {
+  markup: string;
+  bundle_js: string;
+  bundle_css: string;
+  critical_js?: string;
+  critical_css?: string;
+  meta?: any;
+}
+
+export interface DefaultMiddleware {
+  start: Handler[];
+  logging: Handler[];
+  tracing: Handler[];
+  metrics: Handler[];
+  finish: Array<Handler | ErrorRequestHandler>;
+}

package/src/http-server/utils.ts

@@ -0,0 +1,105 @@
+import type { Request, Response } from 'express';
+import type { ConventionalJson, PageAssets } from './types';
+import { isIP } from 'net';
+
+/**
+ * Определяет IP входящего запроса.
+ * @param req Входящий запрос.
+ * @return IP.
+ */
+export function getXClientIp(req: Request): string {
+  const headerValue =
+    req.get('x-client-ip') || req.get('x-forwarded-for') || req.socket.remoteAddress || '';
+
+  return isIP(headerValue) ? headerValue : '';
+}
+
+/**
+ * Определяет служебные заголовки по соглашению.
+ * @param req Входящий запрос.
+ * @return Служебные заголовки.
+ */
+export function getServiceHeaders(req: Request): Record<string, string | undefined> {
+  const result: Record<string, string | undefined> = {};
+
+  for (const [key] of Object.entries(req.headers)) {
+    if (key.toLowerCase().indexOf('simaland-') === 0) {
+      result[key] = req.header(key);
+    }
+  }
+
+  return result;
+}
+
+/* eslint-disable require-jsdoc, jsdoc/require-jsdoc */
+export class PageResponse {
+  private type: 'html' | 'json';
+  private html: string;
+  private assets: PageAssets;
+
+  static create() {
+    return new PageResponse();
+  }
+
+  static defineFormat(req: Request): PageResponse['type'] {
+    let result: PageResponse['type'] = 'html';
+
+    if ((req.header('accept') || '').toLowerCase().includes('application/json')) {
+      result = 'json';
+    }
+
+    return result;
+  }
+
+  constructor() {
+    this.type = 'html';
+    this.html = '';
+    this.assets = { js: '', css: '' };
+  }
+
+  markup(html: string) {
+    this.html = html;
+    return this;
+  }
+
+  script(url: string) {
+    this.assets.js = url;
+    return this;
+  }
+
+  style(url: string) {
+    this.assets.css = url;
+    return this;
+  }
+
+  format(type: PageResponse['type']) {
+    this.type = type;
+    return this;
+  }
+
+  send(res: Response) {
+    switch (this.type) {
+      case 'json': {
+        const result: ConventionalJson = {
+          markup: this.html,
+          bundle_js: this.assets.js,
+          bundle_css: this.assets.css,
+        };
+
+        res.json(result);
+        break;
+      }
+      case 'html': {
+        res.setHeader('simaland-bundle-js', this.assets.js);
+        res.setHeader('simaland-bundle-css', this.assets.css);
+
+        // @todo dev-шаблон?
+        res.send(this.html);
+        break;
+      }
+      default:
+        throw Error(`Unknown response format ${String(this.type)}`);
+    }
+  }
+}
+/* eslint-enable require-jsdoc, jsdoc/require-jsdoc */

package/src/logger/handler/console.ts

@@ -0,0 +1,35 @@
+import type { BaseConfig } from '../../config/types';
+import pino from 'pino';
+import pinoPretty from 'pino-pretty';
+import { LoggerEventHandler } from '../types';
+
+/**
+ * Возвращает новый handler для logger'а для вывода событий в терминал.
+ * @param config Конфиг.
+ * @return Handler.
+ */
+export function createConsoleHandler(config: BaseConfig): LoggerEventHandler {
+  const isProd = config.env === 'production';
+
+  const logger = pino(
+    isProd
+      ? {
+          formatters: {
+            // ВАЖНО: для Fluent необходимо наличие поля level: string
+            level: label => ({ level: label }),
+          },
+        }
+      : pinoPretty({ colorize: true }),
+  );
+
+  return function (event) {
+    switch (event.type) {
+      case 'info':
+        logger.info(event.data);
+        break;
+      case 'error':
+        logger.error(event.data);
+        break;
+    }
+  };
+}

package/src/logger/handler/sentry.ts

@@ -0,0 +1,38 @@
+import type { SentryLib } from '../../error-tracker/types';
+import type { LoggerEventHandler } from '../types';
+import { SentryError } from '../../error-tracker/utils';
+
+/**
+ * Возвращает новый handler для logger'а для отправки событий в Sentry.
+ * @param sentry Набор данных для работы с Sentry.
+ * @return Handler.
+ */
+export function createSentryHandler(sentry: SentryLib): LoggerEventHandler {
+  return event => {
+    if (event.type === 'error') {
+      const error = event.data;
+
+      if (error instanceof SentryError) {
+        const { level, context, extra } = error.data;
+
+        sentry.withScope(scope => {
+          if (level) {
+            scope.setLevel(level);
+          }
+
+          if (context) {
+            scope.setContext(context.key, context.data);
+          }
+
+          if (extra) {
+            scope.setExtra(extra.key, extra.data);
+          }
+
+          sentry.client.captureException(error);
+        });
+      } else {
+        sentry.client.captureException(error);
+      }
+    }
+  };
+}

package/src/logger/index.ts

@@ -0,0 +1,31 @@
+import type { Logger, LoggerEvent, LoggerEventType, LoggerEventHandler } from './types';
+
+/**
+ * Возвращает новый logger - объект для журналирования событий подобно console.
+ * @return Logger.
+ */
+export function createLogger(): Logger {
+  const handlers: LoggerEventHandler[] = [];
+
+  // eslint-disable-next-line require-jsdoc, jsdoc/require-jsdoc
+  function createMethod(type: LoggerEventType) {
+    return function (data: any) {
+      const event: LoggerEvent = { type, data };
+      for (const handler of handlers) {
+        handler(event);
+      }
+    };
+  }
+
+  return {
+    log: createMethod('log'),
+    info: createMethod('info'),
+    warn: createMethod('warn'),
+    error: createMethod('error'),
+    debug: createMethod('debug'),
+
+    subscribe: handler => {
+      handlers.push(handler);
+    },
+  };
+}

package/src/logger/types.ts

@@ -0,0 +1,28 @@
+export type LoggerEventType = 'error' | 'log' | 'info' | 'warn' | 'debug';
+
+export interface LoggerEvent {
+  type: LoggerEventType;
+  data: unknown;
+}
+
+export interface LoggerEventHandler {
+  (event: LoggerEvent): void;
+}
+
+export interface Logger {
+  error(data: any): void;
+  log(data: any): void;
+  info(data: any): void;
+  warn(data: any): void;
+  debug(data: any): void;
+  subscribe(handler: LoggerEventHandler): void;
+}
+
+export interface ConventionalFluentInfo {
+  version: string;
+  latency: number;
+  method: string;
+  remote_ip: string;
+  route: string;
+  status: number;
+}

package/src/metrics/constants.ts

@@ -0,0 +1,4 @@
+export const ConventionalLabels = {
+  HTTP_RESPONSE: ['version', 'route', 'code', 'method'],
+  SSR: ['version', 'route', 'method'],
+} as const;

package/src/metrics/node.ts

@@ -0,0 +1,54 @@
+import express, { Application } from 'express';
+import * as PromClient from 'prom-client';
+import { ConventionalLabels } from './constants';
+
+export interface DefaultNodeMetrics {
+  requestCount: PromClient.Counter<typeof ConventionalLabels.HTTP_RESPONSE[number]>;
+  responseDuration: PromClient.Histogram<typeof ConventionalLabels.HTTP_RESPONSE[number]>;
+  renderDuration: PromClient.Histogram<typeof ConventionalLabels.SSR[number]>;
+}
+
+/**
+ * Возвращает новое express-приложение, настроенное для выдачи информации о метриках.
+ * @return Приложение.
+ */
+export function createMetricsHttpApp(): Application {
+  const app = express();
+
+  PromClient.collectDefaultMetrics();
+
+  app.get('/', async function (req, res) {
+    const metrics = await PromClient.register.metrics();
+
+    res.setHeader('Content-Type', PromClient.register.contentType);
+    res.send(metrics);
+  });
+
+  return app;
+}
+
+/**
+ * Возвращает набор готовых метрик по умолчанию для приложений.
+ * @return Набор метрик.
+ */
+export function createDefaultMetrics(): DefaultNodeMetrics {
+  return {
+    requestCount: new PromClient.Counter({
+      name: 'http_request_count',
+      help: 'Incoming HTTP request count',
+      labelNames: ConventionalLabels.HTTP_RESPONSE,
+    }),
+    responseDuration: new PromClient.Histogram({
+      name: 'http_response_duration_ms',
+      help: 'Duration of incoming HTTP requests in ms',
+      labelNames: ConventionalLabels.HTTP_RESPONSE,
+      buckets: [30, 100, 200, 500, 1000, 2500, 5000, 10000],
+    }),
+    renderDuration: new PromClient.Histogram({
+      name: 'render_duration_ms',
+      help: 'Duration of SSR ms',
+      labelNames: ConventionalLabels.SSR,
+      buckets: [0.1, 15, 50, 100, 250, 500, 800, 1500],
+    }),
+  };
+}

package/src/preset/index.ts

@@ -0,0 +1,24 @@
+import type { Application } from '../container/application';
+import type { Provider, Token } from '../container/types';
+import type { Preset, PresetEntry } from './types';
+
+/**
+ * Возвращает новый "preset" приложения - набор предустановленных компонентов которые можно переопределять.
+ * @param defaults Предустановленные зависимости.
+ * @return Preset.
+ */
+export function createPreset(defaults: PresetEntry[]): Preset {
+  const registry = new Map<Token<any>, Provider<any>>(defaults);
+
+  return {
+    override: <T>(token: Token<T>, provider: Provider<T>) => {
+      registry.set(token, provider);
+    },
+
+    apply: (container: Application) => {
+      for (const [token, provider] of registry) {
+        container.bind(token).toProvider(provider);
+      }
+    },
+  };
+}

package/src/preset/node/index.ts

@@ -0,0 +1,101 @@
+/* eslint-disable require-jsdoc */
+import type { Preset } from '../types';
+import type { Provider } from '../../container/types';
+import type { BaseConfig } from '../../config/types';
+import type { Logger } from '../../logger/types';
+import type { Tracer } from '@opentelemetry/api';
+import type { DefaultMiddleware } from '../../http-server/types';
+import { KnownToken as Token } from '../../tokens';
+import { createPreset } from '..';
+import { createConfigSource } from '../../config/node';
+import { createBaseConfig } from '../../config';
+import { createLogger } from '../../logger';
+import { createTracer } from '../../tracer/node';
+import { createConsoleHandler } from '../../logger/handler/console';
+import { createSentryHandler } from '../../logger/handler/sentry';
+import { createSentryLib } from '../../error-tracker/node';
+import { loggingMiddleware } from '../../http-server/middleware/logging';
+import { tracingMiddleware } from '../../http-server/middleware/tracing';
+import {
+  renderMetricsMiddleware,
+  responseMetricsMiddleware,
+} from '../../http-server/middleware/metrics';
+import { createDefaultMetrics, createMetricsHttpApp } from '../../metrics/node';
+import { JaegerExporter } from '@opentelemetry/exporter-jaeger';
+import { create } from 'middleware-axios';
+import Express from 'express';
+import { Handlers } from '@sentry/node';
+
+/**
+ * Возвращает preset с зависимостями по умолчанию для frontend-микросервисов на Node.js.
+ * @return Preset.
+ */
+export function PresetNode(): Preset {
+  return createPreset([
+    [Token.Config.source, createConfigSource],
+    [Token.Config.base, provideBaseConfig],
+    [Token.logger, provideLogger],
+    [Token.tracer, provideTracer],
+    [Token.Http.Client.factory, () => create],
+    [Token.Http.Server.factory, () => Express],
+    [Token.Http.Server.Defaults.middleware, provideDefaultMiddleware],
+    [Token.Metrics.httpApp, createMetricsHttpApp],
+  ]);
+}
+
+export const provideBaseConfig: Provider<BaseConfig> = resolve => {
+  const source = resolve(Token.Config.source);
+
+  return createBaseConfig(source);
+};
+
+export const provideLogger: Provider<Logger> = resolve => {
+  const source = resolve(Token.Config.source);
+  const config = resolve(Token.Config.base);
+
+  const sentry = createSentryLib({
+    dsn: source.get('SENTRY_DSN'),
+    release: source.get('SENTRY_RELEASE'),
+    environment: source.get('SENTRY_ENVIRONMENT'),
+  });
+
+  const logger = createLogger();
+  logger.subscribe(createConsoleHandler(config));
+  logger.subscribe(createSentryHandler(sentry));
+
+  return logger;
+};
+
+export const provideTracer: Provider<Tracer> = resolve => {
+  const source = resolve(Token.Config.source);
+
+  const exporter = new JaegerExporter({
+    endpoint: source.require('JAEGER_ENDPOINT'),
+  });
+
+  return createTracer(resolve(Token.Config.base), exporter);
+};
+
+export const provideDefaultMiddleware: Provider<DefaultMiddleware> = resolve => {
+  const config = resolve(Token.Config.base);
+  const logger = resolve(Token.logger);
+  const tracer = resolve(Token.tracer);
+
+  const metrics = createDefaultMetrics();
+
+  return {
+    start: [Handlers.requestHandler()],
+    logging: [loggingMiddleware(config, logger)],
+    tracing: [tracingMiddleware(tracer)],
+    metrics: [
+      responseMetricsMiddleware(config, {
+        counter: metrics.requestCount,
+        histogram: metrics.responseDuration,
+      }),
+      renderMetricsMiddleware(config, {
+        histogram: metrics.renderDuration,
+      }),
+    ],
+    finish: [Handlers.errorHandler()],
+  };
+};

package/src/preset/node/response.ts

@@ -0,0 +1,57 @@
+/* eslint-disable require-jsdoc */
+import type { Preset } from '../types';
+import type { Provider } from '../../container/types';
+import type { SagaRunner } from '../../saga-runner/types';
+import { KnownToken } from '../../tokens';
+import { createPreset } from '..';
+import { renderToString } from 'react-dom/server';
+import { createSagaRunner } from '../../saga-runner';
+import { RESPONSE_EVENT } from '../../http-server/constants';
+import { PageResponse } from '../../http-server/utils';
+
+/**
+ * Возвращает preset с зависимостями по умолчанию для работы в рамках ответа на http-запрос.
+ * @return Preset.
+ */
+export function PresetResponse(): Preset {
+  return createPreset([
+    [KnownToken.Response.sagaRunner, provideSagaRunner],
+    [KnownToken.Response.render, provideRender],
+    [KnownToken.Response.main, provideMain],
+  ]);
+}
+
+export const provideSagaRunner: Provider<SagaRunner> = resolve => {
+  const logger = resolve(KnownToken.logger);
+  return createSagaRunner(logger);
+};
+
+export const provideRender: Provider<(el: JSX.Element) => string | Promise<string>> = resolve => {
+  const { res } = resolve(KnownToken.Response.context);
+
+  return function render(element: JSX.Element): string {
+    res.emit(RESPONSE_EVENT.renderStart);
+
+    const result = renderToString(element);
+
+    res.emit(RESPONSE_EVENT.renderFinish);
+
+    return result;
+  };
+};
+
+export const provideMain: Provider<() => void> = resolve => {
+  const context = resolve(KnownToken.Response.context);
+  const assets = resolve(KnownToken.Response.assets);
+  const prepare = resolve(KnownToken.Response.prepare);
+  const render = resolve(KnownToken.Response.render);
+
+  return async function main() {
+    PageResponse.create()
+      .markup(await render(await prepare()))
+      .script(assets.js)
+      .style(assets.css)
+      .format(PageResponse.defineFormat(context.req))
+      .send(context.res);
+  };
+};

package/src/preset/types.ts

@@ -0,0 +1,9 @@
+import type { Application } from '../container/application';
+import type { Token, Provider } from '../container/types';
+
+export type PresetEntry<T = any> = [Token<T>, Provider<T>];
+
+export interface Preset {
+  override: <T>(token: Token<T>, provider: Provider<T>) => void;
+  apply: (application: Application) => void;
+}

package/src/saga-runner/index.ts

@@ -0,0 +1,59 @@
+import type { Store } from '@reduxjs/toolkit';
+import type { Logger } from '../logger/types';
+import type { SagaRunner } from './types';
+import createSagaMiddleware, { Saga, END } from 'redux-saga';
+import { SentryError } from '../error-tracker/utils';
+
+/**
+ * Возвращает новый runner для redux-saga.
+ * @param logger Logger.
+ * @return Runner.
+ */
+export function createSagaRunner(logger: Logger): SagaRunner {
+  const middleware = createSagaMiddleware({
+    onError: (error, { sagaStack }) => {
+      logger.error(
+        new SentryError(error.message, {
+          extra: { key: 'Saga stack', data: sagaStack },
+        }),
+      );
+    },
+  });
+
+  return {
+    middleware,
+
+    // eslint-disable-next-line require-jsdoc, jsdoc/require-jsdoc
+    prepare(store: Store, { timeout }: { timeout?: number } = {}) {
+      return {
+        // eslint-disable-next-line require-jsdoc, jsdoc/require-jsdoc
+        async run<S extends Saga>(saga: S, ...args: Parameters<S>) {
+          let ready = false;
+
+          await Promise.race([
+            // ждем пока сага выполнится
+            middleware
+              .run(saga, ...args)
+              .toPromise()
+              .then(() => {
+                ready = true;
+              }),
+
+            // если сага не выполнилась за положенное время - прерываем
+            typeof timeout === 'number' &&
+              Number.isFinite(timeout) &&
+              new Promise<void>(resolve => {
+                setTimeout(() => {
+                  if (!ready) {
+                    logger.error(Error('Сага прервана по таймауту'));
+                    store.dispatch(END);
+                  }
+                  resolve();
+                }, timeout);
+              }),
+          ]);
+        },
+      };
+    },
+  };
+}

package/src/saga-runner/types.ts

@@ -0,0 +1,13 @@
+import type { Saga, SagaMiddleware } from 'redux-saga';
+import type { Store } from '@reduxjs/toolkit';
+
+export interface SagaRunner {
+  middleware: SagaMiddleware<any>;
+
+  prepare: (
+    store: Store,
+    options?: { timeout?: number },
+  ) => {
+    run: <S extends Saga>(saga: S, ...args: Parameters<S>) => Promise<void>;
+  };
+}