feat(extract): sync round4-part2 and round5 improvements from 3.0.x

Author: loong10k

easypdf-xhtml/src/main/java/io/github/easy4j/pdf/xhtml/convert/EasyPdf.java

@@ -37,7 +37,7 @@ public static void markdownToPdf(String markdown, OutputStream out) throws IOExc
 
     /** PDF 文件 → Markdown 文本（尽力而为：文本提取 + 段落整理，结构还原以可读性为准）。 */
     public static String pdfToMarkdown(File pdf) throws IOException {
-        Objects.requireNonNull(pdf, "pdf must not be null");
+        pdf = requireFile(pdf);
         return MarkdownConverter.textToMarkdown(HtmlPdfConverter.pdfToText(pdf));
     }
 
@@ -55,13 +55,13 @@ public static String pdfToMarkdown(InputStream in) throws IOException {
 
     /** PDF 文件 → 结构化 Markdown（标题/列表/表格，document 顶层；Task 2-3 新增）。 */
     public static String pdfToStructuredMarkdown(File pdf) throws IOException {
-        Objects.requireNonNull(pdf, "pdf must not be null");
+        pdf = requireFile(pdf);
         return PdfToMarkdownConverter.pdfToFullMarkdown(pdf);
     }
 
     /** PDF 文件 → 结构化 Document（智能体按需取章节/表格，Task 2-3 新增）。 */
     public static DocumentStructure pdfToStructured(File pdf) throws IOException {
-        Objects.requireNonNull(pdf, "pdf must not be null");
+        pdf = requireFile(pdf);
         return PdfToMarkdownConverter.pdfToStructured(pdf);
     }
 
@@ -99,7 +99,7 @@ public static void markdownToPdfTagged(String markdown, OutputStream out) throws
      * 智能体先看目录树决定要取哪些章节，避免整篇驻留。
      */
     public static DocumentSummary summary(File pdf) throws IOException {
-        Objects.requireNonNull(pdf, "pdf must not be null");
+        pdf = requireFile(pdf);
         return DocumentSummaryBuilder.build(pdf, PdfExtractionProperties.defaults());
     }
 
@@ -121,7 +121,16 @@ public static DocumentSummary summary(InputStream in, String filename) throws IO
      * 按页流式提取并只拼接区间内各页的 partial 结果。
      */
     public static String pageRange(File pdf, int fromPage, int toPage) throws IOException {
-        Objects.requireNonNull(pdf, "pdf must not be null");
+        pdf = requireFile(pdf);
+        if (fromPage > toPage) {
+            throw new IllegalArgumentException("fromPage(" + fromPage + ") > toPage(" + toPage + ")");
+        }
+        if (fromPage <= 0) {
+            throw new IllegalArgumentException("fromPage must be >= 1, was " + fromPage);
+        }
+        if (toPage <= 0) {
+            throw new IllegalArgumentException("toPage must be >= 1, was " + toPage);
+        }
         final StringBuilder md = new StringBuilder();
         PdfStructureExtractor.extractPerPage(pdf, PdfExtractionProperties.defaults(),
                 new PdfStructureExtractor.PageConsumer() {
@@ -142,7 +151,34 @@ public boolean page(int pageNo, DocumentStructure partial) {
 
     /** PDF 文件 → RAG / Embedding 友好的切片流（配置见 {@link ChunkOptions}）。 */
     public static List<DocumentChunk> chunked(File pdf, ChunkOptions opts) throws IOException {
-        Objects.requireNonNull(pdf, "pdf must not be null");
+        pdf = requireFile(pdf);
         return DocumentChunker.chunk(PdfStructureExtractor.extract(pdf), opts);
     }
+
+    // ---------------- Round5-Security Task 3: 入口文件护栏 + 日志转义 ----------------
+
+    /**
+     * 所有接受 PDF 文件的公开入口统一护栏：null 拒绝（NPE，与历史一致）+
+     * 文件存在性校验（缺失时按 {@link ExtractionException.Code#NOT_FOUND} 分级抛出，
+     * 文案头部保持历史 "PDF not found:"——{@link ExtractionException} 为 IOException 子类，调用方兼容）。
+     */
+    private static File requireFile(File pdf) throws IOException {
+        Objects.requireNonNull(pdf, "pdf must not be null");
+        if (!pdf.isFile()) {
+            throw new ExtractionException(ExtractionException.Code.NOT_FOUND,
+                "PDF not found: " + escapeForLog(pdf.getName()));
+        }
+        return pdf;
+    }
+
+    /**
+     * 日志/异常消息安全转义：反斜杠先转义（保证转义序列不可被二次解释），
+     * 再把换行/回车/制表符转为可见转义序列，防伪造日志行注入。
+     */
+    static String escapeForLog(String s) {
+        return s.replace("\\", "\\\\")
+                .replace("\n", "\\n")
+                .replace("\r", "\\r")
+                .replace("\t", "\\t");
+    }
 }

easypdf-xhtml/src/main/java/io/github/easy4j/pdf/xhtml/convert/ExtractorMetrics.java

@@ -0,0 +1,115 @@
+package io.github.easy4j.pdf.xhtml.convert;
+
+import java.util.Collections;
+import java.util.LinkedHashMap;
+import java.util.Map;
+import java.util.Objects;
+import java.util.concurrent.ConcurrentHashMap;
+import java.util.concurrent.atomic.AtomicLong;
+
+/**
+ * PDF 提取的进程内计数器（无需 JMX / Spring Boot Actuator，直接 {@link #snapshot()} 读数即可）。
+ *
+ * <p>埋点口径：每次结构化提取计一次（成功与失败都计入 {@code total}）——
+ * 由 {@link PdfStructureExtractor#extract(File, io.github.easy4j.pdf.xhtml.convert.layout.PdfExtractionProperties)
+ * extract} 单一收口，
+ * 报告式入口 {@code extractWithReport} 内部委托同一方法，因此不会重复计数；
+ * 纯字符串操作（如 {@code MarkdownConverter.mdToHtml}）不计。
+ *
+ * <p>线程安全：多字段更新在 synchronized 块内完成，{@link #snapshot()} 读取一致视图；
+ * 返回的 Map 为独立不可变副本，后续计数不影响已取出的快照。
+ *
+ * <p>用法：诊断/巡检接口直接读 {@link #INSTANCE}；单测可用 {@code new ExtractorMetrics()}
+ * 构造独立实例避免进程级状态串扰。
+ */
+public final class ExtractorMetrics {
+
+    /** 进程级共享实例：常规调用方经此读数。 */
+    public static final ExtractorMetrics INSTANCE = new ExtractorMetrics();
+
+    /** 总提取次数（成功 + 失败）。 */
+    private final AtomicLong totalExtracts = new AtomicLong();
+
+    /** 成功次数。 */
+    private final AtomicLong totalSuccesses = new AtomicLong();
+
+    /** 失败总次数（按分级码细分见 {@link #failureByCode}）。 */
+    private final AtomicLong totalFailures = new AtomicLong();
+
+    /** 累计耗时（毫秒，含失败尝试；时间源 System.currentTimeMillis()）。 */
+    private final AtomicLong totalDurationMs = new AtomicLong();
+
+    /** 按失败分级码的累计次数。 */
+    private final ConcurrentHashMap<ExtractionException.Code, AtomicLong> failureByCode =
+            new ConcurrentHashMap<ExtractionException.Code, AtomicLong>();
+
+    /** 记一次成功提取及其耗时（负值按 0 计）。 */
+    public void recordSuccess(long durationMs) {
+        synchronized (this) {
+            totalExtracts.incrementAndGet();
+            totalSuccesses.incrementAndGet();
+            addDuration(durationMs);
+        }
+    }
+
+    /**
+     * 记一次失败提取：分级码取自 {@link ExtractionException#getCode()}；
+     * 未分级的异常由埋点侧归入 {@link ExtractionException.Code#CORRUPT} 后传入。
+     */
+    public void recordFailure(ExtractionException.Code code, long durationMs) {
+        Objects.requireNonNull(code, "code must not be null");
+        synchronized (this) {
+            totalExtracts.incrementAndGet();
+            totalFailures.incrementAndGet();
+            addDuration(durationMs);
+            counterFor(code).incrementAndGet();
+        }
+    }
+
+    /**
+     * 只读诊断快照（不可变、与内部状态隔离）。key 契约：
+     * {@code total}（成功+失败总数）、{@code successes}、{@code durationMs}
+     * 与每个分级码固定存在的 {@code failures.CORRUPT / failures.ENCRYPTED /
+     * failures.LIMIT_EXCEEDED / failures.NOT_FOUND}（未发生为 0；
+     * 无顶层 "failures" 聚合 key，避免与逐码 key 混淆）。
+     */
+    public Map<String, Long> snapshot() {
+        synchronized (this) {
+            Map<String, Long> snap = new LinkedHashMap<String, Long>();
+            snap.put("total", Long.valueOf(totalExtracts.get()));
+            snap.put("successes", Long.valueOf(totalSuccesses.get()));
+            snap.put("durationMs", Long.valueOf(totalDurationMs.get()));
+            for (ExtractionException.Code code : ExtractionException.Code.values()) {
+                AtomicLong c = failureByCode.get(code);
+                snap.put("failures." + code.name(), Long.valueOf(c == null ? 0L : c.get()));
+            }
+            return Collections.unmodifiableMap(snap);
+        }
+    }
+
+    /** 清零全部计数（仅测试/巡检复位用；不影响进行中的提取）。 */
+    public void reset() {
+        synchronized (this) {
+            totalExtracts.set(0);
+            totalSuccesses.set(0);
+            totalFailures.set(0);
+            totalDurationMs.set(0);
+            failureByCode.clear();
+        }
+    }
+
+    private void addDuration(long durationMs) {
+        if (durationMs > 0) {
+            totalDurationMs.addAndGet(durationMs);
+        }
+    }
+
+    private AtomicLong counterFor(ExtractionException.Code code) {
+        return failureByCode.computeIfAbsent(code, new java.util.function.Function<ExtractionException.Code, AtomicLong>() {
+            @Override
+            public AtomicLong apply(ExtractionException.Code k) {
+                return new AtomicLong();
+            }
+        });
+    }
+}

easypdf-xhtml/src/main/java/io/github/easy4j/pdf/xhtml/convert/PdfStructureExtractor.java

@@ -10,8 +10,10 @@
 import java.util.Objects;
 
 import com.itextpdf.kernel.PdfException;
+import com.itextpdf.kernel.pdf.PdfCatalog;
 import com.itextpdf.kernel.pdf.PdfDictionary;
 import com.itextpdf.kernel.pdf.PdfDocument;
+import com.itextpdf.kernel.pdf.PdfName;
 import com.itextpdf.kernel.pdf.PdfReader;
 import com.itextpdf.kernel.pdf.canvas.parser.PdfTextExtractor;
 import com.itextpdf.kernel.pdf.tagging.IStructureNode;
@@ -22,7 +24,7 @@
 
 import io.github.easy4j.pdf.xhtml.convert.layout.ExtractCache;
 import io.github.easy4j.pdf.xhtml.convert.layout.PageModel;
-import io.github.easy4j.pdf.xhtml.convert.layout.PageModelListener;
+import io.github.easy4j.pdf.xhtml.convert.layout.PageModelCollector;
 import io.github.easy4j.pdf.xhtml.convert.layout.PdfExtractionProperties;
 import io.github.easy4j.pdf.xhtml.convert.layout.RestLayoutAnalyzer;
 import io.github.easy4j.pdf.xhtml.convert.layout.RuleLayoutAnalyzer;
@@ -33,15 +35,42 @@
  */
 public final class PdfStructureExtractor {
 
+    /** 结构化日志：入口 debug / 结果 INFO / warnings 与失败 WARN。 */
+    private static final org.slf4j.Logger LOG =
+            org.slf4j.LoggerFactory.getLogger(PdfStructureExtractor.class);
+
     private PdfStructureExtractor() {
     }
 
     public static DocumentStructure extract(File pdf) throws IOException {
         return extract(pdf, PdfExtractionProperties.defaults());
     }
 
+    /**
+     * 结构化提取（带进程级计数）：成功与失败各计一次进 {@link ExtractorMetrics#INSTANCE}。
+     * 本方法是全部提取路径的单一收口（报告式 {@link #extractWithReport} 也委托至此），
+     * 因此不会重复计数；耗时用 System.currentTimeMillis() 测量。未分级的
+     * IOException / 运行时异常按 CORRUPT 归类，与报告式入口的兜底口径一致。
+     */
     public static DocumentStructure extract(File pdf, PdfExtractionProperties props) throws IOException {
         Objects.requireNonNull(pdf, "pdf must not be null");
+        long start = System.currentTimeMillis();
+        try {
+            DocumentStructure doc = doExtract(pdf, props);
+            ExtractorMetrics.INSTANCE.recordSuccess(System.currentTimeMillis() - start);
+            return doc;
+        } catch (IOException | RuntimeException e) {
+            ExtractionException.Code code = e instanceof ExtractionException
+                    ? ((ExtractionException) e).getCode()
+                    : ExtractionException.Code.CORRUPT;
+            ExtractorMetrics.INSTANCE.recordFailure(code, System.currentTimeMillis() - start);
+            throw e;
+        }
+    }
+
+    /** 提取主体：原 extract(File, props) 逻辑，不含计数。 */
+    private static DocumentStructure doExtract(File pdf, PdfExtractionProperties props) throws IOException {
+        LOG.debug("extract requested file={}", pdf.getName());
         if (!pdf.isFile()) {
             // NOT_FOUND 分级包装；文案与历史行为一致（仍为 IOException 子类）
             throw new ExtractionException(ExtractionException.Code.NOT_FOUND,
@@ -138,6 +167,17 @@ public static ExtractReport extractWithReport(File pdf, PdfExtractionProperties
                         "PDF extraction failed (" + t.getClass().getSimpleName() + "): " + t.getMessage(), t);
         }
         r.durationMillis = System.currentTimeMillis() - start;
+        if (r.success) {
+            // file 只取 basename，避免日志泄漏路径 PII
+            LOG.info("extract file={} pages={} chars={} tables={} images={} durationMs={}",
+                    pdf.getName(), r.pages, r.chars, r.tables, r.images, r.durationMillis);
+            if (!r.warnings.isEmpty()) {
+                LOG.warn("extract warnings file={} warnings={}", pdf.getName(), r.warnings);
+            }
+        } else {
+            LOG.warn("extract failed file={} code={} msg={}",
+                    pdf.getName(), r.error.getCode(), r.error.getMessage());
+        }
         return r;
     }
 
@@ -335,9 +375,10 @@ private static final class ParsedDoc implements AutoCloseable {
         ParsedDoc(File pdf) throws IOException {
             this.source = pdf;
             this.pdfDoc = new PdfDocument(new PdfReader(pdf));
+            stripEmbeddedJavaScript(this.pdfDoc);
             String metaTitle = pdfDoc.getDocumentInfo() != null ? pdfDoc.getDocumentInfo().getTitle() : null;
             this.title = (metaTitle == null || metaTitle.isEmpty()) ? pdf.getName() : metaTitle;
-            this.models = PageModelListener.collect(pdfDoc);
+            this.models = PageModelCollector.collect(pdfDoc);
             PdfStructTreeRoot root = pdfDoc.getStructTreeRoot();
             boolean t = false;
             if (root != null && root.getKids() != null) {
@@ -352,6 +393,29 @@ private static final class ParsedDoc implements AutoCloseable {
         public void close() throws IOException {
             pdfDoc.close();
         }
+
+        /**
+         * 纵深防御：打开后立即剥离 catalog 顶层的脚本向量（/JS、/JavaScript 与
+         * JavaScript 型 OpenAction）。iText 内核解析从不执行嵌入 JS（库内无解释器，
+         * 也无 setIgnoreJavaScript 开关——7.x/8.x API 均不存在），此剥离保证本
+         * 上下文以及任何下游复用（序列化/再转换）都不会把脚本带出去。
+         * 全部 reader 构造经由 ParsedDoc，extract 与 extractPerPage 两路径均被覆盖；
+         * 缓存命中分支不打开文件、无 reader，无需处理。
+         */
+        private static void stripEmbeddedJavaScript(PdfDocument doc) {
+            PdfCatalog cat = doc.getCatalog();
+            if (cat == null || cat.getPdfObject() == null) {
+                return;
+            }
+            // PdfCatalog 是 PdfObjectWrapper 包装而非字典本身：经 getPdfObject 操作条目
+            PdfDictionary root = cat.getPdfObject();
+            root.remove(PdfName.JS);
+            root.remove(PdfName.JavaScript);
+            PdfDictionary oa = root.getAsDictionary(PdfName.OpenAction);
+            if (oa != null && PdfName.JavaScript.equals(oa.get(PdfName.S))) {
+                root.remove(PdfName.OpenAction); // 仅摘除 JS 型动作，保留普通页面定位
+            }
+        }
     }
 
     /** 整篇语义提取：与历史行为一致——Tagged 全树优先，REST 服务次之，规则引擎兜底。 */