Thanks for the feedback. I'll move this discussion to a vot.
-- Matteo Merli <[email protected]> On Mon, Mar 2, 2026 at 6:02 PM Tao Jiuming <[email protected]> wrote: > > +1 > > Matteo Merli <[email protected]>于2026年2月28日 周六01:50写道： > > > https://github.com/apache/pulsar/pull/25275 > > > > > > # PIP-457: Remove support for V1 topic names and V1 Admin API > > > > ## Background knowledge > > > > Apache Pulsar historically supported two topic naming formats: > > > > - **V1 format**: `persistent://tenant/cluster/namespace/topic` — > > includes the cluster name in the topic path > > - **V2 format**: `persistent://tenant/namespace/topic` — omits the > > cluster name, making all namespaces implicitly "global" > > > > The V1 format was the original naming convention from Pulsar's early > > days. PIP-10 introduced V2 topic names in Pulsar 2.0 (released June > > 2018) by removing the cluster component, and PIP-11 further simplified > > naming with short topic names defaulting to > > `persistent://public/default/`. V1 topic names have been deprecated > > since Pulsar 2.0 — nearly 8 years ago at the time of this proposal. > > > > The V1 naming format also implied a separate set of Admin REST API > > endpoints, Lookup endpoints, and WebSocket paths that include > > `{property}/{cluster}/{namespace}` in their URL structure, as opposed > > to the V2 paths using `{tenant}/{namespace}`. > > > > These V1 APIs have been deprecated and hidden from the API > > documentation for many years. The V2 format has been the recommended > > and default format since Pulsar 2.0. > > > > ## Motivation > > > > The continued presence of V1 topic name support imposes several costs > > on the project: > > > > 1. **Maintenance burden**: Every Admin API operation must be > > duplicated across V1 and V2 endpoint classes (`v1.PersistentTopics`, > > `v1.NonPersistentTopics`, `v1.Namespaces`, `v1.TopicLookup` alongside > > their V2 counterparts). Bug fixes and new features touching admin APIs > > must account for both code paths. > > > > 2. **Increased attack surface**: The V1 endpoints are hidden from > > documentation but still active and routable, creating undocumented API > > surface area that must be secured, tested, and maintained. > > > > 3. **Code complexity in TopicName parsing**: The `TopicName` class > > must handle both 3-part (V2) and 4-part (V1) name parsing, and the > > `isV2()` check propagates throughout the broker, lookup, and client > > code. > > > > 4. **WebSocket handler complexity**: WebSocket paths must support both > > `/ws/producer/persistent/{property}/{cluster}/{namespace}/{topic}` > > (V1) and `/ws/v2/producer/persistent/{tenant}/{namespace}/{topic}` > > (V2). > > > > 5. **Confusion for new contributors and operators**: The existence of > > two naming schemes and two sets of admin APIs creates unnecessary > > confusion and cognitive overhead. > > > > 6. **Test matrix expansion**: V1 paths must be covered by integration > > and unit tests, expanding the test matrix without providing value to > > modern deployments. > > > > V1 topics have been deprecated since Pulsar 2.0, released in June > > 2018. With nearly 8 years having passed and the project now on the 4.x > > release line, it is time to complete this deprecation and remove V1 > > support entirely. > > > > ## Goals > > > > ### In Scope > > > > - Remove all V1 Admin REST API endpoint classes and their registrations: > > - `org.apache.pulsar.broker.admin.v1.PersistentTopics` > > - `org.apache.pulsar.broker.admin.v1.NonPersistentTopics` > > - `org.apache.pulsar.broker.admin.v1.Namespaces` > > - `org.apache.pulsar.broker.admin.v1.Clusters` (if present) > > - Remove V1 topic lookup endpoint: > > - `org.apache.pulsar.broker.lookup.v1.TopicLookup` > > - Remove V1 WebSocket handler paths > > - Remove V1 (4-part) topic name parsing from `TopicName` and related > > classes > > - Remove `isV2()` method and all conditional branching based on V1 vs > > V2 topic format > > - Remove `LOOKUP_PATH_V1` constant and related redirect logic > > - Remove or update all tests that exercise V1 code paths > > - Update CLI tools that may still reference V1 format > > - Log a clear error message if a client attempts to use a V1-style > > topic name, to aid migration > > > > ### Out of Scope > > > > - Removal of the V2 Admin API in favor of V4 (that would be a separate PIP) > > - Changes to the binary protocol wire format > > - Metadata store migration of existing V1 topic metadata (this PIP > > covers code removal; data migration would be addressed separately if > > needed) > > > > ## High Level Design > > > > The removal will be executed in a single coordinated change: > > > > 1. **Admin API**: Delete the `v1` package under > > `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/` and > > remove the registration of V1 REST resources from the broker's web > > server initialization. > > > > 2. **Lookup**: Delete > > > > `pulsar-broker/src/main/java/org/apache/pulsar/broker/lookup/v1/TopicLookup.java` > > and remove its registration. > > > > 3. **TopicName parsing**: Simplify `TopicName` to only accept the > > 3-part V2 format (`domain://tenant/namespace/localName`). If a 4-part > > name is provided, throw a clear `IllegalArgumentException` with a > > message explaining V1 names are no longer supported and how to > > convert. > > > > 4. **WebSocket**: Remove V1 URI parsing paths from > > `AbstractWebSocketHandler` and related classes. > > > > 5. **Tests**: Remove or convert all V1-specific test cases. Tests that > > coincidentally use V1 names should be updated to V2 format. > > > > ## Detailed Design > > > > ### Admin API Removal > > > > The following classes will be deleted: > > - > > `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/PersistentTopics.java` > > - > > `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/NonPersistentTopics.java` > > - > > `pulsar-broker/src/main/java/org/apache/pulsar/broker/admin/v1/Namespaces.java` > > > > Their registration in the broker's Jersey/JAX-RS application > > configuration will be removed. > > > > ### TopicName Simplification > > > > In `pulsar-common`, the `TopicName` class will be modified: > > > > ```java > > // Before: accepts both V1 (4 parts) and V2 (3 parts) > > // After: only accepts V2 (3 parts) > > private TopicName(String completeTopicName) { > > // ... parse domain:// > > String[] parts = rest.split("/", 3); // tenant/namespace/localName > > if (parts.length != 3) { > > throw new IllegalArgumentException( > > "Invalid topic name '" + completeTopicName + "'. " > > + "Expected format: 'persistent://tenant/namespace/topic'. " > > + "V1 topic names (with cluster component) are no longer > > supported. " > > + "Please use the V2 format without the cluster name."); > > } > > this.tenant = parts[0]; > > this.namespace = parts[1]; > > this.localName = parts[2]; > > // cluster field removed entirely > > } > > ``` > > > > The `isV2()` method and `cluster` field will be removed from > > `TopicName`. All call sites that branch on `isV2()` will be > > simplified. > > > > The `NamespaceName` class will similarly be simplified to remove V1 > > support. > > > > ### Lookup Simplification > > > > The `LOOKUP_PATH_V1` constant and any conditional logic choosing > > between V1/V2 redirect paths will be removed. Lookups will only use V2 > > paths. > > > > ### WebSocket Simplification > > > > The `getTopic()` method in WebSocket handler classes will be > > simplified to only parse V2-style URIs (`/ws/v2/...`). > > > > ## Public-facing Changes > > > > ### REST API > > > > The following REST API paths will be **removed**: > > > > **Persistent Topics (V1)**: > > - `GET /admin/persistent/{property}/{cluster}/{namespace}` — list topics > > - `GET/PUT/DELETE > > /admin/persistent/{property}/{cluster}/{namespace}/{topic}/...` — all > > topic operations > > - `GET/PUT/DELETE > > /admin/persistent/{property}/{cluster}/{namespace}/partitioned` — > > partitioned topic operations > > > > **Non-Persistent Topics (V1)**: > > - `GET /admin/non-persistent/{property}/{cluster}/{namespace}` — list > > topics > > - `GET/PUT/DELETE > > /admin/non-persistent/{property}/{cluster}/{namespace}/{topic}/...` — > > all topic operations > > > > **Namespaces (V1)**: > > - `GET/PUT/DELETE /admin/namespaces/{property}/{cluster}/{namespace}` > > — all namespace operations > > > > **Lookup (V1)**: > > - `GET > > /lookup/v2/destination/{topic-domain}/{property}/{cluster}/{namespace}/{topic}` > > — topic lookup > > > > ### Binary Protocol > > > > No changes to the binary protocol. > > > > ### Configuration > > > > No new configuration. The broker configuration key `allowV1Topics` may > > be considered for a transitional release but is **not** proposed here > > — the removal is clean and complete. > > > > ### CLI > > > > `pulsar-admin` and `pulsar-client` CLI tools will only accept V2 topic > > names. Passing a V1 topic name will produce a clear error message with > > migration guidance. > > > > ### Metrics > > > > No metrics changes. > > > > ## Monitoring > > > > Operators should monitor for client errors after the upgrade. Clients > > attempting to use V1 topic names will receive clear error responses > > (HTTP 404 for V1 admin paths, or client-side > > `IllegalArgumentException` for V1 topic names). > > > > ## Security Considerations > > > > This change reduces the API attack surface by removing undocumented > > but active REST endpoints. No new security considerations are > > introduced. > > > > ## Backward & Forward Compatibility > > > > ### Upgrade > > > > This is a **breaking change** for any deployment still using V1 topic > > names or V1 Admin API paths. > > > > Before upgrading to the version containing this change, operators must: > > 1. Ensure all topic names in use follow the V2 format > > (`persistent://tenant/namespace/topic`) > > 2. Ensure all Admin API clients use V2 endpoints (`/admin/v2/...`) > > 3. Ensure all WebSocket clients use V2 paths (`/ws/v2/...`) > > > > The V1 format has been deprecated since Pulsar 2.0, released in June > > 2018 — nearly 8 years ago. Any deployment that has been maintained on > > a supported Pulsar version should already be using V2 format > > exclusively. > > > > ### Downgrade / Rollback > > > > Rolling back to a prior version that supports V1 topic names will work > > without issues, as no data format changes are involved. > > > > ### Geo-Replication > > > > No impact. Geo-replication already uses V2 topic names. The cluster > > component in V1 topic names was originally related to replication > > configuration but has been decoupled since V2 was introduced. > > > > ## General Notes > > > > ### Related PIPs > > - PIP-10: Remove cluster from topic name (introduced V2 naming) > > - PIP-11: Short topic name (further simplified topic naming) > > - PIP-48: Proposed V4 admin API (future direction for admin APIs) > > > > ### Migration Guide > > > > For any users who may still be using V1 topic names, the migration is > > straightforward: > > > > | V1 Format | V2 Format | > > |---|---| > > | `persistent://my-tenant/my-cluster/my-namespace/my-topic` | > > `persistent://my-tenant/my-namespace/my-topic` | > > | `/admin/persistent/my-tenant/my-cluster/my-namespace` | > > `/admin/v2/persistent/my-tenant/my-namespace` | > > | `/ws/producer/persistent/my-tenant/my-cluster/my-ns/my-topic` | > > `/ws/v2/producer/persistent/my-tenant/my-ns/my-topic` | > > > > Simply remove the cluster component from the topic name path. > > > > > > > > > > > > -- > > Matteo Merli > > <[email protected]> > >
