Add August 2026 preview support for Web PubSub Chat

Generate from the corrected specification and update samples and documentation. Verify the complete sync/async live suite in Central US EUAP, remove the routing workaround, and upload sanitized latest-version recordings. Track the independent upstream async paging limitation without customization.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: Y-Sindo

sdk/webpubsub/azure-messaging-webpubsub-chat/AGENTS.md

@@ -0,0 +1,15 @@
+# Web PubSub Chat development constraints
+
+Before changing tests, recording tests, regenerating, or releasing this package,
+read [KNOWN_ISSUES.md](KNOWN_ISSUES.md) for the pending upstream Java
+generator paging fix. Do not add a paging customization; preserve strict
+regression assertions and verify the upstream fix after regeneration.
+
+Run live tests against a Chat-enabled resource in the TTL = 7 days subscription.
+The server routing fix was verified in Central US EUAP on 2026-10-13 using the
+complete sync/async live suite. All operations, including setup and cleanup,
+use `2026-08-01-preview`; do not restore legacy-version clients or routing skips.
+Upload sanitized recordings and verify clean-cache playback after test changes.
+
+Before publishing an issue, PR, or team message for this package, show the user
+the destination and exact draft and obtain explicit approval.

sdk/webpubsub/azure-messaging-webpubsub-chat/CHANGELOG.md

@@ -4,12 +4,20 @@
 
 ### Features Added
 
+- Added support for service API version `2026-08-01-preview`, now the default service version.
+- Added synchronous and asynchronous operations to list rooms, users, and rooms associated with a user.
+- Added topic creation, replacement, retrieval, update, soft deletion, and listing.
+- Added `ChatTopic`, `ChatTopicState`, and the read-only `ChatUserRoom` projection.
+
 ### Breaking Changes
 
 ### Bugs Fixed
 
 ### Other Changes
 
+- Verified all existing and new operations end to end with `2026-08-01-preview` in Central US EUAP; removed the temporary server routing workaround and restored the complete live/playback suite.
+- Tracked the upstream typed asynchronous page-size defect in [microsoft/typespec#12149](https://github.com/microsoft/typespec/issues/12149). No paging customization is applied; tests temporarily use protocol overloads for asynchronous page-size checks.
+
 ## 1.0.0-beta.1 (2026-09-15)
 
 - Azure WebPubSubChat client library for Java. This package contains Microsoft Azure WebPubSubChat client library.

sdk/webpubsub/azure-messaging-webpubsub-chat/KNOWN_ISSUES.md

@@ -0,0 +1,78 @@
+# Web PubSub Chat SDK known generator issues
+
+## Typed asynchronous paging ignores the requested page size
+
+- **Tracking issue:** [microsoft/typespec#12149](https://github.com/microsoft/typespec/issues/12149).
+- **Status:** Awaiting an upstream Java generator fix; reproduced with
+  `@azure-tools/typespec-java` 0.48.0 on 2026-10-09.
+- **User decision:** Do not add a paging customization or manually repair
+  generated SDK code. Wait for the generator team to fix the implementation.
+
+The typed asynchronous paged convenience methods accept `pageSizeParam` but
+discard it when delegating to `PagedFlux<BinaryData>`. For example,
+`asyncClient.listRoomsForUser("alice").byPage(1)` does not send `maxpagesize=1`.
+Default continuation-token paging still works; the page-size override is
+ignored. Synchronous typed paging forwards the page size correctly.
+
+This affects both existing operations (`listRoles`, `listRoomMembers`,
+`listMessages`) and the new operations (`listRooms`, `listTopics`, `listUsers`,
+`listRoomsForUser`). The defect predates this package's August API upgrade; the
+first affected generator release has not been determined.
+
+### Approved temporary test workaround
+
+The user approved disabling only
+`WebPubSubChatPaginationTests.asyncPageSizeReachesFirstAndNextRequests`; its
+seven strict cases and assertions remain intact. New async live pagination tests
+use the existing protocol overloads, such as
+`asyncClient.listTopics(roomId, new RequestOptions()).byPage(1)`, and still assert
+one item per page and follow continuation requests. Default typed async
+collection/model coverage remains enabled. No production paging customization
+or generated-code repair is applied.
+
+The mock suite also verifies first and next request page sizes for all seven
+protocol async list methods. Passing these tests does not mean the typed async
+generator defect is fixed.
+
+The implementation belongs to the shared
+[Java generator in microsoft/typespec](https://github.com/microsoft/typespec/blob/main/packages/http-client-java/generator/http-client-generator-core/src/main/java/com/microsoft/typespec/http/client/generator/core/template/ConvenienceAsyncMethodTemplate.java).
+The original [Azure/typespec-azure#5657](https://github.com/Azure/typespec-azure/issues/5657)
+was filed in the wrong repository and is closed.
+
+### Checking whether it has been fixed
+
+1. Check the tracking issue and the version of `@azure-tools/typespec-java` in
+   `eng/emitter-package.json`. An issue being closed does not prove that the
+   installed emitter includes the fix.
+2. After the repository adopts a generator release containing the fix,
+   regenerate the package using its pinned `tsp-location.yaml`. Do not bypass
+   the issue by adding a customization.
+3. Remove the issue-linked `@Disabled` annotation from
+   `asyncPageSizeReachesFirstAndNextRequests`, then run the strict,
+   credential-free regression tests:
+
+   ```powershell
+   mvn -f sdk\webpubsub\azure-messaging-webpubsub-chat\pom.xml test "-Dtest=WebPubSubChatPaginationTests" "-Dgpg.skip=true" "-Drevapi.skip=true"
+   ```
+
+   `WebPubSubChatPaginationTests` covers all seven sync and async list operations.
+   It asserts `maxpagesize=1` on **both first-page and continuation requests**,
+   and checks that the corrected `listRoomsForUser` continuation overload sends
+   a query parameter. The original 16-case reproduction produced seven async
+   failures and nine passes. The protocol async cases were added for the
+   approved test workaround. Do not weaken the assertions or accept skipped async
+   page-size cases as evidence of a fix.
+4. Verify the new sync/async live pagination scenarios, then verify sanitized
+   recording playback using the persisted `assets.json` tag. Check actual page
+   sizes and continuation requests, not only whether a non-empty page exists.
+5. Only mark this issue resolved after the generated code and all strict
+   regression cases pass. Switch async live page-size checks back to the typed
+   overloads and remove the temporary test workaround at that point.
+
+### Server routing fix is independent
+
+The server routing issue was verified fixed in Central US EUAP on 2026-10-13:
+all 14 sync/async live scenarios passed with `2026-08-01-preview`, including
+existing operations and setup/cleanup. The routing workaround and its temporary
+skill have been removed. This does not fix the typed async paging generator
+defect; retain its strict regression cases and the protocol paging workaround.

sdk/webpubsub/azure-messaging-webpubsub-chat/README.md

@@ -6,6 +6,8 @@ Use this client library in an application server to:
 
 - Create and manage Chat roles and permissions.
 - Create users, rooms, and room memberships.
+- List rooms and users in a hub, or list the rooms associated with a user.
+- Create, get, update, list, and soft delete topics in a room.
 - Get room conversations and query persisted message history.
 - Update and delete persisted messages.
 - Generate client access credentials for Chat WebSocket clients.
@@ -21,19 +23,22 @@ Use this client library in an application server to:
 - An [Azure Web PubSub resource][create_instance].
 - A Web PubSub hub with [Chat enabled][enable_chat].
 
-### 1. Add the package to your project
+### Install the package
+
+The following dependency shows the current development version. It has not been
+released to Maven Central; build it locally when evaluating the new API.
 
 [//]: # ({x-version-update-start;com.azure:azure-messaging-webpubsub-chat;current})
 ```xml
 <dependency>
     <groupId>com.azure</groupId>
     <artifactId>azure-messaging-webpubsub-chat</artifactId>
-    <version>1.0.0-beta.1</version>
+    <version>1.0.0-beta.2</version>
 </dependency>
 ```
 [//]: # ({x-version-update-end})
 
-### 2. Create and authenticate a `WebPubSubChatServiceClient`
+### Create and authenticate a client
 
 The client supports a connection string, an `AzureKeyCredential`, or a Microsoft Entra ID token credential. The hub passed to the client must have Chat enabled.
 
@@ -98,6 +103,19 @@ A user represents an application identity that can send and receive messages. A
 
 A room groups users together and is the primary organizational unit for chat interactions. Every room has an automatically created default conversation.
 
+### Topic
+
+A topic is a named conversation in a room. Each topic has a title, creation time,
+creator, conversation ID, ETag, and lifecycle state. `ChatTopicState` includes
+`NORMAL`, `ARCHIVED`, and `SOFT_DELETED`. The August API adds topic management;
+topic deletion is a soft delete rather than a room deletion.
+
+### User's rooms
+
+`listRoomsForUser` returns read-only `ChatUserRoom` projections of the rooms
+associated with a user. A projection contains the room ID, title, default
+conversation ID, and ETag; it does not provide a separate room lifecycle.
+
 ### Room member
 
 A room member represents a user added to a room. Membership controls which users can receive and send messages in the room. Each room member is assigned a room role.
@@ -131,61 +149,174 @@ String memberRole = BuiltInChatRoles.ROOM_MEMBER;
 ChatPermission publishPermission = ChatPermission.ROOM_PUBLISH_MESSAGE;
 ```
 
-### Create and list a custom role
+The following examples are independent operations. Where an operation refers to
+`general`, `alice`, or `announcements`, the corresponding resources must already
+exist. All examples use the default `2026-08-01-preview` API version.
+
+### Create a custom role
 
-```java readme-sample-manageChatRoles
+```java readme-sample-createChatRole
 ChatRole moderator = new ChatRole(Arrays.asList(ChatPermission.ROOM_HISTORY,
     ChatPermission.ROOM_REMOVE_USER, ChatPermission.ROOM_PUBLISH_MESSAGE));
 client.createOrReplaceRole("room.moderator", moderator);
+```
 
+### List roles
+
+```java readme-sample-listChatRoles
 client.listRoles().forEach(role -> System.out.println(role.getName()));
+```
+
+### Delete a custom role
+
+```java readme-sample-deleteChatRole
 client.deleteRole("room.moderator");
 ```
 
-### Create a user, room, and room membership
+Remove references to a custom role before deleting it.
+
+### Create a user
+
+```java readme-sample-createChatUser
+client.createOrReplaceUser("alice", new HumanChatUser("Alice", BuiltInChatRoles.USER_NORMAL));
+```
 
-```java readme-sample-manageChatRooms
-client.createOrReplaceRole("user.room_creator",
-    new ChatRole(Arrays.asList(ChatPermission.USER_CREATE_ROOM)));
-client.createOrReplaceRole("room.contributor",
-    new ChatRole(Arrays.asList(ChatPermission.ROOM_PUBLISH_MESSAGE)));
-client.createOrReplaceUser("alice", new HumanChatUser("Alice", "user.room_creator"));
+### Create a room
 
+```java readme-sample-createChatRoom
 ChatRoom room = client.createOrReplaceRoom("general", new ChatRoom("General"));
+String defaultConversationId = room.getDefaultConversation();
+```
+
+### Add a room member
+
+```java readme-sample-addChatRoomMember
 ChatRoomMember member = client.createOrReplaceRoomMember(
-    room.getId(), "alice", new ChatRoomMember("room.contributor"));
+    "general", "alice", new ChatRoomMember(BuiltInChatRoles.ROOM_MEMBER));
 System.out.printf("%s: %s%n", member.getUserId(), member.getRoleName());
+```
+
+### List rooms
 
-client.deleteRoom(room.getId());
-client.deleteUser("alice");
-client.deleteRole("room.contributor");
-client.deleteRole("user.room_creator");
+```java readme-sample-listChatRooms
+client.listRooms().forEach(room -> System.out.printf("%s: %s%n", room.getId(), room.getTitle()));
 ```
 
-Delete dependent resources in reverse order when they are no longer needed: room, user, and then roles.
+### List users
+
+```java readme-sample-listChatUsers
+client.listUsers().forEach(user -> System.out.printf("%s: %s%n", user.getId(), user.getNickname()));
+```
+
+### List rooms for a user
+
+```java readme-sample-listChatRoomsForUser
+client.listRoomsForUser("alice").forEach(room ->
+    System.out.printf("%s: %s%n", room.getId(), room.getTitle()));
+```
+
+List operations return `PagedIterable` on the synchronous client and `PagedFlux`
+on the asynchronous client. Iteration fetches subsequent pages automatically.
+To process synchronous results page by page, use `iterableByPage(pageSize)`.
+
+### Create a topic
+
+The parent room must already exist.
+
+```java readme-sample-createChatTopic
+ChatTopic topic = client.createOrReplaceTopic("general", "announcements",
+    new ChatTopic().setTitle("Announcements"));
+String conversationId = topic.getConversationId();
+```
+
+Use the returned conversation ID when a Chat WebSocket client sends messages to
+the topic. This server-side library manages resources and persisted messages;
+it is not a WebSocket chat client.
+
+### Get a topic
+
+```java readme-sample-getChatTopic
+ChatTopic topic = client.getTopic("general", "announcements");
+System.out.printf("%s: %s%n", topic.getTitle(), topic.getState());
+```
+
+### Update a topic
+
+Only explicitly set properties are included in the merge-patch request.
+Use the overload accepting `MatchConditions` and the current ETag to prevent
+overwriting another caller's changes.
+
+```java readme-sample-updateChatTopic
+ChatTopic updated = client.updateTopic("general", "announcements",
+    new ChatTopic().setTitle("Archived announcements").setState(ChatTopicState.ARCHIVED));
+```
+
+### List topics
+
+```java readme-sample-listChatTopics
+client.listTopics("general").forEach(topic ->
+    System.out.printf("%s: %s%n", topic.getId(), topic.getTitle()));
+```
+
+### Soft delete a topic
+
+```java readme-sample-deleteChatTopic
+client.deleteTopic("general", "announcements");
+```
 
 ### List persisted messages
 
 ```java readme-sample-listChatMessages
-ChatRoom room = client.getRoom("general");
-client.listMessages(room.getDefaultConversation()).forEach(message ->
+String conversationId = "<conversation-id>";
+client.listMessages(conversationId).forEach(message ->
     System.out.printf("%s: %s%n", message.getCreatedBy(), message.getContent().getText()));
 ```
 
+Use a conversation ID returned by room or topic creation. Message history
+queries return messages from latest to earliest.
+
 ### Use the asynchronous client
 
 ```java readme-sample-createAsyncChatClient
 WebPubSubChatServiceAsyncClient asyncClient = new WebPubSubChatServiceClientBuilder()
     .connectionString("<web-pubsub-connection-string>")
     .hub("chat")
     .buildAsyncClient();
+```
 
-asyncClient.listRoles().subscribe(role -> System.out.println(role.getName()));
+Subscribe to the returned publisher to execute an asynchronous operation, and
+handle errors explicitly:
+
+```java readme-sample-listChatTopicsAsync
+asyncClient.listTopics("general").subscribe(
+    topic -> System.out.println(topic.getTitle()),
+    error -> System.err.println("Could not list topics: " + error.getMessage()));
+```
+
+#### Known asynchronous page-size limitation
+
+The generator currently ignores `byPage(pageSize)` on typed asynchronous
+collections. Default continuation paging is unaffected. Until
+[microsoft/typespec#12149](https://github.com/microsoft/typespec/issues/12149)
+is fixed in the emitter used by this package, use the existing protocol overload
+when an explicit asynchronous page size is required:
+
+```java readme-sample-listChatTopicsAsyncByPage
+asyncClient.listTopics("general", new RequestOptions()).byPage(10).subscribe(
+    page -> page.getValue().forEach(data -> System.out.println(data.toObject(ChatTopic.class).getTitle())),
+    error -> System.err.println("Could not list topic pages: " + error.getMessage()));
 ```
 
+See [known generator issues](KNOWN_ISSUES.md) for verification and removal of the
+temporary test workaround. No paging customization is applied.
+
 ### Service API versions
 
-The client library targets the latest service API version by default. To use another supported version, pass a `WebPubSubChatServiceVersion` to the builder's `serviceVersion` method. Verify that the selected version supports the operations and models used by your application.
+The default is `WebPubSubChatServiceVersion.V2026_08_01_PREVIEW`. The library also
+supports `V2026_02_01_PREVIEW` for existing operations. Topic operations and the
+new room/user listing operations require the August version. To select a version,
+pass it to the builder's `serviceVersion` method. All operations are supported
+with the August API; no separate client is needed for existing operations.
 
 ## Troubleshooting
 
@@ -210,6 +341,8 @@ Explore the [complete package samples][samples] to learn how to:
 
 - Authenticate with a connection string, access key, or Microsoft Entra ID.
 - Manage roles, permissions, users, rooms, and room members.
+- List rooms and users, and query rooms associated with a user.
+- Manage topics and their lifecycle states.
 - Generate client access credentials.
 - Query, update, and delete message history.
 - Use synchronous and asynchronous clients.

sdk/webpubsub/azure-messaging-webpubsub-chat/assets.json

@@ -1 +1 @@
-{"AssetsRepo":"Azure/azure-sdk-assets","AssetsRepoPrefixPath":"java","TagPrefix":"java/webpubsub/azure-messaging-webpubsub-chat","Tag": "java/webpubsub/azure-messaging-webpubsub-chat_395861d3d4"}
+{"AssetsRepo":"Azure/azure-sdk-assets","AssetsRepoPrefixPath":"java","TagPrefix":"java/webpubsub/azure-messaging-webpubsub-chat","Tag": "java/webpubsub/azure-messaging-webpubsub-chat_a649b09111"}