sync: cherry-pick changes from feature/3.0.x

Author: loong10k

src/main/java/io/github/easy4j/opencode/HttpCallCancellation.java

@@ -0,0 +1,33 @@
+package io.github.easy4j.opencode;
+
+/**
+ * Binds a business-layer cancellation signal to a single OpenCode HTTP call.
+ *
+ * <p>Implementations allow callers to register a cancellation callback that will be invoked
+ * when the underlying HTTP call should be aborted. The {@link #onCancel(Runnable)} method
+ * returns an {@link AutoCloseable} that, when closed, unregisters the callback.</p>
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see io.github.easy4j.opencode.api.OpenCodeHttpClient
+ */
+@FunctionalInterface
+public interface HttpCallCancellation {
+
+    /**
+     * Registers a cancellation callback and returns a handle to unregister it.
+     *
+     * @param callback the runnable to invoke when cancellation is requested
+     * @return an {@link AutoCloseable} that unregisters the callback when closed
+     */
+    AutoCloseable onCancel(Runnable callback);
+
+    /**
+     * Returns whether this cancellation has been triggered.
+     *
+     * @return {@code true} if cancellation has been requested, {@code false} otherwise
+     */
+    default boolean isCancelled() {
+        return false;
+    }
+}

src/main/java/io/github/easy4j/opencode/HttpResponseMode.java

@@ -0,0 +1,16 @@
+package io.github.easy4j.opencode;
+
+/**
+ * HTTP 对话响应模式。
+ */
+public enum HttpResponseMode {
+
+    /** 等待完整响应后一次性返回。 */
+    BLOCKING,
+
+    /** 消费 Provider SSE 并逐段回调。 */
+    STREAM,
+
+    /** 由调用方根据结构化输出等请求特征选择。 */
+    AUTO
+}

src/main/java/io/github/easy4j/opencode/OpenCodeCliConfig.java

@@ -3,10 +3,16 @@
 import lombok.Data;
 
 /**
- * OpenCode 本地 CLI 客户端配置。
- * <p>
- * 涵盖本地 {@code opencode} 可执行文件路径、超时、工作目录等 CLI 运行时设置。
- * </p>
+ * Configuration for the local OpenCode CLI subsystem.
+ *
+ * <p>Covers local {@code opencode} executable path, timeouts, working directory,
+ * and other CLI runtime settings. Can be mapped from Spring
+ * {@code @ConfigurationProperties}.</p>
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see OpenCodeClient
+ * @see OpenCodeClientConfig
  */
 @Data
 public class OpenCodeCliConfig {

src/main/java/io/github/easy4j/opencode/OpenCodeClient.java

@@ -3,11 +3,17 @@
 import lombok.Data;
 
 /**
- * OpenCode 客户端统一配置（纯 POJO，可与 Spring {@code @ConfigurationProperties} 映射）。
- * <p>
- * 组合 {@link OpenCodeHttpClientConfig}（HTTP/Server 相关）与 {@link OpenCodeCliConfig}（本地 CLI 相关），
- * 作为 {@link OpenCodeClient} 等统一入口的配置载体。
- * </p>
+ * Unified configuration POJO for the OpenCode client.
+ *
+ * <p>Composes {@link OpenCodeHttpClientConfig} (HTTP/Server settings) and
+ * {@link OpenCodeCliConfig} (local CLI settings). Compatible with Spring
+ * {@code @ConfigurationProperties} binding.</p>
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see OpenCodeHttpClientConfig
+ * @see OpenCodeCliConfig
+ * @see OpenCodeClient
  */
 @Data
 public class OpenCodeClientConfig {

src/main/java/io/github/easy4j/opencode/OpenCodeClientConfig.java

@@ -3,14 +3,22 @@
 import lombok.Data;
 
 /**
- * OpenCode HTTP Server 客户端配置。
- * <p>
- * 涵盖 Server 根地址、Basic Auth、TLS、HTTP 超时及默认模型等网络相关设置。
- * </p>
+ * Configuration for the OpenCode HTTP Server client.
+ *
+ * <p>Covers server base URL, Basic Auth, TLS, HTTP timeouts, connection pool sizing,
+ * streaming thread pool, and default model/agent settings.</p>
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see OpenCodeHttpClient
+ * @see OpenCodeOkHttpClientFactory
  */
 @Data
 public class OpenCodeHttpClientConfig {
 
+    /** 对话响应模式，默认保持兼容的完整响应模式。 */
+    private HttpResponseMode mode = HttpResponseMode.BLOCKING;
+
     /**
      * 是否启用 HTTP 子系统。
      * <p>为 false 时跳过 HTTP 客户端初始化和检查。</p>
@@ -31,7 +39,7 @@ public class OpenCodeHttpClientConfig {
     /**
      * OpenCode Server 根地址，例如 {@code http://localhost:4096}。
      */
-    private String serverUrl = "http://localhost:4096";
+    private String baseUrl = "http://localhost:4096";
 
     /**
      * HTTP Basic Auth 用户名（对应 {@code OPENCODE_SERVER_USERNAME}，默认 {@code opencode}）。
@@ -55,6 +63,56 @@ public class OpenCodeHttpClientConfig {
      */
     private int readTimeoutMillis = 300_000;
 
+    /**
+     * 写入超时（毫秒）。
+     */
+    private int writeTimeoutMillis = 120_000;
+
+    /**
+     * 整个调用超时（毫秒）；0 表示不额外限制。
+     */
+    private int callTimeoutMillis;
+
+    /**
+     * 连接池最大空闲连接数。
+     */
+    private int maxIdleConnections = 32;
+
+    /**
+     * 空闲连接保活时间（毫秒）。
+     */
+    private long keepAliveDurationMillis = 300_000L;
+
+    /**
+     * 异步请求最大并发数。
+     */
+    private int maxRequests = 128;
+
+    /**
+     * 单主机异步请求最大并发数。
+     */
+    private int maxRequestsPerHost = 128;
+
+    /** 流式事件处理线程数。 */
+    private int streamCorePoolSize = 32;
+
+    /** 流式事件处理最大线程数。 */
+    private int streamMaxPoolSize = 32;
+
+    /** 流式事件处理有界队列容量。 */
+    private int streamQueueCapacity = 128;
+
+    /** 流式事件处理线程空闲保活时间（毫秒）。 */
+    private long streamKeepAliveMillis = 60_000L;
+
+    /** 单个流式订阅的事件缓存上限。 */
+    private int streamEventQueueCapacity = 1_024;
+
+    /**
+     * 遇到失效连接等传输故障时是否允许 OkHttp 自动恢复。
+     */
+    private boolean retryOnConnectionFailure = true;
+
     /**
      * 是否校验 HTTPS 证书；为 false 时关闭校验（仅建议开发环境）。
      */

src/main/java/io/github/easy4j/opencode/OpenCodeHttpClientConfig.java

@@ -0,0 +1,67 @@
+package io.github.easy4j.opencode;
+
+import okhttp3.ConnectionPool;
+import okhttp3.Dispatcher;
+import okhttp3.OkHttpClient;
+
+import java.util.Objects;
+import java.util.concurrent.TimeUnit;
+
+/**
+ * Factory for creating {@link OkHttpClient} instances used by the OpenCode SDK in standalone mode.
+ *
+ * <p>When a Spring container already provides an external {@link OkHttpClient}, the injection
+ * constructors should be used instead and this factory will not participate.</p>
+ *
+ * @author [@Loong Wan](https://github.com/loong10k)
+ * @since 3.0.0
+ * @see OpenCodeHttpClientConfig
+ */
+public final class OpenCodeOkHttpClientFactory {
+
+    private OpenCodeOkHttpClientFactory() {
+    }
+
+    /**
+     * 根据 OpenCode HTTP 配置创建客户端。
+     *
+     * @param config HTTP 配置
+     * @return SDK 自主管理的 OkHttpClient
+     */
+    public static OkHttpClient create(OpenCodeHttpClientConfig config) {
+        Objects.requireNonNull(config, "config");
+        Dispatcher dispatcher = new Dispatcher();
+        dispatcher.setMaxRequests(Math.max(1, config.getMaxRequests()));
+        dispatcher.setMaxRequestsPerHost(Math.max(1, config.getMaxRequestsPerHost()));
+        ConnectionPool connectionPool = new ConnectionPool(
+                Math.max(1, config.getMaxIdleConnections()),
+                Math.max(1L, config.getKeepAliveDurationMillis()),
+                TimeUnit.MILLISECONDS);
+        OkHttpClient.Builder builder = new OkHttpClient.Builder()
+                .dispatcher(dispatcher)
+                .connectionPool(connectionPool)
+                .connectTimeout(Math.max(1, config.getConnectTimeoutMillis()), TimeUnit.MILLISECONDS)
+                .readTimeout(Math.max(0, config.getReadTimeoutMillis()), TimeUnit.MILLISECONDS)
+                .writeTimeout(Math.max(1, config.getWriteTimeoutMillis()), TimeUnit.MILLISECONDS)
+                .callTimeout(Math.max(0, config.getCallTimeoutMillis()), TimeUnit.MILLISECONDS)
+                .retryOnConnectionFailure(config.isRetryOnConnectionFailure());
+        if (!config.isVerifySsl()) {
+            builder.hostnameVerifier((hostname, session) -> true);
+        }
+        return builder.build();
+    }
+
+    /**
+     * 释放 SDK 自建客户端资源。
+     *
+     * @param client SDK 自建客户端
+     */
+    public static void shutdown(OkHttpClient client) {
+        if (Objects.isNull(client)) {
+            return;
+        }
+        client.dispatcher().cancelAll();
+        client.connectionPool().evictAll();
+        client.dispatcher().executorService().shutdown();
+    }
+}