Merge upstream v2.16.0

CHANGELOG.md

@@ -1,4 +1,12 @@
-## [2.15.0] - 2026-03-30
+## [2.16.0] - 2026-03-24
+- **BREAKING**: Changed `SSHChannelController.sendEnv()` from `void` to `Future<bool>` to properly await environment variable setup responses and avoid race conditions with PTY requests [#102]. Thanks [@itzhoujun] and [@vicajilau].
+- Clarified shell stdio wiring for CLI-only usage and guarded `example/shell.dart` against missing local terminal handles (for example GUI-launched Windows `.exe`) [#121]. Thanks [@bradmartin333] and [@vicajilau].
+- Added support for parsing legacy unencrypted `EC PRIVATE KEY` PEM format in `SSHKeyPair.fromPem` [#109]. Thanks [@jooy2] and [@vicajilau].
+- Added `SSHClient.runWithResult()` to expose command output together with `exitCode` and `exitSignal` while keeping `run()` as a convenience API [#99]. Thanks [@falrom] and [@vicajilau].
+- Added non-breaking high-level SFTP `download()` / `downloadTo()` APIs and read pipeline tuning knobs (`chunkSize`, `maxPendingRequests`) for improved large-file throughput while preserving stream compatibility [#124]. Thanks [@vicajilau].
+- Made SFTP directory/file name parsing tolerant to malformed UTF-8 bytes to avoid `FormatException` on non-UTF-8 server filenames [#95]. Thanks [@vicajilau].
+
+## [2.15.0] - 2026-03-20
 - Updated `pointycastle` dependency to `^4.0.0` [#131]. Thanks [@vicajilau].
 - Added foundational X11 forwarding support with session x11-req API, incoming x11 channel handling, and protocol tests [#1]. Thanks [@vicajilau].
 - Exposed SSH ident configuration from `SSHClient` [#135]. Thanks [@Remulic] and [@vicajilau].
@@ -188,6 +196,12 @@
 [#145]: https://github.com/TerminalStudio/dartssh2/pull/145
 [#141]: https://github.com/TerminalStudio/dartssh2/pull/141
 [#140]: https://github.com/TerminalStudio/dartssh2/pull/140
+[#102]: https://github.com/TerminalStudio/dartssh2/issues/102
+[#99]: https://github.com/TerminalStudio/dartssh2/issues/99
+[#109]: https://github.com/TerminalStudio/dartssh2/issues/109
+[#121]: https://github.com/TerminalStudio/dartssh2/issues/121
+[#124]: https://github.com/TerminalStudio/dartssh2/issues/124
+[#95]: https://github.com/TerminalStudio/dartssh2/issues/95
 [#139]: https://github.com/TerminalStudio/dartssh2/pull/139
 [#133]: https://github.com/TerminalStudio/dartssh2/pull/133
 [#132]: https://github.com/TerminalStudio/dartssh2/pull/132
@@ -219,7 +233,9 @@
 [@alexander-irion]: https://github.com/alexander-irion
 [@Remulic]: https://github.com/Remulic
 [@james-thorpe]: https://github.com/james-thorpe
+[@itzhoujun]: https://github.com/itzhoujun
+[@jooy2]: https://github.com/jooy2
+[@falrom]: https://github.com/falrom
+[@bradmartin333]: https://github.com/bradmartin333
 [@Wackymax]: https://github.com/Wackymax
 [@vicajilau]: https://github.com/vicajilau
-[@shihuili1218]: https://github.com/shihuili1218
-[@isegal]: https://github.com/isegal

README.md

@@ -119,6 +119,18 @@ void main() async {
 
 > `SSHSocket` is an interface and it's possible to implement your own `SSHSocket` if you want to use a different underlying transport rather than standard TCP socket. For example WebSocket or Unix domain socket.
 
+### Web support
+
+Direct native TCP sockets are not available in browsers, so this will fail on
+Flutter Web / Dart Web:
+
+```dart
+await SSHSocket.connect('host', 22);
+```
+
+For web apps, use a custom `SSHSocket` transport over a browser-supported
+channel (for example, a WebSocket tunnel/proxy to your SSH endpoint).
+
 ### Customize client SSH identification
 
 If your jump host or SSH gateway restricts client versions, you can customize the
@@ -142,15 +154,25 @@ void main() async {
 ```dart
 void main() async {
   final shell = await client.shell();
-  stdout.addStream(shell.stdout); // listening for stdout
-  stderr.addStream(shell.stderr); // listening for stderr
-  stdin.cast<Uint8List>().listen(shell.write); // writing to stdin
+
+  // Attach local terminal streams only when a terminal is available.
+  // GUI apps on Windows may not have stdin/stdout/stderr attached.
+  final hasTerminal = stdin.hasTerminal && stdout.hasTerminal && stderr.hasTerminal;
+  if (hasTerminal) {
+    stdout.addStream(shell.stdout); // listening for stdout
+    stderr.addStream(shell.stderr); // listening for stderr
+    stdin.cast<Uint8List>().listen(shell.write); // writing to stdin
+  }
 
   await shell.done; // wait for shell to exit
   client.close();
 }
 ```
 
+> Note: The stdin/stdout bridging above is for CLI apps. If your app is launched
+> without a terminal (for example, double-clicking a Windows `.exe`), skip the
+> local stdio wiring and use your own UI/input pipeline.
+
 ### Execute a command on remote host
 
 
@@ -169,7 +191,51 @@ void main() async {
 }
 ```
 
-> `client.run()` is a convenience method that wraps `client.execute()` for running non-interactive commands.
+> `client.run()` is a convenience method that returns combined output bytes.
+> Use `client.runWithResult()` when you need separate `stdout` / `stderr`
+> streams and command exit metadata (`exitCode` / `exitSignal`).
+
+To also access command exit metadata:
+
+```dart
+void main() async {
+  final result = await client.runWithResult('echo hello');
+  print('exitCode: ${result.exitCode}');
+  print('stdout: ${utf8.decode(result.stdout)}');
+  print('stderr: ${utf8.decode(result.stderr)}');
+}
+```
+
+### End-to-end flow example
+
+Use `example/run_flows.dart` to test the main execution flows in one run:
+
+- `run()`
+- `runWithResult()`
+- `execute()`
+- optional `shell()` via `--shell`
+
+Run it with environment variables:
+
+```sh
+SSH_HOST=test.rebex.net SSH_PORT=22 SSH_USERNAME=demo SSH_PASSWORD=password dart run example/run_flows.dart
+```
+
+Run shell flow too:
+
+```sh
+SSH_HOST=test.rebex.net SSH_PORT=22 SSH_USERNAME=demo SSH_PASSWORD=password dart run example/run_flows.dart --shell
+```
+
+On Windows PowerShell:
+
+```powershell
+$env:SSH_HOST = 'test.rebex.net'
+$env:SSH_PORT = '22'
+$env:SSH_USERNAME = 'demo'
+$env:SSH_PASSWORD = 'password'
+dart run example/run_flows.dart --shell
+```
 
 ### Start a process on remote host
 ```dart
@@ -324,6 +390,71 @@ void main() async {
 }
 ```
 
+### Download remote file (high-level API)
+```dart
+void main() async {
+  final sftp = await client.sftp();
+  final output = File('local_file.txt').openWrite();
+
+  final bytes = await sftp.download(
+    '/remote/file.txt',
+    output,
+    onProgress: (bytesRead) => print('downloaded: $bytesRead bytes'),
+    closeDestination: true,
+  );
+
+  print('download complete: $bytes bytes');
+}
+```
+
+`download()` and `downloadTo()` are opt-in convenience APIs built on top of the
+existing stream-based behavior, so existing code remains fully compatible.
+
+When to use each API:
+
+- Use `sftp.download(path, sink)` when you only have a remote path and want the
+  simplest one-liner flow. It opens and closes the remote file for you.
+- Use `file.downloadTo(sink)` when you already have an open `SftpFile` (for
+  example you want partial downloads with `offset`/`length` or want to reuse the
+  same handle).
+
+```dart
+void main() async {
+  final sftp = await client.sftp();
+  final file = await sftp.open('/remote/file.txt');
+  final output = File('local_partial.bin').openWrite();
+
+  try {
+    // Download bytes [1024, 1024 + 4096) using an existing open handle.
+    await file.downloadTo(
+      output,
+      offset: 1024,
+      length: 4096,
+      closeDestination: true,
+    );
+  } finally {
+    await file.close();
+  }
+}
+```
+
+For high-latency links or large files, you can tune pipelining:
+
+```dart
+void main() async {
+  final sftp = await client.sftp();
+  final output = File('local_file.txt').openWrite();
+
+  await sftp.download(
+    '/remote/file.txt',
+    output,
+    chunkSize: 64 * 1024,
+    maxPendingRequests: 128,
+    closeDestination: true,
+  );
+}
+```
+
 ### Write remote file
 ```dart
 void main() async {

example/run_flows.dart

@@ -0,0 +1,102 @@
+import 'dart:convert';
+import 'dart:io';
+import 'dart:typed_data';
+
+import 'package:dartssh2/dartssh2.dart';
+
+Future<Uint8List> _collectBytes(Stream<Uint8List> stream) async {
+  final builder = BytesBuilder(copy: false);
+  await for (final chunk in stream) {
+    builder.add(chunk);
+  }
+  return builder.takeBytes();
+}
+
+Future<void> main(List<String> args) async {
+  final host = Platform.environment['SSH_HOST'] ?? 'localhost';
+  final port = int.tryParse(Platform.environment['SSH_PORT'] ?? '') ?? 22;
+  final username = Platform.environment['SSH_USERNAME'] ?? 'root';
+
+  final runShellDemo = args.contains('--shell');
+
+  final client = SSHClient(
+    await SSHSocket.connect(host, port),
+    username: username,
+    onPasswordRequest: () {
+      final envPassword = Platform.environment['SSH_PASSWORD'];
+      if (envPassword != null) {
+        return envPassword;
+      }
+
+      if (!stdin.hasTerminal || !stdout.hasTerminal) {
+        throw StateError(
+          'No terminal attached. Set SSH_PASSWORD environment variable.',
+        );
+      }
+
+      stdout.write('Password for $username@$host:$port: ');
+      try {
+        stdin.echoMode = false;
+        final password = stdin.readLineSync();
+        if (password == null || password.isEmpty) {
+          throw StateError('Empty password');
+        }
+        return password;
+      } finally {
+        stdin.echoMode = true;
+        stdout.writeln();
+      }
+    },
+  );
+
+  try {
+    // 1) Convenience run() for simple command output.
+    final runOutput = await client.run('echo run-ok');
+    stdout.writeln('[run] output: ${utf8.decode(runOutput).trim()}');
+
+    // 2) runWithResult() with exit metadata.
+    final runResult = await client.runWithResult(
+      'sh -lc "echo runWithResult-out; echo runWithResult-err 1>&2; exit 7"',
+    );
+    stdout.writeln('[runWithResult] exitCode: ${runResult.exitCode}');
+    stdout.writeln('[runWithResult] stdout: ${utf8.decode(runResult.stdout)}');
+    stdout.writeln('[runWithResult] stderr: ${utf8.decode(runResult.stderr)}');
+
+    // 3) execute() for lower-level session control.
+    final session = await client.execute('echo execute-ok');
+    final executeStdoutFuture = _collectBytes(session.stdout);
+    final executeStderrFuture = _collectBytes(session.stderr);
+    await session.done;
+    final executeStdout = await executeStdoutFuture;
+    final executeStderr = await executeStderrFuture;
+    stdout.writeln('[execute] exitCode: ${session.exitCode}');
+    stdout.writeln('[execute] stdout: ${utf8.decode(executeStdout).trim()}');
+    if (executeStderr.isNotEmpty) {
+      stdout.writeln('[execute] stderr: ${utf8.decode(executeStderr).trim()}');
+    }
+
+    // 4) Optional shell flow for interactive/pty scenarios.
+    if (runShellDemo) {
+      final shell = await client.shell(pty: const SSHPtyConfig());
+      final shellStdoutFuture = _collectBytes(shell.stdout);
+      final shellStderrFuture = _collectBytes(shell.stderr);
+
+      shell.write(Uint8List.fromList('echo shell-ok; exit\n'.codeUnits));
+      await shell.stdin.close();
+      await shell.done;
+
+      final shellStdout = await shellStdoutFuture;
+      final shellStderr = await shellStderrFuture;
+      stdout.writeln('[shell] exitCode: ${shell.exitCode}');
+      stdout.writeln('[shell] stdout: ${utf8.decode(shellStdout).trim()}');
+      if (shellStderr.isNotEmpty) {
+        stdout.writeln('[shell] stderr: ${utf8.decode(shellStderr).trim()}');
+      }
+    } else {
+      stdout.writeln('Shell flow skipped. Use --shell to run it.');
+    }
+  } finally {
+    client.close();
+    await client.done;
+  }
+}

example/shell.dart

@@ -4,6 +4,13 @@ import 'dart:typed_data';
 import 'package:dartssh2/dartssh2.dart';
 
 void main(List<String> args) async {
+  final hasTerminal =
+      stdin.hasTerminal && stdout.hasTerminal && stderr.hasTerminal;
+  if (!hasTerminal) {
+    stderr.writeln('No terminal attached. Exiting.');
+    exit(1);
+  }
+
   final socket = await SSHSocket.connect('localhost', 22);
 
   final client = SSHClient(
@@ -17,6 +24,7 @@ void main(List<String> args) async {
   );
 
   final shell = await client.shell();
+
   stdout.addStream(shell.stdout);
   stderr.addStream(shell.stderr);
   stdin.cast<Uint8List>().listen(shell.write);

lib/src/message/base.dart

@@ -109,8 +109,8 @@ class SSHMessageReader {
     return value;
   }
 
-  String readUtf8() {
-    return utf8.decode(readString());
+  String readUtf8({bool allowMalformed = false}) {
+    return utf8.decode(readString(), allowMalformed: allowMalformed);
   }
 
   List<String> readNameList() {

lib/src/message/msg_channel.dart

@@ -606,7 +606,7 @@ class SSH_Message_Channel_Request implements SSHMessage {
   final bool? singleConnection;
   final String? x11AuthenticationProtocol;
   final String? x11AuthenticationCookie;
-  final String? x11ScreenNumber;
+  final int? x11ScreenNumber;
 
   /// "env" request specific data
   final String? variableName;
@@ -687,7 +687,7 @@ class SSH_Message_Channel_Request implements SSHMessage {
     bool singleConnection = false,
     required String x11AuthenticationProtocol,
     required String x11AuthenticationCookie,
-    required String x11ScreenNumber,
+    required int x11ScreenNumber,
   }) {
     return SSH_Message_Channel_Request(
       recipientChannel: recipientChannel,
@@ -849,7 +849,7 @@ class SSH_Message_Channel_Request implements SSHMessage {
         final singleConnection = reader.readBool();
         final x11AuthenticationProtocol = reader.readUtf8();
         final x11AuthenticationCookie = reader.readUtf8();
-        final x11ScreenNumber = reader.readUtf8();
+        final x11ScreenNumber = reader.readUint32();
         return SSH_Message_Channel_Request(
           recipientChannel: recipientChannel,
           requestType: requestType,
@@ -953,7 +953,7 @@ class SSH_Message_Channel_Request implements SSHMessage {
         writer.writeBool(singleConnection!);
         writer.writeUtf8(x11AuthenticationProtocol!);
         writer.writeUtf8(x11AuthenticationCookie!);
-        writer.writeUtf8(x11ScreenNumber!);
+        writer.writeUint32(x11ScreenNumber!);
         break;
       case 'env':
         writer.writeUtf8(variableName!);