Fix #1575: Enforce terminal closure - prevent use-after-close bugs (v4)

[gnodet]

Summary

Fixes #1575 by implementing strict terminal closure enforcement in JLine 4.x. After a terminal is closed, all attempts to access its streams (reader, writer, input, output) will throw exceptions, preventing use-after-close bugs.

Problem

As reported in #1575, terminals could still be used after calling close(), leading to unexpected behavior:

Terminal terminal = TerminalBuilder.terminal();
terminal.writer().println("foo");
terminal.close();

// This should fail but didn't:
terminal.writer().println("still works!"); // ❌ Should throw

Solution

Implemented two-level closure enforcement:

1. Terminal-Level Checks

• Added closed flag to AbstractTerminal
• Added checkClosed() method that throws IllegalStateException
• All terminal accessor methods (reader(), writer(), input(), output(), getAttributes(), setAttributes(), getSize(), setSize()) now check if terminal is closed
• Prevents accessing terminal methods after closure

2. Stream-Level Checks

• Added closed flag and checkClosed() to NonBlockingInputStream and NonBlockingReader
• Stream operations throw ClosedException when accessed after closure
• Prevents using held stream references after terminal closure

Behavior in JLine 4.x (This PR)

Strict mode by default - accessing closed terminals or streams throws exceptions:

Terminal terminal = TerminalBuilder.terminal();
PrintWriter writer = terminal.writer();
terminal.close();

// Both throw exceptions:
terminal.writer().println("test");  // ✓ Throws IllegalStateException
writer.println("test");              // ✓ Throws ClosedException

Optional soft mode - set -Djline.terminal.strictClose=false to log warnings instead of throwing (for backward compatibility during migration).

Changes

Core Implementation

AbstractTerminal.java

• Added protected volatile boolean closed field
• Added checkClosed() method
• Set closed = true in doClose()

Terminal Implementations (7 files)

• AbstractPosixTerminal.java - Added checks to 4 methods
• AbstractWindowsTerminal.java - Added checks to 7 methods
• DumbTerminal.java - Added checks to 8 methods + proper doClose()
• LineDisciplineTerminal.java - Added checks to 8 methods + fixed close order
• PosixPtyTerminal.java - Added checks to 4 methods + removed wrapper class
• PosixSysTerminal.java - Added checks to 4 methods + close input stream
• AbstractPty.java - Added check to PtyInputStream.read()

NonBlocking Stream Classes

• NonBlockingInputStream.java - Added closed flag, checkClosed(), close() method
• NonBlockingReader.java - Added closed flag, checkClosed(), close() method
• NonBlockingInputStreamImpl.java - Call checkClosed() in read()
• NonBlockingReaderImpl.java - Call checkClosed() in read()
• NonBlockingPumpInputStream.java - Use base class closed field
• NonBlockingPumpReader.java - Use base class closed field

Tests

StrictCloseTest.java (new)

• Tests that held stream references throw ClosedException in strict mode (default)
• Covers reader, input stream, and different terminal types

HeldStreamReferenceTest.java (new)

• Tests soft close mode behavior (requires -Djline.terminal.strictClose=false)
• Verifies warnings are logged instead of throwing

StreamClosureDemonstration.java (new)

• Runnable demonstration of the new behavior
• Shows both correct usage and held reference scenarios

Code Quality Improvements

As part of this fix, also refactored repeated code:

• Replaced 35 inline if (closed) checks with calls to checkClosed()
• Centralized error handling logic
• Net reduction of 59 lines of code

Statistics

• 17 files changed
• 607 additions(+)
• 35 deletions(-)

Breaking Changes

⚠️ JLine 4.x: This is a breaking change from JLine 3.x behavior. Applications that rely on using terminals after closure will need to be updated.

Migration path: Set -Djline.terminal.strictClose=false temporarily to identify issues via warnings, then fix the code to properly manage terminal lifecycle.

Testing

Run the demonstration:

java -cp terminal/target/classes org.jline.terminal.impl.StreamClosureDemonstration

Run strict mode tests:

mvn test -Dtest=StrictCloseTest

Run soft mode tests:

mvn test -Dtest=HeldStreamReferenceTest -Djline.terminal.strictClose=false

Related

• Fixes Question about Terminal close behavior #1575
• Companion PR Fix #1575: Enforce terminal closure with backward compatibility (v3) #1577 for v3 branch (backward compatible version)

[augmentcode]

🤖 Augment PR Summary

Summary: Tightens JLine 4.x terminal lifecycle enforcement to prevent use-after-close by making closed terminals/streams fail fast (with an optional compatibility mode).

Changes:

• Adds TerminalBuilder.PROP_STRICT_CLOSE and introduces a closed flag + checkClosed() in AbstractTerminal.
• Guards common terminal operations (stream accessors, attributes, sizing) in multiple terminal implementations (POSIX, Windows, dumb, line-discipline) once closed.
• Extends NonBlockingInputStream / NonBlockingReader with close-state tracking and checkClosed().
• Implements strict-by-default semantics (throw ClosedException) with a soft-close mode that logs warnings for migration.
• Updates NonBlocking pump/adapter implementations to respect the new close checks.
• Adds tests and a small demo program to illustrate strict vs soft close behavior and held-reference behavior.

Technical Notes: Soft-close behavior is controlled by -Djline.terminal.strictClose=false and is evaluated when non-blocking stream/reader instances are constructed.

_{🤖 Was this summary useful? React with 👍 or 👎}

[augmentcode]

Review completed. 5 suggestions posted.

Comment augment review to trigger a new review at any time.

[gnodet]

augment review

[augmentcode]

Review completed. 6 suggestions posted.

Comment augment review to trigger a new review at any time.