API Stability

API Stability

Every public header carries one line under its license block, // API stability: <tier>, and this page says what each tier promises. The version policy follows from it: a change that breaks a stable API bumps the major version; anything else can ride a minor.

The tiers

Stable. The API a release is committed to. It changes only with a major version bump, and a deprecation is announced one minor release ahead of the removal, with the replacement named. Wire formats under it (the ZDT handshake, the framing) are covered by the ZDT protocol version rather than this policy: a mismatch is refused, never guessed at.

Experimental. The shape is right enough to ship and wrong enough to change. It may change in any minor release; when it does, the wiki page that documents it says what moved and why. Feedback on these is what turns them stable.

Internal. No promise at all, and it may change in a patch. The headers are public so that a project that needs the building blocks can reach them (gipMultiplayer drives p2p::internal directly, for one), not because the shape is settled. Namespaces znet::detail, znet::backends and znet::p2p::internal, and everything under znet/detail/, znet/backends/ and znet/p2p/internal/.

By header

Header	Tier	Notes
znet/znet.h	stable	The umbrella; what it includes is the stable core
znet/buffer.h	stable
znet/packet.h, packet_serializer.h, packet_handler.h, codec.h	stable
znet/client.h, client_events.h	stable
znet/server.h, server_events.h	stable
znet/peer_session.h	stable
znet/options.h, send_options.h, close_options.h	stable	New options may be added in a minor; none removed
znet/event.h	stable
znet/inet_addr.h	stable
znet/encryption.h, compression.h	stable	The configuration surface; the implementations behind them are internal
znet/metrics.h	stable	New counters may be added in a minor; none removed or renamed
znet/error.h, types.h	stable	New Result values may be added in a minor
znet/init.h, logger.h, util.h, version.h, compat.h	stable
znet/p2p.h and everything under znet/p2p/	experimental	Gathering, the rendezvous protocol, the relay and both locators are new in 4.1
znet/p2p/tcp/*	experimental	Kept apart from the ZDT path; may be reshaped with it
znet/p2p/internal/*	internal	The state machines behind p2p::Host
znet/admission.h	internal	Driven through ServerOptions, which is stable
znet/transport.h	internal	The transport interface; no third-party transports yet
znet/interface.h, task.h, scheduler.h, worker_signal.h, signal_handler.h	internal	Threading plumbing
znet/message_pipeline.h, session_encoder.h, outbound_queue.h, mpsc_queue.h	internal	The session's send and receive path
znet/detail/*, znet/backends/*	internal
extensions/* (znet::ext)	experimental	Each extension is promoted on its own once its shape has settled; see Extensions