TIKA-4813 - pre-4.0.0 cleanup: clock-agnostic ParseTimeout, nanoTime inte… (#3011)

Author: tballison

docs/modules/ROOT/pages/advanced/integration-testing/tika-eval-regression.adoc

@@ -169,7 +169,8 @@ Flags:
 * `-n` / `--numClients` — forked worker processes (default 4)
 * `-p` / `--pluginsDir` — explicit plugins directory (omit when
   running from the unzipped distribution — auto-discovery handles it)
-* `-T` / `--timeoutMs` — per-parse timeout
+* `-T` / `--timeoutMillis` — total task timeout per file (sets
+  `totalTaskTimeoutMillis`)
 
 Each run forks worker processes and produces one `.json` per input
 file under the output directory.  Run them sequentially or in

docs/modules/ROOT/pages/advanced/local-vlm-server.adoc

@@ -335,14 +335,14 @@ Point the `OpenAIVLMParser` at your local server:
       "openai-vlm-parser": {
         "baseUrl": "http://127.0.0.1:8000",
         "model": "jinaai/jina-vlm",
-        "timeoutSeconds": 600
+        "timeoutMillis": 600000
       }
     }
   ]
 }
 ----
 
-A generous `timeoutSeconds` is recommended — local inference on Apple
+A generous `timeoutMillis` is recommended — local inference on Apple
 Silicon takes 10-60 seconds per page depending on model size and image
 resolution.
 
@@ -434,7 +434,7 @@ Safe to ignore.
 * Jina VLM (2.4B) on M3 Max: ~15-30 seconds per page image
 * Model loading at startup: ~20-30 seconds
 * Keeping the server running avoids reloading the model per request
-* Consider `timeoutSeconds: 600` or higher in the Tika config for large
+* Consider `timeoutMillis: 600000` or higher in the Tika config for large
   or complex images
 
 == Licensing

docs/modules/ROOT/pages/advanced/setting-limits.adoc

@@ -262,8 +262,10 @@ budget, no matter how it is itself configured.
 
 |`progressTimeoutMillis`
 |120000 (2 minutes)
-|Maximum time in milliseconds the task may go silent before it is considered hung and
-killed. Catches infinite loops and hung processes.
+|Maximum time in milliseconds the task may go silent before it is considered hung.
+Catches infinite loops and hung processes. Enforced (the task actually killed) only
+when the parse runs in a forked JVM -- Pipes mode or tika-app `--fork`; in plain
+in-process library use nothing kills the parsing thread.
 
 |`throwOnDeadline`
 |false

docs/modules/ROOT/pages/configuration/parsers/external-parser.adoc

@@ -97,7 +97,7 @@ configured, the raw bytes are written as text.
 |`boolean`
 |Store raw stderr in metadata. Default: `true`.
 
-|`timeoutMs`
+|`timeoutMillis`
 |`long`
 |Process timeout in milliseconds. Default: `60000`.
 

docs/modules/ROOT/pages/configuration/parsers/tess4j-parser.adoc

@@ -181,10 +181,11 @@ libraries. Prepended to `jna.library.path` at initialization time.
 threads that will call the parser concurrently. Each instance consumes
 native memory.
 
-|`timeoutSeconds`
-|`120`
-|Maximum time (seconds) to wait for a pooled `Tesseract` instance before
-throwing an exception.
+|`timeoutMillis`
+|`120000`
+|Timeout (milliseconds) applied both to waiting for a pooled `Tesseract`
+instance and to each image's OCR call. Each is budgeted separately up to this
+value, clipped to whatever remains of the task's total budget.
 
 |`dpi`
 |`300`

docs/modules/ROOT/pages/configuration/parsers/vlm-parsers.adoc

@@ -183,9 +183,9 @@ All three parsers share the same configuration POJO (`VLMOCRConfig`):
 |`4096`
 |Maximum tokens the model may generate.
 
-|`timeoutSeconds`
-|`300`
-|HTTP read timeout in seconds.
+|`timeoutMillis`
+|`120000`
+|HTTP read timeout in milliseconds.
 
 |`apiKey`
 |`""` (empty)

docs/modules/ROOT/pages/migration-to-4x/migrating-tika-server-4x.adoc

@@ -174,7 +174,11 @@ The following `TikaServerConfig` options have been removed:
 
 * `taskTimeoutMillis` - Was the total time allowed per task before the forked process was
   killed; that is now `parse-context.timeout-limits.totalTaskTimeoutMillis` (same
-  meaning, new home). 4.x also adds a second, independent axis with no pre-4.0
+  meaning, new home). **The default changed**: 3.x `taskTimeoutMillis` defaulted to
+  `300000` (5 minutes), while `totalTaskTimeoutMillis` defaults to `3600000` (1 hour) --
+  an upgrader who never set the 3.x value gets a much larger worst-case per-document
+  bound. Set `totalTaskTimeoutMillis: 300000` to keep the 3.x behavior. 4.x also adds a
+  second, independent axis with no pre-4.0
   equivalent -- `progressTimeoutMillis`, a stall detector that kills the task only after
   a period of genuine silence, not merely after `totalTaskTimeoutMillis` of wall-clock
   time -- worth setting deliberately rather than leaving at its default. See

docs/modules/ROOT/pages/migration-to-4x/migrating-to-4x.adoc

@@ -241,6 +241,17 @@ External parsers must now be explicitly configured via JSON. See
 xref:configuration/parsers/external-parser.adoc[External Parser Configuration]
 for details.
 
+== Timeout Model Changes
+
+4.x replaces the previous ad hoc, per-parser timeout handling with a single unified model
+(`TimeoutLimits` / `ParseTimeout`) shared across library use, `tika-app --fork`, and Tika
+Pipes. This affects error handling (`TikaTimeoutException` is now a checked exception),
+CLI flags (`tika-app --fork-timeout` was removed), and several parser/pipes config field
+names (`*TimeoutSeconds`/`*TimeoutMs` -> `*TimeoutMillis`, including a unit change for
+Tess4J specifically). See
+xref:pipes/timeouts.adoc#_upgrading_from_tika_3_x[Timeouts: Upgrading from Tika 3.x] for
+the full list of behavioral changes and required config edits.
+
 == Deprecations and Removals
 
 * `TikaConfig` -- replaced by `TikaLoader`

docs/modules/ROOT/pages/pipes/configuration.adoc

@@ -25,7 +25,7 @@ how many forked JVMs to run, timeouts, memory management, and parse behavior.
 {
   "pipes": {
     "numClients": 4,
-    "socketTimeoutMs": 60000,
+    "socketTimeoutMillis": 60000,
     "maxFilesProcessedPerProcess": 10000,
     "parseMode": "RMETA",
     "onParseException": "EMIT",
@@ -69,13 +69,17 @@ See also xref:pipes/timeouts.adoc[Timeouts] for the full timeout model.
 |===
 |Field |Default |Description
 
-|`socketTimeoutMs`
+|`socketTimeoutMillis`
 |`60000`
 |Maximum time (ms) to wait for data from a forked process. If no heartbeat or result is received within this window, the parse is considered hung.
 
-|`heartbeatIntervalMs`
+|`heartbeatIntervalMillis`
 |`1000`
-|Interval (ms) between heartbeats sent from the forked process. Must be significantly less than `socketTimeoutMs`.
+|Interval (ms) between heartbeats sent from the forked process. Must be significantly less than `socketTimeoutMillis`.
+
+|`maxTotalTaskTimeoutMillis`
+|`3600000`
+|Ceiling for *request-supplied* timeout limits: a per-request `timeout-limits` override may lower its timeouts freely but can never raise `totalTaskTimeoutMillis` or `progressTimeoutMillis` above this value (values over the cap are clamped with a warning). Limits set in the server's own `parse-context` are trusted and not subject to this cap.
 
 |`shutdownClientAfterMillis`
 |`300000`

docs/modules/ROOT/pages/pipes/getting-started.adoc

@@ -113,9 +113,10 @@ The `pipes` section controls the pipeline behavior:
 |`RMETA`
 |Output mode: `RMETA` (full recursive metadata), `CONCATENATE`, `CONTENT_ONLY`, `UNPACK`
 
-|`socketTimeoutMs`
+|`socketTimeoutMillis`
 |`60000`
-|Maximum time (ms) for a single parse operation
+|Maximum time (ms) to wait for data (heartbeat or result) from a forked process
+before it is considered hung -- a transport/liveness bound, not a per-parse limit
 
 |`maxFilesProcessedPerProcess`
 |`10000`