feat(google_cloud): expand BadRequestException for AIP-193 compliance (#226)

Expand BadRequestException with status and details fields, and add
toJson() for standard JSON error reporting.

Update badRequestMiddleware to leverage toJson() and update tests and
changelog.

Author: kevmoo

pkgs/google_cloud/CHANGELOG.md

@@ -1,3 +1,26 @@
+## 0.4.1-wip
+
+### `bad_request_exception.dart`
+
+- Expanded `BadRequestException` to support structured error reporting as
+  per AIP-193.
+  - Added `status` (`String?`) and `details` (`List<Map<String, Object?>>?`)
+    fields.
+  - Added `toJson()` method to serialize the error into a standard Google Cloud
+    error payload.
+  - Updated `toString()` to include `status` and `details` when non-null.
+  - Added factory constructors for common HTTP 4XX status codes: `badRequest`
+    (400), `unauthorized` (401), `forbidden` (403), `notFound` (404),
+    `conflict` (409), and `tooManyRequests` (429).
+  - Added default `status` values for factories that map 1:1 to gRPC status
+    codes (e.g., `unauthorized` defaults to `'UNAUTHENTICATED'`).
+
+### `http_serving.dart` (and internal files)
+
+- Updated `badRequestMiddleware` to leverage `BadRequestException.toJson()` for
+  JSON responses, returning a standard Google Cloud error payload.
+- Updated plain text errors to use `BadRequestException.toString()`.
+
 ## 0.4.0
 
 ### `constants.dart`

pkgs/google_cloud/lib/src/serving/bad_request_exception.dart

@@ -27,16 +27,37 @@ import 'http_logging.dart';
 /// debugging information which is included in logs, but not sent to the
 /// requester.
 class BadRequestException implements Exception {
+  /// The HTTP status code for the response.
+  ///
+  /// Must be between 400 and 499.
   final int statusCode;
+
+  /// The message sent to the requester.
   final String message;
+
+  /// The error that caused this exception.
   final Object? innerError;
+
+  /// The stack trace of the error that caused this exception.
   final StackTrace? innerStack;
 
+  /// An explicit error status string (e.g., `INVALID_ARGUMENT`).
+  ///
+  /// See https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto
+  final String? status;
+
+  /// Structured error details.
+  ///
+  /// See https://google.aip.dev/193#statusdetails
+  final List<Map<String, Object?>>? details;
+
   BadRequestException(
     this.statusCode,
     this.message, {
     this.innerError,
     this.innerStack,
+    this.status,
+    this.details,
   }) : assert(message.isNotEmpty) {
     if (statusCode < 400 || statusCode > 499) {
       throw ArgumentError.value(
@@ -47,6 +68,143 @@ class BadRequestException implements Exception {
     }
   }
 
+  /// Creates a new [BadRequestException] with status code 400.
+  factory BadRequestException.badRequest(
+    String message, {
+    Object? innerError,
+    StackTrace? innerStack,
+    String? status,
+    List<Map<String, Object?>>? details,
+  }) => BadRequestException(
+    400,
+    message,
+    innerError: innerError,
+    innerStack: innerStack,
+    status: status,
+    details: details,
+  );
+
+  /// Creates a new [BadRequestException] with status code 401.
+  ///
+  /// The request does not have valid authentication credentials for the
+  /// operation.
+  factory BadRequestException.unauthorized(
+    String message, {
+    Object? innerError,
+    StackTrace? innerStack,
+    String? status = 'UNAUTHENTICATED',
+    List<Map<String, Object?>>? details,
+  }) => BadRequestException(
+    401,
+    message,
+    innerError: innerError,
+    innerStack: innerStack,
+    status: status,
+    details: details,
+  );
+
+  /// Creates a new [BadRequestException] with status code 403.
+  ///
+  /// The caller does not have permission to execute the specified
+  /// operation. `PERMISSION_DENIED` must not be used for rejections
+  /// caused by exhausting some resource (use `RESOURCE_EXHAUSTED`
+  /// instead for those errors). `PERMISSION_DENIED` must not be
+  /// used if the caller can not be identified (use `UNAUTHENTICATED`
+  /// instead for those errors). This error code does not imply the
+  /// request is valid or the requested entity exists or satisfies
+  /// other pre-conditions.
+  factory BadRequestException.forbidden(
+    String message, {
+    Object? innerError,
+    StackTrace? innerStack,
+    String? status = 'PERMISSION_DENIED',
+    List<Map<String, Object?>>? details,
+  }) => BadRequestException(
+    403,
+    message,
+    innerError: innerError,
+    innerStack: innerStack,
+    status: status,
+    details: details,
+  );
+
+  /// Creates a new [BadRequestException] with status code 404.
+  ///
+  /// Some requested entity (e.g., file or directory) was not found.
+  ///
+  /// Note to server developers: if a request is denied for an entire class
+  /// of users, such as gradual feature rollout or undocumented allowlist,
+  /// `NOT_FOUND` may be used. If a request is denied for some users within
+  /// a class of users, such as user-based access control, `PERMISSION_DENIED`
+  /// must be used.
+  factory BadRequestException.notFound(
+    String message, {
+    Object? innerError,
+    StackTrace? innerStack,
+    String? status = 'NOT_FOUND',
+    List<Map<String, Object?>>? details,
+  }) => BadRequestException(
+    404,
+    message,
+    innerError: innerError,
+    innerStack: innerStack,
+    status: status,
+    details: details,
+  );
+
+  /// Creates a new [BadRequestException] with status code 409.
+  factory BadRequestException.conflict(
+    String message, {
+    Object? innerError,
+    StackTrace? innerStack,
+    String? status,
+    List<Map<String, Object?>>? details,
+  }) => BadRequestException(
+    409,
+    message,
+    innerError: innerError,
+    innerStack: innerStack,
+    status: status,
+    details: details,
+  );
+
+  /// Creates a new [BadRequestException] with status code 429.
+  ///
+  /// Some resource has been exhausted, perhaps a per-user quota, or
+  /// perhaps the entire file system is out of space.
+  factory BadRequestException.tooManyRequests(
+    String message, {
+    Object? innerError,
+    StackTrace? innerStack,
+    String? status = 'RESOURCE_EXHAUSTED',
+    List<Map<String, Object?>>? details,
+  }) => BadRequestException(
+    429,
+    message,
+    innerError: innerError,
+    innerStack: innerStack,
+    status: status,
+    details: details,
+  );
+
   @override
-  String toString() => '$message ($statusCode)';
+  String toString() {
+    final buffer = StringBuffer('$message ($statusCode)');
+    if (status != null && status!.isNotEmpty) buffer.write(' [$status]');
+    if (details != null && details!.isNotEmpty) {
+      buffer.write(' Details: $details');
+    }
+    return buffer.toString();
+  }
+
+  /// Returns a JSON representation of the error, suitable for including in a
+  /// response body.
+  Map<String, Object?> toJson() => {
+    'error': {
+      'code': statusCode,
+      'message': message,
+      if (status != null && status!.isNotEmpty) 'status': status,
+      if (details != null && details!.isNotEmpty) 'details': details,
+    },
+  };
 }

pkgs/google_cloud/lib/src/serving/http_logging.dart

@@ -52,7 +52,7 @@ Handler _handleBadRequest(Handler innerHandler) => (request) async {
     final response = await innerHandler(request);
     return response;
   } on BadRequestException catch (error, stack) {
-    return _responseFromBadRequest(error, stack);
+    return _responseFromBadRequest(error, stack, request.headers);
   }
 };
 
@@ -80,15 +80,40 @@ Handler _errorWriter(Handler innerHandler) => (request) async {
   return response;
 };
 
-Response _responseFromBadRequest(BadRequestException e, StackTrace stack) =>
-    Response(
+Response _responseFromBadRequest(
+  BadRequestException e,
+  StackTrace stack, [
+  Map<String, String>? requestHeaders,
+]) {
+  if (_isJsonRequest(requestHeaders)) {
+    return Response(
       e.statusCode,
-      body: 'Bad request. ${e.message}',
+      body: jsonEncode(e.toJson()),
+      headers: {HttpHeaders.contentTypeHeader: _jsonMimeType},
       context: {
         _badRequestExceptionContextKey: e,
         _badStackTraceContextKey: stack,
       },
     );
+  }
+
+  return Response(
+    e.statusCode,
+    body: e.toString(),
+    context: {
+      _badRequestExceptionContextKey: e,
+      _badStackTraceContextKey: stack,
+    },
+  );
+}
+
+const _jsonMimeType = 'application/json';
+
+bool _isJsonRequest(Map<String, String>? headers) {
+  final accept = headers?[HttpHeaders.acceptHeader] ?? '';
+  final contentType = headers?[HttpHeaders.contentTypeHeader] ?? '';
+  return accept.contains(_jsonMimeType) || contentType.contains(_jsonMimeType);
+}
 
 /// Return [Middleware] that logs errors using Google Cloud structured logs and
 /// returns the correct response.
@@ -159,7 +184,7 @@ Middleware cloudLoggingMiddleware(String projectId) {
               }
 
               final response = error is BadRequestException
-                  ? _responseFromBadRequest(error, stackTrace)
+                  ? _responseFromBadRequest(error, stackTrace, request.headers)
                   : Response.internalServerError();
 
               completer.complete(response);

pkgs/google_cloud/test/logging_test.dart

@@ -238,10 +238,87 @@ void main() {
       expect(response.statusCode, 400);
       expect(
         await response.readAsString(),
-        contains('Bad request. Custom bad request'),
+        contains('Custom bad request (400)'), // toString() output
       );
     });
 
+    test('badRequestMiddleware handles BadRequestException (JSON)', () async {
+      final handler = const Pipeline()
+          .addMiddleware(badRequestMiddleware)
+          .addHandler((request) {
+            throw BadRequestException(400, 'Custom bad request');
+          });
+
+      final response = await handler(
+        Request(
+          'GET',
+          Uri.parse('http://localhost/'),
+          headers: {'Accept': 'application/json'},
+        ),
+      );
+      expect(response.statusCode, 400);
+      expect(
+        response.headers[HttpHeaders.contentTypeHeader],
+        contains('application/json'),
+      );
+
+      final body = await response.readAsString();
+      final json = jsonDecode(body) as Map<String, dynamic>;
+      expect(json, {
+        'error': {'code': 400, 'message': 'Custom bad request'},
+      });
+    });
+
+    test('skips empty details in toJson', () {
+      final e1 = BadRequestException(400, 'Custom bad request');
+      expect(e1.toJson()['error'], {
+        'code': 400,
+        'message': 'Custom bad request',
+      });
+
+      final e2 = BadRequestException(400, 'Custom bad request', details: []);
+      expect(e2.toJson()['error'], {
+        'code': 400,
+        'message': 'Custom bad request',
+      });
+    });
+
+    test('badRequestMiddleware handles expanded BadRequestException', () async {
+      final handler = const Pipeline()
+          .addMiddleware(badRequestMiddleware)
+          .addHandler((request) {
+            throw BadRequestException.badRequest(
+              'Custom bad request',
+              status: 'INVALID_ARGUMENT',
+              details: [
+                {'field': 'name', 'message': 'required'},
+              ],
+            );
+          });
+
+      final response = await handler(
+        Request(
+          'GET',
+          Uri.parse('http://localhost/'),
+          headers: {'Accept': 'application/json'},
+        ),
+      );
+      expect(response.statusCode, 400);
+
+      final body = await response.readAsString();
+      final json = jsonDecode(body) as Map<String, dynamic>;
+      expect(json, {
+        'error': {
+          'code': 400,
+          'message': 'Custom bad request',
+          'status': 'INVALID_ARGUMENT',
+          'details': [
+            {'field': 'name', 'message': 'required'},
+          ],
+        },
+      });
+    });
+
     test('badRequestMiddleware logs to stderr', () async {
       final stderrLines = <String>[];
       final handler = const Pipeline()