@nodefony/http 10.0.0-alpha.5 → 10.0.0-alpha.6

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

@@ -1,3 +1,4 @@
+import { isPortListening } from "nodefony";
 //#region nodefony/src/servers/portBinder.ts
 /** Nombre de ports essayés après le désiré, en `auto`. */
 const DEFAULT_PORT_RETRY_ATTEMPTS = 20;
@@ -42,6 +43,69 @@ function buildBindPlan(which, servers, environment) {
 		attempts: policy === "auto" ? servers?.portRetryAttempts ?? 20 : 0
 	};
 }
+/** Adresses qui désignent « toutes les interfaces » — rien ne s'y connecte. */
+const WILDCARD_HOSTS = /* @__PURE__ */ new Set([
+	"",
+	"*",
+	"0.0.0.0",
+	"::",
+	"[::]"
+]);
+/** Adresses de la boucle locale, toutes familles — c'est aussi ce qu'on REND. */
+const LOOPBACK_HOSTS = ["127.0.0.1", "::1"];
+/** Les mêmes, plus le nom qui les désigne — DÉRIVÉ, jamais recopié. */
+const LOOPBACK_ALIASES = /* @__PURE__ */ new Set([...LOOPBACK_HOSTS, "localhost"]);
+/**
+* Adresses à interroger pour savoir si notre future liaison chevauche déjà un
+* serveur vivant.
+*
+* La règle est celle du TRAFIC, pas celle du noyau : on sonde ce que notre
+* liaison va RECEVOIR.
+* - Écouter sur **toutes les interfaces** recouvre la boucle locale : on sonde
+*   ses deux adresses (`127.0.0.1` et `::1`). Un wildcard n'est pas une
+*   destination, on ne peut pas s'y connecter.
+* - Écouter sur la **boucle locale** (`localhost` résout `::1` ici, `127.0.0.1`
+*   ailleurs — et les clients ne choisissent pas) : les deux, là encore.
+* - Écouter sur une **adresse d'interface précise** : elle seule. Une connexion
+*   vers elle atteint le tiers qu'il ait lié cette adresse ou le wildcard, donc
+*   une cible suffit — et sonder la boucle locale ferait refuser un pod à cause
+*   d'un voisin de conteneur qui n'a jamais été en conflit.
+*
+* Fonction PURE : le banc l'éprouve sans ouvrir un socket.
+*
+* @param host - hôte passé à `listen` (`kernel.domain`).
+* @returns les adresses à interroger, dans l'ordre.
+*/
+function conflictProbeTargets(host) {
+	const value = (host ?? "").trim().toLowerCase();
+	if (WILDCARD_HOSTS.has(value) || LOOPBACK_ALIASES.has(value)) return LOOPBACK_HOSTS;
+	return [value];
+}
+/**
+* Première adresse où un serveur répond DÉJÀ sur ce port, `null` si la voie est
+* libre.
+*
+* @param port - port candidat.
+* @param host - hôte que `listen` recevra (décide des adresses interrogées).
+* @param probe - sonde de présence (injectée par le banc).
+*/
+async function detectPortConflict(port, host, probe) {
+	for (const target of conflictProbeTargets(host)) if (await probe(port, target)) return target;
+	return null;
+}
+/**
+* Erreur d'un conflit que le noyau aurait laissé passer.
+*
+* Porte `EADDRINUSE` : pour l'appelant c'est le même fait — le port n'est pas
+* prenable — et une seule branche le traite. Le message, lui, doit dire ce que
+* le code d'erreur seul ferait chercher au mauvais endroit : ici `listen` aurait
+* RÉUSSI, et c'est la liaison d'une AUTRE adresse qui capte le trafic.
+*/
+function portConflictError(port, host) {
+	const error = /* @__PURE__ */ new Error(`Port ${port} déjà servi par un autre processus sur ${host} — le noyau l'aurait pourtant accordé (deux adresses distinctes coexistent sur le même port), et cette application aurait écouté sans rien recevoir. Libérer le port (nodefony status · nodefony stop), en figer un autre (servers.http.port / servers.https.port), ou autoriser le repli (servers.portPolicy = "auto", défaut en développement).`);
+	error.code = "EADDRINUSE";
+	return error;
+}
 /** Prochain candidat : incrémente, en sautant ce que les autres serveurs veulent. */
 function nextCandidate(from, reserved) {
 	let port = from + 1;
@@ -84,31 +148,39 @@ function isPortUnavailable(code, port) {
 *   (`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);
+async function bindWithFallback(server, host, plan, probe = isPortListening) {
+	let candidate = plan.desired;
+	let used = 0;
+	/**
+	* Une tentative d'écoute. L'erreur est RENDUE, jamais levée depuis le
+	* callback : les deux écouteurs se retirent dans les deux cas, et la boucle
+	* ci-dessous reste le seul endroit qui décide.
+	*/
+	const listenOnce = (port) => new Promise((settle) => {
+		const onError = (error) => {
+			server.removeListener("listening", onListening);
+			settle(error);
 		};
-		attempt();
+		const onListening = () => {
+			server.removeListener("error", onError);
+			settle(null);
+		};
+		server.once("error", onError);
+		server.once("listening", onListening);
+		server.listen(port, host);
 	});
+	for (;;) {
+		const conflict = plan.desired === 0 || candidate !== plan.desired ? null : await detectPortConflict(candidate, host, probe);
+		const failure = conflict ? portConflictError(candidate, conflict) : await listenOnce(candidate);
+		if (failure === null) return {
+			address: server.address(),
+			shiftedFrom: candidate === plan.desired ? null : plan.desired
+		};
+		if (!conflict && !isPortUnavailable(failure.code, candidate)) throw failure;
+		if (plan.desired === 0 || used >= plan.attempts) throw failure;
+		used += 1;
+		candidate = nextCandidate(candidate, plan.reserved);
+	}
 }
 //#endregion
-export { DEFAULT_PORT_RETRY_ATTEMPTS, bindWithFallback, buildBindPlan, resolvePortPolicy };
+export { DEFAULT_PORT_RETRY_ATTEMPTS, bindWithFallback, buildBindPlan, conflictProbeTargets, detectPortConflict, resolvePortPolicy };

package/dist/types/nodefony/src/servers/portBinder.d.ts

@@ -14,6 +14,24 @@
  * `listen()` est, lui, **atomique** : soit il réussit, soit le noyau dit
  * `EADDRINUSE`. On retente donc sur l'échec réel, jamais sur une prédiction.
  *
+ * ## Pourquoi une SONDE malgré cela
+ *
+ * Le `listen()` est atomique, mais il ne dit pas tout : un port peut être **déjà
+ * servi** et le noyau l'accorder quand même. Lier `0.0.0.0:P` alors qu'un autre
+ * processus tient `127.0.0.1:P` **réussit** sur macOS et les BSD — ce sont deux
+ * liaisons distinctes, et les connexions locales partent à la PLUS SPÉCIFIQUE.
+ * Entre familles d'adresses (`::1` tenu, `0.0.0.0` demandé), même linux
+ * l'accorde. L'application annonce alors `READY`, publie ses ports… et ne reçoit
+ * rien : une panne muette, et un banc qui interroge le serveur du VOISIN.
+ *
+ * On constate donc, AVANT de binder, qu'aucun serveur ne répond déjà là où notre
+ * liaison va recevoir (`isPortListening` — une connexion en boucle locale, aucun
+ * outil système, même verdict sur les trois plateformes). Ce n'est pas la sonde
+ * « ce port est-il libre ? » écartée plus haut : elle ne remplace pas le repli
+ * atomique, qui reste le seul à trancher la course — elle ajoute le seul conflit
+ * que le noyau n'exprime JAMAIS. La course résiduelle (un tiers prend le port
+ * entre la sonde et le bind) retombe donc sur `EADDRINUSE`, inchangé.
+ *
  * ## Pourquoi sauter les ports réservés
  *
  * HTTP veut 5151, HTTPS veut 5152. Si 5151 est pris, incrémenter naïvement ferait
@@ -86,6 +104,45 @@ export interface ServersPortConfig {
  * @param environment - `kernel.environment` (arbitre le défaut de la politique).
  */
 export declare function buildBindPlan(which: "http" | "https", servers: ServersPortConfig | undefined, environment: string | undefined): BindPlan;
+/**
+ * Sonde « un serveur répond-il déjà ici ? ».
+ *
+ * Injectable pour que le banc éprouve la DÉCISION sans dépendre d'un décor
+ * réseau ; le défaut est `isPortListening`, exposé par le cœur pour ne pas être
+ * recopié de paquet en paquet.
+ */
+export type PortListeningProbe = (port: number, host: string) => Promise<boolean>;
+/**
+ * Adresses à interroger pour savoir si notre future liaison chevauche déjà un
+ * serveur vivant.
+ *
+ * La règle est celle du TRAFIC, pas celle du noyau : on sonde ce que notre
+ * liaison va RECEVOIR.
+ * - Écouter sur **toutes les interfaces** recouvre la boucle locale : on sonde
+ *   ses deux adresses (`127.0.0.1` et `::1`). Un wildcard n'est pas une
+ *   destination, on ne peut pas s'y connecter.
+ * - Écouter sur la **boucle locale** (`localhost` résout `::1` ici, `127.0.0.1`
+ *   ailleurs — et les clients ne choisissent pas) : les deux, là encore.
+ * - Écouter sur une **adresse d'interface précise** : elle seule. Une connexion
+ *   vers elle atteint le tiers qu'il ait lié cette adresse ou le wildcard, donc
+ *   une cible suffit — et sonder la boucle locale ferait refuser un pod à cause
+ *   d'un voisin de conteneur qui n'a jamais été en conflit.
+ *
+ * Fonction PURE : le banc l'éprouve sans ouvrir un socket.
+ *
+ * @param host - hôte passé à `listen` (`kernel.domain`).
+ * @returns les adresses à interroger, dans l'ordre.
+ */
+export declare function conflictProbeTargets(host: string | undefined): readonly string[];
+/**
+ * Première adresse où un serveur répond DÉJÀ sur ce port, `null` si la voie est
+ * libre.
+ *
+ * @param port - port candidat.
+ * @param host - hôte que `listen` recevra (décide des adresses interrogées).
+ * @param probe - sonde de présence (injectée par le banc).
+ */
+export declare function detectPortConflict(port: number, host: string | undefined, probe: PortListeningProbe): Promise<string | null>;
 /**
  * Écoute sur `plan.desired`, ou sur le prochain port libre si `attempts > 0`.
  *
@@ -99,4 +156,4 @@ export declare function buildBindPlan(which: "http" | "https", servers: ServersP
  *   (`ENOTFOUND`, `EACCES` sous 1024 — cf `isPortUnavailable`), soit un port
  *   indisponible après épuisement des essais (le fallback n'est PAS infini).
  */
-export declare function bindWithFallback(server: Listenable, host: string, plan: BindPlan): Promise<BindResult>;
+export declare function bindWithFallback(server: Listenable, host: string, plan: BindPlan, probe?: PortListeningProbe): Promise<BindResult>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodefony/http",
-  "version": "10.0.0-alpha.5",
+  "version": "10.0.0-alpha.6",
   "description": "Serveurs HTTP, HTTPS, HTTP/2 et WebSocket natifs pour Nodefony : sessions, contextes de requête, certificats TLS",
   "author": "Christophe CAMENSULI <ccamensuli@gmail.com>",
   "main": "./dist/index.js",
@@ -75,7 +75,7 @@
     "@types/xml2js": "0.4.14",
     "@vitest/coverage-v8": "5.0.0",
     "chai": "6.2.2",
-    "nodefony": "^10.0.0-alpha.5",
+    "nodefony": "^10.0.0-alpha.6",
     "rimraf": "6.1.3",
     "tsx": "4.23.13",
     "vitest": "5.0.0"
@@ -84,7 +84,7 @@
   "readmeFilename": "README.md",
   "contributors": [],
   "peerDependencies": {
-    "nodefony": "^10.0.0-alpha.5",
+    "nodefony": "^10.0.0-alpha.6",
     "zod": "^4.6.1"
   },
   "files": [