data_drain 0.1.19 → 0.2.1

data/skill/references/api-detallada.md

@@ -0,0 +1,257 @@
+# API Detallada
+
+Firmas completas, parámetros, retornos y comportamientos de cada clase pública de DataDrain.
+
+## `DataDrain` (módulo)
+
+### `DataDrain.configure { |config| ... }`
+Bloque de configuración global. `config` es una instancia singleton de `Configuration`.
+
+### `DataDrain.configuration`
+Retorna la `Configuration` singleton (lazy init).
+
+### `DataDrain.reset_configuration!`
+Resetea config y resetea `Storage.adapter`. Útil en tests.
+
+---
+
+## `DataDrain::Configuration`
+
+Atributos (`attr_accessor`):
+
+| Atributo | Tipo | Default | Descripción |
+|----------|------|---------|-------------|
+| `storage_mode` | Symbol | `:local` | `:local` o `:s3` |
+| `aws_region` | String | `nil` | Requerido si `:s3` |
+| `aws_access_key_id` | String | `nil` | Requerido si `:s3` |
+| `aws_secret_access_key` | String | `nil` | Requerido si `:s3` |
+| `db_host` | String | `"127.0.0.1"` | Host PostgreSQL |
+| `db_port` | Integer | `5432` | Puerto PostgreSQL |
+| `db_user` | String | `nil` | Usuario PostgreSQL |
+| `db_pass` | String | `nil` | Password PostgreSQL |
+| `db_name` | String | `nil` | Base de datos |
+| `batch_size` | Integer | `5000` | Registros por DELETE en purga |
+| `throttle_delay` | Float | `0.5` | Segundos de pausa entre lotes |
+| `idle_in_transaction_session_timeout` | Integer | `0` | Milisegundos. `0` = DESACTIVADO. `nil` = no setear |
+| `limit_ram` | String | `nil` | Límite memoria DuckDB (ej. `"2GB"`) |
+| `tmp_directory` | String | `nil` | Spill-to-disk DuckDB |
+| `logger` | Logger | `Logger.new($stdout)` | Logger |
+
+### `#duckdb_connection_string`
+Retorna URI: `postgresql://user:pass@host:port/db?options=-c%20idle_in_transaction_session_timeout%3D<val>`
+
+**No hay validaciones automáticas.** Caller debe garantizar consistencia (ej. credenciales AWS si `storage_mode = :s3`).
+
+---
+
+## `DataDrain::Engine`
+
+### `#initialize(options)`
+
+| Opción | Tipo | Requerido | Descripción |
+|--------|------|-----------|-------------|
+| `:start_date` | Time/DateTime/Date | sí | Convertido a `beginning_of_day` |
+| `:end_date` | Time/DateTime/Date | sí | Convertido a `next_day.beginning_of_day` (semi-abierto `<`) |
+| `:table_name` | String | sí | Tabla origen en `public` |
+| `:partition_keys` | Array<String, Symbol> | sí | Orden = jerarquía Hive |
+| `:bucket` | String | no | Ruta local o nombre bucket S3 |
+| `:folder_name` | String | no | Default = `table_name` |
+| `:select_sql` | String | no | Default = `"*"` |
+| `:primary_key` | String | no | Default = `"id"`. Usado en DELETE |
+| `:where_clause` | String | no | SQL extra (concat con `AND`) |
+| `:skip_export` | Boolean | no | Default `false`. `true` omite export |
+
+Internamente: crea `DuckDB::Database.open(":memory:")`, captura `@config`, `@logger`, `@adapter`.
+
+### `#call → Boolean`
+Ejecuta flujo completo: setup → count → [export] → verify → [purge].
+
+- Retorna `true` si flujo completó (incluyendo caso `pg_count == 0`).
+- Retorna `false` si verify falla o si error leyendo Parquet.
+- Cuando retorna `false`, **NO ejecuta purga** (garantía de seguridad).
+
+Eventos emitidos: ver [eventos-telemetria.md](eventos-telemetria.md).
+
+### Métodos privados notables
+
+- `#base_where_sql` — `created_at >= START AND created_at < END_BOUNDARY [AND where_clause]`. Semi-abierto.
+- `#setup_duckdb` — INSTALL/LOAD postgres, set max_memory/temp_directory, ATTACH pg_source READ_ONLY, delega `setup_duckdb` al adapter.
+- `#get_postgres_count → Integer` — Vía `postgres_query('pg_source', ...)`.
+- `#export_to_parquet` — `COPY ... TO ... PARTITION_BY (...) COMPRESSION 'ZSTD' OVERWRITE_OR_IGNORE 1`.
+- `#verify_integrity → Boolean` — `COUNT(*) read_parquet(...) == @pg_count`. Captura `DuckDB::Error` → `false`.
+- `#purge_from_postgres` — Loop `DELETE WHERE pk IN (SELECT pk ... LIMIT batch_size)` hasta que `cmd_tuples == 0`. Heartbeat cada 100 lotes. `sleep(throttle_delay)` si `> 0`. Cierra conexión PG en `ensure`.
+
+---
+
+## `DataDrain::FileIngestor`
+
+### `#initialize(options)`
+
+| Opción | Tipo | Requerido | Descripción |
+|--------|------|-----------|-------------|
+| `:source_path` | String | sí | Ruta absoluta al archivo |
+| `:folder_name` | String | sí | Carpeta destino en Data Lake |
+| `:bucket` | String | no | Ruta local o bucket S3 |
+| `:partition_keys` | Array | no | Default `[]` (sin particionamiento) |
+| `:select_sql` | String | no | Default `"*"`. Útil para extraer columnas derivadas (`EXTRACT(YEAR FROM ts) AS year`) |
+| `:delete_after_upload` | Boolean | no | Default `true` |
+
+### `#call → Boolean`
+
+Flujo:
+1. Valida que el archivo exista. Si no, log `file_ingestor.file_not_found`, retorna `false`.
+2. Aplica `limit_ram`, `tmp_directory` y delega `setup_duckdb` al adapter.
+3. Determina reader según extensión (`.csv`, `.json`, `.parquet`). Otras extensiones → `raise DataDrain::Error`.
+4. Conteo de seguridad. Si `0`, limpia y retorna `true`.
+5. `COPY ... TO ... [PARTITION_BY (...)] COMPRESSION 'ZSTD' OVERWRITE_OR_IGNORE 1`.
+6. `cleanup_local_file` si `delete_after_upload`.
+7. Retorna `true`.
+
+`rescue DuckDB::Error` → log `file_ingestor.duckdb_error`, retorna `false`. `ensure` cierra conexión DuckDB.
+
+### Formatos soportados
+
+- `.csv` → `read_csv_auto`
+- `.json` → `read_json_auto`
+- `.parquet` → `read_parquet`
+- Otros → `raise DataDrain::Error, "Formato de archivo no soportado para ingestión: ..."`
+
+---
+
+## `DataDrain::Record`
+
+Clase abstracta. Subclasificar para cada tabla archivada.
+
+```ruby
+class ArchivedX < DataDrain::Record
+  self.bucket          = "..."
+  self.folder_name     = "..."
+  self.partition_keys  = [:isp_id, :year, :month]  # ORDEN CRÍTICO
+
+  attribute :id,         :string
+  attribute :created_at, :datetime
+  attribute :payload,    :json   # usa DataDrain::Types::JsonType
+end
+```
+
+Hereda de `ActiveModel::Model` + `ActiveModel::Attributes`.
+
+### `class_attribute`s
+- `bucket` — String
+- `folder_name` — String
+- `partition_keys` — Array<Symbol>
+
+### `.connection → DuckDB::Connection`
+Conexión persistente por thread (cacheada en `Thread.current[:data_drain_duckdb] = { db:, conn: }`). El hash ancla la `Database` para evitar GC. La conexión nunca se cierra explícitamente.
+
+### `.where(limit: 50, **partitions) → Array<self>`
+Construye path Hive en orden de `partition_keys` (no del orden de kwargs). SQL: `SELECT ... FROM read_parquet(path) ORDER BY created_at DESC LIMIT n`. Si Parquet no existe, retorna `[]` y loguea `record.parquet_not_found` en WARN.
+
+### `.find(id, **partitions) → self | nil`
+SQL: `WHERE id = '<safe_id>' LIMIT 1`. Sanitiza `id` con `gsub("'", "''")` (escape de comillas simples). Retorna primera fila o `nil`.
+
+### `.destroy_all(**partitions) → Integer`
+Delega a `Storage.adapter#destroy_partitions`. Loguea `record.destroy_all`. Si no se especifica una key de `partition_keys`, se usa wildcard (`*` en Local, regex `[^/]+` en S3). Retorna cantidad de particiones/objetos borrados.
+
+### `#inspect → String`
+Formato: `#<Class attr1: val1, attr2: val2, ...>`.
+
+### Métodos privados
+- `.build_query_path(partitions)` — Itera `partition_keys` (no kwargs) y arma `key=val/key=val/...`. Acepta keys como Symbol o String en `partitions`.
+- `.execute_and_instantiate(sql, columns)` — Ejecuta query, captura `DuckDB::Error` → `[]` con WARN, mapea filas a instancias.
+
+---
+
+## `DataDrain::GlueRunner`
+
+### `.run_and_wait(job_name, arguments = {}, polling_interval: 30) → true`
+
+| Parámetro | Tipo | Descripción |
+|-----------|------|-------------|
+| `job_name` | String | Nombre del Job en consola AWS |
+| `arguments` | Hash | Args con prefijo `--` (ej. `"--start_date" => "..."`) |
+| `polling_interval` | Integer | Segundos entre chequeos. Default `30` |
+
+Flujo:
+1. `Aws::Glue::Client.new(region: config.aws_region)`
+2. `start_job_run` → captura `run_id`
+3. Loop: `get_job_run`, evalúa `job_run_state`:
+   - `SUCCEEDED` → log `glue_runner.complete`, retorna `true`
+   - `FAILED|STOPPED|TIMEOUT` → log `glue_runner.failed` (incluye `error_message` truncado a 200 chars), `raise RuntimeError`
+   - Otro → log `glue_runner.polling`, `sleep polling_interval`
+
+No tiene timeout máximo. Si Glue queda colgado en `RUNNING`, esto bloquea indefinidamente.
+
+---
+
+## `DataDrain::Storage`
+
+### `.adapter → Storage::Base`
+Memoizada. Devuelve `Local.new` o `S3.new` según `config.storage_mode`. `raise InvalidAdapterError` si modo desconocido.
+
+### `.reset_adapter!`
+Limpia memoización. **Obligatorio** si se cambia `storage_mode` en runtime.
+
+### `Storage::Base` (interfaz)
+Métodos abstractos:
+- `#setup_duckdb(connection)` — `raise NotImplementedError`
+- `#prepare_export_path(bucket, folder_name)` — No-op por defecto
+- `#build_path(bucket, folder_name, partition_path) → String` — `raise NotImplementedError`
+- `#destroy_partitions(bucket, folder_name, partition_keys, partitions) → Integer` — `raise NotImplementedError`
+
+### `Storage::Local`
+- `#setup_duckdb` — No-op (DuckDB nativo)
+- `#prepare_export_path` — `FileUtils.mkdir_p`
+- `#build_path` — `"<bucket>/<folder>/<partition_path>/**/*.parquet"`
+- `#destroy_partitions` — Construye glob con `key=*` para nulos, `Dir.glob`, `FileUtils.rm_rf` cada match
+
+### `Storage::S3`
+- `#setup_duckdb` — `INSTALL httpfs; LOAD httpfs;` + `SET s3_region/s3_access_key_id/s3_secret_access_key`
+- `#prepare_export_path` — No-op (S3 no requiere mkdir)
+- `#build_path` — `"s3://<bucket>/<folder>/<partition_path>/**/*.parquet"`
+- `#destroy_partitions` — `Aws::S3::Client.list_objects_v2` con prefix optimizado (primera key si no es nula), filtra con regex (`key=[^/]+` para nulos), `delete_objects` en lotes de 1000
+
+---
+
+## `DataDrain::Observability` (mixín)
+
+Diseñado para `include` (instance methods, requiere `@logger`) o `extend` (class methods, requiere `@logger` de clase).
+
+### `#safe_log(level, event, metadata = {})` (privado)
+- Si `@logger` es nil, no-op.
+- Construye `fields = { component: observability_name, event: event }.merge(metadata)`.
+- Filtra valores cuyas keys sean `:password|:token|:secret|:api_key|:auth` → `[FILTERED]`.
+- Emite `@logger.send(level) { "k1=v1 k2=v2 ..." }`.
+- `rescue StandardError` silencioso (resilience).
+
+### `#exception_metadata(error)` (privado)
+Retorna `{ error_class: error.class.name, error_message: error.message.gsub('"', "'")[0, 200] }`.
+
+### `#observability_name` (privado)
+Extrae el primer namespace del nombre de clase y lo convierte a snake_case. Ej. `DataDrain::Engine` → `data_drain`.
+
+**Importante:** cuando se usa `extend`, marcar los métodos como `private_class_method :safe_log, :exception_metadata, :observability_name`.
+
+---
+
+## `DataDrain::Types::JsonType`
+
+`ActiveModel::Type::Value` registrado como `:json`. `#cast`:
+- Si valor es Hash, Array o nil → retorna tal cual.
+- Si String → `JSON.parse(value)`.
+- Si parse falla → retorna valor original (no levanta).
+
+---
+
+## `DataDrain::Error` jerarquía
+
+```
+StandardError
+└── DataDrain::Error
+    ├── DataDrain::ConfigurationError
+    ├── DataDrain::IntegrityError
+    ├── DataDrain::StorageError
+    └── DataDrain::Storage::InvalidAdapterError
+```
+
+`DuckDB::Error` y `Aws::S3::Errors::*` NO se envuelven en `StorageError` actualmente — se capturan puntualmente o se propagan.

data/skill/references/eventos-telemetria.md

@@ -0,0 +1,154 @@
+# Eventos y Telemetría
+
+Catálogo completo de eventos KV emitidos por DataDrain. Formato Wispro-Observability-Spec v1.
+
+## Convenciones
+
+- Formato: `component=data_drain event=<clase>.<suceso> [campos]`
+- `component=` y `event=` siempre primeros
+- Tiempos: sufijo `_s`, valor Float redondeado a 2 decimales
+- Contadores: sufijo `_count`, valor Integer
+- Sin unidades en valores (NO `"0.5s"`, SÍ `0.5`)
+- snake_case en todas las keys
+- `source=` lo inyecta `exis_ray` automáticamente — DataDrain NO lo emite
+- Secretos (`password|token|secret|api_key|auth`) → `[FILTERED]`
+- Fallos del logger nunca rompen flujo principal
+
+## Engine
+
+### `engine.start`
+**Nivel:** INFO. Emite al inicio de `#call`.
+**Campos:** `table`, `start_date`, `end_date`.
+
+### `engine.skip_empty`
+**Nivel:** INFO. Emite cuando `pg_count == 0`.
+**Campos:** `table`, `duration_s`, `db_query_duration_s`.
+
+### `engine.skip_export`
+**Nivel:** INFO. Emite cuando `skip_export: true`.
+**Campos:** `table`.
+
+### `engine.export_start`
+**Nivel:** INFO. Emite antes del `COPY ... TO`.
+**Campos:** `table`, `count`.
+
+### `engine.integrity_check`
+**Nivel:** INFO. Emite tras el conteo de Parquet (siempre que se pueda leer).
+**Campos:** `table`, `pg_count`, `parquet_count`.
+
+### `engine.parquet_read_error`
+**Nivel:** ERROR. Emite si `read_parquet` levanta `DuckDB::Error` durante verify.
+**Campos:** `table`, `error_class`, `error_message` (truncado a 200 chars).
+**Consecuencia:** `verify_integrity` retorna `false`, purga abortada.
+
+### `engine.purge_start`
+**Nivel:** INFO. Emite antes del primer DELETE.
+**Campos:** `table`, `batch_size`.
+
+### `engine.purge_heartbeat`
+**Nivel:** INFO. Emite cada 100 lotes durante purga.
+**Campos:** `table`, `batches_processed_count`, `rows_deleted_count`.
+
+### `engine.complete`
+**Nivel:** INFO. Emite al final exitoso del flujo.
+**Campos:** `table`, `duration_s`, `db_query_duration_s`, `export_duration_s`, `integrity_duration_s`, `purge_duration_s`, `count`.
+
+### `engine.integrity_error`
+**Nivel:** ERROR. Emite si `pg_count != parquet_count`.
+**Campos:** `table`, `duration_s`, `count`.
+**Consecuencia:** Retorna `false`, purga abortada.
+
+---
+
+## FileIngestor
+
+### `file_ingestor.start`
+**Nivel:** INFO. Emite al inicio de `#call`.
+**Campos:** `source_path`.
+
+### `file_ingestor.file_not_found`
+**Nivel:** ERROR. Emite si `File.exist?(source_path) == false`.
+**Campos:** `source_path`.
+
+### `file_ingestor.count`
+**Nivel:** INFO. Emite tras el conteo del archivo origen.
+**Campos:** `source_path`, `count`, `source_query_duration_s`.
+
+### `file_ingestor.skip_empty`
+**Nivel:** INFO. Emite si conteo es `0`.
+**Campos:** `source_path`, `duration_s`.
+
+### `file_ingestor.export_start`
+**Nivel:** INFO. Emite antes del `COPY ... TO`.
+**Campos:** `dest_path`.
+
+### `file_ingestor.complete`
+**Nivel:** INFO. Emite al final exitoso.
+**Campos:** `source_path`, `duration_s`, `source_query_duration_s`, `export_duration_s`, `count`.
+
+### `file_ingestor.duckdb_error`
+**Nivel:** ERROR. Emite si `DuckDB::Error` durante el proceso.
+**Campos:** `source_path`, `error_class`, `error_message`, `duration_s`.
+
+### `file_ingestor.cleanup`
+**Nivel:** INFO. Emite tras borrar el archivo local (si `delete_after_upload`).
+**Campos:** `source_path`.
+
+---
+
+## Record
+
+### `record.destroy_all`
+**Nivel:** INFO. Emite al inicio de `.destroy_all`.
+**Campos:** `folder`, `partitions` (inspect del hash).
+
+### `record.parquet_not_found`
+**Nivel:** WARN. Emite si `read_parquet` levanta `DuckDB::Error` en queries `where`/`find`.
+**Campos:** `error_class`, `error_message`.
+**Consecuencia:** Retorna `[]` (no levanta).
+
+---
+
+## GlueRunner
+
+### `glue_runner.start`
+**Nivel:** INFO. Emite antes de `start_job_run`.
+**Campos:** `job`.
+
+### `glue_runner.polling`
+**Nivel:** INFO. Emite cada chequeo de estado mientras Job no terminó.
+**Campos:** `job`, `run_id`, `status`, `next_check_in_s`.
+
+### `glue_runner.complete`
+**Nivel:** INFO. Emite cuando estado es `SUCCEEDED`.
+**Campos:** `job`, `run_id`, `duration_s`.
+
+### `glue_runner.failed`
+**Nivel:** ERROR. Emite cuando estado es `FAILED|STOPPED|TIMEOUT`.
+**Campos:** `job`, `run_id`, `status`, `duration_s`, `error_message` (si Glue lo provee, truncado a 200 chars).
+**Consecuencia:** `raise RuntimeError`.
+
+---
+
+## Ejemplos reales
+
+```
+component=data_drain event=engine.start table=versions start_date=2025-10-01 end_date=2025-11-01
+component=data_drain event=engine.export_start table=versions count=1500000
+component=data_drain event=engine.integrity_check table=versions pg_count=1500000 parquet_count=1500000
+component=data_drain event=engine.purge_heartbeat table=versions batches_processed_count=100 rows_deleted_count=500000
+component=data_drain event=engine.complete table=versions duration_s=185.4 db_query_duration_s=2.1 export_duration_s=42.7 integrity_duration_s=18.3 purge_duration_s=122.3 count=1500000
+
+component=data_drain event=file_ingestor.complete source_path=/tmp/netflow.csv duration_s=12.4 source_query_duration_s=0.8 export_duration_s=11.2 count=4500000
+
+component=data_drain event=glue_runner.polling job=my-export-job run_id=jr_abc123 status=RUNNING next_check_in_s=30
+component=data_drain event=glue_runner.failed job=my-export-job run_id=jr_abc123 status=FAILED duration_s=301.0 error_message='Out of memory in executor 4'
+```
+
+## Cómo agregar un nuevo evento
+
+1. En la clase, asegurar `include Observability` (instance) o `extend Observability` + `private_class_method :safe_log, :exception_metadata, :observability_name` (class).
+2. Asegurar `@logger = config.logger` (instance: en `initialize`; class: antes del primer `safe_log`).
+3. Llamar `safe_log(:level, "clase.suceso", { campo1: val1, campo2: val2 })`.
+4. Validar: keys snake_case, tiempos `_s` Float, contadores `_count` Integer, sin unidades en valores, sin `source=`.
+5. Para errores: incluir `exception_metadata(e)` mergeado al hash de campos.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: data_drain
 version: !ruby/object:Gem::Version
-  version: 0.1.19
+  version: 0.2.1
 platform: ruby
 authors:
 - Gabriel
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-03-30 00:00:00.000000000 Z
+date: 2026-04-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -97,6 +97,10 @@ files:
 - README.md
 - Rakefile
 - data_drain.gemspec
+- docs/IMPROVEMENT_PLAN.md
+- docs/execution/archive/v0.2.0.agente-review.md
+- docs/execution/archive/v0.2.0.md
+- docs/glue_pyspark_example.py
 - lib/data_drain.rb
 - lib/data_drain/configuration.rb
 - lib/data_drain/engine.rb
@@ -110,8 +114,13 @@ files:
 - lib/data_drain/storage/local.rb
 - lib/data_drain/storage/s3.rb
 - lib/data_drain/types/json_type.rb
+- lib/data_drain/validations.rb
 - lib/data_drain/version.rb
 - sig/data_drain.rbs
+- skill/SKILL.md
+- skill/references/antipatrones.md
+- skill/references/api-detallada.md
+- skill/references/eventos-telemetria.md
 homepage: https://github.com/gedera/data_drain
 licenses: []
 metadata: {}