Funciones Edge

Las funciones edge son pequeños controladores JavaScript que se ejecutan en la red edge de Kapsule antes de que una solicitud llegue a tu proyecto, de modo que puedas hacer redirecciones, inyección de encabezados, enrutamiento A/B y filtrado de bots sin un viaje de ida y vuelta a tu aplicación. Esta guía cubre cómo escribir una, las formas de punto de entrada aceptadas, coincidencia de rutas, cómo interactúan múltiples funciones, despliegue y qué sucede cuando una función genera una excepción.

Dónde residen

Abre tu proyecto en Orbit y haz clic en la pestaña Edge functions. Cada función pertenece a un proyecto y se enumera con su distintivo de estado: LIVE, PAUSED, NOT DEPLOYED o DEPLOY FAILED.

Crear una función

1. Haz clic en New function.
2. Completa Name (hasta 120 caracteres).
3. Completa Path pattern, el patrón de URL en el que esta función debe ejecutarse.
4. Elige un Trigger: Request (antes de origin), Response (después de origin), o Both.
5. Elige un Environment scope: All environments, Production only, o Preview only.
6. Escribe el controlador en Function body.
7. Haz clic en Save, luego en Deploy to edge.

El objeto request siempre está en el alcance, y el origen tiene un límite de 64 KB.

Escribir un controlador

Devuelve Response para responder a la solicitud en el edge. No devuelvas nada, o devuelve undefined, para pasar la solicitud a tu proyecto sin cambios.

export default {
  async fetch(request) {
    const url = new URL(request.url)

    // Redirect /old to /new
    if (url.pathname === '/old') {
      return new Response(null, {
        status: 301,
        headers: { Location: '/new' },
      })
    }

    // Returning nothing passes through to the origin
  },
}

La forma de función nombrada también funciona:

export default async function handler(request) {
  // Add a security header to every response
  const response = await fetch(request)
  const headers = new Headers(response.headers)
  headers.set('X-Frame-Options', 'DENY')
  return new Response(response.body, { status: response.status, headers })
}

Formas de punto de entrada admitidas

Patrones de ruta

El Path pattern decide qué solicitudes ejecutan la función. Debe comenzar con / y puede tener hasta 2048 caracteres. * coincide con cualquier secuencia de caracteres y ? coincide con un solo carácter. Un patrón sin comodín coincide con esa ruta exacta y todo lo que está debajo de ella.

El objeto request

request es un Request de Fetch API estándar. Puedes leer la URL, método, encabezados y cuerpo:

export default {
  async fetch(request) {
    const url    = new URL(request.url)
    const cookie = request.headers.get('cookie') ?? ''
    const ua     = request.headers.get('user-agent') ?? ''

    if (ua.includes('BadBot')) {
      return new Response('Forbidden', { status: 403 })
    }
  },
}

Patrones comunes

Redirigir URLs antiguas

export default {
  async fetch(request) {
    const url = new URL(request.url)
    const redirects = {
      '/old-about':   '/about',
      '/old-contact': '/contact',
    }
    const dest = redirects[url.pathname]
    if (dest) return Response.redirect(url.origin + dest, 301)
  },
}

Para un puñado de movimientos de ruta a ruta directos, usa el motor de redirección integrado: no necesita código y se configura en Settings. Consulta Configuring Redirects and Rewrites.

Agregar encabezados de seguridad

export default async function handler(request) {
  const response = await fetch(request)
  const headers = new Headers(response.headers)
  headers.set('X-Frame-Options', 'DENY')
  headers.set('X-Content-Type-Options', 'nosniff')
  headers.set('Referrer-Policy', 'strict-origin-when-cross-origin')
  return new Response(response.body, {
    status: response.status,
    statusText: response.statusText,
    headers,
  })
}

Para reglas de encabezado estático tampoco necesitas código. Settings tiene una sección de encabezados de respuesta con presets de adición rápida para HSTS, CSP, no-embed, no-sniff, política de referrer y CORS.

Enrutamiento A/B

export default {
  async fetch(request) {
    const url     = new URL(request.url)
    const variant = Math.random() < 0.5 ? 'a' : 'b'
    url.searchParams.set('variant', variant)
    return fetch(url.toString(), request)
  },
}

Alcance del entorno

Cómo interactúan múltiples funciones

Todas las funciones habilitadas de tu proyecto se evalúan en el orden en que fueron creadas. Para cada solicitud, el edge recorre la lista y ejecuta la primera función cuyo patrón de ruta coincida con la ruta de solicitud y cuyo alcance cubra el entorno.

• Si esa función devuelve Response, se envía y la evaluación se detiene.
• Si no devuelve nada, la evaluación continúa con la siguiente función coincidente.
• Si ninguna devuelve Response, la solicitud va a tu proyecto como normal.

Esto significa que una función amplia /* creada temprano puede ocultar una más estrecha creada más tarde, si la amplia devuelve Response. Crea las específicas primero, o haz que la amplia devuelva nada para las rutas que no debe manejar.

Desplegar

Haz clic en Deploy to edge. El despliegue regenera un único enrutador combinado para toda la red edge desde el estado actual de la base de datos, por lo que habilitar, deshabilitar, editar o eliminar cualquier función vuelve a publicar todo. Los cambios generalmente surten efecto en unos pocos segundos.

Cada fila de función mantiene un Deploy log que muestra los pasos del último despliegue, y un distintivo DEPLOY FAILED con el error si no tuvo éxito.

Pause saca una función del enrutador sin borrarla, que es la forma más rápida de revertir una función que se comporta mal. Resume la devuelve.

Cuando una función genera una excepción

Una excepción dentro de una función se captura en el edge. El error se registra y la solicitud cae en tu proyecto como si la función no hubiera devuelto nada.

Límites

• Hasta 20 funciones por proyecto. La 21ª se rechaza.
• Hasta 64 KB de origen por función.
• Hasta 120 caracteres para el nombre y 2048 caracteres para el patrón de ruta.

Lectura relacionada

• Configuring Redirects and Rewrites, la opción sin código para reglas de ruta
• Deploying Your Project
• Branch Preview Deployments in Orbit para probar una función antes de que llegue a producción