Add validation and clarification to event source

This commit adds validation to help ensure that CloudTrail event source
values are configured correctly. If also clarifies that the
cloudTrailEventSource property contains the customer-facing value.

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);
+    }
+}