From 14d19d0647bc5c06aea92d2b33df496c7b59a987 Mon Sep 17 00:00:00 2001
From: Michael Dowling <mtdowling@gmail.com>
Date: Fri, 13 Aug 2021 13:11:57 -0700
Subject: [PATCH] Clarify that event streams contain modeled errors

---
 docs/source/1.0/spec/core/stream-traits.rst   | 29 +++++++++++++++++++
 .../event-stream-with-errors.errors           |  0
 .../event-stream-with-errors.smithy           | 28 ++++++++++++++++++
 3 files changed, 57 insertions(+)
 create mode 100644 smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/event-stream-with-errors.errors
 create mode 100644 smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/event-stream-with-errors.smithy

diff --git a/docs/source/1.0/spec/core/stream-traits.rst b/docs/source/1.0/spec/core/stream-traits.rst
index d630715edbd..ee3f92f528d 100644
--- a/docs/source/1.0/spec/core/stream-traits.rst
+++ b/docs/source/1.0/spec/core/stream-traits.rst
@@ -214,12 +214,20 @@ stream in its output:
             down: Movement,
             left: Movement,
             right: Movement,
+            throttlingError: ThrottlingError
         }
 
         structure Movement {
             velocity: Float,
         }
 
+        /// An example error emitted when the client is throttled
+        /// and should terminate the event stream.
+        @error("client")
+        @retryable(throttling: true)
+        structure ThrottlingError {}
+
+
     .. code-tab:: json
 
         {
@@ -253,6 +261,9 @@ stream in its output:
                         },
                         "right": {
                             "target": "smithy.example#Movement"
+                        },
+                        "throttlingError": {
+                            "target": "smithy.example#ThrottlingError"
                         }
                     },
                     "traits": {
@@ -266,11 +277,29 @@ stream in its output:
                             "target": "smithy.api#Float"
                         }
                     }
+                },
+                "smithy.example#ThrottlingError": {
+                    "type": "structure",
+                    "traits": {
+                        "smithy.api#documentation": "An example error emitted when the client is throttled and should terminate the event stream.",
+                        "smithy.api#error": "client",
+                        "smithy.api#retryable": {
+                            "throttling": true
+                        }
+                    }
                 }
             }
         }
 
 
+Modeled errors in event streams
+===============================
+
+Event streams MAY target shapes marked with the :ref:`error-trait`. These
+events are considered terminal errors and MUST terminate the event stream
+when received.
+
+
 .. _initial-messages:
 
 Initial messages
diff --git a/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/event-stream-with-errors.errors b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/event-stream-with-errors.errors
new file mode 100644
index 00000000000..e69de29bb2d
diff --git a/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/event-stream-with-errors.smithy b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/event-stream-with-errors.smithy
new file mode 100644
index 00000000000..d6799801c0b
--- /dev/null
+++ b/smithy-model/src/test/resources/software/amazon/smithy/model/errorfiles/validators/event-stream-with-errors.smithy
@@ -0,0 +1,28 @@
+namespace smithy.example
+
+operation SubscribeToMovements {
+    output: SubscribeToMovementsOutput
+}
+
+structure SubscribeToMovementsOutput {
+    movements: MovementEvents,
+}
+
+@streaming
+union MovementEvents {
+    up: Movement,
+    down: Movement,
+    left: Movement,
+    right: Movement,
+    throttlingError: ThrottlingError
+}
+
+structure Movement {
+    velocity: Float,
+}
+
+/// An example error emitted when the client is throttled
+/// and should terminate the event stream.
+@error("client")
+@retryable(throttling: true)
+structure ThrottlingError {}