chore(smithy,3.0): Simplify serialization

Makes serialization more statically typed. Reduces conflation of Input and InputPayload types. And makes the serialization pipeline more clear overall by tightening API definitions.

Author: Dillon Nys

packages/smithy/goldens/tool/generate.dart

@@ -248,8 +248,8 @@ include: package:lints/recommended.yaml
 analyzer:
   errors:
     avoid_unused_constructor_parameters: ignore
+    deprecated_member_use_from_same_package: ignore
     non_constant_identifier_names: ignore
-    prefer_interpolation_to_compose_strings: ignore
 ''');
 
   // Create mono_pkg for testing

packages/smithy/smithy/lib/src/http/http_operation.dart

@@ -61,10 +61,7 @@ abstract class HttpOperation<InputPayload, Input, OutputPayload, Output>
   /// Builds the output from the [payload] and metadata from the HTTP
   /// [response].
   Output buildOutput(
-    // This is (kind of) a hack to allow `OutputPayload` to always be non-null
-    // even if the payload type is nullable. We need the non-null version to
-    // interop with built_value correctly.
-    covariant Object? payload,
+    OutputPayload payload,
     AWSBaseHttpResponse response,
   );
 
@@ -171,7 +168,7 @@ abstract class HttpOperation<InputPayload, Input, OutputPayload, Output>
       ...request.queryParameters.asMap(),
       ...uri.queryParametersAll,
     };
-    final body = protocol.serialize(input, specifiedType: FullType(Input));
+    final body = protocol.serialize(input);
 
     final awsRequest = AWSStreamedHttpRequest.raw(
       method: AWSHttpMethod.fromString(request.method),
@@ -270,10 +267,7 @@ abstract class HttpOperation<InputPayload, Input, OutputPayload, Output>
     StackTrace? stackTrace;
     var successCode = this.successCode();
     try {
-      final payload = await protocol.deserialize(
-        response.split(),
-        specifiedType: FullType(OutputPayload),
-      );
+      final payload = await protocol.deserialize(response.split());
       output = switch (payload) {
         Output _ => payload,
         _ => buildOutput(payload, response),
@@ -300,8 +294,9 @@ abstract class HttpOperation<InputPayload, Input, OutputPayload, Output>
         smithyError =
             errorTypes.firstWhereOrNull((t) => t.shapeId.shape == resolvedType);
       }
-      smithyError ??= errorTypes
-          .singleWhereOrNull((t) => t.statusCode == response.statusCode);
+      smithyError ??= errorTypes.singleWhereOrNull(
+        (t) => t.statusCode == response.statusCode,
+      );
       if (smithyError == null) {
         throw SmithyHttpException(
           statusCode: response.statusCode,
@@ -311,8 +306,8 @@ abstract class HttpOperation<InputPayload, Input, OutputPayload, Output>
       }
       final errorType = smithyError.type;
       final builder = smithyError.builder;
-      final errorPayload = await protocol.deserialize(
-        response.body,
+      final errorPayload = await protocol.wireSerializer.deserialize(
+        await response.bodyBytes,
         specifiedType: FullType(errorType),
       );
       final smithyException =

packages/smithy/smithy/lib/src/http/http_protocol.dart

@@ -2,6 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import 'dart:convert';
+import 'dart:typed_data';
 
 import 'package:async/async.dart';
 import 'package:aws_common/aws_common.dart';
@@ -12,7 +13,7 @@ import 'package:smithy/smithy.dart';
 /// A protocol for sending requests over HTTP.
 @optionalTypeArgs
 abstract class HttpProtocol<InputPayload, Input, OutputPayload, Output>
-    implements Protocol<Input, Output, Stream<List<int>>> {
+    implements Protocol<Input, OutputPayload> {
   const HttpProtocol();
 
   /// The content type of the request payload, added to the `Content-Type`
@@ -21,7 +22,7 @@ abstract class HttpProtocol<InputPayload, Input, OutputPayload, Output>
 
   /// Protocol headers
   Map<String, String> get headers => {
-        'Content-Type': contentType,
+        AWSHeaders.contentType: contentType,
       };
 
   Serializers get serializers;
@@ -45,45 +46,49 @@ abstract class HttpProtocol<InputPayload, Input, OutputPayload, Output>
     return AWSHttpClient()..supportedProtocols = SupportedProtocols.http1;
   }
 
-  @override
-  Stream<List<int>> serialize(Object? input, {FullType? specifiedType}) {
-    final Object? payload = input is HasPayload ? input.getPayload() : input;
+  /// Serializes [input] to an HTTP body.
+  Stream<List<int>> serialize(Input input) {
+    final payload = switch (input) {
+      InputPayload _ => input,
+      _ as HasPayload<InputPayload> => input.getPayload(),
+    };
     return switch (payload) {
+      null => const Stream.empty(),
       String _ => Stream.value(utf8.encode(payload)),
       List<int> _ => Stream.value(payload),
       Stream<List<int>> _ => payload,
       _ => Stream.fromFuture(
           Future.value(
             wireSerializer.serialize(
-              input,
-              specifiedType:
-                  specifiedType ?? FullType(Input, [FullType(InputPayload)]),
+              payload,
+              // Even though we're serializing the payload, specify the
+              // [Input] type since the semantics of serializing [Input]
+              // vs [InputPayload] vary. For example, some traits
+              // may only apply to the payload when serializing it as part
+              // of an [Input] struct vs. when directly serialized.
+              //
+              // We further pass the [InputPayloas] so that our built_value plugins
+              // have both types which is helpful when making determinations
+              // about how to, for example, process a List<Object?> which
+              // could represent either a Map or a List.
+              specifiedType: FullType(Input, [FullType(InputPayload)]),
             ),
           ),
         ),
     };
   }
 
-  @override
-  Future<Object?> deserialize(
-    Stream<List<int>> response, {
-    FullType? specifiedType,
-  }) async {
-    specifiedType ??= FullType(OutputPayload);
-    if (specifiedType.root == OutputPayload &&
-        OutputPayload == Stream<List<int>>) {
-      return response;
-    }
-
-    final body = await collectBytes(response);
-    if (specifiedType.root == OutputPayload) {
-      if (OutputPayload == List<int>) {
-        return body;
-      } else if (OutputPayload == String) {
-        return body.isEmpty ? '' : utf8.decode(body);
-      }
-    }
-    return await wireSerializer.deserialize(body, specifiedType: specifiedType);
+  /// Deserializes an HTTP [response] body to an [OutputPayload].
+  Future<OutputPayload> deserialize(Stream<List<int>> response) async {
+    return switch (OutputPayload) {
+      const (Stream<List<int>>) => response,
+      const (List<int>) || const (Uint8List) => await collectBytes(response),
+      const (String) => await utf8.decodeStream(response),
+      _ => await wireSerializer.deserialize(
+          await collectBytes(response),
+          specifiedType: FullType(OutputPayload),
+        ),
+    } as OutputPayload;
   }
 }
 
@@ -101,7 +106,7 @@ mixin HasLabel {
   String labelFor(String key);
 }
 
-abstract interface class HasPayload<Payload> {
+abstract interface class HasPayload<Payload extends Object?> {
   Payload? getPayload();
 }
 

packages/smithy/smithy/lib/src/http/http_server.dart

@@ -1,6 +1,7 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
+import 'package:async/async.dart';
 import 'package:aws_common/aws_common.dart';
 import 'package:built_value/serializer.dart';
 import 'package:shelf/shelf.dart';
@@ -30,11 +31,24 @@ abstract class HttpServerBase implements FullSerializer<Stream<List<int>>> {
 
   @override
   Stream<List<int>> serialize(Object? input, {FullType? specifiedType}) =>
-      protocol.serialize(input, specifiedType: specifiedType);
+      Stream.fromFuture(
+        Future.value(
+          protocol.wireSerializer.serialize(
+            input,
+            specifiedType: specifiedType,
+          ),
+        ),
+      );
 
   @override
-  Object? deserialize(Stream<List<int>> input, {FullType? specifiedType}) =>
-      protocol.deserialize(input, specifiedType: specifiedType);
+  Future<Object?> deserialize(
+    Stream<List<int>> output, {
+    FullType? specifiedType,
+  }) async =>
+      protocol.wireSerializer.deserialize(
+        await collectBytes(output),
+        specifiedType: specifiedType,
+      );
 
   Future<Response> handleUncaughtError(Object error, StackTrace st);
 }

packages/smithy/smithy/lib/src/protocol/protocol.dart

@@ -8,8 +8,7 @@ import 'package:smithy/smithy.dart';
 
 /// Metadata related to an operation regarding its serialization format,
 /// authentication schemes, etc.
-abstract class Protocol<Input, Output, WireType>
-    implements FullSerializer<WireType> {
+abstract class Protocol<Input, Output> {
   const Protocol._();
 
   /// The shape ID of the protocol trait this class implements.
@@ -22,5 +21,5 @@ abstract class FullSerializer<WireType>
   FutureOr<WireType> serialize(Object? input, {FullType? specifiedType});
 
   @override
-  FutureOr<Object?> deserialize(WireType input, {FullType? specifiedType});
+  FutureOr<Object?> deserialize(WireType output, {FullType? specifiedType});
 }

packages/smithy/smithy/lib/src/serialization/xml/xml_bool_serializer.dart

@@ -9,7 +9,7 @@ class XmlBoolSerializer extends PrimitiveSmithySerializer<bool> {
   const XmlBoolSerializer() : super('Bool');
 
   @override
-  Iterable<Type> get types => [bool];
+  Iterable<Type> get types => const [bool];
 
   @override
   bool deserialize(

packages/smithy/smithy_aws/lib/src/protocol/event_stream_protocol.dart

@@ -4,7 +4,6 @@
 import 'package:aws_common/aws_common.dart';
 import 'package:built_value/serializer.dart';
 import 'package:smithy/smithy.dart';
-
 import 'package:smithy_aws/src/protocol/aws_http_protocol.dart';
 
 class EventStreamProtocol<InputPayload, Input, OutputPayload, Output>
@@ -18,14 +17,11 @@ class EventStreamProtocol<InputPayload, Input, OutputPayload, Output>
   String get contentType => _baseProtocol.contentType;
 
   @override
-  Future<Object?> deserialize(
-    Stream<List<int>> response, {
-    FullType? specifiedType,
-  }) async {
+  Future<OutputPayload> deserialize(Stream<List<int>> response) async {
     return serializers.deserialize(
       response,
       specifiedType: FullType(OutputPayload),
-    );
+    ) as OutputPayload;
   }
 
   @override
@@ -50,8 +46,7 @@ class EventStreamProtocol<InputPayload, Input, OutputPayload, Output>
       _baseProtocol.responseInterceptors;
 
   @override
-  Stream<List<int>> serialize(Object? input, {FullType? specifiedType}) =>
-      _baseProtocol.serialize(input, specifiedType: specifiedType);
+  Stream<List<int>> serialize(Input input) => _baseProtocol.serialize(input);
 
   @override
   Serializers get serializers => _baseProtocol.serializers;

packages/smithy/smithy_aws/lib/src/protocol/rest_xml.dart

@@ -65,8 +65,7 @@ class RestXmlProtocol<InputPayload, Input, OutputPayload, Output>
       'application/xml';
 
   @override
-  late final FullSerializer<List<int>> wireSerializer =
-      XmlSerializer(serializers);
+  late final XmlSerializer wireSerializer = XmlSerializer(serializers);
 
   static Future<String?> resolveError(AWSBaseHttpResponse response) async {
     try {

packages/smithy/smithy_codegen/lib/src/core/reserved_words.dart

@@ -115,6 +115,7 @@ const structReservedWords = [
   'serializer',
   'replace',
   'toBuilder',
+  'object',
 ];
 
 const reservedTypeNames = [

packages/smithy/smithy_codegen/lib/src/generate.dart

@@ -7,9 +7,17 @@ import 'package:smithy_codegen/smithy_codegen.dart';
 import 'package:smithy_codegen/src/generator/visitors/library_visitor.dart';
 import 'package:smithy_codegen/src/version.dart';
 
+const List<String> _ignoredRules = [
+  'avoid_unused_constructor_parameters',
+  'deprecated_member_use_from_same_package',
+  'non_constant_identifier_names',
+];
+
 /// Header which prefixes all generated files.
-const String header =
-    '// Generated with smithy-dart $packageVersion. DO NOT MODIFY.';
+final String header = '''
+// Generated with smithy-dart $packageVersion. DO NOT MODIFY.
+// ignore_for_file: ${_ignoredRules.join(',')}
+''';
 
 /// The default emitter for codegen operations.
 DartEmitter buildEmitter(Allocator allocator) => DartEmitter(