data_drain 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 48ceb077ad9f22d8550ef1e1974faf7ae77fc9fd2551b26343b067bb50ca36da
-  data.tar.gz: 1fee979b853e79384be9f18b4031c4b5a5cb4a3519a3e95da1824d5546d60283
+  metadata.gz: 8fc6bdf2a5a21825f9bc07185c0fc259056646c6084de2a42fd2d4e3198af4f2
+  data.tar.gz: aa7623b2ec910da4491c38904aa4623fd48a466ccc97a38124f29aafd9677655
 SHA512:
-  metadata.gz: 216ed91eaed0d850f4c882a87a6f9c689ad4f934b60e005967a8236d8d68daecdbf3b7ccc066875e93bdb2ae371db375166fae238069e56d7936ff1a341eeb91
-  data.tar.gz: 46595a513206b4966d58e4a42745ba1c86ba89f7cab21d3f1847446b87a1d32e8cdd5159a2dc6de58f5a579c9cc0446ed4fbc9c3702656d4309053451180d07e
+  metadata.gz: '0201838e917434b529250689a5987008f9e8895366b56a78522752fe5b490fb6ab3d0b4c40dc81bcc830af3132c005fc8d136ab719093a16f0c9de5221e3421c'
+  data.tar.gz: 5be0c9c4a47d07f479f49c977d0490aad909a33fbc0c9292594bd51163132ee5229e0131f23d253120732d530930e5474bd31abbef7a5289f3022055799b5525

data/CHANGELOG.md

@@ -1,9 +1,54 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-15
+
+### Refactor
+- `Engine#call` refactorizado: extraídos `step_count`, `step_export`, `step_verify`, `step_purge` como métodos privados con `timed` helper. CC bajó de 13 a 5. Eventos emitidos idénticos al comportamiento anterior. (item 10)
+- Extraído `DataDrain::Observability::Timing` mixin compartido entre Engine y FileIngestor. (item 20)
+- `FileIngestor#call` refactorizado análogo a Engine. (item 20)
+- Eliminados todos los `# rubocop:disable Metrics/*` en `lib/`. (item 20)
+
+### Features
+- `config.vacuum_after_purge = false` (default). Si `true`, ejecuta `VACUUM ANALYZE` post-purga cuando hubo deletes. Emite `engine.vacuum_complete` con dead_tuples antes/después y duración. Errores PG se capturan como `engine.vacuum_error` WARN. (item 5)
+- `config.slow_batch_threshold_s = 30` y `config.slow_batch_alert_after = 5`. Detecta lotes de purga lentos. Emite `engine.slow_batch` WARN por cada lote lento, `engine.purge_degraded` WARN una vez por streak. Incluye hint a docs de tuning. (item 11b)
+
+### Security
+- `Record.connection` aplica `SET lock_configuration=true` post-setup. Congela cualquier SET futuro sobre la conexión (defensa en profundidad). NO afecta secrets ni extensiones ya cargadas. (item 6)
+
+### Telemetry nueva
+- `engine.vacuum_complete`, `engine.vacuum_error`, `engine.slow_batch`, `engine.purge_degraded`.
+
+### Tests
+- Coverage se mantiene ≥ 80%.
+- Nuevo test de equivalencia para Engine (eventos idénticos pre/post refactor).
+- Timecop agregado para tests de timing (item 11b).
+
+## [0.2.2] - 2026-04-14
+
+### Security
+- `Observability#safe_log` filtra secretos con regex `/password|passwd|pass|secret|token|api_key|apikey|auth|credential|private_key/i` — ahora captura variantes como `db_password`, `aws_secret_access_key`, `bearer_token`, `private_key`, `*credential*`. (item 9)
+
+### Features
+- `GlueRunner.run_and_wait` acepta `max_wait_seconds:` para evitar bloqueo indefinido. Default `nil` (sin límite, backward-compatible). Emite `glue_runner.timeout` y levanta `DataDrain::Error` cuando excede. (item 7)
+- `Configuration#validate!` y `Configuration#validate_for_engine!` invocados automáticamente en `Engine`, `FileIngestor` y `GlueRunner`. Falla rápido con errores descriptivos si falta configuración. (item 8)
+
+### Docs
+- `skill/references/postgres-tuning.md`: guía de tuning Postgres por tamaño de tabla — índices, VACUUM post-purga, particionamiento, diagnóstico. (item 11a)
+
+### Cleanups (review PR #6)
+- Fix typo `依赖` en CHANGELOG v0.2.1 (A1).
+- Comment explicativo en `Record.disconnect!` rescue (A2).
+- Cobertura real string-keys vs symbol-keys en `Record.build_query_path` (A3).
+- Cerrar conn+db en `record_spec.rb#before(:all)` para evitar memory leak en suite (A4).
+- Reorder `public`/`private` en `storage/s3.rb` (B1).
+
+### BREAKING (preventivo)
+- `Engine.new` / `FileIngestor.new` / `GlueRunner.run_and_wait` ahora levantan `DataDrain::ConfigurationError` en el boot si la configuración está incompleta. Antes fallaban tarde con errores oscuros. La gema aún no está en uso en producción — no hay impacto real.
+
 ## [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: Descarga binario pre-compilado de DuckDB en vez de depender 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.

data/CLAUDE.md

@@ -59,7 +59,7 @@ La telemetría debe ser estructurada (KV) para ser procesada por `exis_ray`.
 - **Automatización:** El campo `source` lo inyecta automáticamente `exis_ray` — no incluirlo manualmente.
 - **DEBUG:** Siempre en forma de bloque: `logger.debug { "k=#{v}" }`.
 - **Duraciones:** Usar siempre `Process.clock_gettime(Process::CLOCK_MONOTONIC)`.
-- **Sensibilidad:** Filtrar datos sensibles (`password`, `token`, `secret`) → `[FILTERED]`.
+- **Sensibilidad:** `Observability#safe_log` filtra claves con regex `/password|passwd|pass|secret|token|api_key|apikey|auth|credential|private_key/i` → `[FILTERED]`.
 
 ## Código Ruby
 
@@ -79,3 +79,5 @@ bin/console             # REPL de desarrollo
 
 - `limit_ram` y `tmp_directory` en la configuración evitan OOM en contenedores
 - DuckDB usa spill-to-disk automáticamente cuando `tmp_directory` está seteado
+- Ver `skill/references/postgres-tuning.md` para guía de tuning por tamaño de tabla:
+  índices, VACUUM post-purga, y particionamiento declarativo para tablas >100GB

data/README.md

@@ -51,6 +51,9 @@ DataDrain.configure do |config|
   config.limit_ram     = '2GB'                # evita OOM en contenedores
   config.tmp_directory = '/tmp/duckdb_work'   # spill-to-disk (preferir SSD/NVMe)
 
+  # Tuning de Postgres: ver skill/references/postgres-tuning.md
+  # Índices para DELETE, VACUUM post-purga, particionamiento para tablas >100GB
+
   config.logger = Rails.logger
 end
 ```

data/docs/IMPROVEMENT_PLAN.md

@@ -1,7 +1,7 @@
 # DataDrain — Plan de Mejora v0.2.0 → v0.3.1
 
-**Versión actual:** 0.2.0
-**Última actualización:** 2026-04-13
+**Versión actual:** 0.2.2
+**Última actualización:** 2026-04-14
 **Owner:** Gabriel
 **Estado global:** No iniciado
 
@@ -32,7 +32,7 @@ DataDrain v0.1.19 es una gema bien arquitecturada (Storage Adapter, Observabilit
 - **Memory leak potencial:** conexión DuckDB thread-local sin cleanup.
 - **Documentación de tuning ausente:** sin guía para purgas masivas, índices, particionamiento.
 
-Este plan agrupa 17 items en 4 releases incrementales (v0.2.0 → v0.3.1) priorizados por impacto.
+Este plan agrupa 24 items (17 originales + 7 surgidos post v0.2.1) en 5+ releases incrementales (v0.2.0 → v0.3.1) priorizados por impacto.
 
 ---
 
@@ -433,12 +433,13 @@ spec/
 
 #### Item 5 — VACUUM ANALYZE opcional post-purga
 
-**Estado:** `[ ]`
+**Estado:** `[x]`
 **Prioridad:** P1
 **Tipo:** `feat` `perf`
 **Compatibilidad:** backward-compatible (default `false`, opt-in)
 **Estimación:** S (2-3h)
 **Release:** v0.2.1
+**Commit:** `93bf8a8`
 
 ##### Contexto
 
@@ -502,7 +503,7 @@ Purgar millones de rows deja dead tuples en Postgres. Sin `VACUUM`, el espacio n
 
 #### Item 7 — `max_wait_seconds` en `GlueRunner.run_and_wait`
 
-**Estado:** `[ ]`
+**Estado:** `[x]`
 **Prioridad:** P1
 **Tipo:** `feat`
 **Compatibilidad:** backward-compatible
@@ -553,7 +554,7 @@ Purgar millones de rows deja dead tuples en Postgres. Sin `VACUUM`, el espacio n
 
 #### Item 8 — `Configuration#validate!`
 
-**Estado:** `[ ]`
+**Estado:** `[x]`
 **Prioridad:** P1
 **Tipo:** `feat`
 **Compatibilidad:** backward-compatible (validación opcional explícita)
@@ -624,7 +625,7 @@ Purgar millones de rows deja dead tuples en Postgres. Sin `VACUUM`, el espacio n
 
 #### Item 9 — Filtro de secretos por regex en Observability
 
-**Estado:** `[ ]`
+**Estado:** `[x]`
 **Prioridad:** P1
 **Tipo:** `security`
 **Compatibilidad:** backward-compatible (filtra más, no menos)
@@ -670,7 +671,7 @@ val = SENSITIVE_KEY_PATTERN.match?(k.to_s) ? "[FILTERED]" : v
 
 #### Item 11a — Documentación de Postgres tuning por tamaño de tabla
 
-**Estado:** `[ ]`
+**Estado:** `[x]`
 **Prioridad:** P1
 **Tipo:** `docs`
 **Compatibilidad:** N/A
@@ -754,12 +755,13 @@ Contenido:
 
 #### Item 6 — Sandboxing de `Record.connection`
 
-**Estado:** `[ ]`
+**Estado:** `[x]`
 **Prioridad:** P1
 **Tipo:** `security`
 **Compatibilidad:** backward-compatible (con risk de breaking si caller hizo workarounds raros)
 **Estimación:** M (3-4h)
 **Release:** v0.3.0
+**Commit:** `f042c56`
 
 ##### Contexto
 
@@ -800,12 +802,13 @@ Reduce blast radius si alguien intenta inyectar SQL malicioso vía `where_clause
 
 #### Item 10 — Refactor `Engine#call` (CC=13 → ~5)
 
-**Estado:** `[ ]`
+**Estado:** `[x]`
 **Prioridad:** P1
 **Tipo:** `refactor`
 **Compatibilidad:** backward-compatible
 **Estimación:** M (4-6h)
 **Release:** v0.3.0
+**Commit:** `6a06850`
 
 ##### Contexto
 
@@ -878,12 +881,13 @@ Reduce blast radius si alguien intenta inyectar SQL malicioso vía `where_clause
 
 #### Item 11b — Warning runtime de purga lenta sin avance
 
-**Estado:** `[ ]`
+**Estado:** `[x]`
 **Prioridad:** P1
 **Tipo:** `feat` `perf`
 **Compatibilidad:** backward-compatible
 **Estimación:** M (3-4h)
 **Release:** v0.3.0
+**Commit:** `d72ec0a`
 
 ##### Contexto
 
@@ -1091,6 +1095,262 @@ Solo donde sea limpio. No forzar.
 
 ---
 
+### Items nuevos — surgidos post v0.2.1 (no en plan original)
+
+Agregados el 2026-04-14 tras review de v0.2.1 y análisis del workaround de CI.
+
+---
+
+#### Item 17 — Arreglar 48 ofensas RuboCop en `spec/` y re-habilitar en CI
+
+**Estado:** `[ ]`
+**Prioridad:** P2
+**Tipo:** `chore` `test`
+**Compatibilidad:** N/A
+**Estimación:** M (3-5h)
+**Release sugerido:** v0.3.1
+
+##### Contexto
+
+v0.2.1 excluyó `spec/` de RuboCop en `.rubocop.yml` para desbloquear el CI. La exclusión oculta ~48 ofensas preexistentes. El item 14 del roadmap ("CI con GitHub Actions") asume que RuboCop corre en CI — hoy no aplica a specs.
+
+##### Cambios
+
+1. Quitar `Exclude: - spec/` de `.rubocop.yml`.
+2. `bundle exec rubocop spec/ --auto-correct` para fixes automáticos.
+3. Fix manual de ofensas no auto-corregibles (típicamente `Metrics/BlockLength`, `RSpec/MultipleExpectations`, etc.).
+4. Re-habilitar rubocop en el workflow CI (`.github/workflows/main.yml`).
+
+##### Criterios de aceptación
+
+- [ ] `bundle exec rubocop` (sin argumentos, todo el proyecto) sin ofensas.
+- [ ] Workflow CI corre `bundle exec rubocop` antes de `rspec`.
+- [ ] Todos los specs siguen pasando después del auto-correct.
+
+##### Riesgos
+
+- **Auto-correct puede romper tests.** Correr `rspec` tras cada batch de auto-correct.
+- Algunas ofensas requieren configurar `RSpec/*` cops con límites razonables (ej. `Max: 20` para `RSpec/ExampleLength`).
+
+---
+
+#### Item 18 — Matrix Ruby en CI (3.2, 3.3, 3.4)
+
+**Estado:** `[ ]`
+**Prioridad:** P2
+**Tipo:** `chore`
+**Compatibilidad:** N/A
+**Estimación:** S (1-2h)
+**Release sugerido:** v0.3.1
+
+##### Contexto
+
+v0.2.1 solo corre CI en Ruby 3.4.4. La gema declara `required_ruby_version = ">= 3.0.0"`. Para validar compatibilidad con Rubies soportadas por Rails (3.2, 3.3), agregar matrix.
+
+##### Cambios
+
+1. En `.github/workflows/main.yml`:
+   ```yaml
+   strategy:
+     matrix:
+       ruby: ["3.2", "3.3", "3.4"]
+   ```
+2. Verificar que el binario pre-compilado de DuckDB 1.4.4 funciona en las 3 versiones de Ruby (debería — C ABI estable).
+3. Ajustar `TargetRubyVersion` en `.rubocop.yml` si corresponde (hoy `3.2`, puede bajarse a `3.0` si la gema lo soporta realmente — verificar `required_ruby_version`).
+
+##### Criterios de aceptación
+
+- [ ] Matrix con 3 versiones Ruby corre en CI.
+- [ ] Tiempo total < 10 min.
+- [ ] Las 3 versiones pasan specs.
+
+##### Riesgos
+
+- **DuckDB prebuilt binary dep** — si la C extension no linkea bien en alguna versión, tendrá que recompilar (cambia tiempo de CI).
+
+---
+
+#### Item 19 — Migrar tests S3 de `stub_const` a `Aws::S3::Client.stub_responses`
+
+**Estado:** `[ ]`
+**Prioridad:** P2
+**Tipo:** `refactor` `test`
+**Compatibilidad:** N/A
+**Estimación:** S (2h)
+**Release sugerido:** v0.3.1
+
+##### Contexto
+
+`spec/data_drain/storage/s3_spec.rb` usa `stub_const("Aws::S3::Client", Class.new ...)` para mockear el cliente AWS. Esto reemplaza la clase entera y es frágil (si AWS SDK agrega métodos nuevos, los tests no los cubren). AWS SDK soporta nativamente `Aws::S3::Client.new(stub_responses: true)`.
+
+##### Cambios
+
+1. En `spec/data_drain/storage/s3_spec.rb`, reemplazar `stub_const` por:
+   ```ruby
+   let(:s3_client) { Aws::S3::Client.new(stub_responses: true) }
+
+   before do
+     s3_client.stub_responses(:list_objects_v2, contents: [...])
+     allow(Aws::S3::Client).to receive(:new).and_return(s3_client)
+   end
+   ```
+2. Los tests de `destroy_partitions` quedan más declarativos.
+
+##### Criterios de aceptación
+
+- [ ] Tests pasan con el SDK real (`stub_responses` usa el client real, no mock).
+- [ ] No más `stub_const("Aws::S3::Client", ...)`.
+- [ ] Cobertura igual o superior.
+
+##### Riesgos
+
+- **Setup diferente:** `stub_responses` requiere configurar cada API call. Más verboso pero más robusto.
+
+---
+
+#### Item 20 — Limpiar `rubocop:disable` en `lib/` agregados en v0.2.0
+
+**Estado:** `[x]`
+**Prioridad:** P2
+**Tipo:** `refactor`
+**Compatibilidad:** N/A
+**Estimación:** Depende del item 10 (refactor Engine#call)
+**Release sugerido:** v0.3.0 (junto con item 10)
+**Commit:** `f6f4ddc` (FileIngestor), `02d207c` (S3 refactor), `5522c79` (Timing mixin)
+
+##### Contexto
+
+v0.2.0 agregó `# rubocop:disable` extensivos en 4 archivos:
+- `lib/data_drain/engine.rb`: `Metrics/ClassLength, AbcSize, MethodLength, Naming/AccessorMethodName`
+- `lib/data_drain/file_ingestor.rb`: `Metrics/AbcSize, CyclomaticComplexity, PerceivedComplexity, MethodLength`
+- `lib/data_drain/record.rb`: `Metrics/AbcSize, MethodLength`
+- `lib/data_drain/storage/s3.rb`: `Metrics/AbcSize, CyclomaticComplexity, MethodLength`
+
+Workaround razonable durante v0.2.0 pero deja deuda visible.
+
+##### Cambios
+
+Item 10 del roadmap (refactor `Engine#call` CC=13→5) resolverá parte. Este item complementa:
+
+1. Refactor `FileIngestor#call` en métodos privados (similar a item 10 para Engine).
+2. Refactor `Storage::S3#setup_duckdb` + `#create_s3_secret` — el CC viene del branching credencial explícita vs `credential_chain`. Puede simplificarse.
+3. Refactor `Record#execute_and_instantiate` — probablemente un guard clause resuelve.
+4. Quitar todos los `rubocop:disable` a medida que se refactoriza.
+
+##### Criterios de aceptación
+
+- [ ] Ningún `# rubocop:disable Metrics/*` en `lib/`.
+- [ ] `bundle exec rubocop lib/` sin ofensas ni disables.
+- [ ] Tests verdes.
+
+##### Riesgos
+
+- **Refactor mayor de `FileIngestor`** — no tiene tests integration tan robustos como Engine. Requiere atención.
+
+---
+
+#### Item 22 — Cache de RuboCop en CI
+
+**Estado:** `[ ]`
+**Prioridad:** P3
+**Tipo:** `chore`
+**Compatibilidad:** N/A
+**Estimación:** XS (30min)
+**Release sugerido:** v0.3.1
+**Origen:** Review big-pickle 2026-04-14 (ClickUp 86b9dka0c).
+
+##### Contexto
+
+Cuando el item 17 re-habilite rubocop en CI, correrá en cada push. Cachear el resultado con `actions/cache` sobre `~/.cache/rubocop_cache` acelera runs subsecuentes de 30s a <5s.
+
+##### Cambios
+
+En `.github/workflows/main.yml`, agregar step antes de `rubocop`:
+```yaml
+- uses: actions/cache@v4
+  with:
+    path: ~/.cache/rubocop_cache
+    key: rubocop-${{ matrix.ruby }}-${{ hashFiles('.rubocop.yml') }}
+    restore-keys: rubocop-${{ matrix.ruby }}-
+```
+
+##### Criterios de aceptación
+
+- [ ] Runs subsecuentes (sin cambios en `.rubocop.yml`) bajan tiempo de rubocop step.
+- [ ] Cache invalida correctamente si `.rubocop.yml` cambia.
+
+##### Riesgos
+
+- Ninguno significativo.
+
+---
+
+#### Item 23 — Coverage ≥ 90% en SimpleCov
+
+**Estado:** `[ ]`
+**Prioridad:** P2
+**Tipo:** `test`
+**Compatibilidad:** N/A
+**Estimación:** M (4-6h)
+**Release sugerido:** v0.3.1
+**Origen:** Review big-pickle 2026-04-14.
+
+##### Contexto
+
+v0.2.0 dejó `minimum_coverage 80` con cobertura real ~97%. Subir el umbral a 90% previene regresiones futuras y obliga a cubrir ramas nuevas.
+
+##### Cambios
+
+1. `spec/spec_helper.rb`: cambiar `minimum_coverage 80` → `minimum_coverage 90`.
+2. Correr `bundle exec rspec` y verificar qué ramas quedan descubiertas.
+3. Agregar tests para cubrirlas (típicamente branches de error, edge cases de `safe_log` y `destroy_partitions`).
+
+##### Criterios de aceptación
+
+- [ ] `SimpleCov` reporta ≥ 90% líneas.
+- [ ] Ningún archivo de `lib/` con cobertura < 80%.
+- [ ] CI falla si alguna corrida baja del 90%.
+
+##### Riesgos
+
+- Puede requerir tests con Postgres real para cubrir `purge_from_postgres` completo — decidir si entran en el suite default o bajo tag `:integration`.
+
+---
+
+#### Item 24 — CI badge en README
+
+**Estado:** `[ ]`
+**Prioridad:** P3
+**Tipo:** `docs`
+**Compatibilidad:** N/A
+**Estimación:** XS (10min)
+**Release sugerido:** v0.3.1
+**Origen:** Review big-pickle 2026-04-14.
+
+##### Contexto
+
+README no muestra estado de CI. Un badge al inicio confirma visualmente que la gema es activamente testeada.
+
+##### Cambios
+
+Agregar al tope del README después del título:
+```markdown
+# DataDrain
+
+[![CI](https://github.com/gedera/data_drain/actions/workflows/main.yml/badge.svg)](https://github.com/gedera/data_drain/actions/workflows/main.yml)
+```
+
+Opcionalmente badges adicionales:
+- Cobertura (requiere integrar con CodeClimate o Codecov)
+- Version de Gem (si se publica en RubyGems)
+
+##### Criterios de aceptación
+
+- [ ] Badge se ve verde en main.
+- [ ] Badge apunta al workflow correcto.
+
+---
+
 ## Riesgos transversales
 
 ### Coordinación con Gemini