Skip to content

Tell requests the machine could not send from ones the API left unanswered, against a fast API that closes its connections - #443

Closed
ssegura wants to merge 1 commit into
masterfrom
docs/fast-api-closing-connections
Closed

ssegura wants to merge 1 commit into
masterfrom
docs/fast-api-closing-connections

Conversation

@ssegura

@ssegura ssegura commented Nov 10, 2026

Copy link
Copy Markdown
Collaborator

Related: None

What you can do now that you could not before

You can tell, from the known limitations, why a run against a fast API that closes its connections
nearly stops about every half minute and shows thousands of requests with no reply the API never
saw, what that means for the run, and what keeping clear of it costs. Until now the page said that
an API answering in HTTP/1.1 was not affected by the connections it closes; measured before 2.5.0,
it is.

Try it yourself

The change is one entry of a page and a pointer to it from the manual:

git fetch && git switch docs/fast-api-closing-connections
sed -n '/fast API that closes the connection after most replies/,/eighth of the requests/p' docs/known-limitations.md
grep -n -A3 'Thousands of `no reply`' docs/manual/10-troubleshooting.md

To see the limitation itself you need an API that answers thousands of requests a second and closes
the connection after most replies. Its run's timeline shows the stretches, with nothing stored:

./restest run <the document> --url <the API's address> --budget 1m
jq -c '[.timeline.intervals[].byClass.noReply // 0]' restest-out/report.json

Expected, on macOS, against cwa-verification (3-second slices, the first twenty of a
three-minute run):
  [0,0,0,0,0,128,6464,6694,6966,6756,4976,2346,0,729,0,0,2917,6409,6762,6802]

How it works

A connection is the line between RESTest and the API. An API may say, in HTTP/1.1, that it will hang
up after a reply (Connection: close); many servers do so after a 400 or a 500. RESTest then opens
a new line for the next request, and against an API that answers in a millisecond or two that is
thousands of new lines a second. A line RESTest lets go before the API has hung up keeps one of the
machine's local addresses (ports) busy for half a minute or more; once none is left, the next
requests cannot even be sent until the first come free. They fail on the machine itself, are counted
under no reply, and make the run slow down as if the API had stopped answering.

The entry says that, how much it cost on two real APIs, how to see it in the report and why it shows
up in stretches, and what engine.mostRequestsPerMinute can do about it and at what price. The
troubleshooting chapter's "The API falls over under the run", where a reader with thousands of
no reply lands, now points there: its first advice, one request at a time, does not help here.

What changed in the code

Nothing. docs/known-limitations.md: one new entry under "What a run says", and the last sentence of
the HTTP/1.0 entry before it. docs/manual/10-troubleshooting.md: one paragraph.

Evidence

  • Tests: none added, two pages only.

  • Architecture tests: unchanged — none weakened. The architecture and documentation rules,
    ./mvnw -q verify -pl restest-arch-tests -am -Dtest='io.restest.arch.**': 162, none failed
    (the links to report.md#timeline and known-limitations.md#what-a-run-says among them).

  • Mutation score: not applicable.

  • Per-request overhead: not applicable.

  • Smoke run, two containerised APIs: not applicable, no code changed.

  • Idle time: not applicable.

  • Artefact: the measurements behind the entry, on macOS (by default 16,384 local ports,
    49152–65535, each kept 30 s), with the release candidate, master 50f1e912, three minutes, every
    request stored:

    API Requests Failed, BindException Before the first failure Replies with Connection: close
    cwa-verification 847,453 173,360 (20%) 17.2 s, 6,449 a second every 400, 71% of its replies
    erc20-rest-service 875,689 116,260 (13%) 18.6 s, 6,693 a second every 500 and 400

    Every request that failed in these two runs failed this way, after a median of 0.43 ms. Read in
    3-second slices, most requests got no reply in stretches of 6 to 15 seconds that began every 30 to
    33 seconds (cwa-verification at 18, 51, 81, 114, 144 and 177 s; erc20-rest-service at 21, 51, 84,
    117 and 150 s). 80,000 and 114,000 connections were closed before the ports ran
    out, so only some of them keep a port. Each stored run took 1.6 GB. 2.2.0 and 2.4.0 lose these
    requests too: it is no regression of 2.5.0.

Decisions taken

  • Document it rather than fix it, for 2.5.0. The maintainer's choice, 10 November 2026. The fix
    would be the one Get a reply to every request from an API that answers in HTTP/1.0, as Python's http.server does #436 made for HTTP/1.0: end outright (SO_LINGER 0) a connection whose reply
    closes it, so that no port waits after it, for Connection: close in HTTP/1.1 too. It would change
    what every run against such an API sends, so it needs measuring on its own.
  • A rule rather than numbers for every system. How many local ports a machine has, how long each
    waits, and whether a waiting one can be reused for a new connection differ by system and setting;
    the entry gives the rule (ports ÷ seconds each is kept × 60) and macOS's figure, where it was
    measured, and nothing unmeasured for Linux or Windows.
  • The rate is given with its price. A review of the first draft pointed out that 30,000 a minute
    would cut a run against those APIs to about an eighth of the requests they answered even with the
    losses, so the entry now leads with reading the no reply as the machine's, and gives the rate
    last, with that cost. The same review found that the first draft said every closed connection keeps
    a port, which the runs contradict, that it pointed to --store (1.6 GB here) where the report's
    timeline shows the same, and that the troubleshooting chapter did not lead to the entry; all four
    are changed.

Open questions

None.


  • Targets master
  • English throughout, including comments and test names
  • The hard rules in AGENTS.md hold

🤖 Generated with Claude Code

…wered, against a fast API that closes its connections

An API answering in HTTP/1.1 with Connection: close after most replies makes RESTest open a
connection per request; on macOS the local ports run out within 17 to 19 seconds and the run then
nearly stops for up to fifteen seconds every half minute, its unsent requests counted under no
reply. The known limitations said HTTP/1.1 was not affected; they now say it is, how to see it in
the report's timeline, and what a rate below the ports' limit costs. The troubleshooting chapter
points there.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ssegura ssegura closed this Nov 10, 2026
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