@rsdk/db 5.15.0-next.9 → 5.15.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (141) hide show
  1. package/CHANGELOG.md +4 -0
  2. package/dist/index.d.ts +1 -0
  3. package/dist/index.js +15 -0
  4. package/dist/index.js.map +1 -1
  5. package/dist/metrics/call-then.d.ts +30 -0
  6. package/dist/metrics/call-then.js +91 -0
  7. package/dist/metrics/call-then.js.map +1 -0
  8. package/dist/metrics/clock.d.ts +2 -0
  9. package/dist/metrics/clock.js +9 -0
  10. package/dist/metrics/clock.js.map +1 -0
  11. package/dist/metrics/db-client-metrics.d.ts +85 -0
  12. package/dist/metrics/db-client-metrics.js +164 -0
  13. package/dist/metrics/db-client-metrics.js.map +1 -0
  14. package/dist/metrics/db-metric.d.ts +41 -0
  15. package/dist/metrics/db-metric.js +99 -0
  16. package/dist/metrics/db-metric.js.map +1 -0
  17. package/dist/metrics/db-metrics.config.d.ts +7 -0
  18. package/dist/metrics/db-metrics.config.js +60 -0
  19. package/dist/metrics/db-metrics.config.js.map +1 -0
  20. package/dist/metrics/db-metrics.module-base.d.ts +61 -0
  21. package/dist/metrics/db-metrics.module-base.js +61 -0
  22. package/dist/metrics/db-metrics.module-base.js.map +1 -0
  23. package/dist/metrics/db-metrics.providers.d.ts +66 -0
  24. package/dist/metrics/db-metrics.providers.js +83 -0
  25. package/dist/metrics/db-metrics.providers.js.map +1 -0
  26. package/dist/metrics/detach-group.d.ts +19 -0
  27. package/dist/metrics/detach-group.js +31 -0
  28. package/dist/metrics/detach-group.js.map +1 -0
  29. package/dist/metrics/detach.d.ts +24 -0
  30. package/dist/metrics/detach.js +45 -0
  31. package/dist/metrics/detach.js.map +1 -0
  32. package/dist/metrics/entity-operations.recorder.d.ts +17 -0
  33. package/dist/metrics/entity-operations.recorder.js +28 -0
  34. package/dist/metrics/entity-operations.recorder.js.map +1 -0
  35. package/dist/metrics/events.d.ts +11 -0
  36. package/dist/metrics/events.js +20 -0
  37. package/dist/metrics/events.js.map +1 -0
  38. package/dist/metrics/guards.d.ts +12 -0
  39. package/dist/metrics/guards.js +19 -0
  40. package/dist/metrics/guards.js.map +1 -0
  41. package/dist/metrics/index.d.ts +1 -0
  42. package/dist/metrics/index.js +11 -0
  43. package/dist/metrics/index.js.map +1 -0
  44. package/dist/metrics/instrumentation/pg-pool.instrumentation.d.ts +48 -0
  45. package/dist/metrics/instrumentation/pg-pool.instrumentation.js +117 -0
  46. package/dist/metrics/instrumentation/pg-pool.instrumentation.js.map +1 -0
  47. package/dist/metrics/instrumentation/pool-adapters.d.ts +22 -0
  48. package/dist/metrics/instrumentation/pool-adapters.js +16 -0
  49. package/dist/metrics/instrumentation/pool-adapters.js.map +1 -0
  50. package/dist/metrics/instrumentation/pool-close.d.ts +10 -0
  51. package/dist/metrics/instrumentation/pool-close.js +43 -0
  52. package/dist/metrics/instrumentation/pool-close.js.map +1 -0
  53. package/dist/metrics/instrumentation/pool-scope.d.ts +13 -0
  54. package/dist/metrics/instrumentation/pool-scope.js +3 -0
  55. package/dist/metrics/instrumentation/pool-scope.js.map +1 -0
  56. package/dist/metrics/instrumentation/pool.adapter.d.ts +50 -0
  57. package/dist/metrics/instrumentation/pool.adapter.js +3 -0
  58. package/dist/metrics/instrumentation/pool.adapter.js.map +1 -0
  59. package/dist/metrics/instrumentation/pool.recorder.d.ts +74 -0
  60. package/dist/metrics/instrumentation/pool.recorder.js +125 -0
  61. package/dist/metrics/instrumentation/pool.recorder.js.map +1 -0
  62. package/dist/metrics/instrumentation/query-completion.d.ts +12 -0
  63. package/dist/metrics/instrumentation/query-completion.js +76 -0
  64. package/dist/metrics/instrumentation/query-completion.js.map +1 -0
  65. package/dist/metrics/instrumentation/query.instrumentation.d.ts +35 -0
  66. package/dist/metrics/instrumentation/query.instrumentation.js +85 -0
  67. package/dist/metrics/instrumentation/query.instrumentation.js.map +1 -0
  68. package/dist/metrics/instrumentation/tarn-pool.instrumentation.d.ts +44 -0
  69. package/dist/metrics/instrumentation/tarn-pool.instrumentation.js +95 -0
  70. package/dist/metrics/instrumentation/tarn-pool.instrumentation.js.map +1 -0
  71. package/dist/metrics/instrumentation/transaction-tracker.d.ts +32 -0
  72. package/dist/metrics/instrumentation/transaction-tracker.js +64 -0
  73. package/dist/metrics/instrumentation/transaction-tracker.js.map +1 -0
  74. package/dist/metrics/metric-types.d.ts +17 -0
  75. package/dist/metrics/metric-types.js +3 -0
  76. package/dist/metrics/metric-types.js.map +1 -0
  77. package/dist/metrics/metrics.d.ts +82 -0
  78. package/dist/metrics/metrics.js +269 -0
  79. package/dist/metrics/metrics.js.map +1 -0
  80. package/dist/metrics/plugin-kit.d.ts +12 -0
  81. package/dist/metrics/plugin-kit.js +42 -0
  82. package/dist/metrics/plugin-kit.js.map +1 -0
  83. package/dist/metrics/pool-names.d.ts +47 -0
  84. package/dist/metrics/pool-names.js +44 -0
  85. package/dist/metrics/pool-names.js.map +1 -0
  86. package/dist/metrics/pool-stats.registry.d.ts +25 -0
  87. package/dist/metrics/pool-stats.registry.js +32 -0
  88. package/dist/metrics/pool-stats.registry.js.map +1 -0
  89. package/dist/metrics/scrape-source.registry.d.ts +29 -0
  90. package/dist/metrics/scrape-source.registry.js +55 -0
  91. package/dist/metrics/scrape-source.registry.js.map +1 -0
  92. package/dist/metrics/sql.d.ts +34 -0
  93. package/dist/metrics/sql.js +132 -0
  94. package/dist/metrics/sql.js.map +1 -0
  95. package/package.json +2 -2
  96. package/src/index.ts +1 -0
  97. package/src/metrics/call-then.ts +134 -0
  98. package/src/metrics/clock.ts +5 -0
  99. package/src/metrics/db-client-metrics.spec.ts +1894 -0
  100. package/src/metrics/db-client-metrics.ts +206 -0
  101. package/src/metrics/db-metric.spec.ts +185 -0
  102. package/src/metrics/db-metric.ts +186 -0
  103. package/src/metrics/db-metrics.config.ts +46 -0
  104. package/src/metrics/db-metrics.module-base.spec.ts +91 -0
  105. package/src/metrics/db-metrics.module-base.ts +77 -0
  106. package/src/metrics/db-metrics.providers.spec.ts +182 -0
  107. package/src/metrics/db-metrics.providers.ts +134 -0
  108. package/src/metrics/detach-group.spec.ts +41 -0
  109. package/src/metrics/detach-group.ts +30 -0
  110. package/src/metrics/detach.spec.ts +61 -0
  111. package/src/metrics/detach.ts +57 -0
  112. package/src/metrics/entity-operations.recorder.ts +26 -0
  113. package/src/metrics/events.spec.ts +19 -0
  114. package/src/metrics/events.ts +28 -0
  115. package/src/metrics/guards.spec.ts +20 -0
  116. package/src/metrics/guards.ts +19 -0
  117. package/src/metrics/index.ts +6 -0
  118. package/src/metrics/instrumentation/pg-pool.instrumentation.ts +177 -0
  119. package/src/metrics/instrumentation/pool-adapters.ts +35 -0
  120. package/src/metrics/instrumentation/pool-close.ts +59 -0
  121. package/src/metrics/instrumentation/pool-guards.spec.ts +318 -0
  122. package/src/metrics/instrumentation/pool-scope.ts +14 -0
  123. package/src/metrics/instrumentation/pool.adapter.ts +67 -0
  124. package/src/metrics/instrumentation/pool.recorder.ts +167 -0
  125. package/src/metrics/instrumentation/query-completion.spec.ts +209 -0
  126. package/src/metrics/instrumentation/query-completion.ts +107 -0
  127. package/src/metrics/instrumentation/query.instrumentation.ts +136 -0
  128. package/src/metrics/instrumentation/tarn-pool.instrumentation.ts +138 -0
  129. package/src/metrics/instrumentation/transaction-tracker.ts +103 -0
  130. package/src/metrics/metric-types.ts +36 -0
  131. package/src/metrics/metrics.ts +233 -0
  132. package/src/metrics/plugin-kit.ts +39 -0
  133. package/src/metrics/pool-names.spec.ts +79 -0
  134. package/src/metrics/pool-names.ts +77 -0
  135. package/src/metrics/pool-stats.registry.spec.ts +81 -0
  136. package/src/metrics/pool-stats.registry.ts +54 -0
  137. package/src/metrics/public-api.spec.ts +104 -0
  138. package/src/metrics/scrape-source.registry.spec.ts +59 -0
  139. package/src/metrics/scrape-source.registry.ts +55 -0
  140. package/src/metrics/sql.spec.ts +110 -0
  141. package/src/metrics/sql.ts +172 -0
@@ -0,0 +1,91 @@
1
+ import { Timespan } from '@rsdk/common';
2
+ import { register } from '@rsdk/core';
3
+
4
+ import { DbClientMetrics } from './db-client-metrics';
5
+ import type { DbMetricsConfig } from './db-metrics.config';
6
+ import { DbMetricsModuleBase } from './db-metrics.module-base';
7
+ import type { Detach } from './detach';
8
+ import { EntityOperationsRecorder } from './entity-operations.recorder';
9
+
10
+ class SpecModule extends DbMetricsModuleBase {
11
+ readonly attached = jest.fn<
12
+ void,
13
+ [(detach?: Detach) => void, DbClientMetrics]
14
+ >();
15
+
16
+ constructor(
17
+ client: DbClientMetrics | null,
18
+ entityOperations: EntityOperationsRecorder | null = null,
19
+ ) {
20
+ super(client, entityOperations);
21
+ }
22
+
23
+ recorder(): EntityOperationsRecorder | null {
24
+ return this.entityOperations;
25
+ }
26
+
27
+ protected attach(
28
+ add: (detach?: Detach) => void,
29
+ client: DbClientMetrics,
30
+ ): void {
31
+ this.attached(add, client);
32
+ }
33
+ }
34
+
35
+ describe('DbMetricsModuleBase', () => {
36
+ const client = DbClientMetrics.create(
37
+ {
38
+ slowQueryThreshold: new Timespan(500, 'ms'),
39
+ } as DbMetricsConfig,
40
+ 'svc',
41
+ );
42
+
43
+ afterAll(() => {
44
+ register.clear();
45
+ });
46
+
47
+ it('does not attach when there is no client', () => {
48
+ const module = new SpecModule(null);
49
+
50
+ module.onModuleInit();
51
+ module.onApplicationShutdown();
52
+
53
+ expect(module.attached).not.toHaveBeenCalled();
54
+ });
55
+
56
+ it('attaches once with the injected client', () => {
57
+ const module = new SpecModule(client);
58
+
59
+ module.onModuleInit();
60
+
61
+ expect(module.attached).toHaveBeenCalledTimes(1);
62
+ expect(module.attached.mock.calls[0]![1]).toBe(client);
63
+ });
64
+
65
+ it('detaches everything on shutdown in reverse order', () => {
66
+ const calls: string[] = [];
67
+ const module = new SpecModule(client);
68
+
69
+ module.attached.mockImplementation((add) => {
70
+ add(() => calls.push('first'));
71
+ add(undefined);
72
+ add(() => calls.push('second'));
73
+ });
74
+
75
+ module.onModuleInit();
76
+
77
+ expect(calls).toEqual([]);
78
+
79
+ module.onApplicationShutdown();
80
+ module.onApplicationShutdown();
81
+
82
+ expect(calls).toEqual(['second', 'first']);
83
+ });
84
+
85
+ it('keeps the injected entity operations recorder', () => {
86
+ const recorder = new EntityOperationsRecorder({ inc: jest.fn() });
87
+
88
+ expect(new SpecModule(client, recorder).recorder()).toBe(recorder);
89
+ expect(new SpecModule(client).recorder()).toBeNull();
90
+ });
91
+ });
@@ -0,0 +1,77 @@
1
+ import type { DbClientMetrics } from './db-client-metrics';
2
+ import type { Detach } from './detach';
3
+ import { DetachGroup } from './detach-group';
4
+ import type { EntityOperationsRecorder } from './entity-operations.recorder';
5
+
6
+ /**
7
+ * Базовый класс модуля метрик ORM-плагина. Итог при остановке приложения
8
+ * описан здесь, один раз для всех ORM. Наследник реализует только
9
+ * {@link DbMetricsModuleBase.attach} и не переопределяет `onModuleInit` и
10
+ * `onApplicationShutdown`.
11
+ *
12
+ * Метрики и инструментирование приходят через DI из
13
+ * `dbMetricsModuleProviders`: наследник внедряет `DbClientMetrics` и
14
+ * `EntityOperationsRecorder` через `@Inject(DB_CLIENT_METRICS_TOKEN)` и
15
+ * `@Inject(ENTITY_OPERATIONS_RECORDER_TOKEN)` и передаёт их в конструктор.
16
+ * Классы плагин видит только как типы, так что без токена Nest их не
17
+ * найдёт; к тому же для типа `T | null` он не выводит токен из
18
+ * метаданных. `null` значит, что метрики (или
19
+ * `orm_entity_operations_total`) выключены, — второй проверки конфига здесь
20
+ * нет.
21
+ *
22
+ * Интерфейсы `OnModuleInit` и `OnApplicationShutdown` объявляет наследник:
23
+ * у `@rsdk/db` нет зависимости от Nest, а Nest находит хуки по имени метода
24
+ */
25
+ export abstract class DbMetricsModuleBase {
26
+ private readonly detaches = new DetachGroup();
27
+
28
+ /**
29
+ * @param client инструментирование пулов, запросов и транзакций или
30
+ * `null`, если метрики выключены (`DB_METRICS_ENABLED=false`)
31
+ * @param entityOperations запись `orm_entity_operations_total` или
32
+ * `null`, если метрика выключена
33
+ * (`DB_METRICS_ORM_ENTITY_OPERATIONS_TOTAL_ENABLED`)
34
+ */
35
+ protected constructor(
36
+ private readonly client: DbClientMetrics | null,
37
+ protected readonly entityOperations: EntityOperationsRecorder | null,
38
+ ) {}
39
+
40
+ /**
41
+ * Подключает метрики, если они включены
42
+ */
43
+ onModuleInit(): void {
44
+ if (this.client !== null) {
45
+ this.attach((detach) => this.detaches.add(detach), this.client);
46
+ }
47
+ }
48
+
49
+ /**
50
+ * Снимает всё подключённое в обратном порядке: подводит итог по пулам,
51
+ * выключает subscriber-ы и обёртки.
52
+ *
53
+ * Не `onModuleDestroy`: Nest вызывает его до того, как перестаёт принимать
54
+ * запросы, и транзакция, которая ещё идёт, закоммитилась бы уже после итога
55
+ * по пулу и попала бы в rollback. Если ORM закрыл пул раньше, итог уже
56
+ * подведён. Повторный вызов ничего не делает
57
+ */
58
+ onApplicationShutdown(): void {
59
+ this.detaches.detachAll();
60
+ }
61
+
62
+ /**
63
+ * Подключает метрики ORM: находит пулы и передаёт их в `client`,
64
+ * ставит subscriber-ы и обёртки. Вызывается один раз и только при
65
+ * включённых метриках.
66
+ *
67
+ * @param add принимает detach всего, что подключено: при остановке
68
+ * приложения оно снимается в обратном порядке. `undefined` пропускается,
69
+ * так что можно передать результат подключения, которое не состоялось
70
+ * (например, пул не прошёл проверку)
71
+ * @param client инструментирование, полученное из DI
72
+ */
73
+ protected abstract attach(
74
+ add: (detach?: Detach) => void,
75
+ client: DbClientMetrics,
76
+ ): void;
77
+ }
@@ -0,0 +1,182 @@
1
+ import { Timespan } from '@rsdk/common';
2
+ import { APP_NAME, Counter, register } from '@rsdk/core';
3
+
4
+ import { DbClientMetrics } from './db-client-metrics';
5
+ import { DbMetric } from './db-metric';
6
+ import { DbMetricsConfig } from './db-metrics.config';
7
+ import type { DbMetricProvider } from './db-metrics.providers';
8
+ import {
9
+ DB_CLIENT_METRICS_TOKEN,
10
+ dbMetricsModuleProviders,
11
+ ENTITY_OPERATIONS_RECORDER_TOKEN,
12
+ } from './db-metrics.providers';
13
+ import { EntityOperationsRecorder } from './entity-operations.recorder';
14
+ import {
15
+ DB_CLIENT_METRICS,
16
+ DbClientOperationDuration,
17
+ OrmEntityOperations,
18
+ } from './metrics';
19
+
20
+ const APP = 'svc';
21
+ const EXTRA_NAME = 'spec_db_metrics_providers_total';
22
+ const ENTITY_OPERATIONS_NAME = 'orm_entity_operations_total';
23
+
24
+ @DbMetric('counter', {
25
+ name: EXTRA_NAME,
26
+ help: 'Spec counter',
27
+ labelNames: [],
28
+ })
29
+ class SpecExtra extends Counter<string> {}
30
+
31
+ /**
32
+ * Конфиг без загрузки из окружения
33
+ */
34
+ const config = (
35
+ isEnabled: boolean,
36
+ ormEntityOperationsTotalEnabled: boolean,
37
+ ): DbMetricsConfig =>
38
+ Object.assign(Object.create(DbMetricsConfig.prototype) as DbMetricsConfig, {
39
+ isEnabled,
40
+ ormEntityOperationsTotalEnabled,
41
+ slowQueryThreshold: new Timespan(500, 'ms'),
42
+ });
43
+
44
+ describe('dbMetricsModuleProviders', () => {
45
+ const providers = dbMetricsModuleProviders([SpecExtra]);
46
+ const provided = (token: DbMetricProvider['provide']): DbMetricProvider =>
47
+ providers.find((provider) => provider.provide === token)!;
48
+
49
+ /**
50
+ * Вызывает фабрику провайдера так, как это делает Nest: с конфигом и,
51
+ * если провайдер его внедряет, с `APP_NAME`
52
+ */
53
+ const produce = (
54
+ token: DbMetricProvider['provide'],
55
+ cfg: DbMetricsConfig,
56
+ ): unknown => provided(token).useFactory(cfg, APP);
57
+
58
+ afterEach(() => {
59
+ register.removeSingleMetric(EXTRA_NAME);
60
+ register.removeSingleMetric(ENTITY_OPERATIONS_NAME);
61
+ });
62
+
63
+ it('declares client metrics, extra metrics, OrmEntityOperations and the tokens of their writers', () => {
64
+ expect(providers.map(({ provide }) => provide)).toEqual([
65
+ ...DB_CLIENT_METRICS,
66
+ SpecExtra,
67
+ OrmEntityOperations,
68
+ DB_CLIENT_METRICS_TOKEN,
69
+ ENTITY_OPERATIONS_RECORDER_TOKEN,
70
+ ]);
71
+ expect(provided(DbClientOperationDuration)).toBeDefined();
72
+ expect(provided(SpecExtra)).toBeDefined();
73
+ expect(provided(OrmEntityOperations)).toBeDefined();
74
+ expect(providers.every(({ inject }) => inject[0] === DbMetricsConfig)).toBe(
75
+ true,
76
+ );
77
+ });
78
+
79
+ it('injects APP_NAME only into the DbClientMetrics token provider', () => {
80
+ expect(provided(DB_CLIENT_METRICS_TOKEN).inject).toEqual([
81
+ DbMetricsConfig,
82
+ APP_NAME,
83
+ ]);
84
+ expect(
85
+ providers
86
+ .filter(({ provide }) => provide !== DB_CLIENT_METRICS_TOKEN)
87
+ .every(({ inject }) => inject.length === 1),
88
+ ).toBe(true);
89
+ });
90
+
91
+ it('gives null for every provider when metrics are disabled', () => {
92
+ for (const { provide } of providers) {
93
+ expect(produce(provide, config(false, true))).toBeNull();
94
+ }
95
+ expect(register.getSingleMetric(EXTRA_NAME)).toBeUndefined();
96
+ });
97
+
98
+ it('registers client and extra metrics but not OrmEntityOperations by default', () => {
99
+ const enabled = config(true, false);
100
+
101
+ expect(produce(DbClientOperationDuration, enabled)).toBeInstanceOf(
102
+ DbClientOperationDuration,
103
+ );
104
+ const extra = produce(SpecExtra, enabled);
105
+
106
+ expect(extra).toBeInstanceOf(SpecExtra);
107
+ expect(register.getSingleMetric(EXTRA_NAME)).toBe(extra);
108
+ expect(produce(OrmEntityOperations, enabled)).toBeNull();
109
+ expect(register.getSingleMetric(ENTITY_OPERATIONS_NAME)).toBeUndefined();
110
+ });
111
+
112
+ it.each([
113
+ [false, false],
114
+ [false, true],
115
+ [true, false],
116
+ ])(
117
+ 'gives no OrmEntityOperations and no EntityOperationsRecorder for isEnabled=%p, ormEntityOperationsTotalEnabled=%p',
118
+ (isEnabled, entityOperations) => {
119
+ const cfg = config(isEnabled, entityOperations);
120
+
121
+ expect(produce(OrmEntityOperations, cfg)).toBeNull();
122
+ expect(produce(ENTITY_OPERATIONS_RECORDER_TOKEN, cfg)).toBeNull();
123
+ expect(register.getSingleMetric(ENTITY_OPERATIONS_NAME)).toBeUndefined();
124
+ },
125
+ );
126
+
127
+ it('gives OrmEntityOperations and EntityOperationsRecorder when both flags are on', () => {
128
+ const cfg = config(true, true);
129
+ const metric = produce(OrmEntityOperations, cfg);
130
+
131
+ expect(metric).toBeInstanceOf(OrmEntityOperations);
132
+ expect(register.getSingleMetric(ENTITY_OPERATIONS_NAME)).toBe(metric);
133
+ expect(produce(ENTITY_OPERATIONS_RECORDER_TOKEN, cfg)).toBeInstanceOf(
134
+ EntityOperationsRecorder,
135
+ );
136
+ });
137
+
138
+ it('gives DbClientMetrics only when metrics are enabled', () => {
139
+ expect(produce(DB_CLIENT_METRICS_TOKEN, config(false, true))).toBeNull();
140
+ expect(
141
+ produce(DB_CLIENT_METRICS_TOKEN, config(true, false)),
142
+ ).toBeInstanceOf(DbClientMetrics);
143
+ });
144
+ });
145
+
146
+ const registeredNames = (): string[] =>
147
+ register
148
+ .getMetricsAsArray()
149
+ .map(({ name }) => name)
150
+ .sort();
151
+
152
+ describe('client metrics set', () => {
153
+ beforeEach(() => {
154
+ register.clear();
155
+ });
156
+
157
+ afterAll(() => {
158
+ register.clear();
159
+ });
160
+
161
+ it('DbClientMetrics.create registers exactly the metrics declared as providers', () => {
162
+ // Метрики, которые регистрирует сам DbClientMetrics
163
+ DbClientMetrics.create(config(true, false), APP);
164
+ const created = registeredNames();
165
+
166
+ // Метрики провайдеров, кроме метрик ORM: extra и orm_entity_operations_total
167
+ register.clear();
168
+ for (const { provide, useFactory } of dbMetricsModuleProviders()) {
169
+ if (
170
+ provide !== DB_CLIENT_METRICS_TOKEN &&
171
+ provide !== ENTITY_OPERATIONS_RECORDER_TOKEN &&
172
+ provide !== OrmEntityOperations
173
+ ) {
174
+ useFactory(config(true, false));
175
+ }
176
+ }
177
+ const declared = registeredNames();
178
+
179
+ expect(created).toHaveLength(15);
180
+ expect(created).toEqual(declared);
181
+ });
182
+ });
@@ -0,0 +1,134 @@
1
+ import type { Constructor } from '@rsdk/common';
2
+ import type { AnyMetric } from '@rsdk/core';
3
+ import { APP_NAME } from '@rsdk/core';
4
+
5
+ import { DbClientMetrics } from './db-client-metrics';
6
+ import { resolveDbMetric } from './db-metric';
7
+ import { DbMetricsConfig } from './db-metrics.config';
8
+ import { EntityOperationsRecorder } from './entity-operations.recorder';
9
+ import { DB_CLIENT_METRICS, OrmEntityOperations } from './metrics';
10
+
11
+ /**
12
+ * Токен DI для {@link DbClientMetrics} из {@link dbMetricsModuleProviders}.
13
+ * Плагин внедряет экземпляр через `@Inject(DB_CLIENT_METRICS_TOKEN)`, а сам
14
+ * класс получает из `plugin-kit` только как тип: так фабрика
15
+ * `DbClientMetrics.create` недоступна в обход проверки `DB_METRICS_ENABLED`
16
+ */
17
+ export const DB_CLIENT_METRICS_TOKEN = Symbol('DbClientMetrics');
18
+
19
+ /**
20
+ * Токен DI для {@link EntityOperationsRecorder} из
21
+ * {@link dbMetricsModuleProviders}. Плагин внедряет экземпляр через
22
+ * `@Inject(ENTITY_OPERATIONS_RECORDER_TOKEN)`, а класс получает из
23
+ * `plugin-kit` только как тип, по той же причине, что и
24
+ * {@link DB_CLIENT_METRICS_TOKEN}
25
+ */
26
+ export const ENTITY_OPERATIONS_RECORDER_TOKEN = Symbol(
27
+ 'EntityOperationsRecorder',
28
+ );
29
+
30
+ /**
31
+ * Nest-провайдер модуля метрик ORM: по `DbMetricsConfig` отдаёт метрику,
32
+ * {@link DbClientMetrics} или {@link EntityOperationsRecorder}, а если они
33
+ * выключены — `null`. Метрика объявляется по своему классу, два последних —
34
+ * по токенам {@link DB_CLIENT_METRICS_TOKEN} и
35
+ * {@link ENTITY_OPERATIONS_RECORDER_TOKEN}.
36
+ *
37
+ * Варианты записаны целиком, без вспомогательного generic: тип входит
38
+ * в `plugin-kit` и не должен ссылаться на неэкспортированные типы
39
+ */
40
+ export type DbMetricProvider =
41
+ | {
42
+ provide: Constructor<AnyMetric>;
43
+ inject: (typeof DbMetricsConfig)[];
44
+ useFactory: (config: DbMetricsConfig) => AnyMetric | null;
45
+ }
46
+ | {
47
+ provide: typeof DB_CLIENT_METRICS_TOKEN;
48
+ inject: (typeof DbMetricsConfig | symbol)[];
49
+ useFactory: (
50
+ config: DbMetricsConfig,
51
+ appName: string,
52
+ ) => DbClientMetrics | null;
53
+ }
54
+ | {
55
+ provide: typeof ENTITY_OPERATIONS_RECORDER_TOKEN;
56
+ inject: (typeof DbMetricsConfig)[];
57
+ useFactory: (config: DbMetricsConfig) => EntityOperationsRecorder | null;
58
+ };
59
+
60
+ /**
61
+ * Писать ли `orm_entity_operations_total`: отдельный выключатель метрики
62
+ * работает только при включённых метриках БД
63
+ */
64
+ const entityOperationsEnabled = (config: DbMetricsConfig): boolean =>
65
+ config.isEnabled && config.ormEntityOperationsTotalEnabled;
66
+
67
+ /**
68
+ * Nest-провайдеры метрик: через них метрики попадают в autodoc.
69
+ * Метрика регистрируется в prom-client только когда `when` для конфига
70
+ * приложения вернул `true`, иначе провайдер отдаёт `null`. Сам провайдер
71
+ * объявляется всегда: autodoc читает метрики по объявленным провайдерам.
72
+ *
73
+ * `DbMetricsConfig` в модуль импортировать не нужно: платформа rsdk находит
74
+ * config-секции в `inject` провайдеров и подставляет их сама
75
+ */
76
+ const dbMetricProviders = (
77
+ ctors: readonly Constructor<AnyMetric>[],
78
+ when: (config: DbMetricsConfig) => boolean,
79
+ ): DbMetricProvider[] =>
80
+ ctors.map((ctor) => ({
81
+ provide: ctor,
82
+ inject: [DbMetricsConfig],
83
+ useFactory: (config: DbMetricsConfig): AnyMetric | null =>
84
+ when(config) ? resolveDbMetric(ctor) : null,
85
+ }));
86
+
87
+ /**
88
+ * Провайдеры для модуля метрик ORM: общие метрики пула, запросов и
89
+ * транзакций, метрики самого ORM из `extra`, `orm_entity_operations_total`,
90
+ * а также {@link DbClientMetrics} и {@link EntityOperationsRecorder}.
91
+ *
92
+ * Общие метрики, `extra` и `DbClientMetrics` есть при
93
+ * `DB_METRICS_ENABLED=true`, `orm_entity_operations_total` и
94
+ * `EntityOperationsRecorder` — когда к тому же
95
+ * `DB_METRICS_ORM_ENTITY_OPERATIONS_TOTAL_ENABLED=true`. Иначе провайдер
96
+ * отдаёт `null`, но объявлен всё равно: по нему autodoc находит метрику.
97
+ *
98
+ * `DbClientMetrics` получает `APP_NAME` приложения из DI: с него начинается
99
+ * значение метки `pool`, плагин передаёт только ресурс.
100
+ *
101
+ * Условие «включено» записано только здесь. Модуль метрик внедряет
102
+ * метрики из `extra` через `@Inject(<класс метрики>)`, а `DbClientMetrics` и
103
+ * `EntityOperationsRecorder` — через `@Inject(DB_CLIENT_METRICS_TOKEN)` и
104
+ * `@Inject(ENTITY_OPERATIONS_RECORDER_TOKEN)`, и сам их не создаёт: `null`
105
+ * и значит «выключено»
106
+ *
107
+ * @param extra метрики ORM, объявленные через `@DbMetric`
108
+ */
109
+ export const dbMetricsModuleProviders = (
110
+ extra: readonly Constructor<AnyMetric>[] = [],
111
+ ): DbMetricProvider[] => [
112
+ ...dbMetricProviders(
113
+ [...DB_CLIENT_METRICS, ...extra],
114
+ (config) => config.isEnabled,
115
+ ),
116
+ ...dbMetricProviders([OrmEntityOperations], entityOperationsEnabled),
117
+ {
118
+ provide: DB_CLIENT_METRICS_TOKEN,
119
+ inject: [DbMetricsConfig, APP_NAME],
120
+ useFactory: (
121
+ config: DbMetricsConfig,
122
+ appName: string,
123
+ ): DbClientMetrics | null =>
124
+ config.isEnabled ? DbClientMetrics.create(config, appName) : null,
125
+ },
126
+ {
127
+ provide: ENTITY_OPERATIONS_RECORDER_TOKEN,
128
+ inject: [DbMetricsConfig],
129
+ useFactory: (config: DbMetricsConfig): EntityOperationsRecorder | null =>
130
+ entityOperationsEnabled(config)
131
+ ? EntityOperationsRecorder.create()
132
+ : null,
133
+ },
134
+ ];
@@ -0,0 +1,41 @@
1
+ import { DetachGroup } from './detach-group';
2
+
3
+ describe('DetachGroup', () => {
4
+ it('detaches in reverse order of adding', () => {
5
+ const group = new DetachGroup();
6
+ const calls: string[] = [];
7
+
8
+ group.add(() => calls.push('pool'));
9
+ group.add(() => calls.push('subscriber'));
10
+ group.detachAll();
11
+
12
+ expect(calls).toEqual(['subscriber', 'pool']);
13
+ });
14
+
15
+ it('skips undefined', () => {
16
+ const group = new DetachGroup();
17
+ const detach = jest.fn();
18
+
19
+ group.add(undefined);
20
+ group.add(detach);
21
+ group.add();
22
+
23
+ expect(() => group.detachAll()).not.toThrow();
24
+ expect(detach).toHaveBeenCalledTimes(1);
25
+ });
26
+
27
+ it('detaches each one once', () => {
28
+ const group = new DetachGroup();
29
+ const first = jest.fn();
30
+ const second = jest.fn();
31
+
32
+ group.add(first);
33
+ group.detachAll();
34
+ group.add(second);
35
+ group.detachAll();
36
+ group.detachAll();
37
+
38
+ expect(first).toHaveBeenCalledTimes(1);
39
+ expect(second).toHaveBeenCalledTimes(1);
40
+ });
41
+ });
@@ -0,0 +1,30 @@
1
+ import type { Detach } from './detach';
2
+
3
+ /**
4
+ * Всё, что модуль метрик подключил на время жизни приложения: при остановке
5
+ * снимается одним вызовом {@link DetachGroup.detachAll}
6
+ */
7
+ export class DetachGroup {
8
+ private readonly detaches: Detach[] = [];
9
+
10
+ /**
11
+ * `undefined` пропускается: так можно добавить результат подключения,
12
+ * которое не состоялось (например, пул не прошёл проверку)
13
+ */
14
+ add(detach?: Detach): void {
15
+ if (detach) {
16
+ this.detaches.push(detach);
17
+ }
18
+ }
19
+
20
+ /**
21
+ * Снимает всё в обратном порядке: то, что подключили позже, может
22
+ * опираться на подключённое раньше. Повторный вызов снимает только
23
+ * добавленное после предыдущего
24
+ */
25
+ detachAll(): void {
26
+ for (const detach of this.detaches.splice(0).reverse()) {
27
+ detach();
28
+ }
29
+ }
30
+ }
@@ -0,0 +1,61 @@
1
+ import { replaceMethod } from './detach';
2
+
3
+ const original = (): string => 'original';
4
+ const replacement = (): string => 'replacement';
5
+ const later = (): string => 'later';
6
+
7
+ describe('replaceMethod', () => {
8
+ it('restores an own method', () => {
9
+ const target = { m: original };
10
+ const restore = replaceMethod(target, 'm', replacement);
11
+
12
+ expect(target.m).toBe(replacement);
13
+
14
+ restore();
15
+
16
+ expect(target.m).toBe(original);
17
+ expect(Object.hasOwn(target, 'm')).toBe(true);
18
+ });
19
+
20
+ it('removes the replacement of a prototype method', () => {
21
+ class Target {
22
+ m(): string {
23
+ return 'prototype';
24
+ }
25
+ }
26
+ const target = new Target();
27
+ const restore = replaceMethod(target, 'm', replacement);
28
+
29
+ restore();
30
+
31
+ expect(Object.hasOwn(target, 'm')).toBe(false);
32
+ expect(target.m()).toBe('prototype');
33
+ });
34
+
35
+ it('does not overwrite a later replacement on a second call', () => {
36
+ const target = { m: original };
37
+ const restore = replaceMethod(target, 'm', replacement);
38
+
39
+ restore();
40
+ target.m = later;
41
+ restore();
42
+
43
+ expect(target.m).toBe(later);
44
+ });
45
+
46
+ it('does not delete a later own method of a prototype object on a second call', () => {
47
+ class Target {
48
+ m(): string {
49
+ return 'prototype';
50
+ }
51
+ }
52
+ const target = new Target();
53
+ const restore = replaceMethod(target, 'm', replacement);
54
+
55
+ restore();
56
+ target.m = later;
57
+ restore();
58
+
59
+ expect(target.m).toBe(later);
60
+ });
61
+ });
@@ -0,0 +1,57 @@
1
+ /**
2
+ * Снимает то, что поставил вызов, который его вернул: подписки, обёртки
3
+ * методов, регистрацию. Повторный вызов ничего не делает: это обязана
4
+ * выполнять каждая функция, которая возвращает `Detach`, а не только
5
+ * вызывающий код. Проще всего — обернуть результат в {@link once}.
6
+ *
7
+ * Что именно снимается, описывает функция, которая вернула `Detach`
8
+ */
9
+ export type Detach = () => void;
10
+
11
+ export const noop = (): void => {};
12
+
13
+ /**
14
+ * Вызывает все шаги по порядку при первом вызове результата. Следующие
15
+ * вызовы ничего не делают
16
+ */
17
+ export const once = (...steps: readonly Detach[]): Detach => {
18
+ let done = false;
19
+
20
+ return () => {
21
+ if (done) {
22
+ return;
23
+ }
24
+
25
+ done = true;
26
+ for (const step of steps) {
27
+ step();
28
+ }
29
+ };
30
+ };
31
+
32
+ /**
33
+ * Подменяет метод объекта и возвращает восстановление: собственное свойство
34
+ * получает прежнее значение, а метод из прототипа снова виден через него,
35
+ * потому что подмена удаляется.
36
+ *
37
+ * Восстановление срабатывает один раз: если после него метод подменил
38
+ * кто-то другой, повторный вызов эту подмену не затрёт
39
+ */
40
+ export const replaceMethod = <T extends object, K extends keyof T>(
41
+ target: T,
42
+ key: K,
43
+ replacement: T[K],
44
+ ): Detach => {
45
+ const original = target[key];
46
+ const own = Object.hasOwn(target, key);
47
+
48
+ target[key] = replacement;
49
+
50
+ return once(() => {
51
+ if (own) {
52
+ target[key] = original;
53
+ } else {
54
+ delete target[key];
55
+ }
56
+ });
57
+ };