feat(infra): auto-commit con 56 cambios

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-21 14:22:55 +02:00
parent c1071a82b3
commit 32c7336bf6
56 changed files with 5307 additions and 100 deletions
@@ -0,0 +1,74 @@
+---
+name: refresh_local_hub
+kind: pipeline
+lang: py
+domain: pipelines
+purity: impure
+version: "1.0.0"
+signature: "def refresh_local_hub(manifest_path: str | None = None, reload: bool = True) -> dict"
+description: "Orquesta el refresco del sistema local_hub: descubre los servicios locales, regenera el fragmento de Caddyfile y la config de Glance, recarga Caddy (admin API) y reinicia la user-unit glance. Compone discover_local_services + render_caddyfile + render_glance_config. Lo corre el dag_engine a diario y tambien el usuario a mano."
+tags: [local-hub, pipelines, pipeline, caddy, glance, infra, dashboard]
+uses_functions: [discover_local_services_py_infra, render_caddyfile_py_infra, render_glance_config_py_infra]
+uses_types: []
+returns: []
+returns_optional: false
+error_type: "error_go_core"
+imports: [pyyaml]
+tested: true
+tests:
+  - "compone las tres funciones del registry y escribe ambas configs"
+  - "la config completa de Glance generada es YAML parseable"
+  - "con reload=False no se llama a subprocess.run"
+  - "con reload=True se invoca caddy reload y systemctl --user restart glance"
+  - "el dict de retorno tiene todas las claves del contrato"
+test_file_path: "python/functions/pipelines/refresh_local_hub_test.py"
+file_path: "python/functions/pipelines/refresh_local_hub.py"
+params:
+  - name: manifest_path
+    desc: "Ruta al manifiesto YAML del local_hub. Si es None se usa <RAIZ>/apps/local_hub/local_services.yaml (RAIZ derivada de FN_REGISTRY_ROOT o del path del modulo)."
+  - name: reload
+    desc: "Si True recarga Caddy (admin API localhost:2019, sin sudo) y reinicia la user-unit glance (sin sudo). Si False solo regenera las configs y no toca servicios."
+output: "dict {total, up, down, caddy_path, glance_path, reloaded, caddy_reload_rc, glance_restart_rc, services:[{name,subdomain,port,up}, ...]}"
+---
+
+## Ejemplo
+
+```bash
+./fn run refresh_local_hub
+```
+
+Sin recargar servicios (solo regenera las configs):
+
+```bash
+$HOME/fn_registry/python/.venv/bin/python3 \
+  python/functions/pipelines/refresh_local_hub.py --no-reload
+```
+
+Desde Python:
+
+```python
+from pipelines.refresh_local_hub import refresh_local_hub
+
+r = refresh_local_hub(reload=True)
+print(r)
+# {"total": 8, "up": 6, "down": 2, "caddy_path": "/etc/caddy/conf.d/local_hub.caddy",
+#  "glance_path": ".../apps/local_hub/glance/glance.yml", "reloaded": True,
+#  "caddy_reload_rc": 0, "glance_restart_rc": 0, "services": [...]}
+```
+
+## Cuando usarla
+
+Cuando cambien los servicios locales expuestos como subdominios `*.localhost` (alta/baja de un servicio en el manifiesto, o un service nuevo del registry con bloque `service:`) y quieras que Caddy y el dashboard Glance reflejen el estado actual. Es el paso `function:` que el dag_engine corre a diario para mantener el `local_hub` sincronizado, y el comando que lanzas a mano tras editar `apps/local_hub/local_services.yaml`.
+
+## Gotchas
+
+- **Impura: escribe en `/etc/caddy/conf.d/local_hub.caddy` via ACL**, no via sudo. El usuario debe tener permiso de escritura ahi (ACL ya configurada en este PC). Sin la ACL, el `open(..., "w")` lanza `PermissionError`.
+- **Recarga Caddy por su admin API** (`caddy reload` habla con `localhost:2019`), no reinicia el servicio: requiere que Caddy este corriendo con la admin API activa. Si Caddy no esta levantado, `caddy_reload_rc` queda en un valor != 0 (o -1 si el binario falla) pero el pipeline NO lanza.
+- **Reinicia la user-unit `glance`** (`systemctl --user restart glance`), no la system-unit: requiere que la user-unit `glance` este instalada y el bus de usuario disponible. Si falta, `glance_restart_rc` refleja el fallo sin abortar.
+- **Valida el YAML de Glance antes de escribir**: si `render_glance_config` produjera YAML invalido, el pipeline lanza `RuntimeError` con mensaje claro y no escribe el archivo (fail-fast).
+- **Raiz dinamica**: la raiz del registry se deriva de `FN_REGISTRY_ROOT` o del path del modulo; nunca se hardcodea ningun `/home/<user>`.
+- **`reload=False` no toca ningun servicio**: util para previsualizar las configs generadas sin recargar Caddy ni reiniciar Glance (lo que hace el test).
+
+## Capability growth log
+
+(sin entradas — v1.0.0 inicial)