data_drain 0.4.0 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff8a69a33cb9dc44d9252792b7b6531707ba11f330c81cc9c27f4613e74ef0be
-  data.tar.gz: c6503db21d32c3ea60fe2be121d6422fb5305bf222b07f200cc81364e7b9c152
+  metadata.gz: 036367c9d2512c4a9a2785bbef6efeaaf9ee013ee31c013e1527001f91f22d65
+  data.tar.gz: c7dc050b51c3024ad9e2e62ae57e28bb549fee9a0341aea5ee524d4b55a07da5
 SHA512:
-  metadata.gz: b916b2ee021d9cf6060ae00b2c5f924811b3f42ef7d475b329960be4b80035e1a3348dfb28da49d0a8fc8ec5e6ec749d9145da643f95f18f952b8be1e4c45bde
-  data.tar.gz: 39c9d09e004e75a84f135651f12d7b0eec810f39083fd565ac7edeca3affc83a31f08db4b187312b85121e9284ddb50a4b3f6e4c2cd8d6fb46ff0e7e5888af3a
+  metadata.gz: 9ed7fb071a8d1f0c103c44c402279b9b575b535944a21db6f260b5d2aa4da2675f56095a9d79d1054c8e4c48ac578a955673befde82a84ca030ee508adf11e8e
+  data.tar.gz: f4c3665f97d5f4c287f70a715bd4fc36264bae977f868bb5f062bade177527cb6bfb10dbaf6c83fb6280ab2fce4787bf8abc1789fa9fb5893ac99f3a0a2b1ee0

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 ## [Unreleased]
 
+## [0.5.1] - 2026-04-15
+
+### Docs
+
+- `skill/references/eventos-telemetria.md`: nuevos eventos `script_uploaded` y `script_upload_error`.
+- `README.md`: ejemplos de `script_path` en GlueRunner y observabilidad.
+
+## [0.5.0] - 2026-04-15
+
+### Features
+
+- `Storage::S3#upload_file` y `Storage::Local#upload_file`: primitiva para subir archivos al storage configurado. (item 37)
+- `GlueRunner.upload_script(local_path:, bucket:, folder:, filename:)`: sube script Python local a S3 usando el `Storage::S3` adapter existente. Emite `glue_runner.script_uploaded` (INFO) y `glue_runner.script_upload_error` (ERROR). (item 37)
+- `GlueRunner.create_job` y `GlueRunner.ensure_job` aceptan `script_path:` + `script_bucket:` + `script_folder:` + `script_filename:` para subir scripts locales automáticamente. Si se usa `script_location:`, comportamiento idéntico al anterior. (item 37)
+
+### Docs
+
+- `docs/glue-jobs-lifecycle.md`: sección "Subir scripts locales" con patrón completo, permisos IAM mínimos y limitación de concurrencia.
+- `docs/glue_pyspark_example.py`: ejemplo de uso con `script_path`.
+
+### Notas
+
+- **Upload NO es idempotente en sentido estricto:** `put_object` sobrescribe siempre. Documentado.
+- `upload_script` requiere `storage_mode = :s3`. En `:local` levanta `ConfigurationError`.
+
 ## [0.4.0] - 2026-04-15
 
 ### Features

data/README.md

@@ -115,11 +115,13 @@ DataDrain::GlueRunner.job_exists?("my-glue-export-job")
 job = DataDrain::GlueRunner.get_job("my-glue-export-job")
 # => Aws::Glue::Types::Job (Name, Command, DefaultArguments, etc.)
 
-# Crear un job
+# Crear un job con script local (v0.5.0+)
 job = DataDrain::GlueRunner.create_job(
   "my-glue-export-job",
   role_arn: "arn:aws:iam::123:role/GlueServiceRole",
-  script_location: "s3://my-bucket/scripts/export.py",
+  script_path: "scripts/glue/export.py",  # local → S3 automático
+  script_bucket: "my-bucket",
+  script_folder: "scripts",
   default_arguments: { "--extra-files" => "s3://my-bucket/scripts/udf.py" },
   timeout: 1440,
   max_retries: 2
@@ -129,8 +131,9 @@ job = DataDrain::GlueRunner.create_job(
 job = DataDrain::GlueRunner.ensure_job(
   "my-glue-export-job",
   role_arn: "arn:aws:iam::123:role/GlueServiceRole",
-  script_location: "s3://my-bucket/scripts/export.py",
-  timeout: 1440
+  script_path: "scripts/glue/export.py",
+  script_bucket: "my-bucket",
+  script_folder: "scripts"
 )
 
 # Eliminar un job
@@ -198,6 +201,7 @@ ArchivedVersion.destroy_all(year: 2024, month: 3)    # un mes globalmente
 ```
 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.purge_heartbeat table=versions batches_processed_count=100 rows_deleted_count=500000
+component=data_drain event=glue_runner.script_uploaded local_path=scripts/glue/export.py s3_path=s3://my-bucket/scripts/export.py bytes=4521
 component=data_drain event=glue_runner.failed job=my-export-job run_id=jr_abc123 status=FAILED duration_s=301.0
 ```
 

data/docs/execution/archives/v0.5.0-OBSERVACIONES.md

@@ -0,0 +1,167 @@
+# Observaciones — v0.5.0
+
+Generado por: big-pickle
+Fecha: 2026-04-15
+Revisor: big-pickle (análisis de código real vs plan v2)
+
+---
+
+## Observación 1 — Breaking change implícito en `create_job`/`ensure_job`
+
+**Severidad:** Alta
+
+**Hallazgo:** El plan dice "Breaking: ninguno", pero la firma cambia:
+
+```ruby
+# ACTUAL (script_location: es keyword REQUIRED)
+def self.create_job(job_name, role_arn:, script_location:, ...)
+
+# PLAN (script_location: nil con default, role_arn: sigue required → SyntaxError)
+def self.create_job(job_name, role_arn:, script_location: nil, script_path: nil, ...)
+# required keyword argument cannot have a default value
+```
+
+**Fix requerido:** `role_arn:` también debe tener default `nil`. Esto es técnicamente un cambio de API (aunque todos los callers usan kwargs, así que no rompe en la práctica).
+
+**Estado:** Verificar en pre-flight checklist.
+
+---
+
+## Observación 2 — `s3_client` existe y usa credential chain
+
+**Severidad:** Confirmada OK
+
+**Verificado en** `lib/data_drain/storage/s3.rb:44-50`:
+
+```ruby
+def s3_client
+  Aws::S3::Client.new(
+    region: @config.aws_region,
+    access_key_id: @config.aws_access_key_id,
+    secret_access_key: @config.aws_secret_access_key
+  )
+end
+```
+
+El SDK acepta `nil` en las credenciales y resuelve via credential chain automáticamente. Plan OK.
+
+---
+
+## Observación 3 — `changed_fields` incluye comparación de `script_location`
+
+**Severidad:** Confirmada OK
+
+**Verificado en** `lib/data_drain/glue_runner.rb:174-175`:
+
+```ruby
+changed << :command if current.command.name != desired[:command_name] ||
+                       current.command.script_location != desired[:script_location]
+```
+
+El `script_location` se compara dentro de `:command`. Cuando `ensure_job` construya `desired[:script_location] = final_script` (resultado del upload), el diffing funcionará correctamente.
+
+---
+
+## Observación 4 — `Storage::Local#upload_file` requiere directorio manual
+
+**Severidad:** Media
+
+**Hallazgo:** No existe `Configuration#local_bucket`. El `bucket` en `Storage::Local#upload_file` es un directorio local pasado por el caller.
+
+**Plan OK:** el plan ya documenta esto en la firma del método. Confirmar en pre-flight checklist que el implementador lo sepa.
+
+---
+
+## Observación 5 — `resolve_script_location` es `private_class_method` pero llamado desde métodos públicos
+
+**Severidad:** Info
+
+**Hallazgo:** Ruby permite que métodos públicos de clase llamen `private_class_method`. No hay error. El plan está correcto. Solo documentar para claridad del implementador.
+
+---
+
+## Observación 6 — `spec/data_drain/storage/local_spec.rb` no existe
+
+**Severidad:** Media
+
+**Hallazgo:** El plan propone specs para `Storage::Local#upload_file` pero el archivo no existe. Hay que crearlo en la fase correspondiente.
+
+**Acción:** Crear `spec/data_drain/storage/local_spec.rb` con los specs del plan.
+
+---
+
+## Observación 7 — `spec/data_drain/glue_runner_spec.rb` tiene specs existentes de `create_job`/`ensure_job`
+
+**Severidad:** Info
+
+**Hallazgo:** Ya existen specs en `spec/data_drain/glue_runner_spec.rb:161+` para `create_job` y `ensure_job`. Los specs nuevos del plan deben ser adicionales a los existentes, no reemplazarlos. Verificar que los tests existentes sigan pasando.
+
+---
+
+## Observación 8 — Test de `storage_mode = :local` requiere `reset_adapter!`
+
+**Severidad:** Baja
+
+**Hallazgo:** El test "levanta ConfigurationError si storage_mode es :local" cambia `storage_mode` globalmente. Debe hacer `reset_adapter!` en el `after` block para no contaminar otros tests.
+
+**Plan OK:** el plan menciona esto, solo confirmar que se implemente correctamente.
+
+---
+
+## Observación 9 — Campo `bytes` en evento observabilidad
+
+**Severidad:** Baja
+
+**Hallazgo:** El plan usa `bytes` como nombre de campo en `glue_runner.script_uploaded`. Según Wispro-Observability-Spec v1, los contadores deben usar la palabra `count` en la key.
+
+**Alternativas:**
+- `byte_count` (más consistente con spec)
+- `file_size` (más semántico)
+
+**Decisión:** Mantener `bytes` por convención established en contexto AWS/S3 (donde `ContentLength` se reporta como `bytes`). Bajo riesgo.
+
+---
+
+## Observación 10 — `content_type: "text/x-python"` es explícito
+
+**Severidad:** Info
+
+**Verificado:** S3 infiere correctamente `text/x-python` para archivos `.py` si no se provee. El plan usa explícito para mayor predictibilidad. OK.
+
+---
+
+## Observación 11 — Concurrencia sin lock
+
+**Severidad:** Info
+
+**Documentado en** plan. `put_object` sobrescribe siempre. Scripts PySpark son pequeños, riesgo bajo. Items 38 y 39 definidos como follow-ups.
+
+---
+
+## Resumen para el implementador
+
+| # | Severidad | Acción |
+|---|-----------|--------|
+| 1 | Alta | Clarificar en plan que `role_arn:` también tiene default `nil` |
+| 2 | Confirmada OK | `s3_client` existe, credential chain OK |
+| 3 | Confirmada OK | `changed_fields` compara `script_location` |
+| 4 | Media | Documentar que Local requiere directorio destino manual |
+| 5 | Info | `private_class_method` permitido en Ruby de clase pública |
+| 6 | Media | Crear `spec/data_drain/storage/local_spec.rb` |
+| 7 | Info | Tests existentes de `create_job`/`ensure_job` no se tocan |
+| 8 | Baja | Test de `storage_mode = :local` con `reset_adapter!` |
+| 9 | Baja | Mantener `bytes` (convención AWS) |
+| 10 | Info | `content_type` explícito OK |
+| 11 | Info | Concurrencia documentada, items 38/39 follow-ups |
+
+---
+
+## Checklist de pre-implementación
+
+- [ ] Clarificar que `role_arn:` también tiene default `nil` en el plan
+- [ ] Verificar `s3_client` existe en `Storage::S3` ✅
+- [ ] Verificar `changed_fields` incluye `script_location` ✅
+- [ ] Confirmar que no hay `Configuration#local_bucket` existente
+- [ ] Crear `spec/data_drain/storage/local_spec.rb`
+- [ ] Ejecutar `bundle exec rspec` antes de empezar para tener baseline verde
+- [ ] Ejecutar `bundle exec rubocop` antes de empezar para tener baseline verde