Script bib_openapi.py — Indexación OpenAPI de la Biblioteca

Entidadactivecreado Tue May 05#biblioteca #infra #ci #django #observability #supercontext #reliability #cloudflare

Descripción

scripts/bib_openapi.py es el script encargado de extraer el schema OpenAPI de CreaRack Pro e indexarlo en la Biblioteca mediante el handler MCP bib_index_openapi. Refresca todos los nodos endpoint y schema del grafo de conocimiento (~900 nodos en el estado actual del proyecto).

Es el patrón gemelo de scripts/bib_ast.py: misma auth MCP (BIB_MCP_TOKEN), mismo MCP_URL, mismo unwrap defensivo de errores (Regla 15).

Modos de extracción (desde s50)

Desde el commit 05b0bde (05-05-2026), el script soporta dos modos de extracción del schema:

Modo HTTP (preferido, default)

BIB_MCP_TOKEN=... INTERNAL_TOOLS_TOKEN=... python scripts/bib_openapi.py --push

Realiza un GET https://crearack.com/api/openapi-export con Authorization: Bearer <INTERNAL_TOOLS_TOKEN>.
Más rápido, no requiere Docker, no tiene pico de RAM.
Default cuando no se pasa --container.

Modo docker exec (fallback, dev local)

python scripts/bib_openapi.py --container crearack-pro-zcmvsl-web-1 --push

Ejecuta python -c api.get_openapi_schema() dentro del container web.
Útil en local sin servidor remoto levantado.
Pesado en RAM (~500 MB pico) → provoca OOM (rc=137) en hosts pequeños como STAGE CX23 (4 GB).
Si rc=137, el script emite mensaje claro sugiriendo migrar a --url.

Referencia de argumentos

Argumento	Default	Descripción
`--url`	`https://crearack.com/api/openapi-export`	Endpoint HTTP a consultar
`--internal-token`	`$INTERNAL_TOOLS_TOKEN`	Bearer token para autenticación HTTP
`--container`	autodetect	Fuerza modo docker exec
`--mcp-url`	`https://workspace.crearack.com/api/mcp`	URL del handler MCP
`--mcp-token`	`$BIB_MCP_TOKEN`	Token auth del MCP
`--output <file>`	—	Guarda el JSON a archivo sin postear
`--push`	—	Postea el schema al handler MCP
`--stats`	—	Muestra estadísticas (paths/schemas) y sale

Funciones principales

Función	Descripción
`extract_openapi_via_http(url, token)`	Modo HTTP: GET con Bearer auth. Maneja 401, URLError, JSONDecodeError.
`extract_openapi_via_docker(container)`	Modo docker: `subprocess.run(docker exec ...)`. OOM → rc=137 con aviso.
`autodetect_container()`	Detecta el container web activo vía `docker ps`.
`push_to_mcp(openapi_json, mcp_url, token)`	Postea el spec al handler `bib_index_openapi` con unwrap defensivo.
`stats(openapi_json)`	Cuenta paths y schemas del spec.

Variables de entorno requeridas

Variable	Obligatoria para	Descripción
`INTERNAL_TOOLS_TOKEN`	Modo HTTP	Bearer token del endpoint `/api/openapi-export`
`BIB_MCP_TOKEN`	`--push`	Token de autenticación del MCP de la Biblioteca

Lógica de decisión de modo

if args.container:
    openapi_json = extract_openapi_via_docker(args.container)
else:
    url = args.url or DEFAULT_OPENAPI_URL
    openapi_json = extract_openapi_via_http(url, args.internal_token.strip())

Integración con cron

scripts/cron-bib-reindex.sh --extras-only invoca este script en modo HTTP, leyendo el token desde /opt/bib-reindex/.token-internal (chmod 600). Ver runbook para configuración.

Véase también

[[entity—api—endpoint—openapi-export]]
[[feature—biblioteca—bib-openapi-http-mode]]
[[runbook—infra—deploy-internal-tools-token]]