Add a better toString to _ClientSocketException (#948)

Author: brianquinlan

pkgs/http/CHANGELOG.md

@@ -1,3 +1,7 @@
+## 1.0.1
+
+* Add better error messages for `SocketException`s when using `IOClient`. 
+ 
 ## 1.0.0
 
 * Requires Dart 3.0 or later.

pkgs/http/lib/src/client.dart

@@ -25,6 +25,10 @@ import 'streamed_response.dart';
 /// [http.head], [http.get], [http.post], [http.put], [http.patch], or
 /// [http.delete] instead.
 ///
+/// All methods will emit a [ClientException] if there is a transport-level
+/// failure when communication with the server. For example, if the server could
+/// not be reached.
+///
 /// When creating an HTTP client class with additional functionality, you must
 /// extend [BaseClient] rather than [Client]. In most cases, you can wrap
 /// another instance of [Client] and add functionality on top of that. This

pkgs/http/lib/src/exception.dart

@@ -12,5 +12,11 @@ class ClientException implements Exception {
   ClientException(this.message, [this.uri]);
 
   @override
-  String toString() => message;
+  String toString() {
+    if (uri != null) {
+      return 'ClientException: $message, uri=$uri';
+    } else {
+      return 'ClientException: $message';
+    }
+  }
 }

pkgs/http/lib/src/io_client.dart

@@ -6,6 +6,7 @@ import 'dart:io';
 
 import 'base_client.dart';
 import 'base_request.dart';
+import 'client.dart';
 import 'exception.dart';
 import 'io_streamed_response.dart';
 
@@ -28,9 +29,9 @@ BaseClient createClient() {
 class _ClientSocketException extends ClientException
     implements SocketException {
   final SocketException cause;
-  _ClientSocketException(SocketException e, Uri url)
+  _ClientSocketException(SocketException e, Uri uri)
       : cause = e,
-        super(e.message, url);
+        super(e.message, uri);
 
   @override
   InternetAddress? get address => cause.address;
@@ -40,9 +41,33 @@ class _ClientSocketException extends ClientException
 
   @override
   int? get port => cause.port;
+
+  @override
+  String toString() => 'ClientException with $cause, uri=$uri';
 }
 
-/// A `dart:io`-based HTTP client.
+/// A `dart:io`-based HTTP [Client].
+///
+/// If there is a socket-level failure when communicating with the server
+/// (for example, if the server could not be reached), [IOClient] will emit a
+/// [ClientException] that also implements [SocketException]. This allows
+/// callers to get more detailed exception information for socket-level
+/// failures, if desired.
+///
+/// For example:
+/// ```dart
+/// final client = http.Client();
+/// late String data;
+/// try {
+///   data = await client.read(Uri.https('example.com', ''));
+/// } on SocketException catch (e) {
+///   // Exception is transport-related, check `e.osError` for more details.
+/// } on http.ClientException catch (e) {
+///   // Exception is HTTP-related (e.g. the server returned a 404 status code).
+///   // If the handler for `SocketException` were removed then all exceptions
+///   // would be caught by this handler.
+/// }
+/// ```
 class IOClient extends BaseClient {
   /// The underlying `dart:io` HTTP client.
   HttpClient? _inner;

pkgs/http/pubspec.yaml

@@ -1,5 +1,5 @@
 name: http
-version: 1.0.0
+version: 1.0.1-wip
 description: A composable, multi-platform, Future-based API for HTTP requests.
 repository: https://github.com/dart-lang/http/tree/master/pkgs/http
 

pkgs/http/test/io/client_test.dart

@@ -118,7 +118,15 @@ void main() {
     request.headers[HttpHeaders.contentTypeHeader] =
         'application/json; charset=utf-8';
 
-    expect(client.send(request), throwsA(isA<SocketException>()));
+    expect(
+        client.send(request),
+        throwsA(allOf(
+            isA<http.ClientException>().having((e) => e.uri, 'uri', url),
+            isA<SocketException>().having(
+                (e) => e.toString(),
+                'SocketException.toString',
+                matches('ClientException with SocketException.*,'
+                    ' uri=http://http.invalid')))));
 
     request.sink.add('{"hello": "world"}'.codeUnits);
     request.sink.close();