Introducción
Una API de soporte necesita un catálogo administrado por otro Worker. Conectará la API pública con un catálogo interno proporcionado, reproducirá y reparará un enlace faltante, e implementará ambos servicios mientras mantiene el catálogo sin un endpoint público.
Utilice su propia cuenta de aprendizaje de Cloudflare y los conocimientos sobre autorización, configuración e implementación de laboratorios anteriores. Esta VM independiente se inicia en /home/labex/project/service-binding con Node.js 22.22.0, Wrangler 4.131.1 instalado localmente en el proyecto y un conjunto de datos sintético para el catálogo. No se reutiliza ninguna VM ni ningún recurso anterior. El ejercicio no requiere un dominio comprado, una base de datos ni una actualización de pago; las pocas solicitudes cuentan para el uso normal de la cuenta.
Mantenga una terminal abierta. Utilizará dos procesos locales, creará dos Workers desechables en la nube con nombres únicos, verificará su conexión, eliminará el llamador y la dependencia, y cerrará la sesión antes de finalizar la VM.
Reproducir un enlace de servicio faltante
En este paso, creará una API pública cuya dependencia del catálogo está deliberadamente sin configurar. Otro Worker proporcionado administra dos entradas sintéticas del catálogo. Por ahora, ambos procesos se ejecutan únicamente en esta VM.
cd /home/labex/project/service-binding
node --version
npx wrangler --version
cat catalog/index.js
Debería obtener Node v22.22.0 y Wrangler 4.131.1. La configuración instaló las dependencias locales del proyecto; en otra máquina, utilice npm ci con el archivo de bloqueo de este proyecto. El conjunto de datos devuelve la etiqueta de servicio pública, dos entradas y un valor de consulta sintético opcional probe para rastrear una solicitud. No almacena ningún dato.
Genere un nombre base desechable y registre las identidades de ambos recursos en la configuración normal. Mantenga esta terminal abierta para que WORKER_NAME siga disponible. El valor main del catálogo es relativo a su propio directorio de configuración.
WORKER_NAME="labex-binding-$(openssl rand -hex 6)"
cat > wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-09-14",
"workers_dev": true,
"preview_urls": false,
"services": []
}
CONFIG
cat > catalog/wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME-catalog",
"main": "index.js",
"compatibility_date": "2026-09-14",
"workers_dev": false,
"preview_urls": false,
"routes": [],
"vars": {"SERVICE_ID": "$WORKER_NAME-catalog"}
}
CONFIG
El catálogo desactiva tanto workers.dev como las URL de vista previa, y no tiene rutas. El desarrollo local sigue exponiendo un puerto de loopback para realizar pruebas; esto no crea un endpoint público en la nube. La lista services vacía de la API pública es el defecto que diagnosticará.
Escriba el controlador público. /health funciona de forma independiente. /catalog comprueba que el enlace exista antes de realizar una llamada interna. catalog.internal es una URL de marcador de posición completamente cualificada, no un nombre DNS que deba registrar: env.CATALOG selecciona el destino. Construimos una solicitud GET nueva con solo el valor de consulta previsto, en lugar de reenviar encabezados arbitrarios del cliente.
cat > src/index.js <<'JS'
export default {
async fetch(request, env) {
const url = new URL(request.url);
if (url.pathname === '/health' && request.method === 'GET') {
return Response.json({status: 'ok'});
}
if (url.pathname !== '/catalog') return Response.json({error: 'not_found'}, {status: 404});
if (request.method !== 'GET') {
return Response.json({error: 'method_not_allowed'}, {status: 405, headers: {Allow: 'GET'}});
}
if (!env.CATALOG) return Response.json({error: 'catalog_binding_missing'}, {status: 503});
// This hostname completes the Request URL. The binding selects the target Worker.
const target = new URL('https://catalog.internal/catalog');
target.searchParams.set('probe', url.searchParams.get('probe') || '');
try {
return await env.CATALOG.fetch(new Request(target, {method: 'GET'}));
} catch {
return Response.json({error: 'catalog_unavailable'}, {status: 502});
}
}
};
JS
Inicie el catálogo proporcionado y la API como trabajos en segundo plano separados, con puertos HTTP y de inspección distintos. Los registros permiten ver el inicio; & devuelve el prompt del shell.
npx wrangler dev --config catalog/wrangler.jsonc --ip 127.0.0.1 --port 8081 --inspector-port 9230 > catalog.log 2>&1 &
npx wrangler dev --config wrangler.jsonc --ip 127.0.0.1 --port 8080 --inspector-port 9231 > api.log 2>&1 &
cat catalog.log
cat api.log
Espere a que ambos registros indiquen que los servicios están listos. Repita cat si es necesario y, después, inspeccione las respuestas:
curl -i http://127.0.0.1:8081/catalog
curl -i http://127.0.0.1:8080/health
curl -i http://127.0.0.1:8080/catalog
El catálogo devuelve 200 y sus dos entradas; la comprobación de estado devuelve 200 {"status":"ok"}; la ruta del catálogo de la API devuelve 503 {"error":"catalog_binding_missing"}. La dependencia está en ejecución, pero el llamador no tiene configurada la capacidad necesaria para acceder a ella. Utilice la verificación mientras se mantenga este estado de enlace faltante.
Declarar y probar la conexión interna
En este paso, reparará la configuración sin cambiar el código de la API. Inspeccione los trabajos en segundo plano reales y detenga únicamente el proceso de la API; el ejemplo supone que es el trabajo 2.
jobs
kill %2
cat > wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-09-14",
"workers_dev": true,
"preview_urls": false,
"services": [{"binding": "CATALOG", "service": "$WORKER_NAME-catalog"}]
}
CONFIG
binding es el nombre de la propiedad disponible como env.CATALOG. service es el nombre exacto configurado para el Worker de destino. Un error de escritura en cualquiera de las dos partes es un problema distinto: una propiedad faltante activa el 503 explícito, mientras que un destino no disponible puede activar un 502 o un error durante el inicio o la implementación. No sustituya la llamada mediante el enlace por una URL pública de fetch.
npx wrangler dev --config wrangler.jsonc --ip 127.0.0.1 --port 8080 --inspector-port 9231 > api.log 2>&1 &
cat api.log
Espere a que el servicio esté listo e inspeccione la tabla de enlaces. Wrangler detecta el catálogo en ejecución por su nombre e informa del estado de la conexión. Si aparece como desconectado, confirme el proceso del catálogo y los dos nombres configurados; después, vuelva a intentarlo.
curl -i "http://127.0.0.1:8080/catalog?probe=local-check"
curl -i -X POST http://127.0.0.1:8080/catalog
curl -i http://127.0.0.1:8080/missing
La primera respuesta es 200 e incluye la etiqueta exacta del servicio del catálogo, ambos elementos y probe: local-check. La comprobación del método devuelve 405 y la ruta desconocida devuelve 404. Utilice la verificación con ambos servidores en ejecución; envía una nueva prueba a través de la API pública y comprueba el contrato completo.
Los enlaces pertenecen a los entornos de configuración. Si más adelante utiliza --env preview, declare la matriz services completa en env.preview y apúntela al destino implementado previsto; los enlaces de servicio no se heredan del nivel superior. Este laboratorio utiliza un único entorno sin nombre y nunca pasa --env. Consulte Entornos de Wrangler y la interfaz de enlaces de servicio HTTP.
Implementar el servicio interno y la API pública
En este paso, implementará la misma conexión en su propia cuenta de aprendizaje. Detenga los dos trabajos locales reales que muestra jobs; el ejemplo supone que son los trabajos 1 y 2.
jobs
kill %1 %2
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_tail:read
Abra el enlace del dispositivo que se muestra en su navegador con la sesión iniciada, introduzca el código actual, revise los permisos de Wrangler y el acceso en segundo plano, y seleccione únicamente su cuenta de aprendizaje, como se explicó anteriormente. Espere a que la terminal termine.
npx wrangler whoami --json
Confirme loggedIn: true y el nombre y el ID reales de la cuenta, aunque solo aparezca una cuenta. Sustituya YOUR_ACCOUNT_ID en los dos comandos siguientes por ese mismo ID; conserve los nombres generados originalmente y el enlace.
cat > catalog/wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME-catalog",
"main": "index.js",
"compatibility_date": "2026-09-14",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": false,
"preview_urls": false,
"routes": [],
"vars": {"SERVICE_ID": "$WORKER_NAME-catalog"}
}
CONFIG
cat > wrangler.jsonc <<CONFIG
{
"name": "$WORKER_NAME",
"main": "src/index.js",
"compatibility_date": "2026-09-14",
"account_id": "YOUR_ACCOUNT_ID",
"workers_dev": true,
"preview_urls": false,
"services": [{"binding": "CATALOG", "service": "$WORKER_NAME-catalog"}]
}
CONFIG
Implemente primero el destino para que la dependencia declarada por el Worker público ya exista. Son dos implementaciones independientes, no una única publicación atómica.
npx wrangler deploy --config catalog/wrangler.jsonc
npx wrangler deploy --config wrangler.jsonc
El catálogo no debería tener ninguna ruta pública. La API muestra su URL de workers.dev y su enlace CATALOG. Copie esa URL exacta de la API en la variable siguiente; reutilice el subdominio de workers.dev existente en la cuenta. Si es la primera vez que utiliza la cuenta, siga la indicación de Wrangler para elegir un subdominio disponible sin cambiar un subdominio existente.
API_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"
curl -i "$API_URL/health"
curl -i "$API_URL/catalog?probe=remote-check"
Espere una respuesta 200 para la comprobación de estado y el resultado del catálogo con probe: remote-check. La implementación inicial o la propagación del nombre de host puede requerir un breve reintento; un 503 o 502 persistente requiere inspeccionar la configuración del enlace y la implementación del destino.
Abra la misma cuenta de aprendizaje en el Dashboard, vaya a Compute → Workers & Pages y localice los dos nombres exactos. Abra la pestaña Bindings de la API pública. El diagrama identifica el enlace CATALOG; en la tabla inferior, compare Name (CATALOG) y Value (el Worker -catalog correspondiente). El nombre del enlace se convierte en env.CATALOG en el controlador, mientras que su valor identifica la dependencia implementada.
Siga el enlace del Worker de catálogo en esa tabla y, después, seleccione su pestaña Domains. Confirme que la ruta de navegación superior termina ahora en -catalog. En Worker URL, los interruptores Production y Preview deben estar desactivados. En Custom Domains and Routes, no debería haber ninguna entrada, como se muestra a continuación.
Estos son nombres de ejemplo; utilice el sufijo generado y el subdominio de su cuenta. Un interruptor desactivado significa que la dirección mostrada no es un punto de entrada público habilitado. La solicitud funcional de la API anterior llega a este Worker mediante su enlace de servicio. Mantenga esta comprobación en modo de solo lectura: no habilite un endpoint público, no añada una ruta ni duplique el enlace para que funcione la llamada interna. Utilice la verificación: comprueba de forma independiente la propiedad de la cuenta, el enlace de servicio implementado, la configuración de los endpoints y la respuesta remota con una nueva prueba. Desactivar estos endpoints no impide que los operadores autorizados de la cuenta enlacen con el servicio o lo modifiquen; no es un sistema de inicio de sesión de usuarios.
Eliminar el llamador antes que su dependencia
En este paso, eliminará los dos Workers desechables de la nube mientras sigue autorizado. Los archivos de configuración son el inventario de sus recursos. Confirme sus nombres generados y el ID de la cuenta antes de eliminarlos.
cat wrangler.jsonc
cat catalog/wrangler.jsonc
Elimine primero el llamador público y, después, el catálogo interno. Así evitará dejar un llamador implementado que apunte a un servicio eliminado. En cada solicitud de confirmación, compruebe el nombre exacto del laboratorio y pulse una sola vez la tecla y.
npx wrangler delete --config wrangler.jsonc
npx wrangler delete --config catalog/wrangler.jsonc
Wrangler 4.131.1 puede mostrar un error de autenticación de KV de Workers Sites heredado después de eliminar el script. No amplíe los permisos ni considere ese diagnóstico como una prueba de que la eliminación se realizó correctamente. Actualice Workers & Pages y utilice la verificación: un inventario autorizado correcto debe mostrar que los dos nombres exactos ya no existen. Los fallos de red o autenticación no permiten sacar conclusiones. Conserve los demás Workers, la cuenta y su subdominio existente.
Desconectar la VM del laboratorio
En este paso, eliminará la autorización de la VM después de verificar las dos eliminaciones en la nube.
npx wrangler logout
npx wrangler whoami --json
Debería obtener explícitamente "loggedIn": false. El comando de estado sin autenticación puede terminar con un código distinto de cero; el resultado estructurado es la evidencia importante. Utilice la verificación y, después, finalice la VM. La sesión iniciada en el navegador del Dashboard es independiente y puede permanecer abierta para otro laboratorio. Finalizar la VM no sustituye la eliminación en la nube ni el cierre de sesión.
Resumen
Diagnosticó una dependencia en ejecución que faltaba en los enlaces del llamador, declaró su nombre exacto de servicio y envió solicitudes mediante env.CATALOG.fetch(). Las pruebas locales y remotas devolvieron la identidad y los datos del catálogo. Inspeccionó la conexión implementada y mantuvo desactivados los endpoints públicos del servicio interno; después, eliminó el llamador antes que su dependencia y desconectó la VM.
Los enlaces de servicio hacen explícitas las conexiones internas entre Workers. Los entornos con nombre requieren sus propias declaraciones, y la conectividad local por sí sola no demuestra la propiedad remota ni la configuración de los endpoints.
