URLs, routes et noms d'hôte
Comment un domaine, une URL et ses routes se combinent pour donner le nom d'hôte de chaque environnement, et comment le trafic atteint vos services.
L'exposition d'une application repose sur trois objets déclarés dans l'architecture — le domaine, l'URL et la route — et sur un réglage de l'environnement, le préfixe. Leur combinaison donne un nom d'hôte différent dans chaque environnement, sans que vous ayez à déclarer l'URL plusieurs fois.
Définition
| Objet | Ce que c'est | Où il se déclare |
|---|---|---|
| Domaine | Un nom de domaine que l'app peut utiliser. Un domaine plateforme est fourni par Wakastart et partagé par toutes les apps. Un domaine personnalisé vous appartient et n'est visible que de votre app. | Architecture > URLs > Domaines |
| URL | Un sous-domaine posé sur un domaine, par exemple app sur exemple.fr. Une URL peut porter plusieurs routes. | Architecture > URLs |
| Route | Une règle qui envoie un chemin (/, /api…) d'une URL vers un service de l'app. | Carte de l'URL, Ajouter une route |
| Préfixe d'environnement | Un segment inséré dans tous les noms d'hôte d'un environnement, par exemple staging. | Onglet URLs & IAM de l'environnement |
| Domaine racine | L'exposition d'un domaine personnalisé sans sous-domaine (exemple.fr). | Architecture > URLs > Exposer sur le domaine racine |
Une URL ou une route déclarée n'est encore qu'une intention. Elle ne produit ni DNS ni certificat tant qu'elle n'est pas instanciée dans un environnement. C'est le principe définition et instance appliqué au réseau.
Pourquoi ça existe
Une même application tourne en dev, en staging et en prod. Si chaque environnement avait ses propres URLs à déclarer, elles finiraient par diverger : une route ajoutée en staging et oubliée en prod. En déclarant les URLs une seule fois dans l'architecture, puis en les instanciant par environnement, vous garantissez que tous les environnements exposent la même chose, chacun sous son propre nom d'hôte.
Comment se compose le nom d'hôte
La plateforme calcule le nom d'hôte complet (FQDN) d'une URL dans un environnement avec cette règle :
<sous-domaine> . <préfixe de l'environnement, s'il existe> . <identifiant court de l'app, sur un domaine plateforme> . <domaine>| URL déclarée | Environnement | Préfixe | Nom d'hôte obtenu |
|---|---|---|---|
app sur exemple.fr (personnalisé) | prod | aucun | app.exemple.fr |
app sur exemple.fr (personnalisé) | staging | staging | app.staging.exemple.fr |
app sur un domaine plateforme <domaine-plateforme>, app monapp | dev | dev | app.dev.monapp.<domaine-plateforme> |
Domaine racine de exemple.fr | staging | staging | staging.exemple.fr |
L'identifiant court de l'app n'est ajouté que sur un domaine plateforme : c'est lui qui évite que deux apps se disputent le même nom. Sur votre propre domaine, vous êtes seul maître des noms.
La carte de chaque URL affiche le résultat dans Aperçu FQDN par environnement, avant toute mise en ligne.
Comment le trafic atteint vos services
Quand une route est en ligne, la requête suit ce chemin :
- Le DNS du nom d'hôte pointe vers la gateway de l'environnement.
- La gateway termine le TLS avec le certificat du nom d'hôte. Une requête en
http://reçoit une redirection permanente (301) vershttps://. - La gateway compare le chemin de la requête aux routes de l'URL et transmet la requête au service ciblé, sur le port déclaré dans la définition du service.
Le chemin est transmis tel quel : une requête vers https://app.exemple.fr/api/commandes arrive au service api avec le chemin /api/commandes. Votre service doit donc répondre sous le préfixe de sa route.
Trois types de correspondance sont proposés :
| Type de chemin | Correspond à | Exemple pour /api |
|---|---|---|
PathPrefix (par défaut) | le chemin et tout ce qui commence par lui, segment par segment | /api, /api/commandes ; pas /apis |
Exact | ce chemin seulement | /api |
RegularExpression | les chemins qui satisfont l'expression | /api/v[0-9]+/.* |
Quand plusieurs routes d'une même URL correspondent, la plus précise l'emporte : une correspondance exacte passe avant un préfixe, et un préfixe long avant un préfixe court. La route / sert donc de route par défaut.
L'URL front officielle
Une seule route de l'app peut être marquée URL front officielle de l'app. Elle doit cibler un service de rôle FRONT. Ce repère désigne l'adresse d'entrée de votre front ; le choisir ne change ni le DNS ni le routage.
Exemples
- Une app front + API sur un seul nom : URL
appsurexemple.fr, route/vers le front, route/apivers l'API. En staging, tout est servi sousapp.staging.exemple.fr. - Une API publique séparée : URL
apisurexemple.fr, route/vers l'API. Le front appellehttps://api.exemple.fr, ou mieux, lit l'URL dans sa variableROUTE_API_URL(voir Variables et secrets). - Un environnement de démonstration sans domaine à vous : URL
appsur un domaine plateforme, préfixedemo.