Skip to content

Infisical is the open-source platform for securing secrets, certificates, access, and AI Agents.

47.3 KB
Raw Blame
import type { Cluster } from "ioredis";
import { Redis } from "ioredis";
import { Knex } from "knex";

import { buildRedisFromConfig, TRedisConfigKeys } from "@app/lib/config/redis";
import { pgAdvisoryLockHashText } from "@app/lib/crypto/hashtext";
import { applyJitter } from "@app/lib/dates";
import { delay as delayMs } from "@app/lib/delay";
import { ms } from "@app/lib/ms";
import { ExecutionResult, Redlock, Settings } from "@app/lib/red-lock";

import { TKeyValueStoreDALFactory } from "./key-value-store-dal";

export const PgSqlLock = {
  BootUpMigration: 2023,
  SuperAdminInit: 2024,
  KmsRootKeyInit: 2025,
  SanitizedSchemaGeneration: 2026,
  EmailDomainCreationLock: () => pgAdvisoryLockHashText(`org-email-domain-creation`),
  SecretRotationV2Creation: (folderId: string) => pgAdvisoryLockHashText(`secret-rotation-v2-creation:${folderId}`),
  CreateProject: (orgId: string) => pgAdvisoryLockHashText(`create-project:${orgId}`),
  CreateOrganization: (userId: string) => pgAdvisoryLockHashText(`create-organization:${userId}`),
  CreateFolder: (envId: string, projectId: string) => pgAdvisoryLockHashText(`create-folder:${envId}-${projectId}`),
  InstanceRelayConfigInit: () => pgAdvisoryLockHashText("instance-relay-config-init"),
  OrgGatewayV2Init: (orgId: string) => pgAdvisoryLockHashText(`org-gateway-v2-init:${orgId}`),
  OrgRelayConfigInit: (orgId: string) => pgAdvisoryLockHashText(`org-relay-config-init:${orgId}`),
  OrgKmipInit: (orgId: string) => pgAdvisoryLockHashText(`org-kmip-init:${orgId}`),
  GatewayPamSessionKey: (gatewayId: string) => pgAdvisoryLockHashText(`gateway-pam-session-key:${gatewayId}`),
  IdentityLogin: (identityId: string, nonce: string) => pgAdvisoryLockHashText(`identity-login:${identityId}:${nonce}`),
  PamResourceSshCaInit: (resourceId: string) => pgAdvisoryLockHashText(`pam-resource-ssh-ca-init:${resourceId}`),
  CreateIdentity: (orgId: string) => pgAdvisoryLockHashText(`create-identity:${orgId}`),
  CreateGateway: (orgId: string) => pgAdvisoryLockHashText(`create-gateway:${orgId}`),
  CreateAgentVaultProxy: (projectId: string) => pgAdvisoryLockHashText(`create-agent-vault-proxy:${projectId}`),
  CreateAgentVaultVariable: (projectId: string) => pgAdvisoryLockHashText(`create-agent-vault-variable:${projectId}`),
  CreateAgentVaultSkill: (projectId: string) => pgAdvisoryLockHashText(`create-agent-vault-skill:${projectId}`),
  CreateAgentVaultPersonalVariable: (projectId: string, ownerId: string) =>
    pgAdvisoryLockHashText(`create-agent-vault-personal-variable:${projectId}:${ownerId}`),
  ClearAgentVaultPersonalValues: (projectId: string) =>
    pgAdvisoryLockHashText(`clear-agent-vault-personal-values:${projectId}`),
  AccessSharedSecret: (sharedSecretId: string) => pgAdvisoryLockHashText(`access-shared-secret:${sharedSecretId}`),
  KmsOrgKeyCreation: (orgId: string) => pgAdvisoryLockHashText(`kms-org-key:${orgId}`),
  KmsOrgDataKeyCreation: (orgId: string) => pgAdvisoryLockHashText(`kms-org-data-key:${orgId}`),
  KmsProjectKeyCreation: (projectId: string) => pgAdvisoryLockHashText(`kms-project-key:${projectId}`),
  KmsProjectDataKeyCreation: (projectId: string) => pgAdvisoryLockHashText(`kms-project-data-key:${projectId}`),
  ScimGroupUpdate: (groupId: string) => pgAdvisoryLockHashText(`scim-group-update:${groupId}`),
  OrgAccessReconcile: (actorId: string) => pgAdvisoryLockHashText(`org-access-reconcile:${actorId}`),
  OrgAccessReconcileScope: (rootOrgId: string) => pgAdvisoryLockHashText(`org-access-reconcile-scope:${rootOrgId}`),
  LastAdminGuard: (scope: "org" | "project", scopeId: string) =>
    pgAdvisoryLockHashText(`last-admin-guard:${scope}:${scopeId}`),
  AuditReportRequest: (projectId: string) => pgAdvisoryLockHashText(`audit-report-request:${projectId}`),
  OrgAuditReportRequest: (orgId: string) => pgAdvisoryLockHashText(`audit-report-request:org:${orgId}`),
  OrgAgentProxyConfigInit: (orgId: string) => pgAdvisoryLockHashText(`org-agent-proxy-config-init:${orgId}`),
  ExternalGroupOrgRoleMappingUpdate: (orgId: string) =>
    pgAdvisoryLockHashText(`external-group-org-role-mapping-update:${orgId}`),
  AuditLogSettingsUpdate: (scopeId: string) => pgAdvisoryLockHashText(`audit-log-settings-update:${scopeId}`)
} as const;

// all the key prefixes used must be set here to avoid conflict
export const KeyStorePrefixes = {
  SecretReplication: "secret-replication-import-lock",
  FolderTreeCheckpoint: (envId: string) => `folder-tree-checkpoint-${envId}`,

  WaitUntilReadyProjectEnvironmentOperation: (projectId: string) =>
    `wait-until-ready-project-environments-operation-${projectId}`,
  ProjectEnvironmentLock: (projectId: string) => `project-environment-lock-${projectId}` as const,
  CreateFolderLock: (envId: string) => `create-folder-lock-${envId}` as const,
  SyncSecretIntegrationLock: (projectId: string, environmentSlug: string, secretPath: string) =>
    `sync-integration-mutex-${projectId}-${environmentSlug}-${secretPath}` as const,
  SyncSecretIntegrationLastRunTimestamp: (projectId: string, environmentSlug: string, secretPath: string) =>
    `sync-integration-last-run-${projectId}-${environmentSlug}-${secretPath}` as const,
  SecretSyncLock: (syncId: string) => `secret-sync-mutex-${syncId}` as const,
  CloudflareWorkerVersionLock: (accountId: string, scriptId: string) =>
    `cloudflare-worker-version-mutex-${accountId}-${scriptId}` as const,
  PkiSyncLock: (syncId: string) => `pki-sync-mutex-${syncId}` as const,
  PkiSyncFilterLock: (syncId: string) => `pki-sync-filter-mutex-${syncId}` as const,
  AppConnectionConcurrentJobs: (connectionId: string, targetHost?: string) =>
    `app-connection-concurrency-${connectionId}${targetHost ? `-${targetHost.toLowerCase()}` : ""}` as const,
  AppConnectionCommandLock: (connectionId: string, targetHost?: string) =>
    `app-connection-command-mutex-${connectionId}${targetHost ? `-${targetHost.toLowerCase()}` : ""}` as const,
  AcmeDnsRecordLock: (connectionId: string, zoneId: string, recordName: string) =>
    `acme-dns-record-mutex-${connectionId}-${zoneId.toLowerCase()}-${recordName.toLowerCase()}` as const,
  LdapHostLogin: (fingerprint: string) => `ldap-host-login-${fingerprint}` as const,
  LdapDirectoryMachines: (connectionId: string, search: string, limit: number) =>
    `ldap-directory-machines-${connectionId}-${limit}-${search}` as const,
  SecretRotationLock: (rotationId: string) => `secret-rotation-v2-mutex-${rotationId}` as const,
  StripeConnectionRefreshLock: (connectionId: string) => `stripe-connection-refresh-mutex-${connectionId}` as const,
  PamAccountRotationLock: (accountId: string) => `pam-account-rotation-mutex-${accountId}` as const,
  OidcIssuerKeyRotationLock: (orgId: string) => `oidc-issuer-key-rotation-mutex-${orgId}` as const,
  OidcIssuerJwks: (orgId: string) => `oidc-issuer-jwks:${orgId}` as const,
  SecretScanningFullScanLease: (resourceId: string) => `secret-scanning-v2-full-scan-lease-${resourceId}` as const,
  SecretScanningDataSourceLock: (dataSourceId: string) =>
    `secret-scanning-v2-data-source-mutex-${dataSourceId}` as const,
  IdentityLockoutLock: (lockoutKey: string) => `identity-lockout-lock-${lockoutKey}` as const,
  CaOrderCertificateForSubscriberLock: (subscriberId: string) =>
    `ca-order-certificate-for-subscriber-lock-${subscriberId}` as const,
  SecretSyncLastRunTimestamp: (syncId: string) => `secret-sync-last-run-${syncId}` as const,
  IdentityAccessTokenStatusUpdate: (identityAccessTokenId: string) =>
    `identity-access-token-status:${identityAccessTokenId}`,
  IdentityTokenUsesRemaining: (identityId: string, jti: string) =>
    `identity-token-uses-remaining:${identityId}:${jti}` as const,
  IdentityRevocationVersion: (identityId: string) => `identity-revocation-version:${identityId}` as const,
  IdentityRevocationVerdict: (identityId: string, fingerprint: string) =>
    `identity-revocation-verdict:${identityId}:${fingerprint}` as const,
  IdentityTrustedIps: (identityId: string, authMethod: string) =>
    `identity-trusted-ips:${identityId}:${authMethod}` as const,
  IdentityUaClientSecretUsageDebounce: (clientSecretId: string) =>
    `identity-ua-client-secret-usage-debounce:${clientSecretId}` as const,
  IdentityLastLoginDebounce: (identityId: string) => `identity-last-login-debounce:${identityId}` as const,
  SpiffeKidMissRefresh: (configId: string) => `spiffe-kid-miss-refresh:${configId}` as const,
  ProxiedServiceUsageDebounce: (serviceId: string) => `proxied-service-usage-debounce:${serviceId}` as const,
  ServiceTokenStatusUpdate: (serviceTokenId: string) => `service-token-status:${serviceTokenId}`,
  // The braces are a Redis Cluster hash tag: only the tagged part picks the slot, so these land on
  // one node. Selection reads them for several gateways at once (one Lua script and two MGETs), and
  // cluster refuses a multi-key command whose keys span slots. They are small counters, so
  // concentrating them costs nothing.
  GatewayReportedLoad: (gatewayId: string) => `gateway-reported-load:{gw-pool}:${gatewayId}` as const,
  GatewayLoadReservation: (gatewayId: string) => `gateway-reservation:{gw-pool}:${gatewayId}` as const,
  GatewaySuspect: (gatewayId: string) => `gateway-suspect:{gw-pool}:${gatewayId}` as const,
  ActiveSSEConnectionsSet: (projectId: string, identityId: string) =>
    `sse-connections:${projectId}:${identityId}` as const,
  ActiveSSEConnections: (projectId: string, identityId: string, connectionId: string) =>
    `sse-connections:${projectId}:${identityId}:${connectionId}` as const,
  RecentAnnouncements: "announcements:recent" as const,

  AlertChannelTestCooldown: (orgId: string, actorId: string, channelType: string) =>
    `alert-channel-test-cooldown:${orgId}:${actorId}:${channelType}` as const,

  ProjectPermissionMarker: (projectId: string, actorType: string, actorId: string, actionProjectType: string) =>
    `project-permission-marker:${projectId}:${actorType}:${actorId}:${actionProjectType}` as const,
  ProjectPermissionData: (projectId: string, actorType: string, actorId: string, actionProjectType: string) =>
    `project-permission-data:${projectId}:${actorType}:${actorId}:${actionProjectType}` as const,

  // Postgres key_value_store key (pgIncrementBy/pgGetIntItem), not a Redis key
  ProjectFolderPermissionVersion: (projectId: string) => `project-folder-permission-version:${projectId}` as const,

  ProjectFolderAccessMarker: (projectId: string, folderId: string, actorType: string, page: string) =>
    `project-folder-access-marker:${projectId}:${folderId}:${actorType}:${page}` as const,
  ProjectFolderAccessData: (projectId: string, folderId: string, actorType: string, page: string) =>
    `project-folder-access-data:${projectId}:${folderId}:${actorType}:${page}` as const,

  KmsProjectSecretManagerMaterial: (projectId: string) => `kms-project-sm-material:${projectId}` as const,

  PkiAcmeNonce: (nonce: string) => `pki-acme-nonce:${nonce}` as const,
  ScepIntuneAccess: (connectionId: string, connectionUpdatedAt: Date) =>
    `scep-intune-access:${connectionId}:${connectionUpdatedAt.getTime()}` as const,
  MfaSession: (mfaSessionId: string) => `mfa-session:${mfaSessionId}` as const,
  MfaCodeResendCooldown: (userId: string) => `mfa-code-resend-cooldown:${userId}` as const,
  WebAuthnChallenge: (userId: string) => `webauthn-challenge:${userId}` as const,
  UserMfaLockoutLock: (userId: string) => `user-mfa-lockout-lock:${userId}` as const,
  UserMfaUnlockEmailSent: (userId: string) => `user-mfa-unlock-email-sent:${userId}` as const,
  UserStepUpMfaAttempts: (userId: string) => `user-step-up-mfa-attempts:${userId}` as const,
  UserStepUpMfaLockout: (userId: string) => `user-step-up-mfa-lockout:${userId}` as const,
  RecentMfaAuth: (userId: string, tokenVersionId: string) => `recent-mfa-auth:${userId}:${tokenVersionId}` as const,
  UsedTotpCode: (userId: string, code: string) => `used-totp-code:${userId}:${code}` as const,
  UsedAccountRecoveryToken: (userId: string, jti: string) => `used-account-recovery-token:${userId}:${jti}` as const,
  UsedGitHubManifestState: (jti: string) => `used-github-manifest-state:${jti}` as const,
  GitHubManifestNameLock: (orgId: string, projectId: string | null, name: string) =>
    `github-manifest-name-lock:${orgId}:${projectId ?? "org"}:${name}` as const,

  // OAuth 2.0 authorization server (Infisical as an OAuth provider)
  OauthAuthorizationCode: (code: string) => `oauth-authorization-code:${code}` as const,

  // Project SSE Connection Rate Limiting
  ProjectSSEConnectionsSet: (projectId: string) => `project-sse-connections:${projectId}` as const,
  ProjectSSEConnectionsLockoutKey: (projectId: string) => `project-sse-connections:lockout:${projectId}` as const,
  ProjectSSEConnection: (projectId: string, connectionId: string) =>
    `project-sse-conn:${projectId}:${connectionId}` as const,

  ProjectDeleteLock: (projectId: string) => `project-delete-lock-${projectId}` as const,

  TelemetryIdentifyIdentity: (dedupKey: string) => `telemetry-identify-identity:${dedupKey}` as const,
  TelemetryGroupIdentify: (orgId: string) => `telemetry-group-identify:${orgId}` as const,
  TelemetryAuditLogsViewed: (orgId: string, distinctId: string) =>
    `telemetry-audit-logs-viewed:${orgId}:${distinctId}` as const,
  TelemetryIdentify: (distinctId: string) => `telemetry-identify:${distinctId}` as const,
  SecretEtag: (projectId: string, dayStamp: string) => `secret-etag:${projectId}:${dayStamp}` as const,
  SecretPermissionFingerprint: (projectId: string, actorType: string, actorId: string) =>
    `secret-perm-fingerprint:${projectId}:${actorType}:${actorId}` as const,

  PamAwsIamAccessKeyId: (sessionId: string) => `pam-aws-iam-access-key-id:${sessionId}` as const,
  PamDefaultProject: (orgId: string) => `pam-default-project:${orgId}` as const,
  AgentVaultDefaultProject: (orgId: string) => `agent-vault-default-project:${orgId}` as const,
  // The live view's Redis stream for a session: the newest chunk file names, with their bucket and size.
  AgentVaultSessionLogFeed: (sessionId: string) => `agent-vault-session-log-feed:${sessionId}` as const,
  AgentVaultOauthAuthorization: (authorizationId: string) =>
    `agent-vault-oauth-authorization:${authorizationId}` as const,
  AgentVaultOauthAuthorizationCompleteLock: (authorizationId: string) =>
    `agent-vault-oauth-authorization:${authorizationId}:complete` as const,
  AgentVaultOauthRefreshLock: (serviceId: string) => `agent-vault-oauth-refresh-lock:${serviceId}` as const,
  // Bytes an org has been allowed to upload to object storage on one UTC day (YYYY-MM-DD).
  ObjectStorageDailyBytes: (orgId: string, day: string) => `object-storage:daily-bytes:${orgId}:${day}` as const,

  CertDashboardStats: (projectId: string) => `cert-dashboard-stats:${projectId}` as const,
  OrgSecretScanningFindingsCount: (orgId: string) => `org-secret-scanning-findings-count:${orgId}` as const,
  CertActivityTrend: (projectId: string, range: string) => `cert-activity-trend:${projectId}:${range}` as const,
  CertPqcTrend: (projectId: string, range: string) => `cert-pqc-trend:${projectId}:${range}` as const,
  RefreshTokenGrace: (sessionId: string) => `refresh-token-grace:${sessionId}` as const,
  EmailSignupOtpHash: (hash: string) => `email-signup-otp:${hash}:hash` as const,
  EmailSignupOtpLock: (hash: string) => `email-signup-otp:${hash}:lock` as const,
  EmailDispatchCooldown: (purpose: string, mailboxHash: string) =>
    `email-dispatch:${purpose}:${mailboxHash}:cd` as const,
  EmailDispatchMailboxSends: (purpose: string, mailboxHash: string) =>
    `email-dispatch:${purpose}:${mailboxHash}:sends` as const,
  EmailDispatchSourceProbe: (purpose: string, window: number) =>
    `email-dispatch-abuse:${purpose}:src:${window}` as const,
  EmailDispatchMailboxProbe: (purpose: string, window: number) =>
    `email-dispatch-abuse:${purpose}:mailbox:${window}` as const,
  // scopeId is a projectId for the per-project dashboard and an orgId for the org-wide aggregates. Both are
  // UUIDs and the endpoint segments do not overlap, so one prefix serves both without collision.
  InsightsCache: (scopeId: string, endpoint: string) => `insights-cache:${scopeId}:${endpoint}` as const,

  // Braces are a Redis Cluster hash tag: the index zset and every member's payload key must land on
  // one slot for the multi-key upsert/delete scripts.
  WorkerHeartbeatIndex: (workerType: string) => `worker-heartbeat:{${workerType}}` as const,
  WorkerHeartbeat: (workerType: string, instanceId: string) =>
    `worker-heartbeat:{${workerType}}:${instanceId}` as const,

  AdminConfig: "infisical-admin-cfg",
  UpdateCheckLatestVersion: "update-check-latest-version",
  InvalidatingCache: "invalidating-cache",
  SecretManagerCachePattern: "secret-manager:*",
  AuditLogMigrationAlert: "audit-log-migration-alert-last-row-count",
  LicenseCloudPlan: (orgId: string) => `infisical-cloud-plan-${orgId}` as const,
  // Set alongside the free plan getPlan caches when the License Server fails, so callers can tell it from a real answer.
  LicenseCloudPlanFallback: (orgId: string) => `infisical-cloud-plan-fallback-${orgId}` as const,
  LicenseCloudPlanLastKnown: (orgId: string) => `infisical-cloud-plan-last-known-${orgId}` as const,
  AuditLogOrgSettings: (orgId: string) => `audit-log-settings-org-${orgId}` as const,
  AuditLogProjectSettings: (orgId: string, projectId: string) =>
    `audit-log-settings-project-${orgId}-${projectId}` as const,
  AuditLogCollapseWindow: (key: string) => `audit-log-collapse-window-${key}` as const,
  AuditLogCollapseCount: (key: string, windowStart: string) =>
    `audit-log-collapse-count-${key}-${windowStart}` as const,
  // Set after a billing mutation to flag the org's plan cache for stale-while-revalidate reads.
  LicenseCachePassThrough: (orgId: string) => `license-cache-passthrough-${orgId}` as const,
  // Single-flight guard so only one background revalidation runs per org per lock window.
  LicenseCacheRevalidateLock: (orgId: string) => `license-cache-revalidate-lock-${orgId}` as const,
  // Throttles the demand-driven usage reconciliation (fired from getPlan) to once per org per interval.
  LicenseUsageReconcileMarker: (orgId: string) => `license-usage-reconcile-${orgId}` as const,
  LicenseUsageLastReported: (orgId: string, featureKey: string) =>
    `license-usage-last-reported-${orgId}-${featureKey}` as const,
  PkiCertificateQuotaCount: (orgId: string) => `pki-certificate-quota-count-${orgId}` as const,
  PkiWildcardCertificateQuotaCount: (orgId: string) => `pki-wildcard-certificate-quota-count-${orgId}` as const,
  IdentityLockoutState: (identityId: string, authMethod: string, slug: string) =>
    `lockout:identity:{${identityId}}:${authMethod}:${slug}` as const,
  // Sorted set of the identity's *locked* auth methods, scored by when each lockout ends.
  IdentityLockoutIndex: (identityId: string) => `lockout:identity:{${identityId}}` as const,
  IdentityLockoutMember: (authMethod: string, slug: string) => `${authMethod}:${slug}` as const,

  TelemetryAggregatedEventStream: (event: string, bucketId: string) =>
    `telemetry-agg-stream:${event}:${bucketId}` as const,

  AuditLogStreamFlushDebounce: (streamId: string) => `audit-log-stream:${streamId}:flush-debounce` as const,
  SecretReadActivityGate: (day: string, actorId: string, scope: string) =>
    `secret-read-activity:${day}:${actorId}:${scope}` as const,
  SecretReadActivityStream: "secret-read-activity-stream" as const,
  SecretReadActivityConsumerLock: "secret-read-activity:consumer-lock" as const,
  SecretReadActivityUnusedAccessLock: (projectId: string) =>
    `secret-read-activity:unused-access-lock:${projectId}` as const,
  AuditLogIngestConsumerLock: "audit-log-ingest:consumer-lock" as const,

  // period is a YYYY-MM stamp so the monthly notice can only go out once per org per month
  NativeIntegrationDeprecationNotice: (orgId: string, period: string) =>
    `native-integration-deprecation-notice:${orgId}:${period}` as const,

  LegacyPkiDeprecationNotice: (orgId: string, period: string) =>
    `legacy-pki-deprecation-notice:${orgId}:${period}` as const,

  SamlAssertionReplay: (samlConfigId: string, assertionIdHash: string) =>
    `saml-assertion-replay:${samlConfigId}:${assertionIdHash}` as const
};

export const KeyStoreTtls = {
  LdapDirectoryMachinesInSeconds: 60,
  LdapHostLoginInSeconds: 3600,
  LdapGuessedHostLoginInSeconds: 30,
  SetSyncSecretIntegrationLastRunTimestampInSeconds: 60,
  SetSecretSyncLastRunTimestampInSeconds: 60,
  AccessTokenStatusUpdateInSeconds: 120,
  IdentityRevocationVerdictBaseInSeconds: 600, // 10 minutes
  IdentityRevocationVerdictJitterInSeconds: 120, // +/- 2 minutes
  IdentityRevocationVersionInSeconds: 604800, // 7 days
  IdentityTrustedIpsInSeconds: 300, // 5 minutes
  ProjectPermissionMarkerTtlSeconds: 10, // 10 seconds - short-lived marker for fingerprint validation
  ProjectPermissionDataTtlSeconds: 600, // 10 minutes - longer-lived data payload
  ProjectFolderAccessMarkerTtlSeconds: 20,
  ProjectFolderAccessDataTtlSeconds: 600, // 10 minutes

  MfaSessionInSeconds: 300, // 5 minutes
  RecentMfaAuthInSeconds: 600, // 10 minutes
  MfaCodeResendCooldownInSeconds: 60, // 1 minute
  AlertChannelTestCooldownInSeconds: 60, // 1 minute

  WebAuthnChallengeInSeconds: 300, // 5 minutes
  UsedTotpCodeInSeconds: 120, // covers the full ±30s acceptance window (window:1 → 90s) with margin
  ProjectSSEConnectionTtlSeconds: 180, // Must be > heartbeat interval (60s) * 2
  TelemetryIdentifyIdentityInSeconds: 86400, // 24 hours
  RefreshTokenGraceInSeconds: 10,
  EmailSignupOtpInSeconds: 300, // 5 minutes
  EmailDispatchCooldownInSeconds: 60, // 1 minute
  EmailDispatchMailboxWindowInSeconds: 86400, // 24 hours
  EmailDispatchAbuseProbeInSeconds: 7200, // 2 hours
  InsightsCacheInSeconds: 300, // 5 minutes
  InsightsDuplicationCacheInSeconds: 300, // 5 minutes
  InsightsWeeklyHistoryCacheInSeconds: 86400, // 24 hours
  InsightsOrgCacheInSeconds: 900, // 15 minutes
  InsightsUnusedAccessCacheInSeconds: 86400, // 24 hours
  AdminConfigInSeconds: 60,
  UpdateCheckLatestVersionInSeconds: 1209600, // 14 days (survives one missed weekly check)
  InvalidatingCacheInSeconds: 1800, // 30 minutes max lock for cache invalidation job
  AuditLogMigrationAlertInSeconds: 604800, // 7 days
  LicenseCloudPlanInSeconds: 900, // 15 minutes
  LicenseCloudPlanLastKnownInSeconds: 86400, // 24 hours
  AuditLogSettingsInSeconds: 600, // 10 minutes
  PamDefaultProjectInSeconds: 300, // 5 minutes
  AgentVaultDefaultProjectInSeconds: 300, // 5 minutes
  OrgSecretScanningFindingsCountInSeconds: 300, // 5 minutes
  // How long reads stay in stale-while-revalidate mode after a billing mutation (covers Stripe reconciliation).
  LicenseCachePassThroughInSeconds: 180, // 3 minutes
  // Longer window for redirect-to-Stripe-checkout paths, where the purchase applies via webhook only
  // after the customer finishes the hosted checkout/card-setup (which can take a few minutes).
  LicenseCachePassThroughCheckoutInSeconds: 900, // 15 minutes
  // Throttle window for the single-flight background revalidation.
  LicenseCacheRevalidateLockInSeconds: 10,
  // How often a billable org's usage is re-emitted for reconciliation (demand-driven from getPlan).
  LicenseUsageReconcileIntervalInSeconds: 21600, // 6 hours
  LicenseUsageLastReportedInSeconds: 604800, // 7 days
  // Short: the count drifts high as certificates expire and low when an ungated path such as a
  // discovery scan inserts rows, and only this expiry corrects either.
  PkiCertificateQuotaCountInSeconds: 60,
  OauthAuthorizationCodeInSeconds: 600, // 10 minutes
  DashboardCacheInSeconds: 600, // 10 minutes
  ProjectEnvironmentOperationMarkerInSeconds: 10,
  UserMfaUnlockEmailSentInSeconds: 300, // 5 minutes
  StepUpMfaAttemptWindowInSeconds: 300, // 5 minutes - rolling window for counting failed step-up attempts
  StepUpMfaLockoutInSeconds: 300, // 5 minutes - temporary lockout after too many failed step-up attempts
  TelemetryGroupIdentifyInSeconds: 3600, // 1 hour
  TelemetryAuditLogsViewedInSeconds: 3600, // 1 hour
  SecretEtagInSeconds: 900, // 15 minutes
  PkiAcmeNonceInSeconds: 300, // 5 minutes
  SecretReplicationSuccessInSeconds: 10,
  NativeIntegrationDeprecationNoticeInSeconds: 3888000, // 45 days - outlives one monthly cycle
  LegacyPkiDeprecationNoticeInSeconds: 3888000, // 45 days - outlives one monthly cycle
  WorkerHeartbeatInSeconds: 300, // 5 minutes - tolerates several missed 60s beats
  OidcIssuerJwksInSeconds: 600 // 10 minutes
};

type TDeleteItems = {
  pattern: string;
  batchSize?: number;
  delay?: number;
  jitter?: number;
};

type TWaitTillReady = {
  key: string;
  waitingCb?: () => void;
  keyCheckCb: (val: string | null) => boolean;
  waitIteration?: number;
  delay?: number;
  jitter?: number;
};

export type TKeyStoreFactory = {
  setItem: (key: string, value: string | number | Buffer, prefix?: string) => Promise<"OK">;
  getItem: (key: string, prefix?: string) => Promise<string | null>;
  getItemBuffer: (key: string, prefix?: string) => Promise<Buffer | null>;
  getItemPrimary: (key: string, prefix?: string) => Promise<string | null>;
  getItems: (keys: string[], prefix?: string) => Promise<(string | null)[]>;
  getItemsPrimary: (keys: string[], prefix?: string) => Promise<(string | null)[]>;
  setExpiry: (key: string, expiryInSeconds: number) => Promise<number>;
  ttl: (key: string) => Promise<number>;
  setItemWithExpiry: (
    key: string,
    expiryInSeconds: number | string,
    value: string | number | Buffer,
    prefix?: string
  ) => Promise<"OK">;
  setItemWithExpiryNX: (
    key: string,
    expiryInSeconds: number | string,
    value: string | number | Buffer,
    prefix?: string
  ) => Promise<"OK" | null>;
  deleteItem: (key: string) => Promise<number>;
  deleteItemsByKeyIn: (keys: string[]) => Promise<number>;
  deleteItems: (arg: TDeleteItems) => Promise<number>;
  incrementBy: (key: string, value: number) => Promise<number>;
  incrementByAndRefreshExpiryIfUnderLimit: (key: string, limit: number, expiryInSeconds: number) => Promise<number>;
  incrementByIfUnderLimitWithFixedExpiry: (
    key: string,
    value: number,
    limit: number,
    expiryInSeconds: number
  ) => Promise<number>;
  decrementByOrDelete: (key: string) => Promise<number>;
  decrementIfExists: (key: string) => Promise<number | null>;
  claimLeastLoaded: (keys: string[], baseOccupancies: number[], expiryInSeconds: number) => Promise<number>;
  incrementByWithExpiry: (key: string, value: number, expiryInSeconds: number) => Promise<number>;
  probeDistinctMember: (key: string, member: string, expiryInSeconds: number) => Promise<boolean>;
  incrementSeededWithExpiry: (key: string, seed: number, expiryInSeconds: number) => Promise<number>;
  getKeysByPattern: (pattern: string, limit?: number) => Promise<string[]>;
  // list operations
  listPush: (key: string, value: string) => Promise<number>;
  listRange: (key: string, start: number, stop: number) => Promise<string[]>;
  listRemove: (key: string, count: number, value: string) => Promise<number>;
  listLength: (key: string) => Promise<number>;
  // stream operations
  streamAdd: (
    key: string,
    id: string,
    fieldValue: Record<string, string>,
    maxLen?: number,
    expiryInSeconds?: number,
    isExactTrim?: boolean
  ) => Promise<string | null>;
  streamRange: (key: string, start: string, end: string, count?: number) => Promise<[string, string[]][]>;
  streamTrim: (key: string, minId: string, inclusive?: boolean) => Promise<number>;
  streamLength: (key: string) => Promise<number>;
  streamCollect: (
    key: string,
    batchSize: number,
    maxEntries: number
  ) => Promise<{ entries: [string, string[]][]; lastId: string | null }>;
  // hash operations
  hashSet: (key: string, field: string, value: string) => Promise<number>;
  hashGet: (key: string, field: string) => Promise<string | null>;
  // sorted-set indexed items: item key gets native TTL; optional index member is scored by the same
  // deadline and pruned on write.
  setIndexedItemWithExpiry: (arg: {
    indexKey: string;
    member: string;
    itemKey: string;
    value: string;
    expiryInSeconds: number;
    indexed: boolean;
  }) => Promise<void>;
  deleteIndexedItems: (arg: { indexKey: string; members: string[]; itemKeys: string[] }) => Promise<void>;
  sortedSetRangeByScore: (key: string, min: string | number, max: string | number) => Promise<string[]>;
  sortedSetMembersPrimary: (key: string) => Promise<string[]>;
  // pg
  pgIncrementBy: (key: string, dto: { incr?: number; expiry?: string; tx?: Knex }) => Promise<number>;
  pgGetIntItem: (key: string, prefix?: string) => Promise<number | undefined>;
  // locks
  acquireLock(resources: string[], duration: number, settings?: Partial<Settings>): Promise<TKeyStoreLock>;
  waitTillReady: ({ key, waitingCb, keyCheckCb, waitIteration, delay, jitter }: TWaitTillReady) => Promise<void>;
};

export type TKeyStoreLock = {
  release: () => Promise<ExecutionResult>;
  extend?: (duration: number) => Promise<TKeyStoreLock>;
};

const pickPrimaryOrSecondaryRedis = (primary: Redis | Cluster, secondaries?: Array<Redis | Cluster>) => {
  if (!secondaries || !secondaries.length) return primary;
  const selectedReplica = secondaries[Math.floor(Math.random() * secondaries.length)];
  return selectedReplica;
};

interface TKeyStoreFactoryDTO extends TRedisConfigKeys {
  REDIS_READ_REPLICAS?: { host: string; port: number }[];
}

export const keyStoreFactory = (
  redisConfigKeys: TKeyStoreFactoryDTO,
  keyValueStoreDAL: TKeyValueStoreDALFactory
): TKeyStoreFactory => {
  const primaryRedis = buildRedisFromConfig(redisConfigKeys, "keystore");

  const redisReadReplicas = redisConfigKeys.REDIS_READ_REPLICAS?.map((el) => {
    const replicaName = `keystore-replica:${el.host}:${el.port}`;

    if (redisConfigKeys.REDIS_URL) {
      const primaryNode = new URL(redisConfigKeys?.REDIS_URL);
      primaryNode.hostname = el.host;
      primaryNode.port = String(el.port);
      return buildRedisFromConfig({ ...redisConfigKeys, REDIS_URL: primaryNode.toString() }, replicaName);
    }

    if (redisConfigKeys.REDIS_SENTINEL_HOSTS) {
      return buildRedisFromConfig({ ...redisConfigKeys, REDIS_SENTINEL_HOSTS: [el] }, replicaName);
    }

    return buildRedisFromConfig({ ...redisConfigKeys, REDIS_CLUSTER_HOSTS: [el] }, replicaName);
  });
  const redisLock = new Redlock([primaryRedis], { retryCount: 2, retryDelay: 200 });

  const setItem = async (key: string, value: string | number | Buffer, prefix?: string) =>
    primaryRedis.set(prefix ? `${prefix}:${key}` : key, value);

  const getItem = async (key: string, prefix?: string) =>
    pickPrimaryOrSecondaryRedis(primaryRedis, redisReadReplicas).get(prefix ? `${prefix}:${key}` : key);

  // Reads a value written as raw bytes. Callers holding binary blobs (ciphertext) use this instead of
  // getItem so the payload never round-trips through a base64 string on either side.
  const getItemBuffer = async (key: string, prefix?: string) =>
    pickPrimaryOrSecondaryRedis(primaryRedis, redisReadReplicas).getBuffer(prefix ? `${prefix}:${key}` : key);

  const getItemPrimary = async (key: string, prefix?: string) => primaryRedis.get(prefix ? `${prefix}:${key}` : key);

  const getItemsPrimary = async (keys: string[], prefix?: string) =>
    primaryRedis.mget(keys.map((key) => (prefix ? `${prefix}:${key}` : key)));

  const getItems = async (keys: string[], prefix?: string) =>
    pickPrimaryOrSecondaryRedis(primaryRedis, redisReadReplicas).mget(
      keys.map((key) => (prefix ? `${prefix}:${key}` : key))
    );

  const setItemWithExpiry = async (
    key: string,
    expiryInSeconds: number | string,
    value: string | number | Buffer,
    prefix?: string
  ) => primaryRedis.set(prefix ? `${prefix}:${key}` : key, value, "EX", expiryInSeconds);

  const setItemWithExpiryNX = async (
    key: string,
    expiryInSeconds: number | string,
    value: string | number | Buffer,
    prefix?: string
  ) => primaryRedis.set(prefix ? `${prefix}:${key}` : key, value, "EX", expiryInSeconds, "NX");

  const deleteItem = async (key: string) => primaryRedis.del(key);

  const deleteItemsByKeyIn = async (keys: string[]) => {
    if (keys.length === 0) return 0;
    return primaryRedis.del(keys);
  };

  const deleteItems = async ({ pattern, batchSize = 500, delay = 1500, jitter = 200 }: TDeleteItems) => {
    let cursor = "0";
    let totalDeleted = 0;

    do {
      // Await in loop is needed so that Redis is not overwhelmed
      // eslint-disable-next-line no-await-in-loop
      const [nextCursor, keys] = await primaryRedis.scan(cursor, "MATCH", pattern, "COUNT", 1000); // Count should be 1000 - 5000 for prod loads
      cursor = nextCursor;

      for (let i = 0; i < keys.length; i += batchSize) {
        const batch = keys.slice(i, i + batchSize);
        const pipeline = primaryRedis.pipeline();
        for (const key of batch) {
          pipeline.unlink(key);
        }
        // eslint-disable-next-line no-await-in-loop
        await pipeline.exec();
        totalDeleted += batch.length;

        // eslint-disable-next-line no-await-in-loop
        await delayMs(Math.max(0, applyJitter(delay, jitter)));
      }
    } while (cursor !== "0");

    return totalDeleted;
  };

  const incrementBy = async (key: string, value: number) => primaryRedis.incrby(key, value);

  // Atomic admit: INCR by 1; if the post-INCR count is over the cap, DECR back and
  // signal rejection without touching EXPIRE — so failed probes against an orphaned
  // counter cannot keep refreshing its TTL. Otherwise refresh the TTL alongside the
  // successful admit. Returns -1 for rejection, otherwise the post-INCR count.
  const INCREMENT_AND_REFRESH_EXPIRY_IF_UNDER_LIMIT_SCRIPT = `
    local count = redis.call("INCR", KEYS[1])
    if count > tonumber(ARGV[1]) then
      redis.call("DECR", KEYS[1])
      return -1
    end
    redis.call("EXPIRE", KEYS[1], ARGV[2])
    return count
  `;

  // Adds the value only if the total stays within the limit, in one atomic step, and otherwise returns -1 without
  // adding. The expiry is set only when the key has none, so it counts from the first write and retries can't push it
  // back.
  const INCREMENT_BY_IF_UNDER_LIMIT_WITH_FIXED_EXPIRY_SCRIPT = `
    local current = tonumber(redis.call("GET", KEYS[1]) or "0")
    local value = tonumber(ARGV[1])
    if current + value > tonumber(ARGV[2]) then
      return -1
    end
    local total = redis.call("INCRBY", KEYS[1], value)
    if redis.call("TTL", KEYS[1]) == -1 then
      redis.call("EXPIRE", KEYS[1], ARGV[3])
    end
    return total
  `;

  // Atomic release: DECR but never below 0, and never leave a no-TTL key behind. If
  // the counter is missing or already ≤ 1, DEL so the next admit creates a fresh
  // key with a fresh TTL. Does NOT touch EXPIRE — the slot is being released.
  const DECREMENT_OR_DELETE_SCRIPT = `
    local current = redis.call("GET", KEYS[1])
    if not current or tonumber(current) <= 1 then
      redis.call("DEL", KEYS[1])
      return 0
    end
    return redis.call("DECR", KEYS[1])
  `;

  // A plain DECR on a missing key creates it at -1 with no TTL, which then lives forever.
  const DECREMENT_IF_EXISTS_SCRIPT = `
    if redis.call("EXISTS", KEYS[1]) == 0 then
      return false
    end
    return redis.call("DECR", KEYS[1])
  `;

  const incrementByAndRefreshExpiryIfUnderLimit = async (
    key: string,
    limit: number,
    expiryInSeconds: number
  ): Promise<number> => {
    const result = await primaryRedis.eval(
      INCREMENT_AND_REFRESH_EXPIRY_IF_UNDER_LIMIT_SCRIPT,
      1,
      key,
      limit,
      expiryInSeconds
    );
    return Number(result);
  };

  const incrementByIfUnderLimitWithFixedExpiry = async (
    key: string,
    value: number,
    limit: number,
    expiryInSeconds: number
  ): Promise<number> => {
    const result = await primaryRedis.eval(
      INCREMENT_BY_IF_UNDER_LIMIT_WITH_FIXED_EXPIRY_SCRIPT,
      1,
      key,
      value,
      limit,
      expiryInSeconds
    );
    return Number(result);
  };

  const decrementByOrDelete = async (key: string): Promise<number> => {
    const result = await primaryRedis.eval(DECREMENT_OR_DELETE_SCRIPT, 1, key);
    return Number(result);
  };

  // Returns null when the key does not exist, leaving it absent.
  const decrementIfExists = async (key: string): Promise<number | null> => {
    const result = await primaryRedis.eval(DECREMENT_IF_EXISTS_SCRIPT, 1, key);
    return result === null ? null : Number(result);
  };

  // Choosing and claiming has to be one round trip. Done as separate read and write calls, every
  // concurrent selection reads the same minimum before any of them claims it and they all pile onto
  // the same gateway, which is the stampede the reservation exists to prevent.
  const CLAIM_LEAST_LOADED_SCRIPT = `
    local ttl = tonumber(ARGV[#ARGV])
    local bestIdx = 0
    local bestTotal = nil
    for i = 1, #KEYS do
      local reserved = tonumber(redis.call("GET", KEYS[i]) or "0")
      local total = tonumber(ARGV[i]) + reserved
      -- strict less-than, so ties fall to the caller's order (pre-shuffled for a random tie-break)
      if bestTotal == nil or total < bestTotal then
        bestTotal = total
        bestIdx = i
      end
    end
    if bestIdx == 0 then return 0 end
    -- Set the expiry only on the first increment. Refreshing it on every claim means a busy key
    -- never elapses, so a crashed pod's leaked reservations would stay counted indefinitely.
    if redis.call("INCR", KEYS[bestIdx]) == 1 then
      redis.call("EXPIRE", KEYS[bestIdx], ttl)
    end
    return bestIdx
  `;

  /** Returns the 1-based index of the claimed key, or 0 when no keys were given. */
  const claimLeastLoaded = async (
    keys: string[],
    baseOccupancies: number[],
    expiryInSeconds: number
  ): Promise<number> => {
    if (keys.length === 0) return 0;
    if (keys.length !== baseOccupancies.length) {
      throw new Error("claimLeastLoaded: baseOccupancies must have one entry per key");
    }
    const result = await primaryRedis.eval(
      CLAIM_LEAST_LOADED_SCRIPT,
      keys.length,
      ...keys,
      ...baseOccupancies.map((n) => String(n)),
      String(expiryInSeconds)
    );
    return Number(result);
  };

  const INCREMENT_WITH_EXPIRY = `
    local v = redis.call('INCRBY', KEYS[1], ARGV[1])
    redis.call('EXPIRE', KEYS[1], ARGV[2])
    return v
  `;

  // Atomically increment key and (re)set TTL on every call so the expiry rolls forward with each write.
  const incrementByWithExpiry = async (key: string, value: number, expiryInSeconds: number): Promise<number> => {
    const result = await primaryRedis.eval(INCREMENT_WITH_EXPIRY, 1, key, String(value), String(expiryInSeconds));
    return result as number;
  };

  // Timestamp-seeded INCR. When the key is missing (INCR returns 1) it rebases
  // the counter by `seed` (a caller-supplied Date.now()), so a resurrected key
  // restarts above any value it held before and a stale cached allow stamped
  // with an old version can never match again.
  const INCREMENT_SEEDED_WITH_EXPIRY = `
    local v = redis.call('INCR', KEYS[1])
    if v == 1 then
      v = redis.call('INCRBY', KEYS[1], ARGV[1])
    end
    redis.call('EXPIRE', KEYS[1], ARGV[2])
    return v
  `;

  const incrementSeededWithExpiry = async (key: string, seed: number, expiryInSeconds: number): Promise<number> => {
    const result = await primaryRedis.eval(INCREMENT_SEEDED_WITH_EXPIRY, 1, key, String(seed), String(expiryInSeconds));
    return Number(result);
  };

  const PROBE_DISTINCT_MEMBER = `
    local isNew = redis.call('PFADD', KEYS[1], ARGV[1])
    redis.call('EXPIRE', KEYS[1], ARGV[2])
    return isNew
  `;

  // Records `member` in a HyperLogLog and reports whether it had not been seen in this key before.
  // The HLL stores a fixed ~12KB register array rather than the members themselves, so a caller can
  // count distinct values without the store ever holding one.
  const probeDistinctMember = async (key: string, member: string, expiryInSeconds: number): Promise<boolean> => {
    const result = await primaryRedis.eval(PROBE_DISTINCT_MEMBER, 1, key, member, String(expiryInSeconds));
    return Number(result) === 1;
  };

  const setExpiry = async (key: string, expiryInSeconds: number) => primaryRedis.expire(key, expiryInSeconds);

  const ttl = async (key: string) => primaryRedis.ttl(key);

  const getKeysByPattern = async (pattern: string, limit?: number) => {
    let cursor = "0";
    const allKeys: string[] = [];

    do {
      // eslint-disable-next-line no-await-in-loop
      const [nextCursor, keys] = await pickPrimaryOrSecondaryRedis(primaryRedis, redisReadReplicas).scan(
        cursor,
        "MATCH",
        pattern,
        "COUNT",
        1000
      );
      cursor = nextCursor;
      allKeys.push(...keys);

      if (limit && allKeys.length >= limit) {
        return allKeys.slice(0, limit);
      }
    } while (cursor !== "0");

    return allKeys;
  };

  const pgIncrementBy: TKeyStoreFactory["pgIncrementBy"] = async (key, { incr = 1, tx, expiry }) => {
    const expiresAt = expiry ? new Date(Date.now() + ms(expiry)) : undefined;
    return keyValueStoreDAL.incrementBy(key, { incr, expiresAt, tx });
  };

  const pgGetIntItem = async (key: string, prefix?: string) =>
    keyValueStoreDAL.findOneInt(prefix ? `${prefix}:${key}` : key);

  const hashSet = async (key: string, field: string, value: string) => primaryRedis.hset(key, field, value);

  const hashGet = async (key: string, field: string) => primaryRedis.hget(key, field);

  // KEYS[1] indexKey (ZSET), KEYS[2] itemKey (payload string).
  // ARGV[1] member, ARGV[2] value, ARGV[3] expiryInSeconds, ARGV[4] expiresAt score (ms),
  // ARGV[5] indexed ('1' | '0'), ARGV[6] now (ms, stale-index prune cutoff).
  const INDEXED_ITEM_UPSERT = `
    redis.call('SET', KEYS[2], ARGV[2], 'EX', ARGV[3])

    if ARGV[5] == '1' then
      redis.call('ZADD', KEYS[1], ARGV[4], ARGV[1])
    else
      redis.call('ZREM', KEYS[1], ARGV[1])
    end

    redis.call('ZREMRANGEBYSCORE', KEYS[1], '-inf', ARGV[6])

    if redis.call('ZCARD', KEYS[1]) == 0 then
      redis.call('DEL', KEYS[1])
    else
      local current = redis.call('TTL', KEYS[1])
      local wanted = tonumber(ARGV[3])
      if current < 0 or current < wanted then
        redis.call('EXPIRE', KEYS[1], wanted)
      end
    end

    return 1
  `;

  const setIndexedItemWithExpiry: TKeyStoreFactory["setIndexedItemWithExpiry"] = async ({
    indexKey,
    member,
    itemKey,
    value,
    expiryInSeconds,
    indexed
  }) => {
    const now = Date.now();
    await primaryRedis.eval(
      INDEXED_ITEM_UPSERT,
      2,
      indexKey,
      itemKey,
      member,
      value,
      String(expiryInSeconds),
      String(now + expiryInSeconds * 1000),
      indexed ? "1" : "0",
      String(now)
    );
  };

  const DELETE_INDEXED_ITEMS = `
    for i = 1, #ARGV do
      redis.call('ZREM', KEYS[1], ARGV[i])
    end
    for i = 2, #KEYS do
      redis.call('DEL', KEYS[i])
    end
    if redis.call('ZCARD', KEYS[1]) == 0 then
      redis.call('DEL', KEYS[1])
    end
    return 1
  `;

  const deleteIndexedItems: TKeyStoreFactory["deleteIndexedItems"] = async ({ indexKey, members, itemKeys }) => {
    if (!members.length && !itemKeys.length) return;
    await primaryRedis.eval(DELETE_INDEXED_ITEMS, itemKeys.length + 1, indexKey, ...itemKeys, ...members);
  };

  const sortedSetRangeByScore = async (key: string, min: string | number, max: string | number) =>
    pickPrimaryOrSecondaryRedis(primaryRedis, redisReadReplicas).zrangebyscore(key, min, max);

  const sortedSetMembersPrimary = async (key: string) => primaryRedis.zrange(key, 0, -1);

  // List operations
  const listPush = async (key: string, value: string) => primaryRedis.rpush(key, value);

  const listRange = async (key: string, start: number, stop: number) =>
    pickPrimaryOrSecondaryRedis(primaryRedis, redisReadReplicas).lrange(key, start, stop);

  const listRemove = async (key: string, count: number, value: string) => primaryRedis.lrem(key, count, value);

  const listLength = async (key: string) => pickPrimaryOrSecondaryRedis(primaryRedis, redisReadReplicas).llen(key);

  // Stream operations
  const streamAdd = async (
    key: string,
    id: string,
    fieldValue: Record<string, string>,
    maxLen = 1_000_000,
    expiryInSeconds?: number,
    // With "~", Redis only trims whole internal blocks of about 100 entries, so a cap of 10 could still hold around
    // 100. Small caps need exact trimming.
    isExactTrim = false
  ) => {
    const args: string[] = [];
    for (const [field, value] of Object.entries(fieldValue)) {
      args.push(field, value);
    }

    if (!expiryInSeconds) {
      return isExactTrim
        ? primaryRedis.xadd(key, "MAXLEN", maxLen, id, ...args)
        : primaryRedis.xadd(key, "MAXLEN", "~", maxLen, id, ...args);
    }

    const pipeline = primaryRedis.multi();
    if (isExactTrim) pipeline.xadd(key, "MAXLEN", maxLen, id, ...args);
    else pipeline.xadd(key, "MAXLEN", "~", maxLen, id, ...args);
    const results = await pipeline.expire(key, expiryInSeconds).exec();

    const [addError, entryId] = results?.[0] ?? [null, null];
    if (addError) throw addError;
    return (entryId as string | null) ?? null;
  };

  const streamRange = async (key: string, start: string, end: string, count?: number) => {
    if (count) {
      return primaryRedis.xrange(key, start, end, "COUNT", count);
    }
    return primaryRedis.xrange(key, start, end);
  };

  const streamLength = async (key: string) => primaryRedis.xlen(key);

  const streamTrim = async (key: string, minId: string, inclusive = false) => {
    let id = minId;
    if (inclusive) {
      const [ts, seq] = minId.split("-");
      id = `${ts}-${Number(seq) + 1}`;
    }
    return primaryRedis.xtrim(key, "MINID", id);
  };

  const streamCollect = async (key: string, batchSize: number, maxEntries: number) => {
    let lastId: string | null = null;
    const allEntries: [string, string[]][] = [];

    for (let i = 0; i < Math.ceil(maxEntries / batchSize); i += 1) {
      const start: string = lastId ? `(${lastId}` : "-";
      // eslint-disable-next-line no-await-in-loop
      const batch: [string, string[]][] = await primaryRedis.xrange(key, start, "+", "COUNT", batchSize);

      if (batch.length === 0) break;

      allEntries.push(...batch);
      // eslint-disable-next-line prefer-destructuring
      lastId = batch[batch.length - 1][0];

      if (allEntries.length >= maxEntries || batch.length < batchSize) break;
    }

    return { entries: allEntries, lastId };
  };

  const waitTillReady = async ({
    key,
    waitingCb,
    keyCheckCb,
    waitIteration = 10,
    delay = 1000,
    jitter = 200
  }: TWaitTillReady) => {
    let attempts = 0;
    let isReady = keyCheckCb(await getItem(key));
    while (!isReady) {
      if (attempts > waitIteration) return;
      // eslint-disable-next-line
      await new Promise((resolve) => {
        waitingCb?.();
        setTimeout(resolve, Math.max(0, applyJitter(delay, jitter)));
      });
      attempts += 1;
      // eslint-disable-next-line
      isReady = keyCheckCb(await getItem(key));
    }
  };

  return {
    setItem,
    getItem,
    getItemBuffer,
    getItemPrimary,
    setExpiry,
    ttl,
    setItemWithExpiry,
    setItemWithExpiryNX,
    deleteItem,
    deleteItems,
    incrementBy,
    incrementByAndRefreshExpiryIfUnderLimit,
    incrementByIfUnderLimitWithFixedExpiry,
    decrementByOrDelete,
    decrementIfExists,
    claimLeastLoaded,
    incrementByWithExpiry,
    probeDistinctMember,
    incrementSeededWithExpiry,
    acquireLock(resources: string[], duration: number, settings?: Partial<Settings>) {
      return redisLock.acquire(resources, duration, settings);
    },
    waitTillReady,
    getKeysByPattern,
    deleteItemsByKeyIn,
    getItems,
    getItemsPrimary,
    pgGetIntItem,
    pgIncrementBy,
    hashSet,
    hashGet,
    setIndexedItemWithExpiry,
    deleteIndexedItems,
    sortedSetRangeByScore,
    sortedSetMembersPrimary,
    listPush,
    listRange,
    listRemove,
    listLength,
    streamAdd,
    streamLength,
    streamRange,
    streamTrim,
    streamCollect
  };
};