feat: add allowUnclosedQuote flag to reader builders (#173)

Allows callers to opt into rejecting input that ends inside a quoted field
(EOF before a closing quote). Default in 4.x is `true` (current lenient
behavior); the default will flip to `false` in 5.0.

The check fires once at EOF: in StrictCsvParser.processBufferTail when
STATUS_QUOTED_MODE is still set, and in RelaxedCsvParser.parseQuoted on
the EOF exit of the OUTER loop. The closed-quote hot path is unaffected.

Independent of this flag, exceeding maxBufferSize inside an unclosed
quoted region continues to throw, as before.

Author: osiegmar

docs/src/content/docs/architecture/interpretation.md

@@ -208,6 +208,24 @@ In this case, we observe:
     - For performance reasons, FastCSV switches to unquoted-field-parsing when the first character is not a quote
       character. It's not reasonable to slow down the parser in order to guess which broken format is used.
 
+### Unclosed quoted fields
+
+A quoted field may be unintentionally truncated, leaving an opening quote without a matching close before end-of-file:
+
+```
+"value 1,value 2CRLF
+value 3CRLF
+```
+
+By default, FastCSV consumes the remaining bytes (including any newlines) as the content of the final field, in line with its tolerance of real-world malformed input.
+
+This behavior can be made strict by setting `CsvReaderBuilder.allowUnclosedQuote(false)` (also available
+on `IndexedCsvReaderBuilder`). FastCSV then throws a `CsvParseException` that references the starting line of the
+offending record.
+
+The default of this flag will change to `false` in version 5.0. To preserve the current lenient behavior across the
+upgrade, set it explicitly to `true`.
+
 ### Other field enclosures
 
 The RFC does not mention any field enclosures other than double quotes.

docs/src/content/docs/guides/basic.md

@@ -55,6 +55,7 @@ CsvReader.builder()
     .extraFieldStrategy(FieldMismatchStrategy.STRICT)
     .missingFieldStrategy(FieldMismatchStrategy.STRICT)
     .allowExtraCharsAfterClosingQuote(false)
+    .allowUnclosedQuote(true)
     .detectBomHeader(false)
     .maxBufferSize(16777216);
 ```

lib/src/intTest/java/blackbox/reader/AbstractCsvReaderTest.java

@@ -8,6 +8,7 @@
 import java.io.IOException;
 import java.io.StringReader;
 import java.io.UncheckedIOException;
+import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
 import java.util.NoSuchElementException;
@@ -29,6 +30,7 @@
 import de.siegmar.fastcsv.reader.CsvRecord;
 import de.siegmar.fastcsv.reader.CsvRecordHandler;
 import de.siegmar.fastcsv.reader.FieldMismatchStrategy;
+import de.siegmar.fastcsv.reader.FieldModifier;
 import de.siegmar.fastcsv.reader.FieldModifiers;
 import testutil.CsvRecordAssert;
 
@@ -220,6 +222,61 @@ void allowExtraCharsAfterClosingQuoteNot() {
             .hasRootCauseMessage("Unexpected character after closing quote: 'b' (0x62)");
     }
 
+    // allow unclosed quote at end of input
+
+    @Test
+    void allowUnclosedQuoteLenient() {
+        assertThat(readAll("\"abc"))
+            .singleElement(CsvRecordAssert.CSV_RECORD)
+            .fields().containsExactly("abc");
+    }
+
+    @Test
+    void allowUnclosedQuoteStrict() {
+        // Throw must reference the record's starting line, not the EOF line; second record's start
+        // (line 2) verifies cross-record line tracking too.
+        crb.allowUnclosedQuote(false);
+        assertThatThrownBy(() -> readAll("a,b\n\"c"))
+            .isInstanceOf(CsvParseException.class)
+            .hasRootCauseInstanceOf(CsvParseException.class)
+            .hasRootCauseMessage("Unclosed quoted field at end of input (record starting at line 2)");
+    }
+
+    @Test
+    void allowUnclosedQuoteStrictAcceptsClosedAtEof() {
+        // Guard against false positives on the closing-quote-immediately-before-EOF path.
+        crb.allowUnclosedQuote(false);
+        assertThatCode(() -> readAll("\"closed\"")).doesNotThrowAnyException();
+    }
+
+    @Test
+    void allowUnclosedQuoteIgnoresComments() {
+        // Comment paths are quote-agnostic — an unbalanced quote inside a comment must stay a comment.
+        crb.allowUnclosedQuote(false).commentStrategy(CommentStrategy.READ);
+        assertThat(readAll("#abc\"def"))
+            .singleElement(CsvRecordAssert.CSV_RECORD)
+            .isComment()
+            .fields().containsExactly("abc\"def");
+    }
+
+    @Test
+    void allowUnclosedQuoteThrowsBeforeFieldModifier() {
+        // The throw must happen before addField is called, so a registered FieldModifier
+        // never sees a phantom field for the failing record.
+        final List<String> seen = new ArrayList<>();
+        final var handler = CsvRecordHandler.of(c -> c.fieldModifier(FieldModifier.modify(value -> {
+            seen.add(value);
+            return value;
+        })));
+
+        crb.allowUnclosedQuote(false);
+
+        assertThatThrownBy(() -> crb.build(handler, "a,b\n\"c").stream().toList())
+            .isInstanceOf(CsvParseException.class);
+
+        assertThat(seen).containsExactly("a", "b");
+    }
+
     // field by index
 
     @Test

lib/src/intTest/java/blackbox/reader/CsvReaderBuilderTest.java

@@ -81,7 +81,8 @@ void builderToString() {
                 CsvReaderBuilder[fieldSeparator=,, quoteCharacter=", \
                 commentStrategy=NONE, commentCharacter=#, skipEmptyLines=true, \
                 extraFieldStrategy=STRICT, missingFieldStrategy=STRICT, allowExtraCharsAfterClosingQuote=false, \
-                trimWhitespacesAroundQuotes=false, detectBomHeader=false, maxBufferSize=16777216]""");
+                allowUnclosedQuote=true, trimWhitespacesAroundQuotes=false, detectBomHeader=false, \
+                maxBufferSize=16777216]""");
     }
 
     @Test
@@ -132,6 +133,7 @@ void chained() {
             .extraFieldStrategy(FieldMismatchStrategy.STRICT)
             .missingFieldStrategy(FieldMismatchStrategy.STRICT)
             .allowExtraCharsAfterClosingQuote(false)
+            .allowUnclosedQuote(true)
             .ofCsvRecord("foo");
 
         assertThat(reader).isNotNull();

lib/src/intTest/java/blackbox/reader/IndexedCsvReaderTest.java

@@ -78,7 +78,7 @@ void readerToString() throws IOException {
             .isEqualTo("""
                     IndexedCsvReader[file=%s, charset=UTF-8, fieldSeparator=,, \
                     quoteCharacter=", commentStrategy=NONE, commentCharacter=#, \
-                    allowExtraCharsAfterClosingQuote=false, pageSize=1, \
+                    allowExtraCharsAfterClosingQuote=false, allowUnclosedQuote=true, pageSize=1, \
                     index=CsvIndex[bomHeaderLength=0, fileSize=3, fieldSeparator=44, quoteCharacter=34, \
                     commentStrategy=NONE, commentCharacter=35, recordCount=1, pageCount=1]]""",
                 file);
@@ -197,6 +197,26 @@ void allowExtraCharsAfterClosingQuoteNot() throws IOException {
         }
     }
 
+    // allow unclosed quote at end of input
+
+    @Test
+    void allowUnclosedQuoteLenientByDefault() throws IOException {
+        try (var csv = singlePageBuilder().ofCsvRecord(prepareTestFile("\"abc"), StandardCharsets.UTF_8)) {
+            CsvRecordAssert.assertThat(csv.readPage(0).getFirst()).fields().containsExactly("abc");
+        }
+    }
+
+    @Test
+    void allowUnclosedQuoteStrictThrows() throws IOException {
+        final var bldr = singlePageBuilder().allowUnclosedQuote(false);
+        try (var csv = bldr.ofCsvRecord(prepareTestFile("\"abc"), StandardCharsets.UTF_8)) {
+            assertThatThrownBy(() -> csv.readPage(0))
+                .isInstanceOf(CsvParseException.class)
+                .hasRootCauseInstanceOf(CsvParseException.class)
+                .hasRootCauseMessage("Unclosed quoted field at end of input (record starting at line 1)");
+        }
+    }
+
     private IndexedCsvReader<CsvRecord> buildSinglePage(final String data) throws IOException {
         return singlePageBuilder().ofCsvRecord(prepareTestFile(data));
     }

lib/src/main/java/de/siegmar/fastcsv/reader/CsvReader.java

@@ -440,6 +440,7 @@ public static final class CsvReaderBuilder {
         private FieldMismatchStrategy extraFieldStrategy = FieldMismatchStrategy.STRICT;
         private FieldMismatchStrategy missingFieldStrategy = FieldMismatchStrategy.STRICT;
         private boolean allowExtraCharsAfterClosingQuote;
+        private boolean allowUnclosedQuote = true;
         private boolean trimWhitespacesAroundQuotes;
         private boolean detectBomHeader;
         private int maxBufferSize = DEFAULT_MAX_BUFFER_SIZE;
@@ -605,6 +606,25 @@ public CsvReaderBuilder allowExtraCharsAfterClosingQuote(final boolean allowExtr
             return this;
         }
 
+        /// Defines whether input that ends inside a quoted field (EOF before a closing quote) is tolerated.
+        ///
+        /// Example: `"foo,bar`
+        ///
+        /// If this is set to `true`, the value `foo,bar` will be returned as a single field; otherwise,
+        /// a [CsvParseException] will be thrown.
+        ///
+        /// Independent of this flag, a [CsvParseException] is thrown if the unclosed region exceeds
+        /// [#maxBufferSize(int)].
+        ///
+        /// **The default will change to `false` in version 5.0.**
+        ///
+        /// @param allowUnclosedQuote allow input ending inside a quoted field (default: `true`).
+        /// @return This updated object, allowing additional method calls to be chained together.
+        public CsvReaderBuilder allowUnclosedQuote(final boolean allowUnclosedQuote) {
+            this.allowUnclosedQuote = allowUnclosedQuote;
+            return this;
+        }
+
         /// Defines whether whitespaces before an opening quote and after a closing quote should be allowed and trimmed.
         ///
         /// RFC 4180 does not allow whitespaces between the quotation mark and the field separator or
@@ -981,12 +1001,13 @@ public <T> CsvReader<T> build(final CsvCallbackHandler<T> callbackHandler, final
             final CsvParser csvParser;
             if (isRelaxedConfiguration()) {
                 csvParser = new RelaxedCsvParser(fieldSeparator, quoteCharacter, commentStrategy,
-                    commentCharacter, trimWhitespacesAroundQuotes, callbackHandler,
+                    commentCharacter, trimWhitespacesAroundQuotes, allowUnclosedQuote, callbackHandler,
                     maxBufferSize, reader
                 );
             } else {
                 csvParser = new StrictCsvParser(fieldSeparator.charAt(0), quoteCharacter, commentStrategy,
-                    commentCharacter, allowExtraCharsAfterClosingQuote, callbackHandler, maxBufferSize, reader);
+                    commentCharacter, allowExtraCharsAfterClosingQuote, allowUnclosedQuote,
+                    callbackHandler, maxBufferSize, reader);
             }
 
             return newReader(callbackHandler, csvParser);
@@ -1009,12 +1030,13 @@ public <T> CsvReader<T> build(final CsvCallbackHandler<T> callbackHandler, final
             final CsvParser csvParser;
             if (isRelaxedConfiguration()) {
                 csvParser = new RelaxedCsvParser(fieldSeparator, quoteCharacter, commentStrategy,
-                    commentCharacter, trimWhitespacesAroundQuotes, callbackHandler,
+                    commentCharacter, trimWhitespacesAroundQuotes, allowUnclosedQuote, callbackHandler,
                     maxBufferSize, data
                 );
             } else {
                 csvParser = new StrictCsvParser(fieldSeparator.charAt(0), quoteCharacter, commentStrategy,
-                    commentCharacter, allowExtraCharsAfterClosingQuote, callbackHandler, data);
+                    commentCharacter, allowExtraCharsAfterClosingQuote, allowUnclosedQuote,
+                    callbackHandler, data);
             }
 
             return newReader(callbackHandler, csvParser);
@@ -1092,6 +1114,7 @@ public String toString() {
                 .add("extraFieldStrategy=" + extraFieldStrategy)
                 .add("missingFieldStrategy=" + missingFieldStrategy)
                 .add("allowExtraCharsAfterClosingQuote=" + allowExtraCharsAfterClosingQuote)
+                .add("allowUnclosedQuote=" + allowUnclosedQuote)
                 .add("trimWhitespacesAroundQuotes=" + trimWhitespacesAroundQuotes)
                 .add("detectBomHeader=" + detectBomHeader)
                 .add("maxBufferSize=" + maxBufferSize)

lib/src/main/java/de/siegmar/fastcsv/reader/IndexedCsvReader.java

@@ -51,6 +51,7 @@ public final class IndexedCsvReader<T> implements Closeable {
     private final CommentStrategy commentStrategy;
     private final char commentCharacter;
     private final boolean allowExtraCharsAfterClosingQuote;
+    private final boolean allowUnclosedQuote;
     private final int pageSize;
     private final RandomAccessFile raf;
     private final Lock fileLock = new ReentrantLock();
@@ -63,6 +64,7 @@ public final class IndexedCsvReader<T> implements Closeable {
                      final char fieldSeparator, final char quoteCharacter,
                      final CommentStrategy commentStrategy, final char commentCharacter,
                      final boolean allowExtraCharsAfterClosingQuote,
+                     final boolean allowUnclosedQuote,
                      final int maxBufferSize,
                      final int pageSize,
                      final CsvCallbackHandler<T> csvRecordHandler,
@@ -78,6 +80,7 @@ public final class IndexedCsvReader<T> implements Closeable {
         this.commentStrategy = commentStrategy;
         this.commentCharacter = commentCharacter;
         this.allowExtraCharsAfterClosingQuote = allowExtraCharsAfterClosingQuote;
+        this.allowUnclosedQuote = allowUnclosedQuote;
         this.pageSize = pageSize;
         this.csvRecordHandler = csvRecordHandler;
 
@@ -103,7 +106,7 @@ public final class IndexedCsvReader<T> implements Closeable {
 
         raf = new RandomAccessFile(file.toFile(), "r");
         csvParser = new StrictCsvParser(fieldSeparator, quoteCharacter, commentStrategy, commentCharacter,
-            allowExtraCharsAfterClosingQuote, csvRecordHandler, maxBufferSize,
+            allowExtraCharsAfterClosingQuote, allowUnclosedQuote, csvRecordHandler, maxBufferSize,
             new InputStreamReader(new RandomAccessFileInputStream(raf), charset));
     }
 
@@ -260,6 +263,7 @@ public String toString() {
             .add("commentStrategy=" + commentStrategy)
             .add("commentCharacter=" + commentCharacter)
             .add("allowExtraCharsAfterClosingQuote=" + allowExtraCharsAfterClosingQuote)
+            .add("allowUnclosedQuote=" + allowUnclosedQuote)
             .add("pageSize=" + pageSize)
             .add("index=" + csvIndex)
             .toString();
@@ -291,6 +295,7 @@ public static final class IndexedCsvReaderBuilder {
         private CommentStrategy commentStrategy = CommentStrategy.NONE;
         private char commentCharacter = '#';
         private boolean allowExtraCharsAfterClosingQuote;
+        private boolean allowUnclosedQuote = true;
 
         @Nullable
         private StatusListener statusListener;
@@ -368,6 +373,25 @@ public IndexedCsvReaderBuilder allowExtraCharsAfterClosingQuote(
             return this;
         }
 
+        /// Defines whether input that ends inside a quoted field (EOF before a closing quote) is tolerated.
+        ///
+        /// Example: `"foo,bar`
+        ///
+        /// If this is set to `true`, the value `foo,bar` will be returned as a single field; otherwise,
+        /// a [CsvParseException] will be thrown.
+        ///
+        /// Independent of this flag, a [CsvParseException] is thrown if the unclosed region exceeds
+        /// [#maxBufferSize(int)].
+        ///
+        /// **The default will change to `false` in version 5.0.**
+        ///
+        /// @param allowUnclosedQuote allow input ending inside a quoted field (default: `true`).
+        /// @return This updated object, allowing additional method calls to be chained together.
+        public IndexedCsvReaderBuilder allowUnclosedQuote(final boolean allowUnclosedQuote) {
+            this.allowUnclosedQuote = allowUnclosedQuote;
+            return this;
+        }
+
         /// Sets the `statusListener` to listen for indexer status updates.
         ///
         /// @param statusListener the status listener.
@@ -502,8 +526,8 @@ public <T> IndexedCsvReader<T> build(final CsvCallbackHandler<T> callbackHandler
                 : new StatusListener() { };
 
             return new IndexedCsvReader<>(file, charset, fieldSeparator, quoteCharacter, commentStrategy,
-                commentCharacter, allowExtraCharsAfterClosingQuote, maxBufferSize, pageSize, callbackHandler,
-                csvIndex, sl);
+                commentCharacter, allowExtraCharsAfterClosingQuote, allowUnclosedQuote,
+                maxBufferSize, pageSize, callbackHandler, csvIndex, sl);
         }
 
     }

lib/src/main/java/de/siegmar/fastcsv/reader/RelaxedCsvParser.java

@@ -36,6 +36,7 @@ final class RelaxedCsvParser implements CsvParser {
     private final CommentStrategy cStrat;
     private final char cChar;
     private final boolean trimWhitespacesAroundQuotes;
+    private final boolean allowUnclosedQuote;
     private final CsvCallbackHandler<?> callbackHandler;
     private final int maxBufferSize;
     private final LookaheadReader reader;
@@ -48,6 +49,7 @@ final class RelaxedCsvParser implements CsvParser {
     RelaxedCsvParser(final String fsep, final char qChar,
                      final CommentStrategy cStrat, final char cChar,
                      final boolean trimWhitespacesAroundQuotes,
+                     final boolean allowUnclosedQuote,
                      final CsvCallbackHandler<?> callbackHandler,
                      final int maxBufferSize,
                      final Reader reader) {
@@ -59,6 +61,7 @@ final class RelaxedCsvParser implements CsvParser {
         this.cStrat = cStrat;
         this.cChar = cChar;
         this.trimWhitespacesAroundQuotes = trimWhitespacesAroundQuotes;
+        this.allowUnclosedQuote = allowUnclosedQuote;
         this.callbackHandler = callbackHandler;
         this.maxBufferSize = maxBufferSize;
         final int initialBufferSize = Math.min(maxBufferSize, DEFAULT_BUFFER_SIZE);
@@ -70,6 +73,7 @@ final class RelaxedCsvParser implements CsvParser {
     RelaxedCsvParser(final String fsep, final char qChar,
                      final CommentStrategy cStrat, final char cChar,
                      final boolean trimWhitespacesAroundQuotes,
+                     final boolean allowUnclosedQuote,
                      final CsvCallbackHandler<?> callbackHandler,
                      final int maxBufferSize,
                      final String data) {
@@ -81,6 +85,7 @@ final class RelaxedCsvParser implements CsvParser {
         this.cStrat = cStrat;
         this.cChar = cChar;
         this.trimWhitespacesAroundQuotes = trimWhitespacesAroundQuotes;
+        this.allowUnclosedQuote = allowUnclosedQuote;
         this.callbackHandler = callbackHandler;
         this.maxBufferSize = maxBufferSize;
         final int dataSize = Math.max(data.length(), 1);
@@ -214,7 +219,17 @@ private boolean parseQuoted() throws IOException {
         boolean endOfRecord = true;
 
         int ch;
-        OUTER: while ((ch = reader.read()) != EOF) {
+        OUTER: while (true) {
+            ch = reader.read();
+            if (ch == EOF) {
+                if (!allowUnclosedQuote) {
+                    throw new CsvParseException(
+                        "Unclosed quoted field at end of input (record starting at line %d)"
+                            .formatted(startingLineNumber));
+                }
+                break;
+            }
+
             // fast-forward
             while (currentFieldIndex < currentField.length && reader.len > reader.start
                 && ch != CR && ch != LF && ch != qChar) {