-
Notifications
You must be signed in to change notification settings - Fork 222
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Make structure order part of the contract
This change updates Smithy to make the order of structure members part of the contract of structures and unions. We previously sorted these members automatically. However, languages like C, C++, Rust and others require the order of structures to be consistent, and new fields added to the end to maintain ABI compatibility. This change adds that language to the spec, updates the semantic model to use insertion order, updates equality checks to ensure that members have the same order, and adds a diff evaluator to detect a violation.
- Loading branch information
Showing
13 changed files
with
343 additions
and
72 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
71 changes: 71 additions & 0 deletions
71
smithy-diff/src/main/java/software/amazon/smithy/diff/evaluators/ChangedMemberOrder.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,71 @@ | ||
| /* | ||
| * Copyright 2020 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.diff.evaluators; | ||
|
|
||
| import java.util.Collection; | ||
| import java.util.Iterator; | ||
| import java.util.List; | ||
| import java.util.stream.Collectors; | ||
| import java.util.stream.Stream; | ||
| import software.amazon.smithy.diff.ChangedShape; | ||
| import software.amazon.smithy.diff.Differences; | ||
| import software.amazon.smithy.model.shapes.MemberShape; | ||
| import software.amazon.smithy.model.shapes.StructureShape; | ||
| import software.amazon.smithy.model.shapes.UnionShape; | ||
| import software.amazon.smithy.model.validation.ValidationEvent; | ||
|
|
||
| /** | ||
| * Creates a DANGER event when a structure or union member is added | ||
| * anywhere other than the end of the previous definition or the | ||
| * member order is changed. | ||
| */ | ||
| public final class ChangedMemberOrder extends AbstractDiffEvaluator { | ||
| @Override | ||
| public List<ValidationEvent> evaluate(Differences differences) { | ||
| Stream<ChangedShape<?>> changes = Stream.concat( | ||
| differences.changedShapes(StructureShape.class), | ||
| differences.changedShapes(UnionShape.class)); | ||
|
|
||
| return changes | ||
| .filter(diff -> isUnordered(diff.getOldShape().members(), diff.getNewShape().members())) | ||
| .map(diff -> danger(diff.getNewShape(), String.format( | ||
| "%s shape members were reordered. This can cause ABI compatibility issues in languages " | ||
| + "like C, C++, and Rust where the layout and alignment of a data structure matters.", | ||
| diff.getOldShape().getType()))) | ||
| .collect(Collectors.toList()); | ||
| } | ||
|
|
||
| private static boolean isUnordered(Collection<MemberShape> a, Collection<MemberShape> b) { | ||
| Iterator<MemberShape> aIter = a.iterator(); | ||
| Iterator<MemberShape> bIter = b.iterator(); | ||
|
|
||
| while (aIter.hasNext()) { | ||
| // If members were removed, then this check is satisfied (though there are | ||
| // other backward incompatible changes that other evaluators will detect). | ||
| if (!bIter.hasNext()) { | ||
| break; | ||
| } | ||
|
|
||
| String oldMember = aIter.next().getMemberName(); | ||
| String newMember = bIter.next().getMemberName(); | ||
| if (!oldMember.equals(newMember)) { | ||
| return true; | ||
| } | ||
| } | ||
|
|
||
| return false; | ||
| } | ||
| } |
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
137 changes: 137 additions & 0 deletions
137
smithy-diff/src/test/java/software/amazon/smithy/diff/evaluators/ChangedMemberOrderTest.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,137 @@ | ||
| /* | ||
| * Copyright 2020 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.diff.evaluators; | ||
|
|
||
| import static org.hamcrest.MatcherAssert.assertThat; | ||
| import static org.hamcrest.Matchers.empty; | ||
| import static org.hamcrest.Matchers.equalTo; | ||
|
|
||
| import java.util.List; | ||
| import org.junit.jupiter.api.Test; | ||
| import software.amazon.smithy.diff.ModelDiff; | ||
| import software.amazon.smithy.model.Model; | ||
| import software.amazon.smithy.model.shapes.MemberShape; | ||
| import software.amazon.smithy.model.shapes.Shape; | ||
| import software.amazon.smithy.model.shapes.StringShape; | ||
| import software.amazon.smithy.model.shapes.StructureShape; | ||
| import software.amazon.smithy.model.validation.Severity; | ||
| import software.amazon.smithy.model.validation.ValidationEvent; | ||
|
|
||
| public class ChangedMemberOrderTest { | ||
| @Test | ||
| public void detectsOrderChanges() { | ||
| Shape shape1 = StringShape.builder().id("foo.baz#String").build(); | ||
| MemberShape member1 = MemberShape.builder().id("foo.baz#Struct$member1").target(shape1).build(); | ||
| MemberShape member2 = MemberShape.builder().id("foo.baz#Struct$member2").target(shape1).build(); | ||
| StructureShape oldStruct = StructureShape.builder() | ||
| .id("foo.baz#Struct") | ||
| .addMember(member1) | ||
| .addMember(member2) | ||
| .build(); | ||
|
|
||
| StructureShape newStruct = StructureShape.builder() | ||
| .id("foo.baz#Struct") | ||
| .addMember(member2) | ||
| .addMember(member1) | ||
| .build(); | ||
|
|
||
| Model modelA = Model.assembler().addShapes(shape1, oldStruct).assemble().unwrap(); | ||
| Model modelB = Model.assembler().addShapes(shape1, newStruct).assemble().unwrap(); | ||
| List<ValidationEvent> events = ModelDiff.compare(modelA, modelB); | ||
|
|
||
| assertThat(TestHelper.findEvents(events, "ChangedMemberOrder").size(), equalTo(1)); | ||
| assertThat(TestHelper.findEvents(events, oldStruct.getId()).size(), equalTo(1)); | ||
| assertThat(TestHelper.findEvents(events, Severity.DANGER).size(), equalTo(1)); | ||
| } | ||
|
|
||
| @Test | ||
| public void detectsOrderInsertionChanges() { | ||
| Shape shape1 = StringShape.builder().id("foo.baz#String").build(); | ||
| MemberShape member1 = MemberShape.builder().id("foo.baz#Struct$member1").target(shape1).build(); | ||
| MemberShape member2 = MemberShape.builder().id("foo.baz#Struct$member2").target(shape1).build(); | ||
| StructureShape oldStruct = StructureShape.builder() | ||
| .id("foo.baz#Struct") | ||
| .addMember(member1) | ||
| .addMember(member2) | ||
| .build(); | ||
|
|
||
| MemberShape member3 = MemberShape.builder().id("foo.baz#Struct$member3").target(shape1).build(); | ||
| StructureShape newStruct = StructureShape.builder() | ||
| .id("foo.baz#Struct") | ||
| .addMember(member1) | ||
| .addMember(member3) | ||
| .addMember(member2) | ||
| .build(); | ||
|
|
||
| Model modelA = Model.assembler().addShapes(shape1, oldStruct).assemble().unwrap(); | ||
| Model modelB = Model.assembler().addShapes(shape1, newStruct).assemble().unwrap(); | ||
| List<ValidationEvent> events = ModelDiff.compare(modelA, modelB); | ||
|
|
||
| assertThat(TestHelper.findEvents(events, "ChangedMemberOrder").size(), equalTo(1)); | ||
| assertThat(TestHelper.findEvents(events, oldStruct.getId()).size(), equalTo(1)); | ||
| assertThat(TestHelper.findEvents(events, Severity.DANGER).size(), equalTo(1)); | ||
| } | ||
|
|
||
| @Test | ||
| public void detectsCompatibleChanges() { | ||
| Shape shape1 = StringShape.builder().id("foo.baz#String").build(); | ||
| MemberShape member1 = MemberShape.builder().id("foo.baz#Struct$member1").target(shape1).build(); | ||
| MemberShape member2 = MemberShape.builder().id("foo.baz#Struct$member2").target(shape1).build(); | ||
| StructureShape oldStruct = StructureShape.builder() | ||
| .id("foo.baz#Struct") | ||
| .addMember(member1) | ||
| .addMember(member2) | ||
| .build(); | ||
|
|
||
| MemberShape member3 = MemberShape.builder().id("foo.baz#Struct$member3").target(shape1).build(); | ||
| StructureShape newStruct = StructureShape.builder() | ||
| .id("foo.baz#Struct") | ||
| .addMember(member1) | ||
| .addMember(member2) | ||
| .addMember(member3) | ||
| .build(); | ||
|
|
||
| Model modelA = Model.assembler().addShapes(shape1, oldStruct).assemble().unwrap(); | ||
| Model modelB = Model.assembler().addShapes(shape1, newStruct).assemble().unwrap(); | ||
| List<ValidationEvent> events = ModelDiff.compare(modelA, modelB); | ||
|
|
||
| assertThat(TestHelper.findEvents(events, "ChangedMemberOrder"), empty()); | ||
| } | ||
|
|
||
| // Ignore the fact that a member was removed. | ||
| @Test | ||
| public void ignoresOtherBreakingChanges() { | ||
| Shape shape1 = StringShape.builder().id("foo.baz#String").build(); | ||
| MemberShape member1 = MemberShape.builder().id("foo.baz#Struct$member1").target(shape1).build(); | ||
| MemberShape member2 = MemberShape.builder().id("foo.baz#Struct$member2").target(shape1).build(); | ||
| StructureShape oldStruct = StructureShape.builder() | ||
| .id("foo.baz#Struct") | ||
| .addMember(member1) | ||
| .addMember(member2) | ||
| .build(); | ||
|
|
||
| StructureShape newStruct = StructureShape.builder() | ||
| .id("foo.baz#Struct") | ||
| .addMember(member1) | ||
| .build(); | ||
|
|
||
| Model modelA = Model.assembler().addShapes(shape1, oldStruct).assemble().unwrap(); | ||
| Model modelB = Model.assembler().addShapes(shape1, newStruct).assemble().unwrap(); | ||
| List<ValidationEvent> events = ModelDiff.compare(modelA, modelB); | ||
|
|
||
| assertThat(TestHelper.findEvents(events, "ChangedMemberOrder"), empty()); | ||
| } | ||
| } |
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
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
Oops, something went wrong.