Introduction
Un centre d’aide peut lire son thème et sa bannière d’accueil depuis KV. Un éditeur peut ainsi modifier ces paramètres sans déployer de nouveau code. Après une mise à jour, des lecteurs situés à des endroits différents peuvent voir brièvement des versions différentes. L’application doit rester utilisable pendant cette transition, au lieu de supposer que chaque lecture renvoie toujours les paramètres les plus récents.
Vous allez construire un lecteur de configuration versionné avec des valeurs par défaut sûres, tester une séquence simulée de valeurs anciennes et nouvelles, puis effectuer une véritable mise à jour dans le cloud. Une version est une étiquette enregistrée avec les paramètres ; elle vous aide à identifier la valeur reçue. Elle ne transforme pas KV en base de données fortement cohérente et ne garantit pas que des requêtes successives voient des numéros de version croissants.
Terminez d’abord les travaux pratiques KV précédents. Cette VM indépendante contient Node.js 22.22.0 et Wrangler 4.131.1 installé localement dans /home/labex/project/delayed-config. Utilisez votre propre compte d’apprentissage avec les mêmes autorisations de lecture du compte, d’écriture pour les Workers et d’écriture pour KV. L’exercice crée un Worker et un namespace temporaires, et n’expose que des paramètres d’affichage synthétiques. Aucun abonnement payant ni domaine acheté n’est nécessaire pour ce petit jeu de données. Ces paramètres ne contrôlent ni l’autorisation, ni les paiements, ni d’autres décisions nécessitant une mise à jour immédiatement approuvée par une source de référence.
Connecter un magasin de configuration indépendant
Dans cette étape, vous allez connecter un nouveau namespace destiné à la configuration d’affichage. La liaison CONFIG conserve la référence de la ressource dans la configuration standard de Wrangler. Utilisez de nouvelles ressources de laboratoire afin que des paramètres volontairement invalides ne puissent pas affecter une autre application.
Accédez au projet préparé :
cd /home/labex/project/delayed-config
Générez un nom unique une seule fois. openssl rand -hex 6 affiche un suffixe aléatoire ; $(...) l’insère dans le nom. La variable shell conserve ce nom pour les commandes suivantes exécutées dans ce terminal.
WORKER_NAME="labex-config-$(openssl rand -hex 6)"
printf '%s\n' "$WORKER_NAME"
Autorisez cette VM. En plus de lire l’identité de votre compte, Workers Scripts Write permet le déploiement et la suppression, tandis que Workers KV Write permet de gérer le namespace et les clés de ce laboratoire.
npx wrangler login --device --browser=false --scopes account:read user:read workers_scripts:write workers_kv:write
Ouvrez dans votre navigateur le lien d’appareil affiché, saisissez le code actuel, vérifiez les autorisations demandées et le compte d’apprentissage, puis autorisez Wrangler. Un accès en arrière-plan peut également apparaître sur la page de consentement. Revenez au terminal et attendez la fin de la connexion.
Vérifiez les mêmes autorisations d’écriture pour les Workers et KV que celles introduites précédemment dans ce cours, puis confirmez le compte d’apprentissage.
npx wrangler whoami --json
Vérifiez que loggedIn: true apparaît ainsi que le name du compte d’apprentissage, même si un seul compte est répertorié. Copiez l’id de ce compte. Enregistrez-le dans la configuration ci-dessous en remplaçant YOUR_ACCOUNT_ID avant d’exécuter la commande. Le here-document cat écrit dans un fichier tout ce qui se trouve entre les deux lignes JSON ; > remplace le fichier. Le délimiteur non placé entre guillemets permet au shell d’insérer $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
Créez un namespace dans ce compte. Son titre reprend le nom unique du Worker afin que vous puissiez reconnaître les deux ressources plus tard. --update-config=false laisse la modification de la liaison visible afin que vous puissiez l’effectuer vous-même, au lieu de modifier automatiquement le fichier.
npx wrangler kv namespace create "$WORKER_NAME-config" --update-config=false
La sortie contient l’ID du nouveau namespace. Copiez-le, puis remplacez YOUR_ACCOUNT_ID et YOUR_NAMESPACE_ID dans cette configuration complète. Le nom de liaison CONFIG est choisi pour votre code ; l’ID identifie la ressource Cloudflare réelle.
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": "CONFIG", "id": "YOUR_NAMESPACE_ID" }
]
}
JSON
npx wrangler kv namespace list
Trouvez le titre du namespace de ce laboratoire et comparez son ID avec celui du fichier. D’autres namespaces peuvent être présents ; laissez-les inchangés. Cette configuration indique à quel compte et à quelle ressource les commandes suivantes doivent accéder. Une liaison est une référence vers un namespace, et non une copie de ses données.
Lire des paramètres versionnés avec des valeurs par défaut sûres
Dans cette étape, vous allez permettre aux deux versions valides de produire des réponses utilisables. Si les paramètres d’affichage sont absents ou endommagés, l’application utilise un thème clair simple et aucune bannière. Ainsi, un paramètre de présentation facultatif ne peut pas interrompre le centre d’aide.
Écrivez le gestionnaire. L’objet defaults fixe ne contient aucun état propre à la requête et n’est jamais modifié. Chaque requête lit son propre résultat KV.
cat > src/index.js <<'JS'
const defaults = { version: 0, theme: "light", banner: "", source: "default" };
export default {
async fetch(request, env) {
const url = new URL(request.url);
if (url.pathname === "/health") return Response.json({ status: "ok" });
const key = url.searchParams.get("key") ?? "config:current";
if (url.pathname !== "/settings" || !/^config:[a-z0-9-]{1,20}$/.test(key)) {
return new Response("Not found", { status: 404 });
}
let value;
try {
value = await env.CONFIG.get(key, { type: "text", cacheTtl: 60 });
} catch {
return Response.json({ error: "Settings temporarily unavailable" }, { status: 503 });
}
if (value === null) return Response.json(defaults);
let settings;
try {
settings = JSON.parse(value);
} catch {
return Response.json(defaults);
}
if (!settings || !Number.isSafeInteger(settings.version) || settings.version < 1 ||
!["light", "dark"].includes(settings.theme) ||
typeof settings.banner !== "string" || settings.banner.length > 80) {
return Response.json(defaults);
}
return Response.json({
version: settings.version, theme: settings.theme,
banner: settings.banner, source: "stored"
});
}
};
JS
La requête envoyée à KV utilise cacheTtl: 60, une durée de mise en cache de lecture exprimée en secondes. Cette option n’expire pas la clé enregistrée. Elle ne demande pas non plus à chaque emplacement de récupérer la valeur la plus récente. Les valeurs existantes comme les résultats correspondant à une clé absente peuvent être mis en cache. Effectuez peu d’écritures et concevez l’application pour qu’elle tolère une configuration valide mais ancienne.
Le gestionnaire vérifie la version, le thème pris en charge et la longueur de la bannière avant de les utiliser. La route /health répond sans lire les paramètres facultatifs. Une erreur de stockage produit toujours explicitement une réponse 503 sur /settings ; l’application ne prétend pas à tort avoir chargé les valeurs par défaut depuis le stockage.
Créez deux petits fichiers de version. Le fait de conserver chaque valeur prévue dans un fichier ordinaire facilite sa vérification avant l’écriture :
cat > config-v1.json <<'JSON'
{"version":1,"theme":"light","banner":"Welcome"}
JSON
cat > config-v2.json <<'JSON'
{"version":2,"theme":"dark","banner":"New help center"}
JSON
Écrivez-les dans des clés locales distinctes servant de jeux de test, ainsi qu’une valeur mal formée. Ces clés rendent les entrées possibles reproductibles ; elles ne simulent pas la temporalité du réseau Cloudflare.
npx wrangler kv key put config:v1 --path config-v1.json --binding CONFIG --local
npx wrangler kv key put config:v2 --path config-v2.json --binding CONFIG --local
npx wrangler kv key put config:broken broken-json --binding CONFIG --local
npx wrangler dev --local --ip 0.0.0.0 --port 8080 > local.log 2>&1 &
DEV_PID=$!
cat local.log
Attendez le message indiquant que le serveur est prêt. Comparez ensuite les deux clés sélectionnées explicitement :
curl -i 'http://127.0.0.1:8080/settings?key=config:v1'
curl -i 'http://127.0.0.1:8080/settings?key=config:v2'
Les deux requêtes renvoient HTTP 200 avec source: "stored". La version 1 utilise le thème clair et Welcome ; la version 2 utilise le thème sombre et New help center. Aucune version ne dépend du résultat d’une requête précédente.
curl -i 'http://127.0.0.1:8080/settings?key=config:missing'
curl -i 'http://127.0.0.1:8080/settings?key=config:broken'
Les deux requêtes doivent renvoyer {"version":0,"theme":"light","banner":"","source":"default"}. La version 0 est l’étiquette par défaut de l’application ; elle ne correspond pas à une révision KV enregistrée.
curl -i http://127.0.0.1:8080/health
Vous devez obtenir {"status":"ok"}. Laissez le serveur local en fonctionnement jusqu’au nettoyage.
Tester une séquence contrôlée de lectures anciennes
Dans cette étape, vous allez tester le gestionnaire avec une séquence prévisible : ancienne, nouvelle, ancienne à nouveau, nouvelle, absente et invalide. Il s’agit d’un jeu de test, c’est-à-dire d’une entrée fournie volontairement pour rendre reproductible une situation normalement imprévisible. Ce résultat ne prouve pas qu’une véritable requête Cloudflare était obsolète.
Créez un petit test à l’aide de la bibliothèque d’assertions standard. Il importe le gestionnaire que vous avez écrit et lui fournit la même interface CONFIG.get() avec des valeurs de retour contrôlées :
cat > test-config.mjs <<'JS'
import assert from "node:assert/strict";
import worker from "./src/index.js";
const older = JSON.stringify({ version: 1, theme: "light", banner: "Welcome" });
const newer = JSON.stringify({ version: 2, theme: "dark", banner: "New help center" });
// A controlled fixture: these values simulate different reads, not a cloud outage.
const values = [older, newer, older, newer, null, "broken-json"];
const expectedVersions = [1, 2, 1, 2, 0, 0];
for (let i = 0; i < values.length; i += 1) {
const env = { CONFIG: { get: async () => values[i] } };
const response = await worker.fetch(new Request("https://example.test/settings"), env);
assert.equal(response.status, 200);
const body = await response.json();
assert.equal(body.version, expectedVersions[i]);
assert.ok(["light", "dark"].includes(body.theme));
assert.equal(typeof body.banner, "string");
}
console.log("Controlled old/new/missing/invalid reads stayed usable.");
JS
node test-config.mjs
Vous devez obtenir Controlled old/new/missing/invalid reads stayed usable. Une assertion échouée arrête la commande et affiche une erreur. La répétition de l’ancienne valeur est intentionnelle : n’ajoutez pas de variable globale au processus contenant la « dernière version » pour la masquer. Les Workers peuvent s’exécuter dans différentes instances ; une telle variable ne peut donc pas établir la dernière version à l’échelle du compte.
Une mise à jour de configuration doit permettre aux lecteurs d’anciennes valeurs valides de rester utilisables pendant la transition. Cette approche convient à une bannière ou à un thème. Elle ne rendrait pas KV adapté à la révocation immédiate de l’accès d’une personne. Le test réel dans le cloud vient ensuite ; il peut afficher la nouvelle valeur dès la première requête, ce qui constitue un résultat valide.
Déployer et établir la première version dans le cloud
Dans cette étape, vous allez établir une base distante réelle avant de la modifier. Seules la configuration actuelle et le jeu de test de repli mal formé doivent se trouver dans le namespace cloud de ce laboratoire.
npx wrangler kv key put config:current --path config-v1.json --binding CONFIG --remote
npx wrangler kv key put config:broken broken-json --binding CONFIG --remote
npx wrangler deploy
Confirmez le nom unique du Worker et la liaison CONFIG, puis copiez l’URL publique réelle :
WORKER_URL="https://YOUR_WORKER.YOUR_SUBDOMAIN.workers.dev"
curl -i "$WORKER_URL/settings"
Vous devez obtenir la version 1, le thème light, la bannière Welcome et source: "stored". Attendez si nécessaire que le nom d’hôte soit prêt et que KV soit visible ; une erreur réseau n’est pas une réponse de configuration. Exécutez le contrôle indépendant de cette étape avant de remplacer la version 1. Il vérifie le compte sélectionné, la valeur enregistrée, la liaison déployée, les valeurs par défaut et la réponse de santé.
Observer une véritable mise à jour sans exiger une lecture obsolète
Dans cette étape, vous allez mettre à jour la configuration enregistrée tout en laissant le code du Worker inchangé. Vérifiez la nouvelle valeur prévue, puis écrivez-la dans la même clé distante :
cat config-v2.json
npx wrangler kv key put config:current --path config-v2.json --binding CONFIG --remote
npx wrangler kv key get config:current --binding CONFIG --remote --text
La lecture de gestion doit contenir la version 2. Vérifiez maintenant ce que voit l’application :
curl -i "$WORKER_URL/settings"
Vous pouvez voir la version 2 immédiatement ou une version valide antérieure pendant la convergence des lectures. N’exigez pas une réponse obsolète pour « prouver » la cohérence éventuelle et ne réécrivez pas rapidement la clé pour en provoquer une. Si nécessaire, répétez la requête HTTP toutes les 15 secondes pendant cinq minutes au maximum. Il s’agit d’une fenêtre d’observation limitée pour l’exercice, et non d’une promesse que tous les emplacements mondiaux convergeront en cinq minutes.
Poursuivez lorsque le point de terminaison renvoie {"version":2,"theme":"dark","banner":"New help center","source":"stored"}. Si la convergence n’a pas lieu pendant cette fenêtre d’observation, vérifiez le compte et la liaison, puis signalez un résultat non concluant. Le contrôle indépendant exige que la version réellement enregistrée et la réponse réelle correspondent ; un fichier local ou un jeu de test ne suffit pas.
curl -i "$WORKER_URL/settings?key=config:broken"
curl -i "$WORKER_URL/health"
La configuration d’affichage endommagée utilise toujours une valeur par défaut contrôlée et l’état de santé reste ok. Dans le Dashboard, sélectionnez le même compte et ouvrez le namespace de ce laboratoire sous Storage & databases → Workers KV. Comparez config:current avec la version 2 de votre fichier. Cette vue en lecture seule affiche la valeur gérée ; elle ne peut pas prouver ce que chaque emplacement distant a actuellement mis en cache.
Le test contrôlé a vérifié la tolérance aux anciennes valeurs, tandis que cette mise à jour réelle a couvert le déploiement et la convergence observée sur votre point de terminaison de test. Gardez ces conclusions séparées. Consultez le fonctionnement de KV pour connaître son modèle de cohérence.
Sélectionnez KV Pairs, puis View à côté de config:current. Utilisez Refresh si la liste ne reflète pas encore la mise à jour. Cet exemple affiche la version 2, le thème dark et la bannière New help center ; le nom généré de votre espace de noms sera différent. Ne modifiez pas la valeur pendant cette vérification.
Supprimer les ressources cloud temporaires
Dans cette étape, vous allez supprimer les deux ressources tant que Wrangler est encore autorisé. Un namespace peut survivre à son Worker ; supprimer uniquement l’application ne nettoie donc pas ses données.
Arrêtez le processus de développement local lancé dans ce terminal :
kill "$DEV_PID"
Examinez les références de ressources enregistrées avant toute suppression :
cat wrangler.jsonc
Confirmez le nom du Worker labex-config-... et l’ID du namespace CONFIG. Supprimez le Worker sélectionné par cette configuration :
npx wrangler delete
Si une confirmation vous est demandée, vérifiez que le nom affiché correspond à ce laboratoire et confirmez avec y. Supprimez ensuite uniquement le namespace référencé par CONFIG :
npx wrangler kv namespace delete --binding CONFIG
Vérifiez le namespace dans toute invite de confirmation avant d’accepter. Conservez wrangler.jsonc intact afin que le contrôle indépendant puisse identifier les ressources qui doivent être absentes.
npx wrangler kv namespace list
Le namespace de ce laboratoire doit avoir disparu ; les namespaces sans rapport doivent rester présents. Actualisez les listes du Dashboard pour confirmer que le Worker et le namespace du laboratoire ont disparu. Une requête échouée ou une session de connexion expirée ne prouve pas la suppression. Exécutez le contrôle de cette étape avant de vous déconnecter afin qu’il puisse inspecter un inventaire autorisé.
Mettre fin à l’autorisation de la VM
Dans cette étape, vous allez déconnecter Wrangler une fois le contrôle du nettoyage réussi. La déconnexion met fin à l’autorisation Wrangler enregistrée sur cette VM ; elle ne supprime pas les ressources cloud et ne vous déconnecte pas de votre session habituelle du Dashboard dans le navigateur.
npx wrangler logout
npx wrangler whoami --json
Vérifiez que le résultat structuré indique "loggedIn": false. Cette commande non authentifiée peut se terminer avec un code de sortie différent de zéro, ce qui est attendu ici. Si elle ne renvoie qu’une erreur de connexion sans état d’authentification explicite, réessayez lorsque la connexion fonctionnera.
Les fichiers locaux restants et l’état KV local appartiennent à cette VM temporaire. Ils sont distincts des ressources cloud que vous avez déjà supprimées. Vous pouvez maintenant terminer le laboratoire.
Résumé
Vous avez créé un lecteur de configuration qui accepte des paramètres valides, anciens ou nouveaux, utilise des valeurs par défaut sûres lorsque les valeurs sont absentes ou invalides, et garde son point de terminaison de santé indépendant des données KV facultatives. Vous avez testé une séquence contrôlée de lectures anciennes, puis modifié une clé distante réelle et observé la convergence de la réponse déployée.
Vous avez appris que les étiquettes de version décrivent les données renvoyées, tandis que la durée de mise en cache des lectures, l’expiration et la cohérence forte sont des notions différentes. Enfin, vous avez supprimé les ressources temporaires et vous vous êtes déconnecté. Le défi du cours combinera une liaison correcte du namespace et une gestion sûre des notifications.
