Que deviennent les URL localhost dans l’aperçu d’un exercice de code

Le frontend d’un projet appelle souvent son API sur http://localhost:4000, depuis un fichier d’env comme NEXT_PUBLIC_API_URL ou en dur dans le code. Dans un aperçu Kendor, la page s’exécute dans le navigateur de la personne qui regarde, où localhost désigne son propre ordinateur, pas le bac à sable. Kendor redirige ces appels vers le bon port du bac à sable : la plupart des projets fonctionnent donc sans modification. Cet article explique ce qui est redirigé, ce qui ne l’est pas, et la manière explicite de construire les URL quand vous préférez ne pas vous en remettre à cette redirection.

Ce que Kendor redirige

Toute URL dont l’hôte est localhost, 127.0.0.1, 0.0.0.0 ou [::1], sur n’importe quel port, émise depuis la page d’aperçu ou ses web workers :

• les requêtes avec fetch et XMLHttpRequest (donc axios et la plupart des autres bibliothèques HTTP)
• les WebSockets, y compris socket.io et le rechargement à chaud, ainsi que les événements envoyés par le serveur (EventSource)
• les images, scripts, feuilles de style, vidéos, iframes, liens et formulaires, qu’ils soient dans le HTML servi, définis depuis JavaScript ou insérés sous forme de balisage
• les redirections de votre serveur vers http://localhost:…

Peu importe d’où vient l’URL : une variable d’env intégrée au bundle, une chaîne écrite en dur, ou une URL construite à l’exécution.

Où va une URL redirigée

• Si le routing de l’exercice envoie ce chemin vers ce port, l’URL va vers l’adresse d’aperçu elle-même. Par exemple, http://localhost:4000/api/users va vers https://<preview-address>/api/users quand /api est routé vers le service du port 4000. Le frontend et l’API partagent alors une seule adresse : il n’y a plus aucun CORS.
• Sinon, elle va vers l’adresse propre de ce port, https://4000-<preview-address>/api/users, la même adresse que la vue Processus ouvre pour ce port.

La première fois qu’un port est redirigé, la console du navigateur l’indique :

[kendor] localhost:4000 is the sandbox's port 4000 here, reached at https://4000-<preview-address>.

CORS, redirections et cookies

Un appel depuis l’aperçu vers l’adresse d’un autre port est inter-origine ; Kendor lui donne donc l’apparence qu’il avait sur votre machine :

• CORS. Votre API reçoit Origin: http://localhost:3000 (le port d’où provient la page), de sorte qu’une liste d’origines autorisées écrite pour le développement local passe. Sa réponse est ramenée à l’adresse d’aperçu. Seuls les appels issus de l’aperçu propre à l’exercice bénéficient de ce traitement ; les requêtes de tout autre site sont laissées telles quelles.
• Redirections. Un en-tête Location: http://localhost:3000/dashboard est réécrit vers l’adresse d’aperçu.
• Cookies. L’aperçu s’affiche dans l’éditeur, sur un autre site, où les navigateurs suppriment les cookies ordinaires. Kendor marque les cookies de votre application comme partitionnés (SameSite=None; Secure; Partitioned), de sorte qu’une connexion par cookie y fonctionne aussi. Un cookie avec Domain=localhost voit ce domaine retiré.

Le code côté serveur n’a besoin de rien de tout cela. Dans le bac à sable, localhost atteint déjà le bon processus : un composant serveur Next.js ou une API qui appelle un autre service sur http://localhost:4000 fonctionne comme sur votre machine.

Ce qui n’est pas redirigé

• Un url() CSS pointant vers localhost, comme background: url(http://localhost:4000/bg.png).
• Les workers créés à partir d’une URL blob ou data, plutôt qu’à partir d’un fichier de script.
• Une navigation de page définie dans le code, comme location.href = 'http://localhost:3000/login', sous Firefox. Chrome, Edge et Safari sont couverts.
• Les URL de rappel OAuth enregistrées auprès d’un fournisseur comme Google ou GitHub avec localhost. Mettez-les à jour chez le fournisseur, ou connectez-vous autrement avec un compte de test.
• Un serveur qui écoute uniquement sur 127.0.0.1. L’aperçu ne peut pas l’atteindre du tout. Faites-le écouter sur $HOST (0.0.0.0) à la place.

Quand la page charge quand même quelque chose depuis localhost, la console du navigateur indique l’URL concernée :

[kendor] This page loaded http://localhost:4000/bg.png (css). That address is the viewer's own
computer, not the sandbox, and Kendor couldn't redirect this one.

Chrome peut aussi demander à la personne l’autorisation d’accéder à son réseau local. Les deux signifient la même chose : modifiez cette URL comme décrit ci-dessous.

La méthode explicite

Plutôt que de vous fier à la redirection, vous pouvez donner vous-même la bonne adresse au navigateur. Les deux méthodes fonctionnent dans le bac à sable comme sur votre machine.

• Un chemin relatif. Avec un routing qui envoie /api vers votre API, appelez fetch('/api/users'). Le frontend et l’API partagent l’adresse d’aperçu. Voir les applications à plusieurs services.
• Une référence dans dev.env.vars. Définissez la variable d’API de votre frontend sur l’URL publique de l’API :

services:
  web:
    dev:
      command: npm run dev -- --port $PORT
      port: 5173
      env:
        vars:
          VITE_API_URL: routing.api.url

routing.api.url se résout en l’adresse d’aperçu suivie de la route de l’API, avant le démarrage de tout service.

Chaque commande dev reçoit aussi KENDOR_PUBLIC_HOST, le nom d’hôte de l’aperçu, pour le code qui construit lui-même ses URL. L’adresse propre d’un port est cet hôte précédé de <port>-.

La désactiver

Si votre application gère ses propres URL et que vous voulez que ses pages soient servies exactement telles qu’écrites, envoyez l’en-tête x-kendor-no-rewrite sur ses réponses HTML. Kendor laisse alors ces pages intactes.