docker-swarm 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e27b0beec0476baca5222a41e38aa7b11998641c39cc15eeb16390343e8364b
-  data.tar.gz: 61faa29cc088ea4286fb864b0b2237bfd104059236e4b748168344148931ab9e
+  metadata.gz: 824016bc8286430e75b85e1daa74f5fa30039667230585bcd548ac76afacd1da
+  data.tar.gz: c8d56047e0e282aa35dcdd3998780f0bfcd7c5ba1be6464068bff91b99276934
 SHA512:
-  metadata.gz: 01b0508429e58f4878e8aa5bba874e67d57e87bf691c31ebc144da22cbeb86d89dc438f268ab85374009949e28296546747be6e0b03b718ddaa4a2df6f1e521b
-  data.tar.gz: bc02c9d23be1bacc5a8f7bee2e105cf0fdc90a75fa96d4257c41467bff9b7369a031c6c21644ac3cfc84159910bd10657371b2b9407d4c9bb270cf081d52af23
+  metadata.gz: bc733a3eb22266fe1ca82dcfbc56445bf0118a8fd9c077cf697849fe15004463571c94248cd48f236d42a67d2ccbb415419e8e1a05096842bb72fec035d63fc9
+  data.tar.gz: e65002ee881d436b549918321b415b3acc224679c40690b08651ff48960f3d8c6ec3f00849ffc7830c91a8ab00d834940299e355e4225a814e231abc51a133c5

data/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 All notable changes to this project will be documented in this file.
 
+## [Unreleased]
+
+## [0.10.0] — 2026-08-05
+
+### Nuevas funcionalidades
+- **`Service.where(status: true)` puebla `ServiceStatus`** (#22). `status` es un query param **propio** de `GET /services` (Engine API ≥ v1.41), no un filtro, y hasta ahora la gema no tenía forma de mandarlo: caía en el JSON de `?filters=`, donde el Engine no lo acepta como filtro de `/services`. Con esto cada elemento del listado trae `ServiceStatus` (`RunningTasks` · `DesiredTasks` · `CompletedTasks`), que es el **único** lugar donde el Engine publica el deseado de un service en modo `global` — un replicado lo expone en `Spec.Mode.Replicated.Replicas`, pero para un global ese campo no existe. Sin `DesiredTasks` un global corriendo en 2 de 3 nodos elegibles es indistinguible de uno sano: solo se detecta el caso extremo de cero tasks — @Pslp
+  - La whitelist de query params del listado sale a `Base.index_query_params` (default `%i[all force limit since before]`, **override por modelo**), y `Service` la extiende con `:status`. Se resuelve así, y **no** subiendo `status` a `Base`, porque en `/containers/json` `status` **sí** es un filtro válido (`running`, `exited`, …): globalizarlo lo sacaría del `?filters=` y rompería `Container.where(status: "running")`. Hay un spec de regresión que lo fija.
+  - **Compatible hacia atrás:** sin pasar `status` el listado no cambia. Y **degrada en silencio**: la gema no fija `?version=`, así que en un Engine por debajo de v1.41 el parámetro se ignora sin error y `ServiceStatus` llega ausente → el consumidor tiene que tolerar `nil`, no hay señal de "no soportado".
+  - **Trampa del consumidor:** en un service `global` recién creado `DesiredTasks` vale **0** — el Engine publica los contadores antes de evaluar los nodos elegibles y lo completa ~1s después (medido contra un Engine `1.54`). En esa ventana `RunningTasks == DesiredTasks == 0`, así que comparar los dos números para decidir salud miente; `DesiredTasks.positive?` va como precondición. Documentado en `docs/consumed/` y `skill/SKILL.md`.
+
 ## [0.9.0] — 2026-08-03
 
 ### Nuevas funcionalidades

data/README.md

@@ -43,7 +43,7 @@ Documentación normada (RFC-001) por capa:
 |---|---|---|
 | Datos | — | `n/a` (gema sin DB) |
 | Glosario | [`docs/glossary/glossary.md`](docs/glossary/glossary.md) | completo (primitivas + arquitectura interna) |
-| Comportamiento | [`docs/behavior/behavior.md`](docs/behavior/behavior.md) | backfill on-demand + incremental (11 flujos) |
+| Comportamiento | [`docs/behavior/behavior.md`](docs/behavior/behavior.md) | backfill on-demand + incremental (12 flujos) |
 | Configuración | [`docs/config/configuracion.md`](docs/config/configuracion.md) | inventario base (7 opciones, sin env vars) |
 | Interfaz | [`docs/interface/interface.md`](docs/interface/interface.md) | API Ruby pública (11 modelos + Base + concerns) |
 | Topología | [`docs/topology/topology.md`](docs/topology/topology.md) | 3 deps runtime + grafo de contexto |

data/docs/behavior/behavior.md

@@ -1,6 +1,6 @@
 # Comportamiento — docker-swarm
 
-> meta: artefacto · RFC-007 · generado dev-enrich · anclado a `v0.9.0` · cobertura: 11 flujos load-bearing (8 backfill inicial + 3 nuevos: auth de registry privado, `Image.pull` síncrono, `Container.create`)
+> meta: artefacto · RFC-007 · generado dev-enrich · anclado a `v0.10.0` · cobertura: 12 flujos load-bearing (8 backfill inicial + 4 nuevos: auth de registry privado, `Image.pull` síncrono, `Container.create`, partición query params/filters del listado)
 
 ## 1. Resumen
 
@@ -8,7 +8,7 @@ Flujos de ejecución load-bearing de `docker-swarm`: cómo se materializan en ru
 
 ## 2. Cobertura declarada
 
-### Documentados (11)
+### Documentados (12)
 
 1. `Service.create` + reload
 2. `Service.update` con `Version.Index`
@@ -21,6 +21,7 @@ Flujos de ejecución load-bearing de `docker-swarm`: cómo se materializan en ru
 9. Auth de registry privado (`RegistryAuth.resolve` → `X-Registry-Auth` / `registryAuthFrom`)
 10. `Image.pull` síncrono (stream NDJSON → error tipado → resultado explícito)
 11. `Container.create` con nombre por query string (`create_query_params`)
+12. `Model.where` — partición query params propios vs. `?filters=` (`index_query_params`)
 
 ### No documentados (ausencia ≠ inexistencia, RFC-007)
 
@@ -327,9 +328,36 @@ sequenceDiagram
 - **El atributo se excluye del payload**, no se duplica: mandarlo en los dos lados no da error pero deja el body con una clave que Docker ignora.
 - Hereda el flujo §3.1: `valid?` antes del POST, `reload` después, y **sin retry** por ser `POST` (§3.5). Si el `create` falla por `Communication`, el caller decide — con nombre determinista puede adoptar el existente en el reintento.
 
+### 3.12 `Model.where` — partición query params propios vs. `?filters=`
+
+El Engine parte los parámetros de un listado en dos grupos, y la gema tiene que decidir a cuál va cada clave **antes** de armar la URL. `Base.index_query_params` es esa declaración; todo lo que no esté ahí se serializa dentro del JSON de `?filters=`.
+
+La trampa: un query param propio que el modelo no declaró **no llega**. Viaja dentro de `filters`, donde el Engine lo rechaza o lo ignora según el recurso — no hay error que diga "esa clave iba en la URL".
+
+```mermaid
+flowchart TD
+    A["Model.where(status: true, name: 'web')"] --> B["_fetch_all"]
+    B --> C{"clave ∈ index_query_params?"}
+    C -->|sí| D["query params propios<br/>{ status: true }"]
+    C -->|no| E["docker_filters<br/>{ name: 'web' }"]
+    E --> F["downcase claves + Array(valor)<br/>→ JSON"]
+    D --> G["query = { status: true,<br/>filters: '{\"name\":[\"web\"]}' }"]
+    F --> G
+    G --> H["GET /services?status=true&filters=..."]
+    H --> I["array de Hash → instancias"]
+```
+
+**Notas load-bearing:**
+- **La lista es por modelo, no global.** `Base` declara `%i[all force limit since before]`; `Service` la extiende con `:status`. Deliberadamente no se generaliza: `status` es query param propio en `/services` pero **filtro válido** en `/containers/json` (`running`, `exited`, …), así que subirlo a `Base` lo sacaría del `?filters=` donde containers lo necesita. Hay un spec de regresión que lo fija.
+- **`Service.where(status: true)` es lo que habilita leer `ServiceStatus`** (`RunningTasks` · `DesiredTasks` · `CompletedTasks`), única superficie donde el Engine publica el **deseado** de un service en modo `global` — un replicado lo tiene en `Spec.Mode.Replicated.Replicas`, un global no tiene ese campo. Sin eso, un global corriendo en 2 de 3 nodos elegibles es indistinguible de uno sano: se ven las tasks que corren, no contra qué comparar.
+- **Requiere API ≥ v1.41 y degrada en silencio.** La gema no fija `?version=` (§3.5 / [`docs/consumed/`](../consumed/docker-engine-api.md)); en un Engine anterior el parámetro se ignora sin error y `ServiceStatus` llega ausente → el consumidor tolera `nil`, no hay señal de "no soportado".
+- **`DesiredTasks` arranca en 0 en un `global` recién creado** y el Engine lo completa después de evaluar los nodos (~1s, medido). En esa ventana `RunningTasks == DesiredTasks == 0`: el deseado no está calculado, así que comparar los dos números miente. Precondición de salud = `DesiredTasks.positive?`. Detalle en [`docs/consumed/`](../consumed/docker-engine-api.md).
+- **Las claves se matchean como símbolos.** `where("status" => true)` cae en `docker_filters` (`slice(:status)` no matchea la string). Comportamiento preexistente y común a todos los query params del listado, no introducido por `:status`.
+- Sin filtros no hay query: `all` manda `query_params: {}` — el listado por default no cambió.
+
 ## 4. Cobertura y fronteras
 
-- **Cobertura (RFC-007 backfill on-demand + incremental):** 8 flujos load-bearing en el backfill inicial + 2 agregados con el soporte de auth de registry privado (auth de registry privado, `Image.pull` síncrono) + 1 con el `create` de containers = 11. Esta gema es chica; el backfill completo era factible y se hizo, y a partir de ahí se acreta por PR.
+- **Cobertura (RFC-007 backfill on-demand + incremental):** 8 flujos load-bearing en el backfill inicial + 2 agregados con el soporte de auth de registry privado (auth de registry privado, `Image.pull` síncrono) + 1 con el `create` de containers + 1 con la partición query params/filters del listado = 12. Esta gema es chica; el backfill completo era factible y se hizo, y a partir de ahí se acreta por PR.
 - **Frontera con glosario:** términos (Service, Spec, Version.Index, etc.) viven en [`docs/glossary/glossary.md`](../glossary/glossary.md). Esta capa documenta secuencias, no significado.
 - **Frontera con configuración:** `DockerSwarm.configure` es boot, no flujo de negocio. No se diagrama.
 - **No localizable / fuera de alcance:**

data/docs/consumed/docker-engine-api.md

@@ -1,6 +1,6 @@
 # Dependencias consumidas — docker-swarm
 
-> meta: artefacto · RFC-018 · generado arch-structure + enriquecido arch-enrich · anclado a `v0.9.0` · cobertura: superficie del Docker Engine API consumida por la gema (`api.rb` ENDPOINTS + `connection.rb`); §c/§e enriquecidas 1/1
+> meta: artefacto · RFC-018 · generado arch-structure + enriquecido arch-enrich · anclado a `v0.10.0` · cobertura: superficie del Docker Engine API consumida por la gema (`api.rb` ENDPOINTS + `connection.rb`); §c/§e enriquecidas 1/1
 
 ## 1. Resumen
 
@@ -39,7 +39,7 @@ Subset que la gema invoca, derivado de `Api::ENDPOINTS` (`api.rb:5-72`). `destin
 | nodes | destroy | `DELETE nodes/%<id>s` | — / — |
 | tasks | index / show | `GET tasks`, `GET tasks/%<id>s` | `?filters=` / array \| Hash |
 | tasks | logs | `GET tasks/%<id>s/logs` | `?stdout/stderr/...` / stream multiplexado (demux en el cliente) |
-| services | index / show | `GET services`, `GET services/%<id>s` | `?filters=` / array \| Hash |
+| services | index / show | `GET services`, `GET services/%<id>s` | `?filters=` + `?status=` (query propio, **no** filtro; ≥ v1.41) / array \| Hash; con `?status=true` cada elemento trae `ServiceStatus` |
 | services | create | `POST services/create` | payload (Spec aplanado) + header `X-Registry-Auth` (opcional, registry privado) / `{ID}` |
 | services | update | `POST services/%<id>s/update` | `?version=` (+ `?registryAuthFrom=` opcional: `spec`\|`previous-spec`) + payload + header `X-Registry-Auth` (opcional; excluyente con `registryAuthFrom`) / — |
 | services | destroy | `DELETE services/%<id>s` | — / — |
@@ -61,6 +61,22 @@ Subset que la gema invoca, derivado de `Api::ENDPOINTS` (`api.rb:5-72`). `destin
 
 Serialización: request body no-String → JSON (`Content-Type: application/json`) vía `Middleware::RequestEncoder`; response `application/json` → `HashWithIndifferentAccess` recursivo vía `Middleware::ResponseJSONParser`.
 
+**Query params propios vs. `?filters=` (listados).** El Engine parte los parámetros de un listado en dos: query params propios de la ruta (`?limit=`, `?all=`, `?status=`) y el JSON de `?filters=`. La gema declara los primeros en `Base.index_query_params` (override por modelo); **todo lo demás se serializa como filtro**. Un query param propio no declarado ahí no llega nunca: viaja dentro del JSON de `filters` y el Engine lo rechaza (si valida la clave) o lo ignora.
+
+Los nombres **no** son globales — el mismo `status` es query param propio en `/services` y filtro válido en `/containers/json` (`running`, `exited`, …). De ahí que la lista sea por modelo y no una whitelist única.
+
+**`?status=true` en `/services`** (API ≥ v1.41) agrega a cada elemento:
+
+```json
+{ "ServiceStatus": { "RunningTasks": 2, "DesiredTasks": 3, "CompletedTasks": 0 } }
+```
+
+Es la **única** superficie donde el Engine publica el deseado de un service en modo `global`: un replicado lo expone en `Spec.Mode.Replicated.Replicas`, pero para un global ese campo no existe (el deseado es "una task por nodo elegible"). Sin `DesiredTasks` no hay número contra el cual comparar las tasks que corren.
+
+Como la gema no fija `?version=`, la versión efectiva la decide el host (ver arriba): en un Engine por debajo de v1.41 el parámetro se **ignora sin error** y `ServiceStatus` llega ausente. El consumidor tiene que tolerar `nil` — no hay señal de "no soportado".
+
+**`DesiredTasks: 0` no significa "sin nodos elegibles".** En un service `global` recién creado el Engine publica el objeto con los tres contadores en **0** y recién después evalúa los nodos (medido contra un Engine `1.54`, swarm de un nodo: `DesiredTasks` pasa de 0 a 1 en ~1s). O sea que hay una ventana en la que `RunningTasks == DesiredTasks == 0` — un consumidor que compare los dos números lee "sano" (0 de 0) o "degradado total" según cómo ordene la comparación, y en ninguno de los dos casos es cierto: el deseado todavía no está calculado. Para decidir salud hace falta `DesiredTasks.positive?` como precondición, no como resultado.
+
 **Streams de logs (`containers`/`services`/`tasks` → `logs`).** Sin TTY el Engine multiplexa: 8 bytes de cabecera por frame (1 tipo de stream · 3 de relleno en cero · 4 de tamaño big-endian). `Middleware::LogStreamDemuxer` los saca, así que `Loggable#logs` entrega texto limpio.
 
 El `Content-Type` **no alcanza** para decidir. `application/vnd.docker.multiplexed-stream` existe **desde la API v1.42**; su entrada de changelog dice, textual:

data/docs/interface/interface.md

@@ -1,6 +1,6 @@
 # Interfaz — docker-swarm
 
-> meta: artefacto · RFC-004 · generado arch-structure · anclado a `v0.9.0` · cobertura: API Ruby pública de la gema (`lib/docker_swarm/**`); símbolos internos marcados en §4
+> meta: artefacto · RFC-004 · generado arch-structure · anclado a `v0.10.0` · cobertura: API Ruby pública de la gema (`lib/docker_swarm/**`); símbolos internos marcados en §4
 
 ## 1. Resumen
 
@@ -15,7 +15,7 @@ Proyección RBS-conceptual: `símbolo · tipo · nota` (raíz → profundidad
 | símbolo | tipo | nota |
 |---|---|---|
 | `DockerSwarm` | módulo | namespace raíz |
-| `DockerSwarm::VERSION` | constante | `"0.8.0"` (`version.rb`) |
+| `DockerSwarm::VERSION` | constante | `"0.10.0"` (`version.rb`) |
 | `DockerSwarm.configuration` | attr (r/w) | instancia de `Configuration`; lazy-init en `configure`/`connection` |
 | `DockerSwarm.configure { \|config\| ... }` | método de módulo | crea/yields `Configuration`; aplica `log_level` al logger; resetea la conexión memoizada |
 | `DockerSwarm.connection` | método de módulo | `Connection` memoizada (auto-`configure` si falta) |
@@ -48,6 +48,7 @@ Inventario completo de opciones: [`docs/config/configuracion.md`](../config/conf
 | `.all(filters = {})` | método de clase | `GET index`; mapea a instancias; aplica `root_key`; `[]` si vacío |
 | `.find(id)` | método de clase | `GET show`; `nil` si `Errors::NotFound` |
 | `.where(filters)` | método de clase | alias de `all` |
+| `.index_query_params` | método de clase | `%i[all force limit since before]` por default; override por modelo (`+ :status` en `Service`). Claves que viajan como **query params propios** del listado; **todo lo no declarado se serializa dentro del JSON de `?filters=`** — si tampoco es filtro válido del recurso, el Engine lo rechaza o lo ignora |
 | `#initialize(attributes = {})` | método de instancia | `assign_attributes` si presente |
 | `#assign_attributes(new_attributes)` | método de instancia | normaliza `Id`→`ID`; `deep_merge` del campo `Spec`; `ArgumentError` si no es Hash |
 | `#attributes` | método de instancia | `instance_values` sin internos de ActiveModel |
@@ -76,7 +77,7 @@ Inventario completo de opciones: [`docs/config/configuracion.md`](../config/conf
 
 | símbolo | tipo | concerns + métodos propios |
 |---|---|---|
-| `DockerSwarm::Service` | clase < Base | Creatable, Updatable, Deletable, Loggable; `#restart` (incrementa `TaskTemplate.ForceUpdate`); `create`/`update` aceptan `registry_auth:` (+ `update`: `registry_auth_from:`) para auth de registry privado |
+| `DockerSwarm::Service` | clase < Base | Creatable, Updatable, Deletable, Loggable; `#restart` (incrementa `TaskTemplate.ForceUpdate`); `create`/`update` aceptan `registry_auth:` (+ `update`: `registry_auth_from:`) para auth de registry privado; `.index_query_params` agrega `:status` → `where(status: true)` puebla `ServiceStatus` (`RunningTasks`/`DesiredTasks`/`CompletedTasks`), único lugar donde el Engine publica el deseado de un service `global` |
 | `DockerSwarm::Node` | clase < Base | Updatable, Deletable (sin `create`: los nodos se unen fuera de la gema) |
 | `DockerSwarm::Task` | clase < Base | Loggable (read-only; generadas por el orquestador) |
 | `DockerSwarm::Container` | clase < Base | Creatable, Deletable, Loggable; `#start`, `#stop`; `.create_query_params == %w[name]` (el Engine toma el nombre por query string — en el body lo descarta en silencio y el container nace con nombre aleatorio). El `create` **no** es gap intencional desde ADR-025 cláusula 1 |

data/docs/release/release.md

@@ -1,6 +1,6 @@
 # Release — docker-swarm
 
-> meta: artefacto · RFC-014 · generado arch-structure + enriquecido arch-enrich · anclado a `v0.9.0` · cobertura: §a estructura completa (versión · changelog · build-trigger · patrón); §b enrich completa (deploy · rollback · ambientes · dueño)
+> meta: artefacto · RFC-014 · generado arch-structure + enriquecido arch-enrich · anclado a `v0.10.0` · cobertura: §a estructura completa (versión · changelog · build-trigger · patrón); §b enrich completa (deploy · rollback · ambientes · dueño)
 
 ## 1. Resumen
 
@@ -12,7 +12,7 @@ Gema Ruby publicada en RubyGems. Release por **tag `v*`**: el push del tag dispa
 
 | campo | valor | fuente |
 |---|---|---|
-| versión actual | `0.9.0` | `lib/docker_swarm/version.rb` (`DockerSwarm::VERSION`) |
+| versión actual | `0.10.0` | `lib/docker_swarm/version.rb` (`DockerSwarm::VERSION`) |
 | esquema de versión | SemVer (`MAJOR.MINOR.PATCH`) | `CHANGELOG.md` (breaking/mejoras/correcciones por bump) |
 | artefacto liberado | gema `docker-swarm` a RubyGems | `docker-swarm.gemspec` (`spec.name`), `.github/workflows/release.yml` |
 | changelog | `CHANGELOG.md`, formato Keep a Changelog, entradas fechadas por versión | `CHANGELOG.md` |

data/docs/test/testing.md

@@ -1,6 +1,6 @@
 # Test — docker-swarm
 
-> meta: artefacto · RFC-013 · generado arch-structure + enriquecido arch-enrich · anclado a `v0.9.0` · cobertura: estructura de la suite (`spec/`, `.github/workflows/main.yml`); §e enriquecida, §f enriquecida, §g `unknown` (sin incidentes registrados), §h enriquecida
+> meta: artefacto · RFC-013 · generado arch-structure + enriquecido arch-enrich · anclado a `v0.10.0` · cobertura: estructura de la suite (`spec/`, `.github/workflows/main.yml`); §e enriquecida, §f enriquecida, §g `unknown` (sin incidentes registrados), §h enriquecida
 
 ## 1. Resumen
 
@@ -54,6 +54,7 @@ Ninguna. No hay `SimpleCov`/`.simplecov` ni umbral declarado en el repo (verific
 - CRUD genérico de `config`, `secret`, `volume`: vía `shared_crud_spec` (`it_behaves_like "a crud resource"`) — no tienen spec dedicado pero **sí** están cubiertos (create/find/destroy). `image` salió del CRUD genérico (su `create` era un pull) → tiene spec propio (abajo).
 - `image`: `image_spec` (dedicado) — `Image.pull` (stream NDJSON, extracción de digest del frame `Digest:`, error tipado ante `error`/`errorDetail`, forma polimórfica del body) + `Deletable` y listado.
 - Auth de registry privado: `registry_auth_spec` (helper `RegistryAuth`: exclusión mutua `registry_auth`/`registry_auth_from`, enum del `from`, traducción a header/query) + bloque registry-auth en `service_spec` (create/update, no-exposición de la credencial en logs).
+- Partición query params propios vs. `?filters=` del listado (`index_query_params`): `base_spec` (default, override, partición mixta), `service_spec` (`status: true` → query param; `ServiceStatus` expuesto y tolerancia a su ausencia), `container_spec` (**regresión**: `status` sigue viajando como filtro). Integration: `services_spec` verifica contra el daemon que `ServiceStatus` aparece **solo** con `status: true`, y un `context` en modo **`global`** pinnea el caso que justifica la feature — `DesiredTasks` legible donde `Spec.Mode.Replicated` no existe. Ese context es el que vuelve necesario el poll del helper `listed_with_status`: en un global el deseado arranca en 0 y el Engine lo completa después (~1s), así que la condición de corte es `DesiredTasks.positive?`, no `ServiceStatus.present?`.
 - Infra de transporte: `api_spec`, `connection_spec`, `configuration_spec`, `log_helper_spec`, los 4 middleware specs.
 - `swarm`, `system` (singletons): `swarm_spec`, `system_spec`.
 

data/lib/docker_swarm/base.rb

@@ -46,14 +46,33 @@ module DockerSwarm
         all(filters)
       end
 
+      # Claves que el Engine toma como **query params propios** del listado
+      # (`?limit=`, `?all=`, …), no como *filters*.
+      #
+      # Todo lo que NO esté declarado acá se serializa dentro del JSON de `?filters=`.
+      # Si además no es un filtro válido del recurso, el Engine lo rechaza o lo ignora:
+      # el parámetro **no llega** y no hay forma de pedirlo desde la gema.
+      #
+      # Override en el modelo que declare uno propio (p. ej. `status` en
+      # {DockerSwarm::Service}). La lista **no** se generaliza acá por comodidad: un
+      # mismo nombre puede ser query param en un recurso y filtro legítimo en otro
+      # (`status` lo es en `/containers/json`), y globalizarlo lo saca del `?filters=`
+      # donde ese otro recurso lo necesita.
+      #
+      # @return [Array<Symbol>] nombres de query param
+      def index_query_params
+        %i[all force limit since before].freeze
+      end
+
       private
 
       def _fetch_all(filters = {})
         query = {}
 
         if filters.present?
-          global_params = filters.slice(:all, :force, :limit, :since, :before)
-          docker_filters = filters.except(:all, :force, :limit, :since, :before)
+          query_keys = index_query_params
+          global_params = filters.slice(*query_keys)
+          docker_filters = filters.except(*query_keys)
 
           query = global_params
 

data/lib/docker_swarm/models/service.rb

@@ -9,6 +9,30 @@ module DockerSwarm
     include Concerns::Deletable
     include Concerns::Loggable
 
+    # `status` es un query param **propio** de `GET /services` (Engine API ≥ v1.41), no un
+    # filtro: con `?status=true` cada elemento del listado trae `ServiceStatus`
+    # (`RunningTasks` · `DesiredTasks` · `CompletedTasks`).
+    #
+    # Es el **único** lugar donde el Engine publica el deseado de un service en modo
+    # `global`. Un service replicado lo expone en `Spec.Mode.Replicated.Replicas`, pero
+    # para uno global ese campo no existe —el deseado es "una task por nodo elegible"—,
+    # así que sin `DesiredTasks` no hay número contra el cual comparar las tasks que
+    # corren: un global degradado *parcialmente* (2 de 3 nodos) es indistinguible de uno
+    # sano, y solo se detecta el caso extremo de cero tasks.
+    #
+    # Va acá y no en la whitelist de {DockerSwarm::Base} porque en `/containers/json`
+    # `status` **sí** es un filtro válido (`running`, `exited`, …): globalizarlo lo sacaría
+    # del `?filters=` y rompería `Container.where(status: "running")`.
+    #
+    # En un Engine por debajo de v1.41 el parámetro se ignora sin error y `ServiceStatus`
+    # llega ausente → el consumidor tiene que tolerar `nil`.
+    #
+    # @return [Array<Symbol>] Symbols (no Strings como +create_query_params+): acá se
+    #   matchea contra las claves de +filters+.
+    def self.index_query_params
+      (super + %i[status]).freeze
+    end
+
     # Restarts the service by incrementing ForceUpdate, which causes
     # Docker to recreate all tasks.
     #

data/lib/docker_swarm/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DockerSwarm
-  VERSION = "0.9.0"
+  VERSION = "0.10.0"
 end

data/skill/SKILL.md

@@ -58,7 +58,7 @@ Defaults son razonables: en local sin TLS, no necesitás bloque `configure`.
 
 | Modelo | Class methods | Instance methods | Notas |
 |---|---|---|---|
-| `Service` | `all(filters)`, `find(id)`, `where(filters)`, `create(attrs)` | `update(attrs)`, `restart`, `destroy`, `logs(query)`, `reload`, `persisted?`, `id` | CRUD completo + force-recreate de tasks; `create`/`update` aceptan `registry_auth:` (+ `update`: `registry_auth_from:`) para auth de registry privado |
+| `Service` | `all(filters)`, `find(id)`, `where(filters)`, `create(attrs)` | `update(attrs)`, `restart`, `destroy`, `logs(query)`, `reload`, `persisted?`, `id` | CRUD completo + force-recreate de tasks; `create`/`update` aceptan `registry_auth:` (+ `update`: `registry_auth_from:`) para auth de registry privado; `where(status: true)` puebla `ServiceStatus` (único deseado legible de un service `global`) |
 | `Node` | `all(filters)`, `find(id)`, `where(filters)` | `update(attrs)`, `destroy` | No `create` (los nodos se unen fuera de la gema) |
 | `Task` | `all(filters)`, `find(id)`, `where(filters)` | `logs(query)`, `reload` | Read-only (generados por orquestador) |
 | `Container` | `all(filters)`, `find(id)`, `where(filters)`, `create(attrs)` | `start`, `stop`, `destroy`, `logs(query)` | `create` manda `name` por query string (`create_query_params`) — en el body Docker lo descarta en silencio |
@@ -80,6 +80,11 @@ DockerSwarm::Service.all(label: ["env=production"])
 DockerSwarm::Node.all(role: ["manager"])
 DockerSwarm::Container.all(status: ["running"])
 
+# Listar pidiendo ServiceStatus (query param propio, NO filtro; Engine API >= v1.41)
+DockerSwarm::Service.where(status: true).each do |svc|
+  svc.ServiceStatus # => { "RunningTasks" => 2, "DesiredTasks" => 3, "CompletedTasks" => 0 } | nil
+end
+
 # Lookup graceful (nil si 404)
 service = DockerSwarm::Service.find("svc-id")  # => Service | nil
 
@@ -134,6 +139,8 @@ Todas heredan de `DockerSwarm::Error`. Tres formas de acceso equivalentes: `Dock
 - **`Spec` se mergea con `deep_merge` en updates**, no se reemplaza. Pasale sólo los campos que cambian: `service.update(Mode: {...})`, no `service.update(Spec: {...completo})`.
 - **`assign_attributes` muta antes de validar.** Si `update` falla por `valid?` o por el API, la instancia local quedó mutada. Hacé `reload` si necesitás estado limpio.
 - **`Container.create` manda el nombre por query string.** Docker **descarta en silencio** un `name:` en el body y responde `201`: el container nace con nombre aleatorio y un reintento duplica en vez de adoptar. La gema lo resuelve sola vía `Container.create_query_params == %w[name]` — pero si armás el request por afuera (`DockerSwarm.request`), el `?name=` es tuyo. Ver ADR-025 cláusula 1 y §3.11 de `docs/behavior/behavior.md`.
+- **`where` parte las claves en dos: query params propios vs. `?filters=`.** Solo lo declarado en `Base.index_query_params` (`%i[all force limit since before]`, más `:status` en `Service`) viaja en la URL; **todo lo demás se serializa como filtro de Docker**. Si le pasás un query param propio que el modelo no declara, no llega: va dentro de `filters` y el Engine lo rechaza o lo ignora — sin error que indique que iba en la URL. Los nombres no son globales: `status` es query param en `/services` y **filtro válido** en `/containers/json`.
+- **`ServiceStatus` solo aparece con `Service.where(status: true)`**, y es el **único** lugar donde el Engine publica el deseado de un service en modo `global` (un replicado lo tiene en `Spec.Mode.Replicated.Replicas`; un global no tiene ese campo). Sin `DesiredTasks` un global corriendo en 2 de 3 nodos elegibles es indistinguible de uno sano. Requiere API ≥ v1.41 y **degrada en silencio**: la gema no fija `?version=`, así que en un Engine anterior el parámetro se ignora y `ServiceStatus` llega `nil` — no hay señal de "no soportado", el consumidor tiene que tolerarlo. Y **`DesiredTasks: 0` no es "sin nodos elegibles"**: en un `global` recién creado el Engine publica los tres contadores en 0 y calcula el deseado después (~1s, medido), así que hay una ventana donde `RunningTasks == DesiredTasks == 0` y comparar los dos números miente — tratá `DesiredTasks.positive?` como precondición para decidir salud. Ver §3.12 de `docs/behavior/behavior.md`.
 - **`logs` devuelve texto ya demultiplexado.** Sin TTY el Engine enmarca cada fragmento con 8 bytes de cabecera; `Middleware::LogStreamDemuxer` los saca en `Container`, `Service` y `Task`. Dos consecuencias: **`stdout` y `stderr` vienen intercalados** en un solo String (si necesitás un dato puntual, delimitalo en origen desde el `Cmd`), y **un frame partido entre chunks no se reensambla** — el demux es todo-o-nada, así que ante cualquier inconsistencia te devuelve el body intacto en vez de texto a medias. Con `follow: 1` el body no llega completo, así que no esperes demux ahí.
 - **`Image.create` retirado (breaking).** Ya no existe (`Image` dejó de ser Creatable; el `create` estaba roto y sin consumidores). Usá `Image.pull(image_reference, registry_auth:)`.
 - **Auth de registry privado soportado** vía credencial opaca base64url en `registry_auth:` — `Image.pull(ref, registry_auth:)`, `Service.create(..., registry_auth:)` y `Service#update(..., registry_auth:` / `registry_auth_from:)`. Viaja por header `X-Registry-Auth` (o query `registryAuthFrom`: `spec`\|`previous-spec`, excluyentes); la gema no la mintea ni decodifica. Ver flujos 3.9/3.10 de `docs/behavior/behavior.md`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: docker-swarm
 version: !ruby/object:Gem::Version
-  version: 0.9.0
+  version: 0.10.0
 platform: ruby
 authors:
 - Gabriel
@@ -136,9 +136,9 @@ licenses:
 metadata:
   homepage_uri: https://github.com/sequre/docker-swarm
   source_code_uri: https://github.com/sequre/docker-swarm
-  changelog_uri: https://github.com/sequre/docker-swarm/blob/v0.9.0/CHANGELOG.md
+  changelog_uri: https://github.com/sequre/docker-swarm/blob/v0.10.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/sequre/docker-swarm/issues
-  documentation_uri: https://github.com/sequre/docker-swarm/blob/v0.9.0/skill/SKILL.md
+  documentation_uri: https://github.com/sequre/docker-swarm/blob/v0.10.0/skill/SKILL.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: