Monedula
monedula-sim-link docs menu

The read-only guarantee

monedula-sim-link connect never writes to your cluster: the read requests it sends, the one that is opt-in, what it never does, and where to verify it.

Concepts 1 of 3

3 min read

Updated 16 October 2026

Markdown

On this page

connect takes its snapshot with eight kinds of Kafka request, all of them reads, and a ninth, also a read, only when you ask for it with --producers.

The requests

Request What connect uses it for
ApiVersions The handshake of the Kafka client library, franz-go, to agree on protocol versions.
Metadata The brokers, the topics, and the leader, replicas and in-sync replicas of every partition.
ListOffsets The earliest and latest offset of every selected partition, which gives the relative fill of each.
ListGroups The list of consumer groups. Only groups with the protocol type consumer are used.
FindCoordinator The Kafka client library’s lookup of the broker that coordinates a group, which DescribeGroups and OffsetFetch go through.
DescribeGroups The state and the members of those groups.
OffsetFetch The offsets those groups have committed, for the selected topics.
DescribeConfigs The configs of the selected topics: cleanup.policy, min.insync.replicas, retention.ms and retention.bytes.
DescribeProducers Only with --producers. The idempotent and transactional producers that wrote to the selected partitions, each with the timestamp of its last write.

The Metadata request is sent with AllowAutoTopicCreation=false, so looking up a topic can never create it. That matters on clusters that have auto.create.topics.enable turned on: asking for a topic that does not exist fails with a message and leaves the cluster as it was.

Why DescribeProducers is opt-in

DescribeProducers (KIP-664, Kafka 2.8 or newer) needs READ on each topic it asks about, where the other requests need only DESCRIBE (and DESCRIBE_CONFIGS for the topic configs). So the tool sends it only when you pass --producers, or set producers on the MCP tool cluster_to_url. Without the flag the request is never sent. READ is also the permission that lets a client fetch records. connect never sends a fetch, and everything on this page holds with the flag too, but that is a reason to grant READ to the principal only when you want producers (Connect to a secured cluster shows how).

What it never does

  • It produces no records, and creates or alters no topics and no configs.
  • It joins no consumer group: there is no JoinGroup, SyncGroup or Heartbeat.
  • It commits no offset: there is no OffsetCommit.
  • It never reads record contents. None of these requests fetches records, so the tool never sees the keys and values of your data. DescribeProducers reports a producer id and the timestamp of its last write, not what it wrote.

The MCP tool cluster_to_url uses the same code path, so it has the same guarantee. The other MCP tools never connect to a cluster.

Where to check it yourself

The whole client surface lives in one file, snapshot/kafka.go, so the guarantee can be audited in one place. Tests back it up:

  • TestFetchMissingTopicDoesNotAutoCreate proves that a failed topic lookup does not create the topic, and TestFetchGroups proves that reading the committed offsets of a group twice never changes them. Both are in snapshot/kafka_test.go.
  • TestFetchWithoutProducersSendsNoDescribeProducers, in snapshot/producers_test.go, proves that a snapshot without --producers sends no DescribeProducers request.
  • An end-to-end suite runs the pipeline against a real three-node KRaft cluster, with Apache Kafka and with Confluent Platform images. It checks the snapshot, the link, the connect binary and the MCP server, and that nothing on the cluster changed: no topic was created, no offset committed and no member joined. Its read-only test takes a snapshot with the producers read as well.

Defense in depth

The guarantee comes from the tool, and your cluster can enforce it as well. Give connect a principal that can only describe the cluster, its topics, its groups and its topic configs, and its permissions match what it does; add READ on the topics only for --producers. Connect to a secured cluster shows how to pass the credentials.