Skip to content

feat: implement thread-safe synchronous blocking client wrapper#80

Open
stenalpjolly wants to merge 1 commit into
googleapis:mainfrom
stenalpjolly:stenalpjolly_pr3-sync-client
Open

feat: implement thread-safe synchronous blocking client wrapper#80
stenalpjolly wants to merge 1 commit into
googleapis:mainfrom
stenalpjolly:stenalpjolly_pr3-sync-client

Conversation

@stenalpjolly

Copy link
Copy Markdown
Contributor

Summary

This pull request implements the thread-safe synchronous blocking client wrapper (McpToolboxSyncClient and HttpMcpToolboxSyncClient) for the Java SDK, providing an idiomatic blocking interface over the underlying asynchronous (CompletableFuture-based) McpToolboxClient.

Dependencies:

  • Depends on PR 1 (decoupled checked/unchecked exception hierarchy: McpToolboxException, McpProtocolException, McpTransportException, ToolExecutionException, plus connect/request timeout and custom logger builder options).
  • Depends on PR 2 (buildSync() interface and implementation on McpToolboxClient / McpToolboxClientBuilder, plus transport constructors supporting timeout and logging configurations).

Expectation & Implementation

Expectations

  • Provide an idiomatic, pure synchronous blocking experience without requiring callers to manually call .join() or handle CompletionException / CancellationException.
  • Ensure all checked and concurrent execution exceptions are cleanly unwrapped into the unchecked McpToolboxException hierarchy.
  • Maintain full thread safety across synchronous tool invocations (Tool.executeSync).

Implementation Details

  • McpToolboxSyncClient interface: Defines synchronous counterparts for tool discovery (listTools, loadToolset), tool loading (loadTool), and tool execution (invokeTool).
  • HttpMcpToolboxSyncClient class: Implements McpToolboxSyncClient by delegating to an underlying McpToolboxClient and blocking via .join(). Unwraps CompletionException and CancellationException cleanly into appropriate McpToolboxException instances or IllegalArgumentException.
  • Builder Integration: Added buildSync() to McpToolboxClient.Builder and McpToolboxClientBuilder to construct HttpMcpToolboxSyncClient directly.
  • Tool.executeSync(): Added synchronous execution wrapper directly on Tool instances.
  • Exception Hierarchy: Introduced McpToolboxException (base unchecked exception), McpProtocolException, McpTransportException, and ToolExecutionException (from PR 1 dependency foundation).
  • Transport Configuration: Extended BaseMcpTransport and versioned HTTP transports with connectTimeout, requestTimeout, and custom Logger support (activeLogger).
  • Documentation: Updated README.md to highlight both async-first and sync-first usage patterns.

Test cases

  • McpToolboxSyncClientTest: Verified constructor validation (null delegate checks).
  • McpToolboxSyncClientTest: Verified builder configuration, buildSync(), connect/request timeouts, and custom logger propagation.
  • McpToolboxSyncClientTest: Verified delegation of all synchronous methods (listTools, loadToolset, loadTool, invokeTool).
  • McpToolboxSyncClientTest: Verified comprehensive exception unwrapping (McpToolboxException, IllegalArgumentException, generic Exception, and null cause).
  • McpToolboxSyncClientTest: Verified Tool.executeSync() exception handling and deep-copying support for complex List parameter default values.
  • McpToolboxClientBuilderTest: Verified McpTransportException constructors and status codes.
  • HttpMcpTransportTest: Verified HTTP request timeout configuration during tool invocation.

Acceptance criteria

  • All 140 unit tests pass with BUILD SUCCESS.
  • 100.00% line coverage achieved on HttpMcpToolboxSyncClient.java and McpToolboxSyncClient.java.
  • All code formatted strictly using google-java-format under JDK 22+.
  • Full thread-safe synchronous wrapper implementation cleanly decoupled from async internals.

Breaking changes

  • None. This is an additive feature layer over the existing asynchronous client.

TAG=agy
CONV=c9cedc7f-5a6a-4d32-bf40-6e0ea2d21364

TAG=agy
CONV=c9cedc7f-5a6a-4d32-bf40-6e0ea2d21364
@stenalpjolly
stenalpjolly requested a review from a team as a code owner July 14, 2026 08:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant