data_drain 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff8a69a33cb9dc44d9252792b7b6531707ba11f330c81cc9c27f4613e74ef0be
-  data.tar.gz: c6503db21d32c3ea60fe2be121d6422fb5305bf222b07f200cc81364e7b9c152
+  metadata.gz: c92c85e6232344565dc090539d3d58aa47904ca1e454b696ba4eba12e2648881
+  data.tar.gz: 1b3332ac50288dfd6793aed0c51ab8fa49d8dc309f7bc8dd4a642ecffd97e3cd
 SHA512:
-  metadata.gz: b916b2ee021d9cf6060ae00b2c5f924811b3f42ef7d475b329960be4b80035e1a3348dfb28da49d0a8fc8ec5e6ec749d9145da643f95f18f952b8be1e4c45bde
-  data.tar.gz: 39c9d09e004e75a84f135651f12d7b0eec810f39083fd565ac7edeca3affc83a31f08db4b187312b85121e9284ddb50a4b3f6e4c2cd8d6fb46ff0e7e5888af3a
+  metadata.gz: d0cecb3d168ad96943b9cc70eb936e9b95e92d03dc0bd08ed5996ac1967ef627191802892097abf3b094d5b59515c150ca8edc4ffcefe13be8b4a2d7721a180a
+  data.tar.gz: 45018ca7e4287bf055cb7060e5720f83da318bd7c9ad44a30d8e832972feb1eb99d29286a9813128d4f84171d4c032e12f9a4f4dd7cc0022b36e44a3098d91c8

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## [Unreleased]
 
+## [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/docs/execution/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