Introduction
Une API de support a besoin d’accéder à un catalogue géré par un autre Worker. Vous allez relier l’API publique à un catalogue interne fourni, reproduire puis corriger une liaison manquante, et déployer les deux services tout en laissant le catalogue sans point de terminaison public.
Utilisez votre propre compte Cloudflare d’apprentissage, ainsi que les connaissances sur l’autorisation, la configuration et le déploiement acquises lors des laboratoires précédents. Cette VM indépendante démarre dans /home/labex/project/service-binding avec Node.js 22.22.0, Wrangler 4.131.1 installé localement au projet et un jeu de données de catalogue synthétique. Aucune VM ni aucune ressource précédente n’est réutilisée. L’exercice ne nécessite ni domaine acheté, ni base de données, ni offre payante ; les quelques requêtes sont comptabilisées dans l’utilisation normale du compte.
Gardez un terminal ouvert. Vous utiliserez deux processus locaux, créerez deux Workers cloud temporaires portant des noms uniques, vérifierez leur connexion, supprimerez l’appelant et sa dépendance, puis vous déconnecterez avant de terminer la VM.
Reproduire une liaison de service manquante
Dans cette étape, vous allez créer une API publique dont la dépendance au catalogue n’est volontairement pas configurée. Un autre Worker fourni gère deux entrées de catalogue synthétiques. Pour le moment, les deux processus s’exécutent uniquement dans cette VM.
cd /home/labex/project/service-binding
node --version
npx wrangler --version
cat catalog/index.js
Vous devez obtenir Node v22.22.0 et Wrangler 4.131.1. La configuration a installé les dépendances locales du projet ; sur une autre machine, utilisez npm ci avec le fichier de verrouillage de ce projet. Le jeu de données renvoie le libellé d’un service public, deux entrées et une valeur de requête synthétique facultative probe permettant de suivre une requête. Il ne stocke aucune donnée.
Générez un nom de base temporaire et enregistrez les identifiants des deux ressources dans la configuration standard. Gardez ce terminal ouvert afin que WORKER_NAME reste disponible. La valeur main du catalogue est relative à son propre répertoire de configuration.
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
Le catalogue désactive à la fois workers.dev et les URL d’aperçu, et ne possède aucune route. Le développement local expose tout de même un port de bouclage pour les tests ; cela ne crée pas de point de terminaison public dans le cloud. La liste services vide de l’API publique est le défaut que vous allez diagnostiquer.
Écrivez le gestionnaire public. /health reste indépendant. /catalog vérifie que la liaison existe avant d’effectuer un appel interne. catalog.internal est une URL d’espace réservé entièrement qualifiée, et non un nom DNS à enregistrer : env.CATALOG sélectionne la destination. Nous construisons une nouvelle requête GET contenant uniquement la valeur de requête prévue, au lieu de transmettre des en-têtes arbitraires du client.
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
Démarrez le catalogue fourni et l’API comme deux tâches d’arrière-plan distinctes, avec des ports HTTP et d’inspection différents. Les journaux rendent le démarrage visible ; & rend l’invite de commande au 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
Attendez que les deux journaux indiquent que les services sont prêts, en répétant cat si nécessaire, puis examinez les réponses :
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
Le catalogue renvoie le code 200 et ses deux entrées ; le contrôle d’état renvoie le code 200 avec {"status":"ok"} ; la route de catalogue de l’API renvoie le code 503 avec {"error":"catalog_binding_missing"}. La dépendance fonctionne, mais l’appelant ne possède aucune capacité configurée pour l’atteindre. Effectuez la vérification tant que la liaison est absente.
Déclarer et tester la connexion interne
Dans cette étape, vous allez corriger la configuration sans modifier le code de l’API. Examinez les tâches d’arrière-plan réelles et arrêtez uniquement le processus de l’API ; l’exemple suppose qu’il s’agit de la tâche 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 est le nom de propriété disponible sous la forme env.CATALOG. service correspond exactement au nom configuré du Worker cible. Une différence d’orthographe dans l’un ou l’autre de ces champs constitue un problème différent : une propriété absente déclenche explicitement une réponse 503, tandis qu’une cible indisponible peut déclencher une réponse 502 ou une erreur au démarrage ou lors du déploiement. Ne remplacez pas l’appel de liaison par une URL publique utilisée avec fetch.
npx wrangler dev --config wrangler.jsonc --ip 127.0.0.1 --port 8080 --inspector-port 9231 > api.log 2>&1 &
cat api.log
Attendez que le service soit prêt et examinez la table des liaisons. Wrangler détecte le catalogue en cours d’exécution grâce à son nom et indique l’état de la connexion. Si la connexion est indiquée comme interrompue, vérifiez le processus du catalogue ainsi que les deux noms configurés, puis réessayez.
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 première réponse doit être 200 et contenir le libellé exact du service du catalogue, les deux éléments et probe: local-check. Le contrôle de méthode renvoie 405 et la route inconnue renvoie 404. Effectuez la vérification avec les deux serveurs en cours d’exécution ; elle envoie une nouvelle sonde à travers l’API publique et contrôle l’ensemble du contrat.
Les liaisons appartiennent aux environnements de configuration. Si vous utilisez ensuite --env preview, déclarez le tableau services complet sous env.preview et faites-le pointer vers la cible déployée prévue ; les liaisons de service ne sont pas héritées du niveau supérieur. Ce laboratoire utilise un environnement sans nom et ne transmet jamais --env. Consultez Wrangler environments et l’interface de liaison de service HTTP.
Déployer le service interne et l’API publique
Dans cette étape, vous allez déployer la même connexion sur votre propre compte d’apprentissage. Arrêtez les deux tâches locales réelles affichées par jobs ; l’exemple suppose qu’il s’agit des tâches 1 et 2.
jobs
kill %1 %2
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_tail:read
Ouvrez le lien affiché pour l’appareil dans votre navigateur connecté, saisissez le code actuel, vérifiez les autorisations de Wrangler et l’accès en arrière-plan, puis sélectionnez uniquement votre compte d’apprentissage comme indiqué précédemment. Attendez que le terminal termine l’opération.
npx wrangler whoami --json
Vérifiez que loggedIn: true apparaît, ainsi que le nom et l’ID réels du compte, même si un seul compte est affiché. Remplacez YOUR_ACCOUNT_ID dans les deux commandes ci-dessous par ce même ID ; conservez les noms générés à l’origine et la liaison.
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
Déployez d’abord la cible afin que la dépendance déclarée par le Worker public existe déjà. Il s’agit de deux déploiements indépendants, et non d’une seule mise en production atomique.
npx wrangler deploy --config catalog/wrangler.jsonc
npx wrangler deploy --config wrangler.jsonc
Le catalogue ne doit avoir aucune route publique. L’API affiche son URL workers.dev ainsi que sa liaison CATALOG. Copiez cette URL exacte de l’API dans la variable ci-dessous ; réutilisez le sous-domaine workers.dev déjà associé au compte. Pour un compte utilisé pour la première fois, suivez l’invite de Wrangler concernant le sous-domaine disponible sans modifier un sous-domaine existant.
API_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"
curl -i "$API_URL/health"
curl -i "$API_URL/catalog?probe=remote-check"
Vous devez obtenir une réponse 200 pour le contrôle d’état et le résultat du catalogue avec probe: remote-check. La propagation initiale du déploiement ou du nom d’hôte peut nécessiter une nouvelle tentative après un court délai ; une réponse 503 ou 502 persistante nécessite d’examiner la configuration de la liaison et le déploiement de la cible.
Ouvrez le même compte d’apprentissage dans le tableau de bord, accédez à Compute → Workers & Pages et recherchez les deux noms exacts. Ouvrez l’onglet Bindings de l’API publique. Le diagramme identifie la liaison CATALOG ; dans le tableau situé dessous, comparez Name (CATALOG) et Value (le Worker -catalog correspondant). Le nom de la liaison devient env.CATALOG dans le gestionnaire, tandis que sa valeur identifie la dépendance déployée.
Suivez le lien du Worker de catalogue dans ce tableau, puis sélectionnez son onglet Domains. Vérifiez que le fil d’Ariane supérieur se termine maintenant par -catalog. Sous Worker URL, les commutateurs Production et Preview doivent tous deux être désactivés. Sous Custom Domains and Routes, aucune entrée ne doit apparaître, comme dans l’illustration ci-dessous.
Ces noms sont des exemples ; utilisez le suffixe que vous avez généré et le sous-domaine de votre compte. Un commutateur désactivé signifie que l’adresse affichée n’est pas un point d’entrée public activé. La requête API fonctionnelle ci-dessus atteint ce Worker via sa liaison de service. Limitez cette vérification à la lecture : n’activez pas de point de terminaison public, n’ajoutez pas de route et ne dupliquez pas la liaison pour faire fonctionner l’appel interne. Effectuez la vérification : elle contrôle indépendamment la propriété du compte, la liaison de service déployée, les paramètres des points de terminaison et la réponse distante avec une nouvelle sonde. La désactivation de ces points de terminaison n’empêche pas les opérateurs autorisés du compte de créer une liaison vers le service ou de le modifier ; il ne s’agit pas d’un système de connexion utilisateur.
Supprimer l’appelant avant sa dépendance
Dans cette étape, vous allez supprimer les deux Workers cloud temporaires tout en étant encore autorisé. Les fichiers de configuration constituent l’inventaire de vos ressources. Vérifiez leurs noms générés et l’ID du compte avant la suppression.
cat wrangler.jsonc
cat catalog/wrangler.jsonc
Supprimez d’abord l’appelant public, puis le catalogue interne. Vous éviterez ainsi de laisser un appelant déployé pointer vers un service supprimé. À chaque invite, vérifiez le nom exact du laboratoire et appuyez sur la seule touche y.
npx wrangler delete --config wrangler.jsonc
npx wrangler delete --config catalog/wrangler.jsonc
Wrangler 4.131.1 peut signaler une erreur d’authentification KV liée à l’ancien système Workers Sites après la suppression du script. N’élargissez pas les autorisations et ne considérez pas ce diagnostic comme une preuve de suppression. Actualisez Workers & Pages et effectuez la vérification : un inventaire autorisé réussi doit indiquer que les deux noms exacts sont absents. Les échecs réseau ou d’authentification ne permettent pas de conclure. Préservez les autres Workers, le compte et son sous-domaine existant.
Déconnecter la VM du laboratoire
Dans cette étape, vous allez supprimer l’autorisation de la VM après avoir vérifié les deux suppressions cloud.
npx wrangler logout
npx wrangler whoami --json
Vous devez obtenir explicitement "loggedIn": false. La commande d’état sans authentification peut se terminer avec un code différent de zéro ; son résultat structuré constitue l’élément de preuve important. Effectuez la vérification, puis terminez la VM. La connexion au navigateur du tableau de bord est indépendante et peut rester active pour un autre laboratoire. Terminer la VM ne remplace ni la suppression des ressources cloud ni la déconnexion.
Résumé
Vous avez diagnostiqué une dépendance en cours d’exécution qui était absente des liaisons de l’appelant, déclaré son nom de service exact et envoyé les requêtes avec env.CATALOG.fetch(). Les sondes locales et déployées ont renvoyé l’identité et les données du catalogue. Vous avez inspecté la connexion déployée et laissé les points de terminaison publics du service interne désactivés, puis supprimé l’appelant avant sa dépendance et déconnecté la VM.
Les liaisons de service rendent explicites les connexions internes entre Workers. Les environnements nommés nécessitent leurs propres déclarations, et une connectivité locale ne prouve pas à elle seule la propriété distante ni la configuration des points de terminaison.
