@windrun-huaiin/backend-core 12.0.0 → 14.0.0

package/src/lib/upstash/redis-counter.ts

@@ -0,0 +1,35 @@
+import { withRedis } from '../upstash-config';
+
+/**
+ * Increment a counter (e.g. views, forwards). Returns null if Redis is unavailable.
+ */
+export const incrCounter = async (key: string, delta = 1): Promise<number | null> => {
+  return withRedis((redis) => redis.incrby(key, delta));
+};
+
+/**
+ * Get a counter value. Returns null if Redis is unavailable.
+ */
+export const getCounter = async (key: string): Promise<number | null> => {
+  return withRedis(async (redis) => {
+    const value = await redis.get<number>(key);
+    return value ?? 0;
+  });
+};
+
+/**
+ * Increment a unique counter via SET (e.g. unique views). Returns null if Redis is unavailable.
+ */
+export const incrUniqueCounter = async (setKey: string, memberId: string): Promise<number | null> => {
+  return withRedis(async (redis) => {
+    await redis.sadd(setKey, memberId);
+    return redis.scard(setKey);
+  });
+};
+
+/**
+ * Get unique counter value (SET cardinality). Returns null if Redis is unavailable.
+ */
+export const getUniqueCounter = async (setKey: string): Promise<number | null> => {
+  return withRedis((redis) => redis.scard(setKey));
+};

package/src/lib/upstash/redis-favorite.ts

@@ -0,0 +1,56 @@
+import { withRedis } from '../upstash-config';
+
+const favoriteTargetKey = (targetId: string): string => `favorite:target:${targetId}`;
+const favoriteUserKey = (userId: string): string => `favorite:user:${userId}`;
+
+/**
+ * Favorite a target. Returns true if added, false if already favorited, null if Redis is unavailable.
+ */
+export const addFavorite = async (targetId: string, userId: string): Promise<boolean | null> => {
+  return withRedis(async (redis) => {
+    const added = await redis.sadd(favoriteTargetKey(targetId), userId);
+    if (added === 1) {
+      await redis.sadd(favoriteUserKey(userId), targetId);
+      return true;
+    }
+    return false;
+  });
+};
+
+/**
+ * Remove a favorite. Returns true if removed, false if not found, null if Redis is unavailable.
+ */
+export const removeFavorite = async (targetId: string, userId: string): Promise<boolean | null> => {
+  return withRedis(async (redis) => {
+    const removed = await redis.srem(favoriteTargetKey(targetId), userId);
+    if (removed === 1) {
+      await redis.srem(favoriteUserKey(userId), targetId);
+      return true;
+    }
+    return false;
+  });
+};
+
+/**
+ * Check whether a user has favorited a target. Returns null if Redis is unavailable.
+ */
+export const isFavorited = async (targetId: string, userId: string): Promise<boolean | null> => {
+  return withRedis(async (redis) => {
+    const result = await redis.sismember(favoriteTargetKey(targetId), userId);
+    return result === 1;
+  });
+};
+
+/**
+ * Get favorite count for a target. Returns null if Redis is unavailable.
+ */
+export const getFavoriteCount = async (targetId: string): Promise<number | null> => {
+  return withRedis((redis) => redis.scard(favoriteTargetKey(targetId)));
+};
+
+/**
+ * Get target ids favorited by a user. Returns null if Redis is unavailable.
+ */
+export const getUserFavorites = async (userId: string): Promise<string[] | null> => {
+  return withRedis((redis) => redis.smembers<string[]>(favoriteUserKey(userId)));
+};

package/src/lib/upstash/redis-like.ts

@@ -0,0 +1,56 @@
+import { withRedis } from '../upstash-config';
+
+const likeTargetKey = (targetId: string): string => `like:target:${targetId}`;
+const likeUserKey = (userId: string): string => `like:user:${userId}`;
+
+/**
+ * Like a target. Returns true if the like was added, false if it already existed, null if Redis is unavailable.
+ */
+export const likeTarget = async (targetId: string, userId: string): Promise<boolean | null> => {
+  return withRedis(async (redis) => {
+    const added = await redis.sadd(likeTargetKey(targetId), userId);
+    if (added === 1) {
+      await redis.sadd(likeUserKey(userId), targetId);
+      return true;
+    }
+    return false;
+  });
+};
+
+/**
+ * Unlike a target. Returns true if removed, false if it didn't exist, null if Redis is unavailable.
+ */
+export const unlikeTarget = async (targetId: string, userId: string): Promise<boolean | null> => {
+  return withRedis(async (redis) => {
+    const removed = await redis.srem(likeTargetKey(targetId), userId);
+    if (removed === 1) {
+      await redis.srem(likeUserKey(userId), targetId);
+      return true;
+    }
+    return false;
+  });
+};
+
+/**
+ * Check whether a user liked a target. Returns null if Redis is unavailable.
+ */
+export const isTargetLiked = async (targetId: string, userId: string): Promise<boolean | null> => {
+  return withRedis(async (redis) => {
+    const result = await redis.sismember(likeTargetKey(targetId), userId);
+    return result === 1;
+  });
+};
+
+/**
+ * Get like count for a target (unique by user). Returns null if Redis is unavailable.
+ */
+export const getTargetLikeCount = async (targetId: string): Promise<number | null> => {
+  return withRedis((redis) => redis.scard(likeTargetKey(targetId)));
+};
+
+/**
+ * Get target ids liked by a user. Returns null if Redis is unavailable.
+ */
+export const getUserLikedTargets = async (userId: string): Promise<string[] | null> => {
+  return withRedis((redis) => redis.smembers<string[]>(likeUserKey(userId)));
+};

package/src/lib/upstash/redis-lock.ts

@@ -0,0 +1,59 @@
+import { withRedis } from '../upstash-config';
+
+const unlockScript = `
+if redis.call("get", KEYS[1]) == ARGV[1] then
+  return redis.call("del", KEYS[1])
+else
+  return 0
+end
+`;
+
+const generateToken = (): string => {
+  try {
+    return crypto.randomUUID();
+  } catch {
+    return `${Date.now()}-${Math.random().toString(16).slice(2)}`;
+  }
+};
+
+/**
+ * Acquire a distributed lock. Returns the lock token or null when unavailable.
+ */
+export const acquireLock = async (key: string, ttlMs: number): Promise<string | null> => {
+  return withRedis(async (redis) => {
+    const token = generateToken();
+    const result = await redis.set(key, token, { nx: true, px: ttlMs });
+    return result === 'OK' ? token : null;
+  });
+};
+
+/**
+ * Release a distributed lock. Returns false when the lock client is unavailable.
+ */
+export const releaseLock = async (key: string, token: string): Promise<boolean> => {
+  const result = await withRedis(async (redis) => {
+    const released = await redis.eval(unlockScript, [key], [token]);
+    return Number(released) === 1;
+  });
+  return result ?? false;
+};
+
+/**
+ * Run a function under a distributed lock. Returns null when the lock is unavailable.
+ */
+export const withLock = async <T>(
+  key: string,
+  ttlMs: number,
+  fn: () => Promise<T> | T
+): Promise<T | null> => {
+  const token = await acquireLock(key, ttlMs);
+  if (!token) {
+    return null;
+  }
+
+  try {
+    return await fn();
+  } finally {
+    await releaseLock(key, token);
+  }
+};

package/src/lib/upstash/redis-structures.ts

@@ -0,0 +1,200 @@
+import { withRedis } from '../upstash-config';
+
+/**
+ * Set a plain string value with optional TTL (seconds).
+ */
+export const setString = async (
+  key: string,
+  value: string,
+  ttlSec?: number
+): Promise<boolean> => {
+  return withRedis(async (redis) => {
+    if (ttlSec && ttlSec > 0) {
+      await redis.set(key, value, { ex: ttlSec });
+      return true;
+    }
+
+    await redis.set(key, value);
+    return true;
+  }).then((result) => result ?? false);
+};
+
+/**
+ * Get a plain string value. Returns null if Redis is unavailable or key missing.
+ */
+export const getString = async (key: string): Promise<string | null> => {
+  return withRedis((redis) => redis.get<string>(key));
+};
+
+/**
+ * Store an object as JSON string with optional TTL (seconds).
+ */
+export const setJson = async <T>(
+  key: string,
+  value: T,
+  ttlSec?: number
+): Promise<boolean> => {
+  return withRedis(async (redis) => {
+    const payload = JSON.stringify(value);
+    if (ttlSec && ttlSec > 0) {
+      await redis.set(key, payload, { ex: ttlSec });
+      return true;
+    }
+
+    await redis.set(key, payload);
+    return true;
+  }).then((result) => result ?? false);
+};
+
+/**
+ * Get an object stored as JSON string. Returns null if missing or invalid JSON.
+ */
+export const getJson = async <T>(key: string): Promise<T | null> => {
+  return withRedis(async (redis) => {
+    const payload = await redis.get<string>(key);
+    if (!payload) {
+      return null;
+    }
+
+    try {
+      return JSON.parse(payload) as T;
+    } catch {
+      return null;
+    }
+  });
+};
+
+/**
+ * Delete a key. Returns false if Redis is unavailable.
+ */
+export const deleteKey = async (key: string): Promise<boolean> => {
+  const result = await withRedis(async (redis) => {
+    const deleted = await redis.del(key);
+    return deleted > 0;
+  });
+  return result ?? false;
+};
+
+/**
+ * Set a hash field value.
+ */
+export const setHashField = async (key: string, field: string, value: string): Promise<boolean> => {
+  const result = await withRedis(async (redis) => {
+    const changed = await redis.hset(key, { [field]: value });
+    return changed > 0;
+  });
+  return result ?? false;
+};
+
+/**
+ * Get a hash field value.
+ */
+export const getHashField = async (key: string, field: string): Promise<string | null> => {
+  return withRedis((redis) => redis.hget<string>(key, field));
+};
+
+/**
+ * Store a hash field as JSON string.
+ */
+export const setHashJson = async <T>(
+  key: string,
+  field: string,
+  value: T
+): Promise<boolean> => {
+  const result = await withRedis(async (redis) => {
+    const payload = JSON.stringify(value);
+    const changed = await redis.hset(key, { [field]: payload });
+    return changed > 0;
+  });
+  return result ?? false;
+};
+
+/**
+ * Get a hash field stored as JSON string.
+ */
+export const getHashJson = async <T>(key: string, field: string): Promise<T | null> => {
+  return withRedis(async (redis) => {
+    const payload = await redis.hget<string>(key, field);
+    if (!payload) {
+      return null;
+    }
+
+    try {
+      return JSON.parse(payload) as T;
+    } catch {
+      return null;
+    }
+  });
+};
+
+/**
+ * Get all hash fields.
+ */
+export const getHashAll = async (key: string): Promise<Record<string, string> | null> => {
+  return withRedis(async (redis) => {
+    const result = await redis.hgetall<Record<string, string>>(key);
+    return result ?? {};
+  });
+};
+
+/**
+ * Remove a hash field.
+ */
+export const deleteHashField = async (key: string, field: string): Promise<boolean> => {
+  const result = await withRedis(async (redis) => {
+    const removed = await redis.hdel(key, field);
+    return removed > 0;
+  });
+  return result ?? false;
+};
+
+type ListDirection = 'left' | 'right';
+
+/**
+ * Push values to a list. Returns list length or null if Redis is unavailable.
+ */
+export const pushList = async (
+  key: string,
+  values: string[],
+  direction: ListDirection = 'right'
+): Promise<number | null> => {
+  return withRedis((redis) => {
+    if (values.length === 0) {
+      return redis.llen(key);
+    }
+
+    return direction === 'left'
+      ? redis.lpush(key, ...values)
+      : redis.rpush(key, ...values);
+  });
+};
+
+/**
+ * Pop a value from a list.
+ */
+export const popList = async (
+  key: string,
+  direction: ListDirection = 'right'
+): Promise<string | null> => {
+  return withRedis((redis) =>
+    direction === 'left' ? redis.lpop<string>(key) : redis.rpop<string>(key)
+  );
+};
+
+/**
+ * Get a range from a list.
+ */
+export const rangeList = async (
+  key: string,
+  start = 0,
+  stop = -1
+): Promise<string[] | null> => {
+  return withRedis((redis) => redis.lrange<string>(key, start, stop));
+};
+
+/**
+ * Get list length.
+ */
+export const listLength = async (key: string): Promise<number | null> => {
+  return withRedis((redis) => redis.llen(key));
+};

package/src/lib/upstash-config.ts

@@ -0,0 +1,261 @@
+import { Redis } from '@upstash/redis';
+import { Client as QstashClient } from '@upstash/qstash';
+
+let cachedRedis: Redis | null = null;
+let cachedQstash: QstashClient | null = null;
+let redisInitPromise: Promise<Redis | null> | null = null;
+let qstashInitPromise: Promise<QstashClient | null> | null = null;
+
+let redisWarnedMissingEnv = false;
+let redisWarnedInvalidEnv = false;
+let redisWarnedInitError = false;
+let redisWarnedHealthCheck = false;
+let redisWarnedHealthSchedule = false;
+
+let qstashWarnedMissingEnv = false;
+let qstashWarnedInitError = false;
+let qstashWarnedHealthCheck = false;
+let qstashWarnedHealthSchedule = false;
+
+let redisHealthTimer: ReturnType<typeof setTimeout> | null = null;
+let qstashHealthTimer: ReturnType<typeof setTimeout> | null = null;
+
+const isNonEmpty = (value: string | undefined): value is string =>
+  typeof value === 'string' && value.trim().length > 0;
+
+const isValidUrl = (value: string): boolean => {
+  try {
+    const parsed = new URL(value);
+    return parsed.protocol === 'http:' || parsed.protocol === 'https:';
+  } catch {
+    return false;
+  }
+};
+
+const parseMinutes = (value: string | undefined, fallback: number): number => {
+  if (!isNonEmpty(value)) {
+    return fallback;
+  }
+  const minutes = Number(value);
+  if (!Number.isFinite(minutes) || minutes <= 0) {
+    return fallback;
+  }
+  return minutes;
+};
+
+const getRedisHealthIntervalMinutes = (): number =>
+  parseMinutes(process.env.UPSTASH_REDIS_HEALTHCHECK_INTERVAL_MINUTES, 10);
+
+const getQstashHealthIntervalMinutes = (): number =>
+  parseMinutes(process.env.UPSTASH_QSTASH_HEALTHCHECK_INTERVAL_MINUTES, 10);
+
+const getQstashHealthcheckUrl = (): string =>
+  process.env.UPSTASH_QSTASH_HEALTHCHECK_URL ?? 'https://qstash.upstash.io/v2/topics';
+
+const scheduleRedisHealthCheck = (): void => {
+  if (redisHealthTimer || !cachedRedis) {
+    return;
+  }
+  const delayMs = getRedisHealthIntervalMinutes() * 60_000;
+  redisHealthTimer = setTimeout(async () => {
+    redisHealthTimer = null;
+    if (!cachedRedis) {
+      return;
+    }
+    try {
+      await cachedRedis.ping();
+    } catch (error) {
+      cachedRedis = null;
+      if (!redisWarnedHealthCheck) {
+        redisWarnedHealthCheck = true;
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[Upstash Config] Redis health check failed: ${message}`);
+      }
+    } finally {
+      try {
+        scheduleRedisHealthCheck();
+      } catch (error) {
+        if (!redisWarnedHealthSchedule) {
+          redisWarnedHealthSchedule = true;
+          const message = error instanceof Error ? error.message : String(error);
+          console.warn(`[Upstash Config] Redis health check schedule failed: ${message}`);
+        }
+      }
+    }
+  }, delayMs);
+};
+
+const checkQstashHealth = async (token: string): Promise<void> => {
+  const response = await fetch(getQstashHealthcheckUrl(), {
+    method: 'GET',
+    headers: {
+      Authorization: `Bearer ${token}`,
+    },
+    cache: 'no-store',
+  });
+  if (!response.ok) {
+    throw new Error(`HTTP ${response.status}`);
+  }
+};
+
+const scheduleQstashHealthCheck = (token: string): void => {
+  if (qstashHealthTimer || !cachedQstash) {
+    return;
+  }
+  const delayMs = getQstashHealthIntervalMinutes() * 60_000;
+  qstashHealthTimer = setTimeout(async () => {
+    qstashHealthTimer = null;
+    if (!cachedQstash) {
+      return;
+    }
+    try {
+      await checkQstashHealth(token);
+    } catch (error) {
+      cachedQstash = null;
+      if (!qstashWarnedHealthCheck) {
+        qstashWarnedHealthCheck = true;
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[Upstash Config] QStash health check failed: ${message}`);
+      }
+    } finally {
+      try {
+        scheduleQstashHealthCheck(token);
+      } catch (error) {
+        if (!qstashWarnedHealthSchedule) {
+          qstashWarnedHealthSchedule = true;
+          const message = error instanceof Error ? error.message : String(error);
+          console.warn(`[Upstash Config] QStash health check schedule failed: ${message}`);
+        }
+      }
+    }
+  }, delayMs);
+};
+
+/**
+ * Get the Upstash Redis client. Returns null when required env vars are missing/invalid.
+ *
+ * Singleton semantics:
+ * - read-through cached instance only
+ */
+export const getRedis = (): Redis | null => {
+  return cachedRedis;
+};
+
+const ensureRedis = async (): Promise<Redis | null> => {
+  if (cachedRedis) {
+    return cachedRedis;
+  }
+  if (redisInitPromise) {
+    return redisInitPromise;
+  }
+
+  redisInitPromise = (async () => {
+    const { UPSTASH_REDIS_REST_URL, UPSTASH_REDIS_REST_TOKEN } = process.env;
+    if (!isNonEmpty(UPSTASH_REDIS_REST_URL) || !isNonEmpty(UPSTASH_REDIS_REST_TOKEN)) {
+      if (!redisWarnedMissingEnv) {
+        redisWarnedMissingEnv = true;
+        console.warn(
+          '[Upstash Config] Redis disabled: missing UPSTASH_REDIS_REST_URL or UPSTASH_REDIS_REST_TOKEN'
+        );
+      }
+      return null;
+    }
+
+    if (!isValidUrl(UPSTASH_REDIS_REST_URL)) {
+      if (!redisWarnedInvalidEnv) {
+        redisWarnedInvalidEnv = true;
+        console.warn('[Upstash Config] Redis disabled: UPSTASH_REDIS_REST_URL is not a valid URL');
+      }
+      return null;
+    }
+
+    try {
+      const client = new Redis({
+        url: UPSTASH_REDIS_REST_URL,
+        token: UPSTASH_REDIS_REST_TOKEN,
+      });
+      await client.ping();
+      cachedRedis = client;
+      scheduleRedisHealthCheck();
+      return cachedRedis;
+    } catch (error) {
+      if (!redisWarnedInitError) {
+        redisWarnedInitError = true;
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[Upstash Config] Redis init failed: ${message}`);
+      }
+      return null;
+    } finally {
+      redisInitPromise = null;
+    }
+  })();
+
+  return redisInitPromise;
+};
+
+/**
+ * Get the Upstash QStash client. Returns null when required env vars are missing.
+ *
+ * Singleton semantics:
+ * - read-through cached instance only
+ */
+export const getQstash = (): QstashClient | null => {
+  return cachedQstash;
+};
+
+const ensureQstash = async (): Promise<QstashClient | null> => {
+  if (cachedQstash) {
+    return cachedQstash;
+  }
+  if (qstashInitPromise) {
+    return qstashInitPromise;
+  }
+
+  qstashInitPromise = (async () => {
+    const { QSTASH_TOKEN } = process.env;
+    if (!isNonEmpty(QSTASH_TOKEN)) {
+      if (!qstashWarnedMissingEnv) {
+        qstashWarnedMissingEnv = true;
+        console.warn('[Upstash Config] QStash disabled: missing QSTASH_TOKEN');
+      }
+      return null;
+    }
+
+    try {
+      const client = new QstashClient({ token: QSTASH_TOKEN });
+      await checkQstashHealth(QSTASH_TOKEN);
+      cachedQstash = client;
+      scheduleQstashHealthCheck(QSTASH_TOKEN);
+      return cachedQstash;
+    } catch (error) {
+      if (!qstashWarnedInitError) {
+        qstashWarnedInitError = true;
+        const message = error instanceof Error ? error.message : String(error);
+        console.warn(`[Upstash Config] QStash init failed: ${message}`);
+      }
+      return null;
+    } finally {
+      qstashInitPromise = null;
+    }
+  })();
+
+  return qstashInitPromise;
+};
+
+export const withRedis = async <T>(fn: (redis: Redis) => Promise<T> | T): Promise<T | null> => {
+  const redis = await ensureRedis();
+  if (!redis) {
+    return null;
+  }
+  return fn(redis);
+};
+
+export const withQstash = async <T>(
+  fn: (qstash: QstashClient) => Promise<T> | T
+): Promise<T | null> => {
+  const qstash = await ensureQstash();
+  if (!qstash) {
+    return null;
+  }
+  return fn(qstash);
+};