@dotdo/postgres 0.1.0

package/src/iceberg/catalog.ts

@@ -0,0 +1,1007 @@
+/**
+ * Iceberg Catalog - Centralized Metadata Storage
+ * Task: postgres-b44 - Iceberg metadata storage strategy
+ *
+ * Implements a centralized Iceberg catalog that supports:
+ * - Namespace hierarchy (tenant/app/do)
+ * - Atomic metadata updates via optimistic locking
+ * - Concurrent writer support
+ * - Metadata caching for performance
+ * - REST catalog API compatibility
+ *
+ * Storage Strategy:
+ * - R2: Primary storage for all metadata files (table metadata, manifests, data)
+ * - DO Storage: Catalog index, version tracking, and lock coordination
+ * - Cache: In-memory LRU cache for frequently accessed metadata
+ *
+ * Layout:
+ * r2://iceberg-catalog/
+ *   catalog/
+ *     catalog.json           # Catalog configuration
+ *     namespaces.json        # Namespace registry
+ *   namespaces/
+ *     {tenant}/
+ *       {app}/
+ *         {table}/
+ *           metadata/
+ *             version-hint.text
+ *             v{n}.metadata.json
+ *           manifests/
+ *             {snapshot}-m{attempt}-{uuid}.avro
+ *           data/
+ *             {partition_path}/
+ *               data-{timestamp}-{uuid}.parquet
+ */
+
+import type {
+  IcebergTableMetadata,
+  IcebergSnapshot,
+} from './types'
+
+/**
+ * Namespace identifier following Iceberg REST catalog spec
+ */
+export interface NamespaceIdentifier {
+  /** Namespace levels (e.g., ['tenant', 'app']) */
+  levels: string[]
+}
+
+/**
+ * Table identifier within a namespace
+ */
+export interface TableIdentifier {
+  /** Namespace containing the table */
+  namespace: NamespaceIdentifier
+  /** Table name */
+  name: string
+}
+
+/**
+ * Namespace metadata
+ */
+export interface NamespaceMetadata {
+  /** Namespace identifier */
+  namespace: NamespaceIdentifier
+  /** Namespace properties */
+  properties: Record<string, string>
+  /** Creation timestamp */
+  createdAt: number
+  /** Last update timestamp */
+  updatedAt: number
+}
+
+/**
+ * Table entry in the catalog
+ */
+export interface CatalogTableEntry {
+  /** Table identifier */
+  identifier: TableIdentifier
+  /** Current metadata location in R2 */
+  metadataLocation: string
+  /** Current metadata version */
+  metadataVersion: number
+  /** Table UUID */
+  tableUuid: string
+  /** Creation timestamp */
+  createdAt: number
+  /** Last update timestamp */
+  updatedAt: number
+  /** Table properties */
+  properties: Record<string, string>
+}
+
+/**
+ * Catalog configuration
+ */
+export interface CatalogConfig {
+  /** R2 bucket for Iceberg storage */
+  bucket: R2Bucket
+  /** Base prefix for all catalog data (default: 'iceberg/') */
+  prefix?: string
+  /** DO state for catalog coordination */
+  state?: DurableObjectState
+  /** Cache TTL in milliseconds (default: 60000) */
+  cacheTtlMs?: number
+  /** Maximum cache entries (default: 1000) */
+  maxCacheEntries?: number
+  /** Enable optimistic locking (default: true) */
+  optimisticLocking?: boolean
+}
+
+/**
+ * Commit conflict error
+ */
+export class CommitConflictError extends Error {
+  constructor(
+    message: string,
+    public readonly expectedVersion: number,
+    public readonly actualVersion: number
+  ) {
+    super(message)
+    this.name = 'CommitConflictError'
+  }
+}
+
+/**
+ * Table not found error
+ */
+export class TableNotFoundError extends Error {
+  constructor(public readonly identifier: TableIdentifier) {
+    super(`Table not found: ${formatTableIdentifier(identifier)}`)
+    this.name = 'TableNotFoundError'
+  }
+}
+
+/**
+ * Namespace not found error
+ */
+export class NamespaceNotFoundError extends Error {
+  constructor(public readonly namespace: NamespaceIdentifier) {
+    super(`Namespace not found: ${formatNamespace(namespace)}`)
+    this.name = 'NamespaceNotFoundError'
+  }
+}
+
+/**
+ * Format namespace as string
+ */
+function formatNamespace(ns: NamespaceIdentifier): string {
+  return ns.levels.join('.')
+}
+
+/**
+ * Format table identifier as string
+ */
+function formatTableIdentifier(id: TableIdentifier): string {
+  return `${formatNamespace(id.namespace)}.${id.name}`
+}
+
+/**
+ * Default configuration values
+ */
+const DEFAULT_CONFIG = {
+  prefix: 'iceberg/',
+  cacheTtlMs: 60 * 1000, // 1 minute
+  maxCacheEntries: 1000,
+  optimisticLocking: true,
+}
+
+/**
+ * Storage keys for DO state
+ */
+const CATALOG_KEYS = {
+  NAMESPACES: '__iceberg_catalog_namespaces__',
+  TABLES: '__iceberg_catalog_tables__',
+  TABLE_LOCKS: '__iceberg_catalog_locks__',
+} as const
+
+/**
+ * Cache entry with TTL
+ */
+interface CacheEntry<T> {
+  value: T
+  expiresAt: number
+}
+
+/**
+ * LRU Cache for metadata
+ */
+class MetadataCache {
+  private cache: Map<string, CacheEntry<unknown>> = new Map()
+  private ttlMs: number
+  private maxEntries: number
+
+  constructor(ttlMs: number, maxEntries: number) {
+    this.ttlMs = ttlMs
+    this.maxEntries = maxEntries
+  }
+
+  get<T>(key: string): T | null {
+    const entry = this.cache.get(key)
+    if (!entry) {
+      return null
+    }
+
+    if (Date.now() > entry.expiresAt) {
+      this.cache.delete(key)
+      return null
+    }
+
+    // Move to end for LRU
+    this.cache.delete(key)
+    this.cache.set(key, entry)
+
+    return entry.value as T
+  }
+
+  set<T>(key: string, value: T): void {
+    // Evict oldest if at capacity
+    if (this.cache.size >= this.maxEntries) {
+      const oldestKey = this.cache.keys().next().value
+      if (oldestKey !== undefined) {
+        this.cache.delete(oldestKey)
+      }
+    }
+
+    this.cache.set(key, {
+      value,
+      expiresAt: Date.now() + this.ttlMs,
+    })
+  }
+
+  delete(key: string): void {
+    this.cache.delete(key)
+  }
+
+  clear(): void {
+    this.cache.clear()
+  }
+
+  /**
+   * Get cache statistics
+   */
+  getStats(): { size: number; maxEntries: number } {
+    return {
+      size: this.cache.size,
+      maxEntries: this.maxEntries,
+    }
+  }
+}
+
+/**
+ * Iceberg Catalog
+ *
+ * Centralized catalog for managing Iceberg tables across multiple DOs.
+ * Provides namespace hierarchy, atomic updates, and concurrent access support.
+ *
+ * @example
+ * ```typescript
+ * const catalog = new IcebergCatalog({
+ *   bucket: env.ICEBERG_BUCKET,
+ *   state: ctx.storage,
+ * })
+ *
+ * await catalog.initialize()
+ *
+ * // Create namespace
+ * await catalog.createNamespace({ levels: ['tenant1', 'app1'] })
+ *
+ * // Create table
+ * const table = await catalog.createTable({
+ *   namespace: { levels: ['tenant1', 'app1'] },
+ *   name: 'events',
+ * }, schema, partitionSpec)
+ *
+ * // Load table
+ * const metadata = await catalog.loadTable({
+ *   namespace: { levels: ['tenant1', 'app1'] },
+ *   name: 'events',
+ * })
+ * ```
+ */
+export class IcebergCatalog {
+  private bucket: R2Bucket
+  private prefix: string
+  private state: DurableObjectState | null
+  private cache: MetadataCache
+  private optimisticLocking: boolean
+  private initialized = false
+
+  // In-memory catalog state (synced with DO storage)
+  private namespaces: Map<string, NamespaceMetadata> = new Map()
+  private tables: Map<string, CatalogTableEntry> = new Map()
+
+  constructor(config: CatalogConfig) {
+    this.bucket = config.bucket
+    this.prefix = config.prefix ?? DEFAULT_CONFIG.prefix
+    this.state = config.state ?? null
+    this.cache = new MetadataCache(
+      config.cacheTtlMs ?? DEFAULT_CONFIG.cacheTtlMs,
+      config.maxCacheEntries ?? DEFAULT_CONFIG.maxCacheEntries
+    )
+    this.optimisticLocking = config.optimisticLocking ?? DEFAULT_CONFIG.optimisticLocking
+  }
+
+  /**
+   * Initialize the catalog
+   *
+   * Loads existing catalog state from DO storage or creates a new catalog.
+   */
+  async initialize(): Promise<void> {
+    if (this.initialized) {
+      return
+    }
+
+    // Load catalog state from DO storage
+    await this.loadCatalogState()
+
+    // Ensure catalog configuration exists in R2
+    await this.ensureCatalogConfig()
+
+    this.initialized = true
+  }
+
+  /**
+   * Ensure initialized
+   */
+  private ensureInitialized(): void {
+    if (!this.initialized) {
+      throw new Error('Catalog not initialized. Call initialize() first.')
+    }
+  }
+
+  /**
+   * Load catalog state from DO storage
+   */
+  private async loadCatalogState(): Promise<void> {
+    if (!this.state) {
+      return
+    }
+
+    // Load namespaces
+    const namespacesData = await this.state.storage.get<Record<string, NamespaceMetadata>>(
+      CATALOG_KEYS.NAMESPACES
+    )
+    if (namespacesData) {
+      this.namespaces = new Map(Object.entries(namespacesData))
+    }
+
+    // Load tables
+    const tablesData = await this.state.storage.get<Record<string, CatalogTableEntry>>(
+      CATALOG_KEYS.TABLES
+    )
+    if (tablesData) {
+      this.tables = new Map(Object.entries(tablesData))
+    }
+  }
+
+  /**
+   * Save catalog state to DO storage
+   */
+  private async saveCatalogState(): Promise<void> {
+    if (!this.state) {
+      return
+    }
+
+    await this.state.storage.put({
+      [CATALOG_KEYS.NAMESPACES]: Object.fromEntries(this.namespaces),
+      [CATALOG_KEYS.TABLES]: Object.fromEntries(this.tables),
+    })
+  }
+
+  /**
+   * Ensure catalog configuration exists in R2
+   */
+  private async ensureCatalogConfig(): Promise<void> {
+    const configPath = `${this.prefix}catalog/catalog.json`
+
+    const existing = await this.bucket.head(configPath)
+    if (existing) {
+      return
+    }
+
+    const catalogConfig = {
+      'catalog-impl': 'iceberg.IcebergCatalog',
+      'warehouse': `r2://${this.prefix}`,
+      'created-at': Date.now(),
+      'version': 1,
+    }
+
+    await this.bucket.put(configPath, JSON.stringify(catalogConfig, null, 2), {
+      httpMetadata: { contentType: 'application/json' },
+    })
+  }
+
+  // ========== Namespace Operations ==========
+
+  /**
+   * Create a namespace
+   */
+  async createNamespace(
+    namespace: NamespaceIdentifier,
+    properties: Record<string, string> = {}
+  ): Promise<NamespaceMetadata> {
+    this.ensureInitialized()
+
+    const key = formatNamespace(namespace)
+
+    if (this.namespaces.has(key)) {
+      throw new Error(`Namespace already exists: ${key}`)
+    }
+
+    const metadata: NamespaceMetadata = {
+      namespace,
+      properties,
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+    }
+
+    this.namespaces.set(key, metadata)
+    await this.saveCatalogState()
+
+    return metadata
+  }
+
+  /**
+   * List all namespaces, optionally under a parent namespace
+   */
+  async listNamespaces(parent?: NamespaceIdentifier): Promise<NamespaceIdentifier[]> {
+    this.ensureInitialized()
+
+    const parentPrefix = parent ? formatNamespace(parent) + '.' : ''
+    const result: NamespaceIdentifier[] = []
+
+    for (const [key] of this.namespaces) {
+      if (parentPrefix && !key.startsWith(parentPrefix)) {
+        continue
+      }
+
+      // Only return direct children
+      const suffix = key.slice(parentPrefix.length)
+      if (!suffix.includes('.')) {
+        result.push({ levels: key.split('.') })
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Get namespace metadata
+   */
+  async getNamespace(namespace: NamespaceIdentifier): Promise<NamespaceMetadata> {
+    this.ensureInitialized()
+
+    const key = formatNamespace(namespace)
+    const metadata = this.namespaces.get(key)
+
+    if (!metadata) {
+      throw new NamespaceNotFoundError(namespace)
+    }
+
+    return metadata
+  }
+
+  /**
+   * Check if namespace exists
+   */
+  async namespaceExists(namespace: NamespaceIdentifier): Promise<boolean> {
+    this.ensureInitialized()
+    return this.namespaces.has(formatNamespace(namespace))
+  }
+
+  /**
+   * Update namespace properties
+   */
+  async updateNamespaceProperties(
+    namespace: NamespaceIdentifier,
+    updates: Record<string, string>,
+    removals: string[] = []
+  ): Promise<NamespaceMetadata> {
+    this.ensureInitialized()
+
+    const key = formatNamespace(namespace)
+    const existing = this.namespaces.get(key)
+
+    if (!existing) {
+      throw new NamespaceNotFoundError(namespace)
+    }
+
+    const newProperties = { ...existing.properties }
+
+    // Apply updates
+    for (const [k, v] of Object.entries(updates)) {
+      newProperties[k] = v
+    }
+
+    // Apply removals
+    for (const k of removals) {
+      delete newProperties[k]
+    }
+
+    const updated: NamespaceMetadata = {
+      ...existing,
+      properties: newProperties,
+      updatedAt: Date.now(),
+    }
+
+    this.namespaces.set(key, updated)
+    await this.saveCatalogState()
+
+    return updated
+  }
+
+  /**
+   * Drop a namespace (must be empty)
+   */
+  async dropNamespace(namespace: NamespaceIdentifier): Promise<void> {
+    this.ensureInitialized()
+
+    const key = formatNamespace(namespace)
+
+    if (!this.namespaces.has(key)) {
+      throw new NamespaceNotFoundError(namespace)
+    }
+
+    // Check if namespace has tables
+    for (const [tableKey] of this.tables) {
+      if (tableKey.startsWith(key + '.')) {
+        throw new Error(`Namespace ${key} is not empty`)
+      }
+    }
+
+    this.namespaces.delete(key)
+    await this.saveCatalogState()
+  }
+
+  // ========== Table Operations ==========
+
+  /**
+   * Create a new table
+   */
+  async createTable(
+    identifier: TableIdentifier,
+    metadata: IcebergTableMetadata,
+    properties: Record<string, string> = {}
+  ): Promise<CatalogTableEntry> {
+    this.ensureInitialized()
+
+    const tableKey = formatTableIdentifier(identifier)
+    const nsKey = formatNamespace(identifier.namespace)
+
+    // Verify namespace exists
+    if (!this.namespaces.has(nsKey)) {
+      throw new NamespaceNotFoundError(identifier.namespace)
+    }
+
+    // Check table doesn't exist
+    if (this.tables.has(tableKey)) {
+      throw new Error(`Table already exists: ${tableKey}`)
+    }
+
+    // Generate table location
+    const tableLocation = this.getTableLocation(identifier)
+
+    // Update metadata location
+    const updatedMetadata: IcebergTableMetadata = {
+      ...metadata,
+      location: tableLocation,
+    }
+
+    // Write initial metadata to R2
+    const metadataPath = `${tableLocation}/metadata/v1.metadata.json`
+    await this.bucket.put(metadataPath, JSON.stringify(updatedMetadata, null, 2), {
+      httpMetadata: { contentType: 'application/json' },
+    })
+
+    // Write version hint
+    await this.bucket.put(`${tableLocation}/metadata/version-hint.text`, '1', {
+      httpMetadata: { contentType: 'text/plain' },
+    })
+
+    // Create catalog entry
+    const entry: CatalogTableEntry = {
+      identifier,
+      metadataLocation: metadataPath,
+      metadataVersion: 1,
+      tableUuid: updatedMetadata['table-uuid'],
+      createdAt: Date.now(),
+      updatedAt: Date.now(),
+      properties,
+    }
+
+    this.tables.set(tableKey, entry)
+    await this.saveCatalogState()
+
+    return entry
+  }
+
+  /**
+   * Load table metadata
+   */
+  async loadTable(identifier: TableIdentifier): Promise<IcebergTableMetadata> {
+    this.ensureInitialized()
+
+    const tableKey = formatTableIdentifier(identifier)
+    const entry = this.tables.get(tableKey)
+
+    if (!entry) {
+      throw new TableNotFoundError(identifier)
+    }
+
+    // Check cache first
+    const cacheKey = `table:${tableKey}`
+    const cached = this.cache.get<IcebergTableMetadata>(cacheKey)
+    if (cached) {
+      return cached
+    }
+
+    // Load from R2
+    const metadataObj = await this.bucket.get(entry.metadataLocation)
+    if (!metadataObj) {
+      throw new Error(`Table metadata not found: ${entry.metadataLocation}`)
+    }
+
+    const metadata = JSON.parse(await metadataObj.text()) as IcebergTableMetadata
+
+    // Cache the result
+    this.cache.set(cacheKey, metadata)
+
+    return metadata
+  }
+
+  /**
+   * List tables in a namespace
+   */
+  async listTables(namespace: NamespaceIdentifier): Promise<TableIdentifier[]> {
+    this.ensureInitialized()
+
+    const nsKey = formatNamespace(namespace)
+    const result: TableIdentifier[] = []
+
+    for (const [key, entry] of this.tables) {
+      if (key.startsWith(nsKey + '.')) {
+        result.push(entry.identifier)
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Check if table exists
+   */
+  async tableExists(identifier: TableIdentifier): Promise<boolean> {
+    this.ensureInitialized()
+    return this.tables.has(formatTableIdentifier(identifier))
+  }
+
+  /**
+   * Drop a table
+   */
+  async dropTable(identifier: TableIdentifier, purge = false): Promise<void> {
+    this.ensureInitialized()
+
+    const tableKey = formatTableIdentifier(identifier)
+    const entry = this.tables.get(tableKey)
+
+    if (!entry) {
+      throw new TableNotFoundError(identifier)
+    }
+
+    // Remove from catalog
+    this.tables.delete(tableKey)
+    this.cache.delete(`table:${tableKey}`)
+    await this.saveCatalogState()
+
+    // Optionally purge data from R2
+    if (purge) {
+      await this.purgeTableData(entry)
+    }
+  }
+
+  /**
+   * Purge all table data from R2
+   */
+  private async purgeTableData(entry: CatalogTableEntry): Promise<void> {
+    const tableLocation = this.getTableLocation(entry.identifier)
+
+    // List and delete all objects under the table location
+    let cursor: string | undefined
+
+    do {
+      const listOptions: R2ListOptions = {
+        prefix: tableLocation + '/',
+        limit: 1000,
+      }
+      if (cursor) {
+        listOptions.cursor = cursor
+      }
+
+      const result = await this.bucket.list(listOptions)
+      const keys = result.objects.map((obj) => obj.key)
+
+      if (keys.length > 0) {
+        await this.bucket.delete(keys)
+      }
+
+      cursor = result.truncated ? result.cursor : undefined
+    } while (cursor)
+  }
+
+  /**
+   * Rename a table
+   */
+  async renameTable(from: TableIdentifier, to: TableIdentifier): Promise<void> {
+    this.ensureInitialized()
+
+    const fromKey = formatTableIdentifier(from)
+    const toKey = formatTableIdentifier(to)
+    const toNsKey = formatNamespace(to.namespace)
+
+    const entry = this.tables.get(fromKey)
+    if (!entry) {
+      throw new TableNotFoundError(from)
+    }
+
+    // Verify target namespace exists
+    if (!this.namespaces.has(toNsKey)) {
+      throw new NamespaceNotFoundError(to.namespace)
+    }
+
+    // Check target doesn't exist
+    if (this.tables.has(toKey)) {
+      throw new Error(`Table already exists: ${toKey}`)
+    }
+
+    // Update entry
+    const updatedEntry: CatalogTableEntry = {
+      ...entry,
+      identifier: to,
+      updatedAt: Date.now(),
+    }
+
+    this.tables.delete(fromKey)
+    this.tables.set(toKey, updatedEntry)
+    this.cache.delete(`table:${fromKey}`)
+    await this.saveCatalogState()
+  }
+
+  // ========== Commit Operations (with Optimistic Locking) ==========
+
+  /**
+   * Commit a new table metadata version
+   *
+   * Uses optimistic locking to handle concurrent updates.
+   * The baseVersion must match the current version or the commit will fail.
+   */
+  async commitTableUpdate(
+    identifier: TableIdentifier,
+    newMetadata: IcebergTableMetadata,
+    baseVersion: number
+  ): Promise<IcebergSnapshot | null> {
+    this.ensureInitialized()
+
+    const tableKey = formatTableIdentifier(identifier)
+    const entry = this.tables.get(tableKey)
+
+    if (!entry) {
+      throw new TableNotFoundError(identifier)
+    }
+
+    // Optimistic locking check
+    if (this.optimisticLocking && entry.metadataVersion !== baseVersion) {
+      throw new CommitConflictError(
+        `Commit conflict: expected version ${baseVersion}, but current version is ${entry.metadataVersion}`,
+        baseVersion,
+        entry.metadataVersion
+      )
+    }
+
+    const newVersion = entry.metadataVersion + 1
+    const tableLocation = this.getTableLocation(identifier)
+    const newMetadataPath = `${tableLocation}/metadata/v${newVersion}.metadata.json`
+
+    // Write new metadata to R2
+    await this.bucket.put(newMetadataPath, JSON.stringify(newMetadata, null, 2), {
+      httpMetadata: { contentType: 'application/json' },
+    })
+
+    // Update version hint
+    await this.bucket.put(`${tableLocation}/metadata/version-hint.text`, String(newVersion), {
+      httpMetadata: { contentType: 'text/plain' },
+    })
+
+    // Update catalog entry
+    const updatedEntry: CatalogTableEntry = {
+      ...entry,
+      metadataLocation: newMetadataPath,
+      metadataVersion: newVersion,
+      updatedAt: Date.now(),
+    }
+
+    this.tables.set(tableKey, updatedEntry)
+    this.cache.delete(`table:${tableKey}`)
+    await this.saveCatalogState()
+
+    // Return the latest snapshot if one was added
+    if (newMetadata.snapshots && newMetadata.snapshots.length > 0) {
+      return newMetadata.snapshots[newMetadata.snapshots.length - 1] ?? null
+    }
+
+    return null
+  }
+
+  /**
+   * Get the current metadata version for a table
+   */
+  async getCurrentVersion(identifier: TableIdentifier): Promise<number> {
+    this.ensureInitialized()
+
+    const tableKey = formatTableIdentifier(identifier)
+    const entry = this.tables.get(tableKey)
+
+    if (!entry) {
+      throw new TableNotFoundError(identifier)
+    }
+
+    return entry.metadataVersion
+  }
+
+  /**
+   * Load a specific metadata version
+   */
+  async loadTableVersion(identifier: TableIdentifier, version: number): Promise<IcebergTableMetadata> {
+    this.ensureInitialized()
+
+    const tableLocation = this.getTableLocation(identifier)
+    const metadataPath = `${tableLocation}/metadata/v${version}.metadata.json`
+
+    const metadataObj = await this.bucket.get(metadataPath)
+    if (!metadataObj) {
+      throw new Error(`Metadata version ${version} not found for table ${formatTableIdentifier(identifier)}`)
+    }
+
+    return JSON.parse(await metadataObj.text()) as IcebergTableMetadata
+  }
+
+  /**
+   * List all metadata versions for a table
+   */
+  async listTableVersions(identifier: TableIdentifier): Promise<number[]> {
+    this.ensureInitialized()
+
+    const tableLocation = this.getTableLocation(identifier)
+    const prefix = `${tableLocation}/metadata/`
+
+    const versions: number[] = []
+    let cursor: string | undefined
+
+    do {
+      const listOptions: R2ListOptions = { prefix, limit: 1000 }
+      if (cursor) {
+        listOptions.cursor = cursor
+      }
+
+      const result = await this.bucket.list(listOptions)
+
+      for (const obj of result.objects) {
+        const match = obj.key.match(/v(\d+)\.metadata\.json$/)
+        if (match && match[1]) {
+          versions.push(parseInt(match[1], 10))
+        }
+      }
+
+      cursor = result.truncated ? result.cursor : undefined
+    } while (cursor)
+
+    return versions.sort((a, b) => a - b)
+  }
+
+  // ========== Utility Methods ==========
+
+  /**
+   * Get the R2 location for a table
+   */
+  private getTableLocation(identifier: TableIdentifier): string {
+    const nsPath = identifier.namespace.levels.join('/')
+    return `${this.prefix}namespaces/${nsPath}/${identifier.name}`
+  }
+
+  /**
+   * Get catalog statistics
+   */
+  getStats(): {
+    namespaceCount: number
+    tableCount: number
+    cacheStats: { size: number; maxEntries: number }
+  } {
+    return {
+      namespaceCount: this.namespaces.size,
+      tableCount: this.tables.size,
+      cacheStats: this.cache.getStats(),
+    }
+  }
+
+  /**
+   * Clear the metadata cache
+   */
+  clearCache(): void {
+    this.cache.clear()
+  }
+
+  /**
+   * Get a table entry without loading metadata
+   */
+  async getTableEntry(identifier: TableIdentifier): Promise<CatalogTableEntry | null> {
+    this.ensureInitialized()
+
+    const tableKey = formatTableIdentifier(identifier)
+    return this.tables.get(tableKey) ?? null
+  }
+}
+
+/**
+ * Create an Iceberg catalog
+ */
+export function createIcebergCatalog(config: CatalogConfig): IcebergCatalog {
+  return new IcebergCatalog(config)
+}
+
+// ========== Catalog REST API Types ==========
+
+/**
+ * REST API request for creating a namespace
+ */
+export interface CreateNamespaceRequest {
+  namespace: string[]
+  properties?: Record<string, string>
+}
+
+/**
+ * REST API response for namespace operations
+ */
+export interface NamespaceResponse {
+  namespace: string[]
+  properties: Record<string, string>
+}
+
+/**
+ * REST API request for creating a table
+ */
+export interface CreateTableRequest {
+  name: string
+  schema: unknown
+  'partition-spec'?: unknown
+  'write-order'?: unknown
+  'stage-create'?: boolean
+  properties?: Record<string, string>
+}
+
+/**
+ * REST API response for table operations
+ */
+export interface TableResponse {
+  'metadata-location': string
+  metadata: IcebergTableMetadata
+}
+
+/**
+ * REST API request for committing updates
+ */
+export interface CommitTableRequest {
+  requirements: TableRequirement[]
+  updates: TableUpdate[]
+}
+
+/**
+ * Table requirement for commit validation
+ */
+export type TableRequirement =
+  | { type: 'assert-create' }
+  | { type: 'assert-table-uuid'; uuid: string }
+  | { type: 'assert-ref-snapshot-id'; ref: string; 'snapshot-id': number | null }
+  | { type: 'assert-last-assigned-field-id'; 'last-assigned-field-id': number }
+  | { type: 'assert-current-schema-id'; 'current-schema-id': number }
+  | { type: 'assert-last-assigned-partition-id'; 'last-assigned-partition-id': number }
+  | { type: 'assert-default-spec-id'; 'default-spec-id': number }
+  | { type: 'assert-default-sort-order-id'; 'default-sort-order-id': number }
+
+/**
+ * Table update operations
+ */
+export type TableUpdate =
+  | { action: 'upgrade-format-version'; 'format-version': number }
+  | { action: 'add-schema'; schema: unknown; 'last-column-id'?: number }
+  | { action: 'set-current-schema'; 'schema-id': number }
+  | { action: 'add-partition-spec'; spec: unknown }
+  | { action: 'set-default-spec'; 'spec-id': number }
+  | { action: 'add-sort-order'; 'sort-order': unknown }
+  | { action: 'set-default-sort-order'; 'sort-order-id': number }
+  | { action: 'add-snapshot'; snapshot: IcebergSnapshot }
+  | { action: 'set-snapshot-ref'; 'ref-name': string; type: 'branch' | 'tag'; 'snapshot-id': number }
+  | { action: 'remove-snapshots'; 'snapshot-ids': number[] }
+  | { action: 'remove-snapshot-ref'; 'ref-name': string }
+  | { action: 'set-location'; location: string }
+  | { action: 'set-properties'; updates: Record<string, string> }
+  | { action: 'remove-properties'; removals: string[] }