Référence de configuration

Chaque clé de flexway.yaml, chaque type de politique, chaque extension du contrat et l'option gRPC de Flexway v1.7.1, lus dans le schéma JSON que la version publie : type, valeurs admises, défaut, bornes, version d'arrivée, rechargement.

Valider dans l'éditeur

Une ligne en tête de flexway.yaml suffit aux éditeurs qui utilisent yaml-language-server : ils complètent les clés, affichent leur description et soulignent une faute à l'écriture - clé inconnue, valeur hors liste, durée mal écrite - plutôt qu'au démarrage.

# yaml-language-server: $schema=https://flexway.io/schema/v1/flexway.schema.json
version: 1

Les schémas de la version publiée (JSON Schema 2020-12), servis à leur identifiant :

Le schéma décrit ; flexway validate décide. Ce qui croise plusieurs fichiers - un amont pour chaque opération du contrat, une politique nommée qui n'existe pas - n'est vérifié que par flexway validate et au démarrage : gardez-le dans la CI.

390 clés

flexway.yaml

Le fichier de configuration de la passerelle : il dit comment servir, jamais quoi. Il ne liste aucune opération - il référence les contrats et décrit les amonts, hôtes, identités et politiques. Décodage strict : une clé inconnue est refusée, et tous les problèmes sont rapportés d'un coup.

`agents`

Ce que les agents atteignent : la surface MCP, les bornes des chaînes de délégation et la gouvernance A2A. Aucun outil n'est listé ici : une opération devient un outil dans le contrat (x-flexway-tool).

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`agents.a2a`

La part du déploiement dans la gouvernance A2A : ce que les cartes d'agents déclarées (contracts.a2a) ne disent pas.

Type: object
Depuis: 1.2.0
Rechargement: à chaud

`agents.a2a.push`

Garde des cibles de notification push qu'un appelant confie à un agent amont. Absente ou vide : toute configuration de notification push est refusée - fermé par défaut.

Type: object
Depuis: 1.2.0
Rechargement: à chaud

`agents.a2a.push.allowed_hosts`

Noms d'hôtes qu'une notification push peut viser : nom exact ou *.domaine pour ses sous-domaines, chacun avec un :port facultatif, en minuscules. Jamais une adresse IP, ni * seul, ni localhost ; une entrée en double est refusée.

Type: list<string>
Depuis: 1.2.0
Rechargement: à chaud

`agents.delegation`

Borne les chaînes d'agents agissant pour une personne (claim act de la RFC 8693) et permet à une révocation de les rompre. Absent : un jeton délégué est accepté comme un autre. Présent, chaque émetteur de auth.issuers doit déclarer client, pour l'introspection.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`agents.delegation.introspection`

Comment une révocation est vue : les jetons délégués sont introspectés auprès de leur émetteur (RFC 7662).

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`agents.delegation.introspection.cache`

Durée de réutilisation d'une réponse d'introspection - le plus long délai pendant lequel une chaîne révoquée fonctionne encore. Durée (10s) ; défaut 10s.

Type: string
Défaut: 10s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 0.1.0
Rechargement: à chaud

`agents.delegation.max_age`

Âge maximal d'une chaîne, compté depuis l'authentification de la personne (auth_time, sinon iat). Durée (15m) ; défaut 15m. Un contrat peut le resserrer par opération, jamais l'élargir.

Type: string
Défaut: 15m
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 0.1.0
Rechargement: à chaud

`agents.delegation.max_depth`

Nombre d'agents qu'une chaîne peut contenir. Entier positif ou nul ; 0 n'accepte aucun jeton délégué ; défaut 2. Un contrat peut le resserrer par opération, jamais l'élargir.

Type: integer
Défaut: 2
Bornes: valeur ≥ 0
Depuis: 0.1.0
Rechargement: à chaud

`agents.mcp`

Surface Model Context Protocol : où elle est servie et pour quelle ressource. Les opérations marquées x-flexway-tool y sont offertes en outils sous la même décision que REST ; le jeton reçu n'est jamais relayé à l'amont.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`agents.mcp.clients`

Quand il est renseigné, seuls clients OAuth admis sur la surface, nommés par l'URL de leur document de métadonnées client : URL https exacte, ou préfixe se terminant par /*. Absent : tout client.

Type: list<string>
Depuis: 1.0.0
Rechargement: à chaud

`agents.mcp.path`

Chemin où la surface MCP répond, sur chaque hôte de resources. Chemin littéral commençant par /, sans {, } ni * ; défaut /mcp.

Type: string
Défaut: /mcp
Depuis: 0.1.0
Rechargement: à chaud

`agents.mcp.resources`

Associe chaque hôte qui sert la surface à son URL publique - l'audience qu'un jeton doit porter pour y être accepté (RFC 8707). URL absolue https (http pour localhost seulement), sans requête ni fragment, terminée par path. Obligatoire et non vide ; déclarée, jamais déduite de la requête.

Type: map<string>
Depuis: 0.1.0
Rechargement: à chaud

`agents.mcp.servers`

Serveurs MCP existants dont les outils sont servis aussi par la surface (fédération), sous leurs noms d'origine, avec l'autorisation, le quota et les métriques de la passerelle. La clé nomme le serveur.

Type: map<object>
Depuis: 0.1.0
Rechargement: à chaud

`agents.mcp.servers.*.discovery`

Comment les outils du serveur sont listés. La découverte tourne en arrière-plan et ne bloque jamais le démarrage.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`agents.mcp.servers.*.discovery.issuer`

Nom d'un émetteur de auth.issuers, doté d'un client, dont la passerelle obtient un jeton client_credentials pour lister les outils - pour un serveur qui exige un jeton même pour cela. Absent : listés anonymement.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`agents.mcp.servers.*.discovery.refresh`

Fréquence à laquelle les outils sont listés à nouveau. Durée (5m) ; défaut 5m.

Type: string
Défaut: 5m
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 0.1.0
Rechargement: à chaud

`agents.mcp.servers.*.hosts`

Surfaces MCP (hôtes de agents.mcp.resources) qui servent ce serveur. Vide : toutes les surfaces.

Type: list<string>
Depuis: 0.1.0
Rechargement: à chaud

`agents.mcp.servers.*.rate_classes`

Classe de débit d'un outil, par nom d'origine (outil servi). Sinon read quand le serveur annonce l'outil en lecture seule, write autrement.

Type: map<string>
Depuis: 0.1.0
Rechargement: à chaud

`agents.mcp.servers.*.rename`

Donne à un outil un autre nom sur la surface, par nom d'origine - contre une collision par exemple. L'outil doit figurer dans tools.

Type: map<string>
Depuis: 0.1.0
Rechargement: à chaud

`agents.mcp.servers.*.scopes`

Portées exigées pour chaque outil du serveur. Vide : un appelant authentifié suffit.

Type: list<string>
Depuis: 0.1.0
Rechargement: à chaud

`agents.mcp.servers.*.tool_scopes`

Remplace scopes pour un outil, par nom d'origine ; l'outil doit figurer dans tools.

Type: map<list<string>>
Depuis: 0.1.0
Rechargement: à chaud

`agents.mcp.servers.*.tools`obligatoire

Outils servis : une liste de noms déclarée - le choix fermé par défaut - ou "*" pour tout ce que le serveur annonce, choisi explicitement. Obligatoire.

Type: "*" | list<string>
Valeurs admises: *
Depuis: 0.1.0
Rechargement: à chaud

`agents.mcp.servers.*.upstream`obligatoire

Nom d'un amont de upstreams de protocol: mcp : où est le serveur, avec le pool, les budgets, le coupe-circuit, le cloisonnement et l'échange de jeton qui vont avec. Obligatoire.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`ai`

Surface d'inférence /v1/* (compatible OpenAI) servie par le plan de données, routée par politique vers des backends, sous des budgets de tokens et d'euros par tenant. Absente : non servie. Aucun contrat à écrire : ses opérations sont intégrées.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`ai.backends`

Backends d'inférence, par nom. Au moins un. Un backend se déclare par genre (kind), capacités, authentification et mesure ; aucun fournisseur n'est nommé : un fournisseur est une URL, une authentification et un prix.

Type: map<object>
Depuis: 0.1.0
Rechargement: à chaud

`ai.backends.*.api_key`secret

Clé du backend, envoyée en jeton Bearer - une référence (${VAR} ou file:/chemin), lue à chaque usage. Vide pour un backend interne sans clé. Exclusive de auth (équivaut à auth: { scheme: bearer, key: ... }).

Type: string
Motif: ^(\$\{[A-Za-z_][A-Za-z0-9_]*\}|file:/\S+)$
Secret: une référence, ${VAR} ou file:/chemin, jamais une valeur en clair
Depuis: 0.1.0
Rechargement: à chaud

`ai.backends.*.auth`

Comment la passerelle s'authentifie auprès du backend, un seul schéma. Absent : api_key en jeton Bearer, sinon aucune.

Type: object
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.auth.key`secret

Clé envoyée, par référence (${VAR} ou file:/chemin), relue à chaque appel : schémas bearer et header. Jamais une clé en clair.

Type: string
Motif: ^(\$\{[A-Za-z_][A-Za-z0-9_]*\}|file:/\S+)$
Secret: une référence, ${VAR} ou file:/chemin, jamais une valeur en clair
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.auth.path`

Fichier d'où un jeton de courte durée est lu à chaque appel, tel qu'une identité de charge de travail le projette ; envoyé en jeton Bearer. Schéma token_file seulement, et alors obligatoire.

Type: string
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.auth.scheme`obligatoire

Schéma d'authentification : none (rien), bearer (Authorization: Bearer <key>), header (la clé dans l'en-tête header), token_file (un jeton lu dans path). Obligatoire dans auth.

Type: string
Valeurs admises: nonebearerheadertoken_file
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.capabilities`

Ce que sert le backend : chat, vision (sert aussi le texte), embeddings, model (modèle spécialisé d'un backend grpc seulement). Sans doublon. Vide : chat, ou model pour un backend grpc.

Type: list<string>
Valeurs admises: chatvisionembeddingsmodel
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.default_model`

Modèle servi quand l'appelant n'en demande pas un de models. Obligatoire, sauf pour un relay (la passerelle relayée choisit) et un grpc.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`ai.backends.*.external`

Marque un tiers : une requête sensible n'y va jamais. Booléen ; non renseigné : false, sauf pour un relay, externe tant que l'exploitant ne déclare pas external: false.

Type: boolean
Depuis: 0.1.0
Rechargement: à chaud

`ai.backends.*.fallback`

Backends essayés tour à tour quand celui-ci échoue avant de répondre (connexion, 5xx, délai, coupe-circuit ouvert), chacun une fois ; jamais sur un 4xx, ni après le premier octet d'un flux, ni vers un externe pour une requête sensible. Noms de ai.backends, sans lui-même, sans doublon, jamais un grpc.

Type: list<string>
Depuis: 0.1.0
Rechargement: à chaud

`ai.backends.*.identity_headers`

Noms d'en-têtes sous lesquels un backend relay reçoit le tenant, l'agent et la sensibilité de l'appel - ceux que l'autre passerelle déclare dans auth.trusted_headers et ai.sensitive_header. Réservé au genre relay, où tenant est obligatoire.

Type: object
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.identity_headers.agent`

Nom de l'en-tête qui porte l'agent appelant vers le relais. Facultatif.

Type: string
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.identity_headers.sensitive`

Nom de l'en-tête qui porte la sensibilité de l'appel vers le relais. Facultatif.

Type: string
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.identity_headers.tenant`

Nom de l'en-tête qui porte le tenant réel de l'appel vers le relais. Obligatoire pour un relay : la passerelle relayée doit voir le vrai tenant, pas un seul appelant.

Type: string
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.kind`

Genre du backend : openai (toute API compatible OpenAI, défaut), relay (une autre Flexway, parlée en OpenAI avec l'identité de l'appel sous des en-têtes déclarés), grpc (modèle spécialisé servi par une méthode d'un contrat gRPC, jamais une cible de /v1/*).

Type: string
Valeurs admises: openairelaygrpc
Défaut: openai
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.metering`

Qui compte le coût : local (défaut, cette passerelle compte et plafonne) ou upstream (la passerelle relayée compte ; celle-ci applique toujours son propre plafond local). upstream est refusé sur un backend openai.

Type: string
Valeurs admises: localupstream
Défaut: local
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.models`

Modèles qu'un appelant peut demander par leur nom ; tout autre est servi par default_model. Aucune entrée vide.

Type: list<string>
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.price`

Prix d'un million de tokens, en euros, entrée et sortie à part ; 0 est un prix. Obligatoire dès qu'un budget est compté en euros (sauf backend grpc ou mesuré en amont).

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`ai.backends.*.price.input_per_mtok`

Prix en euros d'un million de tokens d'entrée. Nombre positif ou nul.

Type: number
Bornes: valeur ≥ 0
Depuis: 0.1.0
Rechargement: à chaud

`ai.backends.*.price.output_per_mtok`

Prix en euros d'un million de tokens de sortie. Nombre positif ou nul.

Type: number
Bornes: valeur ≥ 0
Depuis: 0.1.0
Rechargement: à chaud

`ai.backends.*.tls`

TLS client vers le backend - le TLS mutuel d'un relais -, comme celui d'un amont. Ignoré tant que l'URL n'est pas https://.

Type: object
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.tls.ca_file`

Fichier PEM des autorités qui vérifient le certificat du backend. Absent : les autorités du système.

Type: string
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.tls.cert_file`

Certificat client PEM présenté au backend ; va avec key_file.

Type: string
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.tls.key_file`

Clé privée PEM du certificat client ; va avec cert_file.

Type: string
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.tls.server_name`

Nom attendu dans le certificat du backend (SNI), quand il diffère de l'hôte de l'URL.

Type: string
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.upstream`

Pour un backend grpc seulement, et alors obligatoire : nom d'un amont de protocol: grpc qui sert ses méthodes. Un tel backend ne porte ni url, ni modèle, ni authentification, ni prix : ceux de ses méthodes (x-flexway-ai).

Type: string
Depuis: 1.5.0
Rechargement: à chaud

`ai.backends.*.url`

Adresse du backend : URL absolue http ou https (par exemple https://api.provider.example/v1). Obligatoire, sauf pour un backend grpc.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`ai.budget`

Budget d'inférence par tenant, compté dans un cache partagé compatible Redis (Redis, Dragonfly ou Valkey), commun à toutes les répliques.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`ai.budget.daily_tokens`

Tokens par tenant et par jour UTC. Entier positif ou nul ; 0 : aucun budget journalier.

Type: integer
Depuis: 0.1.0
Rechargement: à chaud

`ai.budget.monthly_eur`

Budget par tenant en euros sur le mois civil, au prix déclaré de chaque backend. Nombre positif ou nul ; 0 : aucun. Exige price sur les backends.

Type: number
Bornes: valeur ≥ 0
Depuis: 0.1.0
Rechargement: à chaud

`ai.budget.monthly_tokens`

Tokens par tenant et par mois civil UTC. Entier positif ou nul ; 0 : aucun budget mensuel.

Type: integer
Depuis: 0.1.0
Rechargement: à chaud

`ai.budget.soft`

Plafond souple : passé at du budget en euros, la passerelle prévient (Flexway-Budget: soft, métrique, journal) et route vers backend s'il est renseigné. Exige un budget en euros (monthly_eur ou celui d'une surcharge).

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`ai.budget.soft.at`

Part du budget en euros au-delà de laquelle le plafond souple s'applique : nombre dans ]0, 1] (par exemple 0.8).

Type: number
Bornes: valeur ≥ 0, ≤ 1
Depuis: 0.1.0
Rechargement: à chaud

`ai.budget.soft.backend`

Backend de ai.backends vers lequel basculer au-delà du plafond souple - sauf une requête sensible, qui reste épinglée. Jamais un grpc. Absent : prévenir seulement.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`ai.budget.store`

Cache des compteurs de budget : redis://hôte:port (ou rediss://), ou une référence (${VAR}, file:/chemin) dès qu'il porte un mot de passe. Obligatoire.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`ai.default_backend`

Backend de ai.backends qui sert un appel qu'aucune surcharge ne route ailleurs. Obligatoire ; un backend openai ou relay, jamais grpc.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`ai.overrides`

Routent ou budgètent autrement un tenant, ou un agent de ce tenant ; la première qui correspond gagne. Une surcharge qui nomme une capacité ne fait que router, jamais budgéter.

Type: list<object>
Depuis: 0.1.0
Rechargement: à chaud

`ai.overrides.*.backend`

Backend de ai.backends qui sert les appels concernés ; jamais un grpc. Obligatoire quand match.capability est renseigné, et ce backend doit servir la capacité.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`ai.overrides.*.daily_tokens`

Budget journalier en tokens du tenant concerné, à la place de ai.budget.daily_tokens. Entier positif ou nul ; interdit avec match.capability.

Type: integer
Depuis: 0.1.0
Rechargement: à chaud

`ai.overrides.*.match`

Ce qui sélectionne les appels : un tenant, un agent de ce tenant, une capacité.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`ai.overrides.*.match.agent`

Agent appelant (le sujet de l'appel) à qui la surcharge s'applique, au sein de tenant.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`ai.overrides.*.match.capability`

Capacité demandée : chat, vision ou embeddings. Une telle surcharge route seulement : elle exige backend et refuse tout budget.

Type: string
Valeurs admises: chatvisionembeddings
Depuis: 1.5.0
Rechargement: à chaud

`ai.overrides.*.match.tenant`

Tenant à qui la surcharge s'applique.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`ai.overrides.*.monthly_eur`

Budget mensuel en euros du tenant concerné, à la place de ai.budget.monthly_eur. Nombre positif ou nul ; exige price sur les backends ; interdit avec match.capability.

Type: number
Depuis: 0.1.0
Rechargement: à chaud

`ai.overrides.*.monthly_tokens`

Budget mensuel en tokens du tenant concerné, à la place de ai.budget.monthly_tokens. Entier positif ou nul ; interdit avec match.capability.

Type: integer
Depuis: 0.1.0
Rechargement: à chaud

`ai.security`

Identités que /v1/* accepte, dont une seule suffit - comme security dans un contrat. Liste non vide ; chaque entrée nomme exactement un mécanisme : trusted_headers, oidc, api_key ou mtls.

Type: list<object>
Depuis: 0.1.0
Rechargement: à chaud

`ai.security.*.api_key`

Accepte une clé d'API ({}). Exige auth.api_keys.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`ai.security.*.mtls`

Accepte un certificat client déclaré ({}). Exige auth.mtls.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`ai.security.*.oidc`

Accepte un jeton d'un émetteur de auth.issuers, avec les portées et rôles exigés. Exige au moins un émetteur.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`ai.security.*.oidc.roles`

Rôles que le jeton doit porter (lus par roles_claim de son émetteur).

Type: list<string>
Depuis: 0.1.0
Rechargement: à chaud

`ai.security.*.oidc.scopes`

Portées que le jeton doit porter.

Type: list<string>
Depuis: 0.1.0
Rechargement: à chaud

`ai.security.*.trusted_headers`

Accepte l'identité écrite par un pair de confiance dans les en-têtes de auth.trusted_headers ({}), crue d'un pair de server.trusted_proxies seulement. Exige auth.trusted_headers.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`ai.sensitive_backend`

Backend interne de ai.backends où une requête sensible est épinglée. Un backend externe ou grpc est refusé ; sans lui, une requête sensible est refusée (403), jamais envoyée à un externe.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`ai.sensitive_header`

En-tête qui, mis à true par l'appelant, épingle la requête sur sensitive_backend. Cru de tout appelant : il ne peut que resserrer le routage. Nom d'en-tête (lettres, chiffres, -).

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`ai.vision`

Bornes des images d'une complétion de chat. Absent : les défauts, et seules les images data: en ligne sont acceptées.

Type: object
Depuis: 1.5.0
Rechargement: à chaud

`ai.vision.allowed_origins`

Origines (https://hôte[:port], sans chemin) depuis lesquelles une image peut être donnée par URL. Vide : images data: en ligne seulement. La passerelle ne les télécharge jamais : le backend le fait.

Type: list<string>
Depuis: 1.5.0
Rechargement: à chaud

`ai.vision.max_body_bytes`

Borne du corps d'une complétion qui porte des images. Taille (24MiB, ou un nombre d'octets) ; défaut 24MiB. Une complétion sans image garde server.limits.max_body. Au moins max_image_bytes.

Type: integer | string
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.5.0
Rechargement: à chaud

`ai.vision.max_image_bytes`

Borne d'une image, une fois décodée. Taille (8MiB, ou un nombre d'octets) ; défaut 8MiB.

Type: integer | string
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.5.0
Rechargement: à chaud

`audit`

Journal d'audit chaîné des décisions d'autorisation du plan API : chaque entrée est liée à la précédente par une empreinte, ce qui rend une réécriture visible.

Type: object
Depuis: 1.0.0
Rechargement: à chaud

`audit.decisions`

Décisions enregistrées : all (toutes) ou refusals (les refus seulement). Absente ou vide : aucune décision n'est enregistrée.

Type: string
Valeurs admises: allrefusals
Depuis: 1.0.0
Rechargement: à chaud

`audit.key`redémarrage

Clé HMAC de la chaîne et de l'empreinte du sujet, par référence (${VAR} ou file:/chemin), jamais en clair. Sans elle, qui peut écrire tout le flux peut le réécrire et recalculer chaque empreinte. Lue une seule fois au démarrage.

Type: string
Depuis: 1.0.0
Rechargement: redémarrage nécessaire

`auth`

Comment une identité est vérifiée - jamais ce qu'une opération exige, que le contrat déclare (security) : émetteurs de jetons, clés d'API, certificats clients, en-têtes de confiance.

Type: object
Depuis: 0.3.0
Rechargement: à chaud

`auth.api_keys`

Clés d'API des appelants, une identité - jamais une autorisation : ce qu'une opération exige reste au contrat (schéma apiKey). La clé ne satisfait que l'alternative qui la nomme et n'ouvre que ses opérations liées.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`auth.api_keys.store`obligatoire

Fichier des empreintes des clés : file: suivi d'un chemin, relatif au fichier de configuration sauf s'il est absolu, monté depuis un secret. Jamais une clé en clair ; relu à chaque rechargement - retirer une entrée révoque la clé.

Type: string
Motif: ^file:.+
Depuis: 0.1.0
Rechargement: à chaud

`auth.issuers`

Fournisseurs de jetons de confiance (OIDC), plusieurs à la fois : un client en a souvent un pour ses employés et un autre pour ses utilisateurs finaux. Deux entrées ne peuvent désigner le même émetteur.

Type: list<object>
Depuis: 0.3.0
Rechargement: à chaud

`auth.issuers.*.algorithms`

Algorithmes de signature acceptés. Défaut : la famille asymétrique (RS256 à RS512, PS256 à PS512, ES256 à ES512, EdDSA). none et la famille HMAC (HS*) sont refusés au chargement.

Type: list<string>
Défaut: ["RS256","RS384","RS512","PS256","PS384","PS512","ES256","ES384","ES512","EdDSA"]
Depuis: 0.3.0
Rechargement: à chaud

`auth.issuers.*.audience`

Audience pour laquelle un jeton doit être émis, vérifiée avec l'émetteur. Obligatoire sauf si audiences est utilisé ; exclusive de audiences.

Type: string
Depuis: 0.3.0
Rechargement: à chaud

`auth.issuers.*.audiences`

À la place de audience, accepte un jeton émis pour l'une d'elles - le temps qu'une API renomme son audience. Aucune entrée vide ; exclusive de audience.

Type: list<string>
Depuis: 1.0.0
Rechargement: à chaud

`auth.issuers.*.client`

Client de la passerelle chez cet émetteur : pour échanger un jeton d'appelant contre un jeton émis pour un amont (RFC 8693), introspecter des jetons opaques ou délégués, obtenir un jeton de découverte. Obligatoire dès qu'un amont déclare token_exchange ou que agents.delegation est présent.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`auth.issuers.*.client.id`obligatoire

Identifiant du client de la passerelle chez l'émetteur. Obligatoire.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`auth.issuers.*.client.secret`obligatoiresecret

Secret du client, par référence (${VAR} ou file:/chemin), résolu à chaque usage : une rotation est lue sans rechargement. Jamais une valeur en clair.

Type: string
Motif: ^(\$\{[A-Za-z_][A-Za-z0-9_]*\}|file:/\S+)$
Secret: une référence, ${VAR} ou file:/chemin, jamais une valeur en clair
Depuis: 0.1.0
Rechargement: à chaud

`auth.issuers.*.discovery`obligatoire

URL du document de découverte du fournisseur, terminée par /.well-known/openid-configuration. URL absolue http(s) ; obligatoire. L'identifiant de l'émetteur en est déduit, sauf si issuer le donne.

Type: string
Depuis: 0.3.0
Rechargement: à chaud

`auth.issuers.*.issuer`

Identifiant que le fournisseur énonce, quand il diffère de l'URL de découverte - un fournisseur joint en interne sous un nom et annonçant son nom public (horizon partagé). URL absolue http(s) ; le document de découverte et chaque jeton doivent énoncer exactement cette valeur. Absent : déduit de discovery.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`auth.issuers.*.name`obligatoire

Nom de l'émetteur dans les journaux et les métriques, unique. Obligatoire ; apikey et mtls sont réservés.

Type: string
Depuis: 0.3.0
Rechargement: à chaud

`auth.issuers.*.opaque_tokens`

Fait de cet émetteur celui qui répond des jetons qui ne sont pas des JWT : ils sont introspectés (RFC 7662) avec client, qui est alors obligatoire. Un seul émetteur au plus : un jeton opaque ne nomme aucun émetteur.

Type: object
Depuis: 1.0.0
Rechargement: à chaud

`auth.issuers.*.opaque_tokens.cache`

Durée de réutilisation d'une réponse d'introspection - le délai avant qu'une révocation soit vue -, jamais au-delà de l'exp du jeton. Durée de 1s à 5m ; défaut 30s.

Type: string
Défaut: 30s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.0.0
Rechargement: à chaud

`auth.issuers.*.roles_claim`

Chemin pointé de la claim qui porte les rôles (realm_access.roles pour Keycloak, roles pour Entra ID). Absent : aucun rôle ne peut être satisfait pour cet émetteur.

Type: string
Depuis: 0.3.0
Rechargement: à chaud

`auth.issuers.*.scopes_claim`

Claim qui porte les portées. Défaut scope (séparées par des espaces), puis scp.

Type: string
Défaut: scope
Depuis: 0.3.0
Rechargement: à chaud

`auth.issuers.*.service_accounts`

Comment ce fournisseur marque un jeton émis à un client agissant pour lui-même, quand son sujet n'est pas l'identifiant du client (Keycloak : preferred_username = service-account-<client>). claim et prefix sont obligatoires.

Type: object
Depuis: 1.0.0
Rechargement: à chaud

`auth.issuers.*.service_accounts.claim`obligatoire

Claim qui marque un compte de service (par exemple preferred_username). Obligatoire.

Type: string
Depuis: 1.0.0
Rechargement: à chaud

`auth.issuers.*.service_accounts.prefix`obligatoire

Préfixe de la valeur de claim qui marque un compte de service, suivi de l'identifiant du client (par exemple service-account-). Obligatoire et non vide : un préfixe vide marquerait tous les jetons.

Type: string
Depuis: 1.0.0
Rechargement: à chaud

`auth.issuers.*.tenant_claim`

Nom de la claim qui porte le tenant. Absente : les requêtes de cet émetteur n'en portent aucun.

Type: string
Depuis: 0.3.0
Rechargement: à chaud

`auth.mtls`

Certificats clients reconnus par la passerelle - une identité, exigée par un schéma mutualTLS du contrat. Vérifiés par l'écouteur TLS (server.tls) ou attestés par l'en-tête x-forwarded-client-cert d'un edge de confiance.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`auth.mtls.clients`

Certificats reconnus, chacun lié à un tenant et à des opérations.

Type: list<object>
Depuis: 0.1.0
Rechargement: à chaud

`auth.mtls.clients.*.id`obligatoire

Nom du certificat dans les journaux et les métriques, unique. Obligatoire.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`auth.mtls.clients.*.operations`

Identifiants d'opération (operationId) que ce certificat ouvre - et seulement eux. Obligatoire et non vide.

Type: list<string>
Depuis: 0.1.0
Rechargement: à chaud

`auth.mtls.clients.*.subject`

Sujet du certificat (par exemple CN=batch,O=Acme). Exactement un de uri ou subject.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`auth.mtls.clients.*.tenant`obligatoire

Tenant auquel le certificat est lié. Obligatoire.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`auth.mtls.clients.*.uri`

Premier SAN URI du certificat (un identifiant SPIFFE par exemple, spiffe://bank.example/settler). Exactement un de uri ou subject.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`auth.tenant_header`

En-tête où le tenant résolu est écrit vers l'amont ; ce qu'un appelant a envoyé sous ce nom est écrasé. Nom d'en-tête (lettres, chiffres, -). Vide : le tenant n'est pas propagé (il reste une dimension des métriques).

Type: string
Depuis: 0.3.0
Rechargement: à chaud

`auth.trusted_headers`

En-têtes où un pair de confiance - une entrée de maillage qui a authentifié l'appelant - écrit l'identité. Crus d'un pair de server.trusted_proxies seulement, qui est alors obligatoire ; refusés avec server.peer_identity_header. Les noms sont ceux du déploiement.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`auth.trusted_headers.subject`

Nom de l'en-tête qui porte le sujet (l'agent appelant). Facultatif ; nom d'en-tête.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`auth.trusted_headers.tenant`

Nom de l'en-tête qui porte le tenant. Obligatoire ; nom d'en-tête (lettres, chiffres, -).

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`contracts`

Les fichiers qui portent l'ensemble servi : le contrat est la configuration. Au moins un des contrats est requis (openapi, protobuf, a2a ou asyncapi), sauf pour une passerelle qui ne sert que la surface d'inférence (ai). Chemins relatifs au fichier de configuration, lus sur disque au chargement, sans accès réseau.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`contracts.a2a`

Cartes d'agent A2A déclarées (fichiers JSON .json) : chaque méthode d'un agent est une opération, servie aux adresses de sa carte et relayée vers l'amont que nomme son x-flexway-a2a. Chaque entrée une seule fois, jamais vide.

Type: list<string>
Depuis: 1.2.0
Rechargement: à chaud

`contracts.asyncapi`

Document AsyncAPI 3 (.yaml, .yml ou .json) : ses opérations send et receive forment le plan asynchrone - publications atteintes par les opérations OpenAPI marquées x-flexway-publish, consommations par x-flexway-subscribe, livraisons webhook déclarées par x-flexway-deliver.

Type: string
Depuis: 1.5.0
Rechargement: à chaud

`contracts.openapi`

Contrat OpenAPI par défaut : servi sur chaque hôte qui ne déclare pas ses propres contracts, et sur tout hôte non déclaré. Facultatif dès qu'un hôte déclare les siens.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`contracts.protobuf`

Jeux de descripteurs Protobuf (FileDescriptorSet, imports compris - buf build ou protoc avec ses imports), extensions .binpb, .pb ou .protoset, servis à côté de l'OpenAPI sur les mêmes hôtes : chaque méthode de chaque service déclaré est une opération.

Type: list<string>
Depuis: 1.1.0
Rechargement: à chaud

`errors`

Forme des documents d'erreur RFC 9457 des routes produit. La surface d'inférence /v1/* garde l'enveloppe OpenAI.

Type: object
Depuis: 1.0.0
Rechargement: à chaud

`errors.field_codes`

Renomme le code d'une erreur de champ (errors[].code d'une réponse 422) : un mot-clé JSON Schema qu'une requête peut enfreindre (required, type, enum, pattern, minLength...) ou invalid, vers un jeton du client (lettres, chiffres, _ . -, 64 au plus). Un mot-clé non listé garde son nom.

Type: map<string>
Depuis: 1.0.0
Rechargement: à chaud

`errors.type_base`

Espace de noms du champ type des erreurs : une URL http(s) absolue terminée par /, à laquelle le code est ajouté - le portail du client plutôt que celui du produit. Absent : l'espace de noms par défaut du produit.

Type: string
Depuis: 1.0.0
Rechargement: à chaud

`hosts`

Les hôtes servis, par nom (l'autorité de la requête) : chacun regroupe les opérations servies sous ce nom et leur donne un amont par défaut.

Type: map<object>
Depuis: 0.1.0
Rechargement: à chaud

`hosts.*.contracts`

Contrats OpenAPI que sert cet hôte - exactement leur union, rien du contrat par défaut. Chemins relatifs au fichier de configuration, chacun une seule fois. Absent : le contrat par défaut (contracts.openapi).

Type: list<string>
Depuis: 0.1.0
Rechargement: à chaud

`hosts.*.default_upstream`

Amont (nom déclaré dans upstreams) des opérations de cet hôte qui n'en nomment pas par x-flexway-upstream.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`hosts.*.validation`

Part d'une requête validée contre le contrat sur cet hôte : full (défaut, tout), params (paramètres seulement, le corps est relayé sans être lu et le service le valide) ou off. Le x-flexway-validation d'une opération l'emporte.

Type: string
Valeurs admises: fullparamsoff
Défaut: full
Depuis: 1.0.0
Rechargement: à chaud

`kms`

Le service de gestion de clés du chiffrement par champ sur l'écouteur Kafka : il enveloppe les clés de données que la passerelle tire, sous une clé qui ne le quitte jamais. Exactement un genre est écrit : vault_transit, aws_kms, gcp_kms ou local ; absent, un contrat qui déclare x-flexway-encrypt est refusé au chargement.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`kms.aws_kms`

AWS KMS. Sans credentials_file, les identifiants viennent de la chaîne par défaut du SDK (IRSA, rôle d'instance).

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`kms.aws_kms.credentials_file`secret

Chemin d'un fichier d'identifiants partagés AWS monté (pas une valeur) ; le fichier doit exister. Absent : chaîne par défaut du SDK.

Type: string
Motif: ^(\$\{[A-Za-z_][A-Za-z0-9_]*\}|file:/\S+)$
Secret: une référence, ${VAR} ou file:/chemin, jamais une valeur en clair
Depuis: 1.6.0
Rechargement: à chaud

`kms.aws_kms.endpoint`

Adresse https:// d'un point d'accès KMS autre que celui de la région (point d'accès privé, émulateur). Absent : le point d'accès public de la région.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`kms.aws_kms.profile`

Profil à lire dans credentials_file ; refusé si credentials_file n'est pas écrit.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`kms.aws_kms.region`obligatoire

Région AWS de la clé (eu-west-3) ; obligatoire.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`kms.cache`

Borne les clés de données gardées déchiffrées en mémoire : en nombre, en durée, et la mémoire d'un refus du KMS.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`kms.cache.max_keys`

Nombre de clés de données gardées déchiffrées, partagé entre tenants ; de 1 à 1 000 000, défaut 10000.

Type: integer
Défaut: 10000
Bornes: valeur ≥ 1, ≤ 1000000
Depuis: 1.6.0
Rechargement: à chaud

`kms.cache.negative_ttl`

Durée pendant laquelle un refus du KMS est retenu avant de redemander ; de 100ms à 5m, défaut 5s. Un effacement de clé prend effet au plus après ttl + negative_ttl.

Type: string
Défaut: 5s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`kms.cache.ttl`

Durée de vie d'une clé de données déchiffrée en mémoire, comptée depuis son déchiffrement ; la clé d'écriture est revérifiée au KMS à chaque ttl. De 1s à 24h, défaut 1h.

Type: string
Défaut: 1h
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`kms.gcp_kms`

Google Cloud KMS. Sans credentials_file, les identifiants par défaut de l'application (Workload Identity).

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`kms.gcp_kms.credentials_file`secret

Chemin d'une clé de compte de service monté (pas une valeur) ; le fichier doit exister. Absent : identifiants par défaut de l'application.

Type: string
Motif: ^(\$\{[A-Za-z_][A-Za-z0-9_]*\}|file:/\S+)$
Secret: une référence, ${VAR} ou file:/chemin, jamais une valeur en clair
Depuis: 1.6.0
Rechargement: à chaud

`kms.gcp_kms.endpoint`

Point d'accès de Cloud KMS autre que le public ; absent : cloudkms.googleapis.com.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`kms.key`obligatoire

La clé du KMS qui enveloppe les clés de données : clé transit Vault, identifiant, ARN ou alias AWS, nom de ressource projects/<p>/locations/<l>/keyRings/<r>/cryptoKeys/<k> pour GCP, fichier de clé en local. {tenant} en fait une clé par tenant (détruire la clé efface les champs de ce seul tenant). Lettres, chiffres et . _ : / @ + = , - ; une clé Vault ou locale est un seul nom, sans / ni :. Obligatoire, vérifiée au démarrage.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`kms.local`

Clés dans des fichiers d'un répertoire monté : tests et développement seulement.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`kms.local.dir`obligatoire

Répertoire des fichiers de clés ; obligatoire, il doit exister.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`kms.previous_keys`

Anciennes valeurs de key qu'un enregistrement peut encore nommer : lues, jamais écrites ; un enregistrement qui nomme une autre clé est refusé. Même syntaxe que key, {tenant} compris ; 8 au plus, sans doublon ni key elle-même.

Type: list<string>
Bornes: éléments ≤ 8
Depuis: 1.6.0
Rechargement: à chaud

`kms.rotation`

Quand une nouvelle clé de données commence : après interval ou max_encryptions champs chiffrés, au premier atteint.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`kms.rotation.interval`

Durée d'usage d'une clé de données avant la suivante ; de 1m à 168h (7 jours), défaut 1h.

Type: string
Défaut: 1h
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`kms.rotation.max_encryptions`

Nombre de champs chiffrés sous une même clé de données avant la suivante ; de 1 à 2^30 (1 073 741 824), défaut 5000000.

Type: integer
Défaut: 5000000
Bornes: valeur ≥ 1, ≤ 1073741824
Depuis: 1.6.0
Rechargement: à chaud

`kms.tenant_calls`

Seau à jetons des appels au KMS que causent les enregistrements d'un tenant : un producteur qui épuise le sien n'entame jamais celui d'un autre tenant.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`kms.tenant_calls.burst`

Appels au KMS permis d'un coup pour un tenant ; au moins 1, défaut 20.

Type: integer
Défaut: 20
Bornes: valeur ≥ 1
Depuis: 1.6.0
Rechargement: à chaud

`kms.tenant_calls.rate`

Appels au KMS par seconde pour un tenant ; plus de 0, défaut 10.

Type: number
Défaut: 10
Depuis: 1.6.0
Rechargement: à chaud

`kms.timeout`

Délai d'un appel au KMS, qui retient la requête Kafka qui en a besoin ; plus de 0 et 30s au plus, défaut 2s. KMS indisponible : KAFKA_STORAGE_ERROR, jamais un clair.

Type: string
Défaut: 2s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`kms.vault_transit`

Le moteur transit de Vault, clé dérivée (son contexte lie le tenant et le sujet). Authentification par token ou par kubernetes, l'une des deux.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`kms.vault_transit.address`obligatoire

Adresse absolue de Vault en https:// (https://vault.security:8200), sans identifiants ni paramètres ; http:// est refusé : le jeton circulerait en clair. Obligatoire.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`kms.vault_transit.kubernetes`

Méthode d'authentification Kubernetes de Vault : le jeton du compte de service du pod, pour un rôle. Exclusive de token.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`kms.vault_transit.kubernetes.mount`

Chemin de la méthode d'authentification Kubernetes dans Vault ; défaut kubernetes.

Type: string
Défaut: kubernetes
Depuis: 1.6.0
Rechargement: à chaud

`kms.vault_transit.kubernetes.role`obligatoire

Rôle Vault demandé avec le jeton du compte de service ; obligatoire.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`kms.vault_transit.kubernetes.token_file`secret

Fichier du jeton du compte de service ; défaut /var/run/secrets/kubernetes.io/serviceaccount/token.

Type: string
Défaut: /var/run/secrets/kubernetes.io/serviceaccount/token
Motif: ^(\$\{[A-Za-z_][A-Za-z0-9_]*\}|file:/\S+)$
Secret: une référence, ${VAR} ou file:/chemin, jamais une valeur en clair
Depuis: 1.6.0
Rechargement: à chaud

`kms.vault_transit.mount`

Chemin du moteur transit dans Vault ; segments de lettres, chiffres, ., _, - séparés par /. Défaut transit.

Type: string
Défaut: transit
Depuis: 1.6.0
Rechargement: à chaud

`kms.vault_transit.namespace`

Espace de noms Vault (Vault Enterprise) ; facultatif.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`kms.vault_transit.tls`

TLS client vers Vault : autorité de confiance, certificat client, nom attendu.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`kms.vault_transit.tls.ca_file`

Fichier PEM de l'autorité qui vérifie le certificat du serveur ; absent : les autorités du système. Le fichier doit exister.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`kms.vault_transit.tls.cert_file`

Certificat client PEM présenté à Vault ; va avec key_file. Le fichier doit exister.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`kms.vault_transit.tls.key_file`

Clé privée PEM du certificat client ; va avec cert_file. Le fichier doit exister.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`kms.vault_transit.tls.server_name`

Nom attendu dans le certificat de Vault, quand il diffère de l'hôte de address.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`kms.vault_transit.token`secret

Jeton Vault par référence, ${VAR} ou file:/chemin, relu à chaque appel ; jamais la valeur. Exclusif de kubernetes.

Type: string
Motif: ^(\$\{[A-Za-z_][A-Za-z0-9_]*\}|file:/\S+)$
Secret: une référence, ${VAR} ou file:/chemin, jamais une valeur en clair
Depuis: 1.6.0
Rechargement: à chaud

`listeners`

Les points d'entrée de la passerelle à côté de HTTP.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka`

L'écouteur Kafka : producteurs, consommateurs et outils d'administration Kafka atteignent les clusters virtuels que le contrat AsyncAPI déclare (x-flexway-kafka-proxy), sous la même décision que HTTP. Rien ici ne liste un sujet : le contrat le fait. Un port TLS, le courtier nommé par le SNI du client (address), ou des ports en clair dans un maillage (plaintext) ; exige contracts.asyncapi.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.address`redémarrage

Adresse hôte:port de l'écouteur TLS (:9093) ; exige tls et sni_domain. Absente : ports en clair seulement. Lue une fois au démarrage.

Type: string
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.kafka.advertised_port`redémarrage

Port écrit dans les adresses de courtier données au client (Metadata, FindCoordinator) : celui qu'expose un répartiteur de charge. De 1 à 65535 ; absent : le port d'address. Seulement avec address.

Type: integer
Bornes: valeur ≥ 1, ≤ 65535
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.kafka.auth_timeout`

Délai absolu dont dispose une connexion pour s'authentifier ; plus de 0 et 1m au plus, défaut 10s.

Type: string
Défaut: 10s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.idle_timeout`

Ferme une connexion qui n'a rien envoyé pendant cette durée (connections.max.idle.ms de Kafka) ; 1s au moins, défaut 10m.

Type: string
Défaut: 10m
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.max_connection_rate_per_tenant`

Connexions qu'un tenant ouvre par seconde, comptées à l'authentification (seau d'une seconde) : un client qui se reconnecte en boucle coûte les places de son tenant, jamais celles des autres. De 0 (sans borne) à 100000, défaut 100.

Type: number
Défaut: 100
Bornes: valeur ≥ 0, ≤ 100000
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.max_connections`redémarrage

Connexions clientes ouvertes à la fois ; au-delà, une nouvelle attend d'être acceptée. De 1 à 100000, défaut 4096.

Type: integer
Défaut: 4096
Bornes: valeur ≥ 1, ≤ 100000
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.kafka.max_connections_per_ip`

Connexions d'une même adresse cliente ; de 0 (sans borne, derrière un proxy qui masque les adresses) à max_connections, défaut 16.

Type: integer
Défaut: 16
Bornes: valeur ≥ 0
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.max_connections_per_tenant`

Connexions d'un même tenant, comptées à l'authentification ; de 1 à max_connections, défaut 1024.

Type: integer
Défaut: 1024
Bornes: valeur ≥ 1
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.max_fetch_wait`

Attente maximale d'un Fetch chez le courtier pour des données (son max_wait_ms) ; de 100ms à 5m, défaut 30s.

Type: string
Défaut: 30s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.max_in_flight_bytes`

Réponses qu'une connexion garde en mémoire, lues du courtier et pas encore écrites ; au-delà, l'écouteur cesse de lire le courtier (contre-pression, jamais un refus). Taille (64MiB) de 1MiB à max_total_in_flight_bytes, défaut 64MiB.

Type: integer | string
Défaut: 64MiB
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.max_request_bytes`

Taille maximale d'une trame de requête d'un client authentifié, lue en entier avant d'être décodée ; de 64KiB à 100MiB, défaut 16MiB. Avant l'authentification, 64 Kio seulement.

Type: integer | string
Défaut: 16MiB
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.max_response_bytes`

Taille maximale d'une réponse du courtier ; le MaxBytes d'un Fetch est tenu sous sa moitié. De 1MiB à 256MiB, défaut 64MiB ; avec des champs chiffrés, au moins max_request_bytes.

Type: integer | string
Défaut: 64MiB
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.max_session_lifetime`

Durée maximale d'une session quel que soit l'identifiant : un client SASL se réauthentifie avant (KIP-368), une connexion identifiée par certificat est fermée ; une révocation se voit au plus tard alors. De 1m à 24h, défaut 1h.

Type: string
Défaut: 1h
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.max_tenant_in_flight_bytes`redémarrage

Même borne que max_in_flight_bytes, pour toutes les connexions d'un tenant : sa part de max_total_in_flight_bytes ; un tenant qui ne lit pas ne bloque jamais les autres. De max_in_flight_bytes à max_total_in_flight_bytes ; absente : un huitième du total, au moins max_in_flight_bytes. Lue une fois au démarrage.

Type: integer | string
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.kafka.max_topic_partitions`

Partitions qu'un administrateur peut donner à un sujet (CreateTopics, CreatePartitions) ; de 1 à 10000, défaut 64.

Type: integer
Défaut: 64
Bornes: valeur ≥ 1, ≤ 10000
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.max_total_in_flight_bytes`redémarrage

Réponses en mémoire pour toute la réplique, toutes connexions confondues ; 64GiB au plus, défaut 1GiB. Lue une fois au démarrage.

Type: integer | string
Défaut: 1GiB
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.kafka.max_unauthenticated_connections`

Connexions qui n'ont pas encore prouvé leur identité ; au-delà, une nouvelle est fermée aussitôt et les clients authentifiés gardent leurs places. De 1 à max_connections, défaut 256.

Type: integer
Défaut: 256
Bornes: valeur ≥ 1
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.on_tenant_budget_exceeded`

Sort d'une connexion dont la réponse dépasserait max_tenant_in_flight_bytes : wait (défaut) - le courtier n'est plus lu jusqu'à ce que les clients du tenant lisent - ou close - la connexion est fermée aussitôt, pour des tenants dont on ne garantit pas la lecture. Les autres tenants ne sont jamais bloqués.

Type: string
Valeurs admises: waitclose
Défaut: wait
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.plaintext`redémarrage

Repli sans TLS : un port d'amorçage et un port par courtier pour chaque cluster virtuel, seulement là où un maillage chiffre déjà entre pods (mesh_only: true obligatoire). Lu une fois au démarrage.

Type: object
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.kafka.plaintext.advertised_host`redémarrage

Hôte écrit dans les adresses de courtier données au client : le nom du Service de la passerelle dans le maillage, sans port. Obligatoire.

Type: string
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.kafka.plaintext.clusters`redémarrage

Les ports de chaque cluster virtuel, par nom de cluster (un label DNS : minuscules, chiffres, -) ; au moins un.

Type: map<object>
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.kafka.plaintext.clusters.*.first_node_id`redémarrage

Identifiant de nœud du premier courtier : le port from + 1 + i sert le nœud first_node_id + i. Entier positif ou nul, défaut 0.

Type: integer
Bornes: valeur ≥ 0
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.kafka.plaintext.clusters.*.ports`redémarrage

Plage fermée des ports du cluster : from est l'amorçage, puis un port par courtier jusqu'à to ; 65 ports au plus, jamais partagés avec un autre cluster ni avec address.

Type: object
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.kafka.plaintext.clusters.*.ports.from`redémarrage

Port d'amorçage du cluster ; de 1 à 65535.

Type: integer
Bornes: valeur ≥ 1, ≤ 65535
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.kafka.plaintext.clusters.*.ports.to`redémarrage

Dernier port de la plage, plus grand que from ; 65535 au plus.

Type: integer
Bornes: valeur ≥ 1, ≤ 65535
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.kafka.plaintext.mesh_only`redémarrage

Doit valoir true : affirme qu'un maillage chiffre entre pods. Sans lui, les identifiants d'un client Kafka traverseraient le réseau en clair, et la configuration est refusée.

Type: boolean
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.kafka.quotas`

Quotas d'octets et de requêtes par principal vérifié et par tenant, comme un courtier Kafka (KIP-219) : la réponse part aussitôt avec throttle_time_ms, puis la connexion n'est plus lue pendant ce délai. Absent : rien n'est freiné.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.quotas.client`

Débits de chaque principal vérifié - sujet du jeton, clé d'API, certificat -, jamais le client.id qu'un client se donne. Aucune borne par défaut.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.quotas.client.consumer_byte_rate`

Octets lus par seconde (réponses Fetch) par principal ; une taille (10MiB), 0 ou absent : sans borne.

Type: integer | string
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.quotas.client.producer_byte_rate`

Octets produits par seconde (requêtes Produce) par principal ; une taille (10MiB), 0 ou absent : sans borne.

Type: integer | string
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.quotas.client.request_rate`

Requêtes par seconde par principal, quelle que soit l'API ; nombre positif, 0 ou absent : sans borne.

Type: number
Bornes: valeur ≥ 0
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.quotas.max_throttle`

Plafond du throttle_time_ms annoncé et du silence qui suit, sous le request.timeout.ms des clients ; de 100ms à 30s, défaut 10s.

Type: string
Défaut: 10s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.quotas.quota`

Nom d'une politique de type quota de policies.definitions : le budget jour ou mois des Produce du tenant, partagé avec HTTP sous le même nom ; épuisé : POLICY_VIOLATION. Vide : aucun.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.quotas.tenant`

Débits de tous les principaux d'un même tenant ensemble. Aucune borne par défaut.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.quotas.tenant.consumer_byte_rate`

Octets lus par seconde par tenant ; une taille, 0 ou absent : sans borne.

Type: integer | string
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.quotas.tenant.producer_byte_rate`

Octets produits par seconde par tenant ; une taille, 0 ou absent : sans borne.

Type: integer | string
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.quotas.tenant.request_rate`

Requêtes par seconde par tenant, quelle que soit l'API ; 0 ou absent : sans borne.

Type: number
Bornes: valeur ≥ 0
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.quotas.window`

Part d'un débit qu'une rafale peut prendre d'un coup : un seau contient débit x fenêtre ; de 100ms à 10s, défaut 1s.

Type: string
Défaut: 1s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.kafka.sni_domain`redémarrage

Domaine DNS sous lequel vivent les noms de courtier (kafka.example.com) : bootstrap.<cluster>.<sni_domain> et broker-<id>.<cluster>.<sni_domain>. Au moins deux labels, en minuscules ; obligatoire avec address.

Type: string
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.kafka.tls`redémarrage

Certificat de l'écouteur TLS - un certificat qui couvre *.<cluster>.<sni_domain> pour chaque cluster - et, avec client_ca_file, l'autorité des certificats clients. Obligatoire avec address, refusé sans lui.

Type: object
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.kafka.tls.cert_file`redémarrage

Certificat PEM de l'écouteur ; obligatoire, le fichier doit exister.

Type: string
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.kafka.tls.client_ca_file`redémarrage

Autorité PEM contre laquelle les certificats clients sont vérifiés (identité X509) ; facultative, le fichier doit exister.

Type: string
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.kafka.tls.key_file`redémarrage

Clé privée PEM du certificat de l'écouteur ; obligatoire, le fichier doit exister.

Type: string
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`listeners.mqtt`

L'écouteur MQTT des appareils : les appareils se connectent en MQTT 5 ou 3.1.1 sur TCP, TLS ou WebSocket et atteignent le courtier du client à travers lui, une connexion au courtier par appareil, chaque paquet sous la même décision que HTTP. Rien ici ne liste un topic : le contrat AsyncAPI le fait (x-flexway-device). Exige contracts.asyncapi.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.address`

Adresse hôte:port de l'écouteur (:8883) ; TLS quand tls est renseigné. Lue une seule fois au démarrage.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.advertised_address`

Adresse hôte:port où les appareils joignent l'écouteur - celle de l'équilibreur : la failover.server_reference par défaut.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.allow_zero_keepalive`

Admet un appareil MQTT 3.1.1 qui ne demande aucun keep-alive (0). false (défaut) : il est refusé (code 0x05), comme celui qui demande plus que max_keepalive - MQTT 3.1.1 ne permet pas d'imposer un keep-alive, et un appareil muet ne serait jamais vu parti. Un appareil MQTT 5 reçoit max_keepalive à la place.

Type: boolean
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.broker_mesh_only`

Admet des courtiers en clair (mqtt://, ws://) quand l'écouteur lui-même est en TLS : le maillage chiffre le saut vers le courtier. false (défaut) : un courtier en clair est refusé au chargement sauf avec mesh_only.

Type: boolean
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.connect_timeout`

Temps laissé à une connexion pour finir TLS et envoyer son CONNECT, et au courtier pour répondre ; plus de 0 et 1m au plus, défaut 5s.

Type: string
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.device`

Bornes de chaque connexion d'appareil ; le x-flexway-device d'une opération surcharge ses débits.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.device.burst`

Secondes de chaque débit qu'une rafale peut prendre d'un coup ; de 1 à 60, défaut 2.

Type: number
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.device.bytes_per_second`

Octets de charge des PUBLISH d'un appareil par seconde, sous la même contre-pression. 0 : aucune borne. Défaut 512 Kio.

Type: integer | string
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.device.connect_rate_per_identity`

CONNECT d'une identité par seconde ; au-delà 0x9F : un appareil qui se reconnecte en boucle ne s'évince pas lui-même sans fin. 0 : aucune borne. Défaut 1.

Type: number
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.device.max_correlation_data_bytes`

Octets de la donnée de corrélation d'un PUBLISH ; au-delà 0x95. Défaut 8 Kio.

Type: integer | string
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.device.max_filters_per_subscribe`

Filtres d'un SUBSCRIBE ; au-delà chacun est refusé 0x97. Défaut 10.

Type: integer
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.device.max_refusals_per_minute`

Paquets refusés d'une connexion en une minute : chaque refus dépense le débit de messages de l'appareil, son audit est échantillonné (une entrée par seconde et par cause), et au-delà de ce nombre l'appareil est déconnecté 0x96. 0 : sans borne. De 0 à 100000, défaut 60.

Type: integer
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.device.max_sessions_per_identity`

Connexions qu'une identité tient à la fois sur un réplica avec sessions: per_client_id ; au-delà une nouvelle est refusée 0x97 (3.1.1 : 0x03). De 1 à max_connections, défaut 10 (ou max_connections s'il est plus bas).

Type: integer
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.device.max_subscriptions`

Abonnements d'un appareil ; au-delà un filtre est refusé 0x97 (3.1.1 0x80). Défaut 50.

Type: integer
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.device.max_user_properties_bytes`

Octets des propriétés utilisateur d'un paquet ; au-delà 0x95. Défaut 8 Kio.

Type: integer | string
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.device.messages_per_second`

PUBLISH envoyés par seconde par un appareil ; au-delà l'écouteur cesse de lire l'appareil (contre-pression, jamais un refus) et garde vivante sa connexion au courtier. 0 : aucune borne. Défaut 100.

Type: number
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.device.receive_maximum`

PUBLISH QoS 1 et 2 en vol d'un appareil, annoncé comme le plus bas de lui et du courtier ; au-delà 0x93. Défaut 100.

Type: integer
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.device.sessions`

Sessions d'une identité : single (défaut) - client id <tenant>/<identité> au courtier, une seconde connexion évince la première (0x8E) -, ou per_client_id - <tenant>/<identité>/<client id de l'appareil>, pour une identité que plusieurs appareils partagent.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.failover`

Bascule les appareils d'une réplique qui draine ou est pleine vers une autre : MQTT 5 est dirigé, 3.1.1 se reconnecte par l'équilibreur.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.failover.handover_timeout`

Temps pendant lequel une réplique qui draine tient la connexion au courtier d'un appareil pour qu'il revienne ailleurs ; au-delà elle se ferme avec le testament. De 0s à 10m, défaut 30s.

Type: string
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.failover.mode`

redirect (défaut) : 0x9C (ou 0x9D) et une Server Reference, la connexion au courtier tenue handover_timeout pour que l'appareil revienne par une autre réplique ; off : un arrêt envoie 0x8B et ferme la connexion au courtier avec le testament.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.failover.reason`

use_another_server (0x9C, temporaire, défaut) ou server_moved (0x9D, permanent).

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.failover.redirect_above`

Part de max_connections, en pourcentage, au-delà de laquelle un CONNECT est redirigé plutôt qu'accepté. Défaut 95.

Type: number
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.failover.server_reference`

Où va un appareil redirigé ; défaut advertised_address - un client qui l'ignore se reconnecte au même endroit de toute façon.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.failover.will_delay_on_handover`

Vers un courtier MQTT 5, un testament qui ne déclare aucun délai (Will Delay Interval) est écrit avec un délai égal à handover_timeout, et l'expiration de la session au courtier relevée pour le couvrir : le testament survit à une reprise par une autre réplique. La contrepartie : le testament d'un appareil vraiment perdu part jusqu'à handover_timeout plus tard. Sans effet sur un appareil MQTT 3.1.1. Défaut false.

Type: boolean
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.max_connection_rate_per_ip`

Nouvelles connexions d'une adresse cliente par seconde ; 0 : aucune borne. Défaut 20.

Type: number
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.max_connection_rate_per_tenant`

Nouvelles connexions d'appareils d'un tenant par seconde ; au-delà 0x9F (3.1.1 0x03). 0 : aucune borne. Défaut 100.

Type: number
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.max_connections`

Connexions d'appareils d'une réplique ; au-delà un CONNECT est refusé 0x97 (3.1.1 0x03). De 1 à 1000000, défaut 50000. Lu une seule fois au démarrage.

Type: integer
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.max_connections_per_ip`

Connexions d'une adresse cliente ; 0 : aucune borne - à poser derrière un répartiteur ou un proxy qui masque les adresses des appareils (le chart les garde avec externalTrafficPolicy: Local), sinon tous les appareils partagent une adresse et une borne. Défaut 64.

Type: integer
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.max_connections_per_tenant`

Connexions d'appareils d'un tenant sur une réplique ; au-delà 0x97. Défaut 10000.

Type: integer
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.max_keepalive`

Keep-alive le plus haut accordé : un appareil MQTT 5 qui demande plus (ou rien) reçoit celui-ci (Server Keep Alive) ; un appareil MQTT 3.1.1 qui demande plus est refusé (0x05), rien aussi sauf avec allow_zero_keepalive. De 1s à 65535s, défaut 1200s.

Type: string
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.max_packet_bytes`

Borne d'un paquet, lu en entier avant d'être décodé ; annoncée à un appareil MQTT 5 comme la plus basse d'elle et du Maximum Packet Size du courtier. De 1 Kio à 256 Mio, défaut 256 Kio.

Type: integer | string
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.max_session_expiry`

Expiration de session la plus longue accordée au courtier. Défaut 1h.

Type: string
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.max_session_lifetime`

Durée la plus longue d'une connexion d'appareil quel que soit son identifiant : au-delà l'appareil est déconnecté et se reconnecte avec un identifiant vérifié à nouveau. De 1m à 30d, défaut 24h.

Type: string
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.max_unauthenticated_connections`

Connexions qui n'ont pas encore envoyé leur CONNECT ; au-delà une nouvelle est fermée aussitôt. De 1 à max_connections, défaut 1024.

Type: integer
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.mesh_only`

Admet l'écouteur sans TLS : le jeton ou la clé d'un appareil traverse le réseau en clair, donc ne s'écrit que là où un maillage chiffre entre pods. Refusé avec tls. Défaut false.

Type: boolean
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.tenant`

Bornes de tous les appareils d'un tenant ensemble.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.tenant.bytes_per_second`

Octets de charge des PUBLISH de tous les appareils d'un tenant par seconde, sous contre-pression. 0 : aucune borne. Défaut 20 Mio.

Type: integer | string
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.tenant.messages_per_second`

PUBLISH de tous les appareils d'un tenant par seconde, sous contre-pression. 0 : aucune borne. Défaut 5000.

Type: number
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.tenant.quota`

Nomme une politique de type quota : le budget jour et mois de PUBLISH du tenant, partagé avec HTTP sous ce nom. Épuisé : PUBACK 0x97, QoS 0 jeté et compté, 3.1.1 fermé. Absent : aucun.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.tls`

Certificat de l'écouteur et, avec client_ca_file, l'autorité qui vérifie les certificats d'appareil (exigée par une alternative X509). Obligatoire sauf mesh_only. Lu une seule fois au démarrage.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.tls.cert_file`

Chemin du certificat de l'écouteur (PEM).

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.tls.client_ca_file`

Chemin de l'autorité qui vérifie les certificats d'appareil ; absent : aucun certificat d'appareil vérifié.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.tls.key_file`

Chemin de la clé privée de l'écouteur (PEM).

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.topic_alias_maximum`

Alias de topic qu'un appareil MQTT 5 peut employer vers l'écouteur ; un alias n'est retenu qu'une fois son topic accordé, jamais relayé. 0 : aucun. Au plus 1000, défaut 10.

Type: integer
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.websocket`

MQTT sur WebSocket (sous-protocole mqtt) sur une adresse à lui, avec le TLS de l'écouteur. Lu une seule fois au démarrage.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.websocket.address`

Adresse hôte:port de l'écouteur WebSocket (:8884), pas celle de l'écouteur.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`listeners.mqtt.websocket.path`

Chemin HTTP du WebSocket ; défaut /mqtt.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`observability`

Traces, journaux et mesures de la passerelle. Sans collecteur, la passerelle démarre quand même : c'est une configuration valide, pas un mode dégradé ; /metrics reste servi.

Type: object
Depuis: 0.2.0
Rechargement: à chaud

`observability.access_log`

Écrit une ligne par requête terminée, avec le gabarit du chemin - jamais le chemin reçu. Défaut false.

Type: boolean
Depuis: 1.0.0
Rechargement: à chaud

`observability.kafka`

Mesures de l'écouteur Kafka au-delà de ses instruments fixes.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`observability.kafka.budget_wait_buckets`redémarrage

Bornes de l'histogramme flexway.kafka.tenant_budget.wait (attente d'un tenant pour sa part d'octets en vol) : durées strictement croissantes et positives, 20 au plus ; défaut de 1 ms à 30 s. Lues une seule fois au démarrage.

Type: list<string>
Défaut: ["1ms","5ms","10ms","50ms","100ms","500ms","1s","5s","10s","30s"]
Bornes: éléments ≤ 20
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: redémarrage nécessaire

`observability.kafka.closures`

Compte les fermetures normales de connexions Kafka (flexway.kafka.connections.closed). Défaut true.

Type: boolean
Défaut: true
Depuis: 1.6.0
Rechargement: à chaud

`observability.log_level`

Niveau le moins grave écrit dans les journaux : debug, info (défaut), warn, error ou fatal. Se change à chaud, par exemple debug le temps d'un diagnostic.

Type: string
Valeurs admises: debuginfowarnerrorfatal
Défaut: info
Depuis: 1.1.0
Rechargement: à chaud

`observability.mqtt`

Mesures de l'écouteur MQTT des appareils au-delà de ses instruments fixes.

Type: object
Depuis: 0.2.0
Rechargement: à chaud

`observability.mqtt.closures`

Compte les fermetures normales de connexions d'appareils (flexway.mqtt.connections.closed). Défaut true.

Type: boolean
Depuis: 0.2.0
Rechargement: à chaud

`observability.otlp_endpoint`redémarrage

Collecteur OTLP des traces (hôte:port, par exemple tempo.observ:4317) ; prime sur OTEL_EXPORTER_OTLP_ENDPOINT. Vide : aucun export de traces. Lu une seule fois au démarrage.

Type: string
Depuis: 0.2.0
Rechargement: redémarrage nécessaire

`observability.sampling`redémarrage

Plafond d'échantillonnage des traces. Absent : toutes les traces sont gardées. Lu une seule fois au démarrage.

Type: object
Depuis: 1.0.0
Rechargement: redémarrage nécessaire

`observability.sampling.max_per_second`redémarrage

Nouvelles traces racines gardées par seconde et par réplique, nombre positif ; 0 : sans plafond.

Type: number
Bornes: valeur ≥ 0
Depuis: 1.0.0
Rechargement: redémarrage nécessaire

`observability.sparkplug`

Table des nœuds Sparkplug B que chaque réplique tient pour les nœuds qui la traversent (GET /sparkplug/nodes, écran Appareils de la console). Se change à chaud.

Type: object
Depuis: 0.2.0
Rechargement: à chaud

`observability.sparkplug.max_devices_per_node`

Appareils (DBIRTH, DDEATH) gardés pour un nœud, de 1 à 10000 ; au-delà, la liste est dite tronquée. Défaut 1000.

Type: integer
Défaut: 1000
Depuis: 0.2.0
Rechargement: à chaud

`observability.sparkplug.max_nodes`

Nœuds et applications hôtes gardés par réplique, de 1 à 50000 (un nœud est une connexion). Pleine, la table oublie d'abord un nœud inconnu, puis le plus ancien hors ligne ; pleine de nœuds en ligne, un nouveau n'est pas gardé et il est compté. Défaut 10000.

Type: integer
Défaut: 10000
Depuis: 0.2.0
Rechargement: à chaud

`observability.sparkplug.max_nodes_per_tenant`

Nœuds d'un même tenant gardés par réplique, de 1 à max_nodes : un tenant ne remplit jamais la table des autres ; à sa borne, la table oublie d'abord un de ses nœuds inconnus, puis le plus ancien hors ligne ; plein de nœuds en ligne, un nouveau n'est pas gardé et il est compté. Défaut 1000 (ou max_nodes s'il est plus bas).

Type: integer
Défaut: 1000
Depuis: 0.2.0
Rechargement: à chaud

`observability.sparkplug.offline_retention`

Durée pendant laquelle un nœud hors ligne, rattaché à une autre réplique ou seulement vu par ses commandes reste dans la table, de 1m à 720h. Défaut 24h.

Type: string
Défaut: 24h
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 0.2.0
Rechargement: à chaud

`policies`

Le modèle de politiques : des définitions nommées et réutilisables, attachées par des chaînes. Chaîne effective global -> hôte -> routes -> opération ; l'opération ajoute la sienne par x-flexway-policies au contrat.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`policies.chains`

Attache les politiques, du plus large au plus précis : global, par hôte, par motif de route. Un nom préfixé de ! retire une politique qu'un niveau plus large a apportée.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`policies.chains.global`

Politiques appliquées à toute requête, par nom de définition.

Type: list<string>
Depuis: 0.1.0
Rechargement: à chaud

`policies.chains.hosts`

Politiques par hôte : nom d'hôte -> liste de noms de définitions.

Type: map<list<string>>
Depuis: 0.1.0
Rechargement: à chaud

`policies.chains.routes`

Politiques par motif de route : un gabarit de chemin commençant par /, où * vaut un segment et ** plusieurs ("/orders/**") -> liste de noms de définitions.

Type: map<list<string>>
Depuis: 0.1.0
Rechargement: à chaud

`policies.definitions`

Les politiques nommées : nom -> définition (type, phase, when, config). Seules les politiques attachées par une chaîne ou par x-flexway-policies s'appliquent.

Type: map<object>
Depuis: 0.1.0
Rechargement: à chaud

`policies.definitions.*.config`

Configuration propre au type, décodée strictement contre le schéma de ce type (voir les types de politiques) : une clé inconnue est refusée.

Type: any
Depuis: 0.1.0
Rechargement: à chaud

`policies.definitions.*.phase`

Moment où la politique agit : request, response ou error, parmi les phases que son type accepte. Absente : la première phase du type.

Type: string
Valeurs admises: requestresponseerror
Depuis: 0.1.0
Rechargement: à chaud

`policies.definitions.*.type`obligatoire

Type de la politique, dans le catalogue : cors, rate-limit, quota, cache, header-inject, header-remove, rewrite-path, query-inject, query-remove, transform-body, redact, map-status, external-call. Obligatoire.

Type: string
Valeurs admises: cachecorsexternal-callheader-injectheader-removemap-statusquery-injectquery-removequotarate-limitredactrewrite-pathtransform-body
Depuis: 0.1.0
Rechargement: à chaud

`policies.definitions.*.when`

Condition CEL compilée au chargement (has(auth.subject)) : la politique ne s'applique que si elle est vraie. Refusée pour cors, rate-limit et quota, qu'on attache plutôt là où ils s'appliquent.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`policies.fragments`

Fragments de politique importés (1.7.0) : nom d'import -> fichier épinglé par son empreinte. Les définitions d'un fragment s'appellent ici <import>/<nom> ; celles qu'il impose passent en tête de chaque chaîne de l'écouteur HTTP, avant global, et ne se retirent, ne se remplacent ni ne se défont localement. Lu de fichiers montés seulement, jamais du réseau ; ancres, alias et clés de fusion YAML refusés ici. Absent : aucun fragment, comportement de 1.6.0. Le nom d'import : lettres minuscules, chiffres et -, 63 au plus.

Type: map<object>
Depuis: 1.7.0
Rechargement: à chaud

`policies.fragments.*.digest`obligatoire

Empreinte qui épingle le fichier : sha256: suivi des 64 caractères hexadécimaux du sha256 de ses octets, sans forme canonique - la valeur de sha256sum et de flexway fragment digest. Obligatoire. Différente de l'empreinte lue : refus qui nomme l'import, l'attendue et la lue.

Type: string
Motif: ^sha256:[0-9a-f]{64}$
Depuis: 1.7.0
Rechargement: à chaud

`policies.fragments.*.path`obligatoire

Fichier du fragment (kind: PolicyFragment), relatif au flexway.yaml, dans son répertoire ou en dessous (.. et chemin absolu hors de ce répertoire refusés) ; un fichier ordinaire de 1 Mio au plus. Obligatoire. Relu à chaque rechargement : un fichier absent ou changé sans son empreinte refuse le chargement, et la configuration en cours reste.

Type: string
Depuis: 1.7.0
Rechargement: à chaud

`policies.fragments.*.verify`

Réservé à la vérification d'une signature du fragment, qui n'est pas construite dans cette version : déclarée, elle refuse le chargement plutôt que d'être ignorée. L'empreinte seule épingle le fichier.

Type: object
Depuis: 1.7.0
Rechargement: à chaud

`policies.fragments.*.verify.bundle`

Réservé : le paquet de signature du fragment. Non construit dans cette version - refusé au chargement.

Type: string
Depuis: 1.7.0
Rechargement: à chaud

`policies.fragments.*.verify.key`

Réservé : la clé publique qui vérifie la signature. Non construit dans cette version - refusé au chargement.

Type: string
Depuis: 1.7.0
Rechargement: à chaud

`schema_registry`

Le registre de schémas sous lequel sont lues les charges binaires : l'API de Confluent, que servent Confluent, Apicurio, Karapace et Redpanda. Lu, jamais écrit. Absent : un message qui déclare le format filaire du registre est refusé au chargement.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`schema_registry.auth`

Authentification de la passerelle au registre : username et password (HTTP Basic, la clé et le secret de Confluent Cloud), ou token - pas les deux. Refusée si url est en http://.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`schema_registry.auth.password`secret

Mot de passe par référence, ${VAR} ou file:/chemin, relu à chaque requête ; va avec username.

Type: string
Motif: ^(\$\{[A-Za-z_][A-Za-z0-9_]*\}|file:/\S+)$
Secret: une référence, ${VAR} ou file:/chemin, jamais une valeur en clair
Depuis: 1.6.0
Rechargement: à chaud

`schema_registry.auth.token`secret

Jeton porteur par référence, ${VAR} ou file:/chemin ; exclusif de username et password.

Type: string
Motif: ^(\$\{[A-Za-z_][A-Za-z0-9_]*\}|file:/\S+)$
Secret: une référence, ${VAR} ou file:/chemin, jamais une valeur en clair
Depuis: 1.6.0
Rechargement: à chaud

`schema_registry.auth.username`

Nom d'utilisateur HTTP Basic ; va avec password.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`schema_registry.circuit_breaker`

Coupe-circuit du registre, comme celui d'un amont : ouvert, un message qui a besoin du registre est refusé aussitôt (503), jamais attendu. Actif par défaut.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`schema_registry.circuit_breaker.cooldown`

Repos du coupe-circuit ouvert avant un appel d'essai ; défaut 5s.

Type: string
Défaut: 5s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`schema_registry.circuit_breaker.failure_ratio`

Part d'échecs qui ouvre le coupe-circuit, dans (0, 1] ; défaut 0.5.

Type: number
Défaut: 0.5
Bornes: valeur ≥ 0, ≤ 1
Depuis: 1.6.0
Rechargement: à chaud

`schema_registry.circuit_breaker.min_requests`

Appels minimum dans la fenêtre avant que la part d'échecs compte ; défaut 20.

Type: integer
Défaut: 20
Depuis: 1.6.0
Rechargement: à chaud

`schema_registry.circuit_breaker.window`

Fenêtre glissante sur laquelle la part d'échecs est mesurée ; défaut 10s.

Type: string
Défaut: 10s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`schema_registry.max_schemas`

Schémas gardés en mémoire, par identifiant, compilés une fois chacun ; de 1 à 100000, défaut 1000.

Type: integer
Défaut: 1000
Bornes: valeur ≥ 1, ≤ 100000
Depuis: 1.6.0
Rechargement: à chaud

`schema_registry.timeout`

Délai d'une recherche au registre, qui retient le message qui en a besoin ; plus de 0 et 30s au plus, défaut 2s.

Type: string
Défaut: 2s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.6.0
Rechargement: à chaud

`schema_registry.tls`

TLS client vers le registre ; seulement avec une url en https://.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`schema_registry.tls.ca_file`

Fichier PEM de l'autorité qui vérifie le certificat du serveur ; absent : les autorités du système. Le fichier doit exister.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`schema_registry.tls.cert_file`

Certificat client PEM présenté au registre ; va avec key_file. Le fichier doit exister.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`schema_registry.tls.key_file`

Clé privée PEM du certificat client ; va avec cert_file. Le fichier doit exister.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`schema_registry.tls.server_name`

Nom attendu dans le certificat du registre, quand il diffère de l'hôte de url.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`schema_registry.url`obligatoire

Adresse de base absolue du registre en http(s)://, sans identifiants, paramètres ni fragment (https://registry.internal:8081) ; obligatoire. En http://, ni tls ni auth.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`server`

Comportement de la passerelle face à ses amonts et à l'arrêt, indépendamment de toute opération. Chaque clé a un défaut : une section server: vide est valide.

Type: object
Depuis: 0.2.0
Rechargement: à chaud

`server.body`

Bornes des corps de réponse que lisent les politiques de corps (transform-body, redact, map-status), pour les seules opérations qui en déclarent.

Type: object
Depuis: 1.2.0
Rechargement: à chaud

`server.body.max_bytes`

Plus grand corps de réponse lu pour être transformé, taille (1MiB, 512KiB ou un nombre d'octets) ; défaut 1MiB. Au-delà : 502 response_too_large, jamais un corps tronqué ni non transformé.

Type: integer | string
Défaut: 1MiB
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.2.0
Rechargement: à chaud

`server.body.validate_sample`

Part des réponses transformées vérifiées contre le schéma du contrat, entre 0 et 1 ; défaut 0.01. Un écart est compté et journalisé, jamais servi en erreur ; 0 n'en vérifie aucune.

Type: number
Défaut: 0.01
Bornes: valeur ≥ 0, ≤ 1
Depuis: 1.2.0
Rechargement: à chaud

`server.cache`redémarrage

Bornes du cache de réponses des opérations qui en déclarent un. Ne tient rien tant qu'aucune opération ne déclare de cache. Lu une seule fois au démarrage.

Type: object
Depuis: 1.2.0
Rechargement: redémarrage nécessaire

`server.cache.max_bytes`redémarrage

Mémoire totale du cache par réplique, taille ; défaut 32MiB. Au-delà, la réponse la moins récemment servie est évincée.

Type: integer | string
Défaut: 32MiB
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.2.0
Rechargement: redémarrage nécessaire

`server.cache.max_entry_bytes`redémarrage

Plus grande réponse gardée, taille ; défaut 1MiB (au plus max_bytes). Une réponse plus grande est relayée, jamais gardée.

Type: integer | string
Défaut: 1MiB
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 1.2.0
Rechargement: redémarrage nécessaire

`server.counters`redémarrage

Partage des débits et des quotas entre répliques par un cache partagé compatible Redis (Redis, Dragonfly ou Valkey), avec réconciliation périodique. Absent : chaque compteur est local à sa réplique, et aucun quota ne peut être déclaré. Lu une seule fois au démarrage.

Type: object
Depuis: 1.0.0
Rechargement: redémarrage nécessaire

`server.counters.prefix`redémarrage

Préfixe des clés de ce déploiement dans le cache partagé : lettres, chiffres et tirets ; défaut flexway. Deux déploiements qui partagent un cache compteraient sinon ensemble.

Type: string
Défaut: flexway
Depuis: 1.0.0
Rechargement: redémarrage nécessaire

`server.counters.store`obligatoireredémarrage

Adresse du cache partagé : redis://hôte:port ou rediss://, sans mot de passe, ou une référence (${VAR}, file:/chemin) quand elle en porte un. Obligatoire.

Type: string
Depuis: 1.0.0
Rechargement: redémarrage nécessaire

`server.counters.sync`redémarrage

Période de réconciliation avec le cache partagé, entre 100ms et 1m ; défaut 1s. C'est la fenêtre dont une limite partagée peut être dépassée.

Type: string
Défaut: 1s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.0.0
Rechargement: redémarrage nécessaire

`server.in_flight`redémarrage

Porte devant le plan de données : requêtes traitées à la fois, attente d'une place, connexions ouvertes ; au-delà, 503 aussitôt. Absente : dérivée de la limite mémoire du conteneur quand il en a une. Lue une seule fois au démarrage.

Type: object
Depuis: 1.1.0
Rechargement: redémarrage nécessaire

`server.in_flight.connections`redémarrage

Connexions clientes ouvertes à la fois, par écouteur ; au-delà, une nouvelle attend dans la file du noyau. 0 : sans plafond. Absente : dérivée de la limite mémoire (25 % de la mémoire / 32 KiB).

Type: integer
Bornes: valeur ≥ 0
Depuis: 1.1.0
Rechargement: redémarrage nécessaire

`server.in_flight.max`redémarrage

Requêtes en vol à la fois, flux compris. 0 : sans plafond. Absente : dérivée de la limite mémoire (50 % de la mémoire / 128 KiB, 64 au moins), adaptée à la saturation.

Type: integer
Bornes: valeur ≥ 0
Depuis: 1.1.0
Rechargement: redémarrage nécessaire

`server.in_flight.queue`redémarrage

Requêtes qui peuvent attendre une place ; défaut 0 (refus immédiat). Exige wait, et une limite max non nulle.

Type: integer
Bornes: valeur ≥ 0
Depuis: 1.1.0
Rechargement: redémarrage nécessaire

`server.in_flight.wait`redémarrage

Attente au plus d'une requête en file, 10s au plus. Exigée avec queue, refusée sans elle.

Type: string
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.1.0
Rechargement: redémarrage nécessaire

`server.limits`

Ce qu'une requête peut faire tenir à la passerelle.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`server.limits.max_body`

Plus grand corps de requête lu - il n'est lu que pour être validé contre le contrat ; taille, défaut 1MiB. Au-delà : 413. Un corps seulement relayé n'est jamais retenu, quelle que soit sa taille.

Type: integer | string
Défaut: 1MiB
Bornes: valeur ≥ 1
Motif: ^\s*[1-9][0-9]*\s*(B|KiB|MiB|GiB)?\s*$
Depuis: 0.1.0
Rechargement: à chaud

`server.peer_identity_header`

En-tête où un proxy de maillage local écrit l'identité vérifiée du pair (Linkerd : l5d-client-id), crue des seuls pairs de trusted_proxies (obligatoire avec lui). Déclare un maillage ; incompatible avec auth.trusted_headers.

Type: string
Depuis: 1.0.0
Rechargement: à chaud

`server.reload`redémarrage

Comment la passerelle voit une configuration changée. Lu une seule fois au démarrage.

Type: object
Depuis: 0.1.0
Rechargement: redémarrage nécessaire

`server.reload.interval`redémarrage

Intervalle de relecture de la configuration et de ses contrats, comparés par contenu ; défaut 5s. "0s" : jamais, seul SIGHUP recharge.

Type: string
Défaut: 5s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 0.1.0
Rechargement: redémarrage nécessaire

`server.shedding`redémarrage

Délestage d'une part du trafic pendant que la passerelle elle-même sature. Absent : rien n'est délesté. Lu une seule fois au démarrage.

Type: object
Depuis: 1.0.0
Rechargement: redémarrage nécessaire

`server.shedding.target`obligatoireredémarrage

Saturation au-delà de laquelle la passerelle déleste : 99e centile de la latence d'ordonnancement Go (attente d'un processeur par une goroutine prête), entre 1ms et 1s. Les opérations x-flexway-priority: critical ne sont jamais délestées.

Type: string
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.0.0
Rechargement: redémarrage nécessaire

`server.shutdown`redémarrage

Ce qui se passe entre SIGTERM et la sortie. Lu une seule fois au démarrage.

Type: object
Depuis: 0.2.0
Rechargement: redémarrage nécessaire

`server.shutdown.drain`redémarrage

Temps laissé aux requêtes et flux en cours pour finir une fois les nouvelles refusées ; défaut 20s. Au-delà, les connexions restantes sont fermées et c'est journalisé.

Type: string
Défaut: 20s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 0.2.0
Rechargement: redémarrage nécessaire

`server.shutdown.mqtt_drain_spread`redémarrage

Étale les redirections des appareils de l'écouteur MQTT sur l'arrêt, sans tempête de reconnexions sur les autres répliques ; plafonné à la moitié de drain. De 0s à 10m, défaut 30s.

Type: string
Défaut: 30s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 0.2.0
Rechargement: redémarrage nécessaire

`server.timeouts`

Budgets d'un échange relayé, par couches. Il n'y a volontairement pas de délai global unique.

Type: object
Depuis: 0.2.0
Rechargement: à chaud

`server.timeouts.connect`

Délai d'établissement d'une connexion vers un amont, poignée de main TLS comprise. Durée (5s, 500ms) ; défaut 5s.

Type: string
Défaut: 5s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 0.2.0
Rechargement: à chaud

`server.timeouts.read`

Silence toléré entre deux octets d'une réponse amont ; c'est lui seul qui gouverne un flux. Défaut 60s.

Type: string
Défaut: 1m
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 0.2.0
Rechargement: à chaud

`server.timeouts.total`

Budget de l'échange entier, reprises comprises ; une réponse en flux en est exemptée. Défaut 30s. Surchargé par upstreams.*.timeout, puis par x-flexway-timeout.

Type: string
Défaut: 30s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 0.2.0
Rechargement: à chaud

`server.tls`redémarrage

La passerelle termine TLS elle-même, sur un écouteur à part, et demande un certificat client, vérifié contre client_ca_file s'il est présenté. Lu une seule fois au démarrage ; les fichiers sont relus à leur rotation.

Type: object
Depuis: 0.1.0
Rechargement: redémarrage nécessaire

`server.tls.cert_file`obligatoireredémarrage

Chemin du certificat de l'écouteur TLS (PEM). Obligatoire.

Type: string
Depuis: 0.1.0
Rechargement: redémarrage nécessaire

`server.tls.client_ca_file`redémarrage

Chemin de l'autorité (PEM) qui vérifie les certificats clients présentés. Absent : aucun certificat client vérifié.

Type: string
Depuis: 0.1.0
Rechargement: redémarrage nécessaire

`server.tls.key_file`obligatoireredémarrage

Chemin de la clé privée de l'écouteur TLS (PEM). Obligatoire.

Type: string
Depuis: 0.1.0
Rechargement: redémarrage nécessaire

`server.trusted_proxies`

Pairs (CIDR, par exemple 10.0.0.0/8) dont X-Forwarded-For est cru - l'edge ; venant de tout autre, l'en-tête est ignoré. local désigne les adresses propres du pod (un proxy de maillage). Aucun par défaut.

Type: list<string>
Depuis: 0.1.0
Rechargement: à chaud

`upstreams`

Les amonts, par nom : où les opérations déclarées sont relayées, et les courtiers et cibles webhook du plan asynchrone. Au moins un ; le nom ai est réservé à la surface d'inférence.

Type: map<object>
Depuis: 0.1.0
Rechargement: à chaud

`upstreams.*.allow_private`

Webhook seulement : ouvre les plages d'adresses privées à la garde de connexion (et http://), refusées par défaut. Défaut false.

Type: boolean
Depuis: 1.5.0
Rechargement: à chaud

`upstreams.*.amqp1`

AMQP 1.0 seulement (protocol: amqp, protocol_version: "1.0") : ce que fait le courtier au-delà du standard.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`upstreams.*.amqp1.broker`

Courtier AMQP 1.0 : rabbitmq, artemis, solace, servicebus ou generic (défaut). Il dit comment un flux lit un canal sans prendre les messages des autres consommateurs ; servicebus et generic publient et livrent par webhook seulement.

Type: string
Valeurs admises: rabbitmqartemissolaceservicebusgeneric
Défaut: generic
Depuis: 1.6.0
Rechargement: à chaud

`upstreams.*.brokers`

Courtiers seulement (kafka, amqp, mqtt, nats), obligatoire : adresses d'amorçage. Kafka : hôte:port ; AMQP et MQTT : URL amqp:// ou amqps://, mqtt:// ou mqtts:// ; NATS : nats:// ou tls://. Jamais d'identifiant dans l'adresse.

Type: list<string>
Depuis: 1.5.0
Rechargement: à chaud

`upstreams.*.circuit_breaker`

Coupe-circuit de l'amont, toujours actif : il s'ouvre quand trop d'appels échouent, refuse aussitôt pendant le repos, puis laisse passer un appel d'essai. Chaque clé a un défaut.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`upstreams.*.circuit_breaker.cooldown`

Repos du coupe-circuit ouvert avant l'appel d'essai ; défaut 5s.

Type: string
Défaut: 5s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 0.1.0
Rechargement: à chaud

`upstreams.*.circuit_breaker.failure_ratio`

Part d'appels en échec qui ouvre le coupe-circuit, dans ]0, 1] ; défaut 0.5.

Type: number
Défaut: 0.5
Bornes: valeur ≥ 0, ≤ 1
Depuis: 0.1.0
Rechargement: à chaud

`upstreams.*.circuit_breaker.min_requests`

Nombre minimal d'appels dans la fenêtre avant de juger le ratio ; défaut 20.

Type: integer
Défaut: 20
Bornes: valeur ≥ 1
Depuis: 0.1.0
Rechargement: à chaud

`upstreams.*.circuit_breaker.window`

Fenêtre glissante sur laquelle les échecs sont comptés ; défaut 10s.

Type: string
Défaut: 10s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 0.1.0
Rechargement: à chaud

`upstreams.*.max_in_flight`

Requêtes relayées à la fois vers cet amont ; au-delà, 503 aussitôt (cloisonnement). 0 : sans plafond. Pour un courtier, borne les publications en attente d'accusé, 1024 par défaut.

Type: integer
Bornes: valeur ≥ 0
Depuis: 0.1.0
Rechargement: à chaud

`upstreams.*.nats`

NATS seulement : identité de la passerelle et JetStream. Une seule identité au plus - credentials, nkey_seed ou token, ou sasl PLAIN ; sans aucune, une connexion anonyme n'est admise qu'avec un certificat client ou dans un maillage déclaré.

Type: object
Depuis: 1.6.0
Rechargement: à chaud

`upstreams.*.nats.credentials`secret

Fichier d'identifiants NATS (JWT et graine nkey), par référence (${VAR} ou file:/chemin).

Type: string
Motif: ^(\$\{[A-Za-z_][A-Za-z0-9_]*\}|file:/\S+)$
Secret: une référence, ${VAR} ou file:/chemin, jamais une valeur en clair
Depuis: 1.6.0
Rechargement: à chaud

`upstreams.*.nats.domain`

Domaine JetStream (super-grappe, nœud feuille), facultatif : un seul jeton, sans point, espace, * ni >. Sans effet avec jetstream: false, donc refusé.

Type: string
Depuis: 1.6.0
Rechargement: à chaud

`upstreams.*.nats.jetstream`

Publier et consommer par JetStream (publication accusée par un flux) ; défaut true. false : NATS Core, lu en server-sent events seulement, jamais publié.

Type: boolean
Défaut: true
Depuis: 1.6.0
Rechargement: à chaud

`upstreams.*.nats.nkey_seed`secret

Graine nkey seule, par référence (${VAR} ou file:/chemin).

Type: string
Motif: ^(\$\{[A-Za-z_][A-Za-z0-9_]*\}|file:/\S+)$
Secret: une référence, ${VAR} ou file:/chemin, jamais une valeur en clair
Depuis: 1.6.0
Rechargement: à chaud

`upstreams.*.nats.token`secret

Jeton NATS, par référence ; il est envoyé tel quel, d'où TLS obligatoire (tls ou un courtier tls://).

Type: string
Motif: ^(\$\{[A-Za-z_][A-Za-z0-9_]*\}|file:/\S+)$
Secret: une référence, ${VAR} ou file:/chemin, jamais une valeur en clair
Depuis: 1.6.0
Rechargement: à chaud

`upstreams.*.pool`

Connexions gardées vers cet amont. Sans objet pour un courtier ou un webhook, qui gardent leurs propres connexions.

Type: object
Depuis: 0.2.0
Rechargement: à chaud

`upstreams.*.pool.idle_timeout`

Durée de vie d'une connexion inactive avant sa fermeture ; défaut 90s.

Type: string
Défaut: 1m30s
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 0.2.0
Rechargement: à chaud

`upstreams.*.pool.max_conns`

Connexions ouvertes à la fois vers l'amont ; 0 (défaut) : sans plafond. Un plafond transforme un ralentissement en file à la passerelle plutôt qu'en tempête de connexions.

Type: integer
Bornes: valeur ≥ 0
Depuis: 0.2.0
Rechargement: à chaud

`upstreams.*.pool.max_idle`

Connexions inactives gardées pour réutilisation ; défaut 100. 0 ou absent : le défaut - désactiver la réutilisation n'est pas offert.

Type: integer
Défaut: 100
Depuis: 0.2.0
Rechargement: à chaud

`upstreams.*.protocol`

Protocole de l'amont : http (défaut, https:// compris), grpc (HTTP/2, h2c en clair dans un maillage), mcp (serveur MCP fédéré), a2a (agent A2A, token_exchange obligatoire), kafka, amqp, mqtt, nats (courtiers) ou webhook (cible de livraison).

Type: string
Valeurs admises: httpgrpcmcpa2akafkaamqpmqttnatswebhook
Défaut: http
Depuis: 0.1.0
Rechargement: à chaud

`upstreams.*.protocol_version`

Version du protocole, AMQP et MQTT seulement : MQTT 5 (défaut) ou 3.1.1 ; AMQP 0-9-1 (défaut) ou 1.0. Kafka et NATS négocient leur version : clé refusée.

Type: string
Valeurs admises: 53.1.10-9-11.0
Depuis: 1.5.0
Rechargement: à chaud

`upstreams.*.retries`

Webhook seulement : réessais bornés d'une livraison.

Type: object
Depuis: 1.5.0
Rechargement: à chaud

`upstreams.*.retries.max`

Réessais au plus d'une livraison, de 0 à 20 ; défaut 8.

Type: integer
Défaut: 8
Bornes: valeur ≥ 0, ≤ 20
Depuis: 1.5.0
Rechargement: à chaud

`upstreams.*.retries.max_delay`

Délai au plus entre deux tentatives ; défaut 10m.

Type: string
Défaut: 10m
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.5.0
Rechargement: à chaud

`upstreams.*.sasl`

Courtiers seulement : comment la passerelle s'authentifie auprès du courtier - sa propre identité, jamais celle d'un appelant.

Type: object
Depuis: 1.5.0
Rechargement: à chaud

`upstreams.*.sasl.mechanism`obligatoire

Mécanisme SASL : Kafka PLAIN, SCRAM-SHA-256 ou SCRAM-SHA-512 ; AMQP 0-9-1, MQTT et NATS PLAIN ; AMQP 1.0 PLAIN, ANONYMOUS (avec certificat client ou dans un maillage) ou EXTERNAL (le certificat client comme identité). PLAIN seulement sur TLS.

Type: string
Valeurs admises: PLAINSCRAM-SHA-256SCRAM-SHA-512ANONYMOUSEXTERNAL
Depuis: 1.5.0
Rechargement: à chaud

`upstreams.*.sasl.password`secret

Mot de passe, par référence (${VAR} ou file:/chemin). Absent avec ANONYMOUS et EXTERNAL.

Type: string
Motif: ^(\$\{[A-Za-z_][A-Za-z0-9_]*\}|file:/\S+)$
Secret: une référence, ${VAR} ou file:/chemin, jamais une valeur en clair
Depuis: 1.5.0
Rechargement: à chaud

`upstreams.*.sasl.username`

Nom d'utilisateur de la passerelle auprès du courtier. Absent avec ANONYMOUS et EXTERNAL.

Type: string
Depuis: 1.5.0
Rechargement: à chaud

`upstreams.*.secrets`

Webhook seulement : secrets de signature (Standard Webhooks), par référence - un seul, ou deux pendant une rotation.

Type: list<string>
Bornes: éléments ≤ 2
Motif: ^(\$\{[A-Za-z_][A-Za-z0-9_]*\}|file:/\S+)$
Depuis: 1.5.0
Rechargement: à chaud

`upstreams.*.timeout`

Budget total d'un échange avec cet amont (3s), jamais un compte de nanosecondes. Surcharge server.timeouts.total, surchargé à son tour par x-flexway-timeout. Pour un courtier : budget d'une publication, accusé compris.

Type: string
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 0.2.0
Rechargement: à chaud

`upstreams.*.tls`

TLS client vers l'amont hors maillage : autorité, certificat client, nom attendu. Seulement avec une URL https:// (ou un courtier TLS) ; dans un maillage, le sidecar fait le mTLS et l'URL reste http://. Pas de certificat client vers un webhook.

Type: object
Depuis: 0.3.0
Rechargement: à chaud

`upstreams.*.tls.ca_file`

Chemin de l'autorité (PEM) qui vérifie le certificat de l'amont. Absent : les autorités du système.

Type: string
Depuis: 0.3.0
Rechargement: à chaud

`upstreams.*.tls.cert_file`

Chemin du certificat client (PEM) présenté à l'amont ; va avec key_file.

Type: string
Depuis: 0.3.0
Rechargement: à chaud

`upstreams.*.tls.key_file`

Chemin de la clé privée du certificat client (PEM) ; va avec cert_file.

Type: string
Depuis: 0.3.0
Rechargement: à chaud

`upstreams.*.tls.server_name`

Nom attendu dans le certificat de l'amont (SNI), quand il diffère de l'hôte de l'URL.

Type: string
Depuis: 0.3.0
Rechargement: à chaud

`upstreams.*.token_exchange`

Cet amont reçoit un jeton émis pour lui au nom de l'appelant (RFC 8693), à chaque appel, REST et MCP, jamais celui de l'appelant ni de repli. Exige un client chez l'émetteur de l'appelant. Refusé pour un courtier ou un webhook.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`upstreams.*.token_exchange.audience`obligatoire

Audience pour laquelle l'amont attend un jeton (orders-api). Obligatoire.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`upstreams.*.token_exchange.scope`

Portées qui restreignent le jeton échangé ; vide : laissé au fournisseur.

Type: list<string>
Depuis: 0.1.0
Rechargement: à chaud

`upstreams.*.url`

Adresse de l'amont : URL http(s) absolue (http://orders.internal:8080), obligatoire sauf pour un courtier, qui se joint par brokers. Webhook : URL https:// nommée par un hôte, jamais une adresse IP, sans identifiant.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`version`obligatoire

Version du schéma du fichier : 1, seule valeur admise. Obligatoire.

Type: integer
Valeurs admises: 1
Depuis: 0.1.0
Rechargement: à chaud

60 clés

Types de politiques

La config d'une politique déclarée sous policies.definitions suit son type : une rubrique par type, décodée strictement (une clé inconnue est refusée).

`policy.cache`

Politique de cache de réponses publiques, déclarée sous policies.definitions avec type: cache et attachée par une chaîne ; consultée à la phase request. Ne vaut que pour GET et HEAD ; sa condition when est gardée (par exemple !has(auth.subject)). Un cache authentifié se déclare par l'opération (x-flexway-cache), jamais par une politique.

Type: object
Depuis: 1.2.0
Rechargement: à chaud

`policy.cache.scope`

Portée du cache : public seulement (défaut). subject est refusé ici : il se déclare dans x-flexway-cache de l'opération.

Type: string
Valeurs admises: public
Défaut: public
Depuis: 1.2.0
Rechargement: à chaud

`policy.cache.ttl`obligatoire

Durée de conservation d'une réponse, durée positive (60s) ; obligatoire.

Type: string
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.2.0
Rechargement: à chaud

`policy.cors`

Politique CORS, déclarée sous policies.definitions avec type: cors, attachée globalement, par hôte, par route ou par opération ; phase request, sans condition when. Fermée par défaut : une origine non listée est refusée.

Type: object
Depuis: 0.3.0
Rechargement: à chaud

`policy.cors.allow_credentials`

Autorise les requêtes du navigateur avec identifiants (Access-Control-Allow-Credentials). Défaut false ; refusé avec l'origine *.

Type: boolean
Depuis: 0.3.0
Rechargement: à chaud

`policy.cors.allow_headers`

En-têtes de requête autorisés en plus de ceux que l'opération déclare. Vide : la liste blanche de l'opération seule.

Type: list<string>
Depuis: 0.3.0
Rechargement: à chaud

`policy.cors.allow_methods`

Méthodes annoncées en réponse au préliminaire. Vide : les méthodes que le contrat déclare pour le chemin.

Type: list<string>
Depuis: 0.3.0
Rechargement: à chaud

`policy.cors.allow_origins`obligatoire

Origines autorisées (https://app.example.com), au moins une ; * admet toute origine mais jamais avec allow_credentials.

Type: list<string>
Bornes: éléments ≥ 1
Depuis: 0.3.0
Rechargement: à chaud

`policy.cors.expose_headers`

En-têtes de réponse que le navigateur laisse lire au script (Access-Control-Expose-Headers).

Type: list<string>
Depuis: 0.3.0
Rechargement: à chaud

`policy.cors.max_age`

Durée pendant laquelle le navigateur garde la réponse au préliminaire (Access-Control-Max-Age), durée positive (10m) ; absente : en-tête non envoyé.

Type: string
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 0.3.0
Rechargement: à chaud

`policy.external-call`

Appel à un service déclaré dont la réponse peut refuser la requête (deny) ou poser des en-têtes (set_headers), rien d'autre ; type: external-call sous policies.definitions, phase request (défaut, avant l'amont) ou response. Délai et on_failure obligatoires, le budget de l'opération est consommé ; une requête simulée n'appelle rien.

Type: object
Depuis: 1.2.0
Rechargement: à chaud

`policy.external-call.deny`

Refus de la requête quand une condition tient sur la réponse du service externe ; when, status et code tous obligatoires. Il faut au moins deny ou set_headers.

Type: object
Depuis: 1.2.0
Rechargement: à chaud

`policy.external-call.deny.code`obligatoire

Code d'erreur du problème servi, ^[a-z][a-z0-9_]{0,63}$ ; jamais un code propre à la passerelle (forbidden, rate_limited...).

Type: string
Motif: ^[a-z][a-z0-9_]{0,63}$
Depuis: 1.2.0
Rechargement: à chaud

`policy.external-call.deny.status`obligatoire

Statut du refus : un 4xx enregistré, hors 401, 405, 407 et 416.

Type: integer
Bornes: valeur ≥ 400, ≤ 499
Depuis: 1.2.0
Rechargement: à chaud

`policy.external-call.deny.when`obligatoire

Condition CEL sur response.status et response.body - la réponse du service externe, jamais celle de l'amont.

Type: string
Depuis: 1.2.0
Rechargement: à chaud

`policy.external-call.on_failure`obligatoire

Ce qui se passe sans réponse exploitable (délai, erreur, coupe-circuit) : fail-open continue comme si la politique ne s'appliquait pas, fail-closed refuse. Obligatoire, sans défaut.

Type: string
Valeurs admises: fail-openfail-closed
Depuis: 1.2.0
Rechargement: à chaud

`policy.external-call.path`obligatoire

Chemin appelé sur l'amont, littéral commençant par /, sans ?, #, {, } ni espace.

Type: string
Motif: ^/[^?#{} ]*$
Depuis: 1.2.0
Rechargement: à chaud

`policy.external-call.send`

Ce que l'appel envoie au service externe ; rien par défaut.

Type: object
Depuis: 1.2.0
Rechargement: à chaud

`policy.external-call.send.body`

Envoie le corps de la requête. Refusé à la phase response, où il est déjà relayé.

Type: boolean
Depuis: 1.2.0
Rechargement: à chaud

`policy.external-call.send.headers`

En-têtes de la requête préparée pour l'amont à transmettre (en-têtes déclarés, tenant écrit par la passerelle) ; 32 au plus. Jamais un en-tête non déclaré de l'appelant.

Type: list<string>
Bornes: éléments ≤ 32
Depuis: 1.2.0
Rechargement: à chaud

`policy.external-call.set_headers`

En-têtes posés à partir de la réponse externe : nom -> expression CEL sur response ; 32 au plus, valeur de 4 096 octets au plus (au-delà, l'appel a échoué). En-têtes protégés refusés.

Type: map<string>
Depuis: 1.2.0
Rechargement: à chaud

`policy.external-call.timeout`obligatoire

Délai de l'appel, durée positive (200ms) ; obligatoire. L'appel consomme aussi le budget de l'opération.

Type: string
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.2.0
Rechargement: à chaud

`policy.external-call.upstream`obligatoire

Amont appelé, déclaré dans upstreams, en HTTP et sans token_exchange ; obligatoire.

Type: string
Depuis: 1.2.0
Rechargement: à chaud

`policy.header-inject`

Pose ou renomme des en-têtes ; type: header-inject sous policies.definitions, phase request (défaut), response ou error, condition when possible. Les en-têtes protégés (identité, transfert, traçage, saut par saut, flexway-*, en-tête du tenant) sont refusés.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`policy.header-inject.on_missing`

Ce que fait un gabarit dont la valeur manque : skip (en-tête non posé), empty (posé vide) ou fail (requête refusée). Obligatoire dès qu'une valeur est une expression ; skip sinon.

Type: string
Valeurs admises: skipemptyfail
Depuis: 0.1.0
Rechargement: à chaud

`policy.header-inject.rename`

En-têtes renommés : ancien nom -> nouveau nom, valeurs gardées.

Type: map<string>
Depuis: 0.1.0
Rechargement: à chaud

`policy.header-inject.set`

En-têtes posés : nom -> valeur, littérale ou gabarit {{ expression CEL }} ({{ auth.claims.plan }}) ; une valeur existante est remplacée. Au moins set ou rename.

Type: map<string>
Depuis: 0.1.0
Rechargement: à chaud

`policy.header-remove`

Retire des en-têtes ; type: header-remove sous policies.definitions, phase request (défaut), response ou error. Les en-têtes protégés sont refusés.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`policy.header-remove.names`obligatoire

Noms des en-têtes retirés, au moins un.

Type: list<string>
Bornes: éléments ≥ 1
Depuis: 0.1.0
Rechargement: à chaud

`policy.map-status`

Change le statut d'une réponse de l'amont en statut sémantique ; type: map-status sous policies.definitions, phase response. Sa configuration est une liste de 1 à 64 règles { from, to, when, code }, la première qui s'applique gagne ; une règle après une règle sans condition de même from est refusée.

Type: list<object>
Bornes: éléments ≥ 1, ≤ 64
Depuis: 1.2.0
Rechargement: à chaud

`policy.map-status.*.code`

Code d'erreur du problème servi, seulement quand to est 400 ou plus ; ^[a-z][a-z0-9_]{0,63}$, jamais un code propre à la passerelle.

Type: string
Motif: ^[a-z][a-z0-9_]{0,63}$
Depuis: 1.2.0
Rechargement: à chaud

`policy.map-status.*.from`obligatoire

Statut de l'amont visé, de 200 à 599 ; obligatoire.

Type: integer
Bornes: valeur ≥ 200, ≤ 599
Depuis: 1.2.0
Rechargement: à chaud

`policy.map-status.*.to`obligatoire

Statut servi, obligatoire : 200 ou plus, avec une raison RFC 9110, différent de from, jamais un 3xx ni 204, 205, 206, 304, 401, 405, 407, 416 ou 426.

Type: integer
Bornes: valeur ≥ 200, ≤ 599
Depuis: 1.2.0
Rechargement: à chaud

`policy.map-status.*.when`

Condition CEL facultative, qui peut lire body, le corps JSON de la réponse.

Type: string
Depuis: 1.2.0
Rechargement: à chaud

`policy.query-inject`

Pose des paramètres de requête ; type: query-inject sous policies.definitions, phase request.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`policy.query-inject.on_missing`

Ce que fait un gabarit dont la valeur manque : skip, empty ou fail. Obligatoire dès qu'une valeur est une expression ; skip sinon.

Type: string
Valeurs admises: skipemptyfail
Depuis: 0.1.0
Rechargement: à chaud

`policy.query-inject.set`obligatoire

Paramètres posés : nom -> valeur, littérale ou gabarit {{ expression CEL }} ; au moins un.

Type: map<string>
Depuis: 0.1.0
Rechargement: à chaud

`policy.query-remove`

Retire des paramètres de requête ; type: query-remove sous policies.definitions, phase request.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`policy.query-remove.names`obligatoire

Noms des paramètres retirés, au moins un.

Type: list<string>
Bornes: éléments ≥ 1
Depuis: 0.1.0
Rechargement: à chaud

`policy.quota`

Quota de requêtes d'un tenant sur des fenêtres calendaires UTC (jour, mois) ; type: quota sous policies.definitions, phase request, sans condition. Exige server.counters : compté en mémoire, un quota mensuel repartirait à chaque déploiement. Au-delà : 429 quota_exceeded.

Type: object
Depuis: 1.0.0
Rechargement: à chaud

`policy.quota.key`

Ce qui est compté : tenant seulement (défaut).

Type: string
Valeurs admises: tenant
Défaut: tenant
Depuis: 1.0.0
Rechargement: à chaud

`policy.quota.limits`obligatoire

Plafonds par fenêtre : day et/ou month, chacun un entier d'au moins 1 ; au moins une fenêtre.

Type: map<integer>
Depuis: 1.0.0
Rechargement: à chaud

`policy.rate-limit`

Seaux à jetons par appelant ; type: rate-limit sous policies.definitions, phase request, sans condition. Une opération prend la classe read (GET, HEAD, OPTIONS) ou write, ou celle de x-flexway-rate-class ; au-delà : 429 rate_limited.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`policy.rate-limit.classes`obligatoire

Classes de débit par nom (read, write, ou les vôtres), chacune un seau ; au moins une.

Type: map<object>
Depuis: 0.1.0
Rechargement: à chaud

`policy.rate-limit.classes.*.burst`obligatoire

Taille du seau : requêtes admises d'un coup ; entier d'au moins 1, obligatoire.

Type: integer
Bornes: valeur ≥ 1
Depuis: 0.1.0
Rechargement: à chaud

`policy.rate-limit.classes.*.rps`obligatoire

Remplissage du seau, en requêtes par seconde ; nombre strictement positif, obligatoire.

Type: number
Bornes: valeur > 0
Depuis: 0.1.0
Rechargement: à chaud

`policy.rate-limit.classes.*.scope`

Remplace scope de la politique pour cette classe : class ou operation.

Type: string
Valeurs admises: classoperation
Depuis: 1.0.0
Rechargement: à chaud

`policy.rate-limit.key`

Ce qu'un seau compte : caller (défaut) - le sujet authentifié, sinon l'adresse du client - ou header - pour un anonyme, la valeur de header, crue seulement d'un pair dont l'identité figure dans trusted. Un sujet authentifié reste la clé dans les deux cas.

Type: string
Valeurs admises: callerheader
Défaut: caller
Depuis: 0.1.0
Rechargement: à chaud

`policy.rate-limit.scope`

Ce qu'un seau couvre : class (défaut) - un seau par appelant et par classe, partagé par les opérations de la classe - ou operation - un seau par appelant et par opération, la classe en donnant la taille.

Type: string
Valeurs admises: classoperation
Défaut: class
Depuis: 1.0.0
Rechargement: à chaud

`policy.rate-limit.trusted`

Avec key: header, les identités de pair vérifiées (par server.peer_identity_header) dont l'en-tête clé est cru ; obligatoire avec key: header.

Type: list<string>
Depuis: 1.0.0
Rechargement: à chaud

`policy.redact`

Masque ou retire des champs du corps JSON de la réponse ; type: redact sous policies.definitions, phase response. Exactement un de with ou remove: true.

Type: object
Depuis: 1.2.0
Rechargement: à chaud

`policy.redact.fields`obligatoire

Chemins des champs, commençant par body. (body.card.number), segments [A-Za-z_][A-Za-z0-9_]* ; 1 à 256 chemins, 32 segments au plus, sans doublon.

Type: list<string>
Bornes: éléments ≥ 1, ≤ 256
Motif: ^body\.
Depuis: 1.2.0
Rechargement: à chaud

`policy.redact.remove`

true retire les champs au lieu de les masquer ; jamais avec with.

Type: boolean
Depuis: 1.2.0
Rechargement: à chaud

`policy.redact.with`

Valeur qui remplace un champ masqué : une chaîne, un nombre, un booléen ou null ; jamais avec remove: true.

Type: string | number | boolean | null
Depuis: 1.2.0
Rechargement: à chaud

`policy.rewrite-path`

Dirige la requête vers un autre chemin de l'amont ; type: rewrite-path sous policies.definitions, phase request.

Type: object
Depuis: 0.1.0
Rechargement: à chaud

`policy.rewrite-path.to`obligatoire

Chemin de l'amont, commençant par / ; {param} y prend la valeur d'un paramètre de la route, échappée, jamais le texte brut du chemin reçu.

Type: string
Motif: ^/
Depuis: 0.1.0
Rechargement: à chaud

`policy.transform-body`

Projection fermée du corps JSON de la réponse : seuls les champs listés sont servis ; type: transform-body sous policies.definitions, phase response. Corps borné par server.body.max_bytes.

Type: object
Depuis: 1.2.0
Rechargement: à chaud

`policy.transform-body.on_missing`obligatoire

Champ projeté absent de la réponse : fail (réponse refusée) ou omit (champ omis). Obligatoire.

Type: string
Valeurs admises: failomit
Depuis: 1.2.0
Rechargement: à chaud

`policy.transform-body.project`obligatoire

Chemins pointés des champs gardés (id, customer.name), segments [A-Za-z_][A-Za-z0-9_]* ; 1 à 256 chemins, 32 segments au plus.

Type: list<string>
Bornes: éléments ≥ 1, ≤ 256
Depuis: 1.2.0
Rechargement: à chaud

67 clés

Extensions du contrat

Les extensions x-flexway-* qu'un contrat porte (OpenAPI, AsyncAPI, carte d'agent A2A) et l'option gRPC flexway.v1.operation. Liste fermée : une extension x-flexway-* inconnue, pas encore servie ou écrite là où elle n'est pas lue est refusée au chargement.

`x-flexway-a2a`

Bloc de gouvernance d'un agent A2A, au premier niveau de sa carte déclarée (contracts.a2a), obligatoire ; retiré de la carte publiée. Clés inconnues refusées.

Type: object
Lu dans: carte d'agent A2A
Depuis: 1.2.0
Rechargement: à chaud

`x-flexway-a2a.delegation`

Bornes de la chaîne d'agents pour cet agent { max_depth, max_age } : exige agents.delegation et ne peut que les resserrer - une borne plus large est refusée.

Type: object
Depuis: 1.2.0
Rechargement: à chaud

`x-flexway-a2a.delegation.max_age`

Âge maximal depuis l'authentification de la personne, durée positive ; jamais au-delà de agents.delegation.max_age.

Type: string
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.2.0
Rechargement: à chaud

`x-flexway-a2a.delegation.max_depth`

Nombre maximal d'agents dans la chaîne, entier positif ou nul ; jamais au-delà de agents.delegation.max_depth.

Type: integer
Bornes: valeur ≥ 0
Depuis: 1.2.0
Rechargement: à chaud

`x-flexway-a2a.max_streams`

Flux ouverts au plus par réplique pour cet agent ; obligatoire et supérieur à 0 si la carte annonce capabilities.streaming.

Type: integer
Bornes: valeur ≥ 0
Depuis: 1.2.0
Rechargement: à chaud

`x-flexway-a2a.max_task_duration`

Durée maximale d'une tâche suivie en flux, durée positive (10m) ; obligatoire si la carte annonce capabilities.streaming.

Type: string
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.2.0
Rechargement: à chaud

`x-flexway-a2a.methods`

Classe de débit par méthode A2A (SendMessage, GetTask, CancelTask...), ^[a-z][a-z0-9_-]{0,31}$. Défaut : write pour les envois, CancelTask et la création ou suppression d'une configuration de notification, free pour le reste.

Type: map<string>
Depuis: 1.2.0
Rechargement: à chaud

`x-flexway-a2a.signer`

Signataire de la carte publiée : pas encore accepté, toute valeur est refusée.

Type: string
Depuis: 1.10.0
Rechargement: à chaud

`x-flexway-a2a.upstream`obligatoire

Amont qui sert l'agent, déclaré dans upstreams avec protocol: a2a (et donc token_exchange) ; obligatoire.

Type: string
Depuis: 1.2.0
Rechargement: à chaud

`x-flexway-a2a.verify`obligatoire

Vérification de la carte de l'amont : none seulement, obligatoire.

Type: string
Valeurs admises: none
Depuis: 1.2.0
Rechargement: à chaud

`x-flexway-ai`

Nom de l'option ai de flexway.v1.operation sur une méthode gRPC : la méthode est un modèle mesuré. Refusée dans un contrat OpenAPI ou AsyncAPI.

Type: object
Lu dans: méthode gRPC
Depuis: 1.5.0
Rechargement: à chaud

`x-flexway-ai.capability`

Capacité des séries : model (défaut), vision, embeddings ou chat.

Type: string
Valeurs admises: modelvisionembeddingschat
Défaut: model
Depuis: 1.5.0
Rechargement: à chaud

`x-flexway-ai.price_per_1k`

Prix de mille unités, en euros ; positif ou nul.

Type: number
Bornes: valeur ≥ 0
Depuis: 1.5.0
Rechargement: à chaud

`x-flexway-ai.unit`

Unité comptée : call (défaut) ou byte (octets de la requête et de la réponse).

Type: string
Valeurs admises: callbyte
Défaut: call
Depuis: 1.5.0
Rechargement: à chaud

`x-flexway-bind`

Sur un paramètre de canal AsyncAPI : lie le paramètre à un fait de l'identité vérifiée, jamais lu de la requête - tenant, subject, claim:<nom> (nom de 1 à 64 caractères [A-Za-z0-9_.-]) ou, sur une opération x-flexway-device, cert:<champ> du certificat de l'appareil - cn, serial, fingerprint, ou avec son indice ou[i], o[i], san.dns[i], san.uri[i], san.ip[i], san.email[i]. Obligatoire sur chaque paramètre d'un canal utilisé, qui doit figurer dans l'adresse.

Type: string
Motif: ^(tenant|subject|claim:[A-Za-z0-9_.-]{1,64}|cert:(cn|serial|fingerprint|(ou|o|san\.dns|san\.uri|san\.ip|san\.email)\[[0-9]{1,2}\]))$
Lu dans: paramètre AsyncAPI
Depuis: 1.5.0
Rechargement: à chaud

`x-flexway-cache`

Sur une opération OpenAPI GET ou HEAD : cache de réponses propre à l'opération, { ttl, scope }. Refusé sur un flux, un WebSocket, une méthode gRPC, une opération A2A, une porte de courtier, et avec une politique cache nommée par x-flexway-policies.

Type: object
Lu dans: opération OpenAPI
Depuis: 1.2.0
Rechargement: à chaud

`x-flexway-cache.scope`

public (défaut) : partagé, refusé si l'opération exige une identité ; subject : clé tenant et sujet, la seule façon de cacher une réponse authentifiée, refusé sur une opération sans security.

Type: string
Valeurs admises: publicsubject
Défaut: public
Depuis: 1.2.0
Rechargement: à chaud

`x-flexway-cache.ttl`obligatoire

Durée de conservation, durée positive (30s) ; obligatoire.

Type: string
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.2.0
Rechargement: à chaud

`x-flexway-delegation`

Sur une opération OpenAPI : resserre pour elle les bornes de la chaîne d'agents, { max_depth, max_age } ; jamais plus large que agents.delegation, qui s'applique à défaut.

Type: object
Lu dans: opération OpenAPI
Depuis: 0.1.0
Rechargement: à chaud

`x-flexway-delegation.max_age`

Âge maximal depuis l'authentification de la personne, durée positive ; absent : la borne de la configuration.

Type: string
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 0.1.0
Rechargement: à chaud

`x-flexway-delegation.max_depth`

Nombre maximal d'agents dans la chaîne, entier positif ou nul (0 refuse tout jeton délégué) ; absent : la borne de la configuration.

Type: integer
Bornes: valeur ≥ 0
Depuis: 0.1.0
Rechargement: à chaud

`x-flexway-deliver`

Sur une opération AsyncAPI receive : livraisons webhook de ses messages, sans appelant - une liste de cibles { upstream, tenant, dead_letter }. Refusé en MQTT 3.1.1 et NATS Core.

Type: list<object>
Lu dans: opération AsyncAPI
Depuis: 1.5.0
Rechargement: à chaud

`x-flexway-deliver.*.dead_letter`obligatoire

Canal de rebut où va un message que la cible n'a pas accepté après les réessais ; obligatoire, sans { } ni joker.

Type: string
Motif: ^[^{}*>+#\s][^{}*>+#]*$
Depuis: 1.5.0
Rechargement: à chaud

`x-flexway-deliver.*.tenant`

Tenant dont les messages sont livrés, 1 à 128 caractères [A-Za-z0-9_-] ; obligatoire sauf si l'opération est publique.

Type: string
Motif: ^[A-Za-z0-9_-]{1,128}$
Depuis: 1.5.0
Rechargement: à chaud

`x-flexway-deliver.*.upstream`obligatoire

Cible, un amont déclaré avec protocol: webhook ; obligatoire.

Type: string
Depuis: 1.5.0
Rechargement: à chaud

`x-flexway-device`

Sur une opération AsyncAPI : la sert aux appareils sur l'écouteur listeners.mqtt - send : un appareil publie, receive : il s'abonne. true, ou un objet des clés ci-dessous. Exige un amont MQTT (le même pour toutes les opérations d'appareil), une security et un canal aux paramètres liés, le tenant parmi eux ; jamais publique.

Type: boolean | object
Lu dans: opération AsyncAPI
Depuis: 1.7.0
Rechargement: à chaud

`x-flexway-device.bytes_per_second`

Sur une opération send : surcharge listeners.mqtt.device.bytes_per_second pour elle.

Type: integer
Bornes: valeur ≥ 1
Depuis: 1.7.0
Rechargement: à chaud

`x-flexway-device.messages_per_second`

Sur une opération send : surcharge listeners.mqtt.device.messages_per_second pour elle.

Type: number
Bornes: valeur > 0
Depuis: 1.7.0
Rechargement: à chaud

`x-flexway-device.qos_max`

QoS la plus haute sur le canal ; au-delà un PUBLISH est refusé 0x9B et un abonnement accordé à elle. De 0 à 2, défaut 2.

Type: integer
Défaut: 2
Bornes: valeur ≥ 0, ≤ 2
Depuis: 1.7.0
Rechargement: à chaud

`x-flexway-device.shared`

Sur une opération receive : admet les abonnements partagés ($share/<groupe>/<filtre>), le groupe écrit vers le courtier au nom du tenant. Défaut false.

Type: boolean
Défaut: false
Depuis: 1.7.0
Rechargement: à chaud

`x-flexway-encrypt`

Sur un message AsyncAPI : champs écrits chiffrés par la passerelle sur l'écouteur Kafka - liste non vide de chemins pointés (card.number), sans [, ], * ni espace, sans doublon ni chemin qui en contient un autre. Message JSON (champ de type chaîne déclaré), Avro ou Protobuf ; exige kms.

Type: list<string>
Bornes: éléments ≥ 1, ≤ 255
Motif: ^[^.\s\[\]*]+(\.[^.\s\[\]*]+)*$
Lu dans: message AsyncAPI
Depuis: 1.6.0
Rechargement: à chaud

`x-flexway-kafka-proxy`

Sur une opération AsyncAPI : la sert aux clients Kafka natifs de l'écouteur listeners.kafka - send : un client produit, receive : il lit. Exige un amont Kafka, une security et un canal <préfixe>{tenant}.<nom> lié au tenant ; jamais publique.

Type: object
Lu dans: opération AsyncAPI
Depuis: 1.6.0
Rechargement: à chaud

`x-flexway-kafka-proxy.admin_scope`

Portée qui ouvre l'administration bornée du cluster virtuel ; absente : administration refusée.

Type: string
Bornes: longueur ≥ 1
Depuis: 1.6.0
Rechargement: à chaud

`x-flexway-kafka-proxy.cluster`obligatoire

Nom du cluster virtuel, une étiquette DNS de 1 à 63 caractères [a-z0-9-] ; obligatoire.

Type: string
Motif: ^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$
Depuis: 1.6.0
Rechargement: à chaud

`x-flexway-kafka-proxy.decrypt_scope`

Sur une opération receive seulement : portée qui reçoit en clair les champs x-flexway-encrypt du message ; sans elle, ils restent chiffrés.

Type: string
Bornes: longueur ≥ 1
Depuis: 1.6.0
Rechargement: à chaud

`x-flexway-kafka-proxy.transactions`

Sur une opération send seulement : autorise les producteurs transactionnels. Défaut false.

Type: boolean
Depuis: 1.6.0
Rechargement: à chaud

`x-flexway-key`

Sur une opération AsyncAPI : pointeur JSON (commençant par /) vers la clé d'ordonnancement dans le message, la clé de l'enregistrement Kafka ; sans effet en MQTT et AMQP.

Type: string
Motif: ^/
Lu dans: opération AsyncAPI
Depuis: 1.5.0
Rechargement: à chaud

`x-flexway-owner`

Dans info d'un document OpenAPI ou sur une opération, l'opération l'emporte : équipe qui répond de l'opération, { team, contact }. Affichée au catalogue, jamais lue sur le chemin de la requête.

Type: object
Lu dans: bloc info OpenAPI · opération OpenAPI
Depuis: 1.2.0
Rechargement: à chaud

`x-flexway-owner.contact`

Comment joindre l'équipe - un canal, une liste, une page ; 128 caractères au plus, jamais une personne.

Type: string
Bornes: longueur ≤ 128
Depuis: 1.2.0
Rechargement: à chaud

`x-flexway-owner.team`obligatoire

Nom de l'équipe, obligatoire, non vide, 128 caractères au plus.

Type: string
Bornes: longueur ≥ 1, ≤ 128
Depuis: 1.2.0
Rechargement: à chaud

`x-flexway-policies`

Sur une opération OpenAPI : son niveau propre de la chaîne global -> hôte -> routes -> opération, une liste de noms de policies.definitions ; !nom retire une politique d'un niveau plus large.

Type: string | list<string>
Lu dans: opération OpenAPI
Depuis: 0.1.0
Rechargement: à chaud

`x-flexway-priority`

Sur une opération OpenAPI : priorité de délestage sous saturation - critical (jamais délestée), normal (défaut) ou sheddable (délestée en premier).

Type: string
Valeurs admises: criticalnormalsheddable
Défaut: normal
Lu dans: opération OpenAPI
Depuis: 1.0.0
Rechargement: à chaud

`x-flexway-public`

Sur une opération AsyncAPI receive : true laisse quiconque la consommer, anonyme compris - écrit, jamais déduit. Refusé si le canal lie un paramètre ou porte l'attribut tenant, et avec x-flexway-kafka-proxy.

Type: boolean
Lu dans: opération AsyncAPI
Depuis: 1.5.0
Rechargement: à chaud

`x-flexway-publish`

Sur une opération OpenAPI POST : porte HTTP d'une opération AsyncAPI send, { operation, idempotency }. Le corps est publié en CloudEvents et la réponse 202 part après l'accusé du courtier ; jamais avec x-flexway-subscribe, un cache ou une politique de corps, ni pour un appelant anonyme.

Type: object
Lu dans: opération OpenAPI
Depuis: 1.5.0
Rechargement: à chaud

`x-flexway-publish.idempotency`

required refuse une publication sans en-tête Idempotency-Key ; absent : facultatif.

Type: string
Valeurs admises: required
Depuis: 1.5.0
Rechargement: à chaud

`x-flexway-publish.operation`obligatoire

Identifiant de l'opération send de contracts.asyncapi, à un seul message, dont le schéma est celui du corps ; obligatoire.

Type: string
Depuis: 1.5.0
Rechargement: à chaud

`x-flexway-rate-class`

Sur une opération OpenAPI : classe de débit, définie par la politique rate-limit de la chaîne sur chaque hôte ; absente : read ou write selon la méthode.

Type: string
Lu dans: opération OpenAPI
Depuis: 0.1.0
Rechargement: à chaud

`x-flexway-scopes`

Sur une opération OpenAPI : portées ajoutées à chaque alternative à jeton de security (une chaîne ou une liste) ; retire l'alternative anonyme, laisse clés d'API et certificats inchangés. Elle ne peut qu'ajouter.

Type: string | list<string>
Lu dans: opération OpenAPI
Depuis: 0.3.0
Rechargement: à chaud

`x-flexway-source`

Sur une opération AsyncAPI : attribut CloudEvents source de ce qu'elle publie ; absent : //<hôte de la requête>/<identifiant de l'opération>.

Type: string
Lu dans: opération AsyncAPI
Depuis: 1.5.0
Rechargement: à chaud

`x-flexway-sparkplug`

Sur une opération AsyncAPI servie aux appareils (x-flexway-device) : son rôle dans l'espace de noms Sparkplug B 3.0 - edge_node (canal spBv1.0/{groupe}/+/{nœud}/# : send publie naissances, morts et données, testament NDEATH seulement ; receive reçoit ses commandes), host (canal spBv1.0/{groupe}/# : send publie NCMD et DCMD, chaque alternative à jeton nommant des portées ; receive lit le groupe), state (canal spBv1.0/STATE/{hôte}, l'hôte lié au tenant). Le groupe est toujours lié au tenant. Sans message déclaré, la charge est lue sous le descripteur sparkplug_b.proto embarqué (validation avec x-flexway-validation: full).

Type: string
Valeurs admises: edge_nodehoststate
Lu dans: opération AsyncAPI
Depuis: 1.7.0
Rechargement: à chaud

`x-flexway-sunset`

Dans info d'un document OpenAPI ou sur une opération, l'opération l'emporte : date de retrait, AAAA-MM-JJ. L'opération doit être deprecated: true ; posée dans info, chaque opération sans valeur propre doit l'être.

Type: string
Motif: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
Lu dans: bloc info OpenAPI · opération OpenAPI
Depuis: 1.2.0
Rechargement: à chaud

`x-flexway-timeout`

Sur une opération OpenAPI : budget total de l'opération, reprises comprises, durée positive (2s, 500ms) ; prime sur upstreams.*.timeout, puis server.timeouts.total.

Type: string
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Lu dans: opération OpenAPI
Depuis: 0.2.0
Rechargement: à chaud

`x-flexway-tool`

Sur une opération OpenAPI : l'offre en outil sur la surface MCP, sous la même décision qu'en REST. true (outil nommé d'après l'operationId), false, ou un objet { name, description, unattended }. Refusé avec x-flexway-subscribe et sur un flux SSE.

Type: boolean | object
Lu dans: opération OpenAPI
Depuis: 0.1.0
Rechargement: à chaud

`x-flexway-tool.description`

Description de l'outil ; défaut : le summary, puis la description de l'opération.

Type: string
Depuis: 0.1.0
Rechargement: à chaud

`x-flexway-tool.name`

Nom de l'outil, ^[A-Za-z0-9_.-]{1,128}$, unique par hôte ; défaut : l'operationId.

Type: string
Motif: ^[A-Za-z0-9_.-]{1,128}$
Depuis: 0.1.0
Rechargement: à chaud

`x-flexway-tool.unattended`

false réserve l'outil aux agents qu'une personne surveille ; défaut true.

Type: boolean
Défaut: true
Depuis: 1.0.0
Rechargement: à chaud

`x-flexway-upstream`

Sur une opération OpenAPI : amont où elle est relayée, déclaré dans upstreams ; absent : default_upstream de l'hôte. Sur une opération AsyncAPI : obligatoire, l'amont courtier (kafka, amqp, mqtt, nats) où elle publie ou consomme.

Type: string
Lu dans: opération AsyncAPI · opération OpenAPI
Depuis: 0.1.0
Rechargement: à chaud

`x-flexway-validation`

Mode de validation de l'opération. OpenAPI : full, params (le corps est relayé non lu) ou off, prime sur hosts.*.validation. AsyncAPI : full ou off seulement ; défaut full pour un message JSON (où off est refusé), off pour un message binaire.

Type: string
Valeurs admises: fullparamsoff
Lu dans: opération AsyncAPI · opération OpenAPI
Depuis: 1.0.0
Rechargement: à chaud

21 clés

Option gRPC

Dans le .proto, option (flexway.v1.operation) = { ... }; : le pendant, pour une méthode gRPC, des extensions d'une opération OpenAPI.

`flexway.v1.operation`

Option de méthode gRPC (option (flexway.v1.operation) = { ... }; dans le .proto) : ce que la passerelle doit savoir d'une méthode, l'équivalent des extensions x-flexway-* d'une opération OpenAPI. Lue dans le jeu de descripteurs avec ses imports ; chaque champ est facultatif, l'hôte décide à défaut.

Type: object
Lu dans: méthode gRPC
Depuis: 1.1.0
Rechargement: à chaud

`flexway.v1.operation.ai`

Fait de la méthode un modèle spécialisé mesuré par le plan d'inférence (équivalent de x-flexway-ai) : compté dans le budget en euros du tenant, à l'appel ou à l'octet, sans lire le corps. Exige une section ai et un backend kind: grpc de ai.backends qui nomme l'amont de la méthode.

Type: object
Depuis: 1.5.0
Rechargement: à chaud

`flexway.v1.operation.ai.capability`

Capacité dont les séries sont étiquetées : model (défaut), vision, embeddings ou chat.

Type: string
Valeurs admises: modelvisionembeddingschat
Défaut: model
Depuis: 1.5.0
Rechargement: à chaud

`flexway.v1.operation.ai.price_per_1k`

Prix de mille unités, en euros ; positif ou nul (0 est un prix).

Type: number
Bornes: valeur ≥ 0
Depuis: 1.5.0
Rechargement: à chaud

`flexway.v1.operation.ai.unit`

Unité comptée : call (défaut), une unité par appel ; byte, une par octet de la requête et de la réponse.

Type: string
Valeurs admises: callbyte
Défaut: call
Depuis: 1.5.0
Rechargement: à chaud

`flexway.v1.operation.metadata`

Métadonnées de requête autorisées vers l'amont, en plus de celles de gRPC : fermé par défaut, une métadonnée non listée ne passe pas.

Type: list<string>
Depuis: 1.1.0
Rechargement: à chaud

`flexway.v1.operation.owner`

Équipe qui répond de la méthode (équivalent de x-flexway-owner) : affichée au catalogue de la console, jamais lue sur le chemin de la requête.

Type: object
Depuis: 1.2.0
Rechargement: à chaud

`flexway.v1.operation.owner.contact`

Comment joindre l'équipe - un canal, une liste, une page ; 128 caractères au plus. Jamais une personne : tout lecteur du catalogue le voit.

Type: string
Bornes: longueur ≤ 128
Depuis: 1.2.0
Rechargement: à chaud

`flexway.v1.operation.owner.team`obligatoire

Nom de l'équipe, obligatoire dès que owner est écrit ; non vide, 128 caractères au plus.

Type: string
Bornes: longueur ≥ 1, ≤ 128
Depuis: 1.2.0
Rechargement: à chaud

`flexway.v1.operation.policies`

Niveau propre de la méthode dans la chaîne de politiques (équivalent de x-flexway-policies) : noms de policies.definitions ; !nom retire une politique apportée par un niveau plus large.

Type: list<string>
Depuis: 1.1.0
Rechargement: à chaud

`flexway.v1.operation.priority`

Priorité de délestage : critical (jamais délestée), normal (défaut) ou sheddable (délestée en premier).

Type: string
Valeurs admises: criticalnormalsheddable
Défaut: normal
Depuis: 1.1.0
Rechargement: à chaud

`flexway.v1.operation.rate_class`

Classe de débit de la méthode (équivalent de x-flexway-rate-class), définie par la politique rate-limit de la chaîne. Vide : read pour une méthode sans effet de bord ou liée en GET, write sinon.

Type: string
Depuis: 1.1.0
Rechargement: à chaud

`flexway.v1.operation.security`

Alternatives d'accès, dont une seule suffit - comme la liste security d'OpenAPI. Vide : aucune identité exigée.

Type: list<object>
Depuis: 1.1.0
Rechargement: à chaud

`flexway.v1.operation.security.*.anonymous`

Alternative vide : aucune identité exigée. Prime sur les autres champs de l'alternative.

Type: boolean
Depuis: 1.1.0
Rechargement: à chaud

`flexway.v1.operation.security.*.api_key`

Une clé d'API liée à la méthode (Authorization: ApiKey ...) satisfait cette alternative ; portées et rôles y sont ignorés.

Type: boolean
Depuis: 1.1.0
Rechargement: à chaud

`flexway.v1.operation.security.*.mutual_tls`

Un certificat client lié à la méthode satisfait cette alternative ; portées et rôles y sont ignorés.

Type: boolean
Depuis: 1.1.0
Rechargement: à chaud

`flexway.v1.operation.security.*.roles`

Rôles qu'un jeton doit tous porter, lus par la claim roles_claim de son émetteur.

Type: list<string>
Depuis: 1.1.0
Rechargement: à chaud

`flexway.v1.operation.security.*.scopes`

Portées qu'un jeton doit toutes porter.

Type: list<string>
Depuis: 1.1.0
Rechargement: à chaud

`flexway.v1.operation.sunset`

Date de retrait de la méthode, AAAA-MM-JJ (équivalent de x-flexway-sunset). Seulement sur une méthode marquée option deprecated = true; : refusée au chargement sinon.

Type: string
Motif: ^[0-9]{4}-[0-9]{2}-[0-9]{2}$
Depuis: 1.2.0
Rechargement: à chaud

`flexway.v1.operation.timeout`

Budget total d'un appel, durée positive (3s) ; vide : celui de l'amont.

Type: string
Motif: ^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$
Depuis: 1.1.0
Rechargement: à chaud

`flexway.v1.operation.upstream`

Amont qui sert la méthode, déclaré dans upstreams ; vide : l'amont par défaut de l'hôte.

Type: string
Depuis: 1.1.0
Rechargement: à chaud

Référence de configuration

Valider dans l'éditeur

flexway.yaml

agents.mcp.servers.*.toolsobligatoire

agents.mcp.servers.*.upstreamobligatoire

ai.backends.*.api_keysecret

ai.backends.*.auth.keysecret

ai.backends.*.auth.schemeobligatoire

audit.keyredémarrage

auth.api_keys.storeobligatoire

auth.issuers.*.client.idobligatoire

auth.issuers.*.client.secretobligatoiresecret

auth.issuers.*.discoveryobligatoire

auth.issuers.*.nameobligatoire

auth.issuers.*.service_accounts.claimobligatoire

auth.issuers.*.service_accounts.prefixobligatoire

auth.mtls.clients.*.idobligatoire

auth.mtls.clients.*.tenantobligatoire

kms.aws_kms.credentials_filesecret

kms.aws_kms.regionobligatoire

kms.gcp_kms.credentials_filesecret

kms.keyobligatoire

kms.local.dirobligatoire