> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbitlab.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Routage (orbitlab.json)

> Configurez les redirections, réécritures et en-têtes de votre application à la périphérie avec orbitlab.json.

Ajoutez un fichier `orbitlab.json` à votre dépôt pour contrôler la façon dont les requêtes vers votre application sont traitées—**redirections**, **réécritures**, **en-têtes personnalisés**, comportement des barres obliques finales et URLs propres. Ces règles s'exécutent à la périphérie (devant votre application), elles s'appliquent donc avant même qu'une requête n'atteigne votre conteneur.

Le fichier est analysé automatiquement à chaque déploiement. Il n'y a rien à activer.

## Emplacement du fichier

Placez `orbitlab.json` à la racine de votre projet. Dans un monorepo, mettez-le dans le même dossier que celui défini comme **Répertoire racine** (ex : `apps/web/orbitlab.json`).

Seules les clés de routage ci-dessous sont lues—toute autre clé est ignorée, vous pouvez donc conserver sans risque des paramètres non liés dans le même fichier.

## Un exemple minimal

```json theme={null}
{
  "redirects": [
    { "source": "/old-blog/:slug", "destination": "/blog/:slug", "permanent": true }
  ],
  "rewrites": [
    { "source": "/api/:path*", "destination": "https://api.example.com/:path*" }
  ],
  "headers": [
    {
      "source": "/(.*)",
      "headers": [
        { "key": "X-Frame-Options", "value": "DENY" },
        { "key": "Strict-Transport-Security", "value": "max-age=63072000" }
      ]
    }
  ],
  "trailingSlash": false,
  "cleanUrls": true
}
```

## Redirections

Envoyez les visiteurs d'un chemin vers un autre via une redirection HTTP.

```json theme={null}
{
  "redirects": [
    { "source": "/docs", "destination": "/documentation", "permanent": true },
    { "source": "/promo", "destination": "/sale", "statusCode": 302 }
  ]
}
```

| Champ             | Type    | Description                                                                        |
| ----------------- | ------- | ---------------------------------------------------------------------------------- |
| `source`          | string  | Motif de chemin à faire correspondre (voir [Motifs de source](#motifs-de-source)). |
| `destination`     | string  | Où envoyer la requête. Peut référencer les paramètres capturés.                    |
| `permanent`       | boolean | `true` → `308` (par défaut), `false` → `307`. Ignoré si `statusCode` est défini.   |
| `statusCode`      | number  | Code de redirection explicite (`300`–`399`). Prioritaire sur `permanent`.          |
| `has` / `missing` | array   | Conditions optionnelles (voir [Conditions](#conditions-has--missing)).             |

## Réécritures

Servez du contenu depuis un chemin différent ou une autre origine **sans changer l'URL** dans le navigateur.

```json theme={null}
{
  "rewrites": [
    { "source": "/blog/:path*", "destination": "/posts/:path*" },
    { "source": "/api/:path*", "destination": "https://api.example.com/:path*" }
  ]
}
```

* **Réécriture interne** — lorsque `destination` est un chemin absolu (ex : `/posts/:path*`), l'URL est réécrite et la requête continue vers votre application.
* **Réécriture par proxy** — lorsque `destination` est une URL complète (ex : `https://api.example.com/:path*`), la requête est relayée (proxy) vers cette origine. L'en-tête `Host` en amont est défini sur l'hôte de destination, et les origines HTTPS sont prises en charge.

| Champ             | Type   | Description                                                       |
| ----------------- | ------ | ----------------------------------------------------------------- |
| `source`          | string | Motif de chemin à faire correspondre.                             |
| `destination`     | string | Chemin absolu (interne) ou URL complète `http(s)://` (par proxy). |
| `has` / `missing` | array  | Conditions optionnelles.                                          |

## En-têtes

Attachez des en-têtes de réponse personnalisés aux requêtes correspondantes. Les règles d'en-tête **n'arrêtent pas** la requête—une fois les en-têtes définis, elle continue vers les réécritures et votre application.

```json theme={null}
{
  "headers": [
    {
      "source": "/assets/:path*",
      "headers": [{ "key": "Cache-Control", "value": "public, max-age=31536000, immutable" }]
    }
  ]
}
```

| Champ             | Type   | Description                                                      |
| ----------------- | ------ | ---------------------------------------------------------------- |
| `source`          | string | Motif de chemin à faire correspondre.                            |
| `headers`         | array  | Liste de paires d'en-têtes `{ "key": string, "value": string }`. |
| `has` / `missing` | array  | Conditions optionnelles.                                         |

## Barres obliques finales & URLs propres

```json theme={null}
{
  "trailingSlash": false,
  "cleanUrls": true
}
```

* **`trailingSlash`** — `false` supprime la barre oblique finale (`/about/` → `/about`) ; `true` l'impose (`/about` → `/about/`) pour les chemins sans extension de fichier. Les deux utilisent une redirection `308`. La racine `/` n'est jamais affectée.
* **`cleanUrls`** — redirige `/page.html` → `/page` avec un `308`.

## Motifs de source

Le champ `source` prend en charge une syntaxe de correspondance de chemin familière :

| Motif         | Correspond à                          | Exemple         |
| ------------- | ------------------------------------- | --------------- |
| `/exact/path` | Un chemin exact                       | `/pricing`      |
| `:param`      | Un seul segment de chemin             | `/user/:id`     |
| `:param*`     | Zéro ou plusieurs segments            | `/files/:path*` |
| `:param+`     | Un ou plusieurs segments              | `/files/:path+` |
| `:param?`     | Un segment optionnel                  | `/blog/:slug?`  |
| `*`           | Un joker (n'importe quels caractères) | `/legacy/*`     |
| `(regex)`     | Un groupe d'expression régulière brut | `/(.*)`         |

Les paramètres nommés peuvent être réutilisés dans `destination` en réécrivant le même jeton `:param`. Par exemple, `"/old/:slug"` → `"/new/:slug"` transporte le segment capturé.

## Conditions (has / missing)

Les redirections, réécritures et en-têtes acceptent des tableaux optionnels `has` et `missing` pour ne correspondre que lorsque certains attributs de la requête sont présents (`has`) ou absents (`missing`).

```json theme={null}
{
  "redirects": [
    {
      "source": "/dashboard",
      "destination": "/login",
      "missing": [{ "type": "cookie", "key": "session" }]
    }
  ]
}
```

Chaque objet de condition prend en charge :

| Champ   | Description                                                                        |
| ------- | ---------------------------------------------------------------------------------- |
| `type`  | Un de `header`, `query`, `cookie` ou `host`.                                       |
| `key`   | Le nom de l'en-tête/paramètre/cookie. Non requis pour `host`.                      |
| `value` | Valeur exacte optionnelle. Si omise, la règle correspond uniquement à la présence. |

### Règles par domaine (host)

Lorsque plusieurs domaines sont attachés à votre service, utilisez une condition `host` pour n'appliquer une règle qu'à l'un d'eux. Une même application peut ainsi servir un contenu différent selon le sous-domaine :

```json theme={null}
{
  "rewrites": [
    {
      "source": "/:path*",
      "destination": "/tools/:path*",
      "has": [{ "type": "host", "value": "tools.example.com" }]
    },
    {
      "source": "/:path*",
      "destination": "/landing/:path*",
      "has": [{ "type": "host", "value": "www.example.com" }]
    }
  ]
}
```

<Note>
  `orbitlab.json` gère le routage **au sein d'un seul service**. Les conditions `host` distinguent les domaines déjà attachés à *ce* service—elles ne peuvent pas envoyer le trafic vers un autre service. Pour pointer un domaine vers un service précis, attachez-le à ce service depuis le tableau de bord (voir [Domaines](/fr/domains)). Pour atteindre une origine externe, utilisez une réécriture dont la `destination` est une URL complète.
</Note>

## Ordre d'évaluation

Les règles sont appliquées à la périphérie dans cet ordre, puis la requête est transmise à votre application :

1. `cleanUrls`
2. `trailingSlash`
3. `redirects`
4. `headers`
5. `rewrites`
6. Votre application

Les redirections et les réécritures par proxy sont terminales (elles arrêtent le traitement). Les règles d'en-tête et les réécritures internes continuent la chaîne.

## Gérer les règles depuis le tableau de bord

Vous pouvez aussi gérer le routage depuis le tableau de bord/l'API. Lorsque les deux existent, **la configuration du tableau de bord est prioritaire sur le fichier** : les listes de règles sont combinées avec les règles du tableau de bord en premier, et les indicateurs (`trailingSlash`, `cleanUrls`) utilisent la valeur du tableau de bord si elle est définie. Supprimer `orbitlab.json` de votre dépôt efface les règles basées sur le fichier au prochain déploiement, tandis que les règles du tableau de bord restent en place.

## Limites

Pour garder le routage à la périphérie rapide, les limites suivantes s'appliquent :

| Paramètre                              | Limite          |
| -------------------------------------- | --------------- |
| Redirections                           | 256             |
| Réécritures                            | 128             |
| Règles d'en-tête                       | 128             |
| En-têtes par règle                     | 32              |
| Conditions `has` / `missing` par règle | 16 chacune      |
| Longueur du motif                      | 4096 caractères |

Si `orbitlab.json` est invalide, le déploiement continue et les règles de routage précédentes sont conservées—consultez vos journaux de build pour un avertissement de validation.