fn_registry/functions/infra/docker_container_exec.md

name, kind, lang, domain, version, purity, signature, description, tags, uses_functions, uses_types, returns, returns_optional, error_type, imports, params, output, tested, tests, test_file_path, file_path

name	kind	lang	domain	version	purity	signature	description	tags	uses_functions	uses_types	returns	returns_optional	error_type	imports	params	output	tested	tests	test_file_path	file_path
docker_container_exec	function	go	infra	1.0.0	impure	func DockerContainerExec(opts DockerExecOpts) (DockerExecResult, error)	Exec comando dentro de container Docker con whitelist obligatoria de binarios. SIN shell expansion. Stream demuxado stdout/stderr. Timeout context-cancellable. Capability docker.container.exec del device_agent.	docker docker-agent exec security infra		docker_exec_result_go_infra error_go_core	docker_exec_result_go_infra	false	error_go_core	bytes context encoding/json fmt io net/http strings time	name desc opts.ContainerID ID o nombre del container destino. Obligatorio. name desc opts.Cmd argv del comando. Cmd[0] es el binario a ejecutar; debe estar en BinariesAllowed. Sin shell expansion. name desc opts.BinariesAllowed Whitelist exacta de binarios permitidos. EMPTY = rechaza todo sin contactar el engine. Security-critical. name desc opts.User Usuario/grupo en formato UID:GID (ej: '1000:1000'). Vacio = default del container. name desc opts.WorkingDir Directorio de trabajo dentro del container. Vacio = default del container. name desc opts.Env Variables de entorno adicionales en formato KEY=VAL. Combinadas con las del container. name desc opts.TimeoutSeconds Timeout de la operacion completa en segundos. Default 30 si es 0 o negativo. name desc opts.DockerHost Socket Docker. Default 'unix:///var/run/docker.sock'. Soporta 'unix://', 'tcp://', 'http://'.	DockerExecResult{ExitCode, Stdout, Stderr, Duration} con el resultado completo del comando ejecutado.	true	binario en whitelist exitcode 0 stdout stderr capturados binario NO en whitelist error sin contactar engine whitelist vacia rechaza todo timeout simulado	functions/infra/docker_container_exec_test.go	functions/infra/docker_container_exec.go

Ejemplo

result, err := infra.DockerContainerExec(infra.DockerExecOpts{
    ContainerID:     "my-app-container",
    Cmd:             []string{"cat", "/etc/hostname"},
    BinariesAllowed: []string{"cat", "ls", "id", "env"},
    User:            "1000:1000",
    TimeoutSeconds:  10,
})
if err != nil {
    log.Fatalf("exec failed: %v", err)
}
fmt.Printf("exit=%d stdout=%q stderr=%q duration=%dms\n",
    result.ExitCode, result.Stdout, result.Stderr, result.Duration)

Cuando usarla

Cuando necesitas ejecutar un comando dentro de un container en ejecucion desde Go, con control de seguridad sobre que binarios pueden invocarse. Indispensable para el capability group docker-agent (flow 0009 A2): health-checks, introspection, file reads, reconfigurations controladas. Usar antes de cualquier operacion que requiera acceso al filesystem o procesos del container sin montar volumenes adicionales.

Gotchas

• NUNCA usar BinariesAllowed vacio en produccion: la funcion rechaza por diseno. Cualquier lista vacia es un error de configuracion, no un "permitir todo".
• Sin shell expansion: no puedes hacer pipes, redirects ni $VAR desde Cmd. Para eso el manifest del agent debe usar un binario que implemente esa logica (ej. python3 -c "..." si python3 esta en la whitelist).
• Stream demux 8-byte header: el protocolo Docker multiplexado (Tty=false) prefixa cada frame con 8 bytes. Esta funcion lo demux correctamente; si cambias a Tty=true el stream es raw y el demux falla.
• Timeout incluye overhead de red: el TimeoutSeconds aplica al flujo completo (create + start + stream + inspect). En containers locales el overhead es <10ms; en TCP remoto puede ser mas alto.
• ExitCode -1: solo aparece si falla la llamada a /exec/{id}/json (error de red/timeout), no como exit code real del proceso.
• DockerHost en TCP: usar tcp://host:2375 para daemons remotos sin TLS. Para TLS, el cliente HTTP necesitaria cert/key — no soportado en esta version (ver Gotchas de produccion).