Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

30.7 KB
Raw Blame
import { z } from "zod";
import { parseBlockedCidr } from "./server/webhooks/parseBlockedCidr";
import { removeEmptyEnvVariables } from "./utils/environment";

// Per-segment byte budget for S3 event keys. Off by default (2048 > 800-byte
// idSchema cap). Lower to 255 for MinIO on ext4. Affects only new writes —
// existing objects are read by recorded path, not reconstructed.
// Shared with worker/src/env.ts to keep validation rules identical.
export const langfuseS3EventKeyMaxSegmentBytesSchema = z.coerce
  .number()
  .int()
  .min(64)
  .max(2048)
  .default(2048);

// Socket-level watchdog for all Redis connections: ioredis destroys and
// reconnects a socket that received no data for this long, so a hung
// connection cannot pin BullMQ concurrency slots forever. Must be 0 (disabled)
// or >= 10s: BullMQ blocking commands (BZPOPMIN) legitimately idle ~5s between
// packets, and lower values make healthy idle workers cycle through
// reconnects (#12944).
export const redisSocketTimeoutMsSchema = z.coerce
  .number()
  .int()
  .refine((ms) => ms === 0 || ms >= 10_000, {
    message:
      "REDIS_SOCKET_TIMEOUT_MS must be 0 (disabled) or at least 10000; BullMQ blocking commands idle ~5s between packets",
  })
  .default(30_000);

function commaSeparatedLowercase(value: string | undefined): string[] {
  if (!value) return [];
  return value
    .split(",")
    .map((part) => part.toLowerCase().trim())
    .filter((part) => part.length > 0);
}

const optionalCommaSeparatedLowercase = z
  .string()
  .optional()
  .transform(commaSeparatedLowercase);

function isCidr(value: string): boolean {
  return parseBlockedCidr(value) !== undefined;
}

const DEFAULT_LLM_COMPLETION_TIMEOUT_MS = 120_000;

const EnvSchema = z.object({
  NEXT_PUBLIC_LANGFUSE_CLOUD_REGION: z.string().optional(),
  // Dev-only override: set to an ISO datetime string to shift the legacy blob
  // export cutoff for local testing (e.g. "2020-01-01T00:00:00.000Z" makes
  // every project post-cutoff; "2099-01-01T00:00:00.000Z" grandfathers all).
  NEXT_PUBLIC_LANGFUSE_BLOB_EXPORT_CUTOFF: z.iso.datetime().optional(),
  // Same, for the integration-level cutoff (BlobStorageIntegration.createdAt).
  NEXT_PUBLIC_LANGFUSE_BLOB_EXPORTER_CUTOFF: z.iso.datetime().optional(),
  NEXT_PUBLIC_LANGFUSE_ANALYTICS_EXPORTER_CUTOFF: z.iso.datetime().optional(),
  NODE_ENV: z
    .enum(["development", "test", "production"])
    .default("development"),
  NEXTAUTH_URL: z.url().optional(),
  // Internal Topics PoC controls; not a supported self-hosting configuration.
  LANGFUSE_TOPICS_ENABLED: z.enum(["true", "false"]).default("false"),
  LANGFUSE_TOPICS_ENABLED_PROJECT_IDS: z
    .string()
    .default("")
    .transform((value) =>
      value
        .split(",")
        .map((id) => id.trim())
        .filter(Boolean),
    ),
  LANGFUSE_TOPICS_TRACING_ENABLED_PROJECT_IDS: z
    .string()
    .default("")
    .transform((value) =>
      value
        .split(",")
        .map((id) => id.trim())
        .filter(Boolean),
    ),
  LANGFUSE_TOPICS_REDIS_TTL_SECONDS: z.coerce
    .number()
    .int()
    .positive()
    .default(10800),
  // NextAuth.js falls back to VERCEL_URL when NEXTAUTH_URL is unset; the
  // shared base-URL helper mirrors that (see web/src/env.mjs preprocess).
  VERCEL_URL: z.string().optional(),
  EMAIL_FROM_ADDRESS: z.string().optional(),
  // Standard SMTP URL (`smtp://`, `smtps://`) or `ses://<region>` to send via
  // AWS SES using the default AWS credential chain (IAM role, SSO, env vars).
  // Example: `ses://us-east-1`.
  SMTP_CONNECTION_URL: z.string().optional(),
  CLOUD_CRM_EMAIL: z.string().optional(),
  REDIS_HOST: z.string().nullish(),
  REDIS_PORT: z.coerce
    .number() // .env files convert numbers to strings, therefore we have to enforce them to be numbers
    .positive()
    .max(65536, `options.port should be >= 0 and < 65536`)
    .default(6379)
    .nullable(),
  REDIS_AUTH: z.string().nullish(),
  REDIS_USERNAME: z.string().nullish(),
  REDIS_CONNECTION_STRING: z.string().nullish(),
  // Optional prefix for Redis keys. Used by BullMQ queues via their native prefix option
  // and by the singleton cache instance via ioredis keyPrefix. Useful for multi-tenant Redis.
  REDIS_KEY_PREFIX: z.string().nullish(),
  REDIS_TLS_ENABLED: z.enum(["true", "false"]).default("false"),
  REDIS_TLS_CA_PATH: z.string().optional(),
  REDIS_TLS_CERT_PATH: z.string().optional(),
  REDIS_TLS_KEY_PATH: z.string().optional(),
  REDIS_TLS_SERVERNAME: z.string().optional(),
  REDIS_TLS_REJECT_UNAUTHORIZED: z.enum(["true", "false"]).optional(),
  REDIS_TLS_CHECK_SERVER_IDENTITY: z.enum(["true", "false"]).optional(),
  REDIS_TLS_SECURE_PROTOCOL: z.string().optional(),
  REDIS_TLS_CIPHERS: z.string().optional(),
  REDIS_TLS_HONOR_CIPHER_ORDER: z.enum(["true", "false"]).optional(),
  REDIS_TLS_KEY_PASSPHRASE: z.string().optional(),
  REDIS_ENABLE_AUTO_PIPELINING: z.enum(["true", "false"]).default("true"),
  REDIS_SOCKET_TIMEOUT_MS: redisSocketTimeoutMsSchema,
  LANGFUSE_BULLMQ_SKIP_REDIS_VERSION_CHECK: z
    .enum(["true", "false"])
    .default("false"),
  // Redis Cluster Configuration
  REDIS_CLUSTER_ENABLED: z.enum(["true", "false"]).default("false"),
  REDIS_CLUSTER_NODES: z.string().optional(),
  REDIS_CLUSTER_SLOTS_REFRESH_TIMEOUT: z.coerce
    .number()
    .int()
    .positive()
    .default(5000),
  REDIS_SENTINEL_ENABLED: z.enum(["true", "false"]).default("false"),
  REDIS_SENTINEL_TLS_ENABLED: z.enum(["true", "false"]).default("false"),
  REDIS_SENTINEL_NODES: z.string().optional(),
  REDIS_SENTINEL_MASTER_NAME: z.string().optional(),
  REDIS_SENTINEL_USERNAME: z.string().optional(),
  REDIS_SENTINEL_PASSWORD: z.string().optional(),
  ENCRYPTION_KEY: z
    .string()
    .length(
      64,
      "ENCRYPTION_KEY must be 256 bits, 64 string characters in hex format, generate via: openssl rand -hex 32",
    )
    .optional(),
  LANGFUSE_CACHE_MODEL_MATCH_ENABLED: z.enum(["true", "false"]).default("true"),
  LANGFUSE_CACHE_MODEL_MATCH_TTL_SECONDS: z.coerce.number().default(86400), // 24 hours
  LANGFUSE_LOCAL_CACHE_MODEL_MATCH_ENABLED: z
    .enum(["true", "false"])
    .default("false"),
  LANGFUSE_LOCAL_CACHE_MODEL_MATCH_TTL_MS: z.coerce
    .number()
    .positive()
    .default(10_000),
  LANGFUSE_LOCAL_CACHE_MODEL_MATCH_MAX: z.coerce
    .number()
    .int()
    .positive()
    .default(20_000),
  LANGFUSE_CACHE_PROMPT_ENABLED: z.enum(["true", "false"]).default("true"),
  LANGFUSE_CACHE_PROMPT_TTL_SECONDS: z.coerce.number().default(3600), // 1h
  LANGFUSE_CACHE_SKILL_ENABLED: z.enum(["true", "false"]).default("true"),
  LANGFUSE_CACHE_SKILL_TTL_SECONDS: z.coerce
    .number()
    .int()
    .positive()
    .default(3600), // 1h
  CLICKHOUSE_URL: z.url(),
  CLICKHOUSE_READ_ONLY_URL: z.url().optional(),
  CLICKHOUSE_EVENTS_READ_ONLY_URL: z.url().optional(),
  CLICKHOUSE_CLUSTER_ENABLED: z.enum(["true", "false"]).default("true"),
  CLICKHOUSE_CLUSTER_NAME: z.string().default("default"),
  CLICKHOUSE_DB: z.string().default("default"),
  CLICKHOUSE_USER: z.string(),
  CLICKHOUSE_PASSWORD: z.string(),
  CLICKHOUSE_KEEP_ALIVE_IDLE_SOCKET_TTL: z.coerce.number().int().default(9000),
  CLICKHOUSE_MAX_OPEN_CONNECTIONS: z.coerce.number().int().default(25),
  LANGFUSE_JSON_BAD_UNICODE_ESCAPE: z
    .enum(["auto", "no_throw", "sanitize"])
    .optional(),
  // Optional to allow for server-setting fallbacks
  CLICKHOUSE_ASYNC_INSERT_MAX_DATA_SIZE: z.string().optional(),
  CLICKHOUSE_ASYNC_INSERT_BUSY_TIMEOUT_MS: z.coerce.number().int().optional(),
  CLICKHOUSE_ASYNC_INSERT_BUSY_TIMEOUT_MIN_MS: z.coerce
    .number()
    .int()
    .min(50)
    .optional(),
  CLICKHOUSE_LIGHTWEIGHT_DELETE_MODE: z
    .enum(["alter_update", "lightweight_update", "lightweight_update_force"])
    .default("alter_update"),
  CLICKHOUSE_USE_LIGHTWEIGHT_UPDATE: z.enum(["true", "false"]).default("false"),
  CLICKHOUSE_UPDATE_PARALLEL_MODE: z
    .enum(["sync", "async", "auto"])
    .default("auto"),
  // Workarounds for ClickHouse version-specific parser and analyzer bugs. In
  // "auto", Langfuse detects the ClickHouse version on startup and applies
  // known compatibility settings for affected version bands.
  CLICKHOUSE_DISABLE_LAZY_MATERIALIZATION: z
    .enum(["auto", "true", "false"])
    .default("auto"),
  CLICKHOUSE_DISABLE_TOP_K_THROUGH_JOIN: z
    .enum(["auto", "true", "false"])
    .default("auto"),
  // Read-time skip-index evaluation, applied only from the version that fixes
  // the patch-part read bug. See the compatibility rule for details.
  CLICKHOUSE_ENABLE_SKIP_INDEXES_ON_DATA_READ: z
    .enum(["auto", "true", "false"])
    .default("auto"),
  CLICKHOUSE_MAX_BYTES_BEFORE_EXTERNAL_GROUP_BY: z.coerce
    .number()
    .default(32_000_000_000), // ~32GB
  CLICKHOUSE_USE_QUERY_CONDITION_CACHE: z
    .enum(["true", "false"])
    .default("false"),
  LANGFUSE_ENABLE_SINGLE_LEVEL_QUERY_OPTIMIZATION: z
    .enum(["true", "false"])
    .default("false"),
  LANGFUSE_ROOT_EVENT_CONDITION_MAX_WINDOW_HOURS: z.coerce
    .number()
    .int()
    .nonnegative()
    .default(168), // 7 days
  LANGFUSE_INGESTION_QUEUE_DELAY_MS: z.coerce
    .number()
    .nonnegative()
    .default(15_000),
  LANGFUSE_INGESTION_QUEUE_SHARD_COUNT: z.coerce.number().positive().default(1),
  LANGFUSE_INGESTION_SECONDARY_QUEUE_SHARD_COUNT: z.coerce
    .number()
    .positive()
    .default(1),
  LANGFUSE_OTEL_INGESTION_QUEUE_SHARD_COUNT: z.coerce
    .number()
    .positive()
    .default(1),
  LANGFUSE_OTEL_INGESTION_SECONDARY_QUEUE_SHARD_COUNT: z.coerce
    .number()
    .positive()
    .default(1),
  LANGFUSE_OTEL_MAX_SPAN_BYTES: z.coerce.number().positive().default(9_500_000), // 9.5MB — just under ClickHouse's 10MB min_chunk_bytes_for_parallel_parsing default
  LANGFUSE_EVAL_EXECUTION_QUEUE_SHARD_COUNT: z.coerce
    .number()
    .positive()
    .default(1),
  LANGFUSE_EVAL_EXECUTION_SECONDARY_QUEUE_SHARD_COUNT: z.coerce
    .number()
    .positive()
    .default(1),
  LANGFUSE_LLM_AS_JUDGE_EXECUTION_QUEUE_SHARD_COUNT: z.coerce
    .number()
    .positive()
    .default(1),
  LANGFUSE_CODE_EVAL_EXECUTION_QUEUE_SHARD_COUNT: z.coerce
    .number()
    .positive()
    .default(1),
  LANGFUSE_CODE_EVAL_DISPATCHER: z
    .enum(["insecure-local", "aws-lambda"])
    .optional(),
  LANGFUSE_CODE_EVAL_AWS_LAMBDA_ENDPOINT: z.string().optional(),
  LANGFUSE_CODE_EVAL_AWS_LAMBDA_NODE_FUNCTION_NAME: z
    .string()
    .default("code-based-eval-executor-node"),
  LANGFUSE_CODE_EVAL_AWS_LAMBDA_PYTHON_FUNCTION_NAME: z
    .string()
    .default("code-based-eval-executor-python"),
  LANGFUSE_CODE_EVAL_LOCAL_TIMEOUT_MS: z.coerce
    .number()
    .int()
    .positive()
    .default(2_000),
  LANGFUSE_TRACE_UPSERT_QUEUE_SHARD_COUNT: z.coerce
    .number()
    .positive()
    .default(1),
  LANGFUSE_TRACE_UPSERT_QUEUE_ATTEMPTS: z.coerce.number().positive().default(2),
  LANGFUSE_TRACE_DELETE_DELAY_MS: z.coerce
    .number()
    .nonnegative()
    .default(5_000),
  LANGFUSE_LARGE_PROJECT_IDS: z
    .string()
    .default("")
    .transform(
      (value) =>
        new Set(
          value
            .split(",")
            .map((id) => id.trim())
            .filter(Boolean),
        ),
    ),
  LANGFUSE_DELETE_SKIP_PROJECT_IDS: z
    .string()
    .optional()
    .transform((s) => (s ? s.split(",").map((id) => id.trim()) : [])),
  // Has no effect in events_only mode, where the v3 experience cannot work.
  LANGFUSE_FORCE_V3_EXPERIENCE: z
    .string()
    .optional()
    .transform((s) => (s ? s.split(",").map((id) => id.trim()) : [])),
  SALT: z.string().optional(), // used by components imported by web package
  LANGFUSE_LOG_LEVEL: z
    .enum(["trace", "debug", "info", "warn", "error", "fatal"])
    .optional(),
  LANGFUSE_LOG_FORMAT: z.enum(["text", "json"]).default("text"),
  LANGFUSE_LOG_PROPAGATED_HEADERS: z
    .string()
    .optional()
    .transform((s) =>
      s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
    ),
  ENABLE_AWS_CLOUDWATCH_METRIC_PUBLISHING: z
    .enum(["true", "false"])
    .default("false"),
  LANGFUSE_S3_CONCURRENT_WRITES: z.coerce.number().positive().default(50),
  LANGFUSE_S3_UPLOAD_ENABLE_BUFFERED: z
    .enum(["true", "false"])
    .default("false"),
  LANGFUSE_S3_UPLOAD_MAX_PART_ATTEMPTS: z.coerce
    .number()
    .min(1)
    .max(10)
    .default(3),
  LANGFUSE_S3_UPLOAD_MAX_CONCURRENT_PARTS: z.coerce
    .number()
    .min(1)
    .max(10)
    .default(3),
  LANGFUSE_S3_EVENT_UPLOAD_BUCKET: z.string(), // Langfuse requires a bucket name for S3 Event Uploads.
  LANGFUSE_S3_EVENT_UPLOAD_PREFIX: z.string().default(""),
  LANGFUSE_TRACE_BATCH_TRANSCRIPT_STORAGE_REQUEST_TIMEOUT_MS: z.coerce
    .number()
    .int()
    .positive()
    .default(10_000), // 10 seconds
  LANGFUSE_S3_EVENT_UPLOAD_REGION: z.string().optional(),
  LANGFUSE_S3_EVENT_UPLOAD_ENDPOINT: z.string().optional(),
  LANGFUSE_S3_EVENT_UPLOAD_ACCESS_KEY_ID: z.string().optional(),
  LANGFUSE_S3_EVENT_UPLOAD_SECRET_ACCESS_KEY: z.string().optional(),
  LANGFUSE_S3_EVENT_UPLOAD_FORCE_PATH_STYLE: z
    .enum(["true", "false"])
    .default("false"),
  LANGFUSE_S3_EVENT_UPLOAD_SSE: z.enum(["AES256", "aws:kms"]).optional(),
  LANGFUSE_S3_EVENT_UPLOAD_SSE_KMS_KEY_ID: z.string().optional(),
  LANGFUSE_S3_EVENT_KEY_MAX_SEGMENT_BYTES:
    langfuseS3EventKeyMaxSegmentBytesSchema,
  LANGFUSE_OTEL_MEDIA_UPLOAD_CONCURRENCY: z.coerce
    .number()
    .int()
    .positive()
    .default(100),
  LANGFUSE_OTEL_MEDIA_UPLOAD_MAX_BYTES: z.coerce
    .number()
    .int()
    .positive()
    .default(128 * 1024 * 1024),
  LANGFUSE_S3_MEDIA_UPLOAD_BUCKET: z.string().optional(),
  LANGFUSE_S3_MEDIA_UPLOAD_PREFIX: z.string().default(""),
  LANGFUSE_S3_MEDIA_UPLOAD_REGION: z.string().optional(),
  LANGFUSE_S3_MEDIA_UPLOAD_ENDPOINT: z.string().optional(),
  LANGFUSE_S3_MEDIA_UPLOAD_INTERNAL_ENDPOINT: z.string().optional(),
  LANGFUSE_S3_MEDIA_UPLOAD_ACCESS_KEY_ID: z.string().optional(),
  LANGFUSE_S3_MEDIA_UPLOAD_SECRET_ACCESS_KEY: z.string().optional(),
  LANGFUSE_S3_MEDIA_UPLOAD_FORCE_PATH_STYLE: z
    .enum(["true", "false"])
    .default("false"),
  LANGFUSE_S3_MEDIA_UPLOAD_SSE: z.enum(["AES256", "aws:kms"]).optional(),
  LANGFUSE_S3_MEDIA_UPLOAD_SSE_KMS_KEY_ID: z.string().optional(),
  LANGFUSE_S3_MEDIA_UPLOAD_REQUEST_TIMEOUT_MS: z.coerce
    .number()
    .int()
    .positive()
    .default(30_000),
  LANGFUSE_USE_AZURE_BLOB: z.enum(["true", "false"]).default("false"),
  LANGFUSE_AZURE_SKIP_CONTAINER_CHECK: z
    .enum(["true", "false"])
    .default("true"),
  LANGFUSE_USE_GOOGLE_CLOUD_STORAGE: z.enum(["true", "false"]).default("false"),
  LANGFUSE_GOOGLE_CLOUD_STORAGE_CREDENTIALS: z.string().optional(),
  GOOGLE_CLOUD_UNIVERSE_DOMAIN: z.string().default("googleapis.com"),
  LANGFUSE_USE_OCI_NATIVE_OBJECT_STORAGE: z
    .enum(["true", "false"])
    .default("false"),
  LANGFUSE_OCI_AUTH_TYPE: z
    .enum([
      "workload_identity",
      "instance_principal",
      "resource_principal",
      "oci_profile",
      "session_token",
    ])
    .optional(),
  LANGFUSE_OCI_CONFIG_FILE: z.string().optional(),
  LANGFUSE_OCI_CONFIG_PROFILE: z.string().optional(),
  NODE_EXTRA_CA_CERTS: z.string().optional(),
  STRIPE_SECRET_KEY: z.string().optional(),

  LANGFUSE_ENABLE_BLOB_STORAGE_FILE_LOG: z
    .enum(["true", "false"])
    .default("true"),
  // Max concurrent S3 deleteFiles requests the blob-storage cleanup consumer
  // keeps in flight. Bounds memory and backpressures the ClickHouse ref stream.
  LANGFUSE_BLOB_STORAGE_DELETE_S3_CONCURRENCY: z.coerce
    .number()
    .min(1)
    .max(20)
    .default(5),

  // V4 write mode. Mirrors worker/src/env.ts so the web package can gate
  // public API routes that rely on the legacy traces/observations tables.
  // The worker owns the writes; the web only needs to know whether legacy
  // tables are still being populated to decide whether to serve reads.
  // Defaults to `events_only` for the v4 target state (v3 shipped `legacy`);
  // keep this value in sync with worker/src/env.ts and web/src/env.mjs.
  LANGFUSE_MIGRATION_V4_WRITE_MODE: z
    .enum(["legacy", "dual", "events_only"])
    .default("events_only"),

  LANGFUSE_S3_LIST_MAX_KEYS: z.coerce.number().positive().default(200),
  // Checksum algorithm for S3 DeleteObjects requests; unset keeps the SDK
  // default (CRC32). Some S3-compatible stores reject CRC32 with 400
  // MissingContentMD5 and need "MD5" (sent as the legacy Content-MD5 header),
  // e.g. MinIO before RELEASE.2025-02-03 (langfuse/langfuse-k8s#356). MD5 is
  // unavailable on FIPS runtimes; stores that support it also accept e.g.
  // SHA256 as a FIPS-approved alternative.
  LANGFUSE_S3_DELETE_OBJECTS_CHECKSUM_ALGORITHM: z
    .enum(["MD5", "CRC32", "CRC32C", "CRC64NVME", "SHA1", "SHA256"])
    .optional(),
  LANGFUSE_S3_RATE_ERROR_SLOWDOWN_ENABLED: z
    .enum(["true", "false"])
    .default("false"),
  LANGFUSE_S3_RATE_ERROR_SLOWDOWN_TTL_SECONDS: z.coerce
    .number()
    .positive()
    .default(3600), // 1 hour
  LANGFUSE_INGEST_FAILURE_PROJECT_TTL_SECONDS: z.coerce
    .number()
    .int()
    .gt(60)
    .default(600), // 10 minutes
  LANGFUSE_S3_CORE_DATA_EXPORT_IS_ENABLED: z
    .enum(["true", "false"])
    .default("false"),
  LANGFUSE_S3_CORE_DATA_EXPORT_SSE: z.enum(["AES256", "aws:kms"]).optional(),
  LANGFUSE_S3_CORE_DATA_EXPORT_SSE_KMS_KEY_ID: z.string().optional(),
  LANGFUSE_POSTGRES_METERING_DATA_EXPORT_IS_ENABLED: z
    .enum(["true", "false"])
    .default("false"),

  LANGFUSE_CUSTOM_SSO_EMAIL_CLAIM: z.string().default("email"),
  LANGFUSE_CUSTOM_SSO_NAME_CLAIM: z.string().default("name"),
  LANGFUSE_CUSTOM_SSO_SUB_CLAIM: z.string().default("sub"),
  LANGFUSE_CUSTOM_SSO_IMAGE_CLAIM: z.string().default("picture"),
  LANGFUSE_API_TRACE_OBSERVATIONS_SIZE_LIMIT_BYTES: z.coerce
    .number()
    .default(80e6), // 80MB
  // How many observations the trace detail view loads (startTime ASC, so the
  // chronological tail is what a bigger trace loses). Also a crash guard: the
  // client builds one node per observation before it renders.
  LANGFUSE_MAX_OBSERVATIONS_PER_TRACE: z.coerce
    .number()
    .int()
    .positive()
    .default(20_000),
  LANGFUSE_CLICKHOUSE_DELETION_TIMEOUT_MS: z.coerce.number().default(600_000), // 10 minutes
  LANGFUSE_CLICKHOUSE_QUERY_MAX_ATTEMPTS: z.coerce.number().default(3), // Maximum attempts for socket hang up errors
  LANGFUSE_SKIP_S3_LIST_FOR_OBSERVATIONS_PROJECT_IDS: z.string().optional(),
  LANGFUSE_INGESTION_PROCESSING_SAMPLED_PROJECTS: z
    .string()
    .optional()
    .transform((val) => {
      try {
        if (!val) return new Map<string, number>();

        const map = new Map<string, number>();
        const parts = val.split(",");

        for (const part of parts) {
          const [projectId, sampleRateStr] = part.split(":");

          if (!projectId || sampleRateStr === undefined) {
            throw new Error(`Invalid format: ${part}`);
          }

          // Validate sample rate is between 0 and 1
          const sampleRate = z.coerce
            .number()
            .min(0)
            .max(1)
            .parse(sampleRateStr);

          map.set(projectId, sampleRate);
        }

        return map;
      } catch {
        return new Map<string, number>();
      }
    }),
  LANGFUSE_WEBHOOK_WHITELISTED_IPS: z
    .string()
    .optional()
    .transform((s) =>
      s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
    ),
  LANGFUSE_WEBHOOK_WHITELISTED_IP_SEGMENTS: z
    .string()
    .optional()
    .transform((s) =>
      s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
    ),
  LANGFUSE_WEBHOOK_WHITELISTED_HOST: z
    .string()
    .optional()
    .transform((s) =>
      s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
    ),
  // When non-empty, webhook URLs must use one of these hosts. Distinct from
  // LANGFUSE_WEBHOOK_WHITELISTED_HOST, which only exempts a host from the
  // private-address block. Does not apply to other callers of that exemption
  // list. Entries are exact hostnames (no scheme or port; IPv6 in brackets).
  LANGFUSE_WEBHOOK_ALLOWED_HOSTS: optionalCommaSeparatedLowercase,
  LANGFUSE_LLM_CONNECTION_WHITELISTED_IPS: z
    .string()
    .optional()
    .transform((s) =>
      s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
    ),
  LANGFUSE_LLM_CONNECTION_WHITELISTED_IP_SEGMENTS: z
    .string()
    .optional()
    .transform((s) =>
      s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
    ),
  LANGFUSE_LLM_CONNECTION_WHITELISTED_HOST: z
    .string()
    .optional()
    .transform((s) =>
      s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
    ),
  // When non-empty, every outbound LLM request must use one of these hosts,
  // including provider default hosts and Langfuse AI. Bedrock checks
  // bedrock-runtime.<region>.<partition>, or the host of
  // AWS_ENDPOINT_URL_BEDROCK_RUNTIME / AWS_ENDPOINT_URL when one of those is
  // set. Ignored on Langfuse Cloud, same as the LLM exemption list above.
  LANGFUSE_LLM_CONNECTION_ALLOWED_HOSTS: optionalCommaSeparatedLowercase,
  LANGFUSE_BLOB_STORAGE_ENDPOINT_WHITELISTED_IPS: z
    .string()
    .optional()
    .transform((s) =>
      s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
    ),
  LANGFUSE_BLOB_STORAGE_ENDPOINT_WHITELISTED_IP_SEGMENTS: z
    .string()
    .optional()
    .transform((s) =>
      s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
    ),
  LANGFUSE_BLOB_STORAGE_ENDPOINT_WHITELISTED_HOST: z
    .string()
    .optional()
    .transform((s) =>
      s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
    ),
  // When non-empty, blob storage export endpoints must use one of these hosts,
  // and blob endpoint validation is on. Listed hosts may resolve to private
  // addresses. Bucket names under a listed host ({bucket}.{host}) are allowed
  // too, but still may not resolve to a private address unless it is in
  // LANGFUSE_BLOB_STORAGE_ENDPOINT_WHITELISTED_IPS / _IP_SEGMENTS; private
  // S3-compatible stores can use path-style instead. S3 exports without a
  // custom endpoint connect to s3.<region>.amazonaws.com, which must then be
  // listed; region "auto" first connects to s3.us-east-1.amazonaws.com. S3
  // exports using host credentials (web identity or an assumed role) also
  // call sts.<region>.amazonaws.com through the same check, so list it too.
  // GCS exports always connect to Google and are not checked. Ignored on
  // Langfuse Cloud.
  LANGFUSE_BLOB_STORAGE_ENDPOINT_ALLOWED_HOSTS: optionalCommaSeparatedLowercase,
  LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_IPS: z
    .string()
    .optional()
    .transform((s) =>
      s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
    ),
  LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_IP_SEGMENTS: z
    .string()
    .optional()
    .transform((s) =>
      s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
    ),
  LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_WHITELISTED_HOST: z
    .string()
    .optional()
    .transform((s) =>
      s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
    ),
  // When non-empty, external media storage endpoints must use one of these
  // hosts. Ignored on Langfuse Cloud.
  LANGFUSE_EXTERNAL_MEDIA_STORAGE_ENDPOINT_ALLOWED_HOSTS:
    optionalCommaSeparatedLowercase,
  // Buckets that keyless GOOGLE_CLOUD_STORAGE blob exports (default credentials,
  // no service account key) may write to. Those run as the deployment's own GCP
  // identity (ADC), so without this allowlist any project owner could export into
  // any bucket that identity can write. Empty disables keyless GCS exports;
  // exports with a service account key are unaffected.
  LANGFUSE_BLOB_STORAGE_GCS_ALLOWED_BUCKETS: z
    .string()
    .optional()
    .transform((s) =>
      s
        ? s
            .split(",")
            .map((s) => s.toLowerCase().trim())
            .filter(Boolean)
        : [],
    ),
  LANGFUSE_SSO_DISCOVERY_WHITELISTED_IPS: z
    .string()
    .optional()
    .transform((s) =>
      s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
    ),
  LANGFUSE_SSO_DISCOVERY_WHITELISTED_IP_SEGMENTS: z
    .string()
    .optional()
    .transform((s) =>
      s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
    ),
  LANGFUSE_SSO_DISCOVERY_WHITELISTED_HOST: z
    .string()
    .optional()
    .transform((s) =>
      s ? s.split(",").map((s) => s.toLowerCase().trim()) : [],
    ),
  // Extra CIDR ranges merged into the private-address block for outbound URL
  // checks that already run. Blob storage stays opt-in: these ranges apply
  // there only when a blob endpoint exemption or allowed-hosts list turns
  // blob endpoint validation on. Exemptions
  // in the per-surface *_WHITELISTED_* lists still win.
  LANGFUSE_OUTBOUND_BLOCKED_IP_SEGMENTS: optionalCommaSeparatedLowercase.refine(
    (segments) => segments.every(isCidr),
    {
      message:
        "LANGFUSE_OUTBOUND_BLOCKED_IP_SEGMENTS must be a comma-separated list of CIDR ranges",
    },
  ),
  SLACK_CLIENT_ID: z.string().optional(),
  SLACK_CLIENT_SECRET: z.string().optional(),
  SLACK_STATE_SECRET: z.string().optional(),
  SLACK_PAGE_SIZE: z.coerce
    .number()
    .positive()
    .int()
    .max(1000)
    .optional()
    .default(1000) // Use high default to minimize number of API calls and hence avoid rate limits
    .describe("Number of channels to fetch per Slack API page"),
  HTTPS_PROXY: z.string().optional(),
  // Hosts that must be reached directly instead of through HTTPS_PROXY,
  // using the standard NO_PROXY grammar (undici EnvHttpProxyAgent
  // semantics). The lowercase variant wins when both are set, mirroring
  // undici and curl.
  NO_PROXY: z.string().optional(),
  no_proxy: z.string().optional(),

  LANGFUSE_SERVER_SIDE_IO_CHAR_LIMIT: z.coerce
    .number()
    .int()
    .positive()
    .default(1_000),

  LANGFUSE_CLICKHOUSE_DATA_EXPORT_REQUEST_TIMEOUT_MS: z.coerce
    .number()
    .int()
    .positive()
    .default(3_600_000), // 60 minutes

  LANGFUSE_FETCH_LLM_COMPLETION_TIMEOUT_MS: z.coerce
    .number()
    .int()
    .positive()
    .default(DEFAULT_LLM_COMPLETION_TIMEOUT_MS), // 2 minutes

  // LANGFUSE_AI_PROVIDER is optional at boot. Unset means unconfigured;
  // bedrock requires LANGFUSE_AI_PROVIDER=bedrock.
  // LANGFUSE_AI_MODEL / LANGFUSE_AI_SMALL_MODEL / LANGFUSE_AI_AWS_BEDROCK_REGION
  // apply to all providers. LANGFUSE_AI_API_KEY / LANGFUSE_AI_BASE_URL /
  // LANGFUSE_AI_EXTRA_HEADERS apply to anthropic and openai.
  // LANGFUSE_AI_USE_RESPONSES_API applies to openai only.
  // LANGFUSE_AI_VERTEX_LOCATION applies to vertex only; like bedrock, vertex
  // authenticates through the instance credential chain (GCP application
  // default credentials) and takes no key.
  LANGFUSE_AI_PROVIDER: z
    .enum(["bedrock", "anthropic", "openai", "vertex"])
    .optional(),
  LANGFUSE_AI_MODEL: z.string().optional(),
  LANGFUSE_AI_SMALL_MODEL: z.string().optional(),
  LANGFUSE_AI_API_KEY: z.string().optional(),
  LANGFUSE_AI_BASE_URL: z.string().optional(),
  LANGFUSE_AI_USE_RESPONSES_API: z.enum(["true", "false"]).optional(),
  LANGFUSE_AI_EXTRA_HEADERS: z
    .string()
    .optional()
    .refine(
      (value) => {
        if (value == null || value.trim() === "") {
          return true;
        }

        try {
          z.record(z.string(), z.string()).parse(JSON.parse(value));
          return true;
        } catch {
          return false;
        }
      },
      {
        message:
          "LANGFUSE_AI_EXTRA_HEADERS must be a JSON object of string header names and values",
      },
    ),
  LANGFUSE_AI_AWS_BEDROCK_REGION: z.string().optional(),
  // Cloud runtime credentials require an operator-provisioned connection.
  LANGFUSE_BEDROCK_LLM_CONNECTION_RUNTIME_CREDENTIALS_ALLOWED_PROJECT_IDS: z
    .string()
    .default("")
    .transform((value) =>
      value
        .split(",")
        .map((id) => id.trim())
        .filter(Boolean),
    ),
  // Local AI credentials; production normally uses the AWS role chain.
  AWS_PROFILE: z.string().optional(),
  LANGFUSE_AI_FEATURES_AWS_PROFILE: z.string().optional(),
  // Legacy local profile alias.
  LANGFUSE_IN_APP_AGENT_AWS_PROFILE: z.string().optional(),
  LANGFUSE_AI_VERTEX_LOCATION: z.string().optional(),
  LANGFUSE_IN_APP_AGENT_ENABLED: z.enum(["true", "false"]).optional(),
  LANGFUSE_EVALUATOR_MEDIA_TRANSPORT: z
    .enum(["url", "inline", "disabled"])
    .optional(),
  LANGFUSE_EVALUATOR_MEDIA_INLINE_MAX_BYTES: z.coerce
    .number()
    .int()
    .positive()
    .default(20_000_000),

  // API Performance Flags
  // Whether to add a `FINAL` modifier to the observations CTE in GET /api/public/traces.
  // Can be used to improve performance for self-hosters that are fully on the new OTel SDKs.
  LANGFUSE_API_CLICKHOUSE_DISABLE_OBSERVATIONS_FINAL: z
    .enum(["true", "false"])
    .default("false"),
  // Enable Redis-based tracking of projects using OTEL API to optimize ClickHouse queries.
  // When enabled, projects ingesting via OTEL API skip the FINAL modifier on some observations queries for better performance.
  LANGFUSE_SKIP_FINAL_FOR_OTEL_PROJECTS: z
    .enum(["true", "false"])
    .default("false"),
  // Comma-separated project ids whose scores are never updated after ingestion.
  // Reads of the scores table skip deduplication (FINAL / LIMIT 1 BY) for them.
  LANGFUSE_SKIP_SCORES_DEDUP_PROJECT_IDS: z
    .string()
    .default("")
    .transform(
      (value) =>
        new Set(
          value
            .split(",")
            .map((id) => id.trim())
            .filter(Boolean),
        ),
    ),

  // Langfuse AI Features
  LANGFUSE_AI_FEATURES_PUBLIC_KEY: z.string().optional(),
  LANGFUSE_AI_FEATURES_SECRET_KEY: z.string().optional(),
  LANGFUSE_AI_FEATURES_HOST: z.string().optional(),
  LANGFUSE_AI_FEATURES_PROJECT_ID: z.string().optional(),

  // Dataset Service
  LANGFUSE_DATASET_SERVICE_WRITE_TO_VERSIONED_IMPLEMENTATION: z
    .enum(["true", "false"])
    .default("true"),
  LANGFUSE_DATASET_SERVICE_READ_FROM_VERSIONED_IMPLEMENTATION: z
    .enum(["true", "false"])
    .default("true"),

  // API ClickHouse query options
  LANGFUSE_API_CLICKHOUSE_PROPAGATE_OBSERVATIONS_TIME_BOUNDS: z
    .enum(["true", "false"])
    .default("false"),

  // EE License
  LANGFUSE_EE_LICENSE_KEY: z.string().optional(),

  // FIPS mode (EE feature): refuse to start without an enterprise license or
  // an active OpenSSL FIPS provider. See server/ee/fips.
  LANGFUSE_REQUIRE_FIPS: z.enum(["true", "false"]).default("false"),

  // Ingestion Masking (EE feature)
  LANGFUSE_INGESTION_MASKING_CALLBACK_URL: z.url().optional(),
  LANGFUSE_INGESTION_MASKING_CALLBACK_TIMEOUT_MS: z.coerce
    .number()
    .positive()
    .default(500),
  LANGFUSE_INGESTION_MASKING_CALLBACK_FAIL_CLOSED: z
    .enum(["true", "false"])
    .default("false"),
  LANGFUSE_INGESTION_MASKING_MAX_RETRIES: z.coerce
    .number()
    .nonnegative()
    .default(1),
  LANGFUSE_INGESTION_MASKING_PROPAGATED_HEADERS: z
    .string()
    .optional()
    .transform((s) =>
      s ? s.split(",").map((h) => h.toLowerCase().trim()) : [],
    ),
});

export type SharedEnv = z.infer<typeof EnvSchema>;

export const env: SharedEnv =
  process.env.DOCKER_BUILD === "1" // eslint-disable-line turbo/no-undeclared-env-vars
    ? (process.env as any)
    : EnvSchema.parse(removeEmptyEnvVariables(process.env));