Skip to content

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

TypeScript
18.6 KB
Raw Blame
import type { DbClient } from '../../../db.js'
import type {
  DailyCostComponent,
  DailyCostKey,
  PeriodCostSelection,
  PersistedDailyCostVersion,
} from '../maintenance/contracts.js'
import { Decimal9 } from '../maintenance/decimal.js'
import { selectPeriodCosts } from '../maintenance/periodSelection.js'

export type InfrastructureCostPeriod = 'day' | 'week' | 'month'
export type InfrastructureCostValuation = 'estimated' | 'billed' | 'variance'
export type InfrastructureCostBasis = 'requested_capacity' | 'gcp_request_allocation'

export type InfrastructureCostDimensions = Omit<DailyCostKey, 'utcDay'>

export interface InfrastructureCostReadQuery {
  period: InfrastructureCostPeriod
  periodStartUtc: string
  periodEndUtc: string
  valuation: InfrastructureCostValuation
  basis: InfrastructureCostBasis
  dimensions: InfrastructureCostDimensions
}

export interface InfrastructureCostReadResponse {
  period: InfrastructureCostPeriod
  periodStartUtc: string
  periodEndUtc: string
  dimensions: InfrastructureCostDimensions
  requestedCapacity: InfrastructureCostSelectionView | null
  gcpRequestAllocation: InfrastructureCostSelectionView | null
  variance?: {
    netAmount: string
    billedBasis: 'gcp_request_allocation'
    estimateBasis: 'requested_capacity'
  }
}

export interface InfrastructureCostScope {
  dimensions: InfrastructureCostDimensions
  firstUtcDay: string
  lastUtcDay: string
  availableValuations: readonly ('estimated' | 'billed')[]
  latestAsOfUtc: string
  billingExportWatermark: string | null
  billingLagHours: number | null
}

export interface InfrastructureCostScopeCatalog {
  scopes: readonly InfrastructureCostScope[]
  truncated: boolean
}

export interface InfrastructureCostSelectionView extends PeriodCostSelection {
  valuationKind: 'estimated' | 'billed'
  selectedBasis: 'requested_capacity' | 'gcp_request_allocation'
  asOfUtc: string
  billingExportWatermark: string | null
  billingLagHours: number | null
  billingFreshnessStatus: 'fresh' | 'stale' | 'unavailable' | 'not_applicable'
  components: readonly DailyCostComponent[]
}

type BillingFreshness = {
  status: 'fresh' | 'stale' | 'unavailable'
  lagHours: number | null
}

type DailyCostRow = {
  id: string
  utc_day: unknown
  cloud_provider: 'gcp'
  cloud_project_id: string
  cluster_location: string
  cluster_name: string
  environment: string
  namespace: string
  workload_kind: string
  workload_ref: string
  valuation_kind: 'estimated' | 'billed'
  selected_basis: 'requested_capacity' | 'gcp_request_allocation'
  currency: string
  rollup_version: number
  predecessor_version: number | null
  publication_state: 'provisional' | 'finalized'
  completeness_status: 'complete' | 'partial' | 'unavailable'
  as_of_utc: unknown
  source_interval_start: unknown | null
  source_interval_end: unknown | null
  billing_export_watermark: unknown | null
  source_count: string | number
  source_sha256: string
  gross_amount: string
  credits_amount: string
  net_amount: string
}

type DailyCostComponentRow = {
  daily_cost_id: string
  component_key: string
  resource_class: DailyCostComponent['resourceClass']
  allocation_bucket: DailyCostComponent['allocationBucket']
  unit_hours: string | null
  price_snapshot_id: string | null
  provider_service: string | null
  provider_sku: string | null
  billing_view_version: string | null
  source_row_count: string | number | null
  source_sha256: string
  billing_export_watermark: unknown | null
  gross_amount: string
  credits_amount: string
  net_amount: string
  price_source_ref: string | null
  price_effective_from: unknown | null
  price_unit_price: string | null
}

type InfrastructureCostScopeRow = {
  cloud_provider: 'gcp'
  cloud_project_id: string
  cluster_location: string
  cluster_name: string
  environment: string
  namespace: string
  workload_kind: string
  workload_ref: string
  currency: string
  first_utc_day: unknown
  last_utc_day: unknown
  has_estimated: boolean
  has_billed: boolean
  latest_as_of_utc: unknown
  billing_export_watermark: unknown | null
  billing_lag_hours: string | number | null
}

const MAX_SCOPE_CATALOG_ENTRIES = 200
const SCOPE_CATALOG_LOOKBACK_DAYS = 90

function toUtcDay(value: unknown): string {
  if (typeof value === 'string') return value.slice(0, 10)
  if (value instanceof Date) return value.toISOString().slice(0, 10)
  throw new Error('unexpected infrastructure cost utc_day value')
}

function toIsoTimestamp(value: unknown): string {
  if (typeof value === 'string') return new Date(value).toISOString()
  if (value instanceof Date) return value.toISOString()
  throw new Error('unexpected infrastructure cost timestamp value')
}

function toNullableIsoTimestamp(value: unknown | null): string | null {
  return value === null ? null : toIsoTimestamp(value)
}

function sourceCount(value: string | number | null): number | null {
  if (value === null) return null
  return typeof value === 'number' ? value : Number(value)
}

function nullableHours(value: string | number | null): number | null {
  if (value === null) return null
  const parsed = typeof value === 'number' ? value : Number(value)
  if (!Number.isFinite(parsed)) throw new Error('unexpected infrastructure cost lag value')
  return Math.max(0, Math.round(parsed * 1000) / 1000)
}

function periodDayCount(periodStartUtc: string, periodEndUtc: string): number {
  const start = Date.parse(`${periodStartUtc}T00:00:00.000Z`)
  const end = Date.parse(`${periodEndUtc}T00:00:00.000Z`)
  return Math.round((end - start) / 86_400_000)
}

function maxIso(values: readonly string[]): string {
  return values.reduce((max, value) => (value > max ? value : max))
}

function latestBillingWatermark(versions: readonly PersistedDailyCostVersion[]): string | null {
  const watermarks = versions
    .map(version => version.billingExportWatermark)
    .filter((value): value is string => value !== null)
  return watermarks.length === 0 ? null : maxIso(watermarks)
}

function toDailyVersion(
  row: DailyCostRow,
  components: readonly DailyCostComponent[]
): PersistedDailyCostVersion {
  return {
    id: row.id,
    rollupVersion: row.rollup_version,
    predecessorVersion: row.predecessor_version,
    key: {
      utcDay: toUtcDay(row.utc_day),
      cloudProvider: row.cloud_provider,
      cloudProjectId: row.cloud_project_id,
      clusterLocation: row.cluster_location,
      clusterName: row.cluster_name,
      environment: row.environment,
      namespace: row.namespace,
      workloadKind: row.workload_kind,
      workloadRef: row.workload_ref,
      currency: row.currency,
    },
    valuationKind: row.valuation_kind,
    selectedBasis: row.selected_basis,
    publicationState: row.publication_state,
    completenessStatus: row.completeness_status,
    asOfUtc: toIsoTimestamp(row.as_of_utc),
    sourceIntervalStart: toNullableIsoTimestamp(row.source_interval_start),
    sourceIntervalEnd: toNullableIsoTimestamp(row.source_interval_end),
    billingExportWatermark: toNullableIsoTimestamp(row.billing_export_watermark),
    sourceCount: sourceCount(row.source_count) ?? 0,
    sourceSha256: row.source_sha256,
    grossAmount: row.gross_amount,
    creditsAmount: row.credits_amount,
    netAmount: row.net_amount,
    components,
  }
}

function toComponent(row: DailyCostComponentRow): DailyCostComponent {
  return {
    componentKey: row.component_key,
    resourceClass: row.resource_class,
    allocationBucket: row.allocation_bucket,
    unitHours: row.unit_hours,
    priceSnapshotId: row.price_snapshot_id,
    providerService: row.provider_service,
    providerSku: row.provider_sku,
    billingViewVersion: row.billing_view_version,
    sourceRowCount: sourceCount(row.source_row_count),
    sourceSha256: row.source_sha256,
    billingExportWatermark: toNullableIsoTimestamp(row.billing_export_watermark),
    grossAmount: row.gross_amount,
    creditsAmount: row.credits_amount,
    netAmount: row.net_amount,
    priceSourceRef: row.price_source_ref,
    priceEffectiveFrom: toNullableIsoTimestamp(row.price_effective_from),
    priceUnitPrice: row.price_unit_price,
  }
}

function selectionView(
  query: InfrastructureCostReadQuery,
  versions: readonly PersistedDailyCostVersion[],
  billingFreshness: BillingFreshness
): InfrastructureCostSelectionView | null {
  if (versions.length === 0) return null
  const selected = selectPeriodCosts(
    query.period,
    query.periodStartUtc,
    query.periodEndUtc,
    versions
  )
  const asOfUtc = maxIso(versions.map(version => version.asOfUtc))
  const billingExportWatermark = latestBillingWatermark(versions)
  return {
    ...selected,
    valuationKind: versions[0]!.valuationKind as 'estimated' | 'billed',
    selectedBasis: versions[0]!.selectedBasis as 'requested_capacity' | 'gcp_request_allocation',
    asOfUtc,
    billingExportWatermark,
    billingLagHours: versions[0]!.valuationKind === 'billed' ? billingFreshness.lagHours : null,
    billingFreshnessStatus:
      versions[0]!.valuationKind === 'billed' ? billingFreshness.status : 'not_applicable',
    components: versions.flatMap(version =>
      version.components.map(component => ({
        ...component,
        componentKey: `${version.key.utcDay}:${component.componentKey}`,
      }))
    ),
  }
}

function completeComparable(
  expectedDays: number,
  requestedCapacity: InfrastructureCostSelectionView | null,
  gcpRequestAllocation: InfrastructureCostSelectionView | null
): boolean {
  return (
    requestedCapacity !== null &&
    gcpRequestAllocation !== null &&
    gcpRequestAllocation.billingFreshnessStatus === 'fresh' &&
    requestedCapacity.completenessStatus === 'complete' &&
    gcpRequestAllocation.completenessStatus === 'complete' &&
    requestedCapacity.dailyVersionVector.length === expectedDays &&
    gcpRequestAllocation.dailyVersionVector.length === expectedDays
  )
}

function varianceNetAmount(
  requestedCapacity: InfrastructureCostSelectionView,
  gcpRequestAllocation: InfrastructureCostSelectionView
): string {
  return Decimal9.parse(gcpRequestAllocation.netAmount)
    .subtract(Decimal9.parse(requestedCapacity.netAmount))
    .toString()
}

export class InfrastructureCostReadService {
  constructor(
    private readonly db: DbClient,
    private readonly maximumBillingLagHours = 96
  ) {}

  private async currentBillingFreshness(
    dimensions: InfrastructureCostDimensions
  ): Promise<BillingFreshness> {
    const result = await this.db.query(
      `
        SELECT MAX(billing_export_watermark) AS billing_export_watermark,
               CASE WHEN MAX(billing_export_watermark) IS NULL THEN NULL
                    ELSE GREATEST(
                      0,
                      EXTRACT(EPOCH FROM (CURRENT_TIMESTAMP - MAX(billing_export_watermark))) / 3600
                    )
                END AS billing_lag_hours
          FROM infrastructure_cost_daily
         WHERE cloud_provider = $1
           AND cloud_project_id = $2
           AND cluster_location = $3
           AND cluster_name = $4
           AND environment = $5
           AND namespace = $6
           AND workload_kind = $7
           AND workload_ref = $8
           AND currency = $9
           AND valuation_kind = 'billed'
           AND selected_basis = 'gcp_request_allocation'
           AND utc_day >= (CURRENT_TIMESTAMP AT TIME ZONE 'UTC')::date - $10::integer
      `,
      [
        dimensions.cloudProvider,
        dimensions.cloudProjectId,
        dimensions.clusterLocation,
        dimensions.clusterName,
        dimensions.environment,
        dimensions.namespace,
        dimensions.workloadKind,
        dimensions.workloadRef,
        dimensions.currency,
        SCOPE_CATALOG_LOOKBACK_DAYS,
      ]
    )
    const row = result.rows[0] as
      | { billing_export_watermark: unknown | null; billing_lag_hours: string | number | null }
      | undefined
    const lagHours = nullableHours(row?.billing_lag_hours ?? null)
    if (!row?.billing_export_watermark || lagHours === null) {
      return { status: 'unavailable', lagHours: null }
    }
    return {
      status: lagHours <= this.maximumBillingLagHours ? 'fresh' : 'stale',
      lagHours,
    }
  }

  async listScopes(): Promise<InfrastructureCostScopeCatalog> {
    const result = await this.db.query(
      `
        SELECT cloud_provider, cloud_project_id, cluster_location, cluster_name,
               environment, namespace, workload_kind, workload_ref, currency,
               MIN(utc_day) AS first_utc_day,
               MAX(utc_day) AS last_utc_day,
               BOOL_OR(valuation_kind = 'estimated') AS has_estimated,
               BOOL_OR(valuation_kind = 'billed') AS has_billed,
               MAX(as_of_utc) AS latest_as_of_utc,
               MAX(billing_export_watermark) AS billing_export_watermark,
               CASE WHEN MAX(billing_export_watermark) IS NULL THEN NULL
                    ELSE GREATEST(
                      0,
                      EXTRACT(EPOCH FROM (CURRENT_TIMESTAMP - MAX(billing_export_watermark))) / 3600
                    )
                END AS billing_lag_hours
          FROM infrastructure_cost_daily
         WHERE utc_day >= (CURRENT_TIMESTAMP AT TIME ZONE 'UTC')::date - $1::integer
         GROUP BY cloud_provider, cloud_project_id, cluster_location, cluster_name,
                  environment, namespace, workload_kind, workload_ref, currency
         ORDER BY last_utc_day DESC, latest_as_of_utc DESC,
                  environment, cluster_name, namespace, workload_kind, workload_ref, currency
         LIMIT $2
      `,
      [SCOPE_CATALOG_LOOKBACK_DAYS, MAX_SCOPE_CATALOG_ENTRIES + 1]
    )
    const rows = result.rows as InfrastructureCostScopeRow[]
    return {
      scopes: rows.slice(0, MAX_SCOPE_CATALOG_ENTRIES).map(row => ({
        dimensions: {
          cloudProvider: row.cloud_provider,
          cloudProjectId: row.cloud_project_id,
          clusterLocation: row.cluster_location,
          clusterName: row.cluster_name,
          environment: row.environment,
          namespace: row.namespace,
          workloadKind: row.workload_kind,
          workloadRef: row.workload_ref,
          currency: row.currency,
        },
        firstUtcDay: toUtcDay(row.first_utc_day),
        lastUtcDay: toUtcDay(row.last_utc_day),
        availableValuations: [
          ...(row.has_estimated ? (['estimated'] as const) : []),
          ...(row.has_billed ? (['billed'] as const) : []),
        ],
        latestAsOfUtc: toIsoTimestamp(row.latest_as_of_utc),
        billingExportWatermark: toNullableIsoTimestamp(row.billing_export_watermark),
        billingLagHours: nullableHours(row.billing_lag_hours),
      })),
      truncated: rows.length > MAX_SCOPE_CATALOG_ENTRIES,
    }
  }

  async read(query: InfrastructureCostReadQuery): Promise<InfrastructureCostReadResponse> {
    const dailyResult = await this.db.query(
      `
        WITH ranked AS (
          SELECT d.*,
                 ROW_NUMBER() OVER (
                   PARTITION BY d.utc_day, d.valuation_kind, d.selected_basis
                   ORDER BY d.rollup_version DESC
                 ) AS selected_rank
            FROM infrastructure_cost_daily d
           WHERE d.utc_day >= $1::date
             AND d.utc_day < $2::date
             AND d.cloud_provider = $3
             AND d.cloud_project_id = $4
             AND d.cluster_location = $5
             AND d.cluster_name = $6
             AND d.environment = $7
             AND d.namespace = $8
             AND d.workload_kind = $9
             AND d.workload_ref = $10
             AND d.currency = $11
             AND (
               ($12 = 'variance' AND (
                 (d.valuation_kind = 'estimated' AND d.selected_basis = 'requested_capacity')
                 OR (d.valuation_kind = 'billed' AND d.selected_basis = 'gcp_request_allocation')
               ))
               OR ($12 = d.valuation_kind AND $13 = d.selected_basis)
             )
        )
        SELECT *
          FROM ranked
         WHERE selected_rank = 1
         ORDER BY utc_day ASC, valuation_kind ASC, selected_basis ASC
      `,
      [
        query.periodStartUtc,
        query.periodEndUtc,
        query.dimensions.cloudProvider,
        query.dimensions.cloudProjectId,
        query.dimensions.clusterLocation,
        query.dimensions.clusterName,
        query.dimensions.environment,
        query.dimensions.namespace,
        query.dimensions.workloadKind,
        query.dimensions.workloadRef,
        query.dimensions.currency,
        query.valuation,
        query.basis,
      ]
    )
    const dailyRows = dailyResult.rows as DailyCostRow[]
    const ids = dailyRows.map(row => row.id)
    const billingFreshness = dailyRows.some(row => row.valuation_kind === 'billed')
      ? await this.currentBillingFreshness(query.dimensions)
      : { status: 'unavailable' as const, lagHours: null }
    const componentRows =
      ids.length === 0
        ? []
        : ((
            await this.db.query(
              `
              SELECT c.*,
                     price.source_ref AS price_source_ref,
                     price.effective_from AS price_effective_from,
                     price.unit_price::text AS price_unit_price
                FROM infrastructure_cost_daily_components c
                LEFT JOIN infrastructure_price_snapshots price
                  ON price.id = c.price_snapshot_id
               WHERE c.daily_cost_id = ANY($1::uuid[])
               ORDER BY c.daily_cost_id ASC, c.component_key ASC
            `,
              [ids]
            )
          ).rows as DailyCostComponentRow[])
    const componentsByDailyId = new Map<string, DailyCostComponent[]>()
    for (const row of componentRows) {
      const components = componentsByDailyId.get(row.daily_cost_id) ?? []
      components.push(toComponent(row))
      componentsByDailyId.set(row.daily_cost_id, components)
    }
    const versions = dailyRows.map(row =>
      toDailyVersion(row, componentsByDailyId.get(row.id) ?? [])
    )
    const requestedCapacity = selectionView(
      query,
      versions.filter(version => version.selectedBasis === 'requested_capacity'),
      billingFreshness
    )
    const gcpRequestAllocation = selectionView(
      query,
      versions.filter(version => version.selectedBasis === 'gcp_request_allocation'),
      billingFreshness
    )
    const response: InfrastructureCostReadResponse = {
      period: query.period,
      periodStartUtc: query.periodStartUtc,
      periodEndUtc: query.periodEndUtc,
      dimensions: query.dimensions,
      requestedCapacity,
      gcpRequestAllocation,
    }
    if (
      completeComparable(
        periodDayCount(query.periodStartUtc, query.periodEndUtc),
        requestedCapacity,
        gcpRequestAllocation
      )
    ) {
      response.variance = {
        netAmount: varianceNetAmount(requestedCapacity!, gcpRequestAllocation!),
        billedBasis: 'gcp_request_allocation',
        estimateBasis: 'requested_capacity',
      }
    }
    return response
  }
}