Repository navigation
Conversation
What: documentation only. State in the Javadoc of the CompressorStreamFactory no-arg and single-arg constructors, and of the LZMA and XZ builders' setMemoryLimitKiB, that the default (-1) imposes no memory limit; fix the outdated LZMA auto-detection note and extend the "Restricting Memory Usage" section of the site documentation; correct the copy-paste Javadoc links and examples in LZMACompressorInputStream and XZCompressorInputStream. Why: COMPRESS-731. LZMA and XZ decompression may allocate up to about 2 GiB for the dictionary declared inside the stream (xz-java DICT_SIZE_MAX), but nothing says the factory and builder defaults are unbounded, and examples.xml claims LZMA cannot be auto-detected although LZMAUtils.matches() has been part of CompressorStreamFactory.detect() since 1.10. The "Restricting Memory Usage" section also predates the current APIs and did not recommend setting a limit when decompressing untrusted input. How: Javadoc edits in CompressorStreamFactory, LZMACompressorInputStream and XZCompressorInputStream, plus src/site/xdoc/examples.xml. The memory section now recommends a heap-fitting limit for untrusted input with an example, and documents that the builders expose the same limit. No behavior change: japicmp reports no API differences. JIRA: COMPRESS-731 Signed-off-by: Inf1mum <vadimlazuk5@gmail.com>
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.
Fixes COMPRESS-731.
Problem
LZMA and XZ decompression may allocate up to about 2 GiB for the dictionary declared inside the stream (xz-java's
DICT_SIZE_MAX, verified against xz-java 1.12:LZMAInputStream.DICT_SIZE_MAX = Integer.MAX_VALUE & ~15), but no documentation says the defaults are unbounded:new CompressorStreamFactory()andnew CompressorStreamFactory(boolean)does not mention that these constructors run withmemoryLimitInKb = -1, and thememoryLimitInKbparameter ofCompressorStreamFactory(boolean, int)does not explain what-1means;LZMACompressorInputStreamandXZCompressorInputStreamdefault to-1, and the class-level examples show.setMemoryLimitKiB(-1)without saying what it does;-1behave differently between the two formats in xz-java 1.12:LZMAInputStreamchecksmemoryLimit != -1 && memoryNeeded > memoryLimit(so any other negative value rejects every stream), while the XZBlockInputStreamchecksmemoryLimit >= 0(so any negative value disables the check);src/site/xdoc/examples.xmlsays there is no way to detect the LZMA format, althoughLZMAUtils.matches()has been part ofCompressorStreamFactory.detect()since 1.10, and its "Restricting Memory Usage" section describes the 1.14 state without recommending a limit for untrusted input.Change
Documentation only:
CompressorStreamFactory: both existing-constructor Javadocs now state that no memory limit is imposed (LZMA/XZ may allocate up to about 2 GiB), and thememoryLimitInKbparameter documents-1as no limit;LZMACompressorInputStream.Builder.setMemoryLimitKiBand the deprecated two-arg constructor: default-1= no limit; any other negative value makes the underlying decoder reject every stream;XZCompressorInputStream: the class and builder examples explain.setMemoryLimitKiB(-1), and thesetMemoryLimitKiBparameter doc states that any negative value (default-1) imposes no limit;XZCompressorInputStream.BuilderlinkedLZMACompressorInputStream, bothbuilder()methods linkedLZMACompressorOutputStream, the LZMA builder example assigned toLZMACompressorOutputStream, and the two now-unusedLZMACompressor*imports inXZCompressorInputStreamare removed;examples.xml: the compressor-detection note now says only Brotli cannot be detected (LZMA since 1.10), and "Restricting Memory Usage" documents the unbounded default, recommends a heap-fitting limit for untrusted input with a factory example, and points to the builders'setMemoryLimitKiB.Verification
mvn test: 4781 tests, 0 failures, 0 errors (30 skipped, pre-existing);mvn verify(includes apache-rat, checkstyle, japicmp): BUILD SUCCESS, no API differences reported;javadoc:javadoc: BUILD SUCCESS;LZMAInputStream,XZInputStream,SingleXZInputStream,BlockInputStream).