Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
16.6 KB
Raw Blame
/**
 * gfs-controller (gfsc) configuration.
 *
 * Required values FAIL LOUD in production — there is no silent default that
 * would let gfsc start against a misconfigured deployment. Dev mode relaxes the
 * requirements for local runs and unit tests only.
 *
 * gfsc mounts the drive PVC (writer RW, readers RO) and serves a brokered HTTP
 * file API; every other actor reaches the drive over this API, never by
 * mounting the volume. The Postgres connection points at the permission store,
 * which is the source of truth for authorization (re-checked on every op).
 */
import {
  GFS_UPLOAD_V2_DEFAULT_CONCURRENCY,
  GFS_UPLOAD_V2_FALLBACK_CONCURRENCY,
  GFS_UPLOAD_V2_INSTABILITY_FAILURE_THRESHOLD,
  GFS_UPLOAD_V2_MAX_PART_BYTES,
  GFS_UPLOAD_V2_MIN_PART_BYTES,
  GFS_UPLOAD_V2_PART_TIMEOUT_MS,
  GFS_UPLOAD_V2_FINALIZE_TIMEOUT_MS,
  GFS_UPLOAD_V2_STALE_PART_LEASE_MS,
  GFS_UPLOAD_V2_PREFERRED_PART_BYTES,
  GFS_UPLOAD_V2_DEFAULT_PRODUCT_MAX_BYTES,
  GFS_UPLOAD_V2_PROTOCOL_MAX_BYTES,
  GFS_UPLOAD_V2_SESSION_TTL_SECONDS,
} from './upload/protocol'

export interface GfsUploadConfig {
  /** Product policy; never raised by changing the protocol ceiling alone. */
  productMaxFileBytes: number
  /** Arithmetic/test ceiling; not a public capability. */
  protocolMaxFileBytes: number
  preferredPartBytes: number
  maxPartBytes: number
  maxPartCount: number
  maxConcurrentPartsPerSession: number
  maxConcurrentPartStreamsGlobal: number
  maxActivePerSubject: number
  maxActiveGlobal: number
  maxConcurrentFinalizations: number
  minFreeBytes: number
  instabilityFailureThreshold: number
  fallbackConcurrency: number
  sessionTtlSeconds: number
  partTimeoutMs: number
  finalizeTimeoutMs: number
  stalePartLeaseMs: number
  receiptRetentionSeconds: number
  enabled: boolean
}

export interface GfsConfig {
  port: number
  /** Path where the drive PVC is mounted (writer RW, readers RO). */
  storageMountPath: string
  /** 'writer' mounts the volume RW (single replica); 'reader' mounts it RO. */
  storageRole: 'writer' | 'reader'
  /** Postgres connection string for the permission store (source of truth). */
  pgConnectionString: string
  /** Expected `aud` on inbound gfs access tokens. */
  tokenAudience: string
  /** RS256 public key (PEM) used to verify gfs access tokens (wired in P1-S06). */
  publicKey: string
  /** Drive this gfsc serves — a cluster singleton named 'main' in the open core. */
  driveName: string
  /**
   * TTL (ms) for the short-lived authorization decision cache. Bounded so that
   * even with NO invalidation signal a revocation takes effect within this
   * window; the LISTEN/NOTIFY fan-out makes revocation immediate in the healthy
   * path. A tuning knob, not a fail-loud requirement (has a safe default).
   */
  decisionCacheTtlMs: number
  /**
   * Cadence (ms) of the fresh-connection credential probe inside readiness
   * (issue #775): at most one NEW database connection per interval verifies
   * that the DSN still authenticates and the role keeps its grants — the pool
   * alone cannot see a rotated password. Tuning knob with a safe default;
   * garbage values fail loud.
   */
  credentialProbeIntervalMs: number
  blobCleanupSafetyWindowMs: number
  blobCleanupIntervalMs: number
  blobCleanupBatchSize: number
  /** Per-subject agent (host principal) read budget per minute, per replica. */
  agentReadRlPerMinPerReplica: number
  /** Per-subject agent (host principal) write budget per minute, per replica. */
  agentWriteRlPerMinPerReplica: number
  /** Maximum source objects admitted by one synchronous Copy request. */
  syncCopyMaxObjects: number
  /** Maximum observed source bytes admitted by one synchronous Copy request. */
  syncCopyMaxBytes: number
  /** End-to-end deadline for one synchronous Copy request. */
  syncCopyTimeoutMs: number
  /** Maximum live subtree objects admitted by one synchronous rename request. */
  syncRenameMaxObjects: number
  /** End-to-end deadline for one synchronous rename request. */
  syncRenameTimeoutMs: number
  uploadV2: GfsUploadConfig
  devMode: boolean
}

function required(name: string, devMode: boolean, devDefault?: string): string {
  const value = process.env[name]
  if (value !== undefined && value !== '') return value
  if (devMode && devDefault !== undefined) return devDefault
  throw new Error(`[gfsc] required environment variable ${name} is not set`)
}

function tuningMs(name: string, defaultMs: number): number {
  const raw = process.env[name]
  if (raw === undefined || raw === '') return defaultMs
  const value = Number(raw)
  if (!Number.isFinite(value) || value <= 0) {
    throw new Error(`[gfsc] ${name} must be a positive number of milliseconds, got: ${raw}`)
  }
  return value
}

export const AGENT_READ_RL_PER_MIN_DEFAULT = 300
export const AGENT_WRITE_RL_PER_MIN_DEFAULT = 120
/** 1000 requests per second per replica; a larger value is a typo, not a budget. */
export const AGENT_RL_PER_MIN_MAX = 60000

function positiveInteger(name: string, defaultValue: number, maximum: number): number {
  const raw = process.env[name]
  if (raw === undefined || raw === '') return defaultValue
  const value = Number(raw)
  if (!Number.isSafeInteger(value) || value <= 0 || value > maximum) {
    throw new Error(`[gfsc] ${name} must be an integer between 1 and ${maximum}, got: ${raw}`)
  }
  return value
}

/**
 * Canonical positive decimal, optionally bounded. Only an absent variable
 * selects the documented default; an explicitly empty or non-canonical value
 * (`0x10`, `1e3`, ` 45 `, `45.0`, `045`, `+45`) fails startup instead of
 * falling back. Copy admission limits pass no maximum: they intentionally have
 * no compiled product ceiling.
 */
function strictPositiveInteger(name: string, defaultValue: number, maximum?: number): number {
  const raw = process.env[name]
  if (raw === undefined) return defaultValue
  const value = /^[1-9]\d*$/.test(raw) ? Number(raw) : Number.NaN
  if (maximum !== undefined) {
    if (!Number.isSafeInteger(value) || value > maximum) {
      throw new Error(`[gfsc] ${name} must be an integer between 1 and ${maximum}, got: ${JSON.stringify(raw)}`)
    }
    return value
  }
  if (!Number.isSafeInteger(value)) {
    throw new Error(`[gfsc] ${name} must be a positive safe integer, got: ${JSON.stringify(raw)}`)
  }
  return value
}

function storageRole(): GfsConfig['storageRole'] {
  const value = process.env.GFS_STORAGE_ROLE
  if (value === 'reader' || value === 'writer') return value
  throw new Error(`[gfsc] GFS_STORAGE_ROLE must be explicitly set to 'reader' or 'writer', got: ${JSON.stringify(value)}`)
}

function strictBoolean(name: string, defaultValue: boolean): boolean {
  const raw = process.env[name]
  if (raw === undefined) return defaultValue
  if (raw === 'true') return true
  if (raw === 'false') return false
  throw new Error(`[gfsc] ${name} must be exactly 'true' or 'false', got: ${JSON.stringify(raw)}`)
}

function uploadInteger(name: string, defaultValue: number, min: number, max: number): number {
  const raw = process.env[name]
  if (raw === undefined) return defaultValue
  if (!/^[0-9]+$/.test(raw)) {
    throw new Error(`[gfsc] ${name} must be an integer from ${min} through ${max}, got: ${JSON.stringify(raw)}`)
  }
  const value = Number(raw)
  if (!Number.isSafeInteger(value) || value < min || value > max) {
    throw new Error(`[gfsc] ${name} must be an integer from ${min} through ${max}, got: ${raw}`)
  }
  return value
}

function requireCanonicalUploadInteger(name: string): void {
  const raw = process.env[name]
  if (raw !== undefined && !/^(?:0|[1-9][0-9]*)$/.test(raw)) {
    throw new Error(`[gfsc] ${name} must use canonical unsigned decimal integer syntax`)
  }
}

function uploadDurationMs(name: string, defaultValue: number, max: number): number {
  const raw = process.env[name]
  if (raw === undefined) return defaultValue
  if (!/^[0-9]+$/.test(raw)) throw new Error(`[gfsc] ${name} must be a positive integer number of milliseconds`)
  const value = Number(raw)
  if (!Number.isSafeInteger(value) || value <= 0 || value > max) {
    throw new Error(`[gfsc] ${name} must be a positive integer number of milliseconds`)
  }
  return value
}

function uploadDurationMsWithAlias(
  canonicalName: string,
  aliasName: string,
  defaultValue: number,
  max: number,
  aliasMultiplier: number,
): number {
  const canonicalRaw = process.env[canonicalName]
  const aliasRaw = process.env[aliasName]
  const canonical = canonicalRaw === undefined
    ? undefined
    : uploadDurationMs(canonicalName, defaultValue, max)
  const alias = aliasRaw === undefined
    ? undefined
    : uploadInteger(aliasName, Math.round(defaultValue / aliasMultiplier), 1, Math.floor(max / aliasMultiplier)) * aliasMultiplier
  if (canonical !== undefined && alias !== undefined && canonical !== alias) {
    throw new Error(`[gfsc] ${canonicalName} and deprecated ${aliasName} must match`)
  }
  return canonical ?? alias ?? defaultValue
}

function uploadIntegerWithAlias(
  canonicalName: string,
  aliasName: string,
  defaultValue: number,
  min: number,
  max: number,
): number {
  const canonicalRaw = process.env[canonicalName]
  const aliasRaw = process.env[aliasName]
  // Report a conflicting pair before validating the individual range. This
  // keeps the deprecated alias contract explicit even when one side is just
  // outside the canonical range (for example, an old 199 MiB value).
  if (canonicalRaw !== undefined && aliasRaw !== undefined) {
    const canonicalNumber = Number(canonicalRaw)
    const aliasNumber = Number(aliasRaw)
    if (Number.isFinite(canonicalNumber) && Number.isFinite(aliasNumber) && canonicalNumber !== aliasNumber) {
      throw new Error(`[gfsc] ${canonicalName} and deprecated ${aliasName} must match`)
    }
  }
  const canonical = process.env[canonicalName] === undefined
    ? undefined
    : uploadInteger(canonicalName, defaultValue, min, max)
  const alias = process.env[aliasName] === undefined
    ? undefined
    : uploadInteger(aliasName, defaultValue, min, max)
  if (canonical !== undefined && alias !== undefined && canonical !== alias) {
    throw new Error(`[gfsc] ${canonicalName} and deprecated ${aliasName} must match`)
  }
  return canonical ?? alias ?? defaultValue
}

function uploadConfig(): GfsUploadConfig {
  const enabled = strictBoolean('GFS_UPLOAD_V2_ENABLED', false)
  const protocolMaxFileBytes = uploadInteger(
    'GFS_UPLOAD_PROTOCOL_MAX_FILE_BYTES',
    GFS_UPLOAD_V2_PROTOCOL_MAX_BYTES,
    GFS_UPLOAD_V2_DEFAULT_PRODUCT_MAX_BYTES,
    GFS_UPLOAD_V2_PROTOCOL_MAX_BYTES
  )
  requireCanonicalUploadInteger('GFS_UPLOAD_PROTOCOL_MAX_FILE_BYTES')
  requireCanonicalUploadInteger('GFS_UPLOAD_PRODUCT_MAX_FILE_BYTES')
  requireCanonicalUploadInteger('GFS_UPLOAD_MAX_FILE_BYTES')
  const productMaxFileBytes = uploadIntegerWithAlias(
    'GFS_UPLOAD_PRODUCT_MAX_FILE_BYTES',
    'GFS_UPLOAD_MAX_FILE_BYTES',
    GFS_UPLOAD_V2_DEFAULT_PRODUCT_MAX_BYTES,
    1,
    protocolMaxFileBytes
  )
  const preferredPartBytes = uploadIntegerWithAlias(
    'GFS_UPLOAD_PREFERRED_CHUNK_BYTES',
    'GFS_UPLOAD_PREFERRED_PART_BYTES',
    GFS_UPLOAD_V2_PREFERRED_PART_BYTES,
    GFS_UPLOAD_V2_MIN_PART_BYTES,
    GFS_UPLOAD_V2_MAX_PART_BYTES
  )
  const maxPartBytes = uploadIntegerWithAlias(
    'GFS_UPLOAD_MAX_CHUNK_BYTES',
    'GFS_UPLOAD_MAX_PART_BYTES',
    GFS_UPLOAD_V2_MAX_PART_BYTES,
    GFS_UPLOAD_V2_MIN_PART_BYTES,
    GFS_UPLOAD_V2_MAX_PART_BYTES
  )
  if (preferredPartBytes > maxPartBytes) {
    throw new Error(
      `[gfsc] GFS_UPLOAD_PREFERRED_CHUNK_BYTES cannot exceed GFS_UPLOAD_MAX_CHUNK_BYTES (${preferredPartBytes} > ${maxPartBytes})`
    )
  }
  const minPartBytes = uploadInteger(
    'GFS_UPLOAD_MIN_PART_BYTES',
    GFS_UPLOAD_V2_MIN_PART_BYTES,
    GFS_UPLOAD_V2_MIN_PART_BYTES,
    maxPartBytes,
  )
  if (minPartBytes > maxPartBytes) {
    throw new Error(`[gfsc] GFS_UPLOAD_MIN_PART_BYTES cannot exceed GFS_UPLOAD_MAX_CHUNK_BYTES`)
  }
  if (preferredPartBytes < minPartBytes) {
    throw new Error(`[gfsc] GFS_UPLOAD_PREFERRED_CHUNK_BYTES cannot be below GFS_UPLOAD_MIN_PART_BYTES`)
  }
  const maxPartCount = uploadInteger('GFS_UPLOAD_MAX_PART_COUNT', 1024, 1, 1024)
  const maxConcurrentPartsPerSession = uploadInteger(
    'GFS_UPLOAD_MAX_CONCURRENT_PARTS_PER_SESSION',
    GFS_UPLOAD_V2_DEFAULT_CONCURRENCY,
    1,
    GFS_UPLOAD_V2_DEFAULT_CONCURRENCY
  )
  const fallbackConcurrency = uploadInteger(
    'GFS_UPLOAD_FALLBACK_CONCURRENCY',
    GFS_UPLOAD_V2_FALLBACK_CONCURRENCY,
    1,
    GFS_UPLOAD_V2_DEFAULT_CONCURRENCY
  )
  if (fallbackConcurrency >= maxConcurrentPartsPerSession) {
    throw new Error(
      `[gfsc] GFS_UPLOAD_FALLBACK_CONCURRENCY must be lower than GFS_UPLOAD_MAX_CONCURRENT_PARTS_PER_SESSION`
    )
  }
  const maxConcurrentPartStreamsGlobal = uploadInteger(
    'GFS_UPLOAD_MAX_CONCURRENT_PART_STREAMS_GLOBAL',
    16,
    1,
    1024
  )
  const maxActivePerSubject = uploadInteger('GFS_UPLOAD_MAX_ACTIVE_PER_SUBJECT', 2, 1, 100)
  const maxActiveGlobal = uploadInteger('GFS_UPLOAD_MAX_ACTIVE_GLOBAL', 8, 1, 1000)
  const maxConcurrentFinalizations = uploadInteger('GFS_UPLOAD_MAX_CONCURRENT_FINALIZATIONS', 1, 1, 100)
  const minFreeBytes = uploadInteger('GFS_UPLOAD_MIN_FREE_BYTES', 10 * 1024 * 1024 * 1024, 0, Number.MAX_SAFE_INTEGER)
  const instabilityFailureThreshold = uploadInteger(
    'GFS_UPLOAD_INSTABILITY_FAILURE_THRESHOLD',
    GFS_UPLOAD_V2_INSTABILITY_FAILURE_THRESHOLD,
    1,
    100
  )
  const sessionTtlMs = uploadDurationMsWithAlias(
    'GFS_UPLOAD_SESSION_TTL_MS',
    'GFS_UPLOAD_SESSION_TTL_SECONDS',
    GFS_UPLOAD_V2_SESSION_TTL_SECONDS * 1000,
    7 * 24 * 60 * 60 * 1000,
    1000,
  )
  const partTimeoutMs = uploadDurationMs('GFS_UPLOAD_PART_TIMEOUT_MS', GFS_UPLOAD_V2_PART_TIMEOUT_MS, 24 * 60 * 60 * 1000)
  const finalizeTimeoutMs = uploadDurationMs('GFS_UPLOAD_FINALIZE_TIMEOUT_MS', GFS_UPLOAD_V2_FINALIZE_TIMEOUT_MS, 24 * 60 * 60 * 1000)
  const stalePartLeaseMs = uploadDurationMs('GFS_UPLOAD_STALE_PART_LEASE_MS', GFS_UPLOAD_V2_STALE_PART_LEASE_MS, 24 * 60 * 60 * 1000)
  if (stalePartLeaseMs <= partTimeoutMs) {
    throw new Error(
      '[gfsc] GFS_UPLOAD_STALE_PART_LEASE_MS must be greater than GFS_UPLOAD_PART_TIMEOUT_MS'
    )
  }
  const receiptRetentionMs = uploadDurationMsWithAlias(
    'GFS_UPLOAD_COMPLETED_RECEIPT_TTL_MS',
    'GFS_UPLOAD_RECEIPT_RETENTION_SECONDS',
    24 * 60 * 60 * 1000,
    7 * 24 * 60 * 60 * 1000,
    1000,
  )
  return {
    productMaxFileBytes,
    protocolMaxFileBytes,
    preferredPartBytes,
    maxPartBytes,
    maxPartCount,
    maxConcurrentPartsPerSession,
    maxConcurrentPartStreamsGlobal,
    maxActivePerSubject,
    maxActiveGlobal,
    maxConcurrentFinalizations,
    minFreeBytes,
    instabilityFailureThreshold,
    fallbackConcurrency,
    sessionTtlSeconds: Math.floor(sessionTtlMs / 1000),
    partTimeoutMs,
    finalizeTimeoutMs,
    stalePartLeaseMs,
    receiptRetentionSeconds: Math.floor(receiptRetentionMs / 1000),
    enabled,
  }
}

export function loadConfig(): GfsConfig {
  const devMode = process.env.GFS_DEV_MODE === 'true'
  return {
    port: Number(process.env.GFS_PORT || 8087),
    storageMountPath: required('GFS_STORAGE_PATH', devMode, '/tmp/gfs-data'),
    storageRole: storageRole(),
    pgConnectionString: required('GFS_PG_CONNECTION_STRING', devMode, ''),
    tokenAudience: process.env.GFS_TOKEN_AUDIENCE || 'gfs-controller',
    publicKey: process.env.GFS_JWT_PUBLIC_KEY || '',
    driveName: process.env.GFS_DRIVE_NAME || 'main',
    decisionCacheTtlMs: Number(process.env.GFS_DECISION_CACHE_TTL_MS || 5000),
    credentialProbeIntervalMs: tuningMs('GFS_CREDENTIAL_PROBE_INTERVAL_MS', 60000),
    blobCleanupSafetyWindowMs: positiveInteger(
      'GFS_BLOB_CLEANUP_SAFETY_WINDOW_MS',
      3600000,
      31536000000
    ),
    blobCleanupIntervalMs: positiveInteger(
      'GFS_BLOB_CLEANUP_INTERVAL_MS',
      60000,
      2147483647
    ),
    blobCleanupBatchSize: positiveInteger('GFS_BLOB_CLEANUP_BATCH_SIZE', 100, 10000),
    // The operator sets both explicitly (host-context-controller gfscEnv); the
    // defaults cover a gfsc image that rolls out before the operator's env.
    agentReadRlPerMinPerReplica: strictPositiveInteger(
      'GFS_AGENT_READ_RL_PER_MIN_PER_REPLICA',
      AGENT_READ_RL_PER_MIN_DEFAULT,
      AGENT_RL_PER_MIN_MAX
    ),
    agentWriteRlPerMinPerReplica: strictPositiveInteger(
      'GFS_AGENT_WRITE_RL_PER_MIN_PER_REPLICA',
      AGENT_WRITE_RL_PER_MIN_DEFAULT,
      AGENT_RL_PER_MIN_MAX
    ),
    syncCopyMaxObjects: strictPositiveInteger('GFS_SYNC_COPY_MAX_OBJECTS', 1000),
    syncCopyMaxBytes: strictPositiveInteger('GFS_SYNC_COPY_MAX_BYTES', 1073741824),
    syncCopyTimeoutMs: strictPositiveInteger('GFS_SYNC_COPY_TIMEOUT_MS', 30000),
    syncRenameMaxObjects: strictPositiveInteger('GFS_SYNC_RENAME_MAX_OBJECTS', 1000),
    syncRenameTimeoutMs: strictPositiveInteger('GFS_SYNC_RENAME_TIMEOUT_MS', 30000),
    uploadV2: uploadConfig(),
    devMode,
  }
}