Configuration des redirections et réécritures

Orbit has a built-in redirect and rewrite engine that runs before your project is asked for anything, configured either in KPanel or as a file in your repository. This guide covers both, the pattern…

Orbit dispose d'un moteur de redirection et de réécriture intégré qui s'exécute avant que votre projet soit sollicité, configuré soit dans KPanel soit sous forme de fichier dans votre référentiel. Ce guide couvre les deux approches, la syntaxe des modèles et ses captures, l'ordre des règles, les limites et le comportement qui surprend les utilisateurs.

Où configurer les règles

Il y a deux endroits, et ils sont évalués dans un ordre fixe.

Dans KPanel. Ouvrez votre projet dans Orbit, allez dans Settings et faites défiler jusqu'à la section redirects and rewrites pour l'environnement. Chaque environnement dispose de son propre ensemble de règles indépendant, la production et la staging étant configurées séparément.
Dans votre référentiel, en tant que fichier kaps.json. Ceci est couvert plus loin.

Les règles du panel sont évaluées en premier. Si aucune d'elles ne correspond, les règles kaps.json sont essayées.

Section Redirects and rewrites dans les paramètres du projet Orbit

Ajouter une règle dans KPanel

Cliquez sur Add rule.
Remplissez la source, le modèle de chemin à comparer avec les requêtes entrantes. L'espace réservé montre les deux formes qu'il attend : /old-path or /blog/:slug.
Remplissez la destination. L'espace réservé montre /new-path or https://..., donc un chemin local et une URL externe complète sont tous deux valides.
Choisissez le type de règle :
- 301 Permanent : l'URL a déménagé définitivement. Les navigateurs et les moteurs de recherche mettent cela en cache.
- 302 Temporary : déplacé pour l'instant, non mis en cache. À utiliser pour les campagnes et les expériences.
- Rewrite : servir le chemin de destination sans changer l'URL dans la barre d'adresse du navigateur.
Cliquez sur Save rules.

Les règles prennent effet au prochain déploiement, pas immédiatement. Enregistrer une règle ne change pas ce que le déploiement actuellement actif sert. Redéployez après avoir enregistré, sinon vos règles sembleront ne pas fonctionner.

Un 301 est mis en cache par les navigateurs, parfois très longtemps, et il n'y a rien que vous puissiez faire du serveur pour le nettoyer. Si vous n'êtes pas certain qu'un déménagement est permanent, utilisez d'abord un 302 et passez-le à 301 une fois que vous êtes sûr. Se tromper sur un chemin à fort trafic est vraiment difficile à corriger.

Modèles de chemin source

Modèle	Correspond à	Captures
`/old-page`	Exactement `/old-page`	Rien
`/blog/*`	Tout ce qui commence par `/blog/`	Le reste du chemin, référencé comme `*` dans la destination
`/posts/:id`	`/posts/` plus un segment de chemin	Ce segment, comme `:id`
`/files/:rest*`	`/files/` plus tout ce qui suit, barres obliques incluses	Le reste entier, comme `:rest`

La différence entre :id et :rest* est la plus importante. Un paramètre nommé correspond à un seul segment et s'arrête à la barre oblique suivante. Un splat correspond à tout ce qui reste, y compris les barres obliques.

Utiliser les captures dans la destination

Référencez un paramètre nommé par nom, et un caractère générique seul comme * :

Source	Destination	Résultat
`/blog/:slug`	`/articles/:slug`	`/blog/hello-world` devient `/articles/hello-world`
`/docs/:rest*`	`/help/:rest*`	`/docs/a/b/c` devient `/help/a/b/c`
`/old/*`	`/new/*`	`/old/a/b` devient `/new/a/b`

Ordre des règles

Les règles sont testées de haut en bas de la liste et le premier match gagne. Une fois qu'une règle correspond, aucune règle ultérieure n'est considérée. Le panel l'indique sous la liste : « Les règles sont testées dans l'ordre. Le premier match gagne. »

Mettez les règles spécifiques au-dessus des règles générales. Une règle /blog/* placée au-dessus de /blog/2023/:slug avalera chaque requête que la règle plus spécifique était censée traiter, et il semblera que la règle spécifique est simplement cassée.

Si aucune règle ne correspond, la requête est servie normalement.

Cas d'usage courants

Renommer une page

Vous avez renommé /about-us en /about et voulez que les anciens liens continuent à fonctionner.

Source : /about-us
Destination : /about
Type : 301 Permanent

Déplacer une section entière

Votre blog a déménagé de /news/:slug à /blog/:slug.

Source : /news/:slug
Destination : /blog/:slug
Type : 301 Permanent

Proxifier silencieusement un chemin API

Vous voulez que /api/v1/* soit servi à partir d'un chemin interne différent sans exposer le changement.

Source : /api/v1/:path*
Destination : /api/internal/:path*
Type : Rewrite

Une page d'attente temporaire

Source : /checkout
Destination : /maintenance
Type : 302 Temporary

Diriger le trafic vers un autre domaine

La destination peut être une URL absolue, donc une règle peut pointer vers un site complètement différent.

Source : /shop/:rest*
Destination : https://shop.example.com/:rest*
Type : 301 Permanent

Configuration en tant que code avec `kaps.json`

Les règles peuvent vivre dans votre référentiel au lieu du panel. Ajoutez un fichier kaps.json et assurez-vous que votre build le copie dans votre répertoire de sortie, car Orbit le lit à partir de la racine de l'artefact construit plutôt que de la racine du référentiel.

{
  "redirects": [
    { "source": "/about-us", "destination": "/about", "permanent": true },
    { "source": "/news/:slug", "destination": "/blog/:slug", "permanent": true },
    { "source": "/promo", "destination": "/spring-sale", "permanent": false }
  ],
  "rewrites": [
    { "source": "/api/v1/:path*", "destination": "/api/internal/:path*" }
  ],
  "headers": [
    {
      "source": "/*",
      "headers": [
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "X-Content-Type-Options", "value": "nosniff" }
      ]
    }
  ]
}

permanent: true produit un 301 et permanent: false un 302. L'omettre donne un 301.

kaps.json s'applique aux déploiements statiques uniquement. Si Server mode est activé, votre app gère son propre routage et le fichier est ignoré. Il est aussi évalué seulement après que les règles du panel de l'environnement n'aient pas correspondu, donc une règle du panel bat toujours une règle de fichier pour le même chemin.

Utilisez kaps.json quand les règles appartiennent au code, afin qu'elles soient examinées dans une pull request et bougent avec un rollback. Utilisez le panel quand vous avez besoin qu'une règle soit active maintenant sans déploiement. Ne maintenez pas la même règle aux deux endroits : la règle du panel gagnera toujours et la règle du fichier semblera être ignorée, ce qu'elle est.

Limites

Jusqu'à 100 règles de redirection et de réécriture par environnement, et 100 dans un kaps.json.
Jusqu'à 200 règles d'en-têtes personnalisés par environnement.

Les règles au-delà de la limite sont supprimées silencieusement plutôt que de lever une erreur, alors restez bien en dessous.

En-têtes de réponse personnalisés

Parallèlement aux redirections, chaque environnement dispose d'une section d'en-têtes de réponse dans Settings pour injecter des en-têtes HTTP sur les chemins correspondants. Il utilise la même syntaxe de modèle de chemin, et il y a des présets d'ajout rapide pour HSTS, CSP, no-embed, no-sniff, referrer policy et CORS.

Contrairement aux redirections, toutes les règles d'en-têtes correspondantes sont appliquées, pas seulement la première, et une règle ultérieure remplace une règle antérieure quand elles définissent le même en-tête. Content-Length, Transfer-Encoding et Connection sont bloqués, car les définir corromprait la réponse.

Comportement à connaître avant d'en dépendre

Les chaînes de requête ne sont pas transportées à travers une redirection. Une règle correspond que la requête ait ou non une chaîne de requête, mais la destination est construite à partir de votre modèle et des segments de chemin capturés uniquement. Une requête à /old?utm_source=email redirige vers /new, avec les paramètres supprimés. Si vous dépendez des paramètres de suivi qui survivent, gérez la redirection dans une fonction edge à la place, où vous contrôlez complètement l'URL de destination.

Les règles ne correspondent qu'au chemin. Les fragments (#section) ne parviennent jamais au serveur ; le navigateur les rajoute après une redirection.
Une réécriture vers un chemin qui n'existe pas produit un 404, plutôt que de tomber silencieusement au chemin original. Les cibles de réécriture doivent exister dans votre sortie de build.
Les règles s'exécutent avant que votre projet soit sollicité, donc elles s'appliquent aux fichiers statiques et aux requêtes en mode serveur.
Chaque environnement est indépendant. Les règles sur production ne s'appliquent pas à staging ou aux previews. Copiez-les délibérément.

Supprimer une règle

Cliquez sur l'icône de corbeille sur la ligne de règle, puis cliquez sur Save rules pour appliquer le changement. Comme pour en ajouter une, le changement prend effet au prochain déploiement.

Quand utiliser une fonction edge à la place

Le moteur de redirection gère les règles chemin-vers-chemin. Recourez à une fonction edge quand vous avez besoin de logique que le moteur de règles ne peut pas exprimer : branchement sur un en-tête ou un cookie, préservation ou réécriture de paramètres de requête, routage A/B pondéré, ou tout ce qui est conditionnel.