Cómo se sirve una solicitud de caché JSON

Una sola URL de archivo progresivo puede pasar por varias capas. Comprender su orden te ayuda a interpretar las cabeceras, diagnosticar los fallos de caché y evitar configurar dos capas con supuestos contradictorios.

La solicitud que POM Cache reconoce

POM Theme normalmente crea una URL limpia con esta forma:

https://example.com/pom-json/archive/product/<context-hash>/page-2-ppp-12.json

Los sitios traducidos pueden colocar un prefijo de idioma antes de pom-json, por ejemplo:

https://example.com/es/pom-json/archive/product/<context-hash>/page-2-ppp-12.json

La ruta progresiva con forma de REST también se reconoce:

/wp-json/pom/v1/progressive-archive/archive/...

Para la reutilización estática, la solicitud debe resolverse a una ruta .json segura y no debe llevar una cadena de consulta. GET es compatible durante todo el ciclo de vida normal; PHP y el enrutador del tema también entienden HEAD, mientras que las reglas directas de Apache generadas se limitan a GET.

El orden completo

browser or CDN request
        │
        ▼
optional Apache file rule
        │ miss / not installed
        ▼
POM Cache early PHP check
        │ miss / bypass / disabled
        ▼
WordPress + POM Theme router
        │
        ├─ valid stored file through WordPress fallback → response
        │
        └─ no usable file → dynamic generation → optional write → response

La primera capa que devuelve un acierto válido termina la solicitud. Las capas posteriores no se ejecutan.

Capa 1: entrega directa de Apache

Si las reglas opcionales de POM Cache → Advanced → Progressive JSON Apache rules se instalan antes de las reglas de WordPress, Apache comprueba:

• que el método sea GET;
• que la cadena de consulta esté vacía;
• que no esté presente ninguna cookie reconocida de inicio de sesión, protección por contraseña, autor de comentarios, sesión de WooCommerce o carrito;
• que exista el archivo de caché correspondiente.

Cuando se cumplen todas las condiciones, Apache devuelve el archivo como JSON sin iniciar PHP. Esta es la ruta con menor sobrecarga de origen, pero también está fuera del entorno de configuración de WordPress en tiempo de ejecución. Una regla copiada permanece activa hasta que la edites o la elimines.

La entrega de Apache no tiene una cabecera X-POM-Cache generada por PHP. Usa la información de acceso del servidor, el tiempo de respuesta y el comportamiento descrito en Serve JSON cache files directly with Apache para verificarla.

Capa 2: servicio estático temprano de PHP

Si Apache no sirve la solicitud, el drop-in de POM Cache comprueba la ruta JSON antes de que WordPress termine de cargar. Requiere:

• Progressive JSON cache establecido en Enabled;
• PHP early static serving establecido en Enabled;
• una solicitud GET o HEAD sin cadena de consulta;
• que no haya ninguna cookie de omisión reconocida;
• que no haya ninguna instrucción DONOTCACHEPAGE;
• un archivo legible, no vacío y de tamaño válido.

Un acierto devuelve:

Content-Type: application/json; charset=UTF-8
Cache-Control: <configured JSON policy>
X-POM-Cache: Served static JSON cache from PHP; phase=early
Vary: Accept-Encoding

Para HEAD, PHP envía las cabeceras y la longitud del contenido sin el cuerpo.

Esta ruta puede funcionar incluso cuando el Caching de HTML estático está desactivado, porque el interruptor maestro de JSON es independiente.

Capa 3: alternativa de lectura de WordPress

Cuando la solicitud llega al enrutador POM Theme, el enrutador reconstruye el contexto de archivo esperado a partir de la URL. Comprueba que el hash del contexto y el valor de elementos por página sigan coincidiendo con la configuración actual y que la respuesta sea apta para el almacenamiento en caché.

Con WordPress read fallback habilitado, POM Cache lee el archivo almacenado, valida su tamaño y su sintaxis JSON, y lo devuelve al enrutador. La respuesta puede entonces informar de:

X-POM-Progressive-Archive-Cache: hit

Esto evita la consulta del archivo y el renderizado de la plantilla, pero no el arranque de WordPress. Es una ruta de compatibilidad valiosa cuando el servicio temprano no está disponible.

Capa 4: generación dinámica y escritura

En un fallo de caché, POM Theme construye la respuesta. Su cabecera de diagnóstico distingue:

X-POM-Progressive-Archive-Cache: generated-cacheable
X-POM-Progressive-Archive-Cache: generated-dynamic

generated-cacheable significa que la ruta era apta. POM Cache la escribe solo si el interruptor maestro y JSON writes están habilitados y la respuesta supera las comprobaciones de ruta, tamaño, JSON, permisos e integración.

generated-dynamic significa que el tema consideró intencionadamente que esa respuesta no era adecuada para el almacenamiento compartido. No debe esperarse que repetirla produzca un acierto.

Por qué un archivo almacenado puede seguir omitiéndose

Un archivo existente no garantiza la entrega estática. POM Cache pasa deliberadamente a la siguiente capa cuando:

• la solicitud tiene una cadena de consulta;
• está presente una cookie de sesión privada reconocida;
• el archivo está vacío, es ilegible, tiene un JSON no válido o es demasiado grande;
• el contexto de la URL ya no coincide con la configuración actual del archivo;
• el interruptor de entrega correspondiente está desactivado;
• una integración compatible marca la solicitud o la respuesta como no almacenable en caché.

Pasar a la siguiente capa es más seguro que devolver una respuesta compartida cuestionable. WordPress puede entonces producir el resultado dinámico correcto.

Verifica cada capa de forma independiente

1. Borra solo la caché JSON progresiva.
2. Solicita un lote de archivo limpio como visitante sin sesión iniciada.
3. Confirma una respuesta dinámica y almacenable en caché, y un nuevo recuento de archivos.
4. Repite la URL idéntica y comprueba la cabecera de acierto de PHP o del tema esperada.
5. Si las reglas de Apache están instaladas, verifica temporalmente la ruta en la capa de Apache usando el método de la guía de Apache.
6. Repite con una sesión autenticada y confirma que no usa la ruta compartida temprana.
7. Añade un parámetro de consulta inofensivo y confirma que la solicitud recurre al manejo dinámico en lugar de a un archivo estático.

La siguiente guía, How JSON cache entries are generated, explica en detalle la parte del fallo de caché a la escritura.