Class InputSanitizer

java.lang.Object
cloud.opencode.base.flow.internal.InputSanitizer
public final class InputSanitizer extends Object
Package-private utility that sanitises and validates user-supplied text fields (comment / reason / userId) before the engine persists them, per design v4 §7.3. 包私有工具：在引擎写库前清洗与校验用户提交的文本字段（comment / reason / userId），对应设计 v4 §7.3。

Rules:

  • comment: strip 0x00 — 0x1F and 0x7F control characters (preserving \n); collapse \r\n and lone \r to \n; max length 2000.
  • reason: same character rules; max length 500.
  • userId: max length 64; must match ^[A-Za-z0-9_\-]+$.

Length / character violations throw IllegalActionException with FlowErrorCode.INPUT_INVALID_TEXT (BASE-FLOW-INPUT-001). sanitizeComment(String) / sanitizeReason(String) accept null and return null; validateUserId(String) rejects null.

This sanitiser intentionally does not escape HTML/JS — that is the rendering layer's responsibility.

本清洗器有意不做 HTML/JS 转义，那是渲染层的职责。

Since:
JDK 25, opencode-base-flow V1.0.5
Author:
Leon Soo

  • Field Details

    • MAX_COMMENT_LEN

      public static final int MAX_COMMENT_LEN
      Max length of a comment field. — 评论字段长度上限。
      See Also:

    • MAX_REASON_LEN

      public static final int MAX_REASON_LEN
      Max length of a reason field. — 理由字段长度上限。
      See Also:

    • MAX_USERID_LEN

      public static final int MAX_USERID_LEN
      Max length of a user id. — 用户 ID 长度上限。
      See Also:

    • ERROR_FIELD_MAX_LEN

      public static final int ERROR_FIELD_MAX_LEN
      Max length for fields embedded in exception messages. — 异常消息嵌入字段长度上限。
      See Also:

    • USERID_PATTERN

      public static final Pattern USERID_PATTERN
      Allowed characters in a user id. — 用户 ID 允许的字符集。

      The leading character must be alphanumeric or underscore (no hyphen) to prevent argument-injection downstream (a - prefix could be misinterpreted as a CLI flag by hosts that pass userIds into external commands without -- separators).

      首字符必须是字母数字或下划线（禁止 hyphen），避免下游把 -foo 误判为 CLI flag 引发参数注入。

  • Method Details

    • sanitizeComment

      public static String sanitizeComment(String input)
      Sanitises a comment field: returns null for null input; normalises line endings to \n; strips control characters other than \n; enforces MAX_COMMENT_LEN. 清洗 comment：null 直接返回 null；换行统一为 \n；剥离除 \n 外的控制字符；长度上限 MAX_COMMENT_LEN，超长抛 IllegalActionException （FlowErrorCode.INPUT_INVALID_TEXT）。
      Parameters:
      input - raw input — 原始输入
      Returns:
      cleaned text, or null when input is null — 清洗后的文本（输入为 null 时返回 null）
      Throws:
      IllegalActionException - when the cleaned text exceeds MAX_COMMENT_LEN characters
      Since:
      JDK 25, opencode-base-flow V1.0.5

    • sanitizeReason

      public static String sanitizeReason(String input)
      Sanitises a reason field: same rules as sanitizeComment(String) but capped at MAX_REASON_LEN. 清洗 reason：规则同 sanitizeComment(String)，上限 MAX_REASON_LEN。
      Parameters:
      input - raw input — 原始输入
      Returns:
      cleaned text, or null when input is null — 清洗后的文本（输入为 null 时返回 null）
      Throws:
      IllegalActionException - when the cleaned text exceeds MAX_REASON_LEN characters
      Since:
      JDK 25, opencode-base-flow V1.0.5

    • forErrorMessage

      public static String forErrorMessage(String input)
      Sanitises a string for safe embedding in exception / log messages — strips CRLF, C0 controls, DEL, Unicode line / segment separators (U+0085 / U+2028 / U+2029), bidi / zero-width characters and the BOM, then truncates to 64 characters. Never throws and never returns null: null input is rendered as "<null>" so callers can string-concat without a guard. 用于异常 / 日志消息拼接的脱敏：剥离 CRLF、C0、DEL、行 / 段分隔符以及 bidi / zero-width / BOM，按 64 截断。永不 抛异常 / 永不返回 null（null 输入呈现为 "<null>"）， 便于调用方直接字符串拼接而无需空值守卫。

      The truncation marker "…" (U+2026, single char) is appended when the input is trimmed so log readers can see the cut. Use this for error-message contexts only — for persisted text fields use sanitizeComment(String) or sanitizeReason(String).

      截断时追加 "…"（U+2026），便于日志阅读者识别。仅用于 异常消息，持久化场景请用 sanitizeComment / sanitizeReason。

      Parameters:
      input - raw input (may be null) — 原始输入（允许 null）
      Returns:
      sanitised + truncated text, never null — 脱敏 + 截断后的文本
      Since:
      JDK 25, opencode-base-flow V1.0.5

    • validateUserId

      public static String validateUserId(String userId)