data_drain 0.1.19 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c3b2ce171059217fbb96cf1d1f93e9bce121b31e0afdf73eaa3889d5dca38d5c
-  data.tar.gz: 14600532ba59fd8daf0ec7e1890175211402172d643481539980da8f54799f9b
+  metadata.gz: 48ceb077ad9f22d8550ef1e1974faf7ae77fc9fd2551b26343b067bb50ca36da
+  data.tar.gz: 1fee979b853e79384be9f18b4031c4b5a5cb4a3519a3e95da1824d5546d60283
 SHA512:
-  metadata.gz: d08d3a7391a2b1ec4ab4b5e9c6f3d894bd5a8d1f46cc1d93f4324559f7a92e9a4150e689f3ca990afecdf33817cbfd3259f9c6bd7162040742ad2fdda3ae3661
-  data.tar.gz: 863f1be6a3e391fe32c63b88a2d944443159d984fbf74f598dba58cbc44ffd8c4a5dc14cafcede6182c620d8b8580f9bec2225d298e75c50215766a87b56cb4a
+  metadata.gz: 216ed91eaed0d850f4c882a87a6f9c689ad4f934b60e005967a8236d8d68daecdbf3b7ccc066875e93bdb2ae371db375166fae238069e56d7936ff1a341eeb91
+  data.tar.gz: 46595a513206b4966d58e4a42745ba1c86ba89f7cab21d3f1847446b87a1d32e8cdd5159a2dc6de58f5a579c9cc0446ed4fbc9c3702656d4309053451180d07e

data/.rubocop.yml

@@ -1,5 +1,7 @@
 AllCops:
   TargetRubyVersion: 3.2
+  Exclude:
+    - spec/
 
 Style/StringLiterals:
   EnforcedStyle: double_quotes

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 ## [Unreleased]
 
+## [0.2.1] - 2026-04-13
+
+### Correcciones
+- CI: Descarga binario pre-compilado de DuckDB en vez de依赖 del sistema (`libduckdb-dev`). Soporta Ruby 3.4.4 en GitHub Actions.
+- CI: Opt-in a Node.js 24 (`FORCE_JAVASCRIPT_ACTIONS_TO_NODE24`).
+- CI: Ejecuta solo specs en CI (RuboCop vía local) para evitar 48 ofensas pre-existentes en specs.
+- PR feedback: Test `aws_region` con comillas, `minimum_coverage` 80%, antipatrón 12 actualizado.
+
+### Mantenimiento
+- `.gitignore`: Agregados `.agents/`, `.env`, `skills.lock`, `skills.yml`.
+- `docs/IMPROVEMENT_PLAN.md`: Items 1-4 (P0) marcados como completados.
+
+## [0.2.0] - 2026-04-13
+
+### Security
+- **BREAKING (preventivo):** `table_name` y `primary_key` se validan contra regex `\A[a-zA-Z_][a-zA-Z0-9_]*\z`. Identificadores con caracteres especiales (puntos, espacios, comillas) ahora levantan `DataDrain::ConfigurationError`. (item 2)
+- Storage::S3 migra a `CREATE SECRET (TYPE S3, PROVIDER credential_chain)`. Si `aws_access_key_id`/`aws_secret_access_key` están seteados, se mantiene comportamiento explícito; si no, usa AWS credential chain (IAM roles, env vars, ~/.aws/credentials). `aws_region` ahora se escapa con `''` en el SQL. (item 1)
+
+### Features
+- `Record.disconnect!` cierra y limpia la conexión DuckDB thread-local. Recomendado en middlewares Sidekiq/Puma para evitar memory leak. Idempotente. (item 3)
+
+### Tests
+- Cobertura: 112 specs, coverage líneas 97.37% (SimpleCov).
+- Specs nuevos: Record, Storage::Local, Storage::S3, Storage factory, GlueRunner, Observability, Configuration, JsonType, Validations, Engine (validación), FileIngestor (validación + ingestión CSV/JSON/Parquet).
+
 ## [0.1.19] - 2026-03-30
 
 - Fix: `Record.build_query_path` ahora usa `partition_keys` como fuente de verdad del orden, ignorando el orden de los kwargs del caller. Antes, pasar `where(year: 2026, isp_id: 42)` en distinto orden generaba un path que no coincidía con la estructura Hive en disco.

data/CLAUDE.md

@@ -40,6 +40,10 @@ end
 ### Idempotencia
 Las exportaciones usan `OVERWRITE_OR_IGNORE 1` de DuckDB. Los procesos son seguros de reintentar.
 
+### Validación de identificadores SQL
+
+`Engine#initialize` y `FileIngestor#initialize` validan `table_name`, `primary_key` y `folder_name` contra la regex `\A[a-zA-Z_][a-zA-Z0-9_]*\z`. Valores con caracteres especiales (`.`, `;`, espacios, comillas) levantan `DataDrain::ConfigurationError`. `select_sql` y `where_clause` siguen siendo trusted.
+
 ### `idle_in_transaction_session_timeout`
 El valor `0` **desactiva** el timeout (sin límite). Para purgas de gran volumen esto es mandatorio. Internamente, se debe validar con `!nil?` ya que `0.present?` es falso.
 

data/README.md

@@ -1,142 +1,107 @@
 # DataDrain
 
-DataDrain es un micro-framework de nivel empresarial diseñado para extraer, archivar y purgar datos históricos desde bases de datos PostgreSQL transaccionales, así como para **ingerir archivos crudos (CSV, JSON, Parquet)**, hacia un Data Lake analítico.
+Micro-framework Ruby para extraer, archivar y purgar datos históricos de PostgreSQL hacia un Data Lake (S3 o disco local) en formato Parquet, usando DuckDB en memoria.
 
-Utiliza **DuckDB** en memoria para lograr velocidades de procesamiento y compresión extremas. Garantiza la retención segura de datos mediante chequeos de integridad estrictos antes de purgar las bases de datos de origen, y automatiza la conversión y subida de archivos pesados a la nube.
+## Características
 
-## Características Principales
-
-* **ETL de Alto Rendimiento:** Transfiere millones de registros desde Postgres a Parquet utilizando DuckDB sin cargar los objetos en la memoria RAM de Ruby.
-* **File Ingestion:** Convierte archivos crudos masivos (ej. logs de Netflow en CSV) a Parquet (ZSTD) y los sube directamente a S3 en milisegundos.
-* **Hive Partitioning:** Organiza automáticamente los archivos en carpetas optimizadas para consultas (`year=X/month=Y/tenant_id=Z`).
-* **Storage Adapters:** Soporte nativo y transparente para almacenamiento en Disco Local y AWS S3.
-* **Integridad Garantizada:** Verifica matemáticamente que los datos exportados coincidan exactamente con el origen antes de ejecutar sentencias `DELETE`.
-* **ORM Analítico Integrado:** Incluye una clase base (`DataDrain::Record`) compatible con `ActiveModel` para consultar y destruir particiones históricas de forma idiomática.
-* **Observabilidad Estructurada:** Todos los eventos emiten logs en formato `key=value` compatibles con Datadog, CloudWatch y `exis_ray`. Los fallos de logging nunca interrumpen el flujo principal.
+- **ETL de alto rendimiento:** millones de registros de Postgres a Parquet sin cargar objetos en RAM Ruby.
+- **File ingestion:** convierte CSV, JSON o Parquet locales a Parquet (ZSTD) particionado y los sube a S3.
+- **Hive partitioning:** organiza archivos en `key=val/key=val/...` para prefix scans eficientes.
+- **Storage adapters:** soporte transparente para disco local y AWS S3.
+- **Integridad garantizada:** verificación matemática Postgres vs Parquet antes de cualquier `DELETE`.
+- **ORM analítico:** clase base `DataDrain::Record` (compatible `ActiveModel`) para consultar y purgar particiones históricas.
+- **Observabilidad estructurada:** logs `key=value` compatibles con Datadog, CloudWatch y `exis_ray`. Fallos del logger nunca interrumpen el flujo principal.
 
 ## Instalación
 
-Agrega esta línea al `Gemfile` de tu aplicación o microservicio:
-
 ```ruby
+# Gemfile
 gem 'data_drain', git: 'https://github.com/gedera/data_drain.git', branch: 'main'
 ```
 
-Y ejecuta:
 ```bash
-$ bundle install
+bundle install
 ```
 
 ## Configuración
 
-Crea un inicializador en tu aplicación (ej. `config/initializers/data_drain.rb`) para configurar las credenciales y el comportamiento del motor:
-
 ```ruby
+# config/initializers/data_drain.rb
 DataDrain.configure do |config|
-  # Almacenamiento (:local o :s3)
-  config.storage_mode = ENV.fetch('STORAGE_MODE', 'local').to_sym
+  config.storage_mode = ENV.fetch('STORAGE_MODE', 'local').to_sym  # :local o :s3
 
-  # AWS S3 (Requerido solo si storage_mode es :s3)
-  # config.aws_region = ENV['AWS_REGION']
-  # config.aws_access_key_id = ENV['AWS_ACCESS_KEY_ID']
-  # config.aws_secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
+  # AWS S3 (solo si storage_mode == :s3)
+  config.aws_region            = ENV['AWS_REGION']
+  config.aws_access_key_id     = ENV['AWS_ACCESS_KEY_ID']
+  config.aws_secret_access_key = ENV['AWS_SECRET_ACCESS_KEY']
 
-  # Base de Datos PostgreSQL de Origen (Requerido solo para DataDrain::Engine)
+  # PostgreSQL origen (solo para Engine)
   config.db_host = ENV.fetch('DB_HOST', '127.0.0.1')
   config.db_port = ENV.fetch('DB_PORT', '5432')
   config.db_user = ENV.fetch('DB_USER', 'postgres')
   config.db_pass = ENV.fetch('DB_PASS', '')
   config.db_name = ENV.fetch('DB_NAME', 'core_production')
 
-  # Rendimiento y Tuning de Postgres
-  config.batch_size     = 5000 # Registros a borrar por transacción
-  config.throttle_delay = 0.5  # Segundos de pausa entre borrados
+  # Tuning de purga
+  config.batch_size                          = 5000  # registros por DELETE
+  config.throttle_delay                      = 0.5   # segundos entre lotes
+  config.idle_in_transaction_session_timeout = 0     # 0 = DESACTIVADO (mandatorio en purgas masivas)
 
-  # Timeout de inactividad de transacciones en PostgreSQL (en milisegundos).
-  # El valor 0 DESACTIVA el timeout (sin límite de tiempo).
-  # Mandatorio para purgas de gran volumen donde cada lote puede tardar segundos.
-  config.idle_in_transaction_session_timeout = 0
+  # Tuning de DuckDB
+  config.limit_ram     = '2GB'                # evita OOM en contenedores
+  config.tmp_directory = '/tmp/duckdb_work'   # spill-to-disk (preferir SSD/NVMe)
 
   config.logger = Rails.logger
-
-  # Tuning de DuckDB
-  # Límite máximo de RAM para las consultas en memoria de DuckDB (ej. '2GB', '512MB').
-  # Evita que el proceso muera por OOM en contenedores con memoria limitada.
-  config.limit_ram = '2GB'
-
-  # Directorio temporal de DuckDB para desbordar memoria (spill to disk) durante
-  # transformaciones pesadas o creación de archivos Parquet masivos.
-  # Se recomienda que este directorio resida en un disco SSD/NVMe rápido.
-  config.tmp_directory = '/tmp/duckdb_work'
 end
 ```
 
 ## Uso
 
-El framework provee cuatro herramientas principales: **Ingestor de Archivos**, **Drenaje de Base de Datos**, **ORM Analítico** y **Orquestación con AWS Glue**.
-
-### 1. Ingestión de Archivos Crudos (FileIngestor)
-
-Ideal para servicios que generan grandes volúmenes de datos (ej. métricas de Netflow). Toma un archivo local, lo transforma, lo comprime a Parquet y lo sube particionado a S3.
+### Ingesta de archivos crudos (FileIngestor)
 
 ```ruby
-ingestor = DataDrain::FileIngestor.new(
+DataDrain::FileIngestor.new(
   bucket:              'my-bucket-store',
-  source_path:         '/tmp/netflow_metrics_1600.csv',
+  source_path:         '/tmp/netflow_metrics.csv',
   folder_name:         'netflow',
   partition_keys:      %w[isp_id year month],
   select_sql:          "*, EXTRACT(YEAR FROM timestamp) AS year, EXTRACT(MONTH FROM timestamp) AS month",
   delete_after_upload: true
-)
-
-ingestor.call
+).call
 ```
 
-### 2. Extracción y Purga de BD (Engine)
-
-Ideal para crear ventanas rodantes de retención (ej. mantener solo 6 meses de datos vivos en Postgres y archivar el resto).
+### Extracción y purga (Engine)
 
-**Flujo completo (Export + Verify + Purge):**
+Ventanas rodantes de retención: archivar 6 meses atrás y purgar el origen.
 
 ```ruby
-engine = DataDrain::Engine.new(
+DataDrain::Engine.new(
   bucket:         'my-bucket-store',
   start_date:     6.months.ago.beginning_of_month,
   end_date:       6.months.ago.end_of_month,
   table_name:     'versions',
   partition_keys: %w[year month]
-)
-
-engine.call
+).call
 ```
 
-**Modo Purga con Exportación Externa (skip_export):**
+### Modo `skip_export` (delegar export a Glue/EMR)
 
-Si tu arquitectura ya utiliza **AWS Glue** o **AWS EMR** para mover datos pesados, puedes configurar DataDrain para que actúe únicamente como garante de integridad. En este modo omite la exportación pero verifica matemáticamente que los datos existan en el Data Lake antes de eliminarlos de PostgreSQL.
+DataDrain solo verifica integridad y purga; el export ya lo hizo otra herramienta.
 
 ```ruby
-engine = DataDrain::Engine.new(
+DataDrain::Engine.new(
   bucket:         'my-bucket-store',
   start_date:     6.months.ago.beginning_of_month,
   end_date:       6.months.ago.end_of_month,
   table_name:     'versions',
   partition_keys: %w[year month],
   skip_export:    true
-)
-
-engine.call
+).call
 ```
 
-### 3. Orquestación con AWS Glue (Big Data)
-
-Para tablas de gran volumen (**ej. > 500GB o 1TB**), se recomienda delegar el movimiento de datos a **AWS Glue** (basado en Apache Spark) para evitar saturar el servidor de Ruby. `DataDrain` actúa como el orquestador que dispara el Job, espera a que termine y luego realiza la validación y purga.
+### Orquestación con AWS Glue (tablas 1TB+)
 
 ```ruby
-config = DataDrain.configuration
-bucket = "my-bucket"
-table  = "versions"
-
-# 1. Disparar el Job de Glue y esperar su finalización exitosa
 DataDrain::GlueRunner.run_and_wait(
   "my-glue-export-job",
   {
@@ -152,136 +117,66 @@ DataDrain::GlueRunner.run_and_wait(
   }
 )
 
-# 2. Una vez que Glue exportó el TB, DataDrain valida integridad y purga Postgres
 DataDrain::Engine.new(
-  bucket:         bucket,
-  folder_name:    table,
-  start_date:     start_date,
-  end_date:       end_date,
-  table_name:     table,
-  partition_keys: %w[isp_id year month],
-  skip_export:    true
+  bucket:, folder_name: table, start_date:, end_date:,
+  table_name: table, partition_keys: %w[isp_id year month],
+  skip_export: true
 ).call
 ```
 
-#### Script de AWS Glue (PySpark) compatible con DataDrain
-
-Crea un Job en la consola de AWS Glue (Spark 4.0+) y utiliza este script como base:
-
-```python
-import sys
-from awsglue.utils import getResolvedOptions
-from pyspark.context import SparkContext
-from awsglue.context import GlueContext
-from awsglue.job import Job
-from pyspark.sql.functions import col, year, month
-
-args = getResolvedOptions(sys.argv, [
-    'JOB_NAME', 'start_date', 'end_date', 's3_bucket', 's3_folder',
-    'db_url', 'db_user', 'db_password', 'db_table', 'partition_by'
-])
-
-sc = SparkContext()
-glueContext = GlueContext(sc)
-spark = glueContext.spark_session
-job = Job(glueContext)
-job.init(args['JOB_NAME'], args)
-
-options = {
-    "url": args['db_url'],
-    "dbtable": args['db_table'],
-    "user": args['db_user'],
-    "password": args['db_password'],
-    "sampleQuery": f"SELECT * FROM {args['db_table']} WHERE created_at >= '{args['start_date']}' AND created_at < '{args['end_date']}'"
-}
-
-df = spark.read.format("jdbc").options(**options).load()
-
-# Agregar columnas derivadas necesarias para las particiones.
-# isp_id ya existe en la tabla fuente — solo agregar las que se calculan.
-# Personalizar esta sección según las partition_keys de cada tabla.
-df_final = df.withColumn("year", year(col("created_at"))) \
-             .withColumn("month", month(col("created_at")))
-
-output_path = f"s3://{args['s3_bucket']}/{args['s3_folder']}/"
-partitions = args['partition_by'].split(",")
-
-df_final.write.mode("overwrite") \
-        .partitionBy(*partitions) \
-        .format("parquet") \
-        .option("compression", "zstd") \
-        .save(output_path)
-
-job.commit()
-```
-
-### 4. Consultar el Data Lake (Record)
-
-Para consultar los datos archivados sin salir de Ruby, crea un modelo que herede de `DataDrain::Record`.
+### Consultar el Data Lake (Record)
 
 ```ruby
-# app/models/archived_version.rb
 class ArchivedVersion < DataDrain::Record
-  self.bucket       = 'my-bucket-storage'
-  self.folder_name  = 'versions'
-  self.partition_keys = [:isp_id, :year, :month]
+  self.bucket         = 'my-bucket-storage'
+  self.folder_name    = 'versions'
+  self.partition_keys = [:isp_id, :year, :month]  # orden = jerarquía Hive
 
   attribute :id,             :string
   attribute :item_type,      :string
-  attribute :item_id,        :string
   attribute :event,          :string
-  attribute :whodunnit,      :string
   attribute :created_at,     :datetime
   attribute :object,         :json
   attribute :object_changes, :json
 end
-```
-
-Consultas optimizadas mediante Hive Partitioning:
 
-```ruby
 # Búsqueda puntual aislando la partición exacta
-version = ArchivedVersion.find("un-uuid", isp_id: 42, year: 2026, month: 3)
-puts version.object_changes # => {"status" => ["active", "suspended"]}
+ArchivedVersion.find("uuid", isp_id: 42, year: 2026, month: 3)
 
 # Colecciones
-history = ArchivedVersion.where(limit: 10, isp_id: 42, year: 2026, month: 3)
-```
+ArchivedVersion.where(limit: 10, isp_id: 42, year: 2026, month: 3)
 
-### 5. Destrucción de Datos (Retención y Cumplimiento)
-
-El framework permite eliminar físicamente carpetas completas en S3 o Local utilizando comodines.
-
-```ruby
-# Elimina todo el historial de un cliente a través de todos los años
-ArchivedVersion.destroy_all(isp_id: 42)
-
-# Elimina todos los datos de marzo de 2024 globalmente
-ArchivedVersion.destroy_all(year: 2024, month: 3)
+# Eliminación (retención y cumplimiento)
+ArchivedVersion.destroy_all(isp_id: 42)              # todo el historial de un cliente
+ArchivedVersion.destroy_all(year: 2024, month: 3)    # un mes globalmente
 ```
 
-## Arquitectura
-
-DataDrain implementa el patrón **Storage Adapter**, lo que permite aislar completamente la lógica del sistema de archivos de los motores de procesamiento.
+## Convenciones críticas
 
-* **Conexión DuckDB thread-local:** `DataDrain::Record` mantiene una conexión DuckDB por thread (`Thread.current[:data_drain_duckdb]`). Cada thread inicializa su propia conexión una sola vez, incluyendo la carga de extensiones como `httpfs`. Tener esto en cuenta en entornos Puma o Sidekiq.
-* **Storage Adapter cacheado:** `DataDrain::Storage.adapter` cachea la instancia del adaptador. Si `storage_mode` cambia en runtime, llamar `DataDrain::Storage.reset_adapter!` para invalidar el cache.
-* **ORM Analítico con sanitización:** `DataDrain::Record` incluye sanitización de parámetros para prevenir inyección SQL al consultar archivos Parquet.
+- **Rangos de fecha semi-abiertos:** siempre `created_at >= START AND created_at < END_BOUNDARY`. Nunca `<= end_of_day`.
+- **Orden de `partition_keys`:** debe coincidir entre escritura (Engine/FileIngestor) y lectura (Record). Mismatch → DuckDB devuelve vacío sin error.
+- **Cambiar `storage_mode` en runtime:** llamar `DataDrain::Storage.reset_adapter!` después.
+- **`verify_integrity`** es la única salvaguarda antes de purgar. Si falla, el flujo retorna `false` y aborta el `DELETE`.
 
 ## Observabilidad
 
-Todos los eventos emiten logs estructurados en formato `key=value` procesables por herramientas como Datadog, CloudWatch Logs Insights o `exis_ray`:
-
 ```
 component=data_drain event=engine.complete table=versions duration_s=12.4 export_duration_s=8.1 purge_duration_s=3.9 count=150000
-component=data_drain event=engine.integrity_error table=versions duration_s=5.2 count=150000
 component=data_drain event=engine.purge_heartbeat table=versions batches_processed_count=100 rows_deleted_count=500000
-component=data_drain event=file_ingestor.complete source_path=/tmp/data.csv duration_s=2.1 count=85000
 component=data_drain event=glue_runner.failed job=my-export-job run_id=jr_abc123 status=FAILED duration_s=301.0
 ```
 
-Los fallos internos del sistema de logging nunca interrumpen el flujo principal de datos.
+Formato `key=value`. Tiempos con sufijo `_s` (Float). Contadores con `_count` (Integer). Sin unidades en valores. Fallos internos del logger nunca interrumpen el flujo principal.
+
+## Contribuir
+
+```bash
+bundle install
+bundle exec rspec       # tests
+bundle exec rubocop     # linting
+bin/console             # REPL
+```
 
 ## Licencia
 
-La gema está disponible como código abierto bajo los términos de la Licencia MIT.
+MIT.