The open alternative to Salesforce, designed for AI.
TypeScript crmcrm-systemcustomergood-first-issuegraphqlhacktoberfestjavascriptmarketingmonoreponestjsopen-sourcepostgresqlreactreactjssalestypescriptweb
Add optional Redis cache prefix for clustered Redis (#27610)
Weikobed97eafa9e0
diff --git a/packages/twenty-docker/.env.example b/packages/twenty-docker/.env.exampleindex baac0378f2d..0981b4ac908 100644--- a/packages/twenty-docker/.env.example+++ b/packages/twenty-docker/.env.example@@ -6,6 +6,7 @@ TAG=latest#PG_DATABASE_PORT=5432#PG_DATABASE_NAME=default#REDIS_URL=redis://redis:6379+#REDIS_CACHE_PREFIX=SERVER_URL=http://localhost:3000diff --git a/packages/twenty-docker/docker-compose.yml b/packages/twenty-docker/docker-compose.ymlindex aba8fc42add..206ae939c5d 100644--- a/packages/twenty-docker/docker-compose.yml+++ b/packages/twenty-docker/docker-compose.yml@@ -12,6 +12,7 @@ services:PG_DATABASE_URL: postgres://${PG_DATABASE_USER:-postgres}:${PG_DATABASE_PASSWORD:-postgres}@${PG_DATABASE_HOST:-db}:${PG_DATABASE_PORT:-5432}/${PG_DATABASE_NAME:-default}SERVER_URL: ${SERVER_URL}REDIS_URL: ${REDIS_URL:-redis://redis:6379}+ REDIS_CACHE_PREFIX: ${REDIS_CACHE_PREFIX:-}DISABLE_DB_MIGRATIONS: ${DISABLE_DB_MIGRATIONS}DISABLE_CRON_JOBS_REGISTRATION: ${DISABLE_CRON_JOBS_REGISTRATION}@@ -68,6 +69,7 @@ services:PG_DATABASE_URL: postgres://${PG_DATABASE_USER:-postgres}:${PG_DATABASE_PASSWORD:-postgres}@${PG_DATABASE_HOST:-db}:${PG_DATABASE_PORT:-5432}/${PG_DATABASE_NAME:-default}SERVER_URL: ${SERVER_URL}REDIS_URL: ${REDIS_URL:-redis://redis:6379}+ REDIS_CACHE_PREFIX: ${REDIS_CACHE_PREFIX:-}DISABLE_DB_MIGRATIONS: "true" # it already runs on the serverDISABLE_CRON_JOBS_REGISTRATION: "true" # it already runs on the serverdiff --git a/packages/twenty-docs/developers/self-host/capabilities/upgrade-guide.mdx b/packages/twenty-docs/developers/self-host/capabilities/upgrade-guide.mdxindex d0035f50e5e..68a65528fc5 100644--- a/packages/twenty-docs/developers/self-host/capabilities/upgrade-guide.mdx+++ b/packages/twenty-docs/developers/self-host/capabilities/upgrade-guide.mdx@@ -25,6 +25,16 @@ If you use Docker Compose, follow these steps:The server runs all required upgrade migrations automatically on startup. No manual command is needed.+### Redis cache prefix++`REDIS_CACHE_PREFIX` is optional and defaults to an empty string. Leaving it empty preserves existing cache key names exactly, with no extra colon and no key migration.++For Redis Enterprise or Azure Managed Redis deployments that report `CROSSSLOT` errors during cache operations, set `REDIS_CACHE_PREFIX={twenty-cache}` on every server, worker, and upgrade command. The braces make all cache-storage keys share one Redis hash slot. This does not distribute cache data across shards. `REDIS_QUEUE_PREFIX` applies only to queues and remains separate.++For example, `engine:workspace:flatObjectMetadataMaps:123:hash` becomes `{twenty-cache}:engine:workspace:flatObjectMetadataMaps:123:hash` only when that prefix is configured. `cache:flush` automatically uses the configured prefix.++Changing the prefix switches to a separate cache namespace. Stop all Twenty servers and workers before changing it, then restart them with the same value. Existing entries under the previous prefix remain untouched. If you reuse a previously used prefix, run `yarn command:prod cache:flush` with that value before restarting to remove stale entries. Rolling deployments with different prefix values are not supported.+## Upgrading to v2.34+ — PostgreSQL 15 minimumTwenty v2.34 requires PostgreSQL 15 or newer. The official Docker Compose configuration uses PostgreSQL 16. If your instance connects to an externally managed database, upgrade it before starting the v2.34 server.diff --git a/packages/twenty-server/.env.example b/packages/twenty-server/.env.exampleindex 4da86e3b150..fe0ef447c1c 100644--- a/packages/twenty-server/.env.example+++ b/packages/twenty-server/.env.example@@ -10,6 +10,7 @@ FRONTEND_URL=http://localhost:3001# ———————— Optional ————————# PORT=3000+# REDIS_CACHE_PREFIX=# ACCESS_TOKEN_EXPIRES_IN=30m# LOGIN_TOKEN_EXPIRES_IN=15m# REFRESH_TOKEN_EXPIRES_IN=90ddiff --git a/packages/twenty-server/src/engine/core-modules/cache-storage/cache-storage.module.ts b/packages/twenty-server/src/engine/core-modules/cache-storage/cache-storage.module.tsindex 7779dce1484..df35f633587 100644--- a/packages/twenty-server/src/engine/core-modules/cache-storage/cache-storage.module.ts+++ b/packages/twenty-server/src/engine/core-modules/cache-storage/cache-storage.module.ts@@ -21,10 +21,17 @@ import { TwentyConfigService } from 'src/engine/core-modules/twenty-config/twentproviders: [...Object.values(CacheStorageNamespace).map((cacheStorageNamespace) => ({provide: cacheStorageNamespace,- useFactory: (cacheManager: Cache) => {- return new CacheStorageService(cacheManager, cacheStorageNamespace);+ useFactory: (+ cacheManager: Cache,+ twentyConfigService: TwentyConfigService,+ ) => {+ return new CacheStorageService(+ cacheManager,+ cacheStorageNamespace,+ twentyConfigService.get('REDIS_CACHE_PREFIX'),+ );},- inject: [CACHE_MANAGER],+ inject: [CACHE_MANAGER, TwentyConfigService],})),FlushCacheCommand,],diff --git a/packages/twenty-server/src/engine/core-modules/cache-storage/commands/flush-cache.command.ts b/packages/twenty-server/src/engine/core-modules/cache-storage/commands/flush-cache.command.tsindex 0f6fae6bd04..c715dbeb2aa 100644--- a/packages/twenty-server/src/engine/core-modules/cache-storage/commands/flush-cache.command.ts+++ b/packages/twenty-server/src/engine/core-modules/cache-storage/commands/flush-cache.command.ts@@ -7,6 +7,7 @@ import { isNonEmptyString } from '@sniptt/guards';import { CacheStorageService } from 'src/engine/core-modules/cache-storage/services/cache-storage.service';import { CacheStorageNamespace } from 'src/engine/core-modules/cache-storage/types/cache-storage-namespace.enum';+import { TwentyConfigService } from 'src/engine/core-modules/twenty-config/twenty-config.service';const NAMESPACE_VALUES = Object.values(CacheStorageNamespace,@@ -20,7 +21,10 @@ const NAMESPACE_VALUES = Object.values(export class FlushCacheCommand extends CommandRunner {private readonly logger = new Logger(FlushCacheCommand.name);- constructor(@Inject(CACHE_MANAGER) private readonly cacheManager: Cache) {+ constructor(+ @Inject(CACHE_MANAGER) private readonly cacheManager: Cache,+ private readonly twentyConfigService: TwentyConfigService,+ ) {super();}@@ -44,6 +48,7 @@ export class FlushCacheCommand extends CommandRunner {const cacheStorage = new CacheStorageService(this.cacheManager,namespace,+ this.twentyConfigService.get('REDIS_CACHE_PREFIX'),);await cacheStorage.flushByPattern(pattern);@@ -92,7 +97,7 @@ export class FlushCacheCommand extends CommandRunner {@Option({flags: '-p, --pattern <pattern>',description:- 'Pattern within the namespace (default *). Keys matched are <namespace>:<pattern>.',+ 'Pattern within the namespace (default *). REDIS_CACHE_PREFIX is applied automatically.',})parsePattern(val: string): string {return val;diff --git a/packages/twenty-server/src/engine/core-modules/cache-storage/services/cache-storage.service.ts b/packages/twenty-server/src/engine/core-modules/cache-storage/services/cache-storage.service.tsindex 18dc2475343..3285f3a31e9 100644--- a/packages/twenty-server/src/engine/core-modules/cache-storage/services/cache-storage.service.ts+++ b/packages/twenty-server/src/engine/core-modules/cache-storage/services/cache-storage.service.ts@@ -11,7 +11,9 @@ import {CacheStorageExceptionCode,} from 'src/engine/core-modules/cache-storage/exceptions/cache-storage.exception';import { type CacheScript } from 'src/engine/core-modules/cache-storage/types/cache-script.type';-import { CacheStorageNamespace } from 'src/engine/core-modules/cache-storage/types/cache-storage-namespace.enum';+import { type CacheStorageNamespace } from 'src/engine/core-modules/cache-storage/types/cache-storage-namespace.enum';+import { escapeRedisGlob } from 'src/engine/core-modules/cache-storage/utils/escape-redis-glob.util';+import { getCacheStorageKey } from 'src/engine/core-modules/cache-storage/utils/get-cache-storage-key.util';@Injectable()export class CacheStorageService {@@ -19,6 +21,7 @@ export class CacheStorageService {@Inject(CACHE_MANAGER)private readonly cache: Cache,private readonly namespace: CacheStorageNamespace,+ private readonly keyPrefix: string = '',) {}async get<T>(key: string): Promise<T | undefined> {@@ -255,12 +258,12 @@ export class CacheStorageService {}const redisClient = this.cache.store.client;+ const scanKeyPrefix = escapeRedisGlob(this.getKey(''));let cursor = 0;do {const result = await redisClient.scan(cursor, {- // Through getKey: under NODE_ENV=test keys carry an extra prefix, so a raw namespace match flushes nothing.- MATCH: this.getKey(scanPattern),+ MATCH: `${scanKeyPrefix}${scanPattern}`,COUNT: 100,});@@ -511,12 +514,11 @@ end`;}private getKey(key: string) {- const formattedKey = `${this.namespace}:${key}`;-- if (process.env.NODE_ENV === 'test') {- return `${CacheStorageNamespace.IntegrationTests}:${formattedKey}`;- }-- return formattedKey;+ return getCacheStorageKey({+ key,+ namespace: this.namespace,+ keyPrefix: this.keyPrefix,+ isTestEnvironment: process.env.NODE_ENV === 'test',+ });}}diff --git a/packages/twenty-server/src/engine/core-modules/cache-storage/utils/__tests__/escape-redis-glob.util.spec.ts b/packages/twenty-server/src/engine/core-modules/cache-storage/utils/__tests__/escape-redis-glob.util.spec.tsnew file mode 100644index 00000000000..df3b9398bab--- /dev/null+++ b/packages/twenty-server/src/engine/core-modules/cache-storage/utils/__tests__/escape-redis-glob.util.spec.ts@@ -0,0 +1,15 @@+import { escapeRedisGlob } from 'src/engine/core-modules/cache-storage/utils/escape-redis-glob.util';++describe('escapeRedisGlob', () => {+ it.each([+ ['', ''],+ ['{twenty-cache}:engine:workspace:', '{twenty-cache}:engine:workspace:'],+ ['{twenty[prod]}', '{twenty\\[prod\\]}'],+ ['{twenty*}', '{twenty\\*}'],+ ['{twenty?}', '{twenty\\?}'],+ ['{twenty\\prod}', '{twenty\\\\prod}'],+ ['{twenty]prod}', '{twenty\\]prod}'],+ ])('escapes %s as literal Redis glob text', (value, expected) => {+ expect(escapeRedisGlob(value)).toBe(expected);+ });+});diff --git a/packages/twenty-server/src/engine/core-modules/cache-storage/utils/__tests__/get-cache-storage-key.util.spec.ts b/packages/twenty-server/src/engine/core-modules/cache-storage/utils/__tests__/get-cache-storage-key.util.spec.tsnew file mode 100644index 00000000000..fcf2e583455--- /dev/null+++ b/packages/twenty-server/src/engine/core-modules/cache-storage/utils/__tests__/get-cache-storage-key.util.spec.ts@@ -0,0 +1,60 @@+import { CacheStorageNamespace } from 'src/engine/core-modules/cache-storage/types/cache-storage-namespace.enum';+import { getCacheStorageKey } from 'src/engine/core-modules/cache-storage/utils/get-cache-storage-key.util';++describe('getCacheStorageKey', () => {+ it.each([+ {+ keyPrefix: undefined,+ isTestEnvironment: false,+ expectedKey: 'engine:workspace:flatObjectMetadataMaps:123:hash',+ },+ {+ keyPrefix: '',+ isTestEnvironment: false,+ expectedKey: 'engine:workspace:flatObjectMetadataMaps:123:hash',+ },+ {+ keyPrefix: '{twenty-cache}',+ isTestEnvironment: false,+ expectedKey:+ '{twenty-cache}:engine:workspace:flatObjectMetadataMaps:123:hash',+ },+ {+ keyPrefix: '{twenty[prod]*?\\}',+ isTestEnvironment: false,+ expectedKey:+ '{twenty[prod]*?\\}:engine:workspace:flatObjectMetadataMaps:123:hash',+ },+ {+ keyPrefix: '',+ isTestEnvironment: true,+ expectedKey:+ 'integration-tests:engine:workspace:flatObjectMetadataMaps:123:hash',+ },+ {+ keyPrefix: '{twenty-cache}',+ isTestEnvironment: true,+ expectedKey:+ 'integration-tests:{twenty-cache}:engine:workspace:flatObjectMetadataMaps:123:hash',+ },+ ])('builds $expectedKey', ({ keyPrefix, isTestEnvironment, expectedKey }) => {+ expect(+ getCacheStorageKey({+ key: 'flatObjectMetadataMaps:123:hash',+ namespace: CacheStorageNamespace.EngineWorkspace,+ keyPrefix,+ isTestEnvironment,+ }),+ ).toBe(expectedKey);+ });++ it('keeps the configured prefix before other hash tags in the key', () => {+ expect(+ getCacheStorageKey({+ key: 'user:{123}:data',+ namespace: CacheStorageNamespace.EngineCoreEntity,+ keyPrefix: '{twenty-cache}',+ }),+ ).toBe('{twenty-cache}:engine:core-entity:user:{123}:data');+ });+});diff --git a/packages/twenty-server/src/engine/core-modules/cache-storage/utils/escape-redis-glob.util.ts b/packages/twenty-server/src/engine/core-modules/cache-storage/utils/escape-redis-glob.util.tsnew file mode 100644index 00000000000..fae3e45d109--- /dev/null+++ b/packages/twenty-server/src/engine/core-modules/cache-storage/utils/escape-redis-glob.util.ts@@ -0,0 +1,2 @@+export const escapeRedisGlob = (value: string): string =>+ value.replace(/[\\*?[\]]/g, '\\$&');diff --git a/packages/twenty-server/src/engine/core-modules/cache-storage/utils/get-cache-storage-key.util.ts b/packages/twenty-server/src/engine/core-modules/cache-storage/utils/get-cache-storage-key.util.tsnew file mode 100644index 00000000000..ffd5b66e6a0--- /dev/null+++ b/packages/twenty-server/src/engine/core-modules/cache-storage/utils/get-cache-storage-key.util.ts@@ -0,0 +1,22 @@+import { isNonEmptyString } from '@sniptt/guards';++import { CacheStorageNamespace } from 'src/engine/core-modules/cache-storage/types/cache-storage-namespace.enum';++export const getCacheStorageKey = ({+ key,+ namespace,+ keyPrefix = '',+ isTestEnvironment = false,+}: {+ key: string;+ namespace: CacheStorageNamespace;+ keyPrefix?: string;+ isTestEnvironment?: boolean;+}): string => {+ const formattedPrefix = isNonEmptyString(keyPrefix) ? `${keyPrefix}:` : '';+ const formattedKey = `${formattedPrefix}${namespace}:${key}`;++ return isTestEnvironment+ ? `${CacheStorageNamespace.IntegrationTests}:${formattedKey}`+ : formattedKey;+};diff --git a/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts b/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.tsindex 64fd1ad501e..878725c888d 100644--- a/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts+++ b/packages/twenty-server/src/engine/core-modules/twenty-config/config-variables.ts@@ -1482,6 +1482,17 @@ export class ConfigVariables {})REDIS_URL: string;+ @ConfigVariablesMetadata({+ group: ConfigVariablesGroup.ADVANCED_SETTINGS,+ description:+ 'Optional prefix for cache-storage keys. Empty preserves existing key names. Use a Redis hash tag (e.g. "{twenty-cache}") to place all cache-storage keys in one hash slot and avoid CROSSSLOT errors. Changing it switches cache namespaces and requires all servers and workers to restart with the same value.',+ isEnvOnly: true,+ type: ConfigVariableType.STRING,+ })+ @IsOptional()+ @IsString()+ REDIS_CACHE_PREFIX: string = '';+@ConfigVariablesMetadata({group: ConfigVariablesGroup.ADVANCED_SETTINGS,isSensitive: true,diff --git a/packages/twenty-server/test/integration/cache-storage/cache-storage-prefix.integration-spec.ts b/packages/twenty-server/test/integration/cache-storage/cache-storage-prefix.integration-spec.tsnew file mode 100644index 00000000000..e7b031497af--- /dev/null+++ b/packages/twenty-server/test/integration/cache-storage/cache-storage-prefix.integration-spec.ts@@ -0,0 +1,120 @@+import { CACHE_MANAGER } from '@nestjs/cache-manager';+import { ConfigService } from '@nestjs/config';+import { Test, type TestingModule } from '@nestjs/testing';++import { caching } from 'cache-manager';+import { type RedisCache, redisStore } from 'cache-manager-redis-yet';+import { randomUUID } from 'crypto';++import { FlushCacheCommand } from 'src/engine/core-modules/cache-storage/commands/flush-cache.command';+import { CacheStorageService } from 'src/engine/core-modules/cache-storage/services/cache-storage.service';+import { CacheStorageNamespace } from 'src/engine/core-modules/cache-storage/types/cache-storage-namespace.enum';+import { ConfigVariables } from 'src/engine/core-modules/twenty-config/config-variables';+import { CONFIG_VARIABLES_INSTANCE_TOKEN } from 'src/engine/core-modules/twenty-config/constants/config-variables-instance-tokens.constants';+import { EnvironmentConfigDriver } from 'src/engine/core-modules/twenty-config/drivers/environment-config.driver';+import { TwentyConfigService } from 'src/engine/core-modules/twenty-config/twenty-config.service';++describe('Cache storage prefix', () => {+ let cache: RedisCache;+ let entriesToClean: { storage: CacheStorageService; key: string }[];++ beforeAll(async () => {+ cache = await caching(+ await redisStore({ url: process.env.REDIS_URL, ttl: 60_000 }),+ );+ });++ beforeEach(() => {+ entriesToClean = [];+ });++ afterEach(async () => {+ await Promise.all(+ entriesToClean.map(({ storage, key }) => storage.del(key)),+ );+ });++ afterAll(async () => {+ await cache.store.client.quit();+ });++ describe.each([+ { prefix: '', otherPrefix: '{other-cache}' },+ { prefix: '{twenty-cache}', otherPrefix: '{other-cache}' },+ { prefix: '{twenty[prod]}', otherPrefix: '{twentyp}' },+ { prefix: '{twenty*}', otherPrefix: '{twenty-other}' },+ { prefix: '{twenty?}', otherPrefix: '{twentyX}' },+ { prefix: '{twenty\\prod}', otherPrefix: '{twentyprod}' },+ { prefix: '{twenty]prod}', otherPrefix: '{twentyprod}' },+ ])('cache:flush with prefix "$prefix"', ({ prefix, otherPrefix }) => {+ let module: TestingModule;++ beforeAll(async () => {+ module = await Test.createTestingModule({+ providers: [+ { provide: CACHE_MANAGER, useValue: cache },+ {+ provide: ConfigService,+ useValue: new ConfigService({+ REDIS_CACHE_PREFIX: prefix,+ IS_CONFIG_VARIABLES_IN_DB_ENABLED: false,+ }),+ },+ {+ provide: CONFIG_VARIABLES_INSTANCE_TOKEN,+ useValue: new ConfigVariables(),+ },+ EnvironmentConfigDriver,+ TwentyConfigService,+ FlushCacheCommand,+ ],+ }).compile();+ });++ afterAll(async () => {+ await module.close();+ });++ it('matches the suffix pattern while preserving other prefixes and namespaces', async () => {+ const storage = new CacheStorageService(+ cache,+ CacheStorageNamespace.EngineWorkspace,+ prefix,+ );+ const otherPrefixStorage = new CacheStorageService(+ cache,+ CacheStorageNamespace.EngineWorkspace,+ otherPrefix,+ );+ const otherNamespaceStorage = new CacheStorageService(+ cache,+ CacheStorageNamespace.EngineCoreEntity,+ prefix,+ );+ const keyRoot = `cache-prefix:${randomUUID()}`;+ const matchingKeys = [`${keyRoot}:a1:data`, `${keyRoot}:b2:data`];+ const nonMatchingKey = `${keyRoot}:c3:data`;++ entriesToClean = [+ ...[...matchingKeys, nonMatchingKey].map((key) => ({ storage, key })),+ { storage: otherPrefixStorage, key: matchingKeys[0] },+ { storage: otherNamespaceStorage, key: matchingKeys[0] },+ ];+ await Promise.all(+ entriesToClean.map(({ storage: entryStorage, key }) =>+ entryStorage.set(key, 'cached'),+ ),+ );++ await module.get(FlushCacheCommand).run([], {+ namespace: CacheStorageNamespace.EngineWorkspace,+ pattern: `${keyRoot}:[ab]?:data`,+ });++ expect(await storage.mget(matchingKeys)).toEqual([undefined, undefined]);+ expect(await storage.get(nonMatchingKey)).toBe('cached');+ expect(await otherPrefixStorage.get(matchingKeys[0])).toBe('cached');+ expect(await otherNamespaceStorage.get(matchingKeys[0])).toBe('cached');+ });+ });+});