Class DslParser

java.lang.Object
cloud.opencode.base.flow.dsl.DslParser
public class DslParser extends Object
JSON DSL → FlowDefinition parser (v4 §4, §11). JSON DSL → FlowDefinition 解析器（v4 §4 / §11）。

This parser is responsible for structural conversion only:

  • Enforce hard size quota (default 256 KiB; tunable via opencode.base.flow.dsl-max-bytes).
  • Validate schemaVersion == "1.0", else throw FlowErrorCode.DSL_UNSUPPORTED_SCHEMA_VERSION.
  • Materialize raw JSON into model records (Step, Transition, Assignee). Per-record validation (length, mode/strategy compatibility) is enforced inside the records.
  • Cache parsed FlowDefinition by exact DSL string in a size-bounded LRU (default 256; tunable via opencode.base.flow.dsl-cache-size).

Out of scope for this parser: reference completeness (every transition.from/to exists in steps[].id) and other semantic / quota rules — those are owned by the sibling DslValidator class.

本解析器只负责结构层转换：尺寸配额、schemaVersion 检查、raw DSL → 领域 record 转换、按字符串 LRU 缓存。引用完整性 / 配额 / 嵌套深度等校验由 DslValidator 负责。

Both maxBytes and cacheCapacity are read once at construction from System.getProperty(String) and frozen as instance fields (v4 D22 — avoid System.getProperty drift at runtime).

maxBytes 与 cacheCapacity 在构造时一次性读取系统属性并固化为 实例 final 字段（v4 D22：避免运行期 System.getProperty 漂移）。

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

  • Field Details

    • SUPPORTED_SCHEMA_VERSION

      public static final String SUPPORTED_SCHEMA_VERSION
      Currently supported DSL schemaVersion.
      See Also:

    • PROP_MAX_BYTES

      public static final String PROP_MAX_BYTES
      System property for max DSL byte size; default 256 KiB.
      See Also:

    • DEFAULT_MAX_BYTES

      public static final int DEFAULT_MAX_BYTES
      Default max DSL size in bytes (UTF-16 chars; conservative bound).
      See Also:

    • PROP_CACHE_SIZE

      public static final String PROP_CACHE_SIZE
      System property for parse cache capacity; default 256.
      See Also:

    • DEFAULT_CACHE_SIZE

      public static final int DEFAULT_CACHE_SIZE
      Default LRU cache capacity.
      See Also:

    • MAX_FLOW_KEY_LEN

      public static final int MAX_FLOW_KEY_LEN
      Hard cap on flowKey length (matches typical DB index limit). flowKey 长度上限（适配常见 DB 索引限制）。
      See Also:

    • MAX_NAME_LEN

      public static final int MAX_NAME_LEN
      Hard cap on name length. name 字段长度上限。
      See Also:

    • FLOW_KEY_PATTERN

      public static final Pattern FLOW_KEY_PATTERN
      Allowed characters in flowKey — starts with a letter, body limited to alphanumerics / underscore / hyphen / dot. Prevents log forging, path-traversal and metrics-tag injection via flowKey. flowKey 允许字符集；防止借 flowKey 做日志投毒、路径穿越、指标标签注入。

  • Constructor Details

    • DslParser

      public DslParser()
      Constructs a parser using the default JSON provider. 使用默认 JSON 提供者构造 parser。
      Since:
      JDK 25, opencode-base-flow V1.0.5

    • DslParser

      public DslParser(int maxBytes, int cacheCapacity)
      Constructs a parser with explicit limits (mainly for tests). 显式指定上限的构造（主要供测试使用）。
      Parameters:
      maxBytes - max DSL string length — 解析前长度上限
      cacheCapacity - LRU cache size (≥ 1) — LRU 容量（≥ 1）
      Since:
      JDK 25, opencode-base-flow V1.0.5

  • Method Details

    • parse

      public FlowDefinition parse(String dslJson)
      Parses the given DSL JSON string into a FlowDefinition. 把给定的 DSL JSON 解析为 FlowDefinition。

      The returned definition has an empty id (the service layer fills it after validation succeeds — DslValidator owns reference-completeness checks).

      返回值的 id 留空（由 service 层在校验通过后填充； DslValidator 负责引用完整性校验）。

      Parameters:
      dslJson - DSL JSON string — DSL JSON 字符串
      Returns:
      parsed flow definition — 解析后的流程定义
      Throws:
      DslParseException - on quota, schema-version or structural errors
      Since:
      JDK 25, opencode-base-flow V1.0.5

    • cacheSize

      public int cacheSize()
      Returns the size of the parse cache (mainly for tests). 返回解析缓存当前大小（主要供测试使用）。
      Returns:
      current entry count — 当前条目数
      Since:
      JDK 25, opencode-base-flow V1.0.5

    • clearCache

      public void clearCache()
      Clears the parse cache. 清空解析缓存。
      Since:
      JDK 25, opencode-base-flow V1.0.5

    • maxBytes

      public int maxBytes()
      Returns the frozen max-bytes limit. 返回固化后的字节上限。
      Returns:
      max bytes — 上限
      Since:
      JDK 25, opencode-base-flow V1.0.5

    • cacheCapacity

      public int cacheCapacity()
      Returns the frozen cache capacity. 返回固化后的缓存容量。
      Returns:
      cache capacity — 容量
      Since:
      JDK 25, opencode-base-flow V1.0.5