From 97a99cd38167e85f11342684d70935e300875bd7 Mon Sep 17 00:00:00 2001
From: Hong Jiarong <me@jrhim.com>
Date: Thu, 30 Jul 2026 11:16:56 +0800
Subject: [PATCH] fix(hub): raise Docmind OSS upload timeout past httpx 3s
 default

SubmitDocParserJobAdvance uploads PDFs to Aliyun OSS via tea/httpx, which
defaults readTimeout to 3000ms when RuntimeOptions is empty. Multi-MB
teacher PDFs on para silo failed with ReadTimeout(3000) before the job
could start. Set connectTimeout=15s and readTimeout=5m.
---
 hub/scripts/smoke-docmind.ts         |  6 +++++-
 hub/src/capability/docmindClient.ts  | 19 ++++++++++++++++++-
 hub/test/unit/docmind-client.test.ts | 18 +++++++++++++++++-
 3 files changed, 40 insertions(+), 3 deletions(-)

diff --git a/hub/scripts/smoke-docmind.ts b/hub/scripts/smoke-docmind.ts
index 0e61d89..d08af43 100644
--- a/hub/scripts/smoke-docmind.ts
+++ b/hub/scripts/smoke-docmind.ts
@@ -26,7 +26,11 @@ const client = new DocmindClient.default({
 } as never);
 
 const fileStream = createReadStream(pdfPath);
-const runtime = new RuntimeOptions({});
+const runtime = new RuntimeOptions({
+  connectTimeout: 15_000,
+  // httpx defaults to 3000ms; OSS upload of multi-MB PDFs needs far more.
+  readTimeout: 5 * 60_000,
+});
 
 console.log("Submitting job...");
 const submitResp = await client.submitDocParserJobAdvance(
diff --git a/hub/src/capability/docmindClient.ts b/hub/src/capability/docmindClient.ts
index 716febd..92a41af 100644
--- a/hub/src/capability/docmindClient.ts
+++ b/hub/src/capability/docmindClient.ts
@@ -62,6 +62,23 @@ export class DocmindClientError extends Error {
 const COST_PER_PAGE_USD = 0.0056;
 const POLL_INTERVAL_MS = 10_000;
 const POLL_TIMEOUT_MS = 5 * 60_000;
+/**
+ * httpx (tea transport) defaults read/connect timeout to 3000ms when unset.
+ * SubmitDocParserJobAdvance uploads the PDF to OSS; multi-MB files routinely
+ * exceed 3s on the silo host (production: ReadTimeout(3000) on
+ * docmind-api-cn-hangzhou.oss-cn-hangzhou.aliyuncs.com).
+ */
+export const DOCMIND_CONNECT_TIMEOUT_MS = 15_000;
+/** Allow slow / large PDF OSS uploads up to the same bound as job polling. */
+export const DOCMIND_READ_TIMEOUT_MS = POLL_TIMEOUT_MS;
+
+/** RuntimeOptions for Docmind SDK calls that may upload or wait on the wire. */
+export function createDocmindRuntimeOptions(): RuntimeOptions {
+  return new RuntimeOptions({
+    connectTimeout: DOCMIND_CONNECT_TIMEOUT_MS,
+    readTimeout: DOCMIND_READ_TIMEOUT_MS,
+  });
+}
 
 type DocmindConfig = ConstructorParameters<typeof $DocmindClient.default>[0];
 
@@ -90,7 +107,7 @@ export class AliyunDocmindClient implements CapabilityProviderClient {
       outputFormat: ["markdown"],
       formulaEnhancement: true,
     });
-    const runtime = new RuntimeOptions({});
+    const runtime = createDocmindRuntimeOptions();
     let submitResponse;
     try {
       submitResponse = await client.submitDocParserJobAdvance(advanceRequest, runtime);
diff --git a/hub/test/unit/docmind-client.test.ts b/hub/test/unit/docmind-client.test.ts
index ac476a0..1f93b19 100644
--- a/hub/test/unit/docmind-client.test.ts
+++ b/hub/test/unit/docmind-client.test.ts
@@ -1,8 +1,24 @@
 import { join } from "node:path";
 import { tmpdir } from "node:os";
 import { describe, expect, it } from "vitest";
-import { AliyunDocmindClient, DocmindClientError } from "../../src/capability/docmindClient.js";
+import {
+  AliyunDocmindClient,
+  DocmindClientError,
+  DOCMIND_CONNECT_TIMEOUT_MS,
+  DOCMIND_READ_TIMEOUT_MS,
+  createDocmindRuntimeOptions,
+} from "../../src/capability/docmindClient.js";
 
+describe("createDocmindRuntimeOptions", () => {
+  it("overrides httpx's 3s default so PDF OSS uploads can complete", () => {
+    const runtime = createDocmindRuntimeOptions();
+    // Production failure: ReadTimeout(3000) on docmind OSS upload.
+    expect(DOCMIND_CONNECT_TIMEOUT_MS).toBeGreaterThan(3_000);
+    expect(DOCMIND_READ_TIMEOUT_MS).toBeGreaterThan(3_000);
+    expect(runtime.connectTimeout).toBe(DOCMIND_CONNECT_TIMEOUT_MS);
+    expect(runtime.readTimeout).toBe(DOCMIND_READ_TIMEOUT_MS);
+  });
+});
 describe("AliyunDocmindClient local file open", () => {
   it("rejects a missing input file without crashing the process", async () => {
     const client = new AliyunDocmindClient();