Skip to content

Release 0.33.0 #115

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
SNWCreations merged 11 commits into from
Dec 14, 2025
Merged

Release 0.33.0 #115

SNWCreations merged 11 commits into from
Dec 14, 2025

Conversation

@SNWCreations
Copy link
Owner

@SNWCreations SNWCreations commented Nov 15, 2025

@RealSeek @huanmeng-qwq @SNWCreations
refactor: huge project refactor powered by Claude AI (#113)
57ba115 
* build!(core): upgrade to java 21 and adopt virtual threads

- update java target and minimum toolchain to version 21 in build configuration
- add `VirtualThreadUtil` to provide high-performance virtual thread-based executors
- refactor schedulers, event executors, and network threads to use virtual threads
- this improves concurrency and performance for I/O-bound tasks throughout the application

BREAKING CHANGE: The project now requires Java 21 or later to build and run.

* perf(json): migrate from gson to jackson for core json processing

- introduce `JacksonUtil` as a high-performance replacement for `GsonUtil`
- add jackson dependencies to the project build configuration
- refactor `HttpAPIImpl` to use jackson for parsing api responses, improving performance

* test(framework): introduce comprehensive testing and benchmarking suite

- add a full suite of unit tests using JUnit 5, Mockito, and AssertJ for core components
- configure JaCoCo for code coverage reporting and set coverage verification goals
- set up JMH (Java Microbenchmark Harness) for performance benchmarking
- add benchmark tests for virtual threads vs platform threads and jackson vs gson

* docs(architecture): add extensive project and module architecture documentation

- create detailed markdown documents for a project overview and key modules
- document the architecture of the core, command, entity, event, network, and plugin systems
- use mermaid diagrams to illustrate system design, class relationships, and data flows

* refactor(json)!: migrate core JSON processing from Gson to Jackson

This commit replaces Gson with Jackson as the primary JSON processing library.
The migration significantly improves performance and enhances robustness against
incomplete API responses by providing better null-safety.

New stuff:
- introduced `JacksonUtil` for high-performance, null-safe JSON handling
- introduced `JacksonCardUtil` for specialized card message serialization

Refactor:
- network layer now uses `JsonNode` for API responses
- entity builders (`EntityBuilder`, `MessageBuilder`) now prioritize Jackson for safer construction
- all event deserializers updated to use Jackson with a Gson fallback for compatibility
- all entity implementations (`*Impl.java`) now support updates from `JsonNode`
- all page iterators now process `JsonNode` for improved performance

Docs:
- updated architecture documents (`CLAUDE.md`) to reflect the new dual-engine JSON architecture

BREAKING CHANGE: The core JSON processing engine has been switched from Gson to Jackson.
Internal APIs that previously exposed `com.google.gson.JsonObject` now primarily use
`com.fasterxml.jackson.databind.JsonNode`. While compatibility layers are in place, projects
with deep integration may need adjustments.

* feat(async): introduce virtual threads for enhanced performance and async apis

- feat(util): Introduced `VirtualThreadUtil` for centralized management of Java 21 virtual threads.
  - Provides dedicated, lazily-initialized executors for tasks like HTTP, File I/O, and plugins.
  - Includes performance monitoring for thread creation and task execution.

- perf(event): Implemented optional parallel event processing using virtual threads.
  - Allows concurrent execution of event listeners to significantly improve throughput.
  - Added advanced performance monitoring with periodic reports for the event system.
  - New settings are configurable in `kbc.yml`.

- perf(network): Added an asynchronous API to `NetworkClient` for non-blocking operations.
  - New `*Async` methods leverage virtual threads for high-concurrency HTTP requests.
  - Introduced batch methods (`batchGetAsync`, `batchPostAsync`) for parallel API calls.

- perf(plugin): Implemented asynchronous methods for plugin management in `SimplePluginManager`.
  - New `*Async` methods (load, enable, disable, reload) prevent blocking during I/O operations.

- perf(storage): Introduced an asynchronous API for `EntityStorage` to improve cache operations.
  - `*Async` methods for fetching entities and managing the cache run on virtual threads.

- fix(channel): Corrected Jackson deserialization for `VoiceChannelImpl.StreamingInfoImpl`.
  - Added `@JsonCreator` and `@JsonProperty` annotations for robust JSON parsing.

* feat(http): introduce async http api with request coalescing

- feat: Add `AsyncHttpAPI` interface and implementation for non-blocking HTTP requests.
- This includes async methods for file uploads (from file, bytes, and URL), entity fetching,
  and batch operations.
- perf: Implement a smart `RequestCoalescer` to merge identical concurrent requests.
- This avoids redundant network calls, significantly improving performance and reducing API spam
  under high load.
- refactor: Update existing synchronous methods to use the new async backend, centralizing
  logic and improving efficiency.
- test: Introduce comprehensive unit tests for all new async functionality and the
  coalescing mechanism.

* perf(network): overhaul http client for enhanced concurrency and performance

- refactor OkHttpClient configuration for high-throughput scenarios
- utilize a virtual thread-backed dispatcher to improve request handling capacity
- configure a larger connection pool (50 idle, 15 min keep-alive) to reduce connection churn
- fine-tune connection, read, write, and call timeouts for better reliability
- enable automatic retries on connection failure and support for HTTP/2 protocol

* feat(util): add dedicated json executor and network monitoring

- util: introduce a dedicated virtual thread executor for json processing to isolate workloads
- network: add methods to monitor connection pool statistics (total, idle, active connections)
- network: implement a method to manually evict all idle connections from the pool

* feat(core): introduce advanced performance and concurrency framework

This update introduces a framework for high-performance JSON processing and asynchronous operations.
- JSON Optimization: 
  - `JsonEngineSelector`: Intelligently selects between Jackson and Gson for optimal performance.
  - `JsonCacheManager`: Implements a Caffeine-based cache for JSON parsing and serialization.
  - `JsonStreamProcessor`: Provides a low-memory, stream-based API for processing large JSON.
- Asynchronous APIs: 
  - `AsyncHttpAPI`: New public interface for non-blocking, high-concurrency HTTP calls.
  - `AsyncFileUtil`: Utility for non-blocking file I/O using virtual threads.
- Performance Benchmarks: 
  - Added JMH benchmarks for new JSON and HTTP connection pool optimizations.

 refactor(card): migrate card serialization from Gson to Jackson

Replaced the entire card message serialization system, moving from Gson to Jackson for improved
performance, flexibility, and robustness.
- Fix: 
  - Addresses a critical bug where empty modules (e.g., `DividerModule`) would fail to serialize.
- Refactor: 
  - Created `JacksonCardUtil` to centralize all card-related JSON logic.
  - Implemented custom Jackson serializers and deserializers for all card components.
- Test: 
  - Added extensive tests to verify the new Jackson-based serialization with complex examples.

 refactor(event): simplify event manager and remove monitoring code

Streamlined `EventManagerImpl` by removing internal performance monitoring and reporting features.
The core parallel event processing logic is retained.
- chore(config): 
  - Removed deprecated performance-related options from the `kbc.yml` configuration file.

* i18n: localize log and cli messages to chinese

- translate log outputs, exception messages, and command-line interface text to chinese
- this change aims to improve the user experience for chinese-speaking users

 refactor(launch): remove redundant startup messages

- remove warning messages about mixin support on launch to provide a cleaner console output

* fix(serializer): enhance robustness of event deserializers

- Improve null-safety in various event deserializers to prevent crashes from malformed API responses.
- ChannelInfoUpdateEventDeserializer: 
  - Add null checks for 'id' and 'type' fields, throwing an exception if 'id' is missing.
- GuildUserNickNameUpdateEventDeserializer: 
  - Add a null check for 'user_id' and default 'nickname' to an empty string.
  - Enable the Jackson deserialization path to leverage its improved null handling.
- UserInfoUpdateEventDeserializer: 
  - Accommodate inconsistent API field naming by checking for both 'user_id' and 'body_id'.
  - Ensure 'username' and 'avatar' updates are null-safe.
- refactor(network): simplify and correct event processing logic

- Change event handling in ListenerImpl to be synchronous, ensuring events are processed in the
  order they are received and preventing race conditions.
- Simplify the logic for processing buffered out-of-order messages by replacing the iterator-based
  loop with a cleaner `while` loop and a dedicated `find()` helper method.
- style: Remove trailing newline in Session.java.

* fix: remove java home path in gradle.properties

* Adapt LiteCommands API, selfProcessor -> self

* build: Update gradle to 9.1.0

* build: gradle 9.14.x

* feat: update line number

* refactor(json): migrate from gson to jackson for all json processing

This commit completes the full migration from GSON to Jackson for all JSON processing
to improve performance, unify the JSON handling library, and simplify the codebase.

Refactor: 
- Remove the GSON dependency entirely from the project.
- Rewrite `GsonUtil` to be a compatibility layer that delegates all operations to Jackson.
- Gut and deprecate `JsonEngineSelector` as it is no longer needed; Jackson is now the sole engine.
- Update entity classes to use Jackson's `JsonNode` for updates, keeping GSON-based methods
  only for backward compatibility.

Build: 
- Update `build.gradle.kts` to remove the GSON library.
- Downgrade Gradle from 9.1 to 8.9.

Test: 
- Update unit tests and performance benchmarks to reflect the removal of GSON and test
  the new Jackson-based implementation.

BREAKING CHANGE: The `Updatable` interface now requires implementing `update(JsonNode data)` instead
of the previous GSON-based `update(JsonObject data)`. All implementers must be updated.

* feat(thread): implement thread channel feature

- feat: Add full support for Kook Thread Channels (Type 4), enabling creation, viewing, and
  interaction with posts and replies.
- feat: Introduce new entities: `ThreadChannel`, `ThreadPost`, `ThreadReply`, and `ThreadCategory`.
- feat: Implement `ThreadPostIterator` and `ThreadReplyIterator` for efficient pagination of posts
  and replies.
- feat: Register new API routes in `HttpAPIRoute` for all thread-related operations.
- feat: Update `EntityBuilder` and `EntityBuildUtil` to correctly construct thread channel entities.

* refactor(core): migrate to jackson and improve schedulers

- refactor: Migrate the entire project from Gson to Jackson for JSON processing, improving
  performance, memory usage, and type safety.
- refactor: Remove all deprecated Gson-based methods, especially in `PageIterator` and event
  deserializer classes.
- refactor: Implement a robust Jackson-based event deserialization system using `JKookEventModule`,
  making it the primary method with Gson as a legacy fallback.
- refactor: Refactor `VirtualThreadUtil` to use platform threads for `ScheduledExecutorService`
  cores, ensuring reliable and precise task scheduling as per best practices.
- refactor: Convert `UserPermissionSaved` to use Jackson for serialization.
- chore: Add `GsonCompat` utility class to offer a compatibility layer during the transition.

* perf(pageiter): optimize entity fetching and pagination

- perf: Enhance `PageIterator` implementations (e.g., `GuildUserListIterator`) to parse full entity
  data from list API responses, drastically reducing unnecessary HTTP calls.
- perf: Improve `PageIteratorImpl` to correctly handle pagination for API endpoints that do not
  return a `meta` block, relying on the item count instead.

* fix(scheduler): correct runTaskTimer argument order

- fix: Correct the parameter order in `SchedulerImpl.runTaskTimer` by swapping `delay` and `period`
  to match the `ScheduledExecutorService#scheduleAtFixedRate` method signature.

* build(deps): update jkook dependency

- build: Update the JKook dependency to `io.github.snwcreations:jkook:0.54.2`.
- build: Modify `build.gradle.kts` and `libs.versions.toml` to reflect the new Maven coordinates
  and version for the JKook library.

* refactor(core)!: complete migration to jackson for json processing

- remove the gson dependency and all related serializer/deserializer classes
- the project now exclusively uses jackson for all json operations, simplifying the codebase and
  dependency tree
- refactor eventfactory to remove gson fallback logic, relying solely on jackson for event
  deserialization
- clean up entity and message classes by removing gson compatibility layers
- update build configuration to remove the gson library

BREAKING CHANGE: The Gson library has been completely removed from the project. All JSON
serialization and deserialization is now handled exclusively by Jackson. Internal components
relying on the old Gson-based infrastructure will no longer work.

* perf(json, entity): optimize JSON object conversion and permission calculation

- introduce JacksonUtil.convertFromGsonJsonObject for direct Gson to Jackson conversion
- eliminate toString() serialization overhead in entity update methods and message builders by using direct conversion
- refactor UserImpl#update by removing redundant internal synchronization
- leverage virtual threads and parallel streams in UserImpl#calculateChannel for concurrent permission evaluation

* docs(architecture): remove CLAUDE.md architecture document

- the CLAUDE.md file, providing project architecture overview, is no longer needed
- this document is being replaced by other, more up-to-date documentation sources

* refactor(json)!: remove GSON and related JSON utilities

- completely remove GSON library and its associated utility classes
- remove GsonCompat, GsonUtil, and JsonEngineSelector as JSON processing
  is now fully handled by JacksonUtil
- update all internal code usages to directly leverage JacksonUtil
  for JSON operations
- remove deprecated JSON processing benchmarks
- simplify the project's JSON processing stack

BREAKING CHANGE: Direct usage of snw.kookbc.util.GsonCompat, snw.kookbc.util.GsonUtil,
and snw.kookbc.util.JsonEngineSelector classes is no longer supported.
All JSON processing now exclusively uses Jackson.

* fix(ws): improve connection stability and smart reconnection

- introduce `ReconnectStrategy` to manage reconnection attempts and delays
- enhance error handling and logging across `Connector` and `WebSocketMessageProcessor`
- refine `Reconnector` thread logic to handle states more robustly
- increase WebSocket connection timeout for better resilience against network fluctuations

* fix(websocket): enhance error logging for message processing

- provide raw message content in error logs for uncompressed WebSocket messages
- include decompressed message in error logs for compressed WebSocket messages
- add byte size to error logs for WebSocket data decompression failures
- simplify static imports for `JacksonUtil` in `ChannelImpl`
- simplify `Collectors` import in `UserImpl`
- simplify `UnknownHostException` usage in `WebSocketMessageProcessor`

* build: bump version to 0.33.0

* feat(network): implement intelligent reconnection strategy 
- introduce `ReconnectStrategy` for robust WebSocket reconnection
- use exponential backoff (1, 2, 4, 8, 16, 32, 60s) with infinite retry
- differentiate recoverable (network) and unrecoverable (auth) exceptions
- automatically reset retry counter after 5 minutes of stable connection
- provide statistics for monitoring reconnection attempts

* refactor(project): remove legacy test infrastructure and AI docs

- delete all JUnit 5 tests, AssertJ assertions, Mockito mocks, and Testcontainers setups
- remove JMH benchmarks for HTTP connection pool, system performance, and virtual threads
- eliminate AI-generated architectural documentation (`CLAUDE.md` files)
- update `build.gradle.kts` to remove test and benchmark dependencies/configurations
- update `.gitignore` to include AI tool directories and generated documentation

---------

Co-authored-by: huanmeng-qwq <1871735932@qq.com>
Co-authored-by: ZX夏夜之风 <snwcreations@qq.com>
huanmeng-qwq
huanmeng-qwq requested changes Nov 15, 2025
View reviewed changes
Copy link
Collaborator

@huanmeng-qwq huanmeng-qwq left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

大量的类没有被导入，请检查完全import后，再次review

@RealSeek
refactor(json)!: remove Gson compatibility methods and consolidate JS…
33beaee 
…ON processing

- The codebase has fully migrated to using Jackson for all JSON parsing and serialization.
- All methods and utilities providing backward compatibility for Gson `JsonObject`
- and `JsonArray` have been removed.
- This includes Gson-specific update methods in entities, builder methods, storage
- methods, and utility conversion functions.
- This change simplifies the codebase, reduces dependency surface, and improves
- performance by removing unnecessary conversions.

BREAKING CHANGE: All Gson-specific compatibility methods and utilities
 have been removed. Code relying on these methods will need to be updated
 to use Jackson directly.
@RealSeek
refactor(imports): simplify utility class references and imports
51b1bde 
- introduce direct imports for `JacksonUtil` and `CardBuilder` to reduce verbosity
- use static import for `JacksonUtil.get` in several files for cleaner code
- remove fully qualified names when calling utility methods to enhance readability
- streamline references to `HttpAPI` and `CardComponent` interfaces
huanmeng-qwq
huanmeng-qwq requested changes Nov 15, 2025
View reviewed changes
src/main/java/snw/kookbc/impl/serializer/event/jackson/BaseJacksonEventDeserializer.java Outdated
* <p>提供事件反序列化的通用逻辑和工具方法。
*
* @param <T> 事件类型
* @since KookBC 0.32.2
Copy link
Collaborator

@huanmeng-qwq huanmeng-qwq Nov 15, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

所有0.32.2应该重命名为0.33.0

@RealSeek
i18n(logs): localize all log messages to chinese
b5cb7a4 
- translate all existing english log messages to chinese for better user experience
- ensure all system and debug outputs are consistently localized
@RealSeek
refactor(network): delegate event processing to executor
fc5df4c 
- execute event handling asynchronously to prevent blocking the current thread
- improve responsiveness by offloading event processing to a dedicated executor
@RealSeek
build(deps): add gson dependency
fbde845 
- introduce gson 2.10.1 as a shadow dependency
- previously removed, gson is now required for specific functionalities or compatibility
huanmeng-qwq
huanmeng-qwq requested changes Nov 16, 2025
View reviewed changes
SNWCreations and others added 3 commits November 23, 2025 20:16
@SNWCreations @huanmeng-qwq
fix: apply suggestions from code review
54d424a 
Co-authored-by: huanmeng_qwq <1871735932@qq.com>
@RealSeek
docs(javadoc): update since version for BaseJacksonEventDeserializer
fd28633 
- change version in @SInCE tag from 0.32.2 to 0.33.0

fix(network): correct typo in reconnect strategy log message

- change "无��重试模式" to "无限重试模式" (meaning "Infinite Retry Mode")
@huanmeng-qwq
Bump version to 0.33.0
e9c7960
@SNWCreations
Copy link
Owner Author

SNWCreations commented Nov 28, 2025

@xiaoACE6716

xiaoACE6716
xiaoACE6716 reviewed Nov 28, 2025
View reviewed changes
src/main/java/snw/kookbc/CLIOptions.java Outdated
NO_BUCKET = Boolean.getBoolean("kookbc.nobucket");
if (NO_BUCKET) {
logger.warn("You've used kookbc.nobucket option, we won't check if you're going to be out of rate limit!");
logger.warn("您已使用 kookbc.nobucket 选项，我们将不会检查是否会超出速率限制！");
Copy link
Collaborator

@xiaoACE6716 xiaoACE6716 Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"您已使用" 建议改为 "您已启用"

xiaoACE6716
xiaoACE6716 reviewed Nov 28, 2025
View reviewed changes
src/main/java/snw/kookbc/impl/entity/channel/ThreadChannelImpl.java Outdated
* <li>支持 @提及功能</li>
* </ul>
*
* <p>注意: 帖子频道API有每日配额限制(每个开发者账号10000条消息/天,
Copy link
Collaborator

@xiaoACE6716 xiaoACE6716 Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

并非帖子频道单独配额限制，而是每位开发者账号下所有机器人单日消息发送总量上限为 10,000 条，该注释容易误导其他开发者，建议修改

Copy link
Collaborator

@xiaoACE6716 xiaoACE6716 Nov 28, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

顺便在此列出占用配额的接口:
/api/v3/message/create
/api/v3/message/update
/api/v3/direct-message/create
/api/v3/direct-message/update
/api/v3/thread/create
/api/v3/thread/reply

xiaoACE6716
xiaoACE6716 requested changes Nov 28, 2025
View reviewed changes
Copy link
Collaborator

@xiaoACE6716 xiaoACE6716 left a comment •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

挑了点小毛病，另外其实感觉有些地方从英文翻译成中文的时候挺难蚌的，比如那一坨: 从"远程"xxx，但是一时半会不知道改成什么好

@SNWCreations
Copy link
Owner Author

SNWCreations commented Nov 29, 2025

@RealSeek

@SNWCreations
Copy link
Owner Author

SNWCreations commented Nov 29, 2025

另外，README 等文档中引用了旧英文格式日志的部分也应该修改

@RealSeek
docs(readme): update completion message translation in usage example
dc0d603 
- replace English "Done! Type 'help' for help." with Chinese localized message for clarity

docs(channel): remove redundant note about daily quota limit

- delete outdated quota limit note from ThreadChannelImpl documentation

style(clioptions): improve Chinese warning message wording

- replace “已使用” with “已启用” in logger warning for better accuracy
@RealSeek
Merge remote-tracking branch 'origin/dev' into dev
e804390
@SNWCreations
Copy link
Owner Author

SNWCreations commented Dec 14, 2025

正在合并。

@SNWCreations SNWCreations merged commit b10c4d8 into main Dec 14, 2025
1 check passed
@SNWCreations SNWCreations deleted the dev branch December 14, 2025 07:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@huanmeng-qwq huanmeng-qwq huanmeng-qwq approved these changes

@xiaoACE6716 xiaoACE6716 xiaoACE6716 approved these changes

@RealSeek RealSeek Awaiting requested review from RealSeek

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

5 participants

@SNWCreations @huanmeng-qwq @RealSeek @xiaoACE6716