Servir archivos de caché JSON directamente con Apache

La entrega directa con Apache es la ruta JSON de POM Cache más rápida en el origen: Apache asigna una URL de archivo progresivo admitida a un archivo existente antes de que PHP o WordPress se inicien.

Esta guía está dirigida a administradores que controlan la configuración .htaccess del origen o del virtual host. Completa primero la configuración JSON basada en PHP para que un problema con las reglas tenga una alternativa funcional.

Requisitos previos

Necesitas:

• Apache con mod_rewrite;
• mod_headers si Apache debe establecer las cabeceras de respuesta JSON que se muestran en el bloque generado;
• enlaces permanentes bonitos (pretty permalinks) en funcionamiento;
• Progressive JSON cache y JSON writes habilitadas;
• al menos un archivo JSON generado;
• una ruta de caché que Apache pueda leer;
• un método de copia de seguridad y reversión para la configuración activa del servidor.

POM Cache no edita .htaccess. Solo muestra un bloque recomendado.

Copiar el bloque generado

1. Abre Settings → POM Cache → Advanced. En multisitio, usa Network Admin → Settings → POM Cache → Advanced.
2. Busca Progressive JSON Apache rules.
3. Copia Recommended progressive JSON .htaccess rules.
4. Revisa cada ruta del sistema de archivos con el documento raíz real y Cache Location.
5. Coloca el bloque antes del bloque estándar de reescritura de WordPress.
6. Valida la configuración de Apache;
7. Recarga de forma elegante (graceful) cuando uses un archivo de virtual host, o guarda el .htaccess revisado;
8. Solicita una URL JSON generada conocida como visitante que no ha iniciado sesión.

Las reglas colocadas después de la regla del controlador frontal de WordPress pueden no tener nunca la oportunidad de servir el archivo.

Rutas cubiertas por las reglas generadas

El bloque reconoce ambas familias de rutas públicas:

/pom-json/<relative-path>.json
/wp-json/pom/v1/progressive-archive/<relative-path>.json

También reconoce un único prefijo seguro antes de cualquiera de las rutas, que se utiliza para las URL localizadas:

/es/pom-json/<relative-path>.json
/es/wp-json/pom/v1/progressive-archive/<relative-path>.json

El segmento con prefijo pasa a formar parte de la ruta de caché almacenada. La ruta JSON restante puede contener los directorios de archivo anidados creados por POM Theme.

Condiciones aplicadas

Las reglas recomendadas sirven un archivo solo cuando:

• el método de la solicitud es GET;
• la cadena de consulta está vacía;
• no hay presente ninguna cookie reconocida de inicio de sesión de WordPress, protección por contraseña, autor de comentario, sesión de WooCommerce o carrito;
• el archivo correspondiente existe debajo del directorio de caché JSON.

Si alguna condición falla, la solicitud continúa hacia WordPress. Estas comprobaciones son importantes: la entrega directa con Apache no puede preguntar a WordPress si el visitante actual tiene un contexto privado.

Las reglas generadas no sirven HEAD directamente. Una solicitud HEAD puede continuar hacia el servicio temprano de PHP o hacia el enrutador del tema.

Cabeceras de respuesta

Con mod_headers, el bloque generado añade:

Content-Type: application/json; charset=UTF-8
Cache-Control: <policy displayed by POM Cache>
Vary: Accept-Encoding

El valor de Cache-Control se copia en el bloque del servidor en el momento en que lo copias. Si cambias JSON Cache-Control header más adelante, se modifica la entrega de PHP y la recomendación recién mostrada, pero no se reescribe un bloque de Apache ya instalado. Actualiza la regla activa del servidor deliberadamente cuando cambie la política.

La ruta de Apache no añade la cabecera de diagnóstico X-POM-Cache de PHP. Por tanto, la ausencia de esa cabecera no constituye por sí misma un fallo.

Adaptar un almacenamiento no predeterminado

El mapeo mostrado asume un documento raíz de WordPress convencional y el subdirectorio JSON estándar debajo:

/wp-content/cache/pom-cache-json/

Revisa el mapeo cuando:

• Cache Location esté fuera de wp-content/cache;
• WordPress se ejecute debajo de un subdirectorio;
• el DOCUMENT_ROOT de Apache no sea la raíz pública de WordPress;
• el origen utilice enlaces simbólicos o un directorio de publicación (release);
• el multisitio utilice rutas de subdirectorios o mapeo de dominios;
• un proxy inverso cambie el host que recibe Apache.

El árbol de archivos utiliza el host configurado del sitio y, cuando corresponda, la ruta del sitio. %{SERVER_NAME} debe resolver al mismo espacio de nombres que POM Cache usó cuando escribió el archivo. Si no es así, mantén la entrega de PHP hasta que se corrija el mapeo.

No amplíes una regla a una ruta arbitraria del sistema de archivos simplemente para hacer desaparecer un fallo. El destino debe permanecer restringido al árbol de caché JSON previsto.

Comportamiento importante del interruptor maestro

Apache evalúa sus reglas copiadas antes de que PHP lea la configuración de POM Cache. Si más adelante estableces Progressive JSON cache en Disabled pero dejas el bloque de Apache activo, Apache puede seguir sirviendo los archivos existentes.

Para una reversión completa de la entrega directa:

1. Desactiva o elimina el bloque JSON de Apache;
2. Limpia la caché JSON progresiva;
3. Verifica que la URL ahora llegue a la ruta prevista de PHP o WordPress;
4. A continuación, cambia los interruptores de ejecución del plugin según sea necesario.

El mismo principio se aplica al mover Cache Location: actualiza el mapeo del servidor como parte del movimiento.

Verificar la entrega directa

Usa una URL JSON que ya tenga un archivo:

1. Solicítala una vez y confirma el contenido actual;
2. Inspecciona las cabeceras de respuesta;
3. Confirma que Content-Type y Cache-Control coincidan con la regla instalada;
4. Confirma que la cabecera X-POM-Cache de PHP esté ausente;
5. Compara el tiempo del origen con la entrega temprana de PHP;
6. Solicita la misma URL con una cadena de consulta y confirma que la regla directa no la sirve;
7. Repite con sesión iniciada y con un carrito/sesión de WooCommerce, cuando corresponda;
8. Prueba cada prefijo de idioma y un subsitio representativo de multisitio.

Si es posible, consulta el registro de acceso del origen para demostrar que se utilizó el archivo de caché de destino. El tiempo de respuesta por sí solo no es concluyente cuando hay una CDN delante.

Revertir de forma segura

Si las URL JSON devuelven 404, HTML, un aviso de descarga o los datos del sitio equivocado:

1. Restaura la configuración anterior de Apache;
2. Verifica que la entrega temprana de PHP o la alternativa de WordPress siga funcionando;
3. Compara la URL pública, el espacio de nombres del host, el prefijo de idioma y la ruta física;
4. Corrige la regla sin conexión;
5. Valídala y reintrodúcela.

Para servidores que no son Apache, no pegues sintaxis de Apache. Usa Use POM Cache on Nginx and other web servers y conserva los mismos límites de método, consulta, cookies, existencia de archivo, tipo de contenido y contención de ruta.