From 0ee98e02d5c6ffac5b33c884e49c377ad30cee05 Mon Sep 17 00:00:00 2001 From: Zhoujie628 Date: Fri, 11 Sep 2026 17:18:01 +0800 Subject: [PATCH] feat(integration): align notification timeout and starter artifact Signed-off-by: Zhoujie628 --- CHANGELOG.md | 4 ++ README.md | 10 ++-- docs/en/API_REFERENCE.md | 7 +-- docs/en/DEVELOPER_GUIDE.md | 2 +- docs/en/INTEGRATION_GUIDE.md | 14 ++++-- docs/zh/API_REFERENCE.md | 7 +-- docs/zh/DEVELOPER_GUIDE.md | 2 +- docs/zh/INTEGRATION_GUIDE.md | 14 ++++-- pom.xml | 2 +- samples/pom.xml | 2 +- .../examples/SpringWorkbenchApplication.java | 2 +- .../config/WorkbenchClientProperties.java | 11 +++++ .../SpringWorkbenchExtensionLifecycle.java | 3 +- .../WorkbenchExtensionLifecycle.java | 42 ++++++++++++++++- samples/src/main/resources/application.yml | 1 + .../config/WorkbenchClientPropertiesTest.java | 47 +++++++++++++++++++ spring-boot-starter/pom.xml | 4 +- .../client/WorkflowEngineClientConfig.java | 5 +- .../WorkflowEngineClientConfigTest.java | 15 ++++++ 19 files changed, 162 insertions(+), 32 deletions(-) create mode 100644 samples/src/test/java/dev/openan/workflow/engine/examples/config/WorkbenchClientPropertiesTest.java diff --git a/CHANGELOG.md b/CHANGELOG.md index d9329ca3..207d5fc6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,10 @@ ## [Unreleased] +- Increase the default Notification-T acknowledgement timeout from 5 seconds to 5 minutes and expose the sample Spring + setting as `a2a.notification-ack-timeout-seconds` / + `A2A_NOTIFICATION_ACK_TIMEOUT_SECONDS`. + ## [0.0.5] — 2026-09-09 ### Breaking: per-edge conditional routing diff --git a/README.md b/README.md index dc57111f..dd510ca1 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ subscription remains open until the host-defined terminal event, explicit cancel ### 1. Add Maven dependency -The current engine release is `0.0.2` on [Maven Central](https://repo.maven.apache.org/maven2/net/openan/workflow/sdk/). +The current engine release is `0.0.6` on [Maven Central](https://repo.maven.apache.org/maven2/net/openan/workflow/sdk/). A2A-T SDK `1.1.0` is published to Maven Central. Maven resolves it automatically; no SDK source checkout or local SDK build is required. The engine depends only on @@ -51,7 +51,7 @@ upgrade guidance. net.openan.workflow.sdk workflow-engine - 0.0.2 + 0.0.6 ``` @@ -60,8 +60,8 @@ For Spring Boot server-side integration: ```xml net.openan.workflow.sdk - spring-boot-starter - 0.0.2 + spring-boot-a2a-starter + 0.0.6 ``` @@ -162,7 +162,7 @@ graph TD | Module | Description | |-----------------------|---------------------------------------------------------------| | `workflow-engine` | Core SDK: workflow execution, A2A transport, extensions, auth | -| `spring-boot-starter` | Spring Boot auto-configuration for A2A server side | +| `spring-boot-a2a-starter` | Spring Boot auto-configuration for A2A server side | | `samples` | Demo applications (embedded + Spring Boot variants) | ## License diff --git a/docs/en/API_REFERENCE.md b/docs/en/API_REFERENCE.md index cc9c9003..c9a33aee 100644 --- a/docs/en/API_REFERENCE.md +++ b/docs/en/API_REFERENCE.md @@ -119,7 +119,7 @@ Builder-based configuration for the workflow engine client. | `clientKeyPassword` | `String` | null | Password for an encrypted PKCS#8 private key | | `crlPath` | `String` | null | X.509 CRL for HTTP/JSON-RPC; the default gRPC runtime rejects this unsupported combination | | `sendTimeoutSeconds` | `long` | `600` | SSE stream timeout (10 min default) | -| `notificationAckTimeoutSeconds` | `long` | `5` | Wait for the first Notification-T ACK/event | +| `notificationAckTimeoutSeconds` | `long` | `300` | Wait for the first Notification-T ACK/event (five minutes by default) | | `sendExecutorCoreSize` | `int` | `4` | Send executor core threads | | `sendExecutorMaxSize` | `int` | `16` | Send executor maximum threads | | `sendExecutorQueueCapacity` | `int` | `256` | Bounded send executor queue capacity | @@ -136,6 +136,7 @@ WorkflowEngineClientConfig config = WorkflowEngineClientConfig.builder() .clientCertPath("client-cert.pem") .clientKeyPath("client-key.pem") .sendTimeoutSeconds(900) + .notificationAckTimeoutSeconds(300) .credentialsConfigPath("creds.json") .maxNegotiationExchanges(5) .authProvider(myProvider) @@ -621,9 +622,9 @@ not add private negotiation-state keys to the wire message. --- -## spring-boot-starter Module +## spring-boot-a2a-starter Module -The `spring-boot-starter` module provides Spring Boot auto-configuration for the A2A **server** side (not the +The `spring-boot-a2a-starter` module provides Spring Boot auto-configuration for the A2A **server** side (not the client/workflow side). In a Spring Boot web application, set `a2at.server.enabled=true` to register the A2A SDK server components as Spring beans. diff --git a/docs/en/DEVELOPER_GUIDE.md b/docs/en/DEVELOPER_GUIDE.md index 40f1c09d..18aa32a4 100644 --- a/docs/en/DEVELOPER_GUIDE.md +++ b/docs/en/DEVELOPER_GUIDE.md @@ -11,7 +11,7 @@ Add to your `pom.xml`: net.openan.workflow.sdk workflow-engine - 0.0.2 + 0.0.6 ``` diff --git a/docs/en/INTEGRATION_GUIDE.md b/docs/en/INTEGRATION_GUIDE.md index 4378150a..2a83834b 100644 --- a/docs/en/INTEGRATION_GUIDE.md +++ b/docs/en/INTEGRATION_GUIDE.md @@ -22,7 +22,7 @@ callbacks own A2A-T generation, semantic validation, schemas and any LLM calls. net.openan.workflow.sdk workflow-engine -0.0.2 +0.0.6 ``` @@ -221,7 +221,7 @@ configuration without modifying system properties. Never log plaintext or the ke **Encrypt a password** -Build the jar with `mvn -pl workflow-engine -am -Drevision=0.0.2 package`; commands below run from the repository root. +Build the jar with `mvn -pl workflow-engine -am -Drevision=0.0.6 package`; commands below run from the repository root. `set` is Windows cmd syntax (PowerShell: `$env:A2AT_CRED_KEY='...'`). This CLI needs only the SDK jar and JDK. Use disposable example values here: command-line passwords/keys can appear in shell history and process listings. For production, obtain secrets securely in the host and use the Java encryption API. @@ -229,10 +229,10 @@ For production, obtain secrets securely in the host and use the Java encryption ```bash # Option 1: set env var first set A2AT_CRED_KEY=4f8a2b1c3d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b -java -cp workflow-engine/target/workflow-engine-0.0.2.jar dev.openan.workflow.engine.client.CredentialCrypto "Admin@123" +java -cp workflow-engine/target/workflow-engine-0.0.6.jar dev.openan.workflow.engine.client.CredentialCrypto "Admin@123" # Option 2: pass key as second argument -java -cp workflow-engine/target/workflow-engine-0.0.2.jar dev.openan.workflow.engine.client.CredentialCrypto "Admin@123" 4f8a2b1c3d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b +java -cp workflow-engine/target/workflow-engine-0.0.6.jar dev.openan.workflow.engine.client.CredentialCrypto "Admin@123" 4f8a2b1c3d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b ``` Output: @@ -248,7 +248,7 @@ Paste the output into the `value` field of the credentials JSON. 1. Generate a new key: `openssl rand -hex 32` 2. Update the host secret store / explicit `credentialEncryptionKey`, or its OS/JVM `A2AT_CRED_KEY` 3. Re-encrypt all passwords: - `java -cp workflow-engine/target/workflow-engine-0.0.2.jar dev.openan.workflow.engine.client.CredentialCrypto "plaintext" new-key` + `java -cp workflow-engine/target/workflow-engine-0.0.6.jar dev.openan.workflow.engine.client.CredentialCrypto "plaintext" new-key` 4. Update the `enc:...` results in the credentials JSON file > The `.env` file should not be committed to version control. Add it to `.gitignore`. @@ -411,6 +411,10 @@ transport/runtime/context instances. The listener receives the handle and comple host-defined terminal event. acknowledgement() and completion() separately represent ACK and actual stream exit; neither is a workflow prerequisite. +`WorkflowEngineClientConfig.notificationAckTimeoutSeconds` controls the initial subscription ACK wait and defaults to +300 seconds. The Spring sample exposes it as `a2a.notification-ack-timeout-seconds` and +`A2A_NOTIFICATION_ACK_TIMEOUT_SECONDS`. It does not control SSE idle time after acknowledgement. + ## 8. HTTPS Configuration ```java diff --git a/docs/zh/API_REFERENCE.md b/docs/zh/API_REFERENCE.md index b11d20fc..20ffae34 100644 --- a/docs/zh/API_REFERENCE.md +++ b/docs/zh/API_REFERENCE.md @@ -113,7 +113,7 @@ handle 再开始 I/O，监听器直接收到 handle 和完整 ReceivedMessage。 | `clientKeyPassword` | `String` | null | 加密 PKCS#8 私钥密码 | | `crlPath` | `String` | null | HTTP/JSON-RPC 的 X.509 CRL 路径；默认 gRPC runtime 暂不支持并会拒绝启动 | | `sendTimeoutSeconds` | `long` | `600` | SSE 流超时（默认 10 分钟） | -| `notificationAckTimeoutSeconds` | `long` | `5` | Notification-T 首个 ACK/事件等待时间 | +| `notificationAckTimeoutSeconds` | `long` | `300` | Notification-T 首个 ACK/事件等待时间（默认 5 分钟） | | `sendExecutorCoreSize` | `int` | `4` | 发送线程池核心线程数 | | `sendExecutorMaxSize` | `int` | `16` | 发送线程池最大线程数 | | `sendExecutorQueueCapacity` | `int` | `256` | 发送线程池有界队列容量 | @@ -130,6 +130,7 @@ WorkflowEngineClientConfig config = WorkflowEngineClientConfig.builder() .clientCertPath("client-cert.pem") .clientKeyPath("client-key.pem") .sendTimeoutSeconds(900) + .notificationAckTimeoutSeconds(300) .credentialsConfigPath("creds.json") .maxNegotiationExchanges(5) .authProvider(myProvider) @@ -588,9 +589,9 @@ getReceivedMessages() 是保留层级的响应来源，getOutputs() 为便利投 --- -## spring-boot-starter 模块 +## spring-boot-a2a-starter 模块 -`spring-boot-starter` 模块为 A2A **服务端**（非客户端/工作流侧）提供 Spring Boot 自动配置。在 Spring Boot Web 应用中配置 +`spring-boot-a2a-starter` 模块为 A2A **服务端**（非客户端/工作流侧）提供 Spring Boot 自动配置。在 Spring Boot Web 应用中配置 `a2at.server.enabled=true` 后，才会将 A2A SDK 服务端组件注册为 Spring Bean。 ### A2AProperties diff --git a/docs/zh/DEVELOPER_GUIDE.md b/docs/zh/DEVELOPER_GUIDE.md index be5fbf01..e3834b36 100644 --- a/docs/zh/DEVELOPER_GUIDE.md +++ b/docs/zh/DEVELOPER_GUIDE.md @@ -10,7 +10,7 @@ net.openan.workflow.sdk workflow-engine - 0.0.2 + 0.0.6 ``` diff --git a/docs/zh/INTEGRATION_GUIDE.md b/docs/zh/INTEGRATION_GUIDE.md index dc9e60c8..bb94b6e5 100644 --- a/docs/zh/INTEGRATION_GUIDE.md +++ b/docs/zh/INTEGRATION_GUIDE.md @@ -20,7 +20,7 @@ A2A-T 工作流执行引擎是一个 Java SDK，用于基于 A2A 协议和 A2A-T net.openan.workflow.sdk workflow-engine -0.0.2 +0.0.6 ``` @@ -212,17 +212,17 @@ A2AT_CRED_KEY=4f8a2b1c3d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b **加密密码** -先执行 `mvn -pl workflow-engine -am -Drevision=0.0.2 package`，以下命令在仓库根目录运行，仅需 SDK jar 和 JDK。 +先执行 `mvn -pl workflow-engine -am -Drevision=0.0.6 package`，以下命令在仓库根目录运行，仅需 SDK jar 和 JDK。 `set` 是 Windows cmd 语法，PowerShell 应使用 `$env:A2AT_CRED_KEY='...'`。 以下参数仅用于演示；命令行口令/密钥可能进入终端历史和进程参数。生产应由集成方安全读取密钥并调用 Java 加密 API。 ```bash # 方式一：先设置环境变量 set A2AT_CRED_KEY=4f8a2b1c3d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b -java -cp workflow-engine/target/workflow-engine-0.0.2.jar dev.openan.workflow.engine.client.CredentialCrypto "Admin@123" +java -cp workflow-engine/target/workflow-engine-0.0.6.jar dev.openan.workflow.engine.client.CredentialCrypto "Admin@123" # 方式二：密钥作为第二个参数 -java -cp workflow-engine/target/workflow-engine-0.0.2.jar dev.openan.workflow.engine.client.CredentialCrypto "Admin@123" 4f8a2b1c3d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b +java -cp workflow-engine/target/workflow-engine-0.0.6.jar dev.openan.workflow.engine.client.CredentialCrypto "Admin@123" 4f8a2b1c3d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2b ``` 输出： @@ -237,7 +237,7 @@ enc:uHQcTeKZMVNRM9Ga:o5vm4weRozBXBs04phrLq7j7+/yRVyDsrw== 1. 生成新密钥：`openssl rand -hex 32` 2. 更新集成方密钥存储及显式 `credentialEncryptionKey`，或 OS/JVM 的 `A2AT_CRED_KEY`；引擎不自动加载 `.env` -3. 用新密钥重新加密所有密码：`java -cp workflow-engine/target/workflow-engine-0.0.2.jar dev.openan.workflow.engine.client.CredentialCrypto "明文密码" 新密钥` +3. 用新密钥重新加密所有密码：`java -cp workflow-engine/target/workflow-engine-0.0.6.jar dev.openan.workflow.engine.client.CredentialCrypto "明文密码" 新密钥` 4. 将新的 `enc:...` 结果更新到凭证 JSON 文件 > `.env` 文件不应提交到版本库，建议加入 `.gitignore`。 @@ -390,6 +390,10 @@ NotificationSubscription openNotification(String agentName, MessageContent conte 宿主智能体生成最终 Authorization-T/Notification-T 内容后调用上述接口；使用三类独立 transport/runtime/context。订阅监听器收到 handle 与完整 ReceivedMessage，在宿主定义的终态事件上关闭。handle.acknowledgement() 和 completion() 分别表示 ACK 和真实流退出，两者都不是工作流前提。 +`WorkflowEngineClientConfig.notificationAckTimeoutSeconds` 控制首次订阅 ACK 的等待时间，默认 300 秒；Spring 示例可通过 +`a2a.notification-ack-timeout-seconds` 或环境变量 `A2A_NOTIFICATION_ACK_TIMEOUT_SECONDS` 覆盖。该参数不控制 ACK 后的 SSE +空闲时间。 + ## 8. HTTPS 配置 ```java diff --git a/pom.xml b/pom.xml index 482b49e6..047ee09a 100644 --- a/pom.xml +++ b/pom.xml @@ -1,4 +1,4 @@ - + ../pom.xml - spring-boot-starter + spring-boot-a2a-starter jar - spring-boot-starter + spring-boot-a2a-starter Spring Boot auto-configuration for the A2A-T server side. Integration partners add this dependency and implement AgentExecutor -- all server-side beans (RestHandler, DefaultRequestHandler, event bus) diff --git a/workflow-engine/src/main/java/dev/openan/workflow/engine/client/WorkflowEngineClientConfig.java b/workflow-engine/src/main/java/dev/openan/workflow/engine/client/WorkflowEngineClientConfig.java index 6909b305..4d50da5f 100644 --- a/workflow-engine/src/main/java/dev/openan/workflow/engine/client/WorkflowEngineClientConfig.java +++ b/workflow-engine/src/main/java/dev/openan/workflow/engine/client/WorkflowEngineClientConfig.java @@ -35,6 +35,9 @@ @Getter public class WorkflowEngineClientConfig { + /** Default wait for the first Notification-T acknowledgement: five minutes. */ + public static final long DEFAULT_NOTIFICATION_ACK_TIMEOUT_SECONDS = 300; + private final boolean sslVerify; private final String caCertsPath; private final String clientCertPath; @@ -123,7 +126,7 @@ public static class Builder { private String clientKeyPassword = null; private String crlPath = null; private long sendTimeoutSeconds = 600; - private long notificationAckTimeoutSeconds = 5; + private long notificationAckTimeoutSeconds = DEFAULT_NOTIFICATION_ACK_TIMEOUT_SECONDS; private int sendExecutorCoreSize = 4; private int sendExecutorMaxSize = 16; private int sendExecutorQueueCapacity = 256; diff --git a/workflow-engine/src/test/java/dev/openan/workflow/engine/client/WorkflowEngineClientConfigTest.java b/workflow-engine/src/test/java/dev/openan/workflow/engine/client/WorkflowEngineClientConfigTest.java index c5a22562..7b873b73 100644 --- a/workflow-engine/src/test/java/dev/openan/workflow/engine/client/WorkflowEngineClientConfigTest.java +++ b/workflow-engine/src/test/java/dev/openan/workflow/engine/client/WorkflowEngineClientConfigTest.java @@ -25,6 +25,18 @@ import org.junit.jupiter.api.Test; class WorkflowEngineClientConfigTest { + @Test + void notificationAcknowledgementDefaultsToFiveMinutesAndRemainsConfigurable() { + assertEquals( + 300, WorkflowEngineClientConfig.builder().build().getNotificationAckTimeoutSeconds()); + assertEquals( + 45, + WorkflowEngineClientConfig.builder() + .notificationAckTimeoutSeconds(45) + .build() + .getNotificationAckTimeoutSeconds()); + } + @Test void rejectsInvalidResourceLimits() { assertThrows( @@ -33,6 +45,9 @@ void rejectsInvalidResourceLimits() { assertThrows( IllegalArgumentException.class, () -> WorkflowEngineClientConfig.builder().sendTimeoutSeconds(0).build()); + assertThrows( + IllegalArgumentException.class, + () -> WorkflowEngineClientConfig.builder().notificationAckTimeoutSeconds(0).build()); } @Test