אינטגרציות ו־API
Redis ו־BullMQ
הפרדת מסד אמת, מטמון ותורים; גבול ה־worker ותיעוד חיבור התשתית.
בעמוד הזה
Decision#
Redis is an acceleration and asynchronous-work layer for LinkNodes Energy. It is not an application database. Supabase PostgreSQL remains the authoritative source of customer, tenant, vehicle, billing, provider and transaction state.
Redis responsibilities#
- Short-lived cache for expensive, safely cacheable provider/reference reads.
- BullMQ queue state for asynchronous provider work.
- Idempotency/deduplication support for provider events and background jobs where appropriate.
Keys use lowercase colon-separated namespaces. Tenant-specific cache entries always include an explicit tenant:<id> segment. PII and credentials must never appear in Redis key names.
BullMQ queues#
provider-sync: station catalogs, charger/fuel status, tariffs and transaction imports.webhook-reconciliation: provider webhook verification/reconciliation outside the synchronous response path.billing-reconciliation: non-interactive billing reconciliation.
Default jobs use bounded retention, five attempts and exponential backoff. Logical operations use deterministic opaque job IDs to prevent accidental duplicate enqueueing.
Runtime boundary#
Vercel request functions may enqueue work, but a BullMQ worker is a long-lived process and is not started as an ordinary request handler. The dedicated worker runtime must run the worker factory from lib/jobs/worker.ts, receive the same Redis TLS/ACL credential, and shut down gracefully.
Until a production Redis runtime is provisioned and REDIS_URL is configured, Redis and queues remain disabled and the existing Web application behavior is unchanged.
Security#
- Production requires a
rediss://URL. - Use a dedicated least-privilege Redis ACL user for the LinkNodes worker/application.
- Keep Redis off public unauthenticated access.
- Never commit Redis URLs, passwords, provider credentials or job payload secrets.
- Avoid
KEYS; application cache keys are always addressable directly. - Supabase RLS remains the tenant authorization boundary. Redis cache usage must happen only after authorization and must preserve tenant scope.
Observability#
Grafana Cloud remains the official DigitalOps monitoring platform. Export Redis/worker metrics there when the runtime connection exists. Durabull is the queue/Redis operations console for queue backlog, worker status, failed jobs, schedules and Redis health.
Current connection status at implementation time: the Durabull MCP transport is connected, but list_connections returns no visible Redis connections. Runtime operations therefore cannot be certified until that connection appears.
Railway production runtime#
The production Redis instance is hosted inside the Railway project LinkNodes Energy Infrastructure.
The Redis service stays on Railway private networking for worker traffic. The dedicated Railway BullMQ worker runs workers/railway-bullmq-worker.mjs and starts only the system-smoke queue until real provider processors are implemented.
A production redis:// URL is accepted only when the hostname ends in .railway.internal; all other production Redis URLs must use rediss://.
The smoke worker creates one deployment-scoped job at boot, waits for completion, exposes GET /health, and proves Redis/BullMQ/worker connectivity without consuming business queues.