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.
Files changed (165) hide show
  1. package/.agents/AGENTS.md +6 -0
  2. package/.agents/ARCHITECTURE.md +23 -0
  3. package/.agents/CACHE.md +147 -0
  4. package/.agents/CLI.md +1 -1
  5. package/.agents/EARLY_HINTS.md +120 -0
  6. package/.agents/HEALTH.md +118 -0
  7. package/.agents/LIMITS.md +109 -0
  8. package/.agents/ORM.md +155 -1
  9. package/.agents/PLUGINS.md +28 -0
  10. package/.agents/RESILIENCE.md +235 -0
  11. package/AGENTS.md +6 -0
  12. package/README.md +2 -2
  13. package/bin/commands/add-docker.js +6 -6
  14. package/bin/commands/dev.js +4 -3
  15. package/bin/commands/new.js +5 -5
  16. package/bin/commands/openapi.js +1 -1
  17. package/bin/commands/start.js +1 -1
  18. package/bin/utils/orm-map-html.js +2 -8
  19. package/bin/utils/project.js +2 -2
  20. package/core/auth/hash.js +5 -4
  21. package/core/auth/jwt.js +6 -57
  22. package/core/auth/magic-link.js +4 -5
  23. package/core/auth/manager.js +3 -5
  24. package/core/auth/oauth.js +45 -30
  25. package/core/auth/totp.js +5 -16
  26. package/core/auth/user-agent.js +1 -21
  27. package/core/cache/byte-size.js +123 -0
  28. package/core/cache/index.js +21 -0
  29. package/core/cache/lru.js +477 -0
  30. package/core/cache/tagged-lru.js +346 -0
  31. package/core/commands/registry.js +6 -20
  32. package/core/content/renderer.js +1 -13
  33. package/core/early-hints/index.js +267 -0
  34. package/core/errors/domain.js +48 -0
  35. package/core/errors/http.js +31 -0
  36. package/core/errors/index.js +10 -0
  37. package/core/errors/middleware.js +2 -8
  38. package/core/errors/normalize.js +88 -2
  39. package/core/events/discovery.js +6 -24
  40. package/core/events/dispatcher.js +2 -7
  41. package/core/forms/form-builder.js +1 -9
  42. package/core/health/index.js +41 -0
  43. package/core/health/middleware.js +213 -0
  44. package/core/health/normalize.js +140 -0
  45. package/core/health/probes.js +203 -0
  46. package/core/limits/index.js +34 -0
  47. package/core/limits/middleware.js +317 -0
  48. package/core/limits/normalize.js +222 -0
  49. package/core/orm/batch.js +70 -0
  50. package/core/orm/cache/fingerprint.js +2 -2
  51. package/core/orm/cache/memory-provider.js +27 -110
  52. package/core/orm/index.js +76 -8
  53. package/core/orm/json-fields.js +22 -8
  54. package/core/orm/model.js +10 -0
  55. package/core/orm/query-builder.js +63 -9
  56. package/core/orm/query-filters.js +393 -0
  57. package/core/orm/repository.js +318 -19
  58. package/core/orm/schema-helpers.js +8 -10
  59. package/core/orm/scopes.js +321 -1
  60. package/core/orm/transaction.js +10 -2
  61. package/core/orm/utils.js +4 -86
  62. package/core/queue/adapters/database.js +4 -8
  63. package/core/queue/manager.js +55 -41
  64. package/core/resilience/circuit-breaker.js +391 -0
  65. package/core/resilience/errors.js +63 -0
  66. package/core/resilience/index.js +53 -0
  67. package/core/resilience/registry.js +97 -0
  68. package/core/resilience/retry.js +203 -0
  69. package/core/schema-cache.js +9 -2
  70. package/core/shutdown/http-adapter.js +4 -1
  71. package/core/shutdown/shutdown-manager.js +132 -31
  72. package/core/utils/array.js +12 -0
  73. package/core/utils/base64url.js +8 -0
  74. package/core/utils/crypto.js +191 -0
  75. package/core/utils/ensure-leading-slash.js +6 -0
  76. package/core/utils/escape-html.js +7 -0
  77. package/core/utils/escape-regexp.js +7 -0
  78. package/core/utils/fetch.js +121 -0
  79. package/core/utils/fs.js +144 -0
  80. package/core/utils/get-client-ip.js +6 -0
  81. package/core/utils/hmac.js +6 -0
  82. package/core/utils/html.js +72 -0
  83. package/core/utils/ip.js +86 -0
  84. package/core/utils/json.js +98 -0
  85. package/core/utils/object.js +106 -0
  86. package/core/utils/random.js +9 -0
  87. package/core/utils/regex.js +77 -0
  88. package/core/utils/safe-compare.js +3 -0
  89. package/core/utils/sha256.js +6 -0
  90. package/core/utils/string.js +87 -0
  91. package/core/utils/strip-trailing-slash.js +6 -0
  92. package/core/utils/time.js +96 -0
  93. package/core/utils/timeout.js +348 -0
  94. package/core/utils/url.js +106 -0
  95. package/core/utils/walk.js +7 -0
  96. package/index.d.ts +627 -2
  97. package/index.js +158 -0
  98. package/package.json +1 -2
  99. package/plugins/admin-panel/auth.js +15 -7
  100. package/plugins/admin-panel/client/parts/01-state-api-breadcrumb.js +82 -10
  101. package/plugins/admin-panel/client/parts/05-rich-text-file-helpers.js +4 -2
  102. package/plugins/admin-panel/client/parts/08-record-list.js +3 -2
  103. package/plugins/admin-panel/client/parts/10-export-registry.js +6 -0
  104. package/plugins/admin-panel/core/api-extensions.js +3 -80
  105. package/plugins/admin-panel/index.js +1 -1
  106. package/plugins/admin-panel/lib/login-rate-limiter.js +15 -13
  107. package/plugins/admin-panel/modules/menu.js +1 -1
  108. package/plugins/api-key/crypto.js +3 -26
  109. package/plugins/api-key/scopes.js +5 -7
  110. package/plugins/audit-log/api-handlers.js +8 -7
  111. package/plugins/audit-log/middleware.js +11 -2
  112. package/plugins/audit-log/parse.js +3 -3
  113. package/plugins/basic-auth/index.js +2 -26
  114. package/plugins/cors.js +2 -2
  115. package/plugins/csrf/index.js +7 -23
  116. package/plugins/dashboard/app.js +2 -2
  117. package/plugins/dashboard/index.js +5 -5
  118. package/plugins/data-exchange/record-selection.js +2 -5
  119. package/plugins/email/api-handlers.js +5 -18
  120. package/plugins/email/auth-bridge.js +3 -2
  121. package/plugins/file-manager/admin-component.js +3 -1
  122. package/plugins/file-manager/core.js +34 -4
  123. package/plugins/health-check.js +2 -1
  124. package/plugins/index.js +2 -0
  125. package/plugins/lazy.js +5 -6
  126. package/plugins/mcp/auth.js +1 -13
  127. package/plugins/mcp/discovery.js +18 -17
  128. package/plugins/mcp/index.js +23 -1
  129. package/plugins/mcp/transports/sse.js +10 -1
  130. package/plugins/orm-cache-admin/admin-component.js +3 -2
  131. package/plugins/polar/src/api.js +11 -3
  132. package/plugins/polar/src/webhooks.js +7 -13
  133. package/plugins/rate-limit/index.js +3 -1
  134. package/plugins/recaptcha/helpers.js +1 -7
  135. package/plugins/recaptcha/verify.js +37 -23
  136. package/plugins/redirect/index.js +57 -7
  137. package/plugins/rest-resources/index.js +1 -207
  138. package/plugins/rls/index.js +170 -0
  139. package/plugins/schema-explorer/admin-component.js +4 -2
  140. package/plugins/schema-explorer.js +40 -29
  141. package/plugins/seo-checker/index.js +5 -2
  142. package/plugins/site-analytics/tracking.js +21 -18
  143. package/plugins/sitemap.js +21 -17
  144. package/plugins/swagger.js +13 -17
  145. package/plugins/upload/index.js +4 -3
  146. package/plugins/upload/orphan-pruner.js +4 -3
  147. package/plugins/webhooks/crypto.js +6 -28
  148. package/plugins/webhooks/dispatcher.js +14 -9
  149. package/plugins/webhooks/index.js +6 -0
  150. package/plugins/webhooks/matcher.js +28 -17
  151. package/plugins/webhooks/sender.js +40 -13
  152. package/src/app-context.js +41 -5
  153. package/src/dev/banner.js +6 -2
  154. package/src/dev-reload/index.js +47 -6
  155. package/src/file-router.js +1 -3
  156. package/src/helpers.js +180 -33
  157. package/src/modules/module-discovery.js +1 -9
  158. package/src/pages/page-loader.js +53 -1
  159. package/src/plugin-manager.js +90 -17
  160. package/src/server.js +137 -26
  161. package/src/services/discovery.js +19 -40
  162. package/src/services/executor.js +86 -25
  163. package/src/services/memoize.js +3 -25
  164. package/src/services/registry.js +6 -0
  165. 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
+ };