AVRO-4311: [java] Escape backslashes in generated Javadoc#3880
Open
iemejia wants to merge 2 commits into
Open
Conversation
The code generator writes schema documentation strings into the Javadoc comments of generated Java sources. escapeForJavadoc escaped the comment terminator and HTML metacharacters but left backslashes untouched. The Java compiler translates Unicode escapes (\uXXXX) across the whole source file, including inside comments, before comments are recognized (JLS 3.3). A documentation string containing backslash sequences could therefore be reinterpreted by the compiler and change the generated source in unintended ways. Neutralize backslashes in escapeForJavadoc by encoding them as the HTML entity \, so documentation content is always emitted as inert text. Add a regression test covering several escape forms. The string-literal path (escapeForJavaString) already doubles backslashes and is unaffected.
There was a problem hiding this comment.
Pull request overview
This PR hardens the Java specific-code generator’s Javadoc emission by ensuring schema documentation cannot be reinterpreted by javac as Unicode escapes (JLS 3.3), which could otherwise terminate comments early and enable code injection in generated sources.
Changes:
- Update
SpecificCompiler.escapeForJavadocto neutralize backslashes by emitting\(in addition to existing*/and</>escaping). - Add a new regression test that exercises multiple Unicode-escape variants and verifies no raw backslash reaches generated Javadoc comments.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| lang/java/compiler/src/main/java/org/apache/avro/compiler/specific/SpecificCompiler.java | Extends Javadoc-escaping helper to neutralize backslashes and documents the rationale (Unicode-escape translation before comment recognition). |
| lang/java/compiler/src/test/java/org/apache/avro/compiler/specific/TestSpecificCompiler.java | Adds an end-to-end regression test covering multiple malicious doc patterns to ensure generated Javadoc contains no raw backslashes. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Address review feedback: the end-to-end assertion only inspected lines starting with "/**" or "*", so the middle physical lines of a multi-line Javadoc block (a doc containing newlines) were not checked. Replace the line-based scan with one that removes all Java string literals (the embedded schema, which legitimately contains doubled backslashes) and then asserts no backslash remains in the surrounding code and comments. Add a doc vector that spans multiple physical lines.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What is the purpose of the change
The Java code generator (
avro-compiler/avro-maven-plugin) writes schemadocumentation strings into the Javadoc comments of generated Java sources.
The
escapeForJavadochelper escapes the comment terminator (*/) and HTMLmetacharacters, but it leaves backslashes untouched.
The Java compiler translates Unicode escapes (
\uXXXX) across the whole sourcefile, including inside comments, before comments are recognized (JLS 3.3). As a
result, a documentation string containing backslash sequences can be
reinterpreted by the compiler and change the generated source in unintended
ways.
This change updates
escapeForJavadocto also neutralize backslashes byencoding them as the HTML entity
\, so documentation content is alwaysemitted as inert text in the generated Javadoc. The string-literal path
(
escapeForJavaString, used for the embedded schema) already doublesbackslashes and is unaffected.
Fixes AVRO-4311.
Verifying this change
This change added tests and can be verified as follows:
TestSpecificCompiler#unicodeEscapesInDocsAreNeutralized, which checksboth the
escapeForJavadochelper and full code generation against severalescape forms (multiple
us, backslash-producing escapes, even-lengthbackslash runs, uppercase-hex decoys, and a literal
*/), asserting that nobackslash reaches the generated Javadoc comments.
docsAreEscaped_avro4053) continues to pass.avro-compilermodule test suite is green (mvn -pl compiler test) andSpotless formatting passes.
Documentation