@particle-academy/fancy-connector-core 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,43 @@ All notable changes to `fancy-connector-core` are documented here, in
 **This package is pre-1.0, so breaking changes land in MINOR releases.** The
 version number is not a promise it can keep yet; the entries below are.
 
+## [0.3.0] - 2026-08-19
+
+### Fixed
+
+- **`ECONNRESET` and `EPIPE` are `ambiguous`, not `unreachable`. This was a live
+  duplicate-send hazard.** Both were listed as codes proving the request never
+  left. They do not. A peer sends RST whenever it tears the connection down,
+  *including after it has received and acted on the request but before the
+  response comes back*; `EPIPE` is the same story from our side. Node surfaces
+  the safe case and the unsafe case as the same code, so the code cannot carry
+  the claim.
+
+  Because `shouldRetry` returns true for `unreachable` **without consulting
+  `idempotent`**, a reset produced up to three sends of a connector that had
+  explicitly declared `idempotent: false`. For a consumer publishing to social
+  networks that is a second public post that cannot be withdrawn.
+
+  This is the same defect as the 5xx / thrown-transport split fixed earlier, and
+  it contradicted this module's own stated rule -- *"an unknown failure treated
+  as unreachable would be retried, and the one thing worse than a lost send is
+  two sends nobody approved."* The two codes were standing exceptions to a rule
+  that should have covered them.
+
+  **What a consumer must DO:** nothing, if your connectors declare `idempotent`
+  honestly -- the fix only removes retries that were never safe. If you have a
+  connector marked `idempotent: true` that is not actually safe to repeat, this
+  release does not save you; that field is still load-bearing. If you were
+  relying on resets being retried for a genuinely idempotent connector, they
+  still are: `ambiguous` retries when `idempotent: true`.
+
+  `ECONNREFUSED`, `ENOTFOUND`, `EAI_AGAIN`, `EHOSTUNREACH` and `ENETUNREACH`
+  stay `unreachable` -- they do prove nothing was delivered -- and a test now
+  pins them there so the fix cannot overcorrect.
+
+  Found by a consumer's conformance fixture disagreeing with the core on its
+  first run, with a reproduction.
+
 ## [Unreleased]
 
 ## [0.2.0] — unreleased

package/dist/index.cjs

@@ -158,16 +158,33 @@ function satisfiesMinimum(coreVersion, minimum) {
 
 // src/delivery.ts
 var UNREACHABLE_CODES = /* @__PURE__ */ new Set([
+  // Every code here must PROVE the request never reached an application:
+  // nothing listening, no route, or a name that never resolved. If a code can
+  // also occur after the peer received and acted on the request, it belongs in
+  // AMBIGUOUS_CODES -- `shouldRetry` retries `unreachable` without consulting
+  // `idempotent`, so a wrong entry here is a duplicate send, not a slow one.
   "ECONNREFUSED",
   "ENOTFOUND",
   "EAI_AGAIN",
   "EHOSTUNREACH",
   "ENETUNREACH",
-  "ECONNRESET",
-  "EPIPE",
   "ERR_SOCKET_CONNECTION_TIMEOUT"
 ]);
 var AMBIGUOUS_CODES = /* @__PURE__ */ new Set([
+  // A peer sends RST whenever it tears the connection down -- INCLUDING after
+  // it has received and acted on the request but before the response comes
+  // back. EPIPE is the same story from our side: we wrote to a socket the peer
+  // had already closed, and whether an earlier complete request was processed
+  // first is not knowable from here. Node surfaces the safe case and the unsafe
+  // case as the same code, so the code cannot carry the claim.
+  //
+  // These two sat in UNREACHABLE_CODES until 0.3.0, which made them
+  // unconditionally retryable and produced three sends of connectors that had
+  // declared `idempotent: false`. Same defect as the 5xx / thrown-transport
+  // split this module already fixed once, and a stated exception to a rule that
+  // should have covered them.
+  "ECONNRESET",
+  "EPIPE",
   "ETIMEDOUT",
   "UND_ERR_HEADERS_TIMEOUT",
   "UND_ERR_BODY_TIMEOUT",