Add validation and clarification to event source

docs/source/1.0/spec/aws/aws-core.rst

@@ -213,9 +213,9 @@ are combined with the service's arnNamespace to form an ARN.
 =========================
 
 The ``cloudTrailEventSource`` property is a ``string`` value that defines the
-*eventSource* property contained in CloudTrail `event records`_
-emitted by the service. If not specified, this value defaults to the
-``arnNamespace`` plus .amazonaws.com. For example:
+AWS customer-facing *eventSource* property contained in CloudTrail
+`event records`_ emitted by the service. If not specified, this value defaults
+to the ``arnNamespace`` plus .amazonaws.com. For example:
 
 * AWS CloudFormation has an ``arnNamespace`` of ``cloudformation`` and an
   event source of ``cloudformation.amazonaws.com``.
@@ -224,7 +224,8 @@ emitted by the service. If not specified, this value defaults to the
 * Amazon Simple Workflow Service has an ``arnNamespace`` of ``swf`` and
   an event source of ``swf.amazonaws.com``.
 
-This convention has some exceptions. For example, the event source for
+This value SHOULD follow the convention of ``{arnNamespace}.amazonaws.com``,
+but there are some exceptions. For example, the event source for
 Amazon CloudWatch is ``monitoring.amazonaws.com``. Such services will
 need to explicitly configure the ``cloudTrailEventSource`` setting.
 

smithy-aws-traits/src/main/java/software/amazon/smithy/aws/traits/EventSourceValidator.java

@@ -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.aws.traits;
+
+import static java.util.stream.Collectors.toList;
+
+import java.util.List;
+import java.util.Map;
+import java.util.Objects;
+import java.util.Optional;
+import software.amazon.smithy.model.Model;
+import software.amazon.smithy.model.shapes.ServiceShape;
+import software.amazon.smithy.model.traits.Trait;
+import software.amazon.smithy.model.validation.AbstractValidator;
+import software.amazon.smithy.model.validation.ValidationEvent;
+import software.amazon.smithy.utils.MapUtils;
+import software.amazon.smithy.utils.OptionalUtils;
+import software.amazon.smithy.utils.SmithyInternalApi;
+import software.amazon.smithy.utils.StringUtils;
+
+/**
+ * Validates that the aws.api#service/eventSource property matches
+ * {@code aws.api#service/arnNamespace} + ".amazonaws.com" and does
+ * not use incorrect formats.
+ */
+@SmithyInternalApi
+public final class EventSourceValidator extends AbstractValidator {
+
+    private static final Map<String, String> KNOWN_EXCEPTIONS = MapUtils.of(
+            "cloudwatch.amazonaws.com", "monitoring.amazonaws.com"
+    );
+
+    @Override
+    public List<ValidationEvent> validate(Model model) {
+        return model.shapes(ServiceShape.class)
+                .flatMap(service -> Trait.flatMapStream(service, ServiceTrait.class))
+                .flatMap(pair -> OptionalUtils.stream(validateService(pair.getLeft(), pair.getRight())))
+                .collect(toList());
+    }
+
+    private Optional<ValidationEvent> validateService(ServiceShape service, ServiceTrait trait) {
+        String message = null;
+        String source = trait.getCloudTrailEventSource();
+        String expectedEventSource = trait.getArnNamespace() + ".amazonaws.com";
+
+        if (!Objects.equals(KNOWN_EXCEPTIONS.get(expectedEventSource), source)) {
+            if (source.contains("REPLACE") || StringUtils.upperCase(source).equals(source)) {
+                // TODO: ideally this can become a DANGER event in the future.
+                message = "aws.api#service|cloudTrailEventSource must not use placeholders, but found: " + source;
+            } else if (!source.equals(expectedEventSource)) {
+                message = String.format("aws.api#service|cloudTrailEventSource does not match the expected value. "
+                                        + "Expected '%s', but found '%s'.", expectedEventSource, source);
+            }
+        }
+
+        return message == null ? Optional.empty() : Optional.of(warning(service, trait, message));
+    }
+}

smithy-aws-traits/src/main/resources/META-INF/services/software.amazon.smithy.model.validation.Validator

@@ -2,3 +2,4 @@ software.amazon.smithy.aws.traits.ArnTemplateValidator
 software.amazon.smithy.aws.traits.SdkServiceIdValidator
 software.amazon.smithy.aws.traits.clientendpointdiscovery.ClientEndpointDiscoveryValidator
 software.amazon.smithy.aws.traits.protocols.ProtocolHttpValidator
+software.amazon.smithy.aws.traits.EventSourceValidator

smithy-aws-traits/src/test/java/software/amazon/smithy/aws/traits/EventSourceValidatorTest.java

@@ -0,0 +1,93 @@
+package software.amazon.smithy.aws.traits;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.containsString;
+import static org.hamcrest.Matchers.equalTo;
+import static org.hamcrest.Matchers.is;
+
+import java.util.List;
+import org.junit.jupiter.api.Assertions;
+import org.junit.jupiter.api.Test;
+import software.amazon.smithy.model.Model;
+import software.amazon.smithy.model.shapes.ServiceShape;
+import software.amazon.smithy.model.validation.Severity;
+import software.amazon.smithy.model.validation.ValidationEvent;
+
+public class EventSourceValidatorTest {
+    @Test
+    public void detectsWhenEventSourceIsUnexpected() {
+        ServiceTrait trait = ServiceTrait.builder()
+                .sdkId("Foo")
+                .arnNamespace("foo")
+                .cloudTrailEventSource("REPLACE_ME_LATER")
+                .cloudFormationName("AWS::Foo")
+                .build();
+        ServiceShape service = ServiceShape.builder()
+                .id("smithy.example#Foo")
+                .version("123")
+                .addTrait(trait)
+                .build();
+        Model model = Model.builder().addShape(service).build();
+        EventSourceValidator validator = new EventSourceValidator();
+        List<ValidationEvent> events = validator.validate(model);
+        ValidationEvent event = getMatchingEvent(events, validator.getName());
+
+        assertThat(event.getSeverity(), is(Severity.WARNING));
+        assertThat(event.getShapeId().get(), equalTo(service.getId()));
+        assertThat(event.getMessage(), containsString("must not use placeholders"));
+    }
+
+    @Test
+    public void detectsWhenEventSourceIsPlaceholder() {
+        ServiceTrait trait = ServiceTrait.builder()
+                .sdkId("Foo")
+                .arnNamespace("foo")
+                .cloudTrailEventSource("notfoo.amazonaws.com")
+                .cloudFormationName("AWS::Foo")
+                .build();
+        ServiceShape service = ServiceShape.builder()
+                .id("smithy.example#Foo")
+                .version("123")
+                .addTrait(trait)
+                .build();
+        Model model = Model.builder().addShape(service).build();
+        EventSourceValidator validator = new EventSourceValidator();
+        List<ValidationEvent> events = validator.validate(model);
+        ValidationEvent event = getMatchingEvent(events, validator.getName());
+
+        assertThat(event.getSeverity(), is(Severity.WARNING));
+        assertThat(event.getShapeId().get(), equalTo(service.getId()));
+        assertThat(event.getMessage(),
+                   containsString("Expected 'foo.amazonaws.com', but found 'notfoo.amazonaws.com'"));
+    }
+
+    @Test
+    public void ignoresKnownExceptions() {
+        ServiceTrait trait = ServiceTrait.builder()
+                .sdkId("Foo")
+                .arnNamespace("cloudwatch")
+                .cloudTrailEventSource("monitoring.amazonaws.com")
+                .cloudFormationName("AWS::Foo")
+                .build();
+        ServiceShape service = ServiceShape.builder()
+                .id("smithy.example#Foo")
+                .version("123")
+                .addTrait(trait)
+                .build();
+        Model model = Model.builder().addShape(service).build();
+        EventSourceValidator validator = new EventSourceValidator();
+        List<ValidationEvent> events = validator.validate(model);
+
+        Assertions.assertThrows(RuntimeException.class, () -> getMatchingEvent(events, validator.getName()));
+    }
+
+    private ValidationEvent getMatchingEvent(List<ValidationEvent> events, String eventId) {
+        for (ValidationEvent event : events) {
+            if (event.getId().equals(eventId)) {
+                return event;
+            }
+        }
+
+        throw new RuntimeException("Expected validation event not found: " + eventId);
+    }
+}