feat(infra): auto-commit con 86 cambios
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,43 @@
|
||||
---
|
||||
name: docker_container_info
|
||||
lang: go
|
||||
domain: infra
|
||||
version: "1.0.0"
|
||||
algebraic: product
|
||||
definition: |
|
||||
type DockerContainerInfo struct {
|
||||
ID string
|
||||
Names []string
|
||||
Image string
|
||||
State string
|
||||
Status string
|
||||
Ports []string
|
||||
Networks []string
|
||||
Labels map[string]string
|
||||
}
|
||||
description: "Container Docker enriquecido retornado por DockerContainerList. Campos richer que ContainerInfo: Names y Ports como slices, Networks, Labels como map."
|
||||
tags: [docker, docker-agent, container, infra]
|
||||
uses_types: []
|
||||
file_path: "functions/infra/docker_container_list.go"
|
||||
---
|
||||
|
||||
## Ejemplo
|
||||
|
||||
```go
|
||||
c := infra.DockerContainerInfo{
|
||||
ID: "abc123def456",
|
||||
Names: []string{"/my-app"},
|
||||
Image: "nginx:latest",
|
||||
State: "running",
|
||||
Status: "Up 2 hours",
|
||||
Ports: []string{"0.0.0.0:8080->80/tcp"},
|
||||
Networks: []string{"bridge"},
|
||||
Labels: map[string]string{"app": "my-app", "env": "prod"},
|
||||
}
|
||||
// Mostrar nombre sin slash inicial
|
||||
fmt.Println(strings.TrimPrefix(c.Names[0], "/"))
|
||||
```
|
||||
|
||||
## Notas
|
||||
|
||||
Difiere de `ContainerInfo` (container_info_go_infra) en que `Names` y `Ports` son `[]string` en lugar de `string`, y añade `Networks`. Esto refleja el JSON nativo del Docker Engine API (`/containers/json`) donde estos campos son arrays. Retornado por `docker_container_list_go_infra`.
|
||||
@@ -0,0 +1,36 @@
|
||||
---
|
||||
name: docker_exec_result
|
||||
lang: go
|
||||
domain: infra
|
||||
version: "1.0.0"
|
||||
algebraic: product
|
||||
definition: |
|
||||
type DockerExecResult struct {
|
||||
ExitCode int
|
||||
Stdout string
|
||||
Stderr string
|
||||
Duration int64
|
||||
}
|
||||
description: "Resultado de ejecutar un comando dentro de un container Docker via Engine API. ExitCode es el codigo de salida del proceso; Stdout/Stderr estan demuxeados del stream multiplexado; Duration es la duracion real en milisegundos."
|
||||
tags: [docker, docker-agent, exec, infra]
|
||||
uses_types: []
|
||||
file_path: "functions/infra/docker_container_exec.go"
|
||||
---
|
||||
|
||||
## Ejemplo
|
||||
|
||||
```go
|
||||
result := infra.DockerExecResult{
|
||||
ExitCode: 0,
|
||||
Stdout: "uid=0(root) gid=0(root) groups=0(root)\n",
|
||||
Stderr: "",
|
||||
Duration: 42,
|
||||
}
|
||||
if result.ExitCode != 0 {
|
||||
log.Printf("command failed (exit %d): %s", result.ExitCode, result.Stderr)
|
||||
}
|
||||
```
|
||||
|
||||
## Notas
|
||||
|
||||
`ExitCode` refleja el exit code real del proceso ejecutado dentro del container, no el de la llamada HTTP. Si el proceso no termino (timeout, error de red), la funcion retorna error y `DockerExecResult` queda vacio. `Duration` mide tiempo wall-clock incluyendo overhead de red y demux.
|
||||
@@ -0,0 +1,31 @@
|
||||
---
|
||||
name: docker_log_line
|
||||
lang: go
|
||||
domain: infra
|
||||
version: "1.0.0"
|
||||
algebraic: product
|
||||
definition: |
|
||||
type DockerLogLine struct {
|
||||
Stream string
|
||||
Timestamp string
|
||||
Line string
|
||||
}
|
||||
description: "Linea de log de un contenedor Docker con su stream de origen (stdout/stderr), timestamp RFC3339 opcional y contenido."
|
||||
tags: [docker, docker-agent, logs, infra]
|
||||
uses_types: []
|
||||
file_path: "functions/infra/docker_log_line.go"
|
||||
---
|
||||
|
||||
## Ejemplo
|
||||
|
||||
```go
|
||||
line := DockerLogLine{
|
||||
Stream: "stdout",
|
||||
Timestamp: "2026-05-23T12:00:00.000000000Z",
|
||||
Line: "server started on :8080",
|
||||
}
|
||||
```
|
||||
|
||||
## Notas
|
||||
|
||||
`Timestamp` solo se rellena si `DockerLogsOpts.Timestamps = true`. El valor viene del prefijo que el daemon Docker antepone a cada linea antes del demux de frame.
|
||||
@@ -0,0 +1,41 @@
|
||||
---
|
||||
name: docker_logs_opts
|
||||
lang: go
|
||||
domain: infra
|
||||
version: "1.0.0"
|
||||
algebraic: product
|
||||
definition: |
|
||||
type DockerLogsOpts struct {
|
||||
ContainerID string
|
||||
Tail int
|
||||
Since string
|
||||
Stdout bool
|
||||
Stderr bool
|
||||
Timestamps bool
|
||||
DockerHost string
|
||||
}
|
||||
description: "Parametros para la peticion de logs al engine API de Docker. Usado por DockerContainerLogs y DockerContainerLogsStream."
|
||||
tags: [docker, docker-agent, logs, infra]
|
||||
uses_types: []
|
||||
file_path: "functions/infra/docker_log_line.go"
|
||||
---
|
||||
|
||||
## Ejemplo
|
||||
|
||||
```go
|
||||
opts := DockerLogsOpts{
|
||||
ContainerID: "my-app",
|
||||
Tail: 100,
|
||||
Since: "10m",
|
||||
Stdout: true,
|
||||
Stderr: true,
|
||||
Timestamps: true,
|
||||
}
|
||||
```
|
||||
|
||||
## Notas
|
||||
|
||||
- `Tail = 0` efectivamente usa el default de 100 lineas. `Tail = -1` devuelve todas.
|
||||
- `Since` acepta unix timestamp en string ("1716400000"), RFC3339 o duracion Go ("10m", "1h30m").
|
||||
- Si tanto `Stdout` como `Stderr` son false, la funcion los activa ambos por defecto.
|
||||
- `DockerHost` vacio conecta al socket Unix `/var/run/docker.sock`.
|
||||
@@ -0,0 +1,28 @@
|
||||
---
|
||||
name: shell_exec_opts
|
||||
lang: go
|
||||
domain: infra
|
||||
version: "1.0.0"
|
||||
algebraic: product
|
||||
definition: |
|
||||
type ShellExecOpts struct {
|
||||
Cmd []string
|
||||
BinariesAllowed []string
|
||||
Env []string
|
||||
WorkingDir string
|
||||
TimeoutSeconds int
|
||||
StdinPayload []byte
|
||||
MaxOutputBytes int
|
||||
User string
|
||||
}
|
||||
description: "Parametros de configuracion para ShellExecWhitelist. Define el comando, whitelist de binarios, entorno, timeout, stdin y limite de output."
|
||||
tags: [shell, exec, security, sandbox, device-agent, infra, agents]
|
||||
uses_types: []
|
||||
file_path: "functions/infra/shell_exec_whitelist.go"
|
||||
---
|
||||
|
||||
## Notas
|
||||
|
||||
- `BinariesAllowed` vacío rechaza todo sin spawn. Nunca construir dinámicamente desde input externo.
|
||||
- `Env` vacío activa entorno mínimo: `PATH=/usr/bin:/bin`, `HOME`, `USER`, `LANG=C.UTF-8`.
|
||||
- `MaxOutputBytes` aplica por separado a stdout y stderr. Default 1 MB cada uno.
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
name: shell_exec_result
|
||||
lang: go
|
||||
domain: infra
|
||||
version: "1.0.0"
|
||||
algebraic: product
|
||||
definition: |
|
||||
type ShellExecResult struct {
|
||||
ExitCode int
|
||||
Stdout string
|
||||
Stderr string
|
||||
Duration int64
|
||||
Truncated bool
|
||||
TimedOut bool
|
||||
}
|
||||
description: "Resultado de ejecutar un comando shell con ShellExecWhitelist. Contiene stdout/stderr separados, exit code, duracion en ms, y flags de truncado y timeout."
|
||||
tags: [shell, exec, security, sandbox, device-agent, infra, agents]
|
||||
uses_types: []
|
||||
file_path: "functions/infra/shell_exec_whitelist.go"
|
||||
---
|
||||
|
||||
## Notas
|
||||
|
||||
- `ExitCode`: codigo de salida del proceso. -1 si el proceso fue matado por SIGKILL (timeout).
|
||||
- `Truncated`: true si stdout o stderr fue recortado por `MaxOutputBytes`.
|
||||
- `TimedOut`: true si el proceso fue terminado por timeout antes de completar.
|
||||
- `Duration`: tiempo real de ejecucion en milisegundos (incluye tiempo hasta SIGKILL si aplica).
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
name: wg_client_config
|
||||
lang: go
|
||||
domain: infra
|
||||
version: "1.0.0"
|
||||
algebraic: product
|
||||
definition: |
|
||||
type WGClientConfigInput struct {
|
||||
DevicePrivateKey string
|
||||
DeviceAddress string
|
||||
HubPublicKey string
|
||||
HubEndpoint string
|
||||
HubAllowedIPs string
|
||||
PresharedKey string
|
||||
PersistentKA int
|
||||
DNS string
|
||||
}
|
||||
type WGClientConfig struct {
|
||||
INI string
|
||||
QR string
|
||||
Filename string
|
||||
}
|
||||
description: "Par de tipos producto para generar wg0.conf del peer cliente: WGClientConfigInput reune todos los parametros de configuracion del device, WGClientConfig devuelve el .conf listo para instalar, el QR unicode y el filename sugerido."
|
||||
tags: [wireguard, client, config, qr, mesh, vpn]
|
||||
uses_types: []
|
||||
file_path: "functions/infra/wg_client_config_types.go"
|
||||
---
|
||||
|
||||
## Notas
|
||||
|
||||
`WGClientConfigInput.PersistentKA` con valor 0 se interpreta como "usar default 25s". Valor 25 es el recomendado para peers detras de NAT carrier-grade (movil/4G).
|
||||
|
||||
`WGClientConfigInput.PresharedKey` vacio omite la linea PSK del .conf. Si se usa, debe coincidir exactamente con el valor configurado en el hub para este peer.
|
||||
|
||||
`WGClientConfig.QR` usa bloques unicode (skip2/go-qrcode ToString) — visible en terminal y en mensajes Element. Para display en pantallas pequenas, considerar `ToSmallString`.
|
||||
@@ -0,0 +1,21 @@
|
||||
---
|
||||
name: WGKeys
|
||||
lang: go
|
||||
domain: infra
|
||||
version: "1.0.0"
|
||||
algebraic: product
|
||||
definition: |
|
||||
type WGKeys struct {
|
||||
PrivateKey string
|
||||
PublicKey string
|
||||
PresharedKey string
|
||||
}
|
||||
description: "Par de claves WireGuard Curve25519 (privada y publica) en base64, con preshared key opcional para defensa quantum-safe en mesh."
|
||||
tags: [wireguard, crypto, infra, mesh]
|
||||
uses_types: []
|
||||
file_path: "functions/infra/wg_keygen.go"
|
||||
---
|
||||
|
||||
## Notas
|
||||
|
||||
Todos los campos son cadenas base64 de 44 caracteres (32 bytes Curve25519 codificados). `PresharedKey` esta vacio cuando `WGKeygen` se llama con `withPSK=false`. NUNCA persistir `PrivateKey` ni `PresharedKey` en logs ni en texto plano.
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
name: wg_peer_result
|
||||
lang: go
|
||||
domain: infra
|
||||
version: "1.0.0"
|
||||
algebraic: product
|
||||
definition: |
|
||||
type WGPeerResult struct {
|
||||
DeviceID string
|
||||
AssignedIP string
|
||||
ConfigPath string
|
||||
Status string
|
||||
}
|
||||
description: "Resultado de añadir o verificar un peer WireGuard en el hub. Status puede ser 'added', 'already-present' o 'reconfigured'. AssignedIP es la IP pura sin prefijo CIDR."
|
||||
tags: [wireguard, hub, peer, mesh, infra]
|
||||
uses_types: []
|
||||
file_path: "functions/infra/wg_peer_types.go"
|
||||
---
|
||||
|
||||
## Notas
|
||||
|
||||
Retornado por `wg_peer_add_go_infra`. Status "already-present" indica idempotencia exitosa — no se modifico el config. "reconfigured" indica que se reemplazo el bloque del peer (cambio de PublicKey o AllowedIPs).
|
||||
@@ -0,0 +1,22 @@
|
||||
---
|
||||
name: wg_peer_spec
|
||||
lang: go
|
||||
domain: infra
|
||||
version: "1.0.0"
|
||||
algebraic: product
|
||||
definition: |
|
||||
type WGPeerSpec struct {
|
||||
DeviceID string
|
||||
PublicKey string
|
||||
PresharedKey string
|
||||
AllowedIPs string
|
||||
}
|
||||
description: "Especificacion de un peer WireGuard a añadir al hub. DeviceID es el identificador logico del dispositivo. PublicKey y PresharedKey son base64. AllowedIPs es el CIDR a rutear; si vacio se autoasigna del pool."
|
||||
tags: [wireguard, hub, peer, mesh, infra]
|
||||
uses_types: []
|
||||
file_path: "functions/infra/wg_peer_types.go"
|
||||
---
|
||||
|
||||
## Notas
|
||||
|
||||
Usado como input de `wg_peer_add_go_infra`. PresharedKey es opcional — pasar string vacio para omitirlo. AllowedIPs vacio activa la autoasignacion de IP dentro del subnetCIDR pasado a WGPeerAdd.
|
||||
Reference in New Issue
Block a user