graph_explorer/issues/completed/0028-enricher-fetch-webpage.md

id, title, status, priority, created, depends_on

id	title	status	priority	created	depends_on
0028	Enricher fetch_webpage (MVP end-to-end)	pending	high	2026-05-01	0026 0027

Objetivo

Primer enricher real sobre el sistema de jobs (0026). Right-click sobre un nodo Url o Webpage → "Fetch web page". Descarga el HTML, lo convierte a markdown, guarda los blobs en cache, actualiza el nodo (o lo convierte a Webpage si era Url) y crea el nodo Domain con relacion BELONGS_TO.

Este enricher valida el contrato entero. Los siguientes (0028b) reusan exactamente el mismo wire protocol.

Archivos

apps/graph_explorer/enrichers/fetch_webpage/
  manifest.yaml
  run.py

manifest.yaml

id: fetch_webpage
name: "Fetch web page"
description: "Descarga HTML, extrae markdown limpio y guarda en cache."
applies_to: [Webpage, Url]
emits: [Domain]
relations: [BELONGS_TO]
params:
  - { name: timeout_s, type: int, default: 15 }

run.py

Logica:

1. Lee JSON de stdin.
2. Saca url de metadata.url (o metadata.address si es Url legacy).
3. PROGRESS:0.05 normalize — normalize_url_py_cybersecurity.
4. PROGRESS:0.20 fetching — descarga via requests.get(url, timeout=N).
5. PROGRESS:0.60 parsing — html_to_markdown_py_core con readabilipy.
6. PROGRESS:0.85 writing — calcula sha256(url), escribe cache/<sha[0:2]>/<sha>.html y .md.
7. Emite stdout JSON:
   • node_updates: cambia type a Webpage si era Url, anade title/status_code/content_type/fetched_at/html_path/markdown_path/text_length.
   • entities: {type: Domain, name: <dominio>, metadata: {}}.
   • relations: from_id: <node_id>, to_name: <dominio>, to_type: Domain, kind: BELONGS_TO.

Funciones del registry usadas

• normalize_url_py_cybersecurity — limpia tracking params.
• html_to_markdown_py_core — readabilipy + markdownify.
• extract_domain se hace inline en el enricher (regex trivial sobre la URL parseada).

Manejo de errores

• HTTP error (4xx/5xx) → escribe status_code en metadata pero NO marca el job como error (el nodo guarda evidencia del fallo).
• Timeout / DNS error / etc → exit con error JSON en stdout: {"error": "...", "node_updates": [], "entities": [], "relations": []}.
• Si el enricher levanta excepcion, sale con codigo != 0 y stderr capturado va a jobs.error.

Definicion de hecho

• Crear nodo Url con https://example.com → click derecho → "Fetch web page".
• En segundos aparece en panel Jobs como running con progress.
• Al terminar:
  • El nodo cambia a tipo Webpage con icono ti-file-text.
  • El inspector muestra title, status_code, html_path, markdown_path.
  • Aparece nodo Domain "example.com" conectado por BELONGS_TO.
  • El archivo cache/<sha>.md existe en disco.
• El job aparece en panel Jobs como done con entities_added=1, relations_added=1.
• Tirar la red (sin internet) → el job acaba en error con mensaje claro.