Configuración de Redirecciones y Reescrituras

Orbit tiene un motor integrado de redirección y reescritura que funciona antes de que se solicite nada a tu proyecto, configurado ya sea en KPanel o como un archivo en tu repositorio. Esta guía cubre ambos, la sintaxis de patrones y sus capturas, cómo se ordenan las reglas, los límites y el comportamiento que sorprende a la gente.

Dónde Configurar Reglas

Hay dos lugares, y se evalúan en un orden fijo.

1. En KPanel. Abre tu proyecto en Orbit, ve a Settings (Configuración), y desplázate hasta la sección redirects and rewrites (redirecciones y reescrituras) para el entorno. Cada entorno tiene su propio conjunto independiente de reglas, por lo que producción y staging se configuran por separado.
2. En tu repositorio, como un archivo kaps.json. Esto se cubre más adelante.

Las reglas del panel se evalúan primero. Si ninguna de ellas coincide, se prueban las reglas kaps.json.

Agregar una Regla en KPanel

1. Haz clic en Add rule (Agregar regla).
2. Completa la source (origen), el patrón de ruta para hacer coincidir las solicitudes entrantes. El marcador de posición muestra las dos formas que espera: /old-path or /blog/:slug.
3. Completa la destination (destino). El marcador de posición muestra /new-path or https://..., por lo que tanto una ruta local como una URL externa completa son válidas.
4. Elige el tipo de regla:
   • 301 Permanent: la URL se ha movido permanentemente. Los navegadores y motores de búsqueda lo almacenan en caché.
   • 302 Temporary: movida por ahora, no almacenada en caché. Úsalo para campañas y experimentos.
   • Rewrite: sirve la ruta de destino sin cambiar la URL en la barra de direcciones del navegador.
5. Haz clic en Save rules (Guardar reglas).

Patrones de Ruta de Origen

La diferencia entre :id y :rest* es la importante. Un parámetro nombrado coincide con un único segmento y se detiene en la siguiente barra. Un comodín coincide con todo lo restante, incluidas las barras.

Usar Capturas en el Destino

Referencia un parámetro nombrado por nombre, y un comodín desnudo como *:

Orden de Reglas

Las reglas se prueban de arriba a abajo de la lista y la primera coincidencia gana. Una vez que una regla coincide, ninguna regla posterior se considera. El panel lo dice bajo la lista: "Rules are tested in order. First match wins." (Las reglas se prueban en orden. La primera coincidencia gana.)

Si ninguna regla coincide, la solicitud se sirve normalmente.

Casos de Uso Comunes

Cambiar el Nombre de una Página

Cambiaste el nombre de /about-us a /about y quieres que los enlaces antiguos sigan funcionando.

• Origen: /about-us
• Destino: /about
• Tipo: 301 Permanent

Mover una Sección Completa

Tu blog se movió de /news/:slug a /blog/:slug.

• Origen: /news/:slug
• Destino: /blog/:slug
• Tipo: 301 Permanent

Proxificar una Ruta de API Silenciosamente

Quieres que /api/v1/* se sirva desde una ruta interna diferente sin exponer el cambio.

• Origen: /api/v1/:path*
• Destino: /api/internal/:path*
• Tipo: Rewrite

Una Página de Retención Temporal

• Origen: /checkout
• Destino: /maintenance
• Tipo: 302 Temporary

Enviar Tráfico a Otro Dominio

El destino puede ser una URL absoluta, por lo que una regla puede apuntar a un sitio completamente diferente.

• Origen: /shop/:rest*
• Destino: https://shop.example.com/:rest*
• Tipo: 301 Permanent

Configuración como Código con kaps.json

Las reglas pueden vivir en tu repositorio en lugar del panel. Agrega un archivo kaps.json, y asegúrate de que tu compilación lo copie en tu directorio de salida, porque Orbit lo lee desde la raíz del artefacto compilado en lugar de desde la raíz del repositorio.

{
  "redirects": [
    { "source": "/about-us", "destination": "/about", "permanent": true },
    { "source": "/news/:slug", "destination": "/blog/:slug", "permanent": true },
    { "source": "/promo", "destination": "/spring-sale", "permanent": false }
  ],
  "rewrites": [
    { "source": "/api/v1/:path*", "destination": "/api/internal/:path*" }
  ],
  "headers": [
    {
      "source": "/*",
      "headers": [
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "X-Content-Type-Options", "value": "nosniff" }
      ]
    }
  ]
}

permanent: true produce un 301 y permanent: false un 302. Omitirlo da un 301.

Límites

• Hasta 100 reglas de redirección y reescritura por entorno, y 100 en un kaps.json.
• Hasta 200 reglas de encabezado personalizado por entorno.

Las reglas más allá del límite se descartan silenciosamente en lugar de generar un error, por lo que mantente bien por debajo de él.

Encabezados de Respuesta Personalizados

Junto con las redirecciones, cada entorno tiene una sección de encabezados de respuesta en Settings (Configuración) para inyectar encabezados HTTP en rutas coincidentes. Utiliza la misma sintaxis de patrón de ruta, y hay preajustes de agregación rápida para HSTS, CSP, no-embed, no-sniff, política de referrer y CORS.

A diferencia de las redirecciones, todas las reglas de encabezado coincidentes se aplican, no solo la primera, y una regla posterior sobrescribe una anterior cuando establecen el mismo encabezado. Content-Length, Transfer-Encoding y Connection están bloqueados, porque establecerlos corrompería la respuesta.

Comportamiento que Vale la Pena Conocer Antes de Confiar en Él

• Las reglas coinciden solo con la ruta. Los fragmentos (#section) nunca llegan al servidor en absoluto; el navegador los vuelve a adjuntar después de una redirección.
• Una reescritura a una ruta que no existe produce un 404, en lugar de caer silenciosamente a la ruta original. Los destinos de reescritura deben existir en tu salida de compilación.
• Las reglas se ejecutan antes de que se solicite nada a tu proyecto, por lo que se aplican a archivos estáticos y a solicitudes en modo de servidor por igual.
• Cada entorno es independiente. Las reglas en producción no se aplican a staging o vistas previas. Cópialas deliberadamente.

Eliminar una Regla

Haz clic en el icono de basura en la fila de la regla, luego haz clic en Save rules (Guardar reglas) para aplicar el cambio. Al igual que al agregar una, el cambio entra en vigor desde la siguiente implementación.

Cuándo Usar una Función de Borde en su Lugar

El motor de redirección maneja reglas de ruta a ruta. Recurre a una función de borde cuando necesites lógica que el motor de reglas no puede expresar: ramificación en un encabezado o cookie, preservación o reescritura de parámetros de consulta, enrutamiento A/B ponderado, o cualquier cosa condicional.

Lectura Relacionada

• Edge Functions
• Agregando un Dominio Personalizado a Tu Proyecto
• Implementando Tu Proyecto