-
Notifications
You must be signed in to change notification settings - Fork 219
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Improve IDL 1 and 2 interoperability
This commit makes several significant updates to Smithy IDL 2 that improve lossless interoperability with Smithy IDL 1: * Default traits can now coexist with required. This indicates that a member should be serialized, but it is a protocol-specific decision if and how this is enforced. This was a pattern that occurred in Smithy 1.0 models when a member was required and targeted a shape with a zero value. * Default traits can be added to root-level shapes. Any structure member that targets a shape marked with the default trait must repeat the default on the member. This removes the action at a distance problem observed in Smithy IDL 1 where a root level shape implicitly introduced a default zero value, and to know if that's the case for any member, you had to look through from the member to the target shape. This change allows us to know if a root level shape was boxed in IDL 1.0 too -- if it is a shape that had a zero value in IDL 1 and either doesn't have a default or the default is not the zero value, then it was boxed in v1. * When loading v2 models, we will now patch synthetic box traits onto shapes that would have been considered boxed by existing smithy-model consumers. This improves further interop with tooling that has not yet adopted Smithy IDL 2 or that hasn't yet migrated to use the NullableIndex abstraction. * Added an optional nullability report to smithy-build that shows the computed nullability semantics of each member in a model. This can be used to better understand nullability semantics. * Updated smithy-diff to not emit events when diffing a 1.0 model against the 2.0 serialized version of the model. This means that changes to the box trait are ignored unless the change impacts the nullability of the shape. Special handling was added to detect breaking changes with the default trait too (you can't change a default value of a root-level shape for example, you can't change a default value of a shape to or from the zero value of a type as this might break code generators, etc). * Add new NullableIndex modes for testing if a member is nullable based on the supported features of the generator. For example, some generators only make members non-optional when the member is set to the zero value of a type, so there is a NullableIndex check mode for that and other use cases. * Added the @addedDefault trait which is used to indicate that a `@default` trait was added to a member after it was initially released. This can be used by tooling to make an appropriate determination if generating a non-nullable type for the member is a backward compatible change. For example, if a generator only uses default zero values to generate non-nullable types, then the removal of the required trait and addition of a default trait would be a breaking change for them, so they can use addedDefault to ignore the default trait. * When loading 1.0 models, rather than dropping the default trait from a member when the range trait of a shape is invalid for its zero value, we now instead emit only a warning for this specific case. This prevents changing the type and also doesn't lose the range constraint in case implementations are relying on this validation. * Un-deprecated Primitive* shapes in the prelude and add the `@default` trait to them. Any member that targets one of these primitive prelude shapes must now also repeat the zero value of the target shape. * Fixed an issue where synthetic box traits were being dropped when the same model is loaded multiple times.
- Loading branch information
Showing
100 changed files
with
2,508 additions
and
639 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1 +1 @@ | ||
1.24.0 | ||
1.25.0 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
86 changes: 86 additions & 0 deletions
86
smithy-build/src/main/java/software/amazon/smithy/build/plugins/NullabilityReportPlugin.java
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,86 @@ | ||
/* | ||
* Copyright 2022 Amazon.com, Inc. or its affiliates. All Rights Reserved. | ||
* | ||
* Licensed under the Apache License, Version 2.0 (the "License"). | ||
* You may not use this file except in compliance with the License. | ||
* A copy of the License is located at | ||
* | ||
* http://aws.amazon.com/apache2.0 | ||
* | ||
* or in the "license" file accompanying this file. This file is distributed | ||
* on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either | ||
* express or implied. See the License for the specific language governing | ||
* permissions and limitations under the License. | ||
*/ | ||
|
||
package software.amazon.smithy.build.plugins; | ||
|
||
import software.amazon.smithy.build.PluginContext; | ||
import software.amazon.smithy.build.SmithyBuildPlugin; | ||
import software.amazon.smithy.model.Model; | ||
import software.amazon.smithy.model.knowledge.NullableIndex; | ||
import software.amazon.smithy.model.node.Node; | ||
import software.amazon.smithy.model.node.ObjectNode; | ||
import software.amazon.smithy.model.shapes.MemberShape; | ||
import software.amazon.smithy.model.shapes.StructureShape; | ||
import software.amazon.smithy.model.traits.BoxTrait; | ||
|
||
/** | ||
* Generates a JSON report that contains a mapping of every structure member to | ||
* whether the member is considered nullable in v1 and v2 implementations. | ||
*/ | ||
public final class NullabilityReportPlugin implements SmithyBuildPlugin { | ||
|
||
static final String NULLABILITY_REPORT_PATH = "nullability-report.json"; | ||
private static final String NAME = "nullabilityReport"; | ||
|
||
@Override | ||
public String getName() { | ||
return NAME; | ||
} | ||
|
||
@Override | ||
public boolean requiresValidModel() { | ||
return false; | ||
} | ||
|
||
@Override | ||
public void execute(PluginContext context) { | ||
if (context.getOriginalModel().isPresent() && context.getProjection().isPresent()) { | ||
context.getFileManifest().writeJson(NULLABILITY_REPORT_PATH, serializeReport(context)); | ||
} | ||
} | ||
|
||
private static Node serializeReport(PluginContext context) { | ||
ObjectNode.Builder root = Node.objectNodeBuilder(); | ||
Model model = context.getModel(); | ||
NullableIndex index = NullableIndex.of(model); | ||
|
||
for (StructureShape structure : model.getStructureShapes()) { | ||
// Only generate for structures in "sources" that have members. | ||
if (!structure.getAllMembers().isEmpty() && context.isSourceShape(structure)) { | ||
ObjectNode.Builder struct = Node.objectNodeBuilder(); | ||
for (MemberShape member : structure.getAllMembers().values()) { | ||
ObjectNode.Builder entry = Node.objectNodeBuilder(); | ||
entry.withMember("v1", index.isNullable(member)); | ||
entry.withMember("v1-via-box", member.getMemberTrait(model, BoxTrait.class).isPresent()); | ||
entry.withMember("v2-client", | ||
index.isMemberNullable(member, NullableIndex.CheckMode.CLIENT)); | ||
entry.withMember("v2-client-careful", | ||
index.isMemberNullable(member, NullableIndex.CheckMode.CLIENT_CAREFUL)); | ||
entry.withMember("v2-client-zero-value", | ||
index.isMemberNullable(member, NullableIndex.CheckMode.CLIENT_ZERO_VALUE_V1)); | ||
entry.withMember("v2-client-zero-value-no-input", | ||
index.isMemberNullable(member, | ||
NullableIndex.CheckMode.CLIENT_ZERO_VALUE_V1_NO_INPUT)); | ||
entry.withMember("v2-server", | ||
index.isMemberNullable(member, NullableIndex.CheckMode.SERVER)); | ||
struct.withMember(member.getMemberName(), entry.build()); | ||
} | ||
root.withMember(structure.getId().toString(), struct.build()); | ||
} | ||
} | ||
|
||
return root.build(); | ||
} | ||
} |
1 change: 1 addition & 0 deletions
1
...build/src/main/resources/META-INF/services/software.amazon.smithy.build.SmithyBuildPlugin
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,3 +1,4 @@ | ||
software.amazon.smithy.build.plugins.BuildInfoPlugin | ||
software.amazon.smithy.build.plugins.ModelPlugin | ||
software.amazon.smithy.build.plugins.SourcesPlugin | ||
software.amazon.smithy.build.plugins.NullabilityReportPlugin |
Oops, something went wrong.