Record Class BombProtection

java.lang.Object
java.lang.Record
cloud.opencode.base.io.compress.BombProtection
Record Components:
maxCompressionRatio - max ratio of decompressed:compressed bytes (default 100) | 最大解压:压缩字节比（默认 100）
maxTotalSize - max total decompressed bytes (default 10 GiB) | 解压总字节上限（默认 10 GiB）
maxEntryCount - max entries in a single archive (default 65535) | 单个归档的最大条目数（默认 65535）
maxNestingDepth - max nested-zip depth detected by .zip suffix (default 3) | 嵌套 ZIP 最大深度，按 .zip 后缀 识别（默认 3）
maxSingleEntrySize - max decompressed bytes for any single entry (default 5 GiB) | 单条目解压字节上限（默认 5 GiB）
public record BombProtection(long maxCompressionRatio, long maxTotalSize, int maxEntryCount, int maxNestingDepth, long maxSingleEntrySize) extends Record
Anti-bomb thresholds for ZIP extract operations. ZIP extract 操作的反炸弹阈值组。

Groups the five caps that ZipUtil.extract(java.nio.file.Path, java.nio.file.Path, ZipOptions) enforces while inflating entries. Bundling them into a single nested record (instead of five flat fields on ZipOptions) lets policy code propagate a complete tuning preset as one unit — Spring property binding, telemetry, and override-style policy composition all become a single object copy.

把 ZipUtil.extract(java.nio.file.Path, java.nio.file.Path, ZipOptions) 在 inflate 时强制的 5 个上限聚合在一个嵌套记录里（而非散落在 ZipOptions 的 5 个扁平字段）， 让策略代码可以以单对象的形式整体传递、覆盖和上报。

Defaults | 默认值: maxCompressionRatio=100, maxTotalSize=10 GiB, maxEntryCount=65535, maxNestingDepth=3, maxSingleEntrySize=5 GiB. Use defaults() for the canonical preset.

Threat model | 威胁模型: the HARD_MAX_* constants are upper bounds for "what the library will technically accept," NOT "what is safe for unknown input." A BombProtection that pegs every field at its hard cap is a fully-legal record (1 TiB total / 10M entries / 1 TiB single entry / 1M:1 ratio) — far beyond what most production deployments should ever permit. Callers receiving a BombProtection from untrusted configuration (Spring property binding, JSON, env vars, REST payload) MUST validate the values against their own threat model before passing the record to ZipUtil or ZipModifier; treat the hard caps as kill-switches, not safe defaults.

HARD_MAX_* 常量是"库技术上能接受"的上限，**不是**"对未知输入安全"的边界。 五个字段全顶到硬上限的 BombProtection 是合法记录（1 TiB 总量 / 10M 条目 / 1 TiB 单条目 / 1M:1 压缩比），远超绝大多数生产环境应允许的范围。从不可信来源（Spring 属性 绑定、JSON、环境变量、REST 负载）接收 BombProtection 时，调用方必须先用自己的 威胁模型校验后再传给 ZipUtil / ZipModifier；把硬上限当熔断器，不要当安全 默认。

Usage Examples | 使用示例:

// Tighter preset for untrusted archives
BombProtection strict = new BombProtection(20, 100L * 1024 * 1024, 1000, 1, 50L * 1024 * 1024);
ZipOptions opts = ZipOptions.builder().bombProtection(strict).build();
Since:
JDK 25, opencode-base-io V1.0.4
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Field Details

    • HARD_MAX_COMPRESSION_RATIO

      public static final long HARD_MAX_COMPRESSION_RATIO
      Hard upper bound for maxCompressionRatio. / 压缩比硬上限。
      See Also:

    • HARD_MAX_TOTAL_SIZE

      public static final long HARD_MAX_TOTAL_SIZE
      Hard upper bound for maxTotalSize (1 TiB). / 解压总字节硬上限（1 TiB）。
      See Also:

    • HARD_MAX_ENTRY_COUNT

      public static final int HARD_MAX_ENTRY_COUNT
      Hard upper bound for maxEntryCount. / 条目数硬上限。
      See Also:

    • HARD_MAX_NESTING_DEPTH

      public static final int HARD_MAX_NESTING_DEPTH
      Hard upper bound for maxNestingDepth. / 嵌套深度硬上限。
      See Also:

    • HARD_MAX_SINGLE_ENTRY_SIZE

      public static final long HARD_MAX_SINGLE_ENTRY_SIZE
      Hard upper bound for maxSingleEntrySize (1 TiB). / 单条目字节硬上限（1 TiB）。
      See Also:

  • Constructor Details

    • BombProtection

      public BombProtection(long maxCompressionRatio, long maxTotalSize, int maxEntryCount, int maxNestingDepth, long maxSingleEntrySize)
      Canonical constructor with hard-bound enforcement on both ends. Non-positive values (including 0) raise IllegalArgumentException rather than silently falling back to defaults — a misconfiguration like maxCompressionRatio: 0 (intent: disable; effect under the old contract: silently apply 100) hides bugs at the edge where they are most expensive to find. Values above the HARD_MAX_* ceiling also throw, so attacker-controlled config (Spring property binding, JSON, env vars) cannot pretend-to- disable bomb protection by passing Long.MAX_VALUE, and legitimate callers above the cap fail loudly at startup rather than silently running at a different threshold than they configured. Use defaults() when you want defaults. 规范构造器：两端硬约束。非正值（含 0）抛 IllegalArgumentException，不再静默 回退默认 —— 类似 maxCompressionRatio: 0（意图禁用，旧契约下静默装成 100）的配置错误 应在边界报响。超过 HARD_MAX_* 上限同样抛出：攻击者通过外部配置（Spring 属性绑定、 JSON、环境变量）传 Long.MAX_VALUE 不能静默放过；合法调用方超上限也会启动期失败， 不会以与配置不符的阈值静默运行。需要默认值时使用 defaults()。
      Throws:
      IllegalArgumentException - when any value is non-positive or exceeds its corresponding HARD_MAX_* ceiling | 任一值非正或超过对应 HARD_MAX_* 上限时抛出

  • Method Details

    • defaults

      public static BombProtection defaults()
      Default thresholds matching the historical ZipOptions defaults. 与历史 ZipOptions 缺省值一致的默认阈值组。
      Returns:
      canonical defaults | 规范默认值

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with the compare method from their corresponding wrapper classes.
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • maxCompressionRatio

      public long maxCompressionRatio()
      Returns the value of the maxCompressionRatio record component.
      Returns:
      the value of the maxCompressionRatio record component

    • maxTotalSize

      public long maxTotalSize()
      Returns the value of the maxTotalSize record component.
      Returns:
      the value of the maxTotalSize record component

    • maxEntryCount

      public int maxEntryCount()
      Returns the value of the maxEntryCount record component.
      Returns:
      the value of the maxEntryCount record component

    • maxNestingDepth

      public int maxNestingDepth()
      Returns the value of the maxNestingDepth record component.
      Returns:
      the value of the maxNestingDepth record component

    • maxSingleEntrySize

      public long maxSingleEntrySize()
      Returns the value of the maxSingleEntrySize record component.
      Returns:
      the value of the maxSingleEntrySize record component