---
id: 0028
title: Enricher fetch_webpage (MVP end-to-end)
status: pending
priority: high
created: 2026-05-01
depends_on: [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`

```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.