⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
feat: add redis sentinal and cluster support
tiran1339a80aa8d5fe7
diff --git a/.env.sample b/.env.sampleindex 17c743e4a..e89277c21 100644--- a/.env.sample+++ b/.env.sample@@ -8,9 +8,24 @@ POSTGRES_DB=kaneoPOSTGRES_USER=kaneoPOSTGRES_PASSWORD=-# Pub/Sub for Websockets (Optional) -> auto fallback to in memory+# Redis Pub/Sub for WebSockets (Optional) -> auto fallback to in memory+# Only one mode should be configured. Priority: Cluster > Sentinel > Standalone.++# Standalone#REDIS_URL=+# Sentinel+#REDIS_SENTINELS=+#REDIS_SENTINEL_MASTER_NAME=mymaster+#REDIS_SENTINEL_PASSWORD=+#REDIS_SENTINEL_TLS=false++# Cluster+#REDIS_CLUSTER_NODES=++# Shared (Sentinel & Cluster)+#REDIS_PASSWORD=+# AuthenticationAUTH_SECRET=diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.mdindex bc8d06ed5..6735985cb 100644--- a/ENVIRONMENT_SETUP.md+++ b/ENVIRONMENT_SETUP.md@@ -51,7 +51,24 @@ Kaneo supports many optional configuration options including:#### Redis Configuration-- `REDIS_URL` - Redis connection string (e.g., `redis://localhost:6379`). When set, WebSocket broadcasts use Redis Pub/Sub, allowing multiple API instances to relay real-time updates. When not set, an in-memory adapter is used (single-instance only).+Kaneo supports three Redis deployment modes for WebSocket Pub/Sub. When any Redis mode is configured, WebSocket broadcasts use Redis Pub/Sub, allowing multiple API instances to relay real-time updates. When none are set, an in-memory adapter is used (single-instance only).++**Standalone (single server):**+- `REDIS_URL` - Redis connection string (e.g., `redis://localhost:6379`)++**Sentinel (high-availability with automatic failover):**+- `REDIS_SENTINELS` - Comma-separated list of Sentinel nodes (e.g., `sentinel-1:26379,sentinel-2:26379,sentinel-3:26379`)+- `REDIS_SENTINEL_MASTER_NAME` - Name of the Sentinel master group (default: `mymaster`)+- `REDIS_SENTINEL_PASSWORD` - Password for Sentinel instances, if different from the Redis password (optional)+- `REDIS_SENTINEL_TLS` - Set to `true` to enable TLS for Sentinel connections (default: `false`)++**Cluster (horizontal sharding):**+- `REDIS_CLUSTER_NODES` - Comma-separated list of cluster seed nodes (e.g., `node-1:6379,node-2:6379,node-3:6379`)++**Shared (used by Sentinel and Cluster modes):**+- `REDIS_PASSWORD` - Password for the Redis data nodes (used by both Sentinel and Cluster modes, not for Sentinel auth itself — use `REDIS_SENTINEL_PASSWORD` for that)++> **Note:** Only one mode should be configured at a time. If multiple are set, the priority is: Cluster > Sentinel > Standalone.#### SMTP Configurationdiff --git a/apps/api/src/redis/index.ts b/apps/api/src/redis/index.tsindex bc5d9456b..d6f833fa3 100644--- a/apps/api/src/redis/index.ts+++ b/apps/api/src/redis/index.ts@@ -1,19 +1,159 @@-import Redis from "ioredis";+import Redis, { type Cluster } from "ioredis";-let _redisPub: Redis | null = null;-let _redisSub: Redis | null = null;+export type RedisClient = Redis | Cluster;++let _redisPub: RedisClient | null = null;+let _redisSub: RedisClient | null = null;++function isRedisConfigured(): boolean {+ return !!(+ process.env.REDIS_URL ||+ process.env.REDIS_SENTINELS ||+ process.env.REDIS_CLUSTER_NODES+ );+}++export function parseNodeList(+ raw: string,+ envName: string,+ defaultPort: number,+): { host: string; port: number }[] {+ const nodes = raw+ .split(",")+ .map((entry) => entry.trim())+ .filter((entry) => entry.length > 0)+ .map((entry) => {+ let host: string;+ let portStr: string | undefined;++ if (entry.startsWith("[")) {+ // IPv6 bracket notation: [::1]:6379+ const closingBracket = entry.indexOf("]");+ if (closingBracket === -1) {+ throw new Error(+ `Invalid entry "${entry}" in ${envName}: missing closing bracket for IPv6 address`,+ );+ }+ host = entry.slice(1, closingBracket);+ const afterBracket = entry.slice(closingBracket + 1);+ if (afterBracket.startsWith(":")) {+ portStr = afterBracket.slice(1);+ } else if (afterBracket.length > 0) {+ throw new Error(+ `Invalid entry "${entry}" in ${envName}: unexpected characters after IPv6 address`,+ );+ }+ } else {+ const colonCount = entry.split(":").length - 1;+ if (colonCount > 1) {+ // Multiple colons — bare IPv6 address without brackets (e.g. "::1")+ host = entry;+ } else if (colonCount === 1) {+ // Exactly one colon — standard host:port+ const colonIdx = entry.indexOf(":");+ host = entry.slice(0, colonIdx);+ portStr = entry.slice(colonIdx + 1);+ } else {+ // No colons — hostname only+ host = entry;+ }+ }++ if (!host) {+ throw new Error(+ `Invalid entry "${entry}" in ${envName}: host is missing`,+ );+ }+ const port = portStr ? Number(portStr) : defaultPort;+ if (!Number.isInteger(port) || port <= 0 || port > 65535) {+ throw new Error(+ `Invalid entry "${entry}" in ${envName}: port must be a number between 1 and 65535`,+ );+ }+ return { host, port };+ });++ if (nodes.length === 0) {+ throw new Error(`${envName} is set but contains no valid entries`);+ }++ return nodes;+}++type RedisMode =+ | {+ mode: "cluster";+ nodes: { host: string; port: number }[];+ password?: string;+ }+ | {+ mode: "sentinel";+ sentinels: { host: string; port: number }[];+ name: string;+ password?: string;+ sentinelPassword?: string;+ enableTLSForSentinelMode: boolean;+ }+ | { mode: "standalone"; url: string };++export function resolveRedisMode(): RedisMode {+ const clusterNodes = process.env.REDIS_CLUSTER_NODES;+ if (clusterNodes) {+ return {+ mode: "cluster",+ nodes: parseNodeList(clusterNodes, "REDIS_CLUSTER_NODES", 6379),+ password: process.env.REDIS_PASSWORD,+ };+ }++ const sentinels = process.env.REDIS_SENTINELS;+ if (sentinels) {+ return {+ mode: "sentinel",+ sentinels: parseNodeList(sentinels, "REDIS_SENTINELS", 26379),+ name: process.env.REDIS_SENTINEL_MASTER_NAME || "mymaster",+ password: process.env.REDIS_PASSWORD,+ sentinelPassword: process.env.REDIS_SENTINEL_PASSWORD,+ enableTLSForSentinelMode: process.env.REDIS_SENTINEL_TLS === "true",+ };+ }-function getRedisUrl(): string {const url = process.env.REDIS_URL;if (!url) {- throw new Error("REDIS_URL is not set — cannot create Redis client");+ throw new Error(+ "REDIS_URL, REDIS_SENTINELS, or REDIS_CLUSTER_NODES must be set",+ );}- return url;+ return { mode: "standalone", url };}-export function getRedisPub(): Redis {+function createRedisClient(): RedisClient {+ const config = resolveRedisMode();++ switch (config.mode) {+ case "cluster":+ return new Redis.Cluster(config.nodes, {+ redisOptions: { password: config.password },+ clusterRetryStrategy: (times) => Math.min(times * 100, 3000),+ });+ case "sentinel":+ return new Redis({+ sentinels: config.sentinels,+ name: config.name,+ password: config.password,+ sentinelPassword: config.sentinelPassword,+ enableTLSForSentinelMode: config.enableTLSForSentinelMode,+ });+ case "standalone":+ return new Redis(config.url);+ }+}++export { isRedisConfigured };++export function getRedisPub(): RedisClient {if (!_redisPub) {- _redisPub = new Redis(getRedisUrl());+ _redisPub = createRedisClient();_redisPub.on("error", (err) =>console.error("Redis pub client error:", err),);@@ -21,9 +161,9 @@ export function getRedisPub(): Redis {return _redisPub;}-export function getRedisSub(): Redis {+export function getRedisSub(): RedisClient {if (!_redisSub) {- _redisSub = new Redis(getRedisUrl());+ _redisSub = createRedisClient();_redisSub.on("error", (err) =>console.error("Redis sub client error:", err),);diff --git a/apps/api/src/ws/index.ts b/apps/api/src/ws/index.tsindex c359841c5..0cd2dfc39 100644--- a/apps/api/src/ws/index.ts+++ b/apps/api/src/ws/index.ts@@ -1,5 +1,6 @@import type { WSContext } from "hono/ws";import { subscribeToEvent } from "../events";+import { isRedisConfigured } from "../redis";import type {BroadcastAdapter,BroadcastMessage,@@ -38,7 +39,7 @@ let adapter: BroadcastAdapter | null = null;export async function initializeWebSocketAdapter() {if (adapter) return;- const nextAdapter = process.env.REDIS_URL+ const nextAdapter = isRedisConfigured()? new RedisBroadcastAdapter(): new InMemoryBroadcastAdapter();diff --git a/apps/docs/core/installation/environment-variables.mdx b/apps/docs/core/installation/environment-variables.mdxindex 3151079d6..7b2d8809f 100644--- a/apps/docs/core/installation/environment-variables.mdx+++ b/apps/docs/core/installation/environment-variables.mdx@@ -122,11 +122,36 @@ Name | Description |### Redis-Kaneo supports Redis for horizontal scaling of WebSocket broadcasts. When `REDIS_URL` is set, multiple API instances can relay real-time updates via Redis Pub/Sub. When not set, an in-memory adapter is used (single-instance only).+Kaneo supports Redis for horizontal scaling of WebSocket broadcasts. When any Redis mode is configured, multiple API instances can relay real-time updates via Redis Pub/Sub. When none are set, an in-memory adapter is used (single-instance only).++Three deployment modes are supported: **Standalone**, **Sentinel**, and **Cluster**. Only one mode should be configured at a time. If multiple are set, the priority is: Cluster > Sentinel > Standalone.++#### Standalone (single server)++Name | Description |+--- | --- |+| `REDIS_URL` | Redis connection string (e.g., `redis://localhost:6379`).++#### Sentinel (high-availability with automatic failover)++Name | Description | Default |+--- | --- | --- |+| `REDIS_SENTINELS` | Comma-separated list of Sentinel nodes (e.g., `sentinel-1:26379,sentinel-2:26379,sentinel-3:26379`). | |+| `REDIS_SENTINEL_MASTER_NAME` | Name of the Sentinel master group. | `mymaster` |+| `REDIS_SENTINEL_PASSWORD` | Password for Sentinel instances, if different from the Redis password. | |+| `REDIS_SENTINEL_TLS` | Set to `true` to enable TLS for Sentinel connections. | `false` |++#### Cluster (horizontal sharding)++Name | Description |+--- | --- |+| `REDIS_CLUSTER_NODES` | Comma-separated list of cluster seed nodes (e.g., `node-1:6379,node-2:6379,node-3:6379`).++#### Shared (used by Sentinel and Cluster modes)Name | Description |--- | --- |-| `REDIS_URL` | Redis connection string (e.g., `redis://localhost:6379`). Enables multi-instance WebSocket broadcasts via Redis Pub/Sub.+| `REDIS_PASSWORD` | Password for the Redis data nodes (used by both Sentinel and Cluster modes, not for Sentinel auth itself — use `REDIS_SENTINEL_PASSWORD` for that).### SMTP Configurationdiff --git a/tests/api/redis/redis-config.test.ts b/tests/api/redis/redis-config.test.tsnew file mode 100644index 000000000..81175ba73--- /dev/null+++ b/tests/api/redis/redis-config.test.ts@@ -0,0 +1,209 @@+import { afterEach, beforeEach, describe, expect, it } from "vitest";+import {+ isRedisConfigured,+ parseNodeList,+} from "../../../apps/api/src/redis/index";++describe("parseNodeList", () => {+ describe("basic hostname:port parsing", () => {+ it("parses a single host:port entry", () => {+ const result = parseNodeList("redis-1:6379", "REDIS_CLUSTER_NODES", 6379);+ expect(result).toEqual([{ host: "redis-1", port: 6379 }]);+ });++ it("parses multiple host:port entries", () => {+ const result = parseNodeList(+ "redis-1:6379,redis-2:6380,redis-3:6381",+ "REDIS_CLUSTER_NODES",+ 6379,+ );+ expect(result).toEqual([+ { host: "redis-1", port: 6379 },+ { host: "redis-2", port: 6380 },+ { host: "redis-3", port: 6381 },+ ]);+ });++ it("uses the default port when port is omitted", () => {+ const result = parseNodeList("redis-1", "REDIS_SENTINELS", 26379);+ expect(result).toEqual([{ host: "redis-1", port: 26379 }]);+ });++ it("uses the default port for entries without port in a mixed list", () => {+ const result = parseNodeList(+ "redis-1:7000,redis-2",+ "REDIS_CLUSTER_NODES",+ 6379,+ );+ expect(result).toEqual([+ { host: "redis-1", port: 7000 },+ { host: "redis-2", port: 6379 },+ ]);+ });++ it("trims whitespace around entries", () => {+ const result = parseNodeList(+ " redis-1:6379 , redis-2:6380 ",+ "REDIS_CLUSTER_NODES",+ 6379,+ );+ expect(result).toEqual([+ { host: "redis-1", port: 6379 },+ { host: "redis-2", port: 6380 },+ ]);+ });++ it("skips empty entries from extra commas", () => {+ const result = parseNodeList(+ ",redis-1:6379,,redis-2:6380,",+ "REDIS_CLUSTER_NODES",+ 6379,+ );+ expect(result).toEqual([+ { host: "redis-1", port: 6379 },+ { host: "redis-2", port: 6380 },+ ]);+ });+ });++ describe("IPv6 address handling", () => {+ it("parses bracketed IPv6 with port", () => {+ const result = parseNodeList("[::1]:6379", "REDIS_CLUSTER_NODES", 6379);+ expect(result).toEqual([{ host: "::1", port: 6379 }]);+ });++ it("parses bracketed IPv6 without port (uses default)", () => {+ const result = parseNodeList("[::1]", "REDIS_CLUSTER_NODES", 6379);+ expect(result).toEqual([{ host: "::1", port: 6379 }]);+ });++ it("parses full IPv6 in brackets with port", () => {+ const result = parseNodeList(+ "[2001:db8::1]:7000",+ "REDIS_CLUSTER_NODES",+ 6379,+ );+ expect(result).toEqual([{ host: "2001:db8::1", port: 7000 }]);+ });++ it("parses multiple bracketed IPv6 entries", () => {+ const result = parseNodeList(+ "[::1]:6379,[::2]:6380",+ "REDIS_CLUSTER_NODES",+ 6379,+ );+ expect(result).toEqual([+ { host: "::1", port: 6379 },+ { host: "::2", port: 6380 },+ ]);+ });++ it("handles bare IPv6 address without brackets (uses default port)", () => {+ const result = parseNodeList("::1", "REDIS_CLUSTER_NODES", 6379);+ expect(result).toEqual([{ host: "::1", port: 6379 }]);+ });++ it("handles mixed IPv4, IPv6, and hostname entries", () => {+ const result = parseNodeList(+ "redis-1:6379,[::1]:6380,192.168.1.1:6381",+ "REDIS_CLUSTER_NODES",+ 6379,+ );+ expect(result).toEqual([+ { host: "redis-1", port: 6379 },+ { host: "::1", port: 6380 },+ { host: "192.168.1.1", port: 6381 },+ ]);+ });+ });++ describe("error cases", () => {+ it("throws on empty string", () => {+ expect(() => parseNodeList("", "REDIS_CLUSTER_NODES", 6379)).toThrow(+ "REDIS_CLUSTER_NODES is set but contains no valid entries",+ );+ });++ it("throws on string with only commas and spaces", () => {+ expect(() => parseNodeList(" , , ", "REDIS_CLUSTER_NODES", 6379)).toThrow(+ "REDIS_CLUSTER_NODES is set but contains no valid entries",+ );+ });++ it("throws on invalid port (non-numeric)", () => {+ expect(() =>+ parseNodeList("redis-1:abc", "REDIS_CLUSTER_NODES", 6379),+ ).toThrow("port must be a number between 1 and 65535");+ });++ it("throws on port out of range (0)", () => {+ expect(() =>+ parseNodeList("redis-1:0", "REDIS_CLUSTER_NODES", 6379),+ ).toThrow("port must be a number between 1 and 65535");+ });++ it("throws on port out of range (65536)", () => {+ expect(() =>+ parseNodeList("redis-1:65536", "REDIS_CLUSTER_NODES", 6379),+ ).toThrow("port must be a number between 1 and 65535");+ });++ it("throws on missing closing bracket for IPv6", () => {+ expect(() =>+ parseNodeList("[::1:6379", "REDIS_CLUSTER_NODES", 6379),+ ).toThrow("missing closing bracket for IPv6 address");+ });++ it("throws on unexpected characters after IPv6 closing bracket", () => {+ expect(() =>+ parseNodeList("[::1]abc", "REDIS_CLUSTER_NODES", 6379),+ ).toThrow("unexpected characters after IPv6 address");+ });++ it("throws on empty host with port", () => {+ expect(() => parseNodeList(":6379", "REDIS_CLUSTER_NODES", 6379)).toThrow(+ "host is missing",+ );+ });+ });+});++describe("isRedisConfigured", () => {+ const savedEnv = { ...process.env };++ beforeEach(() => {+ delete process.env.REDIS_URL;+ delete process.env.REDIS_SENTINELS;+ delete process.env.REDIS_CLUSTER_NODES;+ });++ afterEach(() => {+ process.env = { ...savedEnv };+ });++ it("returns false when no Redis env vars are set", () => {+ expect(isRedisConfigured()).toBe(false);+ });++ it("returns true when REDIS_URL is set", () => {+ process.env.REDIS_URL = "redis://localhost:6379";+ expect(isRedisConfigured()).toBe(true);+ });++ it("returns true when REDIS_SENTINELS is set", () => {+ process.env.REDIS_SENTINELS = "sentinel-1:26379";+ expect(isRedisConfigured()).toBe(true);+ });++ it("returns true when REDIS_CLUSTER_NODES is set", () => {+ process.env.REDIS_CLUSTER_NODES = "node-1:6379,node-2:6379";+ expect(isRedisConfigured()).toBe(true);+ });++ it("returns true when multiple Redis env vars are set", () => {+ process.env.REDIS_URL = "redis://localhost:6379";+ process.env.REDIS_SENTINELS = "sentinel-1:26379";+ process.env.REDIS_CLUSTER_NODES = "node-1:6379";+ expect(isRedisConfigured()).toBe(true);+ });+});diff --git a/tests/api/redis/redis-priority.test.ts b/tests/api/redis/redis-priority.test.tsnew file mode 100644index 000000000..168bbbb33--- /dev/null+++ b/tests/api/redis/redis-priority.test.ts@@ -0,0 +1,146 @@+import { afterEach, beforeEach, describe, expect, it } from "vitest";+import { resolveRedisMode } from "../../../apps/api/src/redis/index";++describe("resolveRedisMode priority resolution", () => {+ const savedEnv = { ...process.env };++ beforeEach(() => {+ delete process.env.REDIS_URL;+ delete process.env.REDIS_SENTINELS;+ delete process.env.REDIS_CLUSTER_NODES;+ delete process.env.REDIS_PASSWORD;+ delete process.env.REDIS_SENTINEL_MASTER_NAME;+ delete process.env.REDIS_SENTINEL_PASSWORD;+ delete process.env.REDIS_SENTINEL_TLS;+ });++ afterEach(() => {+ process.env = { ...savedEnv };+ });++ it("selects Cluster mode when REDIS_CLUSTER_NODES is set (highest priority)", () => {+ process.env.REDIS_CLUSTER_NODES = "node-1:6379,node-2:6379";+ process.env.REDIS_SENTINELS = "sentinel-1:26379";+ process.env.REDIS_URL = "redis://localhost:6379";++ const result = resolveRedisMode();++ expect(result).toEqual({+ mode: "cluster",+ nodes: [+ { host: "node-1", port: 6379 },+ { host: "node-2", port: 6379 },+ ],+ password: undefined,+ });+ });++ it("selects Sentinel mode when REDIS_SENTINELS is set (no cluster)", () => {+ process.env.REDIS_SENTINELS = "sentinel-1:26379,sentinel-2:26379";+ process.env.REDIS_URL = "redis://localhost:6379";+ process.env.REDIS_SENTINEL_MASTER_NAME = "mymaster";+ process.env.REDIS_PASSWORD = "secret";++ const result = resolveRedisMode();++ expect(result).toEqual({+ mode: "sentinel",+ sentinels: [+ { host: "sentinel-1", port: 26379 },+ { host: "sentinel-2", port: 26379 },+ ],+ name: "mymaster",+ password: "secret",+ sentinelPassword: undefined,+ enableTLSForSentinelMode: false,+ });+ });++ it("selects Standalone mode when only REDIS_URL is set (lowest priority)", () => {+ process.env.REDIS_URL = "redis://localhost:6379";++ const result = resolveRedisMode();++ expect(result).toEqual({+ mode: "standalone",+ url: "redis://localhost:6379",+ });+ });++ it("throws when no Redis configuration is provided", () => {+ expect(() => resolveRedisMode()).toThrow(+ "REDIS_URL, REDIS_SENTINELS, or REDIS_CLUSTER_NODES must be set",+ );+ });++ it("passes REDIS_PASSWORD to Cluster config", () => {+ process.env.REDIS_CLUSTER_NODES = "node-1:6379";+ process.env.REDIS_PASSWORD = "clusterpass";++ const result = resolveRedisMode();++ expect(result).toEqual(+ expect.objectContaining({+ mode: "cluster",+ password: "clusterpass",+ }),+ );+ });++ it("passes sentinel-specific options correctly", () => {+ process.env.REDIS_SENTINELS = "sentinel-1:26379";+ process.env.REDIS_SENTINEL_PASSWORD = "sentinelpass";+ process.env.REDIS_SENTINEL_TLS = "true";++ const result = resolveRedisMode();++ expect(result).toEqual(+ expect.objectContaining({+ mode: "sentinel",+ sentinelPassword: "sentinelpass",+ enableTLSForSentinelMode: true,+ }),+ );+ });++ it("defaults REDIS_SENTINEL_MASTER_NAME to 'mymaster'", () => {+ process.env.REDIS_SENTINELS = "sentinel-1:26379";++ const result = resolveRedisMode();++ expect(result).toEqual(+ expect.objectContaining({+ mode: "sentinel",+ name: "mymaster",+ }),+ );+ });++ it("disables sentinel TLS when REDIS_SENTINEL_TLS is not 'true'", () => {+ process.env.REDIS_SENTINELS = "sentinel-1:26379";+ process.env.REDIS_SENTINEL_TLS = "false";++ const result = resolveRedisMode();++ expect(result).toEqual(+ expect.objectContaining({+ mode: "sentinel",+ enableTLSForSentinelMode: false,+ }),+ );+ });++ it("passes REDIS_PASSWORD to Sentinel config", () => {+ process.env.REDIS_SENTINELS = "sentinel-1:26379";+ process.env.REDIS_PASSWORD = "redispass";++ const result = resolveRedisMode();++ expect(result).toEqual(+ expect.objectContaining({+ mode: "sentinel",+ password: "redispass",+ }),+ );+ });+});