cachette 3.0.1 → 4.0.2

package/src/lib/RedisCache.ts

@@ -0,0 +1,431 @@
+import Redis from 'ioredis';
+import * as Redlock from 'redlock';
+
+import { CachableValue, CacheInstance } from './CacheInstance';
+
+export const SIZE_THRESHOLD_WARNING_BYTES = 20_000_000;
+
+/**
+ * Wrapper class for using Redis as a cache.
+ *
+ * If no redis_strategy nor error event handler are defined, the client
+ * will throw uncaught exceptions on stream errors! These must be defined,
+ * or the process might crash unexpectedly.
+ */
+export class RedisCache extends CacheInstance {
+
+  /**
+   * We cannot store null and booleans in Redis, so we store
+   * random values representing these values instead.
+   */
+  public static NULL_VALUE = 'f405eed4-507c-4aa5-a6d2-c1813d584b8f-NULL';
+  public static TRUE_VALUE = 'f405eed4-507c-4aa5-a6d2-c1813d584b8f-TRUE';
+  public static FALSE_VALUE = 'f405eed4-507c-4aa5-a6d2-c1813d584b8f-FALSE';
+  public static JSON_PREFIX = 'f405eed4-507c-4aa5-a6d2-c1813d584b8f-JSON';
+  public static ERROR_PREFIX = 'f405eed4-507c-4aa5-a6d2-c1813d584b8f-ERROR';
+  public static NUMBER_PREFIX = 'f405eed4-507c-4aa5-a6d2-c1813d584b8f-NUMBER';
+
+  public static REDIS_CONNECTION_TIMEOUT_MS = parseInt(process.env.REDIS_CONNECTION_TIMEOUT_MS as string, 10) || 5000;
+  public static REDLOCK_RETRY_COUNT = parseInt(process.env.REDLOCK_RETRY_COUNT as string, 10) || 20; // lib. default: 10
+  public static REDLOCK_RETRY_DELAY_MS = parseInt(process.env.REDLOCK_RETRY_DELAY_MS as string, 10) || 200; // lib. default: 200
+  public static REDLOCK_CLOCK_DRIFT_FACTOR = parseInt(process.env.REDLOCK_CLOCK_DRIFT_FACTOR as string, 10) || 0.01; // lib. default: 0.01
+  public static REDLOCK_JITTER_MS = parseInt(process.env.REDLOCK_JITTER_MS as string, 10) || 200; // lib. default: 200
+
+  private redisClient: Redis;
+  private ready = false;
+  private url: string;
+  // We manage several redlock instances because some options (like retryCount)
+  // are set at redlock init. By having these options in our constructor too
+  // (and only having one redlock with fixed behavior), we would be unable to
+  // support mixing calls requiring one behavior, then another.
+  // And so, we have as many redlocks as we need to honor these runtime needs.
+  private redlock: Redlock;
+  private redlockWithoutRetry: Redlock;
+
+  constructor(redisUrl: string, readOnly = false) {
+    super();
+
+    if (!redisUrl || (!redisUrl.startsWith('redis://') && !redisUrl.startsWith('rediss://'))) {
+      throw new Error(`Invalid redis url ${redisUrl}.`);
+    }
+
+    this.url = redisUrl;
+    this.redisClient = new Redis(redisUrl, {
+      readOnly,
+      retryStrategy: () => RedisCache.REDIS_CONNECTION_TIMEOUT_MS,
+      // Force a reconnect during Redis maintenance|upgrades, where a failover
+      // primary / replica causes clients connected to the primary to become
+      // connected to what is now a replica, and error that writes fail.
+      // Following upstream recipe at https://github.com/redis/ioredis#reconnect-on-error
+      reconnectOnError: (err: Error) => !readOnly && err.message.includes('READONLY'),
+      // This prevents get/setValue calls from hanging if there is no active connection
+      enableOfflineQueue: false,
+    });
+    this.redlock = new Redlock([this.redisClient as unknown as Redlock.CompatibleRedisClient], { // Hack until Redlock 5.x is out of beta
+      driftFactor: RedisCache.REDLOCK_CLOCK_DRIFT_FACTOR,
+      retryCount: RedisCache.REDLOCK_RETRY_COUNT,
+      retryDelay: RedisCache.REDLOCK_RETRY_DELAY_MS,
+      retryJitter: RedisCache.REDLOCK_JITTER_MS,
+    });
+    this.redlockWithoutRetry = new Redlock([this.redisClient as unknown as Redlock.CompatibleRedisClient], { // Hack until Redlock 5.x is out of beta
+      driftFactor: RedisCache.REDLOCK_CLOCK_DRIFT_FACTOR,
+      retryCount: 0,
+      retryDelay: 0,
+      retryJitter: 0,
+    });
+
+    this.redisClient.on('ready', this.startConnectionStrategy.bind(this));
+    this.redisClient.on('end', this.endConnectionStrategy.bind(this));
+    this.redisClient.on('error', this.errorStrategy.bind(this));
+
+    // TODO when migrating to Redlock v5: rename 'clientError' to 'error'
+    this.redlock.on('clientError', this.redlockErrorStrategy.bind(this));
+    this.redlockWithoutRetry.on('clientError', this.redlockErrorStrategy.bind(this));
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async isReady(): Promise<void> {
+    if (this.ready) {
+      return;
+    }
+    return new Promise<void>(resolve => this.redisClient.on('ready', resolve));
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async itemCount(): Promise<number> {
+    return this.redisClient.dbsize();
+  }
+
+  /**
+   * The error event is emitted on stream error.
+   * We must catch it, otherwise it will crash the process
+   * with an UncaughtException.
+   */
+  public errorStrategy(): void {
+    this.emit('warn', 'Error while connected to the Redis cache!');
+  }
+
+  public redlockErrorStrategy(err: any): void {
+    this.emit('warn', 'Redlock error:', err);
+  }
+
+  /**
+   * The end event is emitted by the redis client when an
+   * established connection has ended.
+   */
+  public endConnectionStrategy(err): void {
+    this.emit('warn', 'Connection lost to Redis.', err);
+  }
+
+  /**
+   * The connect event is emitted by the redis client as
+   * soon as a new connection is established.
+   */
+  public startConnectionStrategy(): void {
+    this.ready = true;
+    this.emit('info', `Connection established to Redis at ${this.url}`);
+  }
+
+  /**
+   * Some values are not supported by Redis and/or by the
+   * Redis client library.
+   * As per the documentation:
+   * > Please be aware that sending null, undefined and Boolean
+   * > values will result in the value coerced to a string!
+   *
+   * We serialize these values to be able to store
+   * and retrieve them as strings.
+   *
+   */
+  public static serializeValue(value: CachableValue): string {
+
+    if (value === null) {
+      return RedisCache.NULL_VALUE;
+    }
+
+    if (value === true) {
+      return RedisCache.TRUE_VALUE;
+    }
+
+    if (value === false) {
+      return RedisCache.FALSE_VALUE;
+    }
+
+    if (value instanceof Error) {
+      return RedisCache.ERROR_PREFIX + JSON.stringify({
+        ...value, // serialize potential Error metadata set as object properties
+        message: value.message,
+      });
+    }
+
+    if (typeof value === 'number') {
+      return `${RedisCache.NUMBER_PREFIX}${value}`;
+    }
+
+    if (value instanceof Object) {
+      return RedisCache.JSON_PREFIX + JSON.stringify(value,  (key, value) => {
+        if (value instanceof Set) {
+          return { __dataType: 'Set', value: Array.from(value) };
+        } else if (value instanceof Map) {
+          return { __dataType: 'Map', value: Array.from(value) };
+        } else {
+          return value;
+        }
+      });
+    }
+
+    return value;
+  }
+
+  /**
+   * Deserializes a value coming from Redis.
+   *
+   * As per the documentation:
+   * > Minimal parsing is done on the replies. Commands that return a
+   * > integer return JavaScript Numbers, arrays return JavaScript Array.
+   * > HGETALL returns an Object keyed by the hash keys.
+   *
+   * also from the documentation:
+   * > If the key is missing, reply will be null.
+   *
+   */
+  public static deserializeValue(value: string | null): CachableValue {
+
+    if (value === null) {
+      // null means that the key was not present, which we interpret as undefined.
+      return undefined;
+    }
+
+    if (value === RedisCache.NULL_VALUE) {
+      return null;
+    }
+
+    if (value === RedisCache.TRUE_VALUE) {
+      return true;
+    }
+
+    if (value === RedisCache.FALSE_VALUE) {
+      return false;
+    }
+
+    if (value.startsWith(RedisCache.ERROR_PREFIX)) {
+      const deserializedError = JSON.parse(value.substring(RedisCache.ERROR_PREFIX.length));
+      // return error, restoring potential Error metadata set as object properties
+      return Object.assign(new Error(deserializedError.message), deserializedError);
+    }
+
+    if (value.startsWith(RedisCache.NUMBER_PREFIX)) {
+      const deserializedNumber = value.substring(RedisCache.NUMBER_PREFIX.length);
+      return Number.parseFloat(deserializedNumber);
+    }
+
+    if (value.startsWith(RedisCache.JSON_PREFIX)) {
+      return JSON.parse(value.substring(RedisCache.JSON_PREFIX.length), (key, value) => {
+        if (typeof value === 'object' && value !== null) {
+          if (value.__dataType === 'Set') {
+            return new Set(value.value);
+          } else if (value.__dataType === 'Map') {
+            return new Map(value.value);
+          } else {
+            return value;
+          }
+        } else {
+          return value;
+        }
+      });
+    }
+
+    return value;
+
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async setValue(
+    key: string,
+    value: CachableValue,
+    ttl = 0,
+  ): Promise<boolean> {
+    try {
+      return await this.setValueInternal(key, value, ttl);
+    } catch (err) {
+       // Examples of things that may occur here:
+       // - A timeout, if the connection was broken during a value fetch.
+       // - A general error, e.g. if Redis is Out Of Memory.
+      const error = err as Error;
+      this.emit('warn', `Error while setting Redis key ${key} with ttl ${ttl}: ${error.name} - ${error.message}\n${error.stack}`);
+      return false;
+    }
+  }
+
+  public async setValueInternal(
+    key: string,
+    value: CachableValue,
+    ttl: number,
+  ): Promise<boolean> {
+    this.emit('set', key, value);
+
+    if (value === undefined) {
+      this.emit('warn', `Cannot set ${key} to undefined!`);
+      return false;
+    }
+
+    value = RedisCache.serializeValue(value);
+
+    const serializedValueBytes = Buffer.byteLength(value, 'utf8');
+    if (serializedValueBytes >= SIZE_THRESHOLD_WARNING_BYTES) {
+      const mb = Math.round(serializedValueBytes / 1_000_000);
+      this.emit('warn', `Writing large value to Redis! Key "${key}" with ttl=${ttl} has a value of ${mb} MB!`);
+    }
+
+    let result: 'OK' | undefined;
+    if (ttl !== 0) {
+      result = await this.redisClient.set(key, value, 'EX', ttl);
+    } else {
+      result = await this.redisClient.set(key, value);
+    }
+
+    return result === 'OK';
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async getValue(key: string): Promise<CachableValue> {
+    try {
+      return await this.getValueInternal(key);
+    } catch (error) {
+      /**
+       * A timeout can occur if the connection was broken during
+       * a value fetching. We don't want to hang forever if this is the case.
+       */
+      this.emit('warn', 'Error while fetching value from the Redis cache', error);
+      return undefined;
+    }
+  }
+
+  private async getValueInternal(key: string): Promise<CachableValue> {
+    const value = await this.redisClient.get(key);
+    this.emit('get', key, value);
+    return RedisCache.deserializeValue(value);
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async getTtl(key: string): Promise<number | undefined> {
+    try {
+      const ttl = await this.redisClient.pttl(key);
+      if (ttl === -1) {
+        return 0;
+      }
+      if (ttl <= 0) {
+        return undefined;
+      }
+      return ttl;
+    } catch (error) {
+      this.emit('warn', 'Error while fetching ttl from the Redis cache', error);
+      return undefined;
+    }
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async delValue(key: string): Promise<void> {
+    this.emit('del', key);
+    await this.redisClient.del(key);
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async waitForReplication(replicas: number, timeout: number): Promise<number> {
+    this.emit('wait');
+    return this.redisClient.wait(replicas, timeout);
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async clear(): Promise<void> {
+    await this.redisClient.flushall();
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async clearMemory(): Promise<void> {
+    return;
+  }
+
+  /**
+   * @inheritdoc
+   * Locking through the redlock algorithm
+   * https://redis.io/topics/distlock
+   */
+  public isLockingSupported(): boolean {
+    return true;
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async lock(resource: string, ttlMs: number, retry = true): Promise<Redlock.Lock> {
+    const redlock = retry === false ? this.redlockWithoutRetry : this.redlock;
+    return redlock.lock(resource, ttlMs);
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async unlock(lock: Redlock.Lock): Promise<void> {
+    return this.redlock.unlock(lock);
+  }
+
+  /**
+   * @inheritdoc
+   *
+   * Implementation note & usage ***warning***: looking at Redis docs and the www,
+   *   there's no "index-backed" Redis function to do this in O(1).
+   *
+   * So, doing it with a Redis SCAN, https://redis.io/commands/scan . In many use cases it's okay,
+   * 1. Because Redis SCAN is fast (10M keys / 40ms on a laptop)
+   * 2. If your use case writes a reasonable number of locks, and sets reasonably-small TTLs,
+   *    guaranteeing Redis contains a reasonable-to-scan volume of items (depending on your hardware).
+   *
+   * Recommendation: This implies **workloads relying on this function should
+   * own their own Redis db**, to not scan through tons of unrelated keys.
+   *
+   * Implementation note: you might try to use instead a redis Hashmap / Set / Sorted set to group
+   * "sublocks", to be able use H/S/Z Redis functions to query efficiently inside a group of locks.
+   * That won't work in use cases where you need one TTL per lock, because it'd limit to one TTL
+   * (associated to a Redis *value*!) per prefix. Thus, values with TTLs, thus, SCAN.
+   */
+  public async hasLock(prefix: string): Promise<boolean> {
+    const redisPrefix = prefix.endsWith('*') ? prefix : `${prefix}*`;
+    let cursor = '';
+    while (cursor !== '0') { // indicates Redis completed the scan
+      // Redis detail: we set the `count` option to a number (1000) greater than
+      // the default (10), to minimize the amount of network round-trips caused
+      // by incomplete scans needing more scanning from the returned cursor.
+      const [nextCursor, matchingKeys] = await this.redisClient.scan(cursor || '0', 'MATCH', redisPrefix, 'COUNT', 1000);
+      if (matchingKeys.length > 0) {
+        return true;
+      }
+      cursor = nextCursor;
+    }
+
+    return false;
+  }
+
+  public async quit(): Promise<void> {
+    await this.redisClient.quit();
+  }
+
+}

package/src/lib/WriteThroughCache.ts

@@ -0,0 +1,200 @@
+import { CachableValue, CacheInstance } from './CacheInstance';
+import { RedisCache } from './RedisCache';
+import { LocalCache } from './LocalCache';
+
+
+/**
+ * Write-through cache, using Redis and a local LRU cache with aligned TTLs.
+ *
+ * **WARNING** if using this in a distributed app where cache consistency matters!
+ * Consider this case of an app with several servers/instances using WriteThroughCache:
+ *  1. Instance I1 sets key/value foo: bar (both local & redis)
+ *  2. Instance I2 gets value foo, populating its local cache with "bar"
+ *  ----- At that moment, LocalCaches of I1 & I2 are aligned, foo: bar
+ *  3. Instance I1 deletes key foo (both local & redis)
+ *  ----- At that moment, LocalCaches of I1 & I2 are *mis*aligned about foo!
+ *        - I1 has nothing
+ *        - I2 has "bar"
+ *
+ * -> This is fixable, e.g. using Redis pub/sub, to let clients subscribe to
+ *    set/del events, and react with an eviction from their LocalCache.
+ *    In the context where we cachette maintainers got bitten by this, it made
+ *    sense to just abandon usage of WriteThroughCache, and switch the app with
+ *    high consistency expectations from a WriteThroughCache to a RedisCache:
+ *      +++: simpler, more consistent
+ *      ---: a tolerable increase in Redis usage (CPU, network, latency)
+ *
+ *    So, pub/sub remains unimplemented, but it would be a reasonable addition.
+ *    API design consideration: set/dels maybe shouldn't *always* cause Redis
+ *    publish (said differently, maybe not *all* set/dels should cause a
+ *    LocalCache eviction, to limit pub/sub traffic explosion? Maybe, or maybe
+ *    "pub/sub traffic explosion" is a non-concern? To be evaluated :)
+ */
+export class WriteThroughCache extends CacheInstance {
+
+  private redisCacheForWriting: CacheInstance;
+  private redisCacheForReading: CacheInstance;
+  private localCache: CacheInstance;
+
+  private metrics: {
+    enabled: boolean;
+    localHits: number;
+    redisHits: number;
+    doubleMisses: number;
+  };
+
+  constructor(redisUrl: string) {
+    super();
+    this.redisCacheForWriting = new RedisCache(redisUrl);
+    this.redisCacheForReading = new RedisCache(redisUrl, true);
+    this.localCache = new LocalCache();
+
+    this.metrics = {
+      enabled: false,
+      localHits: 0,
+      redisHits: 0,
+      doubleMisses: 0,
+    };
+    if (process.env.CACHETTE_METRICS_PERIOD_MINUTES) {
+      const metricsPeriod = parseInt(process.env.CACHETTE_METRICS_PERIOD_MINUTES, 10);
+      if (Number.isInteger(metricsPeriod) && metricsPeriod > 0) {
+        this.metrics.enabled = true;
+        this.redisCacheForWriting.emit('info', `WriteThroughCache metrics enabled, will report every ${metricsPeriod} min`);
+        setInterval(() => {
+          const total = this.metrics.localHits + this.metrics.redisHits + this.metrics.doubleMisses;
+          this.redisCacheForWriting.emit(
+            'info',
+            `WriteThroughCache metrics during last ${metricsPeriod} min - Total: ${total}, ` +
+            `Local hits: ${this.metrics.localHits} (${total && Math.floor(100 * this.metrics.localHits / total)}%), ` +
+            `Redis hits: ${this.metrics.redisHits} (${total && Math.floor(100 * this.metrics.redisHits / total)}%), ` +
+            `Double misses: ${this.metrics.doubleMisses} (${total && Math.floor(100 * this.metrics.doubleMisses / total)}%).`,
+          );
+
+          this.metrics.localHits = 0;
+          this.metrics.redisHits = 0;
+          this.metrics.doubleMisses = 0;
+        }, metricsPeriod * 60 * 1000);
+      } else {
+        this.redisCacheForWriting.emit(
+          'warn',
+          'WriteThroughCache metrics activation impossible, CACHETTE_METRICS_PERIOD_MINUTES is invalid. ' +
+          `Must be a positive integer, but was ${process.env.CACHETTE_METRICS_PERIOD_MINUTES}`);
+      }
+    }
+  }
+
+  public on(eventName: string | symbol, listener: (...args: any[]) => void): this {
+    this.redisCacheForWriting.on(eventName, listener);
+    this.redisCacheForReading.on(eventName, listener);
+    this.localCache.on(eventName, listener);
+    return this;
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async isReady(): Promise<any> {
+    return Promise.all([this.redisCacheForWriting.isReady(), this.redisCacheForReading.isReady()]);
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async itemCount(): Promise<number> {
+    return await this.redisCacheForReading.itemCount() + await this.localCache.itemCount();
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async setValue(
+    key: string,
+    value: CachableValue,
+    ttl = 0,
+  ): Promise<boolean> {
+    const response = await this.localCache.setValue(key, value, ttl);
+    return await this.redisCacheForWriting.setValue(key, value, ttl) && response;
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async getValue(key: string): Promise<CachableValue> {
+    const localValue = await this.localCache.getValue(key);
+    if (localValue !== undefined) {
+      if (this.metrics.enabled) {
+        this.metrics.localHits++;
+      }
+      return localValue;
+    }
+    const [redisValue, ttl] = await Promise.all([
+      this.redisCacheForReading.getValue(key),
+      this.redisCacheForWriting.getTtl(key),
+    ]);
+
+    if (redisValue !== undefined && ttl !== undefined) {
+      await this.localCache.setValue(key, redisValue, ttl / 1000);
+      if (this.metrics.enabled) {
+        this.metrics.redisHits++;
+      }
+      return redisValue;
+    }
+
+    if (this.metrics.enabled) {
+      this.metrics.doubleMisses++;
+    }
+    return redisValue;
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async getTtl(key: string): Promise<number | undefined> {
+    return this.redisCacheForWriting.getTtl(key);
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async delValue(key: string): Promise<void> {
+    this.emit('del', key);
+    await this.localCache.delValue(key);
+    await this.redisCacheForWriting.delValue(key);
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async waitForReplication(replicas: number, timeout: number): Promise<number> {
+    this.emit('wait')
+    await this.localCache.waitForReplication(replicas, timeout);
+    return this.redisCacheForWriting.waitForReplication(replicas, timeout);
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async clear(): Promise<void> {
+    await this.localCache.clear();
+    await this.redisCacheForWriting.clear();
+  }
+
+  /**
+   * @inheritdoc
+   */
+  public async clearMemory(): Promise<void> {
+    await this.localCache.clearMemory();
+    await this.redisCacheForWriting.clearMemory();
+  }
+
+  /**
+   * @inheritdoc
+   * Locking is *not* supported by the Write-Through cache. You want either:
+   * - The full-fledged RedisCache for prod workloads
+   * - A dumb LocalCache for dev/local workloads
+   */
+  public isLockingSupported(): boolean {
+    return false;
+  }
+
+}