Descripción general de Workers perimetrales e inicio rápido

Los Workers perimetrales son funciones JavaScript que se ejecutan en los nodos perimetrales de la CDN. Cuando una solicitud llega al nodo y supera las comprobaciones de seguridad, se ejecuta un Worker cuya ruta coincida antes de consultar la caché y antes de enviar la solicitud al origen. Un Worker puede:

• Responder directamente: devolver contenido personalizado o una redirección sin contactar con el origen.
• Reescribir la solicitud al origen: añadir o sobrescribir encabezados de solicitud (y, de forma opcional, cambiar el método y la ruta) y después continuar hacia el origen.
• Dejar pasar la solicitud: no cambiar nada, de modo que la solicitud se procese según la configuración normal del dominio.

El modelo de programación sigue el de Cloudflare Workers: exporte export default { fetch(request, env, ctx) } y devuelva una Response. Cada ejecución se realiza en un entorno aislado nuevo. No se comparte ningún estado global entre solicitudes.

#Páginas de la consola

#Inicio rápido

#Paso 1: Crear un Worker

1. Vaya a CDN → Workers y haga clic en Crear Worker en la esquina superior derecha.
2. Introduzca un Nombre, que es obligatorio, y una Descripción opcional.
3. Puede seleccionar un ejemplo en el menú desplegable Comenzar desde una plantilla para cargarlo en el editor. Los ejemplos incluyen respuesta personalizada, redirección, token de autenticación, herramientas criptográficas y reenvío mediante fetch. También puede pegar el ejemplo siguiente.
4. Asegúrese de que el interruptor Activar esté encendido y haga clic en Guardar.

Después de guardar, el editor abre la página de detalles del Worker con su número de versión en la parte superior. La versión aumenta en uno cada vez que guarda código nuevo.

#Paso 2: Escribir el código

Este ejemplo mínimo devuelve JSON desde el nodo perimetral para /hello. Las demás rutas se envían al origen como de costumbre.

export default {
  async fetch(request, env, ctx) {
    // request.url may be "/hello?x=1" or a full URL, so extract the path
    const path = request.url.replace(/^https?:\/\/[^\/]+/, "").split("?")[0];

    if (path === "/hello") {
      return Response.json({
        message: "Hello from the edge",
        host: request.headers.get("host"),
        method: request.method,
      });
    }

    // Not handled here: pass through to the origin
    return { action: "continue" };
  },
};

#Paso 3: Vincularlo a un dominio

1. Vaya a CDN → Dominios CDN, abra el dominio y cambie a la pestaña Worker.
2. Haga clic en Añadir vínculo. En el cuadro de diálogo:
   • Seleccione un Worker: seleccione el Worker que acaba de crear. Solo se muestran los Workers activados.
   • Patrón de ruta: por ejemplo, /hello, o /* para todas las rutas. Las reglas se explican más adelante.
   • Prioridad: 0–999. Los números más altos tienen prioridad.
   • Activar: déjelo encendido.
3. Haga clic en Guardar. La configuración se envía automáticamente a los nodos perimetrales y normalmente entra en vigor en poco tiempo.

#Paso 4: Probar

curl -i https://www.example.com/hello

Una respuesta 200 con el JSON anterior indica que el Worker está en funcionamiento. Las demás rutas deberían comportarse exactamente igual que antes de añadir la vinculación.

#Interfaz de programación

#Punto de entrada

La forma recomendada es export default { fetch(request, env, ctx) { ... } }. fetch puede ser una función normal o async. La plataforma también acepta export default function (request) {} y una función global function handler(request) {}.

#El objeto de solicitud

#Valores de retorno

Por ejemplo, este Worker etiqueta las solicitudes al origen con un grupo A/B:

export default {
  fetch(request) {
    const cookie = request.headers.get("cookie") || "";
    const m = /ab_bucket=(A|B)/.exec(cookie);
    const bucket = m ? m[1] : (Math.random() < 0.5 ? "A" : "B");
    return { action: "rewrite", headers: { "x-ab-bucket": bucket } };
  },
};

#Elementos globales disponibles

• fetch(url, init): realiza una subsolicitud a una dirección HTTP/HTTPS pública y devuelve Promise<Response> con status, ok, headers, text() y json(). Puede usar return fetch(url) para enviar el resultado directamente al cliente.
• Headers, Request, Response, TextEncoder / TextDecoder, btoa / atob.
• crypto.subtle.digest, crypto.subtle.importKey / sign / verify (HMAC), crypto.getRandomValues, crypto.randomUUID y las funciones auxiliares crypto.md5(), crypto.sha1(), crypto.sha256() y crypto.hmac(), que devuelven cadenas hexadecimales.

Restricciones de las subsolicitudes:

• Solo http/https en los puertos 80 y 443.
• Las direcciones privadas, de bucle local y de enlace local se rechazan siempre.
• Se siguen como máximo 3 redirecciones. Cada subsolicitud tiene un tiempo de espera de 10 segundos y los cuerpos de respuesta están limitados a 8 MiB.

#Patrones de ruta

Un patrón de ruta se compara únicamente con la ruta de la solicitud, sin el nombre de host ni la cadena de consulta. Debe coincidir con la ruta completa.

• * coincide con cualquier secuencia de caracteres, incluido /, por lo que abarca varios niveles de directorio. ** se comporta igual que *.
• ? coincide con un solo carácter.
• Un patrón vacío, * o /* coincide con todas las rutas.

Se ejecuta como máximo un Worker por solicitud. Si coinciden varias vinculaciones, solo se ejecuta la de mayor prioridad. Asigne prioridades distintas a las vinculaciones que se superpongan.

#Límites de recursos

#Errores y depuración

Cuando un Worker lanza una excepción, tiene un error de sintaxis, agota el tiempo de espera o supera un límite, la plataforma permite que la solicitud continúe. La solicitud sigue hacia el origen como si no hubiera ningún Worker vinculado y no se muestra ninguna página de error. Si no obtiene el resultado esperado, compruebe primero que el código se ejecute correctamente.

#Activar, desactivar y eliminar

• Cuando Desactivar un Worker en la lista de Workers, deja de ejecutarse en todos los dominios. También puede desactivar una vinculación individual en la pestaña Worker de un dominio.
• Al eliminar un Worker, deja de ejecutarse en todos los dominios a los que estaba vinculado.
• Al guardar código nuevo, todos los dominios vinculados a ese Worker se actualizan automáticamente.

#Planes y cuotas

El número de rutas de Worker (vinculaciones) por dominio depende del plan CDN vinculado a ese dominio. Al momento de redactar esta guía, los planes CDN Starter, Professional y Enterprise permiten 5 por dominio cada uno. Consulte los valores vigentes en la página Planes. Cuando alcanza el límite, la consola muestra el aviso "Se ha alcanzado el límite de rutas de Worker". Para añadir más, mejore su plan o elimine vinculaciones existentes.

#Administrar Workers mediante la API

Cada acción de la consola corresponde a una llamada a la API de usuario. Autentíquese con su token de inicio de sesión en un encabezado Authorization: Bearer <token>:

# Create a Worker (include an "id" field to update an existing one)
curl -X POST https://api.yeap.cloud/api/user/cdn/workers/save \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"name":"hello","code":"export default { fetch(){ return new Response(\"hi\"); } };","enabled":true}'

# Bind it to a domain
curl -X POST https://api.yeap.cloud/api/user/cdn/domains/www.example.com/workers/save \
  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
  -d '{"worker_id":123,"route_pattern":"/hello","priority":10,"enabled":true}'

Otros endpoints:

• Workers: GET /api/user/cdn/workers (lista), GET /api/user/cdn/workers/detail?id= (detalles, incluido el código), POST /api/user/cdn/workers/toggle y DELETE /api/user/cdn/workers/delete (cuerpo JSON {"id":...}).
• Vinculaciones de dominio: GET /api/user/cdn/domains/<domain>/workers, POST .../workers/toggle y DELETE .../workers/delete.

#Funciones no admitidas actualmente

• Leer el cuerpo de la solicitud.
• Establecer variables de entorno o KV para un Worker en la consola (env es un objeto vacío).
• Modificar la respuesta devuelta por el origen. La plantilla "reescritura de encabezados de respuesta" no tiene efecto actualmente. Para añadir encabezados de respuesta, utilice la función de reglas del dominio.
• El trabajo en segundo plano pasado a ctx.waitUntil(), cuya ejecución no está garantizada después de enviar la respuesta.
• Registros de ejecución y depuración en línea.