@appweaver/redis 2.1.2 → 2.3.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.
package/README.md CHANGED
@@ -28,6 +28,9 @@ or `weaver module add redis` in a project created with `@appweaver/create`.
28
28
 
29
29
  The connection URL is `memory.redis.url` (`MEMORY_REDIS_URL`). The cache, the rate limit (`rateLimit.store` `auto`) and the BullMQ queue use its connection.
30
30
 
31
+ Commands time out after `memory.redis.commandTimeout`, and a circuit breaker skips Redis after repeated failures.
32
+ Meanwhile the cache falls back to the database, the rate limit is skipped, and the secure routes respond with `503`.
33
+
31
34
  ## Documentation
32
35
 
33
36
  - [Appweaver README](https://github.com/lmatosevic/appweaver#readme) – getting started, configuration, and the overview of every package
@@ -0,0 +1,24 @@
1
+ /** The callbacks of the state changes of a {@link CircuitBreaker}. */
2
+ export type CircuitBreakerListener = {
3
+ onOpen?: (failures: number) => void;
4
+ onClose?: () => void;
5
+ };
6
+ /**
7
+ * Opens after `threshold` consecutive failures and rejects the calls for
8
+ * `cooldown` ms, then lets one call through as a probe. A threshold of `0`
9
+ * never opens it.
10
+ */
11
+ export declare class CircuitBreaker {
12
+ private readonly threshold;
13
+ private readonly cooldown;
14
+ private readonly listener;
15
+ constructor(threshold: number, cooldown: number, listener?: CircuitBreakerListener);
16
+ /** Whether the calls are rejected, `false` once the cooldown allows a probe. */
17
+ isOpen(): boolean;
18
+ /** Milliseconds until the next probe, `0` while the breaker is closed. */
19
+ remaining(): number;
20
+ /** Checks whether a call may run, letting one probe through per cooldown. */
21
+ acquire(): boolean;
22
+ success(): void;
23
+ failure(): void;
24
+ }
@@ -0,0 +1,66 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.CircuitBreaker = void 0;
4
+ /**
5
+ * Opens after `threshold` consecutive failures and rejects the calls for
6
+ * `cooldown` ms, then lets one call through as a probe. A threshold of `0`
7
+ * never opens it.
8
+ */
9
+ class CircuitBreaker {
10
+ threshold;
11
+ cooldown;
12
+ listener;
13
+ /** @internal */
14
+ _failures = 0;
15
+ /** @internal */
16
+ _openedAt;
17
+ constructor(threshold, cooldown, listener = {}) {
18
+ this.threshold = threshold;
19
+ this.cooldown = cooldown;
20
+ this.listener = listener;
21
+ }
22
+ /** Whether the calls are rejected, `false` once the cooldown allows a probe. */
23
+ isOpen() {
24
+ return this._openedAt !== undefined && this.remaining() > 0;
25
+ }
26
+ /** Milliseconds until the next probe, `0` while the breaker is closed. */
27
+ remaining() {
28
+ if (this._openedAt === undefined) {
29
+ return 0;
30
+ }
31
+ return Math.max(0, this._openedAt + this.cooldown - Date.now());
32
+ }
33
+ /** Checks whether a call may run, letting one probe through per cooldown. */
34
+ acquire() {
35
+ if (this._openedAt === undefined) {
36
+ return true;
37
+ }
38
+ if (this.isOpen()) {
39
+ return false;
40
+ }
41
+ this._openedAt = Date.now();
42
+ return true;
43
+ }
44
+ success() {
45
+ this._failures = 0;
46
+ if (this._openedAt !== undefined) {
47
+ this._openedAt = undefined;
48
+ this.listener.onClose?.();
49
+ }
50
+ }
51
+ failure() {
52
+ if (this.threshold <= 0) {
53
+ return;
54
+ }
55
+ this._failures++;
56
+ if (this._openedAt !== undefined) {
57
+ // A failed probe keeps the breaker open for another cooldown
58
+ this._openedAt = Date.now();
59
+ }
60
+ else if (this._failures >= this.threshold) {
61
+ this._openedAt = Date.now();
62
+ this.listener.onOpen?.(this._failures);
63
+ }
64
+ }
65
+ }
66
+ exports.CircuitBreaker = CircuitBreaker;
@@ -0,0 +1,8 @@
1
+ import { Redis as RedisClient } from 'ioredis';
2
+ import { CircuitBreaker } from './circuit-breaker';
3
+ /**
4
+ * Sends the commands of a ready client through the circuit breaker, and fails
5
+ * the ones Redis did not answer with `MemoryUnavailable`. A client that is not
6
+ * ready, i.e. reconnecting, bypasses the breaker.
7
+ */
8
+ export declare function guardClient(client: RedisClient, breaker: CircuitBreaker): RedisClient;
@@ -0,0 +1,46 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.guardClient = guardClient;
4
+ const ioredis_1 = require("ioredis");
5
+ const common_1 = require("@appweaver/common");
6
+ /**
7
+ * Sends the commands of a ready client through the circuit breaker, and fails
8
+ * the ones Redis did not answer with `MemoryUnavailable`. A client that is not
9
+ * ready, i.e. reconnecting, bypasses the breaker.
10
+ */
11
+ function guardClient(client, breaker) {
12
+ const sendCommand = client.sendCommand.bind(client);
13
+ client.sendCommand = (command, stream) => {
14
+ const guarded = client.status === 'ready';
15
+ if (guarded && !breaker.acquire()) {
16
+ command.reject(unavailableError('Redis circuit breaker is open', breaker.remaining()));
17
+ return command.promise;
18
+ }
19
+ const { resolve, reject } = command;
20
+ command.resolve = (result) => {
21
+ if (guarded) {
22
+ breaker.success();
23
+ }
24
+ resolve(result);
25
+ };
26
+ command.reject = (error) => {
27
+ // An error reply is an answer, so Redis is available
28
+ if (error instanceof ioredis_1.ReplyError) {
29
+ if (guarded) {
30
+ breaker.success();
31
+ }
32
+ reject(error);
33
+ return;
34
+ }
35
+ if (guarded) {
36
+ breaker.failure();
37
+ }
38
+ reject(unavailableError(error.message, breaker.remaining(), error));
39
+ };
40
+ return sendCommand(command, stream);
41
+ };
42
+ return client;
43
+ }
44
+ function unavailableError(message, remaining, cause) {
45
+ return new common_1.MemoryError(common_1.ErrorCode.MemoryUnavailable, `Redis is unavailable: ${message}`, remaining > 0 ? { retryAfter: Math.ceil(remaining / 1000) } : {}, { cause });
46
+ }
package/config.d.ts CHANGED
@@ -1,3 +1,6 @@
1
1
  export declare const redisConfig: Readonly<{
2
2
  URL: string;
3
+ COMMAND_TIMEOUT: number;
4
+ CIRCUIT_BREAKER_THRESHOLD: number;
5
+ CIRCUIT_BREAKER_COOLDOWN: number;
3
6
  }>;
package/config.js CHANGED
@@ -5,5 +5,11 @@ const typebox_1 = require("@sinclair/typebox");
5
5
  const common_1 = require("@appweaver/common");
6
6
  exports.redisConfig = (0, common_1.defineConfig)('memory.redis', {
7
7
  /** Redis connection URL. Default: `'redis://localhost:6379/0'`. */
8
- URL: typebox_1.Type.String({ default: 'redis://localhost:6379/0' })
8
+ URL: typebox_1.Type.String({ default: 'redis://localhost:6379/0' }),
9
+ /** Milliseconds a command waits for its reply before it fails, `0` waits indefinitely. Default: `200`. */
10
+ COMMAND_TIMEOUT: typebox_1.Type.Integer({ default: 200, minimum: 0 }),
11
+ /** Consecutive failed commands that open the circuit breaker, `0` disables it. Default: `5`. */
12
+ CIRCUIT_BREAKER_THRESHOLD: typebox_1.Type.Integer({ default: 5, minimum: 0 }),
13
+ /** Milliseconds the open circuit breaker skips Redis before probing it. Default: `10000` (10 sec). */
14
+ CIRCUIT_BREAKER_COOLDOWN: typebox_1.Type.Integer({ default: 10000, minimum: 0 })
9
15
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@appweaver/redis",
3
- "version": "2.1.2",
3
+ "version": "2.3.0",
4
4
  "description": "Appweaver - the backend framework for AI-first development (@redis)",
5
5
  "author": "Luka Matosevic",
6
6
  "license": "MIT",
@@ -44,8 +44,8 @@
44
44
  "flatted": "3.4.2"
45
45
  },
46
46
  "peerDependencies": {
47
- "@appweaver/common": "^2.1.2",
48
- "@appweaver/core": "^2.1.2"
47
+ "@appweaver/common": "^2.3.0",
48
+ "@appweaver/core": "^2.3.0"
49
49
  },
50
50
  "devDependencies": {
51
51
  "@appweaver/common": "^1.12.2",
package/redis-memory.d.ts CHANGED
@@ -4,7 +4,11 @@ export declare class RedisMemory extends Memory<RedisOptions, RedisClient> {
4
4
  constructor();
5
5
  onInit(): Promise<void>;
6
6
  onDestroy(): Promise<void>;
7
- createClient(options?: RedisOptions): RedisClient;
7
+ /**
8
+ * Creates a client of the Redis connection, guarded by the command timeout
9
+ * and the circuit breaker unless `guarded` is false (blocking commands).
10
+ */
11
+ createClient(options?: RedisOptions, guarded?: boolean): RedisClient;
8
12
  connect(): Promise<void>;
9
13
  disconnect(): Promise<void>;
10
14
  get<T = any>(key: string): Promise<T | null>;
package/redis-memory.js CHANGED
@@ -5,9 +5,17 @@ const promises_1 = require("node:timers/promises");
5
5
  const ioredis_1 = require("ioredis");
6
6
  const flatted_1 = require("flatted");
7
7
  const common_1 = require("@appweaver/common");
8
+ const circuit_breaker_1 = require("./circuit-breaker");
9
+ const client_guard_1 = require("./client-guard");
8
10
  const config_1 = require("./config");
9
11
  const logger = (0, common_1.createLogger)('memory');
10
12
  class RedisMemory extends common_1.Memory {
13
+ /** @internal */
14
+ _breaker = new circuit_breaker_1.CircuitBreaker(config_1.redisConfig.CIRCUIT_BREAKER_THRESHOLD, config_1.redisConfig.CIRCUIT_BREAKER_COOLDOWN, {
15
+ onOpen: (failures) => logger.error(`Redis circuit breaker is open after ${failures} failed commands, ` +
16
+ `skipping Redis for ${config_1.redisConfig.CIRCUIT_BREAKER_COOLDOWN} ms`),
17
+ onClose: () => logger.info('Redis circuit breaker is closed')
18
+ });
11
19
  /** @internal */
12
20
  _options;
13
21
  /** @internal */
@@ -35,13 +43,20 @@ class RedisMemory extends common_1.Memory {
35
43
  async onDestroy() {
36
44
  await this.disconnect();
37
45
  }
38
- createClient(options = {}) {
46
+ /**
47
+ * Creates a client of the Redis connection, guarded by the command timeout
48
+ * and the circuit breaker unless `guarded` is false (blocking commands).
49
+ */
50
+ createClient(options = {}, guarded = true) {
39
51
  const client = new ioredis_1.Redis({
40
52
  ...this._options,
53
+ ...(guarded
54
+ ? { commandTimeout: config_1.redisConfig.COMMAND_TIMEOUT || undefined }
55
+ : {}),
41
56
  ...options
42
57
  });
43
58
  this.monitorConnection(client);
44
- return client;
59
+ return guarded ? (0, client_guard_1.guardClient)(client, this._breaker) : client;
45
60
  }
46
61
  async connect() {
47
62
  await this._client.connect();
@@ -116,7 +131,7 @@ class RedisMemory extends common_1.Memory {
116
131
  }
117
132
  }
118
133
  isAvailable() {
119
- return this._client.status === 'ready';
134
+ return this._client.status === 'ready' && !this._breaker.isOpen();
120
135
  }
121
136
  checkHealthConfig() {
122
137
  return { name: 'redis' };
@@ -135,6 +150,8 @@ class RedisMemory extends common_1.Memory {
135
150
  }
136
151
  });
137
152
  client.on('ready', () => {
153
+ // A new connection is not affected by the failures of the old one
154
+ this._breaker.success();
138
155
  if (lost) {
139
156
  logger.info(`Redis connection '${name}' is restored`);
140
157
  }