feat(infra): auto-commit con 86 cambios

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-26 19:38:15 +02:00
parent de9bfec498
commit fe65c5e527
85 changed files with 11840 additions and 92 deletions
@@ -0,0 +1,76 @@
+---
+name: docker_container_list
+kind: function
+lang: go
+domain: infra
+version: "1.0.0"
+purity: impure
+signature: "func DockerContainerList(opts DockerContainerListOpts) ([]DockerContainerInfo, error)"
+description: "Lista containers Docker del host via engine API (unix socket o TCP). Sin SDK pesado — net/http directo. Soporta filtros, All=true para exited. Usado por device_agent como capability docker.container.list."
+tags: [docker, docker-agent, container, list, infra]
+uses_functions: []
+uses_types: [error_go_core, docker_container_info_go_infra]
+returns: [docker_container_info_go_infra]
+returns_optional: false
+error_type: "error_go_core"
+imports:
+  - context
+  - encoding/json
+  - fmt
+  - io
+  - net
+  - net/http
+  - net/url
+  - strings
+  - time
+tested: true
+tests:
+  - "lista solo running"
+  - "All=true incluye exited"
+  - "filter label aplica"
+test_file_path: "functions/infra/docker_container_list_test.go"
+file_path: "functions/infra/docker_container_list.go"
+params:
+  - name: opts
+    desc: "DockerContainerListOpts — All (incluir exited), Filters (expresiones label=k=v / status=running), DockerHost (unix socket o tcp://host:port)"
+output: "Slice de DockerContainerInfo con id, names, image, state, ports, networks para cada container."
+---
+
+## Ejemplo
+
+```go
+// Listar solo containers corriendo con un label específico
+containers, err := DockerContainerList(infra.DockerContainerListOpts{
+    Filters:    []string{"label=app=agents_and_robots"},
+    DockerHost: "unix:///var/run/docker.sock",
+})
+if err != nil {
+    log.Fatal(err)
+}
+for _, c := range containers {
+    fmt.Printf("%s  %-20s  %s  %s\n", c.ID, c.Names[0], c.State, c.Status)
+}
+
+// Todos los containers (incluye exited) en host remoto
+all, err := DockerContainerList(infra.DockerContainerListOpts{
+    All:        true,
+    DockerHost: "tcp://192.168.1.10:2375",
+})
+```
+
+## Cuando usarla
+
+Cuando necesites listar containers Docker desde un agente o servicio sin depender del CLI `docker` instalado en el host — por ejemplo, al implementar la capability `docker.container.list` en un `device_agent` que recibe comandos desde Element/Matrix. También útil en tests y en entornos donde el binario docker no está en el PATH pero el socket sí es accesible.
+
+## Gotchas
+
+- Requiere acceso al docker socket. El proceso debe correr como root o en el grupo `docker`. En WSL2, el socket está en `/var/run/docker.sock` si Docker Desktop está activo.
+- `Ports` puede estar vacío para containers en host network mode (`--network host`) — el engine no reporta port bindings en ese caso.
+- Para acceso remoto sin TLS (`tcp://`), el daemon Docker debe tener `-H tcp://0.0.0.0:2375` habilitado explícitamente (deshabilitado por defecto por seguridad). Usar SSH tunnel o TLS para producción.
+- `DockerHost` acepta `unix://` y `tcp://` solamente. Esquemas `https://` o `ssh://` retornan error.
+- El campo `Names` incluye el slash inicial: `["/my-container"]`. Al mostrar al usuario, usar `strings.TrimPrefix(name, "/")`.
+- Filters del tipo `label=k=v` incluyen el segundo `=` en el valor (el split es en el primer `=`). Para filtrar por presencia de label sin valor: `"label=app"`.
+
+## Notas
+
+Implementa la misma semántica que `GET /containers/json` del Docker Engine API v1.41+. No requiere el SDK `github.com/docker/docker` (evita ~50 MB de dependencias transitivas). El helper `dockerListHTTPClient` maneja la dialección unix socket requerida por `net/http`.