navi-hey 1.9.0 → 1.9.2
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.
- package/lib/exceptions/config/InvalidMemoryDataStore.js +20 -0
- package/lib/models/configs/MemoryConfig.js +50 -2
- package/lib/registry/MemoryRegistry.js +86 -0
- package/lib/registry/MemoryRegistryInstance.js +57 -0
- package/lib/serializers/MemoryDataSerializer.js +25 -0
- package/lib/server/Router.js +2 -0
- package/lib/server/handlers/memory/MemoryHistoryHandler.js +39 -0
- package/lib/services/application/ApplicationConfigurator.js +6 -1
- package/lib/services/engine/ServerController.js +31 -6
- package/lib/services/memory/MemorySampler.js +86 -0
- package/package.json +1 -1
- package/static/assets/index-C7P-w9r_.js +59 -0
- package/static/assets/{index-Dcv_oCts.css → index-FbZXTjVy.css} +1 -1
- package/static/index.html +2 -2
- package/static/assets/index-C81vj0N0.js +0 -11
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
import { AppError } from '../../common/exceptions/AppError.js';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Thrown when a `web.memory.data_store.interval` config value is not a
|
|
5
|
+
* finite number greater than zero. Failing fast here avoids a sampler
|
|
6
|
+
* `setInterval` that fires at ~1 ms and busy-loops the event loop.
|
|
7
|
+
* @author darthjee
|
|
8
|
+
*/
|
|
9
|
+
class InvalidMemoryDataStore extends AppError {
|
|
10
|
+
/**
|
|
11
|
+
* @param {*} interval - The offending, invalid `data_store.interval` value.
|
|
12
|
+
*/
|
|
13
|
+
constructor(interval) {
|
|
14
|
+
super(`Invalid memory data_store interval: ${JSON.stringify(interval)}. Expected a finite number greater than 0`);
|
|
15
|
+
|
|
16
|
+
this.interval = interval;
|
|
17
|
+
}
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
export { InvalidMemoryDataStore };
|
|
@@ -1,34 +1,55 @@
|
|
|
1
|
+
import { InvalidMemoryDataStore } from '../../exceptions/config/InvalidMemoryDataStore.js';
|
|
1
2
|
import { InvalidMemoryThresholds } from '../../exceptions/config/InvalidMemoryThresholds.js';
|
|
2
3
|
import { MemoryMaximumResolver } from '../../utils/memory/MemoryMaximumResolver.js';
|
|
3
4
|
|
|
4
5
|
const DEFAULT_THRESHOLDS = { low: 25.0, medium: 50.0, high: 75.0, over: 100.0 };
|
|
5
6
|
const THRESHOLD_KEYS = ['low', 'medium', 'high', 'over'];
|
|
7
|
+
const DEFAULT_DATA_STORE = { size: 100, interval: 5, page_size: 20 };
|
|
6
8
|
|
|
7
9
|
/**
|
|
8
10
|
* Represents the `web.memory` configuration: the resolved memory maximum and
|
|
9
11
|
* the percentage thresholds used to derive a status from it.
|
|
12
|
+
*
|
|
13
|
+
* The `data_store` block configures the retained RSS-sampling buffer: `size`
|
|
14
|
+
* readings are kept, sampled every `interval` seconds, so the retained
|
|
15
|
+
* window is approximately `size * interval` (~8 minutes at the defaults of
|
|
16
|
+
* `100` / `5`). `page_size` bounds how many entries a future
|
|
17
|
+
* `/memory/history.json` endpoint returns per request.
|
|
10
18
|
* @author darthjee
|
|
11
19
|
*/
|
|
12
20
|
class MemoryConfig {
|
|
13
21
|
#thresholds;
|
|
14
22
|
#dataStoreSize;
|
|
23
|
+
#dataStoreInterval;
|
|
24
|
+
#dataStorePageSize;
|
|
15
25
|
|
|
16
26
|
/**
|
|
17
27
|
* @param {object} [config={}] - Raw `web.memory` configuration object.
|
|
18
28
|
* @param {number} [config.maximum] - Configured memory maximum, in bytes.
|
|
19
29
|
* @param {object} [config.thresholds={}] - Percentage thresholds (`low`, `medium`, `high`, `over`).
|
|
20
|
-
* @param {object} [config.data_store={}] - Configuration for the memory readings store
|
|
30
|
+
* @param {object} [config.data_store={}] - Configuration for the memory readings store
|
|
31
|
+
* (`{ size=100, interval=5, page_size=20 }`). `size` is the maximum number of readings to
|
|
32
|
+
* retain; `interval` is the number of seconds between RSS samples (must be a finite number
|
|
33
|
+
* greater than 0); `page_size` is the maximum number of entries returned per request by the
|
|
34
|
+
* future `/memory/history.json` endpoint.
|
|
21
35
|
* @param {object} [options={}] - Additional options.
|
|
22
36
|
* @param {{resolve: Function}} [options.resolver] - Resolver used to compute the memory maximum,
|
|
23
37
|
* defaulting to {@link MemoryMaximumResolver}.
|
|
24
38
|
* @throws {InvalidMemoryThresholds} When thresholds are not in strictly ascending order.
|
|
39
|
+
* @throws {InvalidMemoryDataStore} When `data_store.interval` is not a finite number greater than 0.
|
|
25
40
|
*/
|
|
26
41
|
constructor({ maximum, thresholds = {}, data_store: dataStore = {} } = {}, { resolver = MemoryMaximumResolver } = {}) {
|
|
27
42
|
this.#thresholds = { ...DEFAULT_THRESHOLDS, ...thresholds };
|
|
28
43
|
this.#validateThresholds();
|
|
29
44
|
|
|
30
45
|
this.maximum = resolver.resolve(maximum);
|
|
31
|
-
|
|
46
|
+
|
|
47
|
+
const mergedDataStore = { ...DEFAULT_DATA_STORE, ...dataStore };
|
|
48
|
+
|
|
49
|
+
this.#dataStoreSize = mergedDataStore.size;
|
|
50
|
+
this.#dataStoreInterval = mergedDataStore.interval;
|
|
51
|
+
this.#dataStorePageSize = mergedDataStore.page_size;
|
|
52
|
+
this.#validateDataStoreInterval();
|
|
32
53
|
}
|
|
33
54
|
|
|
34
55
|
/**
|
|
@@ -45,6 +66,21 @@ class MemoryConfig {
|
|
|
45
66
|
return this.#dataStoreSize;
|
|
46
67
|
}
|
|
47
68
|
|
|
69
|
+
/**
|
|
70
|
+
* @returns {number} The number of seconds between RSS samples.
|
|
71
|
+
*/
|
|
72
|
+
get dataStoreInterval() {
|
|
73
|
+
return this.#dataStoreInterval;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* @returns {number} The maximum number of entries returned per request by the future
|
|
78
|
+
* `/memory/history.json` endpoint.
|
|
79
|
+
*/
|
|
80
|
+
get dataStorePageSize() {
|
|
81
|
+
return this.#dataStorePageSize;
|
|
82
|
+
}
|
|
83
|
+
|
|
48
84
|
/**
|
|
49
85
|
* Derives a status label from a memory usage percentage, using inclusive
|
|
50
86
|
* (`>=`) boundaries checked from the top down.
|
|
@@ -75,6 +111,18 @@ class MemoryConfig {
|
|
|
75
111
|
}
|
|
76
112
|
}
|
|
77
113
|
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* Validates that `data_store.interval` is a finite number greater than 0.
|
|
117
|
+
* @returns {void}
|
|
118
|
+
* @throws {InvalidMemoryDataStore} When the interval is not a finite number greater than 0.
|
|
119
|
+
* @private
|
|
120
|
+
*/
|
|
121
|
+
#validateDataStoreInterval() {
|
|
122
|
+
if (!Number.isFinite(this.#dataStoreInterval) || this.#dataStoreInterval <= 0) {
|
|
123
|
+
throw new InvalidMemoryDataStore(this.#dataStoreInterval);
|
|
124
|
+
}
|
|
125
|
+
}
|
|
78
126
|
}
|
|
79
127
|
|
|
80
128
|
export { MemoryConfig };
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
import { MemoryRegistryInstance } from './MemoryRegistryInstance.js';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* MemoryRegistry is a static singleton facade for the application's process-wide
|
|
5
|
+
* memory-reading history (see {@link MemoryRegistryInstance}).
|
|
6
|
+
*
|
|
7
|
+
* Call `MemoryRegistry.build({ retention })` once during application bootstrap.
|
|
8
|
+
* Use `MemoryRegistry.reset()` in tests to restore a clean state between examples.
|
|
9
|
+
*
|
|
10
|
+
* Strictness is intentionally asymmetric: `build` and the read helper (`getEntries`)
|
|
11
|
+
* throw when the registry has not been built, while the write helper (`add`) silently
|
|
12
|
+
* no-ops so the sampler can call it unconditionally without every spec having to build
|
|
13
|
+
* the registry first.
|
|
14
|
+
*
|
|
15
|
+
* The facade is deliberately minimal (`build` / `reset` / `add` / `getEntries`) — see
|
|
16
|
+
* the parent issue's _Facade surface_ for why the extra `EmissionRegistry`-style read
|
|
17
|
+
* helpers (`getEntryById`, `clear`, `counts`) are not reproduced here.
|
|
18
|
+
* @author darthjee
|
|
19
|
+
*/
|
|
20
|
+
class MemoryRegistry {
|
|
21
|
+
static #instance = null;
|
|
22
|
+
|
|
23
|
+
/**
|
|
24
|
+
* Creates and stores the singleton instance.
|
|
25
|
+
* @param {object} [options={}] - Options.
|
|
26
|
+
* @param {number} [options.retention] - Maximum number of memory readings to retain.
|
|
27
|
+
* @returns {MemoryRegistryInstance} The created instance.
|
|
28
|
+
* @throws {Error} If build() has already been called without a preceding reset().
|
|
29
|
+
*/
|
|
30
|
+
static build({ retention } = {}) {
|
|
31
|
+
if (MemoryRegistry.#instance) {
|
|
32
|
+
throw new Error('MemoryRegistry.build() has already been called. Call reset() first.');
|
|
33
|
+
}
|
|
34
|
+
MemoryRegistry.#instance = new MemoryRegistryInstance({ retention });
|
|
35
|
+
return MemoryRegistry.#instance;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Destroys the singleton instance. Intended for test teardown.
|
|
40
|
+
* @returns {void}
|
|
41
|
+
*/
|
|
42
|
+
static reset() {
|
|
43
|
+
MemoryRegistry.#instance = null;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
/**
|
|
47
|
+
* Records a new memory reading. No-ops when the registry has not been built.
|
|
48
|
+
* @param {number} value - The raw RSS reading, in bytes.
|
|
49
|
+
* @param {number} percentage - `value` as a percentage of the configured memory maximum.
|
|
50
|
+
* @returns {void}
|
|
51
|
+
*/
|
|
52
|
+
static add(value, percentage) {
|
|
53
|
+
if (!MemoryRegistry.#instance) return;
|
|
54
|
+
MemoryRegistry.#instance.add(value, percentage);
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
/**
|
|
58
|
+
* Gets memory entries oldest-first, optionally filtered to entries newer than lastId.
|
|
59
|
+
*
|
|
60
|
+
* Consumer contract quirk: an empty array is returned both when the caller is
|
|
61
|
+
* caught up *and* when its `lastId` has aged out of the retention window — see
|
|
62
|
+
* {@link MemoryRegistryInstance#getEntries}.
|
|
63
|
+
* @param {object} [options={}] - Query options.
|
|
64
|
+
* @param {number|string} [options.lastId] - When provided, returns only entries newer than this ID.
|
|
65
|
+
* @returns {Array<import('../utils/memory/MemoryData.js').MemoryData>} Array of entries, oldest-first.
|
|
66
|
+
* @throws {Error} If build() has not been called.
|
|
67
|
+
*/
|
|
68
|
+
static getEntries({ lastId } = {}) {
|
|
69
|
+
return MemoryRegistry.#getInstance().getEntries({ lastId });
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
/**
|
|
73
|
+
* Returns the singleton instance, throwing if not yet built.
|
|
74
|
+
* @returns {MemoryRegistryInstance} The singleton instance.
|
|
75
|
+
* @throws {Error} If build() has not been called.
|
|
76
|
+
* @private
|
|
77
|
+
*/
|
|
78
|
+
static #getInstance() {
|
|
79
|
+
if (!MemoryRegistry.#instance) {
|
|
80
|
+
throw new Error('MemoryRegistry has not been built. Call MemoryRegistry.build() first.');
|
|
81
|
+
}
|
|
82
|
+
return MemoryRegistry.#instance;
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
export { MemoryRegistry };
|
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
import { LogFilter } from '../utils/logging/LogFilter.js';
|
|
2
|
+
import { MemoryDataStore } from '../utils/memory/MemoryDataStore.js';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Holds a single MemoryDataStore for the MemoryRegistry singleton. Exposes a write
|
|
6
|
+
* helper (`add`) and a read helper (`getEntries`) that delegate to the store. Not
|
|
7
|
+
* exported for direct use; accessed only via MemoryRegistry.
|
|
8
|
+
* @author darthjee
|
|
9
|
+
*/
|
|
10
|
+
class MemoryRegistryInstance {
|
|
11
|
+
#store;
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* Creates a new MemoryRegistryInstance.
|
|
15
|
+
* @param {object} [options={}] - Options for the store.
|
|
16
|
+
* @param {number} [options.retention] - Maximum number of memory readings to retain.
|
|
17
|
+
*/
|
|
18
|
+
constructor({ retention } = {}) {
|
|
19
|
+
this.#store = new MemoryDataStore(retention);
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Returns the underlying MemoryDataStore instance.
|
|
24
|
+
* @returns {MemoryDataStore} The underlying MemoryDataStore instance.
|
|
25
|
+
*/
|
|
26
|
+
get store() {
|
|
27
|
+
return this.#store;
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Records a new memory reading.
|
|
32
|
+
* @param {number} value - The raw RSS reading, in bytes.
|
|
33
|
+
* @param {number} percentage - `value` as a percentage of the configured memory maximum.
|
|
34
|
+
* @returns {import('../utils/memory/MemoryData.js').MemoryData} The created memory entry.
|
|
35
|
+
*/
|
|
36
|
+
add(value, percentage) {
|
|
37
|
+
return this.#store.add(value, percentage);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/**
|
|
41
|
+
* Gets memory entries oldest-first, optionally filtered to entries newer than lastId.
|
|
42
|
+
*
|
|
43
|
+
* Consumer contract quirk: an empty array is returned both when the caller is
|
|
44
|
+
* caught up *and* when its `lastId` has aged out of the retention window (older
|
|
45
|
+
* than `size * interval`) — the two are indistinguishable from the return value
|
|
46
|
+
* alone. Callers seeing a persistent empty response after a gap should reseed
|
|
47
|
+
* from the full history.
|
|
48
|
+
* @param {object} [options={}] - Query options.
|
|
49
|
+
* @param {number|string} [options.lastId] - When provided, returns only entries newer than this ID.
|
|
50
|
+
* @returns {Array<import('../utils/memory/MemoryData.js').MemoryData>} Array of entries, oldest-first.
|
|
51
|
+
*/
|
|
52
|
+
getEntries({ lastId } = {}) {
|
|
53
|
+
return new LogFilter(this.#store.getEntries()).filter({ lastId });
|
|
54
|
+
}
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export { MemoryRegistryInstance };
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
import { Serializer } from './Serializer.js';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Serializes one or more MemoryData instances into plain data objects.
|
|
5
|
+
* @augments Serializer
|
|
6
|
+
* @author darthjee
|
|
7
|
+
*/
|
|
8
|
+
class MemoryDataSerializer extends Serializer {
|
|
9
|
+
/**
|
|
10
|
+
* Serializes a single MemoryData instance.
|
|
11
|
+
*
|
|
12
|
+
* @param {import('../utils/memory/MemoryData.js').MemoryData} entry - The memory entry to serialize.
|
|
13
|
+
* @returns {{ id: number, value: number, percentage: number, timestamp: string }} Plain object representation of the memory entry.
|
|
14
|
+
*/
|
|
15
|
+
static _serializeObject(entry) {
|
|
16
|
+
return {
|
|
17
|
+
id: entry.id,
|
|
18
|
+
value: entry.value,
|
|
19
|
+
percentage: entry.percentage,
|
|
20
|
+
timestamp: entry.timestamp.toISOString(),
|
|
21
|
+
};
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export { MemoryDataSerializer };
|
package/lib/server/Router.js
CHANGED
|
@@ -23,6 +23,7 @@ import { JobRetryHandler } from './handlers/jobs/JobRetryHandler.js';
|
|
|
23
23
|
import { JobsHandler } from './handlers/jobs/JobsHandler.js';
|
|
24
24
|
import { LinksHandler } from './handlers/LinksHandler.js';
|
|
25
25
|
import { LogsHandler } from './handlers/LogsHandler.js';
|
|
26
|
+
import { MemoryHistoryHandler } from './handlers/memory/MemoryHistoryHandler.js';
|
|
26
27
|
import { MemoryStatusHandler } from './handlers/memory/MemoryStatusHandler.js';
|
|
27
28
|
import { SettingsHandler } from './handlers/SettingsHandler.js';
|
|
28
29
|
import { StatsHandler } from './handlers/StatsHandler.js';
|
|
@@ -69,6 +70,7 @@ class Router {
|
|
|
69
70
|
'/job/:id.json': new HandlerConfig(JobHandler),
|
|
70
71
|
'/engine/status': new HandlerConfig(EngineStatusHandler),
|
|
71
72
|
'/memory/status.json': new HandlerConfig(MemoryStatusHandler, [this.#webConfig.memory]),
|
|
73
|
+
'/memory/history.json': new HandlerConfig(MemoryHistoryHandler, this.#webConfig.memory?.dataStorePageSize),
|
|
72
74
|
'/logs.json': new HandlerConfig(LogsHandler, this.#webConfig.logsPageSize),
|
|
73
75
|
'/emissions.json': new HandlerConfig(EmissionsHandler, this.#webConfig.logsPageSize),
|
|
74
76
|
'/extractions.json': new HandlerConfig(ExtractionsHandler, this.#webConfig.logsPageSize),
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { RequestHandler } from '../../../common/server/RequestHandler.js';
|
|
2
|
+
import { MemoryRegistry } from '../../../registry/MemoryRegistry.js';
|
|
3
|
+
import { MemoryDataSerializer } from '../../../serializers/MemoryDataSerializer.js';
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Executes request-handling behaviour for GET /memory/history.json.
|
|
7
|
+
* Returns a paginated, `last_id`-cursored list of serialized memory readings.
|
|
8
|
+
* @author darthjee
|
|
9
|
+
*/
|
|
10
|
+
class MemoryHistoryHandler extends RequestHandler {
|
|
11
|
+
#request;
|
|
12
|
+
#response;
|
|
13
|
+
#pageSize;
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* @param {object} request - The Express request object.
|
|
17
|
+
* @param {object} response - The Express response object.
|
|
18
|
+
* @param {number} pageSize - Maximum number of memory entries to return.
|
|
19
|
+
*/
|
|
20
|
+
constructor(request, response, pageSize) {
|
|
21
|
+
super();
|
|
22
|
+
this.#request = request;
|
|
23
|
+
this.#response = response;
|
|
24
|
+
this.#pageSize = pageSize;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* Responds with a paginated JSON array of memory entries.
|
|
29
|
+
* @returns {void}
|
|
30
|
+
*/
|
|
31
|
+
handle() {
|
|
32
|
+
const { last_id: lastId } = this.#request.query;
|
|
33
|
+
const entries = MemoryRegistry.getEntries({ lastId });
|
|
34
|
+
|
|
35
|
+
this.#response.json(MemoryDataSerializer.serialize(entries.slice(0, this.#pageSize)));
|
|
36
|
+
}
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
export { MemoryHistoryHandler };
|
|
@@ -4,10 +4,11 @@ import { Config } from '../../models/configs/Config.js';
|
|
|
4
4
|
import { EmissionRegistry } from '../../registry/EmissionRegistry.js';
|
|
5
5
|
import { ExtractionRegistry } from '../../registry/ExtractionRegistry.js';
|
|
6
6
|
import { LogRegistry } from '../../registry/LogRegistry.js';
|
|
7
|
+
import { MemoryRegistry } from '../../registry/MemoryRegistry.js';
|
|
7
8
|
|
|
8
9
|
/**
|
|
9
10
|
* ApplicationConfigurator loads the application configuration from disk and
|
|
10
|
-
* bootstraps the log, emission and
|
|
11
|
+
* bootstraps the log, emission, extraction and memory registries that depend on it.
|
|
11
12
|
* @author darthjee
|
|
12
13
|
*/
|
|
13
14
|
class ApplicationConfigurator {
|
|
@@ -28,6 +29,10 @@ class ApplicationConfigurator {
|
|
|
28
29
|
EmissionRegistry.build({ retention: config.emitConfig.size });
|
|
29
30
|
ExtractionRegistry.build({ retention: config.extractionConfig.size });
|
|
30
31
|
|
|
32
|
+
if (config.webConfig) {
|
|
33
|
+
MemoryRegistry.build({ retention: config.webConfig.memory.dataStoreSize });
|
|
34
|
+
}
|
|
35
|
+
|
|
31
36
|
return new ConfigStore({
|
|
32
37
|
config,
|
|
33
38
|
bufferedLogger: logRegistry.bufferedLogger,
|
|
@@ -1,25 +1,30 @@
|
|
|
1
1
|
import { WebServer } from '../../server/WebServer.js';
|
|
2
|
+
import { MemorySampler } from '../memory/MemorySampler.js';
|
|
2
3
|
|
|
3
4
|
/**
|
|
4
5
|
* ServerController owns construction and lifecycle delegation for the optional
|
|
5
|
-
* `WebServer` on behalf of `ApplicationInstance`,
|
|
6
|
-
* `EngineController` wraps `Engine`.
|
|
6
|
+
* `WebServer` (and its `MemorySampler`) on behalf of `ApplicationInstance`,
|
|
7
|
+
* mirroring the way `EngineController` wraps `Engine`.
|
|
7
8
|
* @author darthjee
|
|
8
9
|
*/
|
|
9
10
|
class ServerController {
|
|
10
11
|
#webServer;
|
|
12
|
+
#sampler;
|
|
11
13
|
|
|
12
14
|
/**
|
|
13
15
|
* @param {object} [params={}] - Dependency injection parameters.
|
|
14
16
|
* @param {WebServer} [params.webServer] - Wrapped web server instance (injected for testing).
|
|
17
|
+
* @param {MemorySampler} [params.sampler] - Wrapped memory sampler instance (injected for testing).
|
|
15
18
|
*/
|
|
16
|
-
constructor({ webServer } = {}) {
|
|
19
|
+
constructor({ webServer, sampler } = {}) {
|
|
17
20
|
this.#webServer = webServer;
|
|
21
|
+
this.#sampler = sampler;
|
|
18
22
|
}
|
|
19
23
|
|
|
20
24
|
/**
|
|
21
25
|
* Builds a fully wired `ServerController`: constructs it and builds its
|
|
22
|
-
* wrapped `WebServer` (which may be `null` when there's no web config)
|
|
26
|
+
* wrapped `WebServer` (which may be `null` when there's no web config) and
|
|
27
|
+
* `MemorySampler` (which is only built alongside a `WebServer`).
|
|
23
28
|
* @param {object} params - Build parameters.
|
|
24
29
|
* @param {object} [params.webConfig] - The web configuration object.
|
|
25
30
|
* @returns {ServerController} The built ServerController instance, never `null`.
|
|
@@ -27,6 +32,7 @@ class ServerController {
|
|
|
27
32
|
static build({ webConfig }) {
|
|
28
33
|
const controller = new ServerController();
|
|
29
34
|
controller.#webServer = controller.buildWebServer({ webConfig });
|
|
35
|
+
controller.#sampler = controller.buildSampler({ webConfig });
|
|
30
36
|
return controller;
|
|
31
37
|
}
|
|
32
38
|
|
|
@@ -41,18 +47,37 @@ class ServerController {
|
|
|
41
47
|
}
|
|
42
48
|
|
|
43
49
|
/**
|
|
44
|
-
*
|
|
50
|
+
* Builds and returns a MemorySampler if web configuration is present, otherwise null.
|
|
51
|
+
* `webConfig` presence is equivalent to `#webServer` being non-null: this keeps
|
|
52
|
+
* "no `web:` section → no sampler" true, even though `ServerController` itself is
|
|
53
|
+
* always constructed.
|
|
54
|
+
* @param {object} params - Build parameters.
|
|
55
|
+
* @param {object} [params.webConfig] - The web configuration object.
|
|
56
|
+
* @returns {MemorySampler|null} The created MemorySampler instance or null.
|
|
57
|
+
*/
|
|
58
|
+
buildSampler({ webConfig }) {
|
|
59
|
+
if (!webConfig) return null;
|
|
60
|
+
|
|
61
|
+
return new MemorySampler(webConfig.memory);
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Starts the wrapped web server and memory sampler, if any.
|
|
45
66
|
* @returns {Promise<void>|undefined} The web server's start promise, or undefined when there's no wrapped server.
|
|
46
67
|
*/
|
|
47
68
|
start() {
|
|
69
|
+
this.#sampler?.start();
|
|
48
70
|
return this.#webServer?.start();
|
|
49
71
|
}
|
|
50
72
|
|
|
51
73
|
/**
|
|
52
|
-
*
|
|
74
|
+
* Stops the memory sampler (synchronously, before the web server shutdown so
|
|
75
|
+
* sampling stops even if the web server shutdown rejects) and shuts down the
|
|
76
|
+
* wrapped web server, if any.
|
|
53
77
|
* @returns {Promise<void>|undefined} The web server's shutdown result, or undefined when there's no wrapped server.
|
|
54
78
|
*/
|
|
55
79
|
shutdown() {
|
|
80
|
+
this.#sampler?.stop();
|
|
56
81
|
return this.#webServer?.shutdown();
|
|
57
82
|
}
|
|
58
83
|
}
|
|
@@ -0,0 +1,86 @@
|
|
|
1
|
+
import { MemoryRegistry } from '../../registry/MemoryRegistry.js';
|
|
2
|
+
import { ProcessRssReader } from '../../utils/memory/ProcessRssReader.js';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Samples process RSS into {@link MemoryRegistry} on a fixed interval, driven by
|
|
6
|
+
* `memoryConfig.dataStoreInterval`. The sampler is the sole writer of the retained
|
|
7
|
+
* memory-history buffer — see the parent issue's _Alternatives considered_ for why a
|
|
8
|
+
* fixed-cadence sampler was chosen over sample-on-request.
|
|
9
|
+
* @author darthjee
|
|
10
|
+
*/
|
|
11
|
+
class MemorySampler {
|
|
12
|
+
#memoryConfig;
|
|
13
|
+
#setInterval;
|
|
14
|
+
#clearInterval;
|
|
15
|
+
#rssReader;
|
|
16
|
+
#handle;
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* @param {import('../../models/configs/MemoryConfig.js').MemoryConfig} memoryConfig - The
|
|
20
|
+
* resolved `web.memory` configuration.
|
|
21
|
+
* @param {object} [options={}] - Injectable collaborators.
|
|
22
|
+
* @param {Function} [options.setInterval] - Scheduler used to arm the sampling interval,
|
|
23
|
+
* defaulting to the global `setInterval`.
|
|
24
|
+
* @param {Function} [options.clearInterval] - Scheduler used to disarm the sampling interval,
|
|
25
|
+
* defaulting to the global `clearInterval`.
|
|
26
|
+
* @param {{read: Function}} [options.rssReader] - Reader used to obtain the current process
|
|
27
|
+
* RSS, defaulting to {@link ProcessRssReader}.
|
|
28
|
+
*/
|
|
29
|
+
constructor(memoryConfig, {
|
|
30
|
+
setInterval: setIntervalFn = globalThis.setInterval,
|
|
31
|
+
clearInterval: clearIntervalFn = globalThis.clearInterval,
|
|
32
|
+
rssReader = new ProcessRssReader()
|
|
33
|
+
} = {}) {
|
|
34
|
+
this.#memoryConfig = memoryConfig;
|
|
35
|
+
this.#setInterval = setIntervalFn;
|
|
36
|
+
this.#clearInterval = clearIntervalFn;
|
|
37
|
+
this.#rssReader = rssReader;
|
|
38
|
+
this.#handle = null;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Takes one immediate synchronous sample, then arms the sampling interval. No-ops
|
|
43
|
+
* when already started (a second `start()` while running does not leak a second
|
|
44
|
+
* interval).
|
|
45
|
+
* @returns {void}
|
|
46
|
+
*/
|
|
47
|
+
start() {
|
|
48
|
+
if (this.#handle) return;
|
|
49
|
+
|
|
50
|
+
this.#tick();
|
|
51
|
+
|
|
52
|
+
this.#handle = this.#setInterval(() => this.#tick(), this.#memoryConfig.dataStoreInterval * 1000);
|
|
53
|
+
this.#handle.unref?.();
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Disarms the sampling interval. Idempotent — a second `stop()` no-ops.
|
|
58
|
+
* @returns {void}
|
|
59
|
+
*/
|
|
60
|
+
stop() {
|
|
61
|
+
if (!this.#handle) return;
|
|
62
|
+
|
|
63
|
+
this.#clearInterval(this.#handle);
|
|
64
|
+
this.#handle = null;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Reads the current process RSS and records it into {@link MemoryRegistry}. Swallows
|
|
69
|
+
* any error so a failing read/write never crashes the process from inside a
|
|
70
|
+
* `setInterval` callback; the sample is simply skipped.
|
|
71
|
+
* @returns {void}
|
|
72
|
+
* @private
|
|
73
|
+
*/
|
|
74
|
+
#tick() {
|
|
75
|
+
try {
|
|
76
|
+
const value = this.#rssReader.read();
|
|
77
|
+
const percentage = value / this.#memoryConfig.maximum * 100;
|
|
78
|
+
|
|
79
|
+
MemoryRegistry.add(value, percentage);
|
|
80
|
+
} catch {
|
|
81
|
+
// Best-effort sampling: skip this sample rather than crash the process.
|
|
82
|
+
}
|
|
83
|
+
}
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
export { MemorySampler };
|