You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opennlp.apache.org by kr...@apache.org on 2026/08/14 03:17:20 UTC
(opennlp) 02/16: util: Usage example and hardening tests for the resource installer and tar reader, corrected javadoc
This is an automated email from the ASF dual-hosted git repository.
krickert pushed a commit to branch OPENNLP-1909-resource-installer
in repository https://gitbox.apache.org/repos/asf/opennlp.git
commit 0826827fceb1a87aa79618cf0248e92dff10885e
Author: Kristian Rickert <kr...@gmail.com>
AuthorDate: Thu Jul 16 01:19:45 2026 -0400
util: Usage example and hardening tests for the resource installer and tar reader, corrected javadoc
---
.../java/opennlp/tools/util/ResourceInstaller.java | 22 +-
.../java/opennlp/tools/util/archive/TarStream.java | 37 +++-
.../opennlp/tools/util/ResourceInstallerTest.java | 178 ++++++++++++++-
.../opennlp/tools/util/archive/TarStreamTest.java | 244 +++++++++++++++++++++
4 files changed, 465 insertions(+), 16 deletions(-)
diff --git a/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/util/ResourceInstaller.java b/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/util/ResourceInstaller.java
index 739833634..881db4da0 100644
--- a/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/util/ResourceInstaller.java
+++ b/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/util/ResourceInstaller.java
@@ -33,8 +33,8 @@ import java.util.zip.ZipInputStream;
import opennlp.tools.util.archive.TarStream;
/**
- * Fetches a user-chosen third-party resource, a training corpus, a dictionary archive,
- * a lexicon, into a local directory. The user supplies the location and thereby
+ * Fetches a user-chosen third-party resource, such as a training corpus, a dictionary
+ * archive, or a lexicon, into a local directory. The user supplies the location and thereby
* accepts that resource's license; nothing is bundled and no location is built in,
* which keeps externally licensed data entirely outside this library's distribution.
*
@@ -51,7 +51,7 @@ import opennlp.tools.util.archive.TarStream;
public final class ResourceInstaller {
private ResourceInstaller() {
- // static installer only
+ // This class exposes static methods only and is never instantiated.
}
/**
@@ -61,7 +61,7 @@ public final class ResourceInstaller {
* @param targetDirectory The directory to install into; created when absent. Must
* not be {@code null}.
* @return The target directory. Never {@code null}.
- * @throws IOException Thrown if fetching, verification, or unpacking fails.
+ * @throws IOException Thrown if fetching or unpacking fails.
* @throws IllegalArgumentException Thrown if a parameter is {@code null}.
*/
public static Path install(URI source, Path targetDirectory) throws IOException {
@@ -74,8 +74,9 @@ public final class ResourceInstaller {
* @param source The resource location. Must not be {@code null}.
* @param targetDirectory The directory to install into; created when absent. Must
* not be {@code null}.
- * @param sha256 The expected SHA-256 of the downloaded bytes as a hex string,
- * compared case-insensitively, or {@code null} to skip verification.
+ * @param sha256 The expected SHA-256 of the downloaded bytes as a hex string, compared
+ * case-insensitively and ignoring leading and trailing whitespace, or
+ * {@code null} to skip verification.
* @return The target directory. Never {@code null}.
* @throws IOException Thrown if fetching fails, the checksum does not match, or
* unpacking fails.
@@ -106,7 +107,10 @@ public final class ResourceInstaller {
}
}
- /** Compares the file's SHA-256 with the expected hex digest. */
+ /**
+ * Computes the file's SHA-256 and compares it with the expected hex digest, ignoring
+ * hex letter case and any leading or trailing whitespace around the expected value.
+ */
private static void verify(Path file, String expected) throws IOException {
final MessageDigest digest;
try {
@@ -176,6 +180,7 @@ public final class ResourceInstaller {
}
}
+ /** Unpacks every regular zip entry to its relative location beneath the target. */
private static void unpackZip(InputStream raw, Path target) throws IOException {
final ZipInputStream zip = new ZipInputStream(raw);
ZipEntry entry;
@@ -204,7 +209,8 @@ public final class ResourceInstaller {
&& block[260] == 'a' && block[261] == 'r') {
return true;
}
- // classic tar: a name and a valid octal size field
+ // Without the ustar magic, treat the block as a classic tar header when it starts
+ // with a name and its size field holds only octal digits, blanks, or NUL padding.
if (block[0] == 0) {
return false;
}
diff --git a/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/util/archive/TarStream.java b/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/util/archive/TarStream.java
index db7b4f4f4..653ab99ca 100644
--- a/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/util/archive/TarStream.java
+++ b/opennlp-core/opennlp-runtime/src/main/java/opennlp/tools/util/archive/TarStream.java
@@ -28,9 +28,10 @@ import opennlp.tools.commons.Internal;
* entry, skipping whatever remains of the current one, and {@link #entryStream()}
* exposes exactly the current entry's bytes. No external archive library is involved.
*
- * <p>Reads classic and ustar headers: entry name, octal size, and type flag. Long-name
- * extensions are not interpreted; such entries appear under their extension header
- * names and are skippable like any other.</p>
+ * <p>Reads classic and ustar headers: entry name, octal size, and type flag. The ustar
+ * name prefix field is not consulted, so an entry's name is always the content of the
+ * 100-byte name field alone. Long-name extension entries are not interpreted either;
+ * they appear under their extension header names and are skippable like any other.</p>
*/
@Internal
public final class TarStream {
@@ -146,6 +147,13 @@ public final class TarStream {
};
}
+ /**
+ * Fills the header buffer with the next 512-byte block.
+ *
+ * @return {@code true} when a full block was read, {@code false} at a clean end of
+ * the stream before any byte of the block.
+ * @throws IOException Thrown if the stream ends inside the block.
+ */
private boolean readBlock() throws IOException {
int filled = 0;
while (filled < header.length) {
@@ -161,6 +169,10 @@ public final class TarStream {
return true;
}
+ /**
+ * @return {@code true} if the current header buffer is one of the all-zero blocks
+ * that terminate a tar archive.
+ */
private boolean isEndBlock() {
for (final byte b : header) {
if (b != 0) {
@@ -170,6 +182,14 @@ public final class TarStream {
return true;
}
+ /**
+ * Parses the octal size field of the current header, tolerating NUL and blank
+ * padding around the digits.
+ *
+ * @return The entry size in bytes.
+ * @throws IOException Thrown if the field contains a character that is not an octal
+ * digit, a blank, or NUL padding.
+ */
private long parseOctal() throws IOException {
long value = 0;
for (int i = SIZE_OFFSET; i < SIZE_OFFSET + SIZE_LENGTH; i++) {
@@ -185,11 +205,22 @@ public final class TarStream {
return value;
}
+ /**
+ * @param entrySize The size of an entry's content in bytes.
+ * @return The number of padding bytes that align the entry to the next 512-byte
+ * block boundary.
+ */
private long padding(long entrySize) {
final long remainder = entrySize % BLOCK;
return remainder == 0 ? 0 : BLOCK - remainder;
}
+ /**
+ * Consumes and discards the given number of bytes from the underlying stream.
+ *
+ * @param bytes The number of bytes to discard.
+ * @throws IOException Thrown if the stream ends before all bytes were consumed.
+ */
private void skip(long bytes) throws IOException {
long toSkip = bytes;
final byte[] buffer = new byte[8192];
diff --git a/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/util/ResourceInstallerTest.java b/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/util/ResourceInstallerTest.java
index 5c937e7da..9c95a9762 100644
--- a/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/util/ResourceInstallerTest.java
+++ b/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/util/ResourceInstallerTest.java
@@ -23,6 +23,8 @@ import java.nio.charset.StandardCharsets;
import java.nio.file.Files;
import java.nio.file.Path;
import java.security.MessageDigest;
+import java.util.List;
+import java.util.stream.Stream;
import java.util.zip.GZIPOutputStream;
import java.util.zip.ZipEntry;
import java.util.zip.ZipOutputStream;
@@ -33,11 +35,24 @@ import org.junit.jupiter.api.io.TempDir;
public class ResourceInstallerTest {
- /** Writes one ustar entry: a 512-byte header block and padded content. */
+ /**
+ * Writes one tar entry into the given buffer: a 512-byte header block carrying the
+ * name, the octal content size, and the regular-file type flag, followed by the
+ * content padded to the next 512-byte block boundary.
+ *
+ * @param tar The buffer receiving the entry bytes. Must not be {@code null}.
+ * @param name The entry name; at most 100 bytes when encoded as UTF-8.
+ * @param content The entry content. Must not be {@code null}.
+ * @throws IOException Thrown if writing to the buffer fails.
+ * @throws IllegalArgumentException Thrown if the name exceeds the tar name field.
+ */
private static void tarEntry(ByteArrayOutputStream tar, String name, byte[] content)
throws IOException {
final byte[] header = new byte[512];
final byte[] nameBytes = name.getBytes(StandardCharsets.UTF_8);
+ if (nameBytes.length > 100) {
+ throw new IllegalArgumentException("entry name exceeds 100 bytes: " + name);
+ }
System.arraycopy(nameBytes, 0, header, 0, nameBytes.length);
final String size = String.format("%011o", content.length);
System.arraycopy(size.getBytes(StandardCharsets.US_ASCII), 0, header, 124, 11);
@@ -48,6 +63,14 @@ public class ResourceInstallerTest {
tar.write(new byte[padding]);
}
+ /**
+ * Builds a gzip-compressed tar archive from name and content pairs, terminated by
+ * the two all-zero blocks that end a tar archive.
+ *
+ * @param entries Pairs of entry name and UTF-8 text content. Must not be {@code null}.
+ * @return The archive bytes. Never {@code null}.
+ * @throws IOException Thrown if assembling the archive fails.
+ */
private static byte[] tarGz(String[][] entries) throws IOException {
final ByteArrayOutputStream tar = new ByteArrayOutputStream();
for (final String[] entry : entries) {
@@ -61,6 +84,13 @@ public class ResourceInstallerTest {
return compressed.toByteArray();
}
+ /**
+ * Computes the SHA-256 of the given bytes as a lowercase hex string.
+ *
+ * @param content The bytes to digest. Must not be {@code null}.
+ * @return The 64-character lowercase hex digest. Never {@code null}.
+ * @throws Exception Thrown if the digest algorithm is unavailable.
+ */
private static String sha256(byte[] content) throws Exception {
final StringBuilder hex = new StringBuilder();
for (final byte b : MessageDigest.getInstance("SHA-256").digest(content)) {
@@ -70,6 +100,72 @@ public class ResourceInstallerTest {
return hex.toString();
}
+ /**
+ * Computes the SHA-256 of the given bytes as an uppercase hex string, built from an
+ * uppercase digit table, so tests can prove that checksum comparison does not depend
+ * on the hex letter case.
+ *
+ * @param content The bytes to digest. Must not be {@code null}.
+ * @return The 64-character uppercase hex digest. Never {@code null}.
+ * @throws Exception Thrown if the digest algorithm is unavailable.
+ */
+ private static String sha256UpperCase(byte[] content) throws Exception {
+ final String digits = "0123456789ABCDEF";
+ final StringBuilder hex = new StringBuilder();
+ for (final byte b : MessageDigest.getInstance("SHA-256").digest(content)) {
+ hex.append(digits.charAt((b >> 4) & 0xF)).append(digits.charAt(b & 0xF));
+ }
+ return hex.toString();
+ }
+
+ /**
+ * Lists every regular file below the given directory as relative paths with forward
+ * slashes, sorted lexicographically, so tests can assert the exact installed file
+ * set.
+ *
+ * @param root The directory to walk. Must not be {@code null}.
+ * @return The sorted relative paths. Never {@code null}.
+ * @throws IOException Thrown if walking the directory fails.
+ */
+ private static List<String> installedFiles(Path root) throws IOException {
+ try (Stream<Path> walk = Files.walk(root)) {
+ return walk.filter(Files::isRegularFile)
+ .map(file -> root.relativize(file).toString().replace('\\', '/'))
+ .sorted()
+ .toList();
+ }
+ }
+
+ /**
+ * Demonstrates the intended end-to-end flow: package a small corpus as tar.gz,
+ * compute its real SHA-256, install it through the public API, and verify that
+ * exactly the archived files, and nothing else, appear on disk with their exact
+ * content.
+ */
+ @Test
+ void testInstallEndToEndUsageExample(@TempDir Path source, @TempDir Path target)
+ throws Exception {
+ final byte[] archive = tarGz(new String[][] {
+ {"corpus/README", "A tiny example corpus.\n"},
+ {"corpus/tokens.txt", "the\ncat\n"},
+ {"corpus/pos/tags.tsv", "the\tDET\ncat\tNOUN\n"}});
+ final Path file = source.resolve("corpus.tar.gz");
+ Files.write(file, archive);
+
+ final Path result = ResourceInstaller.install(file.toUri(), target, sha256(archive));
+
+ Assertions.assertEquals(target, result);
+ Assertions.assertEquals(
+ List.of("corpus/README", "corpus/pos/tags.tsv", "corpus/tokens.txt"),
+ installedFiles(target));
+ Assertions.assertEquals("A tiny example corpus.\n",
+ Files.readString(target.resolve("corpus/README")));
+ Assertions.assertEquals("the\ncat\n",
+ Files.readString(target.resolve("corpus/tokens.txt")));
+ Assertions.assertEquals("the\tDET\ncat\tNOUN\n",
+ Files.readString(target.resolve("corpus/pos/tags.tsv")));
+ }
+
@Test
void testTarGzUnpacksWithStructure(@TempDir Path source, @TempDir Path target)
throws Exception {
@@ -94,12 +190,35 @@ public class ResourceInstallerTest {
final Path file = source.resolve("archive.tar.gz");
Files.write(file, archive);
- Assertions.assertThrows(IOException.class, () -> ResourceInstaller.install(
- file.toUri(), target, "00000000000000000000000000000000"
- + "00000000000000000000000000000000"));
+ final String wrong = "0".repeat(64);
+ final IOException thrown = Assertions.assertThrows(IOException.class,
+ () -> ResourceInstaller.install(file.toUri(), target, wrong));
+ Assertions.assertEquals(IOException.class, thrown.getClass());
+ Assertions.assertEquals("checksum mismatch: expected " + wrong
+ + " but downloaded " + sha256(archive), thrown.getMessage());
Assertions.assertEquals(0, Files.list(target).count());
}
+ /**
+ * Proves that the hex digest comparison is case-insensitive: an uppercase rendering
+ * of the correct digest passes verification and the archive is unpacked.
+ */
+ @Test
+ void testChecksumComparisonIgnoresHexLetterCase(@TempDir Path source,
+ @TempDir Path target) throws Exception {
+ final byte[] archive = tarGz(new String[][] {{"data/entry.txt", "payload"}});
+ final Path file = source.resolve("cased.tar.gz");
+ Files.write(file, archive);
+ // The uppercase digest must differ textually from the lowercase one, otherwise
+ // this test would not exercise the case handling at all.
+ Assertions.assertNotEquals(sha256(archive), sha256UpperCase(archive));
+
+ ResourceInstaller.install(file.toUri(), target, sha256UpperCase(archive));
+
+ Assertions.assertEquals("payload",
+ Files.readString(target.resolve("data/entry.txt")));
+ }
+
@Test
void testEscapingEntriesAreRejected(@TempDir Path source, @TempDir Path target)
throws Exception {
@@ -107,11 +226,60 @@ public class ResourceInstallerTest {
final Path file = source.resolve("evil.tar.gz");
Files.write(file, archive);
- Assertions.assertThrows(IOException.class,
+ final IOException thrown = Assertions.assertThrows(IOException.class,
() -> ResourceInstaller.install(file.toUri(), target));
+ Assertions.assertEquals(
+ "archive entry escapes the target directory: ../escape.txt",
+ thrown.getMessage());
Assertions.assertTrue(Files.notExists(target.getParent().resolve("escape.txt")));
}
+ /**
+ * Proves that a tar entry with an absolute name is rejected before anything is
+ * written, so a hostile archive cannot place files at arbitrary locations.
+ */
+ @Test
+ void testAbsoluteTarEntryIsRejected(@TempDir Path source, @TempDir Path target)
+ throws Exception {
+ final byte[] archive = tarGz(new String[][] {
+ {"/absolute-escape-attempt/evil.txt", "bad"}});
+ final Path file = source.resolve("absolute.tar.gz");
+ Files.write(file, archive);
+
+ final IOException thrown = Assertions.assertThrows(IOException.class,
+ () -> ResourceInstaller.install(file.toUri(), target));
+ Assertions.assertEquals(
+ "archive entry escapes the target directory: /absolute-escape-attempt/evil.txt",
+ thrown.getMessage());
+ Assertions.assertEquals(0, Files.list(target).count());
+ Assertions.assertTrue(Files.notExists(Path.of("/absolute-escape-attempt")));
+ }
+
+ /**
+ * Proves that the escape guard also covers zip content: an entry whose name climbs
+ * out of the target directory is rejected and nothing is written.
+ */
+ @Test
+ void testZipEntryWithTraversalIsRejected(@TempDir Path source, @TempDir Path target)
+ throws Exception {
+ final ByteArrayOutputStream out = new ByteArrayOutputStream();
+ try (ZipOutputStream zip = new ZipOutputStream(out)) {
+ zip.putNextEntry(new ZipEntry("../zip-escape.txt"));
+ zip.write("bad".getBytes(StandardCharsets.UTF_8));
+ zip.closeEntry();
+ }
+ final Path file = source.resolve("evil.zip");
+ Files.write(file, out.toByteArray());
+
+ final IOException thrown = Assertions.assertThrows(IOException.class,
+ () -> ResourceInstaller.install(file.toUri(), target));
+ Assertions.assertEquals(
+ "archive entry escapes the target directory: ../zip-escape.txt",
+ thrown.getMessage());
+ Assertions.assertTrue(Files.notExists(target.getParent().resolve("zip-escape.txt")));
+ Assertions.assertEquals(0, Files.list(target).count());
+ }
+
@Test
void testZipUnpacks(@TempDir Path source, @TempDir Path target) throws Exception {
final ByteArrayOutputStream out = new ByteArrayOutputStream();
diff --git a/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/util/archive/TarStreamTest.java b/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/util/archive/TarStreamTest.java
new file mode 100644
index 000000000..dc79ee4e9
--- /dev/null
+++ b/opennlp-core/opennlp-runtime/src/test/java/opennlp/tools/util/archive/TarStreamTest.java
@@ -0,0 +1,244 @@
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one or more
+ * contributor license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright ownership.
+ * The ASF licenses this file to You under the Apache License, Version 2.0
+ * (the "License"); you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package opennlp.tools.util.archive;
+
+import java.io.ByteArrayInputStream;
+import java.io.ByteArrayOutputStream;
+import java.io.IOException;
+import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Exercises {@link TarStream} against archives built byte by byte in the test, covering
+ * regular traversal as well as boundary and corruption cases.
+ */
+public class TarStreamTest {
+
+ /**
+ * Builds one 512-byte tar header block with the given name, declared content size,
+ * and type flag. The mode field is populated with a non-zero octal value so that a
+ * name filling the whole 100-byte name field is followed by non-zero bytes, which
+ * makes name-boundary tests meaningful.
+ *
+ * @param name The entry name; at most 100 bytes when encoded as UTF-8.
+ * @param size The content size to declare in the octal size field; must not be
+ * negative.
+ * @param typeFlag The tar type flag, for example {@code '0'} for a regular file,
+ * {@code '5'} for a directory, or {@code '\0'} for an old-style
+ * regular file.
+ * @return The header block. Never {@code null}.
+ * @throws IllegalArgumentException Thrown if the name does not fit the name field or
+ * the size is negative.
+ */
+ private static byte[] header(String name, long size, char typeFlag) {
+ final byte[] nameBytes = name.getBytes(StandardCharsets.UTF_8);
+ if (nameBytes.length > 100) {
+ throw new IllegalArgumentException("entry name exceeds 100 bytes: " + name);
+ }
+ if (size < 0) {
+ throw new IllegalArgumentException("size must not be negative: " + size);
+ }
+ final byte[] block = new byte[512];
+ System.arraycopy(nameBytes, 0, block, 0, nameBytes.length);
+ final byte[] mode = "0000644 ".getBytes(StandardCharsets.US_ASCII);
+ System.arraycopy(mode, 0, block, 100, mode.length);
+ final String sizeOctal = String.format("%011o", size);
+ System.arraycopy(sizeOctal.getBytes(StandardCharsets.US_ASCII), 0, block, 124, 11);
+ block[156] = (byte) typeFlag;
+ return block;
+ }
+
+ /**
+ * Writes one complete tar entry into the given buffer: the header block declaring
+ * the content's actual length, the content itself, and zero padding up to the next
+ * 512-byte block boundary.
+ *
+ * @param tar The buffer receiving the entry bytes. Must not be {@code null}.
+ * @param name The entry name; at most 100 bytes when encoded as UTF-8.
+ * @param content The entry content. Must not be {@code null}.
+ * @param typeFlag The tar type flag for the header.
+ * @throws IOException Thrown if writing to the buffer fails.
+ */
+ private static void entry(ByteArrayOutputStream tar, String name, byte[] content,
+ char typeFlag) throws IOException {
+ tar.write(header(name, content.length, typeFlag));
+ tar.write(content);
+ tar.write(new byte[(512 - content.length % 512) % 512]);
+ }
+
+ /**
+ * Proves that a stream without a single byte is treated as an archive with no
+ * entries rather than as an error.
+ */
+ @Test
+ void testEmptyStreamHasNoEntries() throws IOException {
+ final TarStream stream = new TarStream(new ByteArrayInputStream(new byte[0]));
+ Assertions.assertFalse(stream.next());
+ }
+
+ /**
+ * Proves that an archive consisting only of the two all-zero terminator blocks
+ * reports no entries.
+ */
+ @Test
+ void testTerminatorOnlyArchiveHasNoEntries() throws IOException {
+ final TarStream stream = new TarStream(new ByteArrayInputStream(new byte[1024]));
+ Assertions.assertFalse(stream.next());
+ }
+
+ /**
+ * Walks an archive holding a directory, a file whose content is deliberately left
+ * unread, a file with an old-style NUL type flag, and a file whose size is an exact
+ * block multiple, asserting name, size, type classification, and content for each
+ * entry, and the end of the archive after the last one.
+ */
+ @Test
+ void testReadsEntriesSizesTypesAndContent() throws IOException {
+ final byte[] blockSized = new byte[512];
+ for (int i = 0; i < blockSized.length; i++) {
+ blockSized[i] = (byte) (i % 251);
+ }
+ final ByteArrayOutputStream tar = new ByteArrayOutputStream();
+ entry(tar, "data/", new byte[0], '5');
+ entry(tar, "data/skip.bin", "0123456789".getBytes(StandardCharsets.US_ASCII), '0');
+ entry(tar, "data/alpha.txt", "alpha\n".getBytes(StandardCharsets.UTF_8), '\0');
+ entry(tar, "block.bin", blockSized, '0');
+ tar.write(new byte[1024]);
+ final TarStream stream = new TarStream(new ByteArrayInputStream(tar.toByteArray()));
+
+ Assertions.assertTrue(stream.next());
+ Assertions.assertEquals("data/", stream.name());
+ Assertions.assertEquals(0, stream.size());
+ Assertions.assertFalse(stream.isFile());
+
+ // The next call must skip the unread content and padding of this entry.
+ Assertions.assertTrue(stream.next());
+ Assertions.assertEquals("data/skip.bin", stream.name());
+ Assertions.assertEquals(10, stream.size());
+ Assertions.assertTrue(stream.isFile());
+
+ Assertions.assertTrue(stream.next());
+ Assertions.assertEquals("data/alpha.txt", stream.name());
+ Assertions.assertEquals(6, stream.size());
+ Assertions.assertTrue(stream.isFile());
+ Assertions.assertArrayEquals("alpha\n".getBytes(StandardCharsets.UTF_8),
+ stream.entryStream().readAllBytes());
+
+ Assertions.assertTrue(stream.next());
+ Assertions.assertEquals("block.bin", stream.name());
+ Assertions.assertEquals(512, stream.size());
+ Assertions.assertTrue(stream.isFile());
+ Assertions.assertArrayEquals(blockSized, stream.entryStream().readAllBytes());
+
+ Assertions.assertFalse(stream.next());
+ }
+
+ /**
+ * Proves that a name occupying all 100 bytes of the name field is read in full and
+ * does not bleed into the adjacent, non-zero mode field.
+ */
+ @Test
+ void testNameFillsFullHundredByteField() throws IOException {
+ final StringBuilder longName = new StringBuilder("d/");
+ while (longName.length() < 100) {
+ longName.append('x');
+ }
+ final String name = longName.toString();
+ final ByteArrayOutputStream tar = new ByteArrayOutputStream();
+ entry(tar, name, "n".getBytes(StandardCharsets.US_ASCII), '0');
+ tar.write(new byte[1024]);
+ final TarStream stream = new TarStream(new ByteArrayInputStream(tar.toByteArray()));
+
+ Assertions.assertTrue(stream.next());
+ Assertions.assertEquals(100, stream.name().length());
+ Assertions.assertEquals(name, stream.name());
+ Assertions.assertArrayEquals("n".getBytes(StandardCharsets.US_ASCII),
+ stream.entryStream().readAllBytes());
+ Assertions.assertFalse(stream.next());
+ }
+
+ /**
+ * Proves that a stream ending in the middle of a header block fails loud instead of
+ * silently reporting the end of the archive.
+ */
+ @Test
+ void testTruncatedHeaderFailsLoud() {
+ final byte[] partial = Arrays.copyOf(header("cut.bin", 0, '0'), 200);
+ final TarStream stream = new TarStream(new ByteArrayInputStream(partial));
+
+ final IOException thrown = Assertions.assertThrows(IOException.class, stream::next);
+ Assertions.assertEquals("truncated tar header", thrown.getMessage());
+ }
+
+ /**
+ * Proves that an entry stream fails loud when the underlying stream ends before the
+ * declared entry size has been delivered.
+ */
+ @Test
+ void testTruncatedEntryContentFailsLoud() throws IOException {
+ final ByteArrayOutputStream tar = new ByteArrayOutputStream();
+ tar.write(header("data.bin", 10, '0'));
+ tar.write("1234".getBytes(StandardCharsets.US_ASCII));
+ final TarStream stream = new TarStream(new ByteArrayInputStream(tar.toByteArray()));
+
+ Assertions.assertTrue(stream.next());
+ final IOException thrown = Assertions.assertThrows(IOException.class,
+ () -> stream.entryStream().readAllBytes());
+ Assertions.assertEquals("truncated tar entry: data.bin", thrown.getMessage());
+ }
+
+ /**
+ * Proves that advancing past an entry whose content is missing from the stream fails
+ * loud during the skip instead of reporting a clean end of the archive.
+ */
+ @Test
+ void testTruncatedArchiveWhenSkippingFailsLoud() throws IOException {
+ final TarStream stream = new TarStream(
+ new ByteArrayInputStream(header("gone.bin", 600, '0')));
+
+ Assertions.assertTrue(stream.next());
+ final IOException thrown = Assertions.assertThrows(IOException.class, stream::next);
+ Assertions.assertEquals("truncated tar archive", thrown.getMessage());
+ }
+
+ /**
+ * Proves that a header whose size field carries a non-octal digit is rejected with a
+ * descriptive exception instead of producing a bogus size.
+ */
+ @Test
+ void testMalformedSizeFieldFailsLoud() {
+ final byte[] block = header("bad.bin", 0, '0');
+ block[124] = '9';
+ final TarStream stream = new TarStream(new ByteArrayInputStream(block));
+
+ final IOException thrown = Assertions.assertThrows(IOException.class, stream::next);
+ Assertions.assertEquals("malformed tar size field in entry header",
+ thrown.getMessage());
+ }
+
+ /**
+ * Proves that the constructor rejects a missing input stream.
+ */
+ @Test
+ void testNullStreamIsRejected() {
+ Assertions.assertThrows(IllegalArgumentException.class, () -> new TarStream(null));
+ }
+}