egutierrez
4ef6a5f7db
Status sincronizado con master: - 0001 chat con Claude -> shipped como panel Echo - 0003 enricher web -> shipped (0028 + 0028b) - 0026 sistema de jobs -> shipped - 0027 tipo Webpage -> shipped - 0028 fetch_webpage -> shipped - 0028b extract trio -> shipped - 0031 layout estable -> shipped Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
79 lines
2.8 KiB
Markdown
79 lines
2.8 KiB
Markdown
---
|
|
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.
|