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

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>;
+  };
+}

package/src/tokens.ts

@@ -0,0 +1,54 @@
+import { createToken } from './container';
+import type { Application } from 'express';
+import type { DefaultMiddleware, PageAssets, ResponseContext } from './http-server/types';
+import type { SagaRunner } from './saga-runner/types';
+import type { Logger } from './logger/types';
+import type { HttpClientFactory } from './http-client/types';
+import type { ConfigSource, BaseConfig } from './config/types';
+import type { Tracer } from './tracer/types';
+import type { Cache } from './cache/types';
+
+export const KnownToken = {
+  // config
+  Config: {
+    source: createToken<ConfigSource>('config.source'),
+    base: createToken<BaseConfig>('config.base'),
+  },
+
+  // cache
+  cache: createToken<Cache>('cache'),
+
+  // logging
+  logger: createToken<Logger>('logger'),
+
+  // tracing
+  tracer: createToken<Tracer>('tracer'),
+
+  // metrics
+  Metrics: {
+    httpApp: createToken<Application>('metrics.http-app'),
+  },
+
+  // http
+  Http: {
+    Client: {
+      factory: createToken<HttpClientFactory>('http.client.factory'),
+    },
+    Server: {
+      factory: createToken<() => Application>('http.server.factory'),
+      Defaults: {
+        middleware: createToken<DefaultMiddleware>('http.server.defaults.middleware'),
+      },
+    },
+  },
+
+  // scope: page response
+  Response: {
+    context: createToken<ResponseContext>('response/context'),
+    assets: createToken<PageAssets>('response/assets'),
+    prepare: createToken<() => JSX.Element | Promise<JSX.Element>>('response/prepare'),
+    render: createToken<(element: JSX.Element) => string | Promise<string>>('response/render'),
+    main: createToken<() => void>('response/main'),
+    sagaRunner: createToken<SagaRunner>('response/saga-runner'),
+  },
+} as const;

package/src/tracer/node.ts

@@ -0,0 +1,40 @@
+import type { Tracer } from './types';
+import type { BaseConfig } from '../config/types';
+import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node';
+import { BatchSpanProcessor, SpanExporter } from '@opentelemetry/tracing';
+import { SemanticResourceAttributes } from '@opentelemetry/semantic-conventions';
+import { registerInstrumentations } from '@opentelemetry/instrumentation';
+import { ExpressInstrumentation } from '@opentelemetry/instrumentation-express';
+import { HttpInstrumentation } from '@opentelemetry/instrumentation-http';
+import { Resource } from '@opentelemetry/resources';
+import { JaegerPropagator } from '@opentelemetry/propagator-jaeger';
+
+/**
+ * Возвращает новый tracer - объект для трассировки стадий различных процессов.
+ * @param config Конфиг.
+ * @param exporter Экспортер данных трассировки.
+ * @return Tracer.
+ */
+export function createTracer(config: BaseConfig, exporter: SpanExporter): Tracer {
+  // @todo доделать по инструкции: https://selvaganesh93.medium.com/tracing-node-js-application-with-opentelemetry-jaeger-ui-9523c0ac8453
+  const provider = new NodeTracerProvider({
+    resource: new Resource({
+      [SemanticResourceAttributes.SERVICE_NAME]: config.appName,
+      [SemanticResourceAttributes.SERVICE_VERSION]: config.appVersion,
+      [SemanticResourceAttributes.DEPLOYMENT_ENVIRONMENT]: config.env,
+    }),
+  });
+
+  // @todo выяснить, почему не сходятся типы и приходится оставлять as any
+  provider.addSpanProcessor(new BatchSpanProcessor(exporter) as any);
+
+  provider.register({
+    propagator: new JaegerPropagator(),
+  });
+
+  registerInstrumentations({
+    instrumentations: [new ExpressInstrumentation(), new HttpInstrumentation()],
+  });
+
+  return provider.getTracer(config.appName, config.appVersion);
+}

package/src/tracer/types.ts

@@ -0,0 +1,3 @@
+import type { Tracer } from '@opentelemetry/api';
+
+export type { Tracer };