Skip to content

refactor(schema): move the validateSchema worker out of JsonValidator into MetaSchemaCheck - #102

Merged
rawo merged 3 commits into
masterfrom
refactor/97-meta-schema-check
Nov 6, 2026
Merged

rawo merged 3 commits into
masterfrom
refactor/97-meta-schema-check

Conversation

@rawo

@rawo rawo commented Nov 6, 2026

Copy link
Copy Markdown
Owner

Summary

Moves the validateSchema() machinery out of JsonValidator.kt into a new MetaSchemaCheck.kt, a pure move with no behaviour change:

The public JsonValidator.validateSchema(schema) keeps its signature and KDoc. It keeps the enableMetaSchemaValidation check and delegates. The Java API is unchanged.

Ownership and lifetime

internal class MetaSchemaCheck(maxValidationDepth: Int) receives only the depth limit. Each JsonValidator holds one in a private val metaSchemaCheck by lazy { ... } instance field, so it is created on the first enabled validateSchema() call and dropped with the validator. Its own meta-schema validator is still by lazy inside it. No callback into the owning validator is needed: the worker only constructs and uses a separate JsonValidator, exactly as before. Nothing is stored in a top-level or companion object; the companion holds only constants and the pure metaSchemaDepth.

Verification

  • ./gradlew ktlintFormat, then CI=true ./gradlew test ktlintCheck --rerun-tasks: 5,849 tests, 0 failures, 0 errors, 0 skipped (from build/test-results/test/*.xml), including ValidateSchemaWorkerTest (3), MetaSchemaValidationTest (36), ValidatorLifecycleTest (3) and JavaApiUsageTest (11)
  • test_counts.py: exit 0 (full run 5,849, custom 1,379)
  • Every moved declaration was diffed against origin/master after normalising indentation and private: identical

Closes #97

🤖 Generated with Claude Code

… into MetaSchemaCheck

validateSchema() brought about 100 lines of thread machinery into JsonValidator.kt:
the iterative nesting check, the 64 MB-stack worker that inherits no thread-locals
(#56), joinUninterruptibly, metaSchemaDepth (#73), the lazily created meta-schema
validator and metaSchemaOf/metaSchemas, and the two constants only they use. Thread
lifecycle is not keyword evaluation (SRP), so it now lives in MetaSchemaCheck.kt,
beside MetaSchemas.kt whose data it uses.

MetaSchemaCheck is an internal class taking only maxValidationDepth. Each
JsonValidator creates its own lazily, on the first validateSchema() call with meta-schema
validation enabled, so the meta-schema validator keeps its lifetime and is freed with
the validator; no state is held in a top-level or companion object. The public
validateSchema() keeps its signature and KDoc, keeps the enableMetaSchemaValidation
check and delegates. The moved bodies, KDoc and comments are unchanged, as are the
thread name, stack size, interrupt handling and exception propagation.

Behaviour is unchanged.

Closes #97

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@rawo rawo added the refactor Restructuring without behaviour change label Nov 6, 2026
@rawo

rawo commented Nov 6, 2026

Copy link
Copy Markdown
Owner Author

Review of #102: move the validateSchema worker into MetaSchemaCheck

Verdict: this is a pure move with no behaviour change, and I found nothing blocking. There is one should-fix (a missing GC test for an acceptance criterion of #97) and two nits.

How I verified

  • I exported the PR head (1c22633) with git archive and ran CI=true ./gradlew test ktlintCheck --rerun-tasks against the sibling official suite. The result was BUILD SUCCESSFUL, with 5,849 tests, 0 failures, 0 errors, 0 skipped counted from build/test-results/test/*.xml. That includes ValidateSchemaWorkerTest, MetaSchemaValidationTest, ValidatorLifecycleTest and the official suite. ktlint is clean, and there are no new compiler warnings in either file.
  • Mechanical move check (script): I took every - line from the JsonValidator.kt diff against the merge base 489b815 and every line of MetaSchemaCheck.kt. I stripped indentation and blank lines and ran difflib on them.
    • All 92 removed lines appear in MetaSchemaCheck.kt, in the same order. None is altered, including the private modifiers.
    • The only lines added are scaffolding forced by the move: the package line, the three kotlinx.serialization.json imports, the class KDoc, internal class MetaSchemaCheck(private val maxValidationDepth: Int) {, fun validateSchema(schema: JsonSchema): ValidationResult {, companion object { and the closing braces.
    • The only lines added to JsonValidator.kt are the delegation, the metaSchemaCheck field and its KDoc. The only line removed outside the moved block is the now-unused ConcurrentHashMap import.
  • Negative control for the lifecycle claim: see the should-fix below.

Blocking

None. What I checked:

  • Worker unchanged: the thread name ktson-validateSchema, the 64 MB stack, inheritThreadLocals = false, the result/failure capture, the StackOverflowError mapping, failure?.let { throw it }, result!! and joinUninterruptibly are all byte-identical. The interrupt status is still restored.
  • Nesting check unchanged: it reads the same maxValidationDepth value, which MetaSchemaCheck receives from the validator. require(maxValidationDepth >= 0) still runs in JsonValidator.init before anything else.
  • enableMetaSchemaValidation = false: it still returns Valid before metaSchemaCheck is touched (JsonValidator.kt:118-122). With the check disabled, MetaSchemaCheck is never created.
  • Meta-schema validator configured the same way: enableMetaSchemaValidation = false, formatAssertion = true, maxValidationDepth = metaSchemaDepth(maxValidationDepth) (same formula, constants unchanged) and schemaLoader = MetaSchemas::load. It cannot recurse into itself: its own metaSchemaCheck is never initialised, because its check is disabled.
  • Eager metaSchemas map becoming lazy: this cannot be observed. Constructing an empty ConcurrentHashMap and two lazy holders has no side effects and cannot throw. metaSchemaOf was only ever called on the worker, as before. The only difference is that a validator that never calls validateSchema() now allocates fewer objects.

Should-fix

  1. The lifetime guarantee in refactor: move the validateSchema worker machinery out of JsonValidator into MetaSchemaCheck.kt #97 ("a dropped validator still frees its meta-schema validator") has no test. src/test/kotlin/org/ktson/ValidatorLifecycleTest.kt never calls validateSchema(); I confirmed this by grep.
    • Why the existing check is not enough: MetaSchemaCheck holds no reference back to its JsonValidator. So a leak of the check or its meta-schema validator into a global would not keep the outer validator alive. A weak reference to the validator alone cannot detect such a leak.
    • What I tried: I planted internal val LEAK = synchronizedList(...) and added the meta-schema validator to it in its lazy. The outer validator was still collected, while the meta-schema validator was not.
    • Suggested fix: add an it under describe("a dropped validator") in ValidatorLifecycleTest.kt. The file already reads private fields reflectively in cacheSize. Something like:
      it("frees its meta-schema check and meta-schema validator after validateSchema (#97)") {
          awaitCollected(validateSchemaAndDrop()) shouldBe true
      }
      
      /** Runs validateSchema, then returns weak references to the validator, its MetaSchemaCheck and that check's meta-schema validator. */
      private fun validateSchemaAndDrop(): List<WeakReference<*>> {
          val validator = JsonValidator()
          validator.validateSchema(JsonSchema.fromString("""{"type":"string"}""")).isValid shouldBe true
          val check = (JsonValidator::class.java.getDeclaredField("metaSchemaCheck\$delegate").apply { isAccessible = true }.get(validator) as Lazy<*>).value!!
          val metaValidator = MetaSchemaCheck::class.java.getDeclaredField("metaSchemaValidator\$delegate").apply { isAccessible = true }.get(check) as Lazy<*>
          metaValidator.isInitialized() shouldBe true
          return listOf(WeakReference(validator), WeakReference(check), WeakReference(metaValidator.value))
      }
    • Cost and robustness: I ran this prototype on the PR head. It passes in about 0.08 s. With the planted leak it fails with expected:<[true, true, true]> but was:<[true, true, false]>. It relies on the $delegate field names that Kotlin generates; those are stable, and a rename fails loudly with NoSuchFieldException rather than passing silently. It reuses awaitCollected, so it is no more flaky than the existing GC tests.
    • Docs to update with it: the ValidatorLifecycleTest count (3 → 4) in CLAUDE.md, the README and memory/MEMORY.md.

Nits

  1. CLAUDE.md:62: entry 1 still says JsonValidator "evaluates every keyword in a single class" and lists where the format grammars live. It could add "and the validateSchema() worker in MetaSchemaCheck", for symmetry with Formats, EcmaRegex and Idna. Those three each got their own numbered entry (11-13), while MetaSchemaCheck is a sub-bullet of entry 10 (CLAUDE.md:115). That is fine, since refactor: move the validateSchema worker machinery out of JsonValidator into MetaSchemaCheck.kt #97 asked for exactly that, but the line in entry 1 would help readers find it.
  2. MetaSchemaCheck.kt:12 and JsonValidator.kt:125: the KDoc says the check is "created on its first validateSchema call" / "created on first use". Strictly, it is created on the first call with meta-schema validation enabled; the PR body and MEMORY.md say this correctly. Optional wording fix.

Other checks (no findings)

  • Thread safety: both lazy fields use the default SYNCHRONIZED mode. git grep LazyThreadSafetyMode finds nothing in src, so no mode was weakened. Concurrent first calls create exactly one MetaSchemaCheck and one meta-schema validator. metaSchemas is still a ConcurrentHashMap with computeIfAbsent; its callback does no loading, only MetaSchemas.load from embedded source.
  • No global mutable state: the MetaSchemaCheck companion holds only two const vals and the pure metaSchemaDepth. Nothing is top-level. The worker thread has terminated by the time validateSchema returns, so it is not a GC root (also confirmed by the prototype test above).
  • API:
    • The validateSchema(schema: JsonSchema): ValidationResult signature, KDoc and annotations are unchanged (it never had @JvmOverloads, since it has no default arguments). JavaApiUsageTest passes.
    • MetaSchemaCheck is internal, so it is public in bytecode. That is the same as Formats, EcmaRegex and Idna.
    • No reflection, getResource or ServiceLoader in src/main.
    • No unused imports in either file: ktlint's no-unused-imports rule passes, and each of JsonArray, JsonElement, JsonObject and ConcurrentHashMap is used in MetaSchemaCheck.kt.
  • Style: it matches the other extractions: a file-level KDoc on the declaration, internal visibility and constants private to the holder. A class rather than an object is correct here, because it holds per-validator state.
  • Docs:
    • The sizes are accurate. JsonValidator.kt is 1,604 lines and 79,860 bytes (≈78 KiB), versus 1,700 lines and 84,299 bytes (≈82 KiB) before, which matches the KiB convention of the old figure. MetaSchemaCheck.kt is 118 lines (≈120).
    • git grep finds no other doc (README, docs/, CLAUDE.md, MEMORY.md) that places the worker, joinUninterruptibly or the meta-schema validator in JsonValidator.
    • The README describes behaviour only. docs/STACK_OVERFLOW_RISK_ANALYSIS.md:408 is a historical proposal, and docs/PROJECT_SUMMARY.md:76 (suspend fun validateSchema) was already stale and is unrelated to this PR.
    • CHANGELOG is untouched, as in the refactor: move the ECMA 262 regex dialect out of JsonValidator into EcmaRegex.kt #95/refactor: move format validation out of JsonValidator into Formats.kt #96 refactors.

🤖 Generated with Claude Code

rawo and others added 2 commits November 6, 2026 12:14
… check is created

CLAUDE.md's JsonValidator entry now names MetaSchemaCheck beside the other
extracted holders, and the KDoc of MetaSchemaCheck and of the metaSchemaCheck
field says it is created on the first validateSchema call with meta-schema
validation enabled, not on any first call.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
MetaSchemaCheck holds no reference back to its JsonValidator, so a leak of
the check or of its meta-schema validator into a global would not keep the
validator alive, and the existing lifecycle test never called
validateSchema(). The new case runs validateSchema(), drops the validator
and checks that the validator, its MetaSchemaCheck and the meta-schema
validator are each collected. A planted global list holding the meta-schema
validator makes it fail ([true, true, false]).

Test counts: custom 1,379 -> 1,380, full run 5,849 -> 5,850.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@rawo
rawo merged commit 33ee2f0 into master Nov 6, 2026
1 check passed
@rawo
rawo deleted the refactor/97-meta-schema-check branch November 6, 2026 11:27
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

refactor Restructuring without behaviour change

Projects

None yet

Development

Successfully merging this pull request may close these issues.

refactor: move the validateSchema worker machinery out of JsonValidator into MetaSchemaCheck.kt

1 participant