Skip to content

refactor(node): one isLoopback, Retry-After reader and network code lookup in pivotkit-node/net - #737

Merged
eizedev merged 2 commits into
mainfrom
refactor/shared-network-helpers
Nov 22, 2026
Merged

eizedev merged 2 commits into
mainfrom
refactor/shared-network-helpers

Conversation

@eizedev

@eizedev eizedev commented Nov 22, 2026

Copy link
Copy Markdown
Owner

Step 2 of the layering rework after #736: one isLoopback, one Retry-After reader and one lookup of a failed connection's code.

What changed

pivotkit-node/net (packages/pivotkit-node/src/net.js) is the one copy of:

  • ipBytes, moved from pivotkit-server's sources/fetch.js.
  • isLoopback. The copy in pivotkit-node/rest and the one in sources/fetch.js are now this function. pivotkit-node/rest re-exports it, so pivotkit-cli/rest and the server entries keep the same function.
  • retryAfterSeconds, the core of the two retryAfterOf (server sources/http.js, CLI remote.js).
  • networkCodeOf, the core of the two networkError (server sources/fetch.js, CLI remote.js).

Each front end keeps its own error class, words and caps. Step 4 unifies the error classes.

Behaviour: no change

I copied the old functions into a scratch harness and compared them with the new ones on every input I could think of: spellings, zones, IPv4-mapped forms, empty values, 11-digit and 400-digit numbers, past and future dates, AggregateErrors and fetch-style causes. No differences. test/net.test.js pins these tables.

Differences that stay, as options

  • isLoopback. By default it reads a host as written: localhost, dotted 127/8, ::1. This applies to the CLI's URL hosts, http.host, publicUrl, and socket addresses after ::ffff: is stripped. { address: true } is guardedFetch's reading: any spelling of an IP address, a zone dropped, IPv4-mapped ::ffff:127.x (also [::ffff:7f00:1] as a URL writes it) counts.
    • guardedFetch needs the mapped form: a socket or lookup can hand it over.
    • The default must not take it. files.test.js pins [::ffff:7f00:1] as not loopback. A free-text http.host such as 0::1 would otherwise drop the auth requirement.
  • Retry-After cap. The server caps at 3600 s: a longer wait is passed on as 3600. The CLI drops anything over a day and returns null, not undefined, which shows in --json. Both callers keep their own caps.
  • Retry-After digits. retryAfterSeconds(value, { maxDigits: 10 }) keeps the server's ^\d{1,10}$. See the possible bug below.
  • Where the error code is. networkCodeOf(e, { client: "node" | "fetch" }).
    • The server uses node:https and looks at e.code, then e.errors[0].code.
    • The CLI uses fetch and node:http and looks at e.cause.code, e.code, then e.cause.cause.code. It also accepts only code-shaped strings, because the code becomes its --json error code.
    • A merged order would differ only for error shapes I found no transport producing, so I kept both orders exact.

Looks like a bug, not fixed here (for an issue)

  • The server reads a Retry-After of more than 10 digits as a date. Through Date.parse, "00000000001" becomes a date in 2001, which gives 0 s. Other values give nothing. The CLI reads the same text as 1 s. RFC 9110's delay-seconds is 1*DIGIT.
  • The server's networkError text slices the code to 40 characters. The CLI refuses a code longer than 41 characters and says "no answer". One OpenSSL code is longer: ERR_SSL_DECRYPTION_FAILED_OR_BAD_RECORD_MAC.

Not part of this change (say what does not fit)

  • Three lists of network codes overlap:
    • TRANSIENT in sources/fetch.js
    • NETWORK_CODES in sources/run.js
    • NETWORK_TEXTS in the CLI's remote.js
  • Two different plainAddress exist, in listen.js and request-id.js. One strips every ::ffff:, the other only before a dotted IPv4.
  • The sign-in client (sign-in.js call) builds its own NETWORK/TIMEOUT error without a code. Its --json codes differ from remote mode's, so it stays until step 4.
  • runner.js:163 and check/issuer.js:70 read a cause's code by hand for printing only.

Growth (scripts/growth.js measures, before → after)

before after
functions over 120 lines 48 48
functions over complexity 25 105 105
unused exports and files (knip) 222 222
jscpd duplicated lines 1631 (0.31%) 1631 (0.31%)
docs lines 25820 25820

No baseline entry changed: the functions that lost lines are below the limits, and the offenders createGuardedFetch, guarded and loadHttp kept their numbers.

Checks

  • npm run lint, npm run types, npm test (all workspaces and tests/), npm run growth, npm run pack:check: green locally.
  • The server, CLI and MCP integration tests are part of npm test.
  • No browser tests: no UI is touched.
  • A neutral review judged the whole files. Its findings are fixed:
    • the exact lookup order per client
    • the option named address
    • tolerating a missing options object
    • the root AGENTS.md line

Places checked for docs:

  • pivotkit-node: README, AGENTS.md, CHANGELOG and the package description
  • root AGENTS.md
  • the server and CLI CHANGELOGs

docs/reference/service-exports.md needs no change, because pivotkit-node is internal (docs/versioning.md).

🤖 Generated with Claude Code

eizedev and others added 2 commits November 22, 2026 21:12
…votkit-node/net

pivotkit-server and pivotkit-cli each read IP addresses, loopback, Retry-After headers
and the code of a failed connection with copies of their own. pivotkit-node/net is now
the one copy; each front end passes options where it needs another result and keeps
its own error class, words and caps.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…puts it

Keeps each caller's lookup order exact (review), names the loopback option address,
and tolerates a missing options object.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@eizedev
eizedev merged commit 6a3f2b9 into main Nov 22, 2026
25 checks passed
@eizedev
eizedev deleted the refactor/shared-network-helpers branch November 22, 2026 20:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant