Servir las preferencias de una cuenta con Workers KV

Introducción

Un sitio web puede recordar opciones de visualización, como un tema oscuro o el idioma preferido. Estas configuraciones suelen leerse en cada visita, pero solo cambian ocasionalmente, por lo que son un buen ejemplo para Workers KV. En lugar de almacenar una sola palabra como indicador de funcionalidad, almacenará JSON: texto que agrupa campos con nombre en un único valor. Su Worker convertirá ese texto nuevamente en configuraciones utilizables.

En este laboratorio, Alice y Bob son etiquetas ficticias de cuentas, no usuarios reales. Les asignará preferencias diferentes y hará que las entradas ausentes o dañadas devuelvan un valor predeterminado razonable. También adjuntará metadatos, una pequeña descripción almacenada junto con un valor, para identificar la revisión de una configuración. Los números de revisión ayudan a explicar qué datos se leyeron; no garantizan que todas las ubicaciones vean inmediatamente el valor más reciente.

Complete primero Crear un almacén de indicadores de funcionalidad. Este laboratorio comienza en una VM nueva, en /home/labex/project/account-preferences, con Node.js 22.22.0 y Wrangler 4.131.1 instalado localmente en el proyecto. Creará un Worker y un espacio de nombres nuevos en su cuenta de aprendizaje, utilizando los mismos permisos de lectura de la cuenta, escritura de Workers y escritura de KV. La demostración pública solo expone configuraciones de visualización sintéticas; la etiqueta de cuenta incluida en la URL no es un mecanismo de autenticación. No necesita una ampliación de pago ni un dominio comprado para este ejercicio breve. Termine de eliminar los recursos antes de salir de la VM.

Conectar un espacio de nombres de preferencias

En este paso, conectará un espacio de nombres independiente para las preferencias de cuentas de ejemplo. Un espacio de nombres agrupa los valores de este servicio; el binding PREFERENCES proporciona a su Worker un nombre estable para acceder a ellos. Esta VM nueva reutiliza la información de su cuenta, pero no el espacio de nombres ni la autorización del laboratorio anterior.

Entre en el proyecto preparado:

cd /home/labex/project/account-preferences

Genere un nombre único una sola vez. openssl rand -hex 6 muestra un sufijo aleatorio; $(...) lo inserta en el nombre. La variable de shell mantiene ese nombre disponible para los comandos siguientes en este terminal.

WORKER_NAME="labex-prefs-$(openssl rand -hex 6)"

printf '%s\n' "$WORKER_NAME"

Autorice esta VM. Además de leer la identidad de su cuenta, Workers Scripts Write permite implementar y eliminar recursos, y Workers KV Write permite administrar el espacio de nombres y las claves de este laboratorio.

npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_kv:write

Abra en el navegador el enlace del dispositivo que se muestra, introduzca el código actual, revise los permisos solicitados y la cuenta de aprendizaje, y autorice Wrangler. En la página de consentimiento también puede aparecer el acceso en segundo plano. Vuelva al terminal y espere a que termine el inicio de sesión.

Expanda Developer Platform para revisar Workers Scripts Write y Workers KV Storage Write. Estos son los mismos permisos de administración de recursos que se introdujeron en Crear un almacén de indicadores de funcionalidad.

npx wrangler whoami --json

Confirme loggedIn: true y el name de la cuenta de aprendizaje, aunque solo aparezca una cuenta. Copie el id de esa cuenta. Guárdelo en la configuración siguiente, reemplazando YOUR_ACCOUNT_ID antes de ejecutar el comando. El here-document de cat escribe en un archivo todo lo que se encuentra entre las dos líneas JSON; > reemplaza el archivo. El delimitador sin comillas permite que el shell inserte $WORKER_NAME.

cat > wrangler.jsonc <<JSON
{
  "name": "$WORKER_NAME",
  "main": "src/index.js",
  "compatibility_date": "2026-07-30",
  "account_id": "YOUR_ACCOUNT_ID",
  "workers_dev": true
}
JSON

Cree un espacio de nombres en esa cuenta. Su título comparte el nombre único del Worker para que pueda reconocer ambos recursos más adelante. --update-config=false deja visible para usted la modificación del binding en lugar de cambiar el archivo automáticamente.

npx wrangler kv namespace create "$WORKER_NAME-preferences" --update-config=false

La salida incluye el ID del nuevo espacio de nombres. Cópielo y, después, reemplace YOUR_ACCOUNT_ID y YOUR_NAMESPACE_ID en esta configuración completa. El nombre del binding PREFERENCES se utiliza en su código; el ID identifica el recurso real de Cloudflare.

cat > wrangler.jsonc <<JSON
{
  "name": "$WORKER_NAME",
  "main": "src/index.js",
  "compatibility_date": "2026-07-30",
  "account_id": "YOUR_ACCOUNT_ID",
  "workers_dev": true,
  "kv_namespaces": [
    { "binding": "PREFERENCES", "id": "YOUR_NAMESPACE_ID" }
  ]
}
JSON

npx wrangler kv namespace list

Busque el título del espacio de nombres de este laboratorio y compare su ID con el del archivo. Puede haber otros espacios de nombres; no los modifique. Esta configuración registra qué cuenta y qué recurso deben utilizar los comandos posteriores. Un binding es una referencia a un espacio de nombres, no una copia de sus datos.

Almacenar valores JSON y metadatos de revisión

En este paso, preparará un conjunto de datos pequeño que incluye configuraciones normales y dos errores de datos realistas. JSON utiliza comillas dobles para los nombres de campos y las cadenas. Las comillas simples alrededor del argumento del comando evitan que el shell interprete esas comillas dobles del JSON.

Escriba las entradas locales. Alice prefiere el modo oscuro y el inglés; Bob prefiere el modo claro y el francés. --metadata adjunta un objeto JSON independiente a la clave. Aquí, su número revision es una etiqueta para la versión guardada, no una decisión de seguridad ni un contador de actualizaciones automático.

npx wrangler kv key put account:alice '{"theme":"dark","language":"en"}' --binding PREFERENCES --local --metadata '{"revision":7}'

npx wrangler kv key put account:bob '{"theme":"light","language":"fr"}' --binding PREFERENCES --local --metadata '{"revision":8}'

npx wrangler kv key put account:broken 'not-json' --binding PREFERENCES --local

npx wrangler kv key put account:invalid '{"theme":"neon","language":"en"}' --binding PREFERENCES --local

account:broken contiene texto que no se puede analizar como JSON. account:invalid es JSON válido, pero indica un tema que la aplicación no admite. Conservar ambos casos le ayuda a distinguir el análisis sintáctico —leer la estructura del texto— de la validación —comprobar si sus campos tienen sentido para la aplicación—. No cree una entrada para Charlie; esto probará la ruta de clave ausente.

npx wrangler kv key list --binding PREFERENCES --local

Busque cuatro nombres de clave. Alice y Bob deben tener metadatos de revisión 7 y 8. Las otras dos entradas no tienen metadatos. El listado muestra los nombres y los metadatos; no muestra todos los valores.

npx wrangler kv key get account:alice --binding PREFERENCES --local --text

Espere {"theme":"dark","language":"en"}. El comando lee únicamente el valor, por lo que la revisión no forma parte de este texto JSON.

Ahora escriba las mismas cuatro entradas sintéticas en el espacio de nombres en la nube de este laboratorio. Estos comandos remotos explícitos son operaciones independientes: las escrituras locales nunca se cargan automáticamente en Cloudflare.

npx wrangler kv key put account:alice '{"theme":"dark","language":"en"}' --binding PREFERENCES --remote --metadata '{"revision":7}'

npx wrangler kv key put account:bob '{"theme":"light","language":"fr"}' --binding PREFERENCES --remote --metadata '{"revision":8}'

npx wrangler kv key put account:broken 'not-json' --binding PREFERENCES --remote

npx wrangler kv key put account:invalid '{"theme":"neon","language":"en"}' --binding PREFERENCES --remote

npx wrangler kv key list --binding PREFERENCES --remote

Confirme los mismos cuatro nombres de clave y sus metadatos de revisión. Son registros de demostración desechables. No modifique los espacios de nombres que no estén relacionados.

Leer preferencias con valores predeterminados seguros

En este paso, escribirá un handler que recupera el valor y los metadatos conjuntamente. getWithMetadata() devuelve un objeto con los campos value y metadata. Una clave ausente tiene un valor null. Los metadatos también pueden ser null, incluso cuando existe un valor.

Escriba este handler. El here-document JS entre comillas conserva el código exactamente. La ruta acepta una etiqueta de cuenta corta en minúsculas y construye una clave distinta, como account:alice; nunca almacena la cuenta de una solicitud anterior en una variable global.

cat > src/index.js <<'JS'
function fallback(account, source) {
  return Response.json({
    account, theme: "light", language: "en", source, revision: null
  });
}

export default {
  async fetch(request, env) {
    const match = new URL(request.url).pathname.match(/^\/preferences\/([a-z]{1,20})$/);
    if (!match) return new Response("Not found", { status: 404 });
    const account = match[1];
    let entry;
    try {
      entry = await env.PREFERENCES.getWithMetadata(`account:${account}`, "text");
    } catch {
      return Response.json({ error: "Preferences temporarily unavailable" }, { status: 503 });
    }
    if (entry.value === null) return fallback(account, "missing");

    let preferences;
    try {
      preferences = JSON.parse(entry.value);
    } catch {
      return fallback(account, "invalid");
    }
    if (!preferences || typeof preferences !== "object" || Array.isArray(preferences) ||
        !["light", "dark"].includes(preferences.theme) ||
        !["en", "fr"].includes(preferences.language)) {
      return fallback(account, "invalid");
    }
    const revision = Number.isInteger(entry.metadata?.revision) && entry.metadata.revision > 0
      ? entry.metadata.revision : null;
    return Response.json({
      account, theme: preferences.theme, language: preferences.language,
      source: "stored", revision
    });
  }
};
JS

El primer try/catch gestiona una lectura de KV no disponible con HTTP 503, que significa que el servicio no está disponible temporalmente. No finge que la cuenta no existe. Leer como "text" y analizar después el contenido en un try/catch separado permite identificar un JSON dañado sin confundirlo con un fallo de almacenamiento. Leer con la opción "json" puede realizar el análisis automáticamente, pero esta lección separa ambas operaciones para que las rutas de error sean visibles.

Tanto las preferencias ausentes como las no válidas vuelven al modo claro y al inglés. El campo source explica por qué se utilizó el valor predeterminado. Para un valor válido, la respuesta utiliza únicamente los campos admitidos de tema e idioma. entry.metadata?.revision gestiona de forma segura la ausencia de metadatos; muestra una revisión entera positiva y, en cualquier otro caso, devuelve null. Estos valores predeterminados mantienen utilizables las opciones de visualización, pero no sustituyen la autenticación ni los permisos.

Inicie el Worker local, guarde su ID de proceso y espere el mensaje de disponibilidad:

npx wrangler dev --local --ip 0.0.0.0 --port 8080 > local.log 2>&1 &

DEV_PID=$!

cat local.log

El proceso en segundo plano mantiene libre el terminal; local.log contiene su salida. Repita el comando del registro si el inicio todavía no ha terminado. Solicite cada caso:

curl -i http://127.0.0.1:8080/preferences/alice

curl -i http://127.0.0.1:8080/preferences/bob

curl -i http://127.0.0.1:8080/preferences/charlie

curl -i http://127.0.0.1:8080/preferences/broken

curl -i http://127.0.0.1:8080/preferences/invalid

Los cinco casos deben devolver HTTP 200 con JSON. Compruebe las diferencias:

Cuenta	Tema	Idioma	Origen	Revisión
alice	dark	en	stored	7
bob	light	fr	stored	8
charlie	light	en	missing	null
broken	light	en	invalid	null
invalid	light	en	invalid	null

Por ejemplo, el cuerpo de la respuesta de Alice es {"account":"alice","theme":"dark","language":"en","source":"stored","revision":7}. Vuelva a solicitar Alice después de Bob: las configuraciones deben seguir perteneciendo a Alice. Mantenga el servidor local en ejecución hasta la limpieza.

Verificar el servicio de preferencias implementado

En este paso, ejecutará los mismos casos contra el espacio de nombres en la nube. La comprobación independiente en la nube verifica la cuenta seleccionada, el binding del espacio de nombres implementado, los registros almacenados y las respuestas HTTP reales.

npx wrangler deploy

Confirme en la salida el nombre generado del Worker y el binding PREFERENCES. Copie la dirección pública implementada en la variable siguiente y reemplace el ejemplo:

WORKER_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"

curl -i "$WORKER_URL/preferences/alice"

curl -i "$WORKER_URL/preferences/bob"

curl -i "$WORKER_URL/preferences/charlie"

curl -i "$WORKER_URL/preferences/broken"

curl -i "$WORKER_URL/preferences/invalid"

Compare las cinco respuestas con la tabla local. Alice y Bob deben conservar sus propias preferencias y metadatos de revisión; Charlie y los dos registros dañados deben utilizar los valores predeterminados explicados. Si una entrada escrita recientemente todavía no es visible, espere a que se propague en KV y vuelva a intentarlo. Es posible que el nombre de host público también necesite tiempo después de la primera implementación. No considere un error de conexión como una respuesta de valor predeterminado.

En el Dashboard, seleccione la cuenta de aprendizaje, abra Storage & databases → Workers KV y busque el espacio de nombres labex-prefs-...-preferences de este laboratorio. Seleccione KV Pairs, inspeccione los cuatro registros y pulse View junto a account:alice para comparar su valor JSON con el terminal. Esta vista muestra claves y valores; compare los metadatos de revisión mediante la lista de claves de Wrangler anterior y la respuesta de la API. El nombre único y los IDs serán diferentes de los del ejemplo.

Alice preference value in the learning namespace

El endpoint público solo es una demostración de configuraciones de visualización sintéticas. Un servicio real de preferencias privadas identificaría primero a quien realiza la solicitud antes de decidir a qué clave de cuenta puede acceder.

Eliminar los recursos en la nube desechables

En este paso, eliminará ambos recursos mientras Wrangler todavía está autorizado. Un espacio de nombres puede sobrevivir a su Worker, por lo que eliminar únicamente la aplicación no limpia sus datos.

Detenga el proceso de desarrollo local iniciado en este terminal:

kill "$DEV_PID"

Inspeccione las referencias de recursos guardadas antes de eliminar nada:

cat wrangler.jsonc

Confirme el nombre del Worker labex-prefs-... y el ID del espacio de nombres PREFERENCES. Elimine el Worker seleccionado por esta configuración:

npx wrangler delete

Si se le solicita confirmación, compruebe que el nombre mostrado coincide con el de este laboratorio y confirme con y. Después, elimine únicamente el espacio de nombres referenciado por PREFERENCES:

npx wrangler kv namespace delete --binding PREFERENCES

Revise el espacio de nombres en cualquier solicitud de confirmación antes de aceptarla. Mantenga intacto wrangler.jsonc para que la comprobación independiente pueda identificar los recursos que deberían estar ausentes.

npx wrangler kv namespace list

El espacio de nombres de este laboratorio debe haber desaparecido; los espacios de nombres no relacionados deben permanecer. Actualice las listas del Dashboard para confirmar que el Worker y el espacio de nombres del laboratorio ya no aparecen. Una solicitud fallida o una sesión de inicio de sesión expirada no demuestra que se haya eliminado el recurso. Ejecute la comprobación de este paso antes de cerrar sesión para que pueda inspeccionar un inventario autorizado.

Finalizar la autorización de la VM

En este paso, desconectará Wrangler después de que la comprobación de limpieza se haya completado correctamente. Cerrar sesión finaliza la autorización de Wrangler guardada en esta VM; no elimina recursos de la nube ni cierra la sesión normal del Dashboard en el navegador.

npx wrangler logout

npx wrangler whoami --json

Confirme que el resultado estructurado informa "loggedIn": false. Este comando sin autenticación puede terminar con un código de salida distinto de cero, lo cual es esperado aquí. Si solo aparece un error de conexión y no un estado de autenticación explícito, vuelva a intentarlo cuando la conexión funcione.

Los archivos locales restantes y el estado local de KV pertenecen a esta VM desechable. Son independientes de los recursos de la nube que ya eliminó. Ahora puede finalizar el laboratorio.

Resumen

Almacenó preferencias estructuradas y metadatos de revisión en Workers KV y después los leyó mediante un binding de Worker. Mantuvo separadas las configuraciones de Alice y Bob e hizo que los valores ausentes, malformados o no admitidos produjeran valores predeterminados explicados. También distinguió un fallo de almacenamiento de un registro ausente, en lugar de ocultar ambos detrás de la misma respuesta.

Después de comparar las respuestas locales y en la nube, eliminó el Worker y el espacio de nombres desechables y cerró la sesión. A continuación, asignará a los avisos temporales una fecha límite de aplicación y una expiración de KV.