server / server-common

Purpose

server-common/ and server/ are two Java modules that hold broker-side infrastructure that is shared across multiple components (the Scala broker in core/, the coordinators, metadata/, tools/). They exist because parts of the broker have been progressively ported from Scala to Java; rather than putting that code back into core/, the project keeps it in dedicated modules so that downstream components can consume it without dragging in core/'s Scala dependency.

Module split

Module	Contents
server-common	Tier-0 infrastructure used by almost every other module: server config classes, MetadataVersion, time-related helpers, fault-handler API, security plumbing, common utilities.
server	Broker-side helpers that depend on metadata/ and storage/ — share-related types, persister, broker quotas, AssignmentsManager, etc.

server-common/src/main/java/org/apache/kafka/
├── server/                                           ← top-level package; almost everything is here
│   ├── common/MetadataVersion.java                  ← cluster-wide feature levels
│   ├── common/ApiMessageAndVersion.java             ← envelope around generated record types
│   ├── config/ServerConfigs.java, KRaftConfigs.java, ReplicationConfigs.java, ServerLogConfigs.java, ...
│   ├── authorizer/Authorizer.java                   ← public Authorizer SPI (used by core + StandardAuthorizer)
│   ├── fault/FaultHandler.java
│   ├── metrics/                                      ← KafkaYammerMetrics adapter, telemetry
│   ├── purgatory/DelayedOperation.java               ← timing-wheel + per-key DelayedOperationPurgatory
│   ├── replica/ClientMetadata.java                   ← rack-aware fetch metadata
│   ├── share/                                         ← share-group API types used by core
│   ├── network/EndPoint.java, BrokerEndPoint.java
│   └── util/CommandLineUtils, ShutdownableThread, ...

server/src/main/java/org/apache/kafka/server/
├── share/                ← Persister, ShareGroupOffsetReader, etc. — used by share coordinator + core
├── AssignmentsManager.java
├── ProcessRole.java       ← enum used by KafkaRaftServer / SharedServer
└── ...

Why this exists

Until 2021, all broker code lived in Scala under core/. The KRaft transition introduced a lot of new logic (controller, metadata image, replication) that was implemented in Java. To make that code reusable across metadata/, core/, and the coordinator modules without forcing all consumers to depend on core/'s Scala compilation, shared infrastructure moved into server-common/ (and later server/). New broker code is generally added in Java in one of these two modules; only logic that genuinely needs to be in core/ (the Scala request pipeline) stays there.

Highlights

MetadataVersion (KIP-778)

server-common/.../server/common/MetadataVersion.java is the master enum of cluster-wide feature levels. Every behavior that is gated on a cluster upgrade — new RPCs, new on-disk record types, new controller features — declares a MetadataVersion and checks metadataVersion.isAtLeast(...) before turning the new behavior on. The controller's FeatureControlManager and UpdateFeatures admin RPC manage transitions.

Feature levels

Beyond the global metadata.version, individual subsystems have their own feature level (e.g., kraft.version, transaction.version, share.version, eligible.leader.replicas.version). Each is registered in Features.java and stored as a FeatureLevelRecord in the metadata log so that brokers can consult the active level without needing to know all of MetadataVersion's axes.

Server configs

Most broker config classes are now in server-common/.../server/config/:

• ServerConfigs.java — generic server options.
• KRaftConfigs.java — KRaft / controller-quorum options.
• ReplicationConfigs.java — replication / ISR options.
• ServerLogConfigs.java — log dir + retention defaults.
• QuotaConfigs.java — per-client quotas.
• DelegationTokenManagerConfigs.java.
• ZkConfigs.java (legacy stub; ZooKeeper is removed but a few enum names remain for upgrade tests).

KafkaConfig in core/ aggregates these and adds Scala validation on top.

Purgatory and DelayedOperation

server-common/.../server/purgatory/ is the canonical timing-wheel-based purgatory used for delayed broker operations (delayed produce, delayed fetch, delayed share fetch, delayed transaction marker). It replaced the older Scala implementation and is now used by both Java and Scala code paths.

Authorizer SPI

The pluggable Authorizer interface lives in server-common/.../server/authorizer/. The default implementation, StandardAuthorizer, lives in metadata/; alternative authorizers (e.g., LDAP-based) implement this interface and are wired in via authorizer.class.name.

Share infrastructure (server/)

server/.../share/ holds the shared types between the share coordinator and the broker request handler: Persister (the SPI for storing share-group state, default impl uses __share_group_state), ShareGroupOffsetReader, etc. The split keeps the share coordinator's record schemas independent of broker internals.

Entry points for modification

• Add a new server config: declare it in the appropriate *Configs class, then expose it through KafkaConfig in core/. Almost always needs a KIP.
• Add a new MetadataVersion: append to the enum, gate the new feature behind metadataVersion.isAtLeast(...), update upgrade tests.
• Add a new feature level: add a FeatureVersion impl, register in Features.java, plumb through FeatureControlManager.
• Change purgatory semantics: DelayedOperation.java and DelayedOperationPurgatory.java in server-common/.../server/purgatory/.

Related pages

• Modules: core (broker) — main consumer of server-common/ types.
• Modules: metadata — MetadataVersion ties the controller / loader together.
• Modules: coordinators — server/ share types.