refactor(api): rename VALKEY_URL to QUEUE_VALKEY_URL for clarity (#464)

This change renames the VALKEY_URL configuration variable to QUEUE_VALKEY_URL
to explicitly indicate its purpose as a queue backing store (for vote buffers,
export/import queues). This naming distinction allows for future introduction
of a separate CACHE_VALKEY_URL for general caching purposes if needed.

The internal variable in the API initialization has also been renamed from
'valkey' to 'queueValkey' to match this semantic clarification.

Deploy: api, math-updater

Author: nicobao

services/api/README.md

@@ -95,7 +95,7 @@ EXPORT_CONVOS_S3_PRESIGNED_URL_EXPIRY_SECONDS=3600         # Presigned URL valid
 EXPORT_CONVOS_ENABLED=true                                 # Enable/disable export feature (default: true)
 
 # Optional: Valkey for export queue persistence across instances
-VALKEY_URL=redis://localhost:6379                          # If not set, uses in-memory storage (lost on restart)
+QUEUE_VALKEY_URL=redis://localhost:6379                          # If not set, uses in-memory storage (lost on restart)
 ```
 
 **Export Queue System:**

services/api/env.example

@@ -13,7 +13,7 @@ VERIFICATOR_SVC_BASE_URL="http://verificator-svc"
 
 # Valkey configuration (optional - for vote/export buffer persistence across instances)
 # If not set, buffers will use in-memory storage only (lost on restart)
-# VALKEY_URL="valkey://localhost:6379"
+# QUEUE_VALKEY_URL="valkey://localhost:6379"
 # NOSTR_PROOF_CHANNEL_EVENT_ID="6cde92f2a057368e4871d5dac0f830e09f399bad666a2070e4c4c6c40d235667"
 # NOSTR_DEFAULT_RELAY_URL="wss://nos.lol"
 POLIS_BASE_URL="http://127.0.0.1:5000"

services/api/src/index.ts

@@ -376,17 +376,17 @@ if (
 }
 
 // Initialize Valkey (optional - for vote buffer persistence)
-const valkey = await initializeValkey({ valkeyUrl: config.VALKEY_URL, log });
+const queueValkey = await initializeValkey({ valkeyUrl: config.QUEUE_VALKEY_URL, log });
 
 // Initialize VoteBuffer (batches votes to reduce DB contention)
 const voteBuffer = createVoteBuffer({
     db,
-    valkey,
+    valkey: queueValkey,
     flushIntervalMs: config.VOTE_BUFFER_FLUSH_INTERVAL_MS,
     valkeyBatchLimit: config.VOTE_BUFFER_VALKEY_BATCH_LIMIT,
 });
 log.info(
-    `[API] Vote buffer initialized (flush interval: ${String(config.VOTE_BUFFER_FLUSH_INTERVAL_MS)}ms, batch limit: ${String(config.VOTE_BUFFER_VALKEY_BATCH_LIMIT)}, persistence: ${valkey !== undefined ? "Valkey" : "in-memory only"})`,
+    `[API] Vote buffer initialized (flush interval: ${String(config.VOTE_BUFFER_FLUSH_INTERVAL_MS)}ms, batch limit: ${String(config.VOTE_BUFFER_VALKEY_BATCH_LIMIT)}, persistence: ${queueValkey !== undefined ? "Valkey" : "in-memory only"})`,
 );
 
 // Initialize Notification SSE Manager for real-time notifications
@@ -396,7 +396,7 @@ notificationSSEManager.initialize();
 // Initialize ExportBuffer (batches export requests to reduce system load)
 const exportBuffer = createExportBuffer({
     db,
-    valkey,
+    valkey: queueValkey,
     notificationSSEManager,
     flushIntervalMs: 1000,
     maxBatchSize: config.EXPORT_CONVOS_BUFFER_MAX_BATCH_SIZE,
@@ -408,13 +408,13 @@ const exportBuffer = createExportBuffer({
         config.EXPORT_CONVOS_BUFFER_STALE_CLEANUP_EVERY_N_FLUSHES,
 });
 log.info(
-    `[API] Export buffer initialized (flush interval: 1s, max batch: ${String(config.EXPORT_CONVOS_BUFFER_MAX_BATCH_SIZE)}, cooldown: ${String(config.EXPORT_CONVOS_COOLDOWN_SECONDS)}s, persistence: ${valkey !== undefined ? "Valkey" : "in-memory only"})`,
+    `[API] Export buffer initialized (flush interval: 1s, max batch: ${String(config.EXPORT_CONVOS_BUFFER_MAX_BATCH_SIZE)}, cooldown: ${String(config.EXPORT_CONVOS_COOLDOWN_SECONDS)}s, persistence: ${queueValkey !== undefined ? "Valkey" : "in-memory only"})`,
 );
 
 // Initialize ImportBuffer (batches import requests to reduce system load)
 const importBuffer = createImportBuffer({
     db,
-    valkey,
+    valkey: queueValkey,
     notificationSSEManager,
     voteBuffer,
     axiosPolis,
@@ -426,7 +426,7 @@ const importBuffer = createImportBuffer({
         config.IMPORT_BUFFER_STALE_CLEANUP_EVERY_N_FLUSHES,
 });
 log.info(
-    `[API] Import buffer initialized (flush interval: ${String(config.IMPORT_BUFFER_FLUSH_INTERVAL_MS)}ms, max batch: ${String(config.IMPORT_BUFFER_MAX_BATCH_SIZE)}, max concurrency: ${String(config.IMPORT_BUFFER_MAX_CONCURRENCY)}, persistence: ${valkey !== undefined ? "Valkey" : "in-memory only"})`,
+    `[API] Import buffer initialized (flush interval: ${String(config.IMPORT_BUFFER_FLUSH_INTERVAL_MS)}ms, max batch: ${String(config.IMPORT_BUFFER_MAX_BATCH_SIZE)}, max concurrency: ${String(config.IMPORT_BUFFER_MAX_CONCURRENCY)}, persistence: ${queueValkey !== undefined ? "Valkey" : "in-memory only"})`,
 );
 
 // Cleanup stuck imports/exports from previous server session

services/api/src/shared-backend/config.ts

@@ -30,7 +30,7 @@ export const sharedConfigSchema = z.object({
     GOOGLE_APPLICATION_CREDENTIALS: z.string().optional(),
     // Valkey (optional - for vote buffer persistence across instances)
     // Empty strings are treated as undefined to prevent connection attempts
-    VALKEY_URL: z
+    QUEUE_VALKEY_URL: z
         .string()
         .optional()
         .transform((val) => (val === "" ? undefined : val)),

services/api/src/shared-backend/valkey.ts

@@ -53,7 +53,7 @@ function parseValkeyUrl(urlString: string): ParsedValkeyUrl {
  * - Export buffer queue management
  * - Future: Distributed locks, rate limiting, etc.
  *
- * If VALKEY_URL is not provided, returns undefined and services fall back to in-memory only.
+ * If QUEUE_VALKEY_URL is not provided, returns undefined and services fall back to in-memory only.
  *
  * Configuration:
  * - Local: valkey://localhost:6379

services/math-updater/src/shared-backend/config.ts

@@ -30,7 +30,7 @@ export const sharedConfigSchema = z.object({
     GOOGLE_APPLICATION_CREDENTIALS: z.string().optional(),
     // Valkey (optional - for vote buffer persistence across instances)
     // Empty strings are treated as undefined to prevent connection attempts
-    VALKEY_URL: z
+    QUEUE_VALKEY_URL: z
         .string()
         .optional()
         .transform((val) => (val === "" ? undefined : val)),

services/math-updater/src/shared-backend/valkey.ts

@@ -53,7 +53,7 @@ function parseValkeyUrl(urlString: string): ParsedValkeyUrl {
  * - Export buffer queue management
  * - Future: Distributed locks, rate limiting, etc.
  *
- * If VALKEY_URL is not provided, returns undefined and services fall back to in-memory only.
+ * If QUEUE_VALKEY_URL is not provided, returns undefined and services fall back to in-memory only.
  *
  * Configuration:
  * - Local: valkey://localhost:6379

services/shared-backend/src/config.ts

@@ -29,7 +29,7 @@ export const sharedConfigSchema = z.object({
     GOOGLE_APPLICATION_CREDENTIALS: z.string().optional(),
     // Valkey (optional - for vote buffer persistence across instances)
     // Empty strings are treated as undefined to prevent connection attempts
-    VALKEY_URL: z
+    QUEUE_VALKEY_URL: z
         .string()
         .optional()
         .transform((val) => (val === "" ? undefined : val)),

services/shared-backend/src/valkey.ts

@@ -52,7 +52,7 @@ function parseValkeyUrl(urlString: string): ParsedValkeyUrl {
  * - Export buffer queue management
  * - Future: Distributed locks, rate limiting, etc.
  *
- * If VALKEY_URL is not provided, returns undefined and services fall back to in-memory only.
+ * If QUEUE_VALKEY_URL is not provided, returns undefined and services fall back to in-memory only.
  *
  * Configuration:
  * - Local: valkey://localhost:6379