webspresso 0.0.103 → 0.0.105
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/.agents/AGENTS.md +6 -0
- package/.agents/ARCHITECTURE.md +23 -0
- package/.agents/CACHE.md +147 -0
- package/.agents/CLI.md +1 -1
- package/.agents/EARLY_HINTS.md +120 -0
- package/.agents/HEALTH.md +118 -0
- package/.agents/LIMITS.md +109 -0
- package/.agents/ORM.md +155 -1
- package/.agents/PLUGINS.md +28 -0
- package/.agents/RESILIENCE.md +235 -0
- package/AGENTS.md +6 -0
- package/README.md +2 -2
- package/bin/commands/add-docker.js +6 -6
- package/bin/commands/dev.js +4 -3
- package/bin/commands/new.js +5 -5
- package/bin/commands/openapi.js +1 -1
- package/bin/commands/start.js +1 -1
- package/bin/utils/orm-map-html.js +2 -8
- package/bin/utils/project.js +2 -2
- package/core/auth/hash.js +5 -4
- package/core/auth/jwt.js +6 -57
- package/core/auth/magic-link.js +4 -5
- package/core/auth/manager.js +3 -5
- package/core/auth/oauth.js +45 -30
- package/core/auth/totp.js +5 -16
- package/core/auth/user-agent.js +1 -21
- package/core/cache/byte-size.js +123 -0
- package/core/cache/index.js +21 -0
- package/core/cache/lru.js +477 -0
- package/core/cache/tagged-lru.js +346 -0
- package/core/commands/registry.js +6 -20
- package/core/content/renderer.js +1 -13
- package/core/early-hints/index.js +267 -0
- package/core/errors/domain.js +48 -0
- package/core/errors/http.js +31 -0
- package/core/errors/index.js +10 -0
- package/core/errors/middleware.js +2 -8
- package/core/errors/normalize.js +88 -2
- package/core/events/discovery.js +6 -24
- package/core/events/dispatcher.js +2 -7
- package/core/forms/form-builder.js +1 -9
- package/core/health/index.js +41 -0
- package/core/health/middleware.js +213 -0
- package/core/health/normalize.js +140 -0
- package/core/health/probes.js +203 -0
- package/core/limits/index.js +34 -0
- package/core/limits/middleware.js +317 -0
- package/core/limits/normalize.js +222 -0
- package/core/orm/batch.js +70 -0
- package/core/orm/cache/fingerprint.js +2 -2
- package/core/orm/cache/memory-provider.js +27 -110
- package/core/orm/index.js +76 -8
- package/core/orm/json-fields.js +22 -8
- package/core/orm/model.js +10 -0
- package/core/orm/query-builder.js +63 -9
- package/core/orm/query-filters.js +393 -0
- package/core/orm/repository.js +318 -19
- package/core/orm/schema-helpers.js +8 -10
- package/core/orm/scopes.js +321 -1
- package/core/orm/transaction.js +10 -2
- package/core/orm/utils.js +4 -86
- package/core/queue/adapters/database.js +4 -8
- package/core/queue/manager.js +55 -41
- package/core/resilience/circuit-breaker.js +391 -0
- package/core/resilience/errors.js +63 -0
- package/core/resilience/index.js +53 -0
- package/core/resilience/registry.js +97 -0
- package/core/resilience/retry.js +203 -0
- package/core/schema-cache.js +9 -2
- package/core/shutdown/http-adapter.js +4 -1
- package/core/shutdown/shutdown-manager.js +132 -31
- package/core/utils/array.js +12 -0
- package/core/utils/base64url.js +8 -0
- package/core/utils/crypto.js +191 -0
- package/core/utils/ensure-leading-slash.js +6 -0
- package/core/utils/escape-html.js +7 -0
- package/core/utils/escape-regexp.js +7 -0
- package/core/utils/fetch.js +121 -0
- package/core/utils/fs.js +144 -0
- package/core/utils/get-client-ip.js +6 -0
- package/core/utils/hmac.js +6 -0
- package/core/utils/html.js +72 -0
- package/core/utils/ip.js +86 -0
- package/core/utils/json.js +98 -0
- package/core/utils/object.js +106 -0
- package/core/utils/random.js +9 -0
- package/core/utils/regex.js +77 -0
- package/core/utils/safe-compare.js +3 -0
- package/core/utils/sha256.js +6 -0
- package/core/utils/string.js +87 -0
- package/core/utils/strip-trailing-slash.js +6 -0
- package/core/utils/time.js +96 -0
- package/core/utils/timeout.js +348 -0
- package/core/utils/url.js +106 -0
- package/core/utils/walk.js +7 -0
- package/index.d.ts +627 -2
- package/index.js +158 -0
- package/package.json +1 -2
- package/plugins/admin-panel/auth.js +15 -7
- package/plugins/admin-panel/client/parts/01-state-api-breadcrumb.js +82 -10
- package/plugins/admin-panel/client/parts/05-rich-text-file-helpers.js +4 -2
- package/plugins/admin-panel/client/parts/08-record-list.js +3 -2
- package/plugins/admin-panel/client/parts/10-export-registry.js +6 -0
- package/plugins/admin-panel/core/api-extensions.js +3 -80
- package/plugins/admin-panel/index.js +1 -1
- package/plugins/admin-panel/lib/login-rate-limiter.js +15 -13
- package/plugins/admin-panel/modules/menu.js +1 -1
- package/plugins/api-key/crypto.js +3 -26
- package/plugins/api-key/scopes.js +5 -7
- package/plugins/audit-log/api-handlers.js +8 -7
- package/plugins/audit-log/middleware.js +11 -2
- package/plugins/audit-log/parse.js +3 -3
- package/plugins/basic-auth/index.js +2 -26
- package/plugins/cors.js +2 -2
- package/plugins/csrf/index.js +7 -23
- package/plugins/dashboard/app.js +2 -2
- package/plugins/dashboard/index.js +5 -5
- package/plugins/data-exchange/record-selection.js +2 -5
- package/plugins/email/api-handlers.js +5 -18
- package/plugins/email/auth-bridge.js +3 -2
- package/plugins/file-manager/admin-component.js +3 -1
- package/plugins/file-manager/core.js +34 -4
- package/plugins/health-check.js +2 -1
- package/plugins/index.js +2 -0
- package/plugins/lazy.js +5 -6
- package/plugins/mcp/auth.js +1 -13
- package/plugins/mcp/discovery.js +18 -17
- package/plugins/mcp/index.js +23 -1
- package/plugins/mcp/transports/sse.js +10 -1
- package/plugins/orm-cache-admin/admin-component.js +3 -2
- package/plugins/polar/src/api.js +11 -3
- package/plugins/polar/src/webhooks.js +7 -13
- package/plugins/rate-limit/index.js +3 -1
- package/plugins/recaptcha/helpers.js +1 -7
- package/plugins/recaptcha/verify.js +37 -23
- package/plugins/redirect/index.js +57 -7
- package/plugins/rest-resources/index.js +1 -207
- package/plugins/rls/index.js +170 -0
- package/plugins/schema-explorer/admin-component.js +4 -2
- package/plugins/schema-explorer.js +40 -29
- package/plugins/seo-checker/index.js +5 -2
- package/plugins/site-analytics/tracking.js +21 -18
- package/plugins/sitemap.js +21 -17
- package/plugins/swagger.js +13 -17
- package/plugins/upload/index.js +4 -3
- package/plugins/upload/orphan-pruner.js +4 -3
- package/plugins/webhooks/crypto.js +6 -28
- package/plugins/webhooks/dispatcher.js +14 -9
- package/plugins/webhooks/index.js +6 -0
- package/plugins/webhooks/matcher.js +28 -17
- package/plugins/webhooks/sender.js +40 -13
- package/src/app-context.js +41 -5
- package/src/dev/banner.js +6 -2
- package/src/dev-reload/index.js +47 -6
- package/src/file-router.js +1 -3
- package/src/helpers.js +180 -33
- package/src/modules/module-discovery.js +1 -9
- package/src/pages/page-loader.js +53 -1
- package/src/plugin-manager.js +90 -17
- package/src/server.js +137 -26
- package/src/services/discovery.js +19 -40
- package/src/services/executor.js +86 -25
- package/src/services/memoize.js +3 -25
- package/src/services/registry.js +6 -0
- package/src/template/precompile.js +8 -19
|
@@ -0,0 +1,391 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Webspresso Enterprise Circuit Breaker
|
|
5
|
+
* Protects downstream systems from cascading failures with CLOSED, OPEN, and HALF_OPEN states,
|
|
6
|
+
* rolling window failure rates, per-call execution timeouts, graceful fallbacks, and event monitoring.
|
|
7
|
+
* @module core/resilience/circuit-breaker
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
const EventEmitter = require('events');
|
|
11
|
+
const { parseDurationMs } = require('../utils/time');
|
|
12
|
+
const { CircuitBreakerOpenError, CircuitBreakerTimeoutError } = require('./errors');
|
|
13
|
+
|
|
14
|
+
const STATE_CLOSED = 'CLOSED';
|
|
15
|
+
const STATE_OPEN = 'OPEN';
|
|
16
|
+
const STATE_HALF_OPEN = 'HALF_OPEN';
|
|
17
|
+
|
|
18
|
+
/**
|
|
19
|
+
* @typedef {Object} CircuitBreakerOptions
|
|
20
|
+
* @property {string} [name='default'] - Breaker identifier
|
|
21
|
+
* @property {number} [failureThreshold=5] - Consecutive failure count to open circuit
|
|
22
|
+
* @property {number} [failureRateThreshold] - Percentage failure rate threshold (0.1 to 1.0)
|
|
23
|
+
* @property {number} [minimumRequests=5] - Minimum requests in rolling window for failure rate calculation
|
|
24
|
+
* @property {number|string} [rollingWindowMs=10000] - Rolling window for metrics in ms or duration string
|
|
25
|
+
* @property {number} [successThreshold=2] - Consecutive successes in HALF_OPEN to close circuit
|
|
26
|
+
* @property {number|string} [resetTimeout=10000] - Duration in ms or duration string to stay OPEN before HALF_OPEN
|
|
27
|
+
* @property {number|string} [timeout=0] - Per-call execution timeout in ms or duration string (0 = disabled)
|
|
28
|
+
* @property {function(Error, ...*): *} [fallback] - Fallback handler when OPEN or call fails
|
|
29
|
+
* @property {function(Error): boolean} [isFailure] - Custom error classifier predicate
|
|
30
|
+
* @property {function(string, string, CircuitBreaker): void} [onStateChange] - State transition listener
|
|
31
|
+
*/
|
|
32
|
+
|
|
33
|
+
class CircuitBreaker extends EventEmitter {
|
|
34
|
+
/**
|
|
35
|
+
* @param {CircuitBreakerOptions} [options]
|
|
36
|
+
*/
|
|
37
|
+
constructor(options = {}) {
|
|
38
|
+
super();
|
|
39
|
+
|
|
40
|
+
this.name = options.name || 'default';
|
|
41
|
+
this.failureThreshold = typeof options.failureThreshold === 'number' ? Math.max(1, options.failureThreshold) : 5;
|
|
42
|
+
this.failureRateThreshold = typeof options.failureRateThreshold === 'number'
|
|
43
|
+
? Math.min(1, Math.max(0.01, options.failureRateThreshold))
|
|
44
|
+
: null;
|
|
45
|
+
this.minimumRequests = typeof options.minimumRequests === 'number' ? Math.max(1, options.minimumRequests) : 5;
|
|
46
|
+
|
|
47
|
+
this.rollingWindowMs = options.rollingWindowMs !== undefined
|
|
48
|
+
? parseDurationMs(options.rollingWindowMs, 10000)
|
|
49
|
+
: (options.rollingWindow !== undefined ? parseDurationMs(options.rollingWindow, 10000) : 10000);
|
|
50
|
+
|
|
51
|
+
this.successThreshold = typeof options.successThreshold === 'number' ? Math.max(1, options.successThreshold) : 2;
|
|
52
|
+
|
|
53
|
+
this.resetTimeoutMs = options.resetTimeout !== undefined
|
|
54
|
+
? parseDurationMs(options.resetTimeout, 10000)
|
|
55
|
+
: (options.resetTimeoutMs !== undefined ? parseDurationMs(options.resetTimeoutMs, 10000) : 10000);
|
|
56
|
+
|
|
57
|
+
this.timeoutMs = options.timeout !== undefined
|
|
58
|
+
? parseDurationMs(options.timeout, 0)
|
|
59
|
+
: (options.timeoutMs !== undefined ? parseDurationMs(options.timeoutMs, 0) : 0);
|
|
60
|
+
|
|
61
|
+
this.fallback = typeof options.fallback === 'function' ? options.fallback : null;
|
|
62
|
+
this.isFailure = typeof options.isFailure === 'function'
|
|
63
|
+
? options.isFailure
|
|
64
|
+
: (err) => {
|
|
65
|
+
if (!err) return false;
|
|
66
|
+
const status = err.status || err.statusCode || err.response?.status;
|
|
67
|
+
if (typeof status === 'number' && status >= 400 && status < 500 && status !== 429) {
|
|
68
|
+
return false;
|
|
69
|
+
}
|
|
70
|
+
return true;
|
|
71
|
+
};
|
|
72
|
+
|
|
73
|
+
if (typeof options.onStateChange === 'function') {
|
|
74
|
+
this.on('stateChange', options.onStateChange);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
this.state = STATE_CLOSED;
|
|
78
|
+
this.consecutiveFailures = 0;
|
|
79
|
+
this.consecutiveSuccesses = 0;
|
|
80
|
+
this.lastStateChange = Date.now();
|
|
81
|
+
this.lastFailureTime = null;
|
|
82
|
+
this.lastSuccessTime = null;
|
|
83
|
+
|
|
84
|
+
/** @type {Array<{ time: number, success: boolean }>} Rolling window samples */
|
|
85
|
+
this._samples = [];
|
|
86
|
+
|
|
87
|
+
this.metrics = {
|
|
88
|
+
totalCalls: 0,
|
|
89
|
+
successfulCalls: 0,
|
|
90
|
+
failedCalls: 0,
|
|
91
|
+
rejectedCalls: 0,
|
|
92
|
+
timedOutCalls: 0,
|
|
93
|
+
fallbackCalls: 0,
|
|
94
|
+
};
|
|
95
|
+
}
|
|
96
|
+
|
|
97
|
+
static get STATE_CLOSED() { return STATE_CLOSED; }
|
|
98
|
+
static get STATE_OPEN() { return STATE_OPEN; }
|
|
99
|
+
static get STATE_HALF_OPEN() { return STATE_HALF_OPEN; }
|
|
100
|
+
|
|
101
|
+
get isClosed() { return this.state === STATE_CLOSED; }
|
|
102
|
+
get isOpen() { return this.state === STATE_OPEN; }
|
|
103
|
+
get isHalfOpen() { return this.state === STATE_HALF_OPEN; }
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Transition circuit breaker state
|
|
107
|
+
* @private
|
|
108
|
+
*/
|
|
109
|
+
_transitionTo(newState) {
|
|
110
|
+
if (this.state === newState) return;
|
|
111
|
+
|
|
112
|
+
const oldState = this.state;
|
|
113
|
+
this.state = newState;
|
|
114
|
+
this.lastStateChange = Date.now();
|
|
115
|
+
|
|
116
|
+
if (newState === STATE_CLOSED) {
|
|
117
|
+
this.consecutiveFailures = 0;
|
|
118
|
+
this.consecutiveSuccesses = 0;
|
|
119
|
+
this.emit('close', this);
|
|
120
|
+
} else if (newState === STATE_OPEN) {
|
|
121
|
+
this.consecutiveSuccesses = 0;
|
|
122
|
+
this.emit('open', this);
|
|
123
|
+
} else if (newState === STATE_HALF_OPEN) {
|
|
124
|
+
this.consecutiveSuccesses = 0;
|
|
125
|
+
this.emit('halfOpen', this);
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
this.emit('stateChange', oldState, newState, this);
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
/**
|
|
132
|
+
* Manually force open the circuit
|
|
133
|
+
*/
|
|
134
|
+
open() {
|
|
135
|
+
this._transitionTo(STATE_OPEN);
|
|
136
|
+
return this;
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/**
|
|
140
|
+
* Manually force close the circuit
|
|
141
|
+
*/
|
|
142
|
+
close() {
|
|
143
|
+
this._transitionTo(STATE_CLOSED);
|
|
144
|
+
return this;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
/**
|
|
148
|
+
* Manually transition to half-open
|
|
149
|
+
*/
|
|
150
|
+
halfOpen() {
|
|
151
|
+
this._transitionTo(STATE_HALF_OPEN);
|
|
152
|
+
return this;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* Reset circuit breaker state and metrics
|
|
157
|
+
*/
|
|
158
|
+
reset() {
|
|
159
|
+
this.state = STATE_CLOSED;
|
|
160
|
+
this.consecutiveFailures = 0;
|
|
161
|
+
this.consecutiveSuccesses = 0;
|
|
162
|
+
this.lastStateChange = Date.now();
|
|
163
|
+
this.lastFailureTime = null;
|
|
164
|
+
this.lastSuccessTime = null;
|
|
165
|
+
this._samples = [];
|
|
166
|
+
|
|
167
|
+
this.metrics.totalCalls = 0;
|
|
168
|
+
this.metrics.successfulCalls = 0;
|
|
169
|
+
this.metrics.failedCalls = 0;
|
|
170
|
+
this.metrics.rejectedCalls = 0;
|
|
171
|
+
this.metrics.timedOutCalls = 0;
|
|
172
|
+
this.metrics.fallbackCalls = 0;
|
|
173
|
+
|
|
174
|
+
return this;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
/**
|
|
178
|
+
* Prune sample measurements outside the rolling window
|
|
179
|
+
* @private
|
|
180
|
+
*/
|
|
181
|
+
_pruneSamples() {
|
|
182
|
+
const cutoff = Date.now() - this.rollingWindowMs;
|
|
183
|
+
while (this._samples.length > 0 && this._samples[0].time < cutoff) {
|
|
184
|
+
this._samples.shift();
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
|
|
188
|
+
/**
|
|
189
|
+
* Record invocation sample in rolling window
|
|
190
|
+
* @private
|
|
191
|
+
*/
|
|
192
|
+
_recordSample(success) {
|
|
193
|
+
this._samples.push({ time: Date.now(), success });
|
|
194
|
+
this._pruneSamples();
|
|
195
|
+
}
|
|
196
|
+
|
|
197
|
+
/**
|
|
198
|
+
* Calculate current failure rate in rolling window (0.0 to 1.0)
|
|
199
|
+
*/
|
|
200
|
+
getFailureRate() {
|
|
201
|
+
this._pruneSamples();
|
|
202
|
+
if (this._samples.length === 0) return 0;
|
|
203
|
+
|
|
204
|
+
let failures = 0;
|
|
205
|
+
for (let i = 0; i < this._samples.length; i++) {
|
|
206
|
+
if (!this._samples[i].success) failures++;
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
return failures / this._samples.length;
|
|
210
|
+
}
|
|
211
|
+
|
|
212
|
+
/**
|
|
213
|
+
* Process successful call
|
|
214
|
+
* @private
|
|
215
|
+
*/
|
|
216
|
+
_onSuccess() {
|
|
217
|
+
this.lastSuccessTime = Date.now();
|
|
218
|
+
this.metrics.successfulCalls++;
|
|
219
|
+
this._recordSample(true);
|
|
220
|
+
|
|
221
|
+
if (this.state === STATE_HALF_OPEN) {
|
|
222
|
+
this.consecutiveSuccesses++;
|
|
223
|
+
if (this.consecutiveSuccesses >= this.successThreshold) {
|
|
224
|
+
this._transitionTo(STATE_CLOSED);
|
|
225
|
+
}
|
|
226
|
+
} else if (this.state === STATE_CLOSED) {
|
|
227
|
+
this.consecutiveFailures = 0;
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
this.emit('success', this);
|
|
231
|
+
}
|
|
232
|
+
|
|
233
|
+
/**
|
|
234
|
+
* Process failed call
|
|
235
|
+
* @private
|
|
236
|
+
*/
|
|
237
|
+
_onFailure(err) {
|
|
238
|
+
this.lastFailureTime = Date.now();
|
|
239
|
+
this.metrics.failedCalls++;
|
|
240
|
+
this._recordSample(false);
|
|
241
|
+
|
|
242
|
+
if (this.state === STATE_HALF_OPEN) {
|
|
243
|
+
// In HALF_OPEN, any failure immediately trips circuit back to OPEN
|
|
244
|
+
this._transitionTo(STATE_OPEN);
|
|
245
|
+
} else if (this.state === STATE_CLOSED) {
|
|
246
|
+
this.consecutiveFailures++;
|
|
247
|
+
|
|
248
|
+
// Check consecutive failures
|
|
249
|
+
if (this.consecutiveFailures >= this.failureThreshold) {
|
|
250
|
+
this._transitionTo(STATE_OPEN);
|
|
251
|
+
} else if (
|
|
252
|
+
this.failureRateThreshold !== null &&
|
|
253
|
+
this._samples.length >= this.minimumRequests &&
|
|
254
|
+
this.getFailureRate() >= this.failureRateThreshold
|
|
255
|
+
) {
|
|
256
|
+
this._transitionTo(STATE_OPEN);
|
|
257
|
+
}
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
this.emit('failure', err, this);
|
|
261
|
+
}
|
|
262
|
+
|
|
263
|
+
/**
|
|
264
|
+
* Execute an async function protected by this circuit breaker.
|
|
265
|
+
*
|
|
266
|
+
* @param {Function} fn - Async or sync function to execute
|
|
267
|
+
* @param {...*} args - Arguments forwarded to fn
|
|
268
|
+
* @returns {Promise<*>}
|
|
269
|
+
*/
|
|
270
|
+
async execute(fn, ...args) {
|
|
271
|
+
this.metrics.totalCalls++;
|
|
272
|
+
|
|
273
|
+
// 1. Check if OPEN state should attempt recovery to HALF_OPEN
|
|
274
|
+
if (this.state === STATE_OPEN) {
|
|
275
|
+
const now = Date.now();
|
|
276
|
+
if (now - this.lastStateChange >= this.resetTimeoutMs) {
|
|
277
|
+
this._transitionTo(STATE_HALF_OPEN);
|
|
278
|
+
} else {
|
|
279
|
+
// Fast-fail: Circuit is OPEN and reset timeout has not expired
|
|
280
|
+
this.metrics.rejectedCalls++;
|
|
281
|
+
const openErr = new CircuitBreakerOpenError(this.name, this.resetTimeoutMs);
|
|
282
|
+
|
|
283
|
+
if (this.fallback) {
|
|
284
|
+
this.metrics.fallbackCalls++;
|
|
285
|
+
this.emit('fallback', openErr, this);
|
|
286
|
+
return await this.fallback(openErr, ...args);
|
|
287
|
+
}
|
|
288
|
+
|
|
289
|
+
throw openErr;
|
|
290
|
+
}
|
|
291
|
+
}
|
|
292
|
+
|
|
293
|
+
// 2. Execute operation with optional timeout
|
|
294
|
+
let timerId = null;
|
|
295
|
+
let timedOut = false;
|
|
296
|
+
|
|
297
|
+
try {
|
|
298
|
+
let execPromise;
|
|
299
|
+
if (this.timeoutMs > 0) {
|
|
300
|
+
const timeoutPromise = new Promise((_, reject) => {
|
|
301
|
+
timerId = setTimeout(() => {
|
|
302
|
+
timedOut = true;
|
|
303
|
+
this.metrics.timedOutCalls++;
|
|
304
|
+
const timeoutErr = new CircuitBreakerTimeoutError(this.name, this.timeoutMs);
|
|
305
|
+
this.emit('timeout', timeoutErr, this);
|
|
306
|
+
reject(timeoutErr);
|
|
307
|
+
}, this.timeoutMs);
|
|
308
|
+
if (typeof timerId?.unref === 'function') timerId.unref();
|
|
309
|
+
});
|
|
310
|
+
|
|
311
|
+
execPromise = Promise.race([
|
|
312
|
+
Promise.resolve().then(() => fn(...args)),
|
|
313
|
+
timeoutPromise,
|
|
314
|
+
]);
|
|
315
|
+
} else {
|
|
316
|
+
execPromise = Promise.resolve().then(() => fn(...args));
|
|
317
|
+
}
|
|
318
|
+
|
|
319
|
+
const result = await execPromise;
|
|
320
|
+
if (timerId) clearTimeout(timerId);
|
|
321
|
+
|
|
322
|
+
this._onSuccess();
|
|
323
|
+
return result;
|
|
324
|
+
} catch (err) {
|
|
325
|
+
if (timerId) clearTimeout(timerId);
|
|
326
|
+
|
|
327
|
+
const isCountedFailure = this.isFailure(err);
|
|
328
|
+
if (isCountedFailure) {
|
|
329
|
+
this._onFailure(err);
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
// If fallback configured, invoke fallback on error
|
|
333
|
+
if (this.fallback) {
|
|
334
|
+
this.metrics.fallbackCalls++;
|
|
335
|
+
this.emit('fallback', err, this);
|
|
336
|
+
return await this.fallback(err, ...args);
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
throw err;
|
|
340
|
+
}
|
|
341
|
+
}
|
|
342
|
+
|
|
343
|
+
/**
|
|
344
|
+
* Wrap a function with this circuit breaker
|
|
345
|
+
* @param {Function} fn
|
|
346
|
+
* @returns {Function}
|
|
347
|
+
*/
|
|
348
|
+
wrap(fn) {
|
|
349
|
+
return (...args) => this.execute(fn, ...args);
|
|
350
|
+
}
|
|
351
|
+
|
|
352
|
+
/**
|
|
353
|
+
* Telemetry stats snapshot
|
|
354
|
+
*/
|
|
355
|
+
getStats() {
|
|
356
|
+
this._pruneSamples();
|
|
357
|
+
return {
|
|
358
|
+
name: this.name,
|
|
359
|
+
state: this.state,
|
|
360
|
+
totalCalls: this.metrics.totalCalls,
|
|
361
|
+
successfulCalls: this.metrics.successfulCalls,
|
|
362
|
+
failedCalls: this.metrics.failedCalls,
|
|
363
|
+
rejectedCalls: this.metrics.rejectedCalls,
|
|
364
|
+
timedOutCalls: this.metrics.timedOutCalls,
|
|
365
|
+
fallbackCalls: this.metrics.fallbackCalls,
|
|
366
|
+
consecutiveFailures: this.consecutiveFailures,
|
|
367
|
+
consecutiveSuccesses: this.consecutiveSuccesses,
|
|
368
|
+
failureRate: this.getFailureRate(),
|
|
369
|
+
lastFailureTime: this.lastFailureTime,
|
|
370
|
+
lastSuccessTime: this.lastSuccessTime,
|
|
371
|
+
lastStateChange: this.lastStateChange,
|
|
372
|
+
};
|
|
373
|
+
}
|
|
374
|
+
}
|
|
375
|
+
|
|
376
|
+
/**
|
|
377
|
+
* Factory helper
|
|
378
|
+
* @param {CircuitBreakerOptions} [options]
|
|
379
|
+
* @returns {CircuitBreaker}
|
|
380
|
+
*/
|
|
381
|
+
function createCircuitBreaker(options) {
|
|
382
|
+
return new CircuitBreaker(options);
|
|
383
|
+
}
|
|
384
|
+
|
|
385
|
+
module.exports = {
|
|
386
|
+
CircuitBreaker,
|
|
387
|
+
createCircuitBreaker,
|
|
388
|
+
STATE_CLOSED,
|
|
389
|
+
STATE_OPEN,
|
|
390
|
+
STATE_HALF_OPEN,
|
|
391
|
+
};
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Webspresso Resilience Exceptions
|
|
5
|
+
* Semantic errors for Circuit Breaker and Fault Tolerance failures.
|
|
6
|
+
* @module core/resilience/errors
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
const { ServiceUnavailableError, GatewayTimeoutError } = require('../errors/http');
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* CircuitBreakerOpenError
|
|
13
|
+
* Thrown when an invocation is rejected because the circuit is in the OPEN state.
|
|
14
|
+
* Maps directly to HTTP 503 Service Unavailable.
|
|
15
|
+
*/
|
|
16
|
+
class CircuitBreakerOpenError extends ServiceUnavailableError {
|
|
17
|
+
/**
|
|
18
|
+
* @param {string} breakerName - Name of the circuit breaker
|
|
19
|
+
* @param {number} [resetTimeoutMs] - Time until the breaker attempts half-open
|
|
20
|
+
* @param {Object} [options]
|
|
21
|
+
*/
|
|
22
|
+
constructor(breakerName = 'default', resetTimeoutMs = 0, options = {}) {
|
|
23
|
+
const message = `Circuit breaker '${breakerName}' is OPEN and failing fast`;
|
|
24
|
+
super(message, {
|
|
25
|
+
code: 'CIRCUIT_BREAKER_OPEN',
|
|
26
|
+
expose: true,
|
|
27
|
+
...options,
|
|
28
|
+
});
|
|
29
|
+
|
|
30
|
+
this.breakerName = breakerName;
|
|
31
|
+
this.resetTimeoutMs = resetTimeoutMs;
|
|
32
|
+
this.state = 'OPEN';
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* CircuitBreakerTimeoutError
|
|
38
|
+
* Thrown when an invocation inside a circuit breaker exceeds the configured per-call timeout.
|
|
39
|
+
* Maps directly to HTTP 504 Gateway Timeout.
|
|
40
|
+
*/
|
|
41
|
+
class CircuitBreakerTimeoutError extends GatewayTimeoutError {
|
|
42
|
+
/**
|
|
43
|
+
* @param {string} breakerName - Name of the circuit breaker
|
|
44
|
+
* @param {number} timeoutMs - Timeout duration in milliseconds
|
|
45
|
+
* @param {Object} [options]
|
|
46
|
+
*/
|
|
47
|
+
constructor(breakerName = 'default', timeoutMs = 0, options = {}) {
|
|
48
|
+
const message = `Execution in circuit breaker '${breakerName}' timed out after ${timeoutMs}ms`;
|
|
49
|
+
super(message, {
|
|
50
|
+
code: 'CIRCUIT_BREAKER_TIMEOUT',
|
|
51
|
+
expose: true,
|
|
52
|
+
...options,
|
|
53
|
+
});
|
|
54
|
+
|
|
55
|
+
this.breakerName = breakerName;
|
|
56
|
+
this.timeoutMs = timeoutMs;
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
|
|
60
|
+
module.exports = {
|
|
61
|
+
CircuitBreakerOpenError,
|
|
62
|
+
CircuitBreakerTimeoutError,
|
|
63
|
+
};
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Webspresso Enterprise Resilience & Fault Tolerance Engine
|
|
5
|
+
* Circuit Breaker, Exponential Backoff Retry with Jitter, and Failure Protection.
|
|
6
|
+
* @module core/resilience
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
const {
|
|
10
|
+
CircuitBreaker,
|
|
11
|
+
createCircuitBreaker,
|
|
12
|
+
STATE_CLOSED,
|
|
13
|
+
STATE_OPEN,
|
|
14
|
+
STATE_HALF_OPEN,
|
|
15
|
+
} = require('./circuit-breaker');
|
|
16
|
+
|
|
17
|
+
const {
|
|
18
|
+
retry,
|
|
19
|
+
withRetry,
|
|
20
|
+
isTransientError,
|
|
21
|
+
calculateBackoffDelay,
|
|
22
|
+
} = require('./retry');
|
|
23
|
+
|
|
24
|
+
const {
|
|
25
|
+
CircuitBreakerRegistry,
|
|
26
|
+
circuitBreakerRegistry,
|
|
27
|
+
getBreaker,
|
|
28
|
+
} = require('./registry');
|
|
29
|
+
|
|
30
|
+
const {
|
|
31
|
+
CircuitBreakerOpenError,
|
|
32
|
+
CircuitBreakerTimeoutError,
|
|
33
|
+
} = require('./errors');
|
|
34
|
+
|
|
35
|
+
module.exports = {
|
|
36
|
+
CircuitBreaker,
|
|
37
|
+
createCircuitBreaker,
|
|
38
|
+
STATE_CLOSED,
|
|
39
|
+
STATE_OPEN,
|
|
40
|
+
STATE_HALF_OPEN,
|
|
41
|
+
|
|
42
|
+
retry,
|
|
43
|
+
withRetry,
|
|
44
|
+
isTransientError,
|
|
45
|
+
calculateBackoffDelay,
|
|
46
|
+
|
|
47
|
+
CircuitBreakerRegistry,
|
|
48
|
+
circuitBreakerRegistry,
|
|
49
|
+
getBreaker,
|
|
50
|
+
|
|
51
|
+
CircuitBreakerOpenError,
|
|
52
|
+
CircuitBreakerTimeoutError,
|
|
53
|
+
};
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
'use strict';
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Webspresso - Circuit Breaker Registry
|
|
5
|
+
* Central registry for named CircuitBreaker instances across the application.
|
|
6
|
+
* @module core/resilience/registry
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
const { CircuitBreaker } = require('./circuit-breaker');
|
|
10
|
+
|
|
11
|
+
class CircuitBreakerRegistry {
|
|
12
|
+
constructor() {
|
|
13
|
+
/** @type {Map<string, CircuitBreaker>} */
|
|
14
|
+
this.breakers = new Map();
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* Retrieve an existing circuit breaker or create a new one with options.
|
|
19
|
+
*
|
|
20
|
+
* @param {string} name - Unique breaker identifier
|
|
21
|
+
* @param {import('./circuit-breaker').CircuitBreakerOptions} [options]
|
|
22
|
+
* @returns {CircuitBreaker}
|
|
23
|
+
*/
|
|
24
|
+
getBreaker(name, options = {}) {
|
|
25
|
+
if (!name || typeof name !== 'string') {
|
|
26
|
+
name = 'default';
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
if (!this.breakers.has(name)) {
|
|
30
|
+
const breaker = new CircuitBreaker({ name, ...options });
|
|
31
|
+
this.breakers.set(name, breaker);
|
|
32
|
+
return breaker;
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
return this.breakers.get(name);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Check if a named breaker exists
|
|
40
|
+
* @param {string} name
|
|
41
|
+
* @returns {boolean}
|
|
42
|
+
*/
|
|
43
|
+
hasBreaker(name) {
|
|
44
|
+
return this.breakers.has(name);
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Get all registered circuit breakers
|
|
49
|
+
* @returns {CircuitBreaker[]}
|
|
50
|
+
*/
|
|
51
|
+
getAllBreakers() {
|
|
52
|
+
return Array.from(this.breakers.values());
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Get telemetry stats summary for all breakers
|
|
57
|
+
* @returns {Record<string, Object>}
|
|
58
|
+
*/
|
|
59
|
+
getStats() {
|
|
60
|
+
const summary = {};
|
|
61
|
+
for (const [name, breaker] of this.breakers.entries()) {
|
|
62
|
+
summary[name] = breaker.getStats();
|
|
63
|
+
}
|
|
64
|
+
return summary;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Reset all registered circuit breakers to CLOSED state
|
|
69
|
+
*/
|
|
70
|
+
resetAll() {
|
|
71
|
+
for (const breaker of this.breakers.values()) {
|
|
72
|
+
breaker.reset();
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* Clear all registered breakers
|
|
78
|
+
*/
|
|
79
|
+
clear() {
|
|
80
|
+
for (const breaker of this.breakers.values()) {
|
|
81
|
+
breaker.removeAllListeners();
|
|
82
|
+
}
|
|
83
|
+
this.breakers.clear();
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
const circuitBreakerRegistry = new CircuitBreakerRegistry();
|
|
88
|
+
|
|
89
|
+
function getBreaker(name, options) {
|
|
90
|
+
return circuitBreakerRegistry.getBreaker(name, options);
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
module.exports = {
|
|
94
|
+
CircuitBreakerRegistry,
|
|
95
|
+
circuitBreakerRegistry,
|
|
96
|
+
getBreaker,
|
|
97
|
+
};
|