@nodefony/http 10.0.0-alpha.1

package/dist/nodefony/src/proxy/generateProxyConfig.js

@@ -0,0 +1,157 @@
+//#region nodefony/src/proxy/generateProxyConfig.ts
+/** Valeurs par défaut d'un modèle d'introspection (complété par la commande). */
+const defaultIntrospection = {
+	domains: [],
+	backendHost: "127.0.0.1",
+	httpPort: 5151,
+	httpsPort: 5152,
+	staticRoots: [],
+	mounts: [],
+	listen: 80,
+	reencrypt: false,
+	maxBodyBytes: 0,
+	keepaliveIntervalMs: 0
+};
+/**
+* Délai d'inactivité, en secondes, qu'un proxy doit accorder à une connexion
+* portée par le heartbeat WebSocket.
+*
+* Quatre intervalles de battement : il faut trois pings perdus d'affilée pour
+* que le proxy coupe, ce qui laisse passer une pause de collecteur mémoire ou
+* une seconde de charge sans sacrifier des sockets vivantes. Plancher à 300 s
+* pour que les requêtes HTTP lentes ne soient pas coupées par le même réglage ;
+* heartbeat éteint → une heure, parce que plus rien ne garantit du trafic et
+* qu'un silence légitime peut alors durer.
+*/
+function idleTimeoutSeconds(intro) {
+	if (intro.keepaliveIntervalMs <= 0) return 3600;
+	return Math.max(300, Math.ceil(intro.keepaliveIntervalMs * 4 / 1e3));
+}
+/** `server_name` nginx / hôte de comparaison — IP et `0.0.0.0` exclus. */
+function serverNames(domains) {
+	const names = domains.filter((d) => d && d !== "0.0.0.0" && !isIpLiteral(d));
+	return names.length > 0 ? names.join(" ") : "_";
+}
+/** IP littérale (IPv4 ou IPv6) — ne va pas en `server_name`. */
+function isIpLiteral(host) {
+	return /^\d{1,3}(\.\d{1,3}){3}$/.test(host) || host.includes(":");
+}
+/** En-têtes forwarded nginx (pattern EDGE : on ÉCRASE X-Forwarded-For). */
+const NGINX_FORWARD_HEADERS_TPL = `      # EDGE (face client) : on ÉCRASE X-Forwarded-For avec la SEULE IP vue par
+      # nginx → toute valeur forgée par le client est jetée (RFC 7239 §8.1).
+      proxy_set_header Host              $host;
+      proxy_set_header X-Real-IP         $remote_addr;
+      proxy_set_header X-Forwarded-For   $remote_addr;
+      proxy_set_header X-Forwarded-Proto $scheme;
+      proxy_set_header X-Forwarded-Host  $host;
+      proxy_set_header X-Forwarded-Port  $server_port;
+      # WebSocket (Nodefony co-héberge HTTP + WS sur le même port).
+      proxy_set_header Upgrade           $http_upgrade;
+      proxy_set_header Connection        $connection_upgrade;
+      # Inactivité tolérée — dérivée du heartbeat WebSocket du serveur, pas du
+      # défaut nginx (60 s) : entre deux messages, une socket vivante ne montre
+      # au proxy que les pings du serveur.
+      proxy_read_timeout __IDLE__s;
+      proxy_send_timeout __IDLE__s;`;
+/** Les en-têtes forwarded nginx, avec le délai d'inactivité effectif. */
+function nginxForwardHeaders(idleSeconds) {
+	return NGINX_FORWARD_HEADERS_TPL.replaceAll("__IDLE__", String(idleSeconds));
+}
+/**
+* Génère une configuration nginx complète (reverse-proxy + offload statiques).
+*
+* @param intro - modèle d'introspection Nodefony.
+* @returns le contenu d'un `nginx.conf`.
+*/
+function generateNginxConfig(intro) {
+	const scheme = intro.reencrypt ? "https" : "http";
+	const backendPort = intro.reencrypt ? intro.httpsPort : intro.httpPort;
+	const idleSeconds = idleTimeoutSeconds(intro);
+	const lines = [];
+	lines.push("# Généré par `nodefony proxy:generate nginx` — NE PAS éditer à la main.", "# Reverse-proxy dérivé de l'introspection Nodefony (domaines, statiques, ports).", "worker_processes auto;", "events { worker_connections 1024; }", "", "http {", "  # Upgrade WebSocket — HTTP et WS co-habitent sur le même port Nodefony.", "  map $http_upgrade $connection_upgrade { default upgrade; '' close; }", "", `  upstream nodefony { server ${intro.backendHost}:${backendPort}; keepalive 32; }`, "");
+	if (intro.maxBodyBytes > 0) lines.push(`  # Aligné sur \`http.maxBodySize\` (${intro.maxBodyBytes} octets) — sans quoi`, "  # nginx rendrait 413 à 1 Mo, son défaut, sans que le serveur le sache.", `  client_max_body_size ${intro.maxBodyBytes};`, "");
+	lines.push("  server {", `    listen ${intro.listen};`, `    server_name ${serverNames(intro.domains)};`);
+	if (intro.reencrypt) lines.push("    # Re-encrypt : valider le cert backend (cf docker/certs).", "    # proxy_ssl_trusted_certificate /etc/nginx/certs/ca.pem;", "    # proxy_ssl_verify on; proxy_ssl_name nodefony.com;");
+	for (const m of intro.mounts) lines.push("", `    location ${m.prefix} {`, `      alias ${ensureTrailingSlash(m.dir)};`, "      access_log off;", "      expires 1h;", "    }");
+	lines.push("", `    location @nodefony {`, `      proxy_pass ${scheme}://nodefony;`, "      proxy_http_version 1.1;", nginxForwardHeaders(idleSeconds), "    }");
+	if (intro.staticRoots.length === 0) lines.push("", "    location / {", `      proxy_pass ${scheme}://nodefony;`, "      proxy_http_version 1.1;", nginxForwardHeaders(idleSeconds), "    }");
+	else {
+		const roots = intro.staticRoots;
+		lines.push("", "    # Statiques multi-dossiers (racine app + modules) : chaîne try_files,", "    # fallback vers le backend Nodefony si aucun fichier ne matche.", "    location / {", `      root ${roots[0]};`, `      try_files $uri ${roots.length > 1 ? "@r1" : "@nodefony"};`, "    }");
+		for (let i = 1; i < roots.length; i++) {
+			const next = i + 1 < roots.length ? `@r${i + 1}` : "@nodefony";
+			lines.push(`    location @r${i} {`, `      root ${roots[i]};`, `      try_files $uri ${next};`, "    }");
+		}
+	}
+	lines.push("  }", "}", "");
+	return lines.join("\n");
+}
+/**
+* Génère une configuration haproxy (reverse-proxy + Forwarded RFC 7239).
+* haproxy ne sert PAS de fichiers : les statiques sont proxifiés au backend
+* (ou désactivés côté serveur via `statics.enabled: false` + un nginx/CDN).
+*
+* @param intro - modèle d'introspection Nodefony.
+* @returns le contenu d'un `haproxy.cfg`.
+*/
+function generateHaproxyConfig(intro) {
+	const backendPort = intro.reencrypt ? intro.httpsPort : intro.httpPort;
+	const idleSeconds = idleTimeoutSeconds(intro);
+	const serverSsl = intro.reencrypt ? ` ssl ca-file /etc/haproxy/certs/ca.pem verify required verifyhost ${firstDomain(intro)} sni str(${firstDomain(intro)})` : "";
+	const staticNote = intro.staticRoots.length > 0 || intro.mounts.length > 0 ? "  # NB : haproxy ne sert pas de fichiers — les statiques sont proxifiés au\n  # backend. Pour les offloader, utiliser nginx (proxy:generate nginx) +\n  # `statics.enabled: false` côté Nodefony.\n" : "";
+	return `# Généré par \`nodefony proxy:generate haproxy\` — NE PAS éditer à la main.
+# Reverse-proxy dérivé de l'introspection Nodefony.
+global
+  log stdout format raw local0 info
+
+defaults
+  mode http
+  log global
+  option httplog
+  timeout connect 5s
+  timeout client  ${idleSeconds}s
+  timeout server  ${idleSeconds}s
+  # Une fois l'échange passé en WebSocket, ce sont ces secondes-là qui comptent :
+  # \`timeout server\` ne s'applique plus au tunnel. Sans cette ligne, la valeur
+  # implicite coupe des sockets que le heartbeat gardait pourtant vivantes.
+  timeout tunnel  ${idleSeconds}s
+
+frontend fe_nodefony
+  bind *:${intro.listen}
+
+  # SÉCU : effacer le Forwarded entrant (forgé) avant de poser le nôtre (§8.1).
+  http-request del-header Forwarded
+  option forwardfor
+
+  # Le \`proto\` annoncé au serveur est le scheme vu par le CLIENT — il se
+  # CONSTATE sur la connexion entrante (\`ssl_fc\`), il ne se déduit pas.
+  #
+  # Il était déduit du re-chiffrement vers le backend, qui est une tout autre
+  # question : un frontend en clair re-chiffrant vers le backend annonçait
+  # \`proto=https\`, et le serveur traitait alors une requête EN CLAIR comme
+  # sécurisée — cookies \`Secure\` posés sur du clair, garde « exiger HTTPS »
+  # jamais déclenchée. Le cas inverse (frontend TLS, backend en clair) faisait
+  # boucler les redirections vers HTTPS.
+  http-request set-header X-Forwarded-Proto https if { ssl_fc }
+  http-request set-header X-Forwarded-Proto http  unless { ssl_fc }
+  http-request set-header X-Forwarded-Host  %[req.hdr(host)]
+  http-request set-header X-Real-IP         %[src]
+  http-request set-header Forwarded "for=%[src];proto=https;host=%[req.hdr(host)]" if { ssl_fc }
+  http-request set-header Forwarded "for=%[src];proto=http;host=%[req.hdr(host)]" unless { ssl_fc }
+
+  default_backend be_nodefony
+
+backend be_nodefony
+${staticNote}  server nodefony ${intro.backendHost}:${backendPort} check${serverSsl}
+`;
+}
+/** Premier domaine non-IP (pour verifyhost/sni), défaut `localhost`. */
+function firstDomain(intro) {
+	return intro.domains.find((d) => d && d !== "0.0.0.0" && !isIpLiteral(d)) ?? "localhost";
+}
+/** Garantit un `/` final (requis par `alias` nginx). */
+function ensureTrailingSlash(dir) {
+	return dir.endsWith("/") ? dir : `${dir}/`;
+}
+//#endregion
+export { defaultIntrospection, generateHaproxyConfig, generateNginxConfig };

package/dist/nodefony/src/rateLimit/IRateLimitStore.js

@@ -0,0 +1 @@
+export {};

package/dist/nodefony/src/rateLimit/MemoryRateLimitStore.js

@@ -0,0 +1,146 @@
+import { assertPageQuery } from "nodefony";
+//#region nodefony/src/rateLimit/MemoryRateLimitStore.ts
+/**
+* Store de rate-limit **en mémoire** — algorithme *fixed window* par clé (IP).
+*
+* Une entrée par IP `{ count, resetAt }` ; à l'expiration de la fenêtre le
+* compteur repart à zéro (mutation in-place, 0 alloc pour une IP récurrente).
+* `hit()` est O(1) (1 `Map.get` + arithmétique), et la `Map` est allouée en
+* **lazy** au 1ᵉʳ hit → 0 coût mémoire si le rate-limit n'est jamais sollicité.
+*
+* Mémoire **bornée** par `maxTracked` : au cap, on purge d'abord les fenêtres
+* expirées puis on évince en FIFO (ordre d'insertion `Map`). Un {@link gc}
+* planifiable (GcScheduler du core) fait le ménage hors hot-path.
+*
+* ⚠️ Limite assumée (fenêtre fixe) : un pic à cheval sur deux fenêtres peut
+* laisser passer jusqu'à `2 × max` sur un court intervalle. Acceptable pour une
+* défense de capacité ; un *sliding window* viendrait en option si nécessaire.
+*/
+var MemoryRateLimitStore = class {
+	#entries = null;
+	#rejectedTotal = 0;
+	#windowMs;
+	#max;
+	#maxTracked;
+	#now;
+	/**
+	* @param options - fenêtre, plafond, borne mémoire.
+	* @param now - horloge injectable (ms) — `Date.now` par défaut, surchargée en test.
+	*/
+	constructor(options, now = Date.now) {
+		this.#windowMs = options.windowMs;
+		this.#max = options.max;
+		this.#maxTracked = options.maxTracked;
+		this.#now = now;
+	}
+	hit(key) {
+		const now = this.#now();
+		const entries = this.#entries ??= /* @__PURE__ */ new Map();
+		const entry = entries.get(key);
+		if (entry === void 0) {
+			if (entries.size >= this.#maxTracked) this.#evict(now);
+			const resetAt = now + this.#windowMs;
+			entries.set(key, {
+				count: 1,
+				resetAt
+			});
+			return this.#allow(resetAt, this.#max - 1);
+		}
+		if (now >= entry.resetAt) {
+			entry.count = 1;
+			entry.resetAt = now + this.#windowMs;
+			return this.#allow(entry.resetAt, this.#max - 1);
+		}
+		entry.count += 1;
+		if (entry.count > this.#max) {
+			this.#rejectedTotal += 1;
+			return {
+				limited: true,
+				limit: this.#max,
+				remaining: 0,
+				resetAtMs: entry.resetAt,
+				retryAfterS: Math.max(1, Math.ceil((entry.resetAt - now) / 1e3))
+			};
+		}
+		return this.#allow(entry.resetAt, this.#max - entry.count);
+	}
+	gc(nowMs = this.#now()) {
+		if (this.#entries === null) return 0;
+		let purged = 0;
+		for (const [key, entry] of this.#entries) if (nowMs >= entry.resetAt) {
+			this.#entries.delete(key);
+			purged += 1;
+		}
+		return purged;
+	}
+	/**
+	* {@inheritDoc IRateLimitStore.listPage}
+	*
+	* La collection est déjà en RAM et **bornée par `maxTracked`** (c'est la
+	* nature de ce store) : le tri porte sur des références, seule la page est
+	* matérialisée en objets de sortie. Les fenêtres expirées sont exclues à la
+	* lecture — les montrer ferait passer un compteur mort pour du trafic vivant
+	* (le `gc` les retire plus tard, hors hot-path).
+	*/
+	listPage(query) {
+		assertPageQuery(query, "offset");
+		const limit = Math.max(1, Math.floor(query.limit));
+		const offset = Math.max(0, Math.floor(query.offset ?? 0));
+		const now = this.#now();
+		const prefix = query.q !== void 0 && query.q.length > 0 ? query.q : null;
+		const matched = [];
+		for (const pair of this.#entries ?? []) {
+			const [key, entry] = pair;
+			if (now >= entry.resetAt) continue;
+			if (prefix !== null && !key.startsWith(prefix)) continue;
+			if (query.limited !== void 0 && entry.count > this.#max !== query.limited) continue;
+			matched.push(pair);
+		}
+		matched.sort((a, b) => b[1].count - a[1].count || (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+		const items = matched.slice(offset, offset + limit).map(([key, entry]) => ({
+			key,
+			count: entry.count,
+			resetAtMs: entry.resetAt,
+			limited: entry.count > this.#max
+		}));
+		return Promise.resolve({
+			items,
+			total: query.withTotal === false ? void 0 : matched.length,
+			limit,
+			offset,
+			hasNext: offset + items.length < matched.length
+		});
+	}
+	get trackedCount() {
+		return this.#entries?.size ?? 0;
+	}
+	get rejectedTotal() {
+		return this.#rejectedTotal;
+	}
+	/** Verdict « autorisé » — factorise la forme commune (0 rejet). */
+	#allow(resetAtMs, remaining) {
+		return {
+			limited: false,
+			limit: this.#max,
+			remaining,
+			resetAtMs,
+			retryAfterS: 0
+		};
+	}
+	/**
+	* Borne mémoire : supprime d'abord les fenêtres expirées ; si le cap tient
+	* toujours, évince en FIFO (ordre d'insertion `Map`) jusqu'à faire de la place.
+	*/
+	#evict(now) {
+		const entries = this.#entries;
+		if (entries === null) return;
+		for (const [key, entry] of entries) if (now >= entry.resetAt) entries.delete(key);
+		while (entries.size >= this.#maxTracked) {
+			const oldest = entries.keys().next().value;
+			if (oldest === void 0) break;
+			entries.delete(oldest);
+		}
+	}
+};
+//#endregion
+export { MemoryRateLimitStore };

package/dist/nodefony/src/rateLimit/WsConnectionCounter.js

@@ -0,0 +1,64 @@
+//#region nodefony/src/rateLimit/WsConnectionCounter.ts
+/**
+* Compteur de connexions WebSocket CONCURRENTES par IP — backstop opt-in
+* (F6c, revue 0.6). Distinct du {@link MemoryRateLimitStore} : celui-ci compte un
+* DÉBIT d'ouverture par fenêtre (handshakes/s) ; celui-là un NOMBRE de sockets
+* simultanément ouvertes par IP.
+*
+* ⚠️ Portée : PAR PROCESS (1 pod). Un vrai plafond global/IP se fait à l'ingress
+* (nginx `limit_conn`, HAProxy `sc_conn_cur`, annotation k8s) — l'edge voit tout le
+* trafic, rejette avant que l'app paie le fd + le handshake TLS, et couvre TOUS les
+* pods. Ce compteur est une défense en profondeur pour le bare-metal/VPS sans
+* ingress. Cf `wsMaxConnectionsPerIp` (config, opt-in, `null` par défaut).
+*
+* Auto-bornée : la Map ne suit que les IP AYANT des sockets ouvertes (bornée par le
+* nombre de connexions réelles), et se vide au fur et à mesure des fermetures — pas
+* besoin d'un GC ni d'un `maxTracked` (contrairement au store de débit qui retient
+* les IP sur toute la fenêtre). Lazy : Map allouée au 1ᵉʳ acquire.
+*/
+var WsConnectionCounter = class {
+	#max;
+	#counts = null;
+	#rejectedTotal = 0;
+	/** @param max - plafond de connexions concurrentes par IP (entier > 0). */
+	constructor(max) {
+		this.#max = max;
+	}
+	/**
+	* Tente de réserver un créneau pour `ip`. `true` = sous le plafond (compteur
+	* incrémenté, appeler {@link release} à la fermeture) ; `false` = plafond atteint
+	* (rien n'est incrémenté, la connexion doit être refusée).
+	*/
+	tryAcquire(ip) {
+		const counts = this.#counts ??= /* @__PURE__ */ new Map();
+		const cur = counts.get(ip) ?? 0;
+		if (cur >= this.#max) {
+			this.#rejectedTotal += 1;
+			return false;
+		}
+		counts.set(ip, cur + 1);
+		return true;
+	}
+	/** Libère un créneau de `ip` (à la fermeture de la socket). Idempotent-safe. */
+	release(ip) {
+		if (this.#counts === null) return;
+		const cur = this.#counts.get(ip);
+		if (cur === void 0) return;
+		if (cur <= 1) this.#counts.delete(ip);
+		else this.#counts.set(ip, cur - 1);
+	}
+	/** Plafond configuré (par IP). */
+	get max() {
+		return this.#max;
+	}
+	/** Nombre d'IP actuellement suivies (avec ≥ 1 socket ouverte). */
+	get trackedIps() {
+		return this.#counts?.size ?? 0;
+	}
+	/** Total de connexions refusées depuis la construction (observabilité). */
+	get rejectedTotal() {
+		return this.#rejectedTotal;
+	}
+};
+//#endregion
+export { WsConnectionCounter, WsConnectionCounter as default };

package/dist/nodefony/src/rateLimit/rateLimitFilters.js

@@ -0,0 +1,20 @@
+//#region nodefony/src/rateLimit/rateLimitFilters.ts
+/**
+* **Le vocabulaire de filtre du registre de rate-limit**, en noms PUBLICS —
+* celui que la console écrit dans l'URL (`?limited=true`).
+*
+* `limited` répond à la seule question qu'on pose à ce registre en exploitation :
+* « qui est au plafond en ce moment ? ». Il est booléen STRICT — `?limited=1`
+* est refusé plutôt que lu comme `false`, ce que faisait la comparaison
+* `limitedRaw === "true"` : sur un tableau de bord d'incident, une liste vide
+* obtenue par erreur de syntaxe se lit « aucun client bloqué ».
+*
+* `q` n'y figure pas : c'est une clé du contrat de page, lue par
+* `parsePageQuery`. Le data plane la recopiait à la main — deuxième lecteur du
+* même paramètre, exactement le motif que ce chantier supprime.
+*/
+const RATE_LIMIT_FILTERS = { 
+/** `true` = seulement les clés au plafond, `false` = seulement les autres. */
+limited: "boolean" };
+//#endregion
+export { RATE_LIMIT_FILTERS };

package/dist/nodefony/src/servers/portBinder.js

@@ -0,0 +1,114 @@
+//#region nodefony/src/servers/portBinder.ts
+/** Nombre de ports essayés après le désiré, en `auto`. */
+const DEFAULT_PORT_RETRY_ATTEMPTS = 20;
+/**
+* Politique de port effective.
+*
+* Le défaut dépend de l'environnement, et ce n'est pas de la coquetterie :
+* - **production** → `strict`. Le port y est un contrat (service k8s, ingress,
+*   sonde de santé). Un bind silencieux ailleurs donnerait un pod déclaré sain
+*   que personne n'atteint : une panne invisible, le pire des deux mondes.
+* - **test** → `strict`. Un port occupé veut dire « un serveur est resté debout » ;
+*   le banc doit s'arrêter, pas viser à côté (il taperait le serveur du voisin).
+* - **développement** → `auto`. Ici un port pris n'est qu'une nuisance.
+*
+* @param environment - `kernel.environment` (normalisé `development`/`production`/`test`).
+* @param explicit - `servers.portPolicy` s'il est configuré (il gagne toujours).
+*/
+function resolvePortPolicy(environment, explicit) {
+	if (explicit === "auto" || explicit === "strict") return explicit;
+	return environment === "development" ? "auto" : "strict";
+}
+/** Port configuré d'un serveur, ou `0` (désactivé / non précisé → choix noyau). */
+function configuredPort(entry) {
+	if (!entry) return 0;
+	return entry.port ?? 0;
+}
+/**
+* Compose le plan de bind d'un serveur depuis la config du kernel — source UNIQUE
+* (les deux serveurs l'appellent ; la politique n'est décidée qu'ici).
+*
+* @param which - le serveur qu'on borne.
+* @param servers - `kernel.options.servers`.
+* @param environment - `kernel.environment` (arbitre le défaut de la politique).
+*/
+function buildBindPlan(which, servers, environment) {
+	const desired = configuredPort(servers?.[which]);
+	const other = configuredPort(servers?.[which === "http" ? "https" : "http"]);
+	const policy = resolvePortPolicy(environment, servers?.portPolicy);
+	return {
+		desired,
+		reserved: other > 0 && other !== desired ? [other] : [],
+		attempts: policy === "auto" ? servers?.portRetryAttempts ?? 20 : 0
+	};
+}
+/** Prochain candidat : incrémente, en sautant ce que les autres serveurs veulent. */
+function nextCandidate(from, reserved) {
+	let port = from + 1;
+	while (reserved.includes(port)) port += 1;
+	return port;
+}
+/**
+* Vrai si ce code d'erreur signifie « ce port-ci n'est pas prenable ».
+*
+* `EADDRINUSE` est le cas de tous les systèmes. Windows en ajoute un second, et
+* il n'est pas anecdotique : Hyper-V, WSL et WinNAT **réservent des plages
+* entières** de ports éphémères (`netsh interface ipv4 show excludedportrange`),
+* qu'un `listen` refuse en **`EACCES`** — pas en `EADDRINUSE`. Une application
+* qui glisse de port en port finit statistiquement dans l'une de ces plages et
+* meurt là où linux et macOS auraient continué. C'est le PRODUIT que l'utilisateur
+* Windows subit, pas une singularité de banc.
+*
+* La borne est le port privilégié : sous 1024, `EACCES` veut dire « pas les
+* droits », et se replier en silence sur 81 quand l'exploitant demande 80 serait
+* une dégradation muette — exactement ce que ce fichier refuse.
+*
+* @param code - code d'erreur rendu par `listen`.
+* @param port - le port qui vient d'être refusé.
+* @returns `true` s'il faut essayer le port suivant plutôt qu'échouer.
+*/
+function isPortUnavailable(code, port) {
+	if (code === "EADDRINUSE") return true;
+	return code === "EACCES" && port >= 1024;
+}
+/**
+* Écoute sur `plan.desired`, ou sur le prochain port libre si `attempts > 0`.
+*
+* Aucun `error` permanent ne doit être attaché au serveur pendant l'appel : cette
+* fonction pose ses propres écouteurs le temps du bind et les retire toujours (le
+* handler d'erreur durable s'installe APRÈS, sur le serveur qui écoute — sinon il
+* verrait passer les `EADDRINUSE` de repli et croirait à une panne).
+*
+* @returns l'adresse obtenue + le port désiré si un décalage a eu lieu.
+* @throws l'erreur de `listen` : soit un code qui ne dit pas « ce port est pris »
+*   (`ENOTFOUND`, `EACCES` sous 1024 — cf `isPortUnavailable`), soit un port
+*   indisponible après épuisement des essais (le fallback n'est PAS infini).
+*/
+function bindWithFallback(server, host, plan) {
+	return new Promise((resolve, reject) => {
+		let candidate = plan.desired;
+		let used = 0;
+		const attempt = () => {
+			const onError = (error) => {
+				server.removeListener("listening", onListening);
+				if (!isPortUnavailable(error.code, candidate) || plan.desired === 0 || used >= plan.attempts) return reject(error);
+				used += 1;
+				candidate = nextCandidate(candidate, plan.reserved);
+				attempt();
+			};
+			const onListening = () => {
+				server.removeListener("error", onError);
+				resolve({
+					address: server.address(),
+					shiftedFrom: candidate === plan.desired ? null : plan.desired
+				});
+			};
+			server.once("error", onError);
+			server.once("listening", onListening);
+			server.listen(candidate, host);
+		};
+		attempt();
+	});
+}
+//#endregion
+export { DEFAULT_PORT_RETRY_ATTEMPTS, bindWithFallback, buildBindPlan, resolvePortPolicy };