DEV Community: Yusuf İhsan Görgel

I counted one MCP server on the wire: without the handshake, HTTP stays lighter until call ten

Yusuf İhsan Görgel — Sun, 11 Oct 2026 13:37:36 +0000

1. What did one flow cost under each revision?

I counted complete flows on loopback to see whether removing initialization and the session identifier reduced a short HTTP session, or moved bytes into request metadata and input retries.

Plain means tools/list followed by one tools/call. Input means one call whose handler asks the user one question. Ten means tools/list followed by ten calls in one session. The catalog contained three tools.

Every cross-revision row below is a raw message driver against Python SDK server (mcp 2.2.0). The main flows ran 20 times and the axis variations 5 times, 990 runs over 90 configurations. Every repeat was byte-identical. Each median therefore equals each single run.

HTTP heads include the request or status line and headers. Body columns exclude chunk framing.

I wrote this prediction down on 2026-09-30 at 00:14 UTC, five hours before the first counted run, and translated it for this post.

P1: The plain flow has seven JSON-RPC messages under 2025-11-25 and four under 2026-07-28.

P2: Each 2026-07-28 request carries 110 to 200 metadata bytes; the old handshake costs 400 to 900 body bytes once. A one-call flow should move fewer body bytes under the new revision.

P3: After a request-count threshold between two and eight, 2026-07-28 should move more body bytes. A ten-call flow should be heavier.

P4: Both input flows take four messages per call. The new flow should add 150 to 400 body bytes, with a larger gap as arguments grow.

P5: New HTTP requests add 70 to 110 bytes of protocol headers each. HTTP framing should exceed half the old plain-flow total, while body differences stay small beside it.

P6: Stdio adds one newline byte per message, leaving the message body to decide most of the total.

P7: Fixed request IDs should produce identical bytes across 20 repeats, and any varying field should be found.

P1 held: the plain flow counted seven JSON-RPC objects under 2025-11-25 and four under 2026-07-28.
P2 failed: new HTTP request bodies carried 530 bytes against 353. Measured _meta spans totaled 377 bytes across two POSTs.
P3 was about body bytes and failed: the new revision carried more body bytes from the first call. Its second half held: ten calls were heavier. On total HTTP bytes a linear estimate puts the crossover near call ten (section 6).
P4 held for its range of 150 to 400: the new input flow added 270 body bytes, while its complete HTTP total was 791 bytes lower. I did not vary arguments in the input flow. Its last clause is untested.
P5 is three claims. Per-request protocol headers were not counted separately. The first is untested. The second held: framing was 60 percent of the old plain total. The third held too: the body difference (177 request bytes) is small beside the framing. Under 2026-07-28 framing fell to 32 percent of the total.
P6 held: stdio logs contain one newline byte per JSON-RPC message.
P7 held: summary.tsv marks every repeated run byte-identical across 90 configurations and 990 runs.

Flow	Revision	Server	JSON-RPC C→S / S→C	HTTP requests	Request head	Request body	Response head	Response body	Chunk bytes	SSE events	Total bytes
plain	2025-11-25	Python SDK server (mcp 2.2.0)	4 / 3	4	821	353	990	866	34	3	3,064
plain	2026-07-28	Python SDK server (mcp 2.2.0)	2 / 2	2	418	530	252	865	0	0	2,065
input	2025-11-25	Python SDK server (mcp 2.2.0)	4 / 3	4	821	404	900	588	28	3	2,741
input	2026-07-28	Python SDK server (mcp 2.2.0)	2 / 2	2	436	675	252	587	0	0	1,950
ten	2025-11-25	Python SDK server (mcp 2.2.0)	13 / 12	13	2,855	1,211	3,420	1,904	133	12	9,523
ten	2026-07-28	Python SDK server (mcp 2.2.0)	11 / 11	11	2,371	3,088	1,386	2,721	0	0	9,566

The stdio rows below are also from raw driver runs against Python SDK server (mcp 2.2.0). Stdio has no HTTP heads or bodies; newline bytes count line endings in the JSON-RPC stream.

Flow	Revision	JSON-RPC C→S / S→C	Newline bytes	Total bytes
plain	2025-11-25	4 / 3	7	1,148
plain	2026-07-28	2 / 2	4	1,399
input	2025-11-25	4 / 3	7	921
input	2026-07-28	2 / 2	4	1,266
ten	2025-11-25	13 / 12	25	2,828
ten	2026-07-28	11 / 11	22	5,831

The call itself is four JSON-RPC messages under both revisions; the old end-to-end row shows seven because it includes initialize, its result, and notifications/initialized.

A short HTTP flow saved total bytes, while its request bodies grew.

2. What ran, and what did I leave out?

I measured package:dart_mcp at dart-lang/ai commit cdf9ad1cb50f148f8dd332eaea765e79e5d9b475. That checkout reports 0.6.0-wip; it is not a release. The latest pub.dev release is 0.5.2.

At this pin, package:dart_mcp serves 2025-11-25 over stdio and 2026-07-28 over Streamable HTTP. Its own rows cannot compare revisions over one transport.

I used Python SDK server (mcp 2.2.0) to fill those cells; every such table row is labeled.

I call each JSON-RPC object a message. An HTTP round trip is one request and its response, including a 202 response to a notification. It is a count, not elapsed time.

A byte is an application byte observed by the relay or stdio tap. HTTP totals include request and response lines, headers, bodies, and chunk framing.

The relay runs on loopback without TLS. Keepalive frames and retransmissions are excluded; I report no elapsed time.

The scripts, raw results in results/, and run logs are all in the published instrument folder.

The environment was captured from that checkout:

$ sw_vers
ProductName:    macOS
ProductVersion: 26.3
BuildVersion:   25D125
$ uname -m
arm64
$ dart --version
Dart SDK version: 3.11.0 (stable) (Mon Feb 9 00:38:07 2026 -0800) on "macos_arm64"
$ venv/bin/python --version
Python 3.14.3
$ git -C ai rev-parse HEAD
cdf9ad1cb50f148f8dd332eaea765e79e5d9b475
$ grep ^version: ai/pkgs/dart_mcp/pubspec.yaml
version: 0.6.0-wip
$ venv/bin/python -c "import importlib.metadata as m; print(m.version(\"mcp\"))"
2.2.0

I contribute to package:dart_mcp and wrote the multi-version client and server used as the instrument (PR #676) and both ends of its Streamable HTTP transport (PR #572, PR #638).

The comparison is scoped to one pinned Dart package, one Python SDK server, and loopback traffic.

3. What does each revision require on the wire?

For 2025-11-25, the lifecycle specification requires initialization before normal operations:

The client MUST initiate this phase by sending an initialize request containing:

Protocol version supported

Client capabilities

Client implementation information

After successful initialization, the client must send an initialized notification. For Streamable HTTP, a server may assign an MCP-Session-Id; if it does, later requests must include it. Lifecycle requirements at the pinned specification commit Initialized notification rule HTTP session rules at the pinned specification commit

For 2026-07-28, the versioning text says:

“There is no negotiation handshake. Every request carries its protocol version, and the server accepts or rejects each request independently:”

On Streamable HTTP, every POST includes MCP-Protocol-Version and Mcp-Method; tools/call also carries Mcp-Name. Request context travels in _meta. Pinned versioning text Pinned HTTP header rules

When a call needs input, the new revision returns input_required and the client retries. If the result contains requestState, the client must echo its exact value on that retry. Pinned retry rule

The protocol moves request context into each new-revision request and defines a retry for input.

4. Where did the plain-flow HTTP bytes go?

These exchanges are trimmed from the decoded logs; counts come from complete runs.

Python SDK server (mcp 2.2.0), 2025-11-25
client -> POST initialize
server -> HTTP 200, text/event-stream: initialize result
client -> POST notifications/initialized [MCP-Protocol-Version, Mcp-Session-Id]
server -> HTTP 202 Accepted
client -> POST tools/list [MCP-Protocol-Version, Mcp-Session-Id]
server -> HTTP 200, text/event-stream: tools/list result
client -> POST tools/call [MCP-Protocol-Version, Mcp-Session-Id]
server -> HTTP 200, text/event-stream: tools/call result

Python SDK server (mcp 2.2.0), 2026-07-28
client -> POST tools/list [MCP-Protocol-Version, Mcp-Method, _meta]
server -> HTTP 200, application/json: tools/list result
client -> POST tools/call [MCP-Protocol-Version, Mcp-Method, Mcp-Name, _meta]
server -> HTTP 200, application/json: tools/call result

For 2025-11-25, request heads, response heads, and chunk framing sum to 1,845 bytes of 3,064: (821 + 990 + 34) / 3,064, or 60 percent.

For 2026-07-28, they sum to 670 bytes of 2,065: (418 + 252 + 0) / 2,065, or 32 percent.

The new request bodies grew from 353 to 530 bytes. Response bodies were nearly equal, at 866 and 865 bytes. Four HTTP requests and three SSE events became two requests and no SSE events.

Two things moved those bytes. Two fewer requests took request heads from 821 to 418 bytes. Response heads fell from 990 to 252: two fewer responses, and this server answers 2025-11-25 calls with an SSE stream and 2026-07-28 calls with plain JSON. The older spec allows either answer. Part of that saving is a server choice.

The raw driver sends no DELETE when an old-revision session ends; the spec says clients SHOULD. A client that sends one adds a fifth request to the old rows. Under 2026-07-28 there is no session id and nothing to end with a DELETE. The pinned changelog removes protocol-level sessions

For one new-revision HTTP flow, the raw driver with the Dart server moved 2,211 bytes; the Python SDK server row moved 2,065. The package client row moved 2,394.

Its request head was 574 bytes against 418 for the raw driver, and its chunk framing was 46 bytes against 23.

On stdio, the Python SDK server plain flow moved 1,148 bytes under 2025-11-25 and 1,399 under 2026-07-28. There is no HTTP head layer there.

On this server, fewer requests and JSON answers instead of SSE covered the larger request bodies.

5. What happens when a tool asks for an answer?

Under 2025-11-25, the server sends elicitation/create on the SSE response opened by tools/call. The client posts its answer on a new request tied to the session. Under revision 2026-07-28, input_required comes back as JSON, and the client retries tools/call with its original arguments and inputResponses.

The traces and numbers in this section are the raw driver against Python SDK server (mcp 2.2.0). The tool here takes no requestState. The arrows in both images label body bytes; the totals also include HTTP lines and headers.

In logs for revision 2026-07-28, both POSTs are tools/call. The retry repeats the empty arguments and adds the accepted answer. The full HTTP input total fell from 2,741 to 1,950 bytes.

Request bodies alone rose from 404 to 675 bytes, a 271-byte increase. Combined request and response bodies rose by 270 bytes because response bodies fell from 588 to 587.

Under 2025-11-25, the flow sent three SSE events and used four HTTP requests. The new flow sent no SSE events and used two requests.

package:dart_mcp does the same job on both revisions in its own way. PR #654 routes server-to-client requests on older revisions, and PR #655 removed elicit, listRoots and createMessage from the server. A compatibility shim turns an input-required result into the older server request. On the client, PR #632 answers the input requests in an input_required result, and PR #637 lets handlers return one. None of the Dart code is in this section's numbers.

The retry enlarged request bodies while the complete input flow moved fewer HTTP bytes.

6. At what call count does the HTTP total cross?

Using Python SDK server (mcp 2.2.0) plain-flow totals, I estimated a fixed session cost and marginal bytes per added call from the measured one-call and ten-call endpoints. The fixed term includes tools/list and session setup.

Revision	One-call total	Ten-call total	Fixed bytes per session	Marginal bytes per added call
2025-11-25	3,064	9,523	2,346.3	717.7
2026-07-28	2,065	9,566	1,231.6	833.4

Only one call and ten calls were measured. If each added call costs the same, the totals meet at 9.63 calls: sessions of up to nine calls would be lighter under 2026-07-28. That middle part is an estimate. The measured ten-call totals were 9,566 against 9,523, 43 bytes heavier under the new revision.

Stdio goes the other way from the short HTTP result. At one call, the new revision moved 1,399 bytes against 1,148.

At ten calls, it moved 5,831 against 2,828. That gap is consistent with the per-request _meta: 377 bytes over both new-revision requests of the plain flow, 2,078 over eleven requests in the ten-call flow.

On HTTP, the short-flow lead narrows until the measured ten-call total is 43 bytes higher.

7. What does carried request state do to the retry?

This separate input-and-state flow uses the raw driver against Python SDK server (mcp 2.2.0). It calls a tool that does some work, asks for a confirmation, and carries a request state of the configured size. Its tool and arguments differ from section 5, which is why its zero-state totals (2,765 and 2,057) differ from the input rows there (2,741 and 1,950). The old revision has no requestState. Only the new rows grow with the state size.

State bytes	Revision	Total bytes	Request body bytes	Response body bytes
0	2025-11-25	2,765	429	586
0	2026-07-28	2,057	745	606
2,048	2025-11-25	2,771	432	589
2,048	2026-07-28	6,164	2,799	2,657

The specification treats requestState as opaque. When an input_required result contains it, the client must return the exact value with its retry. Pinned retry text

With no state, flow under revision 2026-07-28 moved 2,057 bytes against 2,765 under 2025-11-25. With 2,048 state bytes, it moved 6,164 against 2,771.

The response delivers state to the client, and the retry sends it back with the answer.

This is the Python SDK server's configured state representation, measured on loopback with this raw driver. It does not establish a universal encoding cost for requestState.

With a 2,048-byte state string on this server, the retry cost more than the saved setup.

8. How were the bytes counted?

The relay forwards socket data unchanged in both directions and logs each chunk as base64. It does not parse HTTP or add TLS.

#!/usr/bin/env python3
"""TCP relay: copies bytes unchanged in both directions, logs each chunk as one JSON line.

Usage: relay.py --listen HOST:PORT --upstream HOST:PORT --log FILE
"""
import argparse
import base64
import contextlib
import json
import selectors
import signal
import socket
import sys


def hostport(text):
    host, _, port = text.rpartition(":")
    return host, int(port)


def main():
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument("--listen", required=True, type=hostport)
    ap.add_argument("--upstream", required=True, type=hostport)
    ap.add_argument("--log", required=True)
    args = ap.parse_args()

    signal.signal(signal.SIGTERM, signal.default_int_handler)  # same path as Ctrl-C
    sel = selectors.DefaultSelector()
    server = socket.create_server(args.listen)
    sel.register(server, selectors.EVENT_READ, None)
    log = open(args.log, "w")
    seq = conns = 0
    open_dirs = {}  # connection number -> directions still open
    print("listening on %s:%d" % server.getsockname()[:2], file=sys.stderr, flush=True)

    def record(conn, direction, **fields):
        nonlocal seq
        seq += 1  # one counter shared by all connections
        log.write(json.dumps({"conn": conn, "seq": seq, "dir": direction, **fields}) + "\n")
        log.flush()

    try:
        while True:
            for key, _ in sel.select():
                if key.data is None:  # new client: open the matching upstream connection
                    client, _ = server.accept()
                    upstream = socket.create_connection(args.upstream)
                    conns += 1
                    open_dirs[conns] = 2
                    sel.register(client, selectors.EVENT_READ, (conns, "c2s", upstream))
                    sel.register(upstream, selectors.EVENT_READ, (conns, "s2c", client))
                    continue
                conn, direction, peer = key.data
                try:
                    data = key.fileobj.recv(65536)
                except OSError:
                    data = b""
                if data:
                    record(conn, direction, b64=base64.b64encode(data).decode())
                    with contextlib.suppress(OSError):
                        peer.sendall(data)
                    continue
                record(conn, direction, eof=True)
                sel.unregister(key.fileobj)
                with contextlib.suppress(OSError):
                    peer.shutdown(socket.SHUT_WR)  # pass the end of stream along
                open_dirs[conn] -= 1
                if open_dirs[conn] == 0:
                    key.fileobj.close()
                    peer.close()
    except KeyboardInterrupt:
        pass
    finally:
        log.close()
        server.close()
        for key in list(sel.get_map().values()):
            key.fileobj.close()


if __name__ == "__main__":
    main()

The HTTP counter reconstructs streams from logged chunks and separates heads, bodies, chunk framing, SSE events, and JSON-RPC messages. It reads logs without forwarding traffic or rewriting bytes. Published count.py

The stdio tap spawns a server child, copies stdin and stdout byte-for-byte, and logs chunks in the relay format. It leaves stderr inherited and does not inspect payloads or use sockets. Published tee_stdio.py

The stdio counter reconstructs both pipe streams and counts complete newline-terminated lines as JSON-RPC messages. It does not parse HTTP and measures _meta only on client-to-server lines.

#!/usr/bin/env python3
"""Summarise a stdio relay log (one JSON-RPC message per line) as the same TSV row as count.py.

Usage: count_stdio_log.py LOG [--label LABEL] [--header]
The log has the relay format; "conn" may be missing. Every chunk that ends with a newline
byte holds whole messages, and each newline byte is counted in newline_bytes.
"""
import argparse

from count import COLUMNS, emit, load_log, meta_bytes, rpc_count


def main():
    ap = argparse.ArgumentParser(description="Summarise one stdio log as a TSV row.")
    ap.add_argument("log")
    ap.add_argument("--label", default="run")
    ap.add_argument("--header", action="store_true", help="print the header line first")
    args = ap.parse_args()
    streams, total = load_log(args.log)
    row = dict.fromkeys(COLUMNS, 0)
    for (_, direction), buf in sorted(streams.items()):
        lines = buf.split(b"\n")[:-1]  # text after the last newline is not a message yet
        row["newline_bytes"] += len(lines)
        for line in lines:
            row["jsonrpc_" + direction] += rpc_count(line)
            if direction == "c2s":
                row["meta_bytes_c2s"] += meta_bytes(line)
    row.update(label=args.label, mcp_headers="none", total_bytes=total)
    emit(row, args.header)


if __name__ == "__main__":
    main()

The relay preserves application bytes; the counters classify the captured streams.

9. What did I catch before counting?

The matrix runner is Python, and it starts the Dart client with a state size. My first version built that argument as state_bytes or 256. Python treats zero as false. A zero-state run would have carried 256 state bytes under a label that said zero.

I caught it while writing the runner, before any counted run, and changed it to pass the configured integer as it is. The rows labeled 256 in the results are a separate, deliberate setting.

The runner error was fixed before it entered results.tsv.

10. What can these numbers not tell me?

Bytes are not tokens. I measured application bytes on loopback, without TLS or a model in the path. I did not measure elapsed time, retransmissions, keepalive frames, or IP packet bytes.

The cache-hint re-list was not measured.

I did not open the subscriptions/listen stream described by PR #636, or measure request-triggered notifications/message from PR #595. tools/list returned one page; PR #682 adds page walking.

A client helper for initializing a server across versions later landed on main in PR #690. I did not measure it.

The prior-work scan found two posts counting request-body bytes for one tools/call across revisions, both against 2025-06-18, and an SDK issue counting HTTP requests and TCP connections.

I could not find a counted whole-flow comparison against 2025-11-25 with message counts, HTTP round trips, request and response bytes, and header bytes from an SDK. Links welcome: rizz.dev, amitrix on dev.to, and the SDK issue.

A Hacker News discussion argues about protocol overhead. This notebook counts bytes for the stated flows on loopback.

These totals describe one pinned implementation, one server, and one transport at a time.

11. How do I reproduce one row?

Clone the published instrument at its pinned commit, then follow its README build and one-configuration run. I ran these steps from an empty directory before publishing; the full matrix reproduced all 1,800 median cells.

git clone --filter=blob:none --no-checkout https://github.com/Yusufihsangorgel/yusufihsangorgel.github.io site
git -C site sparse-checkout set mcp-count
git -C site checkout 83a170383621eb2f2db7e080c837585bb5604d69
cp -R site/mcp-count ~/mcp-count && cd ~/mcp-count

git clone https://github.com/dart-lang/ai ai
git -C ai checkout cdf9ad1cb50f148f8dd332eaea765e79e5d9b475
(cd ai/pkgs/dart_mcp && dart pub get)
(cd dart && dart pub get && dart analyze)
mkdir -p build
for n in server client_stdio client_http; do (cd dart && dart compile exe bin/$n.dart -o ../build/$n); done

uv venv --python 3.14 venv
uv pip install --python venv/bin/python -r pysdk/requirements.txt

python3 run_matrix.py --dart-build build --py venv/bin/python --py-server pysdk/server.py --out out-one \
  --only pkg-dart-http-2026-07-28-plain-cion-none-a0-s0-c3
python3 tools/median.py out-one/results.tsv | awk -F '\t' '$2 == "total_bytes"'

Expected output from results/medians.tsv:

pkg-dart-http-2026-07-28-plain-cion-none-a0-s0-c3   total_bytes 2394    2394    2394

The pinned one-configuration command regenerates the package HTTP total_bytes row.

12. What should another SDK measure?

If you maintain another MCP SDK, run plain, input, and ten-call flows on every transport it supports. Please share the server and revision with the same message, request, header, body, framing, event, and total columns.

Response format and per-request metadata both moved these totals; another server may answer differently.

Why one failed font load kept breaking pendingFonts() in Flutter

Yusuf İhsan Görgel — Thu, 24 Sep 2026 16:05:05 +0000

In google_fonts 8.2.0, one failed font load stayed in the set that GoogleFonts.pendingFonts() waits on, and every later call threw.

It kept throwing after a retry loaded the same font.

If your widget tests or your startup code await pendingFonts() on 8.2.0, one bad download is enough. Version 8.2.1 stops the failure from sticking.

A google_fonts user, @bramp, reported it in issue #182430 in February, named the cause and proposed the fix: whenComplete with catchError, plus a test for it. I applied it in flutter/packages#12240 with ignore() in place of catchError and a regression test, released as version 8.2.1 on July 31.

What a test sees

The test in the last section calls GoogleFonts.lato(), then awaits pendingFonts() three times, each call inside try/catch.

In this test TestWidgetsFlutterBinding answers the default HTTP client with status 400, and the font download fails without any mock. The output blocks below are excerpts of the recorded runs.

On 8.2.0 all three runs exited with code 1. The test failed on an uncaught error:

00:00 +0 -1: pendingFonts after a failed load [E]
  Exception: Failed to load font with url: https://fonts.gstatic.com/s/a/5ced1045820caaac87af3f61ded09bacc90881f158d04c59dcce436fd02ad368.ttf
  package:google_fonts/src/google_fonts_base.dart 275:5            _httpFetchFontAndSaveToDevice
  ===== asynchronous gap ===========================
  dart:async                                                       _CustomZone.registerBinaryCallback
  package:google_fonts/src/google_fonts_base.dart 144:23           loadFontIfNecessary
  package:google_fonts/src/google_fonts_base.dart 107:38           googleFontsTextStyle
  package:google_fonts/src/google_fonts_parts/part_l.dart 1375:12  PartL.lato
  test/pending_fonts_test.dart 11:21                               main.<fn>

After the test binding's warning about status 400, the output ends with all three calls throwing, although each one was caught:

first pendingFonts(): threw _Exception
second pendingFonts(): threw _Exception
third pendingFonts(): threw _Exception
00:00 +0 -1: Some tests failed.

On 8.2.1 all three runs exited with code 0. The first call still threw, because that load really failed. The later calls completed:

first pendingFonts(): threw _Exception
second pendingFonts(): completed
third pendingFonts(): completed
00:00 +1: All tests passed!

On 8.2.1 a failed load fails the calls already waiting for it, and none that come after it.

A completed pendingFonts() means no failed load is still pending. It does not mean the font is available: the first call still sees the failure, and only another request for the font retries it.

One line, two problems

pendingFontFutures is a top-level set of loading futures, and pendingFonts() is Future.wait(pendingFontFutures).

The production-code change is one line (lines 107-109 after the fix); the pull request also updated the set's doc comment and added a test:

   final Future<void> loadingFuture = loadFontIfNecessary(descriptor);
   pendingFontFutures.add(loadingFuture);
-  loadingFuture.then((_) => pendingFontFutures.remove(loadingFuture));
+  loadingFuture.whenComplete(() => pendingFontFutures.remove(loadingFuture)).ignore();

In 8.2.0 that then callback is the only code that removes anything from the set: the library names the set in four places (its declaration, the add, this remove and the Future.wait).

A then callback without onError runs only when the future succeeds. A failed load stays in the set, and every later Future.wait over the set fails. That is the cause @bramp's issue named.

The same line has a second problem. then returns a new future, and without onError the error "is forwarded directly to the returned future."

Nothing listens to that returned future. Its error is uncaught, and flutter test fails the test for it, even when every pendingFonts() call is caught.

In 8.2.1, whenComplete runs the removal on success and on error. Its returned future fails the same way as the load, and ignore() handles that error. Callers of pendingFonts() still get the load's own failure.

Each half on its own

Five versions of line 109 were measured. Each ran the pull request's test and a retry test three times, with the same result every time (remove is the removal callback):

line 109	`pendingFonts()` after the failure	uncaught error
`.then(remove)` (8.2.0)	throw the old error	yes
`.then(remove).ignore()`	throw the old error	no
`.whenComplete(remove)`	complete	yes
`.whenComplete(remove).ignore()` (8.2.1)	complete	no
`.whenComplete(remove).catchError((_) {})` (the issue's version)	complete	no

Each problem shows up as its own error report in the test output. With .whenComplete(remove) alone the set is clean, and the pull request's test still fails on the uncaught error:

00:00 +0 -1: pendingFonts removes failed font loads [E]
  Exception: Failed to load font with url: https://fonts.gstatic.com/s/a/1194f6ffe4d2f05258573616a77932c38041f3102763096c19437c3db1818a04.ttf
  package:google_fonts/src/google_fonts_base.dart 275:5   _httpFetchFontAndSaveToDevice
  ===== asynchronous gap ===========================
  dart:async                                              _CustomZone.registerBinaryCallback
  package:google_fonts/src/google_fonts_base.dart 152:9   loadFontIfNecessary
  package:google_fonts/src/google_fonts_base.dart 107:38  googleFontsTextStyle
  test/load_font_if_necessary_test.dart 374:5             main.<fn>

00:00 +0 -1: Some tests failed.

whenComplete cleans the set and ignore() handles the future it returns. Drop either half and one failure comes back.

The issue's version used catchError((_) {}) where 8.2.1 uses ignore(). It passed the same tests, and these tests do not tell them apart.

The pull request's own test fails at the parent commit in three runs out of three and passes at the merge commit. The whole test file goes from 11 passed and 1 failed to 12 passed.

On 8.2.0, a successful retry does not help

When a load fails, loadFontIfNecessary forgets the font, and a later request for the same font tries to load it again.

The retry test answers 404 first, then 200, and requests the same font twice. The retry's own future completes.

With a then line one future is still in the set, and pendingFonts() throws the first error again. The output below is from .then(remove).ignore(), to keep it to one error report:

retry loaded; pending futures: 1
00:00 +0 -1: pendingFonts after a failed load and a successful retry [E]
  Exception: Failed to load font with url: https://fonts.gstatic.com/s/a/1194f6ffe4d2f05258573616a77932c38041f3102763096c19437c3db1818a04.ttf
  package:google_fonts/src/google_fonts_base.dart 275:5  _httpFetchFontAndSaveToDevice

00:00 +0 -1: Some tests failed.

With whenComplete the set is empty after the retry.

In 8.2.0, loading the font later did not clear the failure.

What this does not cover

Every run here is flutter test on the Dart VM. The HTTP 400 in the first test comes from the test binding, not from a real outage.

What the uncaught error does in a running app was not measured: the zone handler, PlatformDispatcher.onError and crash reporters are outside these runs. The web was not measured either.

No workaround for 8.2.0 was measured.

Use 8.2.1

The pull request merged on July 31, 2026, and google_fonts 8.2.1 was published 17 minutes later. Its changelog entry reads "Fixes pendingFonts() retaining failed font loads."

On September 24 it is still the latest release.

Check it yourself

In an empty directory, create this pubspec.yaml:

name: app
publish_to: none
environment:
  sdk: ^3.10.0
dependencies:
  flutter:
    sdk: flutter
  google_fonts: 8.2.0
dev_dependencies:
  flutter_test:
    sdk: flutter

Create a test directory (mkdir -p test) and save this as test/pending_fonts_test.dart:

// Reproduction for flutter/packages#12240: pendingFonts() after one failed font load.
// TestWidgetsFlutterBinding answers the default HTTP client with status 400, and the font fetch fails on its own.
import 'package:flutter_test/flutter_test.dart';
import 'package:google_fonts/google_fonts.dart';

void main() {
  TestWidgetsFlutterBinding.ensureInitialized();

  test('pendingFonts after a failed load', () async {
    GoogleFonts.config.allowRuntimeFetching = true;
    GoogleFonts.lato();

    for (final call in ['first', 'second', 'third']) {
      try {
        await GoogleFonts.pendingFonts();
        print('$call pendingFonts(): completed');
      } catch (e) {
        print('$call pendingFonts(): threw ${e.runtimeType}');
      }
    }
  });
}

Then run:

flutter pub get
flutter test test/pending_fonts_test.dart

Change the dependency to google_fonts: 8.2.1, run flutter pub get again and rerun the test. The recorded runs used Flutter 3.41.2 and Dart 3.11.0.

Run it, bound it, check it every week: how I made a Dart MCP client checkable

Yusuf İhsan Görgel — Wed, 23 Sep 2026 09:02:58 +0000

A protocol library has to connect, list results, stop and follow the spec.

You should be able to check those promises without taking my word for it.

Over one week of pull requests to package:dart_mcp, I made three of them checkable:

Run it: a client example that talks to the existing server example.
Bound it: list helpers that walk every page and stop after 64.
Check it: a weekly run against the protocol's own conformance suite.

Start with the client example.

1. Run both sides in two terminals

The repository had a server example, example/streamable_http_server.dart. It had no client to pair with it.

Its readme suggested a curl command. That shows the wire format. It does not show how the Dart client API fits together.

PR #671 added example/streamable_http_client.dart. Start the server, copy the URL it prints, and pass it to the client:

cd pkgs/dart_mcp
dart run example/streamable_http_server.dart
# Listening on http://127.0.0.1:61009/mcp   (the port changes per run)

dart run example/streamable_http_client.dart http://127.0.0.1:61009/mcp

This is the client's output from a run on the current main:

connecting to server at http://127.0.0.1:61009/mcp
discovering server
Listing tools from server
Found Tool: greet
Calling `greet` tool
Progress: 1/1: Greeting world
Tool call succeeded: [{text: Hello, world!, type: text}]

The client is 94 lines. You can read it in one sitting and copy it into a project as a starting point.

2. List everything, but stop at 64 pages

MCP list requests page their results. A server returns items and a nextCursor. The client sends the cursor back to get the next page.

Before PR #682, the package left that loop to the caller.

Now there are four helpers: listAllTools, listAllResources, listAllResourceTemplates and listAllPrompts. Each one returns a Stream and yields items as pages arrive.

// Walks every page. Throws a StateError if page 64 still has a cursor.
await for (final tool in server.listAllTools()) {
  print(tool.name);
}

// Trust the server? Lift the bound explicitly.
final everything = await server.listAllTools(maxPageCount: null).toList();

A server that never stops paging should not trap your walk.

A server that hands out a cursor on every page keeps a naive while (cursor != null) loop running forever. By default the helpers stop. When a 64th page still ends in a cursor, they throw a StateError.

The pull request only adds code to client.dart: 120 lines added, none removed. The single-page methods are untouched. Existing callers keep their exact behaviour.

The tests pin the edges a real server can hit:

an empty string nextCursor is a cursor, not the end;
an empty page in the middle does not end the walk;
the first page yields before the second page is requested;
maxPageCount stops a server that alternates two cursors.

3. Sampling content as a list, and the error inside a 415

Sampling content can be one block or a list. In the schema, SamplingMessage.content and CreateMessageResult.content take one block or an array of blocks. The old getter cast straight to one block, and a list on the wire threw.

PR #685 changed the getter's type:

-  SamplingMessageContentBlock get content =>
-      _value[Keys.content] as SamplingMessageContentBlock;
+  List<SamplingMessageContentBlock> get content {

One block now reads as a one-element list. On the way out, a single block still goes on the wire as that block.

A 415 now carries the right error code. PR #684 did not change the HTTP status. It changed the JSON-RPC error inside the response:

       HttpStatus.unsupportedMediaType,
       RpcException(
-        McpErrorCodes.headerMismatch,
+        error_code.INVALID_REQUEST,
         'The request body must be sent as ${ContentType.json.mimeType}',

The schema binds HeaderMismatch to 400 Bad Request. Content-Type is not one of the headers the specification requires. An oversized body already got a generic invalid request error with its own 413, and this branch now matches it.

4. Run conformance weekly and catch stale expected failures

PR #675 added a workflow that runs the MCP conformance suite against both fixtures under tool/:

on:
  pull_request:
    paths:
      - 'pkgs/dart_mcp/**'
  schedule:
    - cron: '0 0 * * 0' # weekly
  workflow_dispatch:

jobs:
  conformance:
    continue-on-error: true

The suite is still an alpha npm package, pinned to 0.2.0-alpha.11. With continue-on-error, the job still reports a failure, but the workflow run stays green.

According to the pull request, every scored 2026-07-28 scenario passed on the server run, and the tasks extension was the only failure.

The client run reads a baseline of expected failures. The package has no OAuth client yet. The file lists the auth scenarios. PR #681 later gave the client step a timeout.

The baseline is checked in both directions.

A listed scenario that starts passing also fails the job. When OAuth support lands, the list has to shrink with it. A stale entry shows up as a failing job.

5. Docs that match the code

PR #673 added a DEVELOPING.md for the package. It covers the schema files, the checks CI runs, the conformance fixtures and the changelog convention.

PR #677 cleaned up the README after elicitation, sampling and roots came out of the server. A section still described a call pattern that no longer existed. It now describes answering with an InputRequiredResult, and Streamable HTTP is marked supported in the support table.

What I would do the same way again

Add helpers beside old methods, not over them. No existing call to a single-page list method had to change.
Make the safe behaviour the default. A 64-page bound that throws, with null as the explicit way out.
Let an alpha dependency report, not gate. Its failures stay visible without turning the run red.

Run the example, read the pagination tests, and open the conformance workflow.

Correction, 2026-09-23: an earlier version said #684 fixed a status code. It changed the JSON-RPC error code sent with 415, and the status stayed 415.

Your leak test is probably measuring the test runner

Yusuf İhsan Görgel — Mon, 03 Aug 2026 08:48:55 +0000

I have a test that checks a native buffer gets freed. Yesterday I ran it two
ways, twenty seconds apart, on the same machine against the same code.

Alone, it measured 5.11 MB of growth.

As part of the full suite, it measured 489.13 MB.

Nothing about the code under test changed. The only difference was what else
was running at the same time.

Why this happens

ProcessInfo.currentRss returns the resident set size of the process. For
a package that allocates through FFI that is exactly what you want, because
native allocations never show up in Dart heap statistics. It is also the
problem: the number includes everything else the process is doing.

And dart test runs your suite files concurrently, in one process, by default.

So a leak test that reads currentRss is reading a counter that another test
file is also writing to. When my JSON parsing suite ran next to it, the number
moved by nearly half a gigabyte. The bound that decides whether that test passes
is 16.4 MB. The noise is thirty times the entire decision.

The failure mode is nastier than a wrong number. The test passes when you run
it by itself, which is what you do while writing it, and fails in CI where the
whole suite runs. That reads like flakiness. You retry the job, it fails again,
you widen the threshold until it stops complaining, and now the test cannot
detect anything.

Move the measurement into a child process

Move the allocation loop into its own script and run it with
Process.runSync. The child sees only its own work.

// test/leak_probe.dart
void main(List<String> args) {
  final mode = args[0];
  final iterations = int.parse(args[1]);

  // ... build `cycle` for the mode under test ...

  for (var i = 0; i < warmup; i++) {
    cycle();
  }
  final before = ProcessInfo.currentRss;
  for (var i = 0; i < iterations; i++) {
    cycle();
  }
  final grown = (ProcessInfo.currentRss - before) / 1048576;
  print('RSS_DELTA_MB=${grown.toStringAsFixed(2)}');
}

And from the test:

final result = Process.runSync(Platform.resolvedExecutable, [
  'run',
  'test/leak_probe.dart',
  mode,
  '$iterations',
]);

expect(result.exitCode, 0, reason: result.stderr as String);

final reported =
    RegExp(r'RSS_DELTA_MB=(-?[0-9.]+)').firstMatch(result.stdout as String);
expect(reported, isNotNull,
    reason: 'leak_probe printed no measurement: ${result.stdout}');
final grownMb = double.parse(reported!.group(1)!);

The exit-code check runs before the parent parses the marker. A child that failed is reported with its own stderr instead of being read as a result.

Two details in there are not decoration.

The warm-up loop. The first iteration pays for library loading, runtime
dispatch and the allocator's initial arena. Without it you attribute all of
that startup to whichever thing you measured first. I once benchmarked two APIs
and got 231 ms versus 2 ms, then added warm-up and got 1.3 ms versus 2.5 ms.
The ordering alone produced a hundredfold error.

The marker. The child prints RSS_DELTA_MB= and the test greps for it
rather than parsing the last line. dart run writes build-hook progress to
stdout. The output is not just your number. Parsing stdout.trim() works
until the day a hook logs something, and then it breaks in a way that looks
like your code changed.

Here is the same measurement taken all three ways, this morning:

How it ran	RSS delta
in-process, alone	5.11 MB
in-process, full suite	489.13 MB
child process	3.25 MB

Derive the threshold, do not pick it

A separate process gives you a clean number. It does not tell you what to
compare it against, and this is where I had been guessing.

My original bound was 50 MB. I picked it because it was round and comfortably
above what I saw when the test passed. The payload it was parsing is 4 KB.

A threshold chosen that way is not an assertion. It is a wish with a number
next to it, and it will accept anything that fits under the wish.

Derive it from the payload instead. Ask what the smallest leak on this code
path would actually cost over the iteration count, then bound well under that:

for (final probe in const [
  ('parseBytes',  'padded input and the tape behind at()',      65.5),
  ('decodeBytes', 'the tape and the native copy of the input',  65.5),
  ('ndjson',      'the tape and the native copy of the input',  92.1),
  ('pointer',     'the native copy of a long JSON pointer',     46.9),
]) {
  final (mode, what, smallestLeakMb) = probe;

  test('$mode releases $what', () {
    // ... run the probe, parse grownMb ...
    expect(grownMb, lessThan(smallestLeakMb / 4),
        reason: 'grew ${grownMb}MB over $iterations iterations; losing the '
            'smallest native buffer on this path would cost ${smallestLeakMb}MB');
  }, testOn: '!windows');
}

Each number is the cost of dropping the single cheapest free on that path.
The bound sits at a quarter of it. That leaves room for allocator behaviour
while staying far below any real leak, and it means all four paths have four
different bounds, because they allocate different things.

One more thing about the source data: use bytes that do not compress. I had a
test feeding a flat grey PNG through an image pipeline, and it compressed so
well that the buffers I was trying to observe never got big enough to see.

Verify the test can fail

All of the above is still just a story about a number until you check the one
thing that matters: delete a free and confirm the test turns red.

Do it per-call, not all at once. When I first ran this audit across my
packages, the leak test in one of them stayed green with all four native
frees removed, because the total still landed under the guessed threshold. Any
single one of them, deleted on its own, has to fail. If it does not, that call
site is unprotected regardless of what the suite says.

While doing exactly this, my mutation script reported everything green on the
first run. The script was fine. The Python assert that applied each mutation
was failing silently. Nothing was ever mutated. A check passing does not
mean it ran.

What RSS cannot answer

I deleted a test during this work and did not replace it.

It asserted that a NativeFinalizer reclaimed a document nobody closed, by
measuring resident set after a fixed amount of work. That is a bet on when the
garbage collector runs. It passed locally and failed on Linux CI. A rewrite
comparing dropped references against retained ones was no better: measured back
to back, the arms came out 123 MB and 177 MB. The margin it claimed was
not there.

RSS does not fall when native memory is freed, because the allocator keeps the
pages. It cannot answer "was this reclaimed," and the collector makes no timing
promise a test could hold it to.

Deleting that test made the suite honest. What replaced it is coverage of the
things that are actually deterministic: using a closed handle throws, closing
twice is safe, malformed input raises rather than corrupting memory.

Checklist

Measurement runs in a child process
The child warms up before the timed loop
Output uses a marker the parent greps for, not the last line
Each allocation site is measured in its own loop
The threshold is derived from the payload, not picked
Source data does not compress
Deleting any single free turns the test red

The last one is the cheapest and the only one that proves the rest.

Numbers here were measured on Dart 3.11.0, macOS 26.6, Apple M4, against
simdjson_dart.

The Biggest MCP Update Ever, Explained With a Restaurant

Yusuf İhsan Görgel — Wed, 29 Jul 2026 06:43:25 +0000

MCP 2026-07-28 is out, and sessions are gone. The whole thing in plain English.

Before: the balancer is sticky, so every request goes to Instance A and dies with it. After: the next free instance takes it.

There is a restaurant in your city with one very good waiter. He remembers everything. Your table number, your no-onions rule, the fact that your friend wants the bill split in two. You never repeat yourself.

Then the waiter gets sick.

The new waiter knows nothing. Not your order, not the onions, not the split bill. You start again from zero. The whole restaurant, it turns out, was running on one person's memory.

Until this week, the Model Context Protocol worked exactly like that restaurant.

First: what is MCP?

If you have never heard of MCP, the docs' own one-line pitch is the fastest start: a USB-C port for AI applications. It is an open standard. It lets AI applications (IDEs, chat assistants, agents) plug into tools and data the same way, no matter who built them.

Without a shared protocol you build one integration per pair. With one, you build one per side.

In our restaurant: your AI app is the host, and it sends one client to each kitchen it wants to order from. You, at the counter, are that client. The kitchen is the server, a program that offers tools, resources (files and data), and prompts. The dishes on the menu are the tools. And MCP itself is the ordering system: how you ask, how the kitchen answers, what happens when something goes wrong.

On July 28, the MCP team released the 2026-07-28 revision (their word for a version). When the release candidate went out in May they called it the largest revision of the protocol since launch. Having now read the whole diff, I would not argue: it changes the ordering system from top to bottom.

The waiter is gone: MCP is now stateless

In the old protocol, a client and a server first did a handshake called initialize, a "hello, who are you?" step. After that, the server kept a session for you. On HTTP there was even a special header, Mcp-Session-Id, that locked you to one specific server instance (one running copy of the server).

That session was the waiter's memory, and it had the waiter's weakness. If the instance holding it crashed, your session died with it. So if you ran three copies of the server, the load balancer in front of them had to be sticky: it had to send you back to the same copy every time, the way a host sends you back to the same waiter. Serverless platforms broke this outright. Services like AWS Lambda start and stop instances whenever a request arrives, so there is no same copy to go back to.

The new version removes sessions from the protocol completely. initialize is gone. Instead, every request carries everything the server needs, inside a small _meta block: which protocol version you speak and what your client can do. Just the technical facts, not your conversation; anything else the server needs arrives as normal request parameters.

So the restaurant reopened as a counter-service place: you order at the counter, receipt in hand. Your whole order is printed on the receipt, and any cashier can pick it up and serve it. If one cashier goes home, the next one reads the same receipt and continues. Nobody has to remember you.

Stateless does not mean your server has to forget everything. It means the protocol no longer remembers for you. If a server needs state across calls, it mints its own handle and returns it from a tool like any other output. The model passes that handle back as an ordinary argument on the next call, so the state is visible in the request instead of hidden in the transport. It is the ticket number on your receipt: the counter does not know who you are, but it knows what number 47 ordered.

Old: one waiter's memory. New: a receipt any cashier can read.

The smallest possible before and after:

// Before (2025-era): a handshake first, then a session to protect
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "my-app", "version": "1.0.0" }
  }
}

// After (2026-07-28): no handshake, the receipt carries everything
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {
    "_meta": {
      "io.modelcontextprotocol/protocolVersion": "2026-07-28",
      "io.modelcontextprotocol/clientCapabilities": {}
    }
  }
}

The animation at the top of this article is the same story in fifteen seconds. On the left the host is sticky: every request goes to Instance A, with a session tag pinned to it, and when A dies the client dies with it. On the right the host sends each new arrival to whichever counter is free, taking turns between A, B and C. When A dies, the queue keeps moving.

This is the payoff. You can now deploy an MCP server on serverless or edge platforms (small servers close to the user), or scale it behind any ordinary load balancer.

The card at the door: `server/discover`

Without a handshake, how do you learn what a server offers? One new call: server/discover. It returns the server's capabilities (what it can do) and the protocol versions it supports, in a single response, and every 2026-07-28 server must implement it. Clients do not have to call it: you can send tools/list straight away and handle an unsupported-version error if one comes back. server/discover is there for when you want the whole picture up front, and it is how you probe an older server over stdio.

There is now a card at the door listing what this branch can do. You still ask for the dishes separately, with tools/list. The card even says how long it stays fresh.

Capabilities at the door, dishes on the menu. Two different calls.

The buzzer: `subscriptions/listen`

Sometimes the kitchen needs to tell you something: a resource changed, the tool list was updated. The old protocol did this with a stream over HTTP GET (a stream is a connection that stays open so the server can keep sending; over HTTP these are SSE, Server-Sent Events), plus separate resources/subscribe and resources/unsubscribe calls. All of that is replaced by one method: subscriptions/listen.

Think of the buzzer they hand you at the counter: it sits on your table and rings only when your order changes. You tell the server what you care about (a resource changing, or the tool or prompt list changing), and the server opens a stream tagged with your subscription ID. When the server wants to close the stream on purpose, it should now say a proper goodbye: a small "complete" result carrying that same ID. That way your client knows the difference between a normal close and a broken connection.

One buzzer replaces the old GET stream and both subscribe calls.

Something else quietly disappeared: you can no longer resume a broken stream. The old spec let you pick up where you left off with a Last-Event-ID header, which meant the server had to remember what it had already sent you. State again, hiding in the transport. Now, if a stream breaks, you send the request again with a new ID. If your buzzer breaks, nobody repairs it mid-ring; you take a new buzzer from the counter.

The question written on your receipt: MRTR

Nobody can come to your table anymore; the waiter who would have carried the kitchen's question is gone. So the cashier writes on your receipt: "Which sauce?" You come back to the counter with the same receipt and the answer written on it. Any cashier can complete the order from there. That is the pattern the spec settled on, and it has a name: Multi Round-Trip Requests (MRTR).

In the old protocol, a server could send requests back to the client in the middle of an operation. For example: "please ask the user a question" or "please run this through your model". That needs a two-way, stateful channel (stateful means the server must remember you between messages), which is exactly the thing the new version threw out.

The replacement: when a server needs something from you, it does not call you. It finishes the current request with a result marked resultType: "input_required", and lists what it needs in inputRequests. Your client then retries the same request with the answers attached. If the server sent a state token, the client sends that back too, unread; that is the note scribbled on your receipt. The server reads it and picks up where it stopped.

The kitchen writes its question on your receipt. You come back with the answer.

This is also why every result must now declare a resultType, either "complete" or "input_required". If an older server sends nothing, clients treat it as "complete".

The menu photo has an expiry time: caching hints

There is a photo of the menu taped up, with a note on it: valid for 10 minutes. That is what the new caching hints are. Being stateless has a cost, because clients ask "what tools do you have?" far more often, so the spec standardises the answer's shelf life.

Five results (tools/list, prompts/list, resources/list, resources/read, resources/templates/list) plus server/discover now carry two required fields: ttlMs and cacheScope. ttlMs is how long the result stays valid, in milliseconds. cacheScope decides who else may reuse it: "private" means only the same logged-in user (the same auth token), "public" means anyone. The photo either goes on the public board next to the card at the door, or stays on your table where only you can use it. Only final "complete" results carry these hints; an "input_required" half-answer can never be saved for reuse.

The complaint codes on the wall

Every branch of the restaurant now prints the same complaint codes on the wall. Error codes were renumbered and, for the first time, given a real rule about who owns which numbers: header mismatch is -32020, missing required client capability is -32021, unsupported protocol version is -32022. The range -32020 to -32099 now belongs to the spec itself, and servers and clients must not invent their own codes inside it. One older number moved too: resource not found is now -32602 instead of -32002, so clients should keep accepting the old code from older servers. Your client can react to a number instead of reading an error message and guessing.

The old side door is closing

A release this big also says goodbye to things:

Roots, Sampling and Logging are deprecated: still working today, marked for removal. Roots let a server see your folders; Sampling let it borrow your model. Logging control moved into _meta, so you set a logLevel per request instead of calling logging/setLevel.
ping, logging/setLevel, and the roots list-changed notification are removed.
The original HTTP+SSE transport from 2024 (a transport is the way messages travel) is now formally deprecated under the new lifecycle policy.
Tasks moved out of the core into an extension, so the core spec stays smaller.
OAuth Dynamic Client Registration is deprecated and replaced by Client ID Metadata Documents. Skip this bullet if you do not touch OAuth.

The old side door still opens for a while, because the spec defines careful rules for talking to older servers. But the sign on it now says: please use the main entrance.

Why I am the one telling you this

I am not neutral about this release. For the last few weeks I have been moving the Dart team's MCP SDK (package:dart_mcp) to it, with five merged pull requests so far in dart-lang/ai. The work is tracked publicly in dart-lang/ai#162. When the final spec came out, I compared it line by line with the release candidate (the near-final draft) and posted the report there. So everything above comes from the schema and the docs themselves, not from a summary of a summary.

What this means for you

If you build apps that use MCP servers: wait for your SDK to update. After that there is less to get wrong: no handshake, no session to lose. Version and capabilities travel with every request.

If you write MCP servers: tape this one to the kitchen wall. server/discover is mandatory now, and every result needs a resultType. Your */list and resources/read results need ttlMs and cacheScope on top of that. The painful part is anywhere you used to call back into the client: that has to be redesigned around input_required, and it changes your control flow, not just your types. What you get back is a server that runs anywhere.

If you are just curious: the practical news is freedom in where servers can run. MCP servers used to need a machine that stays up and remembers things. Now they can run as short-lived functions close to users, and scale like any normal web service.

Also changed, in one breath

A few smaller items, so you know they exist:

The OpenTelemetry keys traceparent, tracestate and baggage got reserved slots in _meta, so one request can be traced across services.
tools/list should now return tools in a stable order.
A tool parameter can now be mirrored into an HTTP header with the new x-mcp-header annotation, under strict naming rules.
clientInfo is no longer required on requests, and servers should now send serverInfo in every result's _meta. Both are recommended, not mandatory.
JSON Schema $ref resolution over the network (fetching schema pieces from other servers) is now banned by default.

None of it changes the story above. It is the boring kind of change, which in a protocol is the good kind.

Your receipt, please

A restaurant that runs on one waiter's memory is a lovely place, right up until the day he is not there. Counter service is duller. It also never loses your order, and it can open a hundred branches without breaking.

MCP just made that trade-off, and I think it chose well. If you want to see the change happen in real code, the Dart migration in dart-lang/ai#162 is open to read, one pull request at a time.

The object that falls out of the Set it is still in — mutable hashCode in Dart

Yusuf İhsan Görgel — Fri, 24 Jul 2026 08:39:13 +0000

Here is a Set with one element. One assignment later, contains stops finding it:

final attrs = <String, Object?>{'page': 1};
final tag = Tag('intro', attrs);
final seen = {tag};

print(seen.contains(tag)); // true
attrs['page'] = 2;
print(seen.contains(tag)); // false
print(identical(tag, seen.first)); // true

The object is in the set. identical confirms it is the same object. seen.contains(tag) says it isn't there. All I did in between was change a map I had a reference to.

I shipped this aliasing bug three times across two of my own packages before I caught it, and one of those times involved the map feeding hashCode, exactly the version above. This is not a contrived puzzle. It is what happens when a value type puts a mutable field into its hashCode.

Why the set loses it

Set is a hash set. When you add an object, it computes hashCode, picks a bucket, and drops the object in. When you later ask contains, it computes hashCode again, goes to that bucket, and looks. If the hashes differ, it looks in the wrong bucket and finds nothing.

That's fine as long as hashCode never changes while the object is in the set. It is the one rule hashing depends on.

Here is the Tag that breaks it:

class Tag {
  Tag(this.name, this.attrs);
  final String name;
  final Map<String, Object?> attrs; // stored by reference

  @override
  bool operator ==(Object other) =>
      other is Tag && name == other.name && _mapEquals(attrs, other.attrs);

  @override
  int get hashCode => Object.hash(name, _mapHash(attrs));
}

// Element-wise, one level deep: each value compares and hashes with its own
// == and hashCode. package:collection's MapEquality does the same thing.
bool _mapEquals(Map<String, Object?> a, Map<String, Object?> b) {
  if (a.length != b.length) return false;
  for (final k in a.keys) {
    if (!b.containsKey(k) || a[k] != b[k]) return false;
  }
  return true;
}

int _mapHash(Map<String, Object?> m) {
  var h = 0;
  for (final e in m.entries) {
    h ^= Object.hash(e.key, e.value); // xor: order-independent
  }
  return h;
}

attrs is final. That makes it look immutable. It isn't. final freezes the reference, not the map it points at. The constructor stored the exact map the caller passed, and the caller still has it. When they write attrs['page'] = 2, they are writing into the same map tag.attrs reads. hashCode folds attrs in. When the map changes, tag's hash changes, and the bucket the set filed it under no longer matches the bucket contains computes. The object is sitting in the set, in a bucket the lookup never visits.

The final is the tell that makes this easy to miss. It reads as a guarantee of immutability, and for an int or a String it is one. For a Map or a List it guarantees only that you won't reassign the field.

Two ways to be correct

The rule is narrow: anything that feeds hashCode must not change while the object could be in a hashed collection. There are two honest ways to satisfy it.

The first is to not put mutable state in equality at all. If Tag is a handle to something (it owns a resource or wraps a big buffer you mutate in place), then value equality is the wrong model, and identity equality (the default, no == override) is correct. Two handles are the same when they are the same object, and nothing can drift.

The second, when the type really is a value and callers will compare it, is to make the state actually immutable by copying it in and handing back something no one can write to:

class Tag {
  Tag(this.name, Map<String, Object?> attrs)
      : attrs = Map<String, Object?>.unmodifiable(attrs);
  final String name;
  final Map<String, Object?> attrs;
  // == and hashCode unchanged
}

The constructor now takes the caller's map as a parameter and stores a separate, unmodifiable copy. The caller can do whatever they like to their map; it's not the one Tag holds. And tag.attrs['page'] = 3 throws instead of silently corrupting the object. Rerun the first snippet against this version and contains stays true.

Map.unmodifiable copies the top level, which is what the hash reads. That is where it has to be. If you nest a mutable List or Map as a value inside attrs, that inner collection is still shared and still mutable. Either document that equality compares those values by identity or freeze them too. Be explicit about your choice. A half-frozen value type is its own trap.

Where this actually bites

Nobody writes attrs['page'] = 2 right after building a Tag on purpose. It happens at a distance. A store keeps the objects in a Set or uses them as Map keys, hands one back to you, and you update its metadata (reasonable, the field is right there), and now a Set somewhere else silently can't find it. Or a builder reuses one map across several objects, filling it in between, and they all end up sharing state. The failure surfaces far from the mutation, as a lookup that misses or a deduplication that doesn't dedupe, with no error to trace back.

The check is quick. For every type in your public API that overrides ==, ask what its hashCode reads, and whether any of it can change after construction. If it can, either drop value equality or copy the mutable parts in. Add one test that puts an instance in a Set, mutates the collection you handed the constructor, and asserts the instance is still found. The assertion is one line and it fails loudly the day someone reintroduces the reference.

My CI ran on three platforms and still could not catch this

Yusuf İhsan Görgel — Fri, 24 Jul 2026 01:50:11 +0000

For thirteen releases, my Ogg/MP3 decoder's README said this:

it decodes the same bytes to the same samples on every platform

I believed it. The decoding happens in C, the C is compiled from the same source everywhere, the tests pass on macOS, Linux and Windows. Where would a difference even come from?

I was getting the package ready to freeze at 1.0.0, which is the point where a documented promise stops being a sentence and becomes a contract. So instead of reading the claim again, I tested it. It is false, and it has been false since the first release.

Testing a claim about two architectures needs two architectures

That sounds obvious written down. It is exactly what my CI did not do.

On an Apple laptop you can do the whole thing locally, because clang will cross-compile and Rosetta will run the result. The driver ships in the repo at doc/blog/cross-arch/detdrv.c; from a fresh clone, run these at the repo root:

cp doc/blog/cross-arch/detdrv.c .
clang -arch arm64  -O3 -Isrc/third_party -o det_arm64  detdrv.c src/*.c
clang -arch x86_64 -O3 -Isrc/third_party -o det_x86_64 detdrv.c src/*.c

detdrv.c is about fifty lines: read a file, call the package's own decode function, print the channel count, the sample rate, the frame count, and an FNV-1a hash of the decoded samples. Then run both binaries over six test fixtures and compare the hashes. src/*.c here is the package's two C files. The build actually uses -O3, making this the production configuration rather than a special one. The x86-64 binary runs under Rosetta, but Rosetta only executes the instructions it is handed; anything the binaries disagree on was decided when clang compiled them, not at run time.

Five of those six came back different.

fixture                      arm64             x86_64            same?
sine_44100_mono_1s.mp3       26f26e4d00bd4680  db3ed41489553717  NO
sine_44100_mono_1s.ogg       741546cc3f0e3857  9b9fa075856e40b1  NO
sine_44100_stereo_1s.mp3     62655177b196b90f  db39b9b9973061b7  NO
sine_44100_stereo_1s.ogg     b712d80468229e7f  ab1522a686a648df  NO
sine_48000_mono_halfsec.mp3  03a0cfb92eff3109  03a0cfb92eff3109  yes
sine_48000_mono_halfsec.ogg  0e38543dbad39c7e  db914b5a5a724d93  NO

Same source, same compiler, same optimisation level, same input bytes. Different samples. The one that matched, a short MP3, matched by luck rather than by rule: the divergence only shows up when a sample lands close enough to a rounding boundary to fall the other way, and that clip happened to have none.

How big, exactly

A hash mismatch tells you nothing about severity. The next step is to dump both PCM buffers and diff them sample by sample:

sine_44100_mono_1s.ogg      12 of 44100 samples differ (0.027%), max delta 1 LSB
sine_44100_mono_1s.mp3       3 of 47232 samples differ (0.006%), max delta 1 LSB
sine_44100_stereo_1s.ogg    16 of 88200 samples differ (0.018%), max delta 1 LSB
sine_44100_stereo_1s.mp3    10 of 94464 samples differ (0.011%), max delta 1 LSB
sine_48000_mono_halfsec.ogg  5 of 24000 samples differ (0.021%), max delta 1 LSB

That is all five of the fixtures that diverged. Every difference is one least-significant bit, on a fraction of a percent of samples. In 16-bit audio one LSB is one part in 32768 of peak amplitude. Nobody is going to hear it. The frame count, channel count and sample rate matched on both architectures for all six fixtures.

So the audio is fine. The sentence is not.

Where the bit goes missing

Both decoders do their arithmetic in floating point, and the C standard lets a compiler contract a multiply followed by an add into a single fused multiply-add. An fma computes a * b + c with one rounding instead of two. It is more accurate and produces a different number than the unfused version.

arm64 has an fmadd instruction and clang uses it freely. Baseline x86-64 does not guarantee FMA. On that target the same expression compiles to a separate multiply and add, with a rounding in between. One rounding versus two, in a decoder that then scales to 16-bit integers, and occasionally a sample lands on the other side of .5.

This is not a bug in the decoders this package vendors (stb_vorbis for Ogg and minimp3 for MP3), nor in clang or my shim. It is the default behaviour of C floating point, and -ffp-contract=off turns it off. I checked what the build actually passes: only an optimisation level and no floating-point flags. Contraction is on, and the divergence I had documented as impossible is exactly what the default asks for.

For stb_vorbis that flag is the whole story. Rebuilt with contraction off, all three Ogg fixtures decode identically on both architectures. But both MP3 fixtures still differ. I disassembled the contraction-off arm64 build. It contains zero fused multiply-add instructions. Whatever is left cannot be a fused-versus-unfused split.

It is minimp3 hand-writing its final float-to-int16 conversion once per instruction set. Its two versions round differently. The SSE path converts with _mm_cvtps_epi32, which rounds to nearest and breaks ties to even. The NEON path adds 0.5f and truncates. The float values feeding that step are bit-identical on both architectures once contraction is off. I decoded to float on both and hashed the result to check. The entire residual difference is those two rounding rules disagreeing on a handful of samples by one. Force the plain scalar path with -DMINIMP3_NO_SIMD, which also adds 0.5f and truncates. x86-64 now rounds the way the NEON path does, and all six fixtures finally match with contraction off as well.

The part worth generalising

My CI matrix is three jobs: macOS (arm64), Ubuntu (x64), Windows (x64). It looks like it covers this. It cannot.

Each job builds the package and runs the test suite, and the test suite checks that decoding produces the right frame count, the right sample rate, and a waveform whose dominant frequency is the tone it should be. Every one of those assertions is a comparison against itself, inside one job. Nothing ever compares the macOS output against the Ubuntu output, because nothing in the matrix has both.

The trap is not specific to audio:

No number of independent self-comparisons tests a cross-environment claim. The only test is to carry an output from one environment into the other and compare. A matrix that never moves an output between jobs does not do that.

The fix in CI, if you need the guarantee, is to have jobs upload a hash of the output and have a final job assert they all match. The fix in the docs, if you do not need the guarantee, is to stop claiming it.

What the docs say now

I took the second option, because bit-identical cross-architecture output is not worth turning off contraction and minimp3's SIMD paths for a decoder whose output goes to a waveform or an FFT:

Decoding is deterministic for a given build: the same bytes decode to the same samples every time, and the geometry (channel count, sample rate, frame count) is the same everywhere. Sample values are not bit-identical across CPU architectures, though. [...] Measured across this package's own fixtures, that is around 0.03% of samples differing by one least-significant bit: inaudible, but enough that a checksum of decoded PCM will not match across a mixed-architecture fleet.

That last clause is the only case where any of this bites. If you decode audio on a build machine and compare a hash against audio decoded on a user's machine, or you cache by content hash across a mixed fleet, you will get misses that look like corruption and are not. Everyone else can ignore the whole thing, which is why the honest version of the sentence is longer than the false one.

If you maintain a native package that computes in floating point, the check costs one afternoon: build for two architectures, hash the output, compare. I would not assume the answer.

The 24.8 milliseconds you pay before ffmpeg decodes a single sample

Yusuf İhsan Görgel — Fri, 24 Jul 2026 01:50:09 +0000

You have an .ogg file and you need the raw samples. In Dart there is no decoder in the standard library, so you do the normal thing: you shell out to ffmpeg, read its stdout, and get your PCM. It works, it is one line, and ffmpeg is better at codecs than anything you are going to write.

I wanted to know what that costs, so I measured it against decoding in the same process. The interesting number turned out not to be the one I went looking for.

The measurement

Four clips of a 440 Hz sine, 44.1 kHz stereo, Vorbis in Ogg, at 1, 5, 15 and 30 seconds. Two ways to turn each one into interleaved 16-bit PCM:

In process. decodeOgg(bytes) from my audio_decode package, which compiles stb_vorbis from source through a Dart build hook and calls it over FFI.
Subprocess. ffmpeg -i clip.ogg -f s16le -acodec pcm_s16le -, run with Process.runSync, reading the PCM off stdout. ffmpeg 8.1.1.

Nine runs each, median reported, Apple M-series laptop. The bench checks that both paths produce the same amount of audio before it trusts either timing, which matters more than it sounds like and which I will come back to.

clip	in process	ffmpeg	ratio
1 s	0.594 ms	25.221 ms	42x
5 s	2.108 ms	27.406 ms	13x
15 s	6.294 ms	32.746 ms	5x
30 s	12.923 ms	40.452 ms	3x

Run to run these move by a few percent, and more than that on the sub-millisecond cell: a second run, from a fresh clone of the repo, gave 0.622 ms and 24.727 ms in the first row. Nothing below depends on the third decimal.

A 42x ratio at one second is the sort of number that ends up in a README, and it would be a dishonest one. Look at what the ffmpeg column actually does: thirty times more audio, and the time goes up by 15 ms. The clip length is barely moving that number. Something else is most of it.

The floor

The way to find out is to give ffmpeg nothing to do. I encoded a 0.05-second clip, 4 KB, and decoded it the same way:

Decoding a 0.05 s clip through ffmpeg still takes 24.793 ms, so that
is roughly what the process itself costs, before any audio is decoded.

That is the answer. About 24.8 ms of the 25.2 ms at one second is not decoding. It is fork, exec, the dynamic linker resolving ffmpeg's dependencies, ffmpeg parsing its arguments, probing the input format, setting up filters, and tearing all of that down again.

Subtract it and the two decoders look like what they are, which is two competent implementations of the same codec:

clip	in process	ffmpeg, decoding only
1 s	0.594 ms	0.428 ms
5 s	2.108 ms	2.613 ms
15 s	6.294 ms	7.953 ms
30 s	12.923 ms	15.659 ms

ffmpeg is faster than me at one second and I am faster at thirty. Nobody should switch decoders over that. The 24.8 ms is the whole story, and it has nothing to do with audio.

What it actually costs you

Because the floor is fixed per invocation, the arithmetic is per file, not per second of audio:

One 30-minute podcast: ffmpeg spends ~25 ms starting up and around a second decoding. The startup is 2-3% of the job. Shell out; it is fine.
A thousand short voice clips: 1000 × 24.8 ms is about 25 seconds, spent entirely on process startup, before counting a single sample. Batch them into one ffmpeg call and that goes away, but the moment the files arrive one at a time, or need different decode options, you are back to paying it per file. In process, it never exists.
A Flutter app decoding a clip in response to a tap: 25 ms is a frame and a half at 60 fps, on top of whatever the decode costs, and you cannot amortise it because there is one clip.

That last one is the case where it stops being an optimisation and becomes a design constraint. It is also the case where shelling out is often not available at all: on iOS you cannot spawn a process, so there the subprocess column is not a slower option, it is not an option.

The honest summary is narrow. If you decode occasionally, or in a batch job where a few seconds of overhead disappears, run ffmpeg and enjoy its enormous format coverage. If you decode many files, or decode on a latency budget, or ship somewhere without a shell, the per-file floor is the reason to pull the decoder in process.

The check that made the numbers mean anything

Before the bench times anything, it decodes the clip both ways and checks that each produced the same amount of audio. This felt like belt-and-braces when I wrote it. It was not.

A first, stricter version of the check compared the raw sample counts and threw:

sample count differs for 1s: 88200 vs 87944

128 frames short, 256 samples across the two stereo channels, on the one-second clip only. Two decoders disagreeing about how much audio is in a file is exactly the kind of thing that quietly makes a benchmark meaningless, so I went and looked instead of loosening the check.

The container settles it. ffprobe reports duration_ts=44100 for that clip, which is the frame count the Ogg stream declares. My decoder returns 44100 frames. ffmpeg's raw PCM pipe delivers 43972, stopping 128 frames early, and only at the shortest clip:

1s:  declared 44100     audio_decode 44100     ffmpeg pipe 43972
5s:  declared 220500    audio_decode 220500    ffmpeg pipe 220500
15s: declared 661500    audio_decode 661500    ffmpeg pipe 661500
30s: declared 1323000   audio_decode 1323000   ffmpeg pipe 1323000

A tail-trimming edge case at very short durations. 128 frames is 2.9 ms of audio, so for most uses it does not matter. But it does mean the check has to be about how much audio each side produced, counted in frames, not about the samples matching byte for byte. The samples do not match byte for byte, and that is the second thing worth knowing: stb_vorbis and ffmpeg's Vorbis decoder are two different decoders, so about half the samples differ by one least-significant bit. Both are correct; floating-point Vorbis synthesis simply does not have a single right answer to the last bit. A check that demanded identical samples would fail on every clip and tell you nothing.

So the check counts frames: it reports the 128-frame gap rather than hiding it, and fails only if the two decoders ever disagree by more than about a thousand frames, a codec block's worth, which would mean one of them is genuinely dropping audio. A benchmark that does not check that both sides did the same work is measuring something, and you do not know what.

Run it yourself

The timings in this post come from a script in the package, not from my notes:

git clone https://github.com/Yusufihsangorgel/audio_decode
cd audio_decode
dart run bench/vs_ffmpeg.dart

It needs ffmpeg on your PATH and a C toolchain for the build hook, generates its own clips, and prints the table above plus the measured floor for your machine. If your floor is very different from 24.8 ms I would genuinely like to know: process startup varies a lot by OS and by how ffmpeg was built, and the whole argument in this post is downstream of that one number.

None of this is specific to audio. Shell out to a tool in a hot path and you pay for the process, not the tool, at the same price whether you asked it to do a little work or a lot.

Pinning the point you pinch: the one line behind anchored zoom

Yusuf İhsan Görgel — Thu, 23 Jul 2026 20:41:57 +0000

Open a photo on your phone and pinch to zoom. The spot between your fingers stays between your fingers while everything around it grows. Trackpad pinch, scroll-wheel zoom on a map, double-tap to zoom into a diagram: same feel. Whatever point you aim at holds still while the view scales around it.

That behavior is anchored zoom, and it comes down to one line of arithmetic. This post is about that line. The example package is photo_zoom, which I maintain, but the math is the same whether you are building an image viewer, a map, a canvas, or a diagram editor.

That is a conceptual illustration of the behavior. It is not a screen recording of the Flutter widget. The marked point holds its spot on screen while the grid scales, then the whole view pans.

A view is a scale and a translation

A zoomable view maps content coordinates (where a pixel sits inside the image or the map) to screen coordinates (where it lands on the display). In one dimension the entire mapping is one equation:

screen = scale * content + translation

scale is how far you are zoomed in. translation is how far the content is shifted. Two numbers per axis, and that is the whole transform.

Now zoom in, meaning raise scale, and leave translation alone. Every content value gets multiplied by a bigger number, so every point moves, including the one you were looking at. The image balloons toward a corner and the thing you cared about slides away.

Pin one point and solve for the rest

Pick the point you want to hold still. Say it sits at content coordinate F, and you want it to stay at screen coordinate S. Put those into the mapping:

S = scale * F + translation

You know S, F, and the new scale. The only unknown is translation, so solve for it:

translation = S - scale * F

That is the line. Recompute it every time scale changes, and the point at F lands on S on every frame. The translation is forced here: once the focal point and the scale are fixed, there is exactly one translation that keeps the point pinned. You never choose it directly.

Where the focal point comes from

A pinch hands you two things: a focal point, which is the midpoint between your two fingers, and a change in scale. Feed that focal point into translation = S - scale * F and the image grows out from between your fingers instead of drifting toward a corner.

The same formula covers the other zoom gestures you already use:

Double-tap to zoom: the focal point is where you tapped.
Scroll-wheel or trackpad zoom on desktop: the focal point is the cursor.

Different input, same math. Whatever point you name as the focal point is the point that stays put.

Two axes, no new ideas

Screens are 2D, and the rule runs on each axis on its own. Same formula, twice:

translationX = focalScreenX - scale * focalContentX

translationY = focalScreenY - scale * focalContentY

There is no cross-talk between X and Y. The point you pinch is pinned horizontally and vertically by the same subtraction.

The line, as code

Here it is as a pure-Dart function. It takes the focal point in both coordinate spaces plus the scale, and returns the translation that pins it, as a record with x and y:

// Given where the focal point is on screen and in the content, and the
// scale, return the translation that keeps the focal point pinned.
({double x, double y}) anchoredTranslation({
  required double focalScreenX,
  required double focalScreenY,
  required double focalContentX,
  required double focalContentY,
  required double scale,
}) => (
      x: focalScreenX - focalContentX * scale,
      y: focalScreenY - focalContentY * scale,
    );

Read the body and it is the 2D formula from the last section. focalScreenX - focalContentX * scale is S - scale * F on the X axis, and the same on Y.

Checking it holds

Here is the check I ran. Drop this into the same file as the function above and run it. It fixes a focal point, zooms from scale 1.0 to 3.0, and pushes the pinned point back through screen = scale * content + translation to confirm it lands in the same place:

void main() {
  const focalScreenX = 200.0;
  const focalScreenY = 150.0;
  const focalContentX = 300.0;
  const focalContentY = 400.0;

  for (final scale in [1.0, 3.0]) {
    final t = anchoredTranslation(
      focalScreenX: focalScreenX,
      focalScreenY: focalScreenY,
      focalContentX: focalContentX,
      focalContentY: focalContentY,
      scale: scale,
    );
    final backX = scale * focalContentX + t.x;
    final backY = scale * focalContentY + t.y;
    print('scale $scale -> translation (${t.x}, ${t.y}); '
        'focal maps back to ($backX, $backY)');
  }
}

Run it and you get two lines. At scale 1.0 the translation is (-100.0, -250.0). At scale 3.0 it is (-700.0, -1050.0). The translation moves a long way between the two, because at 3x the content has to shift much further to hold that one point in place. But the pinned point maps back to (200.0, 150.0) at both scales. That equality, the same screen position at every scale, is the property the formula guarantees.

Where this lives in Flutter

In Flutter the transform is a Matrix4. A Transform widget applies one, and InteractiveViewer maintains one for you as you pan and zoom. The scale and translation from above are entries in that matrix. When you pinch inside an InteractiveViewer, it is running this same focal-point arithmetic to pick the matrix for the next frame.

photo_zoom, the package I maintain, is a drop-in replacement for photo_view that wires this up for image viewing. It reads the pinch, double-tap, and drag gestures, builds the anchored transform internally, and scales the image around the gesture's focal point. A caller uses PhotoView with an imageProvider and, if they want, minScale, maxScale, and initialScale (typed as PhotoViewScale). The anchored-zoom math stays inside; the caller gets zoom that holds where they pinched.

To be plain about what that buys you: anchored zoom is standard behavior. photo_view does it, InteractiveViewer does it, your phone's photo app does it. None of it is special to photo_zoom. The part worth carrying to other projects is the one line, translation = S - scale * F. Once you have seen it you can add anchored zoom to a custom canvas, a diagram editor, or a map yourself.

A wrinkle: when a drag should pan and when it should dismiss

Once you allow zooming, a drag has two possible jobs. It can pan the zoomed image, or it can dismiss the viewer and close the full-screen view. You have to decide which one a given drag means.

The rule that feels right keys off whether there is anything to pan into. While the image is larger than the viewport, there is off-screen content to pan into, so a drag pans. When the image is at or below the fit scale, there is nothing to pan, so a drag can dismiss.

photo_zoom 0.2.1 fixed a case here: dismiss had gone dead once the image was zoomed out below its initial scale. At that point there is nothing left to pan, so a drag should have been free to dismiss, and it was not. This is the kind of edge that shows up only once anchored zoom already works and you start spending time in the zoomed-out state.

Keep this one line

If you keep one thing from this, keep translation = S - scale * F. Recompute it whenever the scale changes, using the focal point the gesture hands you, and the point under your finger stays under your finger. The matrix, the widget, and the package are all wrappers around that subtraction.

A public const constructor is the back door around your factory's validation

Yusuf İhsan Görgel — Thu, 23 Jul 2026 20:15:24 +0000

You put your validation in a factory. Schema.string(pattern: ...) checks that the pattern is a real regex before it hands you an object. Schema.enumeration(values) refuses an empty list and copies the one you pass in. The factory is the front door, and it has a bouncer.

Then someone calls the constructor instead.

If the concrete class has a public constructor sitting next to that factory, it is a second door into the same object, and that door has no bouncer. Everything the factory checked, the constructor skips. This is a general Dart trap, and I hit it in my own package, instructor_dart. The interesting part is why the obvious fix does not work: the constructor is const, and const is exactly what stops it from defending itself.

The setup

instructor_dart takes a plain-Dart schema and a prompt and returns a validated, correctly-typed Dart object from an LLM. You describe the shape you want with a small schema API:

import 'package:instructor_dart/instructor_dart.dart';

final email = Schema.string(pattern: r'^[^@]+@[^@]+$');
final priority = Schema.enumeration(['low', 'medium', 'high']);

Schema is a sealed base type with static factory methods: Schema.string(), Schema.integer(), Schema.number(), Schema.boolean(), Schema.enumeration(), Schema.list(), and Schema.object(). Each one returns a concrete type: StringSchema, IntegerSchema, EnumSchema, and so on.

Those concrete types are where the problem lived.

Two doors, one object

Before 0.4.0, the concrete classes had public const constructors. So you could build a StringSchema two ways:

Schema.string(pattern: '(') goes through the factory, which validates.
StringSchema(pattern: '(') goes straight to the constructor, which does not.

Both gave you a StringSchema. Only one of them checked anything. Two of the factory invariants were real, and both were skippable through the raw constructor.

The regex is validated eagerly. Schema.string(pattern: ...) runs RegExp(pattern) at construction time. If you pass a broken pattern, you get a FormatException right there, at the line where you wrote the mistake:

// Schema.string runs RegExp(pattern) and throws FormatException on a bad pattern:
final bad = Schema.string(pattern: '(');

Call the raw StringSchema(pattern: '(') constructor and that check never runs. The broken pattern gets stored and sits there until something tries to match against it, which is usually far away from the typo, in a stack trace that points at the matcher instead of at you.

The enum set cannot be empty, and it gets copied. Schema.enumeration(values) throws ArgumentError if values is empty, and it copies the list with List.unmodifiable. So the allowed set is never empty, and nobody can mutate it after the fact:

final priority = Schema.enumeration(['low', 'medium', 'high']);

The raw EnumSchema(const []) constructor skipped both. You could build an enum that matches nothing, or pass in a list you keep a reference to and change later, out from under the schema.

"Just make the constructor validate itself"

This is the obvious idea, and in Dart it does not work, because these constructors are const.

A const constructor is restricted. It can assign to fields and it can run assert statements in its initializer list. That is the whole menu:

class Port {
  final int value;
  // A const constructor may assert. That is as far as it goes.
  const Port(this.value) : assert(value >= 1 && value <= 65535);
}

assert has two problems for real validation. It only runs in debug mode, so in a release build it is gone. And it takes a boolean condition, so it cannot express "parse this string as a regular expression and throw a FormatException if it fails." There is no way to call RegExp(pattern) from inside a const constructor, and no way to throw an ArgumentError conditionally the way an ordinary method can.

So the real checks have to live somewhere that can run real code: a factory, or a static method. That is the actual reason these packages reach for factories in the first place. The factory is the only place a check can live, and a public const constructor sits right beside it as a way around it.

The fix in 0.4.0

Make the concrete constructor library-private. Each concrete class now has a private named constructor, and the factory routes through it. In shape:

StringSchema has const StringSchema._(...).
Schema.string(...) does its regex check, then calls StringSchema._(...).

From a caller's side, the change is small and total. The factory still works exactly as before:

// Still the way to do it:
final email = Schema.string(pattern: r'^[^@]+@[^@]+$');

Writing StringSchema(pattern: r'^[^@]+@[^@]+$') is now an analyzer error: the class has no accessible unnamed constructor. There is no second door to walk through.

The concrete classes stay exported as types, and that part matters. You still get StringSchema and EnumSchema as return types, you can still switch over the sealed Schema hierarchy and match on them, and you can still read their fields. Closing the constructor closes construction only; the type is still yours to use.

One more thing fell out of this. The factories do not take an isOptional argument, so once the raw constructors were closed, the only way left to mark a field optional is the .optional() method that was the intended one. Removing the public constructor removed the shortcut around that too.

Honest scope: this was mostly preventive

I want to be exact about what this changed, because it did not fix five broken validators.

Of the seven factories, only two enforced an invariant that the raw constructor skipped: string with its regex check, and enumeration with its non-empty-and-copy rule. Those two were real holes, and closing the constructor closed them.

The other five (integer, number, boolean, list, object) forwarded their arguments and validated nothing. For those, there was no bug to fix. Closing their constructors is preventive: it means that the day someone adds a check to Schema.integer(), there is no public IntegerSchema(...) sitting next to it to route around the check. The single construction path is set up before it carries anything worth protecting.

So the count is small: two real checks locked, and five constructors closed before they ever guard anything, with all seven now built through one path.

Why this had to happen before 1.0.0

Removing a public constructor is a breaking change. Any code that wrote StringSchema(...) stops compiling.

Once a package puts out a stable 1.0.0, you cannot take a public constructor away without going to 2.0.0. instructor_dart is young, so the cost of the break right now rounds to zero. After 1.0.0 the same cleanup costs a major version and a migration for everyone who depends on you. This was the cheap moment, so I took it.

If a factory validates, close the constructor

The specific bug was mine, but the shape is everywhere: any value type with a validating factory and a public constructor has a back door. If you write these in Dart, the mechanics are worth keeping in your head. Here is the Port from earlier with the door closed:

class Port {
  final int value;

  // The only real constructor, and it is private.
  const Port._(this.value);

  // The public door, and it can run whatever checks it wants.
  factory Port(int value) {
    if (value < 1 || value > 65535) {
      throw ArgumentError.value(value, 'value', 'must be 1..65535');
    }
    return Port._(value);
  }
}

Give the class a private named constructor (ClassName._), route the factory through it, and if the type is part of a sealed hierarchy, keep the class exported so it still works as a type in returns and switch arms. The const constructor cannot carry the validation itself, because const constructors can only assign and assert. The factory is where the checks live, and a public constructor next to it is a way around them.

Go look at your own value types. If the validation is in the factory and the constructor is public, you have two doors, and callers will find the one without the bouncer.

2.75 seconds or 2 microseconds: the same regex, two engines

Yusuf İhsan Görgel — Thu, 23 Jul 2026 19:59:12 +0000

Here is a regular expression: (a+)+$. Here is an input: a string of 28 a characters followed by one !, which the pattern cannot match.

Ask Dart's built-in RegExp whether the pattern matches that input, and on my laptop it takes 2.75 seconds to return false. Ask Google's RE2 engine the same question about the same bytes, and it returns false in about 2 microseconds. Same pattern, same string, same answer. The only thing that changed is which engine did the matching, and it made the answer arrive roughly a million times sooner.

Both numbers are real. I ran the benchmark on Apple Silicon with Dart 3.11, and both engines saw byte-for-byte identical input. The gap is not something you can close by writing a cleverer pattern. Here is where it comes from, and when it is worth paying RE2's cost to avoid it.

The measurement

The pattern is (a+)+$. The input is n copies of the letter a followed by one !, so the match always fails (the string does not end the way the pattern demands). I fed the identical pattern and input to both engines and timed the match. Times are in microseconds; I write us for microseconds and ms for milliseconds.

n	Dart RegExp (us)	re2 (us)
16	4,712	2 to 3
18	10,490	2 to 3
20	15,671	2 to 3
22	49,416	2 to 3
24	169,381	2 to 3
26	679,067	2 to 3
28	2,746,957 (2.75 s)	2 to 3

re2 sits flat at 2 to 3 us the whole way down the column. Dart's RegExp roughly quadruples every time n goes up by two. By n=28 it is spending 2.75 seconds to answer a yes/no question about a 29-character string.

This is the shape of a ReDoS (regular expression denial of service) bug. A pattern that looks ordinary meets an input that is a little bit adversarial, and one match call ties up the isolate for seconds. This is not hypothetical: in dart-lang/sdk#61284 an ordinary URL pattern froze a running app on iOS. Nobody wrote that pattern to be malicious. It just had the wrong shape and met the wrong input.

Why one explodes and the other does not

Both engines answer the same question. They go about it in completely different ways, and that difference is the entire 2.75-seconds-versus-2-microseconds gap.

A backtracking engine treats matching as a search

For (a+)+ to match a run of a's, the engine has to decide how to divide that run between the inner a+ and the outer repetition. Five a's could be one group of five, or four then one, or two then three, and so on. As long as more a's keep coming, the greedy path just extends and the division never has to be reconsidered; the engine takes the first split that works and moves on.

The trouble starts at the character after the run. In our input that character is !, and the pattern still needs $ (end of string) there. The match fails at that point. A backtracking engine does not give up there. It backs up and tries the next way of dividing the a's, then the next, then the next, on the theory that some other division might let the rest of the pattern match.

The number of ways to split a run of n a's into ordered groups is 2 to the power n-1. At n=28 that is 2^27, which is 134,217,728 divisions the engine works through before it can be sure there is no match. Every extra a doubles that count. That is where the "quadruple every time n goes up by two" in the table comes from: one more character, twice the work; two more, four times.

RE2 does not search

RE2 compiles the pattern once into a finite-state machine. Then it reads the input one character at a time, and instead of tracking a single guess it tracks the entire set of states the machine could be in at that point. Each character advances that whole set by one step. The read pointer only ever moves forward; it never backs up to retry a division, because RE2 is not trying divisions at all. It is asking, after these characters, is any accepting state reachable.

The linear-time guarantee is exactly this: n characters take exactly n steps, and no input, however it is crafted, can push an RE2 match into exponential time. There are no divisions to enumerate, so there is nothing to enumerate exponentially many of.

The engine behind the re2 package is an FFI binding to Google's RE2, the same C++ engine, exposed to Dart.

Why Dart's built-in RegExp is the backtracking kind

Dart's RegExp is Irregexp, the engine that came from V8. Irregexp is a backtracking engine, which is why it is fast and full-featured on ordinary patterns and can handle features like backreferences. The same design is what lets a nested quantifier like (a+)+ blow up. Every backtracking engine behaves this way when a nested quantifier fails to match. The exponential search is the algorithm working as designed. There is no patch for it; a backtracking engine does this by construction.

The million-character match

Because RE2 takes one step per character, you can throw genuinely large input at it and watch the time stay reasonable. Each of these is n a's followed by one non-matching character, the same failing shape as before, just longer:

input length (n)	re2 match time
1,000	50 us
10,000	138 us
100,000	111 us
1,000,000	1,894 us (1.9 ms)

Those numbers do not climb smoothly. At the microsecond scale, fixed overhead (crossing into native code, marshalling the string) and ordinary measurement noise dominate, so n=100,000 can clock in under n=10,000. The trend is the point: ten times the input is nowhere near ten times the time, and a million characters match in 1.9 ms.

Put that same million-character hostile input in front of a backtracking engine on (a+)+$ and it would have 2^999999 divisions to work through, which is longer than the age of the universe. RE2 finishes it in under two milliseconds because it never asks that question.

Using it in Dart

The API is small. You construct a Re2 from a pattern and call hasMatch, firstMatch, or allMatches.

import 'package:re2/re2.dart';

void main() {
  // The classic catastrophic-backtracking pattern.
  final re = Re2(r'(a+)+$');
  final hostile = 'a' * 30 + '!';
  print(re.hasMatch(hostile)); // returns false in microseconds; the built-in
                               // RegExp would take seconds on the same input
  re.dispose();
}

I used 30 a's here; since each a doubles the backtracking engine's work, 30 is well past the point where the built-in RegExp stalls for seconds, while RE2 does not notice the difference.

Re2 implements Dart's Pattern, so an instance drops into String.split, String.replaceAll, and the other methods that take a Pattern. Call dispose when you are done with it; it holds a native resource behind the FFI boundary.

The honest trade-off

RE2 is not a general speed boost for everyday regexes. On ordinary patterns and ordinary input, Dart's built-in RegExp is usually the faster of the two, because every RE2 call has to cross the FFI boundary and marshal the string, and that costs something (roughly 2x in my measurements). What RE2 buys you is a ceiling on match time that holds no matter what the input is. That is a security property, and it only matters when the pattern or the input is outside your control. Most of your regexes run against strings you control, and the built-in RegExp is the right tool for those.

So the rule I use:

Reach for re2 when the pattern or the input is attacker-reachable: user-supplied search terms, validating uploaded content, a WAF-style ruleset, anything where someone else picks the string you match against.
Keep the built-in RegExp everywhere else, which is most places.

One constraint is worth knowing before you commit. RE2 does not support backreferences (\1) or lookaround ((?=...), (?<=...)) at all. Those are the features that force a backtracking implementation and open the door to the exponential blow-up, so RE2 leaves them out by design. A pattern using them throws a FormatException the moment you construct the Re2, long before it could bite you in production.

The 2.75-seconds-versus-2-microseconds gap comes from RE2 refusing to enumerate divisions at all, which is a game a backtracking engine has no way to refuse. Once a regex runs against input someone else chose, the exponential case turns from a curiosity into an availability bug, and a linear-time engine earns its FFI cost. The package is re2 on pub.dev; the engine underneath is the one Google wrote for exactly this problem.

Disclosure: re2 is my package; the RE2 engine it binds is Google's.

A finite loop in skeleton_shimmer that stopped resuming when the loop count was raised

Yusuf İhsan Görgel — Thu, 23 Jul 2026 18:10:24 +0000

The clip above is a conceptual illustration of the behavior, with a card frozen after a finite loop on the left and a card still sweeping on the right. It is not a screen recording of the running widget.

skeleton_shimmer draws a shimmer loading effect, a light gradient that sweeps across gray skeleton placeholders while data loads. It is API-compatible with the shimmer package. Its Shimmer widget takes a loop parameter: loop: 0 sweeps forever, and loop: N stops after N sweeps.

Version 0.2.1 had a bug in the loop: N path. Once a finite loop finished, raising loop at runtime did not start the sweep again. The widget stayed frozen on a static gray field. Version 0.2.2 fixes it with a one-line change, and the reason that line works comes down to how AnimationController behaves when it is parked at one of its bounds.

The symptom

Give the widget loop: 2 and let both sweeps play. The shimmer settles on gray, which is what loop: 2 asks for. Now raise the count to loop: 4 while the widget is on screen. Before 0.2.2, nothing happened. The placeholder stayed gray and static, and the two extra sweeps never ran.

Root cause

The sweep is driven by an AnimationController that animates from its lower bound to its upper bound, 0.0 to 1.0. One pass from 0.0 to 1.0 is one sweep.

A status listener, _onStatus, counts completed passes. Each time the controller reaches the end it increments a completed-loops counter, _completedLoops. While that counter is below the target it calls forward(from: 0) to run the next sweep. Once the counter reaches the target it stops calling forward(from: 0), and the controller is left parked at the upper bound: value is 1.0, its status is completed, and it is not animating. For loop: N that is correct, since the animation is meant to stop after N sweeps.

Raising loop at runtime goes through didUpdateWidget. That resets the completed-loops counter back to 0 and calls a resync method, _syncAnimation, to line the animation up with the new configuration.

_syncAnimation saw that the controller was not animating and tried to resume it with a bare forward(). That is where it went wrong. forward() animates toward the upper bound, and the controller was already sitting at the upper bound with value at 1.0. The remaining distance was zero, so the call was a zero-duration no-op: it scheduled no ticker and did not fire the status listener again. The sweep never restarted, and the widget stayed frozen.

The framework behavior underneath it

This is deterministic, and you can confirm it away from the package with a plain AnimationController. Calling forward() when value is already 1.0 does nothing: the status stays completed and isAnimating stays false. It is a genuine no-op. Calling forward(from: 0) instead sets value to 0.0 and isAnimating to true, and the controller runs again.

The fix

The change is one line in _syncAnimation. The branch before 0.2.2:

  } else if (!_controller.isAnimating) {
    _controller.forward();
  }

And after:

  } else if (!_controller.isAnimating) {
    // A finished finite loop parks the controller at the upper bound, where
    // forward() would be a no-op; restart from 0 so a raised loop count
    // sweeps again. Otherwise (e.g. re-enabled mid-sweep) resume in place.
    _controller.forward(from: _controller.isCompleted ? 0 : _controller.value);
  }

The ternary picks a starting point based on where the controller is parked.

When the controller is completed, meaning it is parked at the upper bound after a finished finite loop, forward(from: 0) restarts it from the beginning. That is the case the old code got wrong, and it matches what the status listener already does between loops.

When the controller is not completed, for example it was stopped mid-sweep because the widget was disabled and is now being re-enabled, forward(from: _controller.value) starts from the value the controller already holds. Setting the start to the current value is a no-op assignment, and the controller forwards from there. For that path the behavior is identical to the old bare forward(). Only the completed case changed.

Two behaviors that had to keep working

First, toggling the widget's enabled flag off and back on in the middle of a sweep resumes in place rather than jumping to the start. A controller stopped mid-sweep is not completed, so the fix sends it down the resume-in-place branch, forward(from: _controller.value).

Second, reduced motion still holds. When the platform's disableAnimations accessibility setting is on, the shimmer freezes on its base color. That path calls _controller.stop(), and the fix does not touch it.

The regression test

A regression test shipped with the fix for exactly this scenario. It mounts the widget with loop: 2 and pumps until the animation settles. Once the finite loop is done the controller stops, so the transient callback count, the number of one-shot callbacks registered for the next frame, falls back to 0. The test then rebuilds with loop: 4 and checks that the sweep resumes, which shows up as the transient callback count going above 0 again.

On the pre-fix code the count stays at 0, because the frozen controller schedules no ticker. After the fix it goes back above 0. I confirmed this by reverting only the fix and rerunning: the test fails before and passes after.

An AnimationController parked at a bound is a quiet trap

Calling forward() toward the bound you are already at is a no-op, and so is reverse() toward the bound you are already at, because the remaining distance is zero. When you want the controller to run again from that bound, you have to say so: forward(from: 0) from the upper bound, or reverse(from: 1) from the lower bound.

The other half of this bug sits in didUpdateWidget. When a runtime parameter change resets internal state, here the completed-loops counter, it has to re-establish the animation to match the new state. Resuming a controller and restarting it are different operations, and the code has to choose the right one for where the controller is parked at that moment.

DEV Community: Yusuf İhsan Görgel

I counted one MCP server on the wire: without the handshake, HTTP stays lighter until call ten

1. What did one flow cost under each revision?

2. What ran, and what did I leave out?

3. What does each revision require on the wire?

4. Where did the plain-flow HTTP bytes go?

5. What happens when a tool asks for an answer?

6. At what call count does the HTTP total cross?

7. What does carried request state do to the retry?

8. How were the bytes counted?

9. What did I catch before counting?

10. What can these numbers not tell me?

11. How do I reproduce one row?

12. What should another SDK measure?

Why one failed font load kept breaking pendingFonts() in Flutter

What a test sees

One line, two problems

Each half on its own

On 8.2.0, a successful retry does not help

What this does not cover

Use 8.2.1

Check it yourself

Run it, bound it, check it every week: how I made a Dart MCP client checkable

1. Run both sides in two terminals

2. List everything, but stop at 64 pages

3. Sampling content as a list, and the error inside a 415

4. Run conformance weekly and catch stale expected failures

5. Docs that match the code

What I would do the same way again

Your leak test is probably measuring the test runner

Why this happens

Move the measurement into a child process

Derive the threshold, do not pick it

Verify the test can fail

What RSS cannot answer

Checklist

The Biggest MCP Update Ever, Explained With a Restaurant

First: what is MCP?

The waiter is gone: MCP is now stateless

The card at the door: server/discover

The buzzer: subscriptions/listen

The question written on your receipt: MRTR

The menu photo has an expiry time: caching hints

The complaint codes on the wall

The old side door is closing

Why I am the one telling you this

What this means for you

Also changed, in one breath

Your receipt, please

The object that falls out of the Set it is still in — mutable hashCode in Dart

Why the set loses it

Two ways to be correct

Where this actually bites

My CI ran on three platforms and still could not catch this

Testing a claim about two architectures needs two architectures

How big, exactly

Where the bit goes missing

The part worth generalising

What the docs say now

The 24.8 milliseconds you pay before ffmpeg decodes a single sample

The measurement

The floor

What it actually costs you

The check that made the numbers mean anything

Run it yourself

Pinning the point you pinch: the one line behind anchored zoom

A view is a scale and a translation

Pin one point and solve for the rest

Where the focal point comes from

Two axes, no new ideas

The line, as code

Checking it holds

Where this lives in Flutter

A wrinkle: when a drag should pan and when it should dismiss

Keep this one line

A public const constructor is the back door around your factory's validation

The setup

Two doors, one object

"Just make the constructor validate itself"

The fix in 0.4.0

The card at the door: `server/discover`

The buzzer: `subscriptions/listen`