Modo proxy upstream

El modo proxy upstream convierte a Pier en una réplica transparente de registry.npmjs.org (o cualquier upstream compatible con npm). Todo el equipo usa una sola URL de .npmrc y Pier se encarga del resto — los packuments se almacenan en caché y se revalidan, los tarballs se descargan de forma diferida en la primera instalación, y el GC mantiene el uso de disco por debajo de un límite.

Por qué usarlo

• Una URL, sin enrutamiento por scope. Los paquetes privados y públicos viven detrás del mismo https://your-pier-host/registry/npm/. Se acabó el @org:registry=… más un registro por defecto — una sola línea.
• Las instalaciones sobreviven a las caídas de npmjs.org. Todo lo que hayas instalado antes está en la caché. Las nuevas dependencias transitivas solo fallan en el primer fallo de caché.
• Visibilidad de auditoría. La pestaña Mirror lista cada paquete público que el equipo ha instalado a través de Pier, con el tamaño en disco y la hora de la última descarga.
• Cumplimiento. Si necesitas revisar qué versiones llegan a tu código base, el proxy es el punto de estrangulamiento.

Cómo funciona

Client                Pier                       Upstream
  │                    │                            │
  │  GET /react        │                            │
  ├───────────────────►│  cache miss / TTL expired  │
  │                    ├───────────────────────────►│
  │                    │   200 packument            │
  │                    │◄───────────────────────────┤
  │   packument        │  cache + URL-rewrite       │
  │◄───────────────────┤  dist.tarball → /registry/ │
  │                    │                            │
  │  GET /react/-/.tgz │                            │
  ├───────────────────►│  cache miss                │
  │                    ├───────────────────────────►│
  │                    │   tarball bytes            │
  │                    │◄───────────────────────────┤
  │   tarball          │  write FS + DB row         │
  │◄───────────────────┤                            │

• La caché de packuments vive en SQLite como un único blob JSON por paquete (npm_packages.upstream_packument_json). Una fila por paquete — incluso para next (3769 versiones) sigue siendo una sola fila.
• La caché de tarballs vive en disco en data/registry/{package}/{file}.tgz. Solo las versiones que los clientes realmente instalaron llegan aquí.
• Revalidación por TTL — cuando un packument en caché es más antiguo que el TTL configurado, Pier envía If-None-Match: <stored-etag> al upstream. Un 304 hace cortocircuito sin carga útil; un 200 reemplaza el blob.

Configurar

Packages → Upstream proxy tiene cuatro ajustes:

Ajuste	Qué hace	Valores razonables
Enable upstream proxy	Conmutador principal	Desactivado por defecto; actívalo
Upstream URL	De dónde descargar	https://registry.npmjs.org (por defecto)
Packument TTL (seconds)	Con qué frecuencia revalidar los metadatos	600 (10 min) por defecto; 3600 si quieres menos tráfico
Max cache size (MiB)	Límite estricto del almacenamiento de tarballs. 0 = ilimitado	Consulta el dimensionamiento abajo

Dimensionar la caché

La caché de packuments es pequeña (~1–50 KB por paquete, todo en SQLite — cuenta para el archivo de la base de datos, no para el límite en disco). Los tarballs dominan.

Escenario	Límite recomendado
Máquina de un solo desarrollador	500–1000 MiB
Equipo pequeño (3–5 devs)	2–5 GiB
Réplica de CI compartida	20+ GiB
Servidor con abundante disco	0 (ilimitado)

Cuando se supera el límite, el GC con LRU en segundo plano (se ejecuta cada 10 minutos) elimina los tarballs más antiguos hasta que el total quepa. Los tarballs expulsados se vuelven a descargar silenciosamente en la siguiente instalación — el usuario no ve ningún error, solo una ida y vuelta de red adicional.

Inspeccionar qué hay en caché

La pestaña Mirror en Packages lista cada paquete público en caché:

• Versions cached — recuento del packument upstream
• Tarballs on disk — suma de las versiones realmente descargadas
• Last fetched — cuándo se refrescó por última vez el packument
• ★ — fija los paquetes que te importan, luego filtra con Pinned only

Haz clic en una fila para abrir el detalle del paquete. Las versiones en caché muestran su tamaño, su hash de integridad y un botón Deprecate / Unpublish (operaciones a nivel de operador).

Descargar una versión por adelantado

Cuando un paquete del proxy tiene metadatos pero no tarballs en disco (tras un GC, o con una caché fría), la página de detalle muestra un botón Download latest (X.Y.Z). Haz clic para descargar de forma anticipada el tarball de esa versión a través de Pier sin ejecutar npm install localmente — útil para precalentar la caché o para probar rápidamente una réplica nueva.

Desactivar temporalmente

Desactiva Enable upstream proxy y guarda. Los paquetes en caché permanecen en la base de datos y en disco; las nuevas peticiones de paquetes no almacenados en caché devuelven 404. Vuelve a activarlo para reanudar. La caché nunca se borra automáticamente al desactivar.

Manejo de fallos

Si el upstream es inaccesible durante una revalidación por TTL, Pier sirve la copia en caché y registra una advertencia. El proxy nunca bloquea las lecturas a la espera de la disponibilidad del upstream.

Si el upstream devuelve 404 al refrescar un paquete previamente almacenado en caché, Pier sigue sirviendo la copia en caché — la despublicación explícita desde tu registro es una operación aparte y más cuidadosa.

Relacionado

• Configuración — habilitación inicial + token.
• Solución de problemas — errores comunes cuando el proxy está activado.
• Integración con CI — usar el proxy desde los ejecutores de compilación.