← Volver al listado de tecnologías

Capítulo 1: Introducción y Configuración Segura del Entorno

Por: Tu Nombre
cloudflareworkerswranglersecuritytestingintroduccionconfiguracionvitestminiflare

Capítulo 1: Introducción y Configuración Segura del Entorno

¡Bienvenido al primer capítulo! Aquí sentaremos las bases para trabajar con Cloudflare Workers de forma segura y eficiente, preparando nuestro entorno de desarrollo y entendiendo los conceptos fundamentales.

< Volver al Índice del Tutorial

¿Qué son los Cloudflare Workers? Ventajas y Modelo de Seguridad

Cloudflare Workers es una plataforma de computación serverless que te permite ejecutar código JavaScript (y otros lenguajes compilados a WebAssembly) directamente en la red global de Edge de Cloudflare. A diferencia de las arquitecturas tradicionales donde tu código se ejecuta en un servidor centralizado, los Workers se ejecutan en centros de datos distribuidos por todo el mundo, muy cerca de tus usuarios finales.

  • Ventajas Clave:

    • Rendimiento: Al ejecutarse cerca del usuario, la latencia se reduce drásticamente, lo que mejora significativamente la velocidad de respuesta de tus aplicaciones o APIs.
    • Escalabilidad: La plataforma escala automáticamente para manejar cualquier volumen de tráfico sin que tengas que gestionar servidores.
    • Costo-Efectividad: El modelo de precios se basa en el uso real (solicitudes, tiempo de CPU, etc.), con un generoso nivel gratuito, lo que lo hace muy económico para muchos casos de uso.
    • Flexibilidad: Puedes interceptar y modificar peticiones HTTP, construir APIs completas, servir sitios estáticos dinámicamente, realizar pruebas A/B, implementar lógica de autenticación en el borde, y mucho más.

  • Modelo de Seguridad (V8 Isolates): En lugar de usar contenedores o máquinas virtuales pesadas, Cloudflare Workers utiliza los V8 Isolates, la misma tecnología que impulsa Google Chrome. Cada Worker se ejecuta en su propio isolate, proporcionando un entorno de ejecución seguro y ligero con un arranque casi instantáneo (milisegundos). Esto ofrece ventajas significativas:

    • Aislamiento Seguro: Cada isolate tiene su propia memoria y contexto, impidiendo que un Worker afecte a otro.
    • Eficiencia: Los isolates consumen muchos menos recursos que los contenedores, permitiendo una mayor densidad y menor costo.
    • Arranque Rápido: Elimina el “cold start” típico de otras plataformas serverless. La seguridad se basa en los mecanismos probados del navegador, limitando el acceso a recursos del sistema y proporcionando un entorno controlado. Es crucial entender que, aunque seguro, debemos ser conscientes de las dependencias que introducimos y seguir las mejores prácticas.

Configuración Inicial: Wrangler CLI y Gestión de Secretos

Wrangler es la interfaz de línea de comandos (CLI) oficial para desarrollar, probar y desplegar Cloudflare Workers. Es nuestra herramienta principal.

  • Instalación de Wrangler: Necesitas tener Node.js y Bun (o npm/pnpm/yarn) instalados. Para instalar la última versión de Wrangler, abre tu terminal y ejecuta:

    bun install -g wrangler
# O si usas npm: npm install -g wrangler
# O pnpm: pnpm install -g wrangler

    Verifica la instalación con wrangler --version.

  • Autenticación: Para permitir que Wrangler interactúe con tu cuenta de Cloudflare, necesitas iniciar sesión:

    wrangler login

    Esto abrirá tu navegador para que autorices a Wrangler. Sigue las instrucciones en pantalla.

  • Inicialización del Proyecto: Navega en tu terminal al directorio donde quieres crear tu proyecto y ejecuta:

    wrangler init mi-worker-seguro

    (Reemplaza mi-worker-seguro con el nombre deseado). Wrangler te hará algunas preguntas para configurar la estructura inicial del proyecto (tipo de worker, uso de TypeScript, etc.). Recomendamos usar TypeScript para mayor seguridad y mantenibilidad. Esto creará una estructura de directorios básica, incluyendo src/index.ts (tu código) y wrangler.toml (el archivo de configuración principal).

  • Gestión Segura de Secretos (wrangler.toml y wrangler secret): Nunca debes incluir claves de API, tokens u otra información sensible directamente en tu código fuente o en el archivo wrangler.toml si este se va a versionar (¡lo cual deberías hacer!). Wrangler proporciona una forma segura de manejar secretos:

    1. Definir en wrangler.toml (para variables no secretas): Puedes definir variables de entorno bajo la sección [vars]. Son útiles para configuración no sensible. 
      # wrangler.toml
name = "mi-worker-seguro"
main = "src/index.ts"
compatibility_date = "YYYY-MM-DD" # Usa la fecha actual

[vars]
MI_VARIABLE = "valor_publico"
    2. Usar wrangler secret (para información sensible): Para secretos reales, usa el comando wrangler secret put. Wrangler encriptará y almacenará este valor de forma segura, haciéndolo accesible a tu Worker a través del objeto env. 
      # Lee el valor del secreto desde la entrada estándar (más seguro)
echo "valor_super_secreto" | wrangler secret put MI_SECRETO_API
      Ahora, MI_SECRETO_API estará disponible en env.MI_SECRETO_API dentro de tu código Worker, pero su valor real no estará en tu wrangler.toml ni en tu código fuente. Importante: Necesitarás definir el tipo en la interfaz Env en tu index.ts.

Tu Primer “Hello World” Worker (con enfoque en dependencias seguras)

Vamos a crear y entender el Worker más básico.

  • Código Básico del Worker (src/index.ts): El archivo src/index.ts generado por wrangler init contendrá algo similar a esto:

    // src/index.ts
/**
 * ¡Bienvenido a Cloudflare Workers! Este es tu primer Worker.
 *
 * - Rellena la interfaz `Env` con tus bindings (D1, KV, R2, secrets, etc.)
 * - En `fetch`, escribe la lógica para manejar las peticiones entrantes.
 * - Puedes encontrar más documentación en https://developers.cloudflare.com/workers/
 */
export default {
  // El método `fetch` se ejecuta cada vez que tu Worker recibe una petición.
  async fetch(request: Request, env: Env, ctx: ExecutionContext): Promise<Response> {
    // `request`: Contiene información sobre la petición entrante (URL, método, headers, body).
    // `env`: Contiene tus bindings (variables, secretos, acceso a KV, D1, etc.).
    // `ctx`: Proporciona métodos como `waitUntil` para tareas que pueden continuar después de enviar la respuesta.

    console.log(`[${request.method}] ${request.url} - Recibida petición`);
    // Lógica simple y segura: Devolver una respuesta básica.
    // En un worker real, aquí interactuarías con `request` y `env`.
    return new Response('Hello World!');
  },
};

// Define la interfaz para tus bindings. Wrangler inferirá los tipos
// de los bindings configurados en wrangler.toml. Asegúrate de que
// los secretos añadidos con `wrangler secret put` estén definidos aquí.
interface Env {
  // Ejemplo: Si añadiste un secreto MI_SECRETO_API
  // MI_SECRETO_API: string;

  // Ejemplo: Si tienes un binding a un KV Namespace llamado MI_KV
  // MI_KV: KVNamespace;

  // Ejemplo: Si tienes un binding a una base de datos D1 llamada MI_DB
  // MI_DB: D1Database;
}

  • Explicación:

    • El objeto exportado default contiene el manejador fetch.
    • fetch es asíncrono y debe devolver una Promise<Response>.
    • La interfaz Env es crucial para que TypeScript entienda qué propiedades (bindings y secretos) están disponibles en el objeto env. Debes mantenerla actualizada a medida que añadas bindings en wrangler.toml o secretos con wrangler secret put.

  • Dependencias Seguras: Por ahora no tenemos dependencias externas, pero si las añadieras (ej: bun add alguna-libreria), es vital:

    • Auditar: Usa bun pm audit (o el equivalente de tu gestor de paquetes) regularmente para detectar vulnerabilidades conocidas.
    • Fuentes Confiables: Instala paquetes solo de fuentes reputadas.
    • Mínimo Necesario: Añade solo las dependencias estrictamente necesarias para reducir la superficie de ataque.

Testing: Configuración Inicial del Entorno de Pruebas

Configuraremos Vitest, un framework de testing moderno, junto con Miniflare, un simulador local de la runtime de Workers.

  • Instalación de Dependencias: Añade las dependencias de desarrollo necesarias:

    bun add --dev vitest miniflare @cloudflare/vitest-pool-workers
# O con npm: npm install --save-dev vitest miniflare @cloudflare/vitest-pool-workers

    @cloudflare/vitest-pool-workers integra Miniflare con Vitest.

  • Configuración de Vitest (vitest.config.ts): Crea un archivo vitest.config.ts en la raíz de tu proyecto con la siguiente configuración básica:

    // vitest.config.ts
import { defineWorkersConfig } from '@cloudflare/vitest-pool-workers/config';

export default defineWorkersConfig({
  test: {
    // Opciones de Vitest
    poolOptions: {
      workers: {
        // Opciones específicas para el pool de workers
        wrangler: { configPath: './wrangler.toml' }, // Asegúrate que la ruta a tu wrangler.toml sea correcta
      },
    },
  },
});

    Esto le dice a Vitest que use el pool de workers de Cloudflare y que cargue la configuración de tu wrangler.toml para simular los bindings.

  • Primera Prueba Unitaria (test/index.test.ts): Crea un directorio test y dentro un archivo index.test.ts (o el nombre que prefieras):

    // test/index.test.ts
// Importa utilidades de testing específicas de Cloudflare y Vitest
import { env, createExecutionContext, waitOnExecutionContext } from 'cloudflare:test';
import { describe, it, expect } from 'vitest';
// Importa tu worker (ajusta la ruta si es necesario)
import worker from '../src/index';

describe('Hello World Worker', () => {
  it('debería responder con "Hello World!" y status 200', async () => {
    // Crea una petición simulada
    const request = new Request('http://example.com');
    // Crea un contexto de ejecución simulado
    const ctx = createExecutionContext();

    // Ejecuta el manejador fetch de tu worker con el entorno y contexto simulados
    // 'env' es inyectado automáticamente por el pool de workers basado en wrangler.toml
    const response = await worker.fetch(request, env, ctx);

    // Espera a que las tareas asíncronas en ctx.waitUntil terminen (si las hubiera)
    await waitOnExecutionContext(ctx);

    // Afirmaciones (Assertions) sobre la respuesta
    expect(response.status).toBe(200);
    expect(await response.text()).toBe('Hello World!');
  });

  // Puedes añadir más tests aquí para otros casos
});

    Esta prueba simula una petición a tu worker y verifica que la respuesta sea la esperada.

  • Ejecución de Pruebas: Añade un script a tu package.json:

    // package.json
{
  // ... otras configuraciones ...
  "scripts": {
    "test": "vitest"
    // ... otros scripts como "start", "deploy" ...
  }
}

    Ahora puedes ejecutar tus pruebas con:

    bun test
# O con npm: npm test

Con estos fundamentos establecidos (Workers, Wrangler, Secretos, Testing básico), estarás listo para avanzar hacia la construcción de rutas y lógica más compleja con Hono en el siguiente capítulo, manteniendo siempre la seguridad y el testing como pilares.

< Volver al Índice del Tutorial --- Capítulo 2: Construyendo la Base con Hono >

← Volver al listado de tecnologías