feat: adds sunset handler specification

Signed-off-by: Vincent Biret <[email protected]>

Observability.md

@@ -75,8 +75,15 @@ Open Telemetry spans are nested and can have attributes attached to each span. T
                 "com.microsoft.kiota.handler.decompression.enable": "boolean, true if the handler is present and enabled",
                 "ParametersNameDecodingHandler_intercept?": {
                   "com.microsoft.kiota.handler.parameters_name_decoding.enable": "boolean, true if the handler is present and enabled",
-                    "Request_transport?": {
-                    // this span is present only to measure network latency and deduct it from the middleware pipeline
+                    "SunsetHandler_intercept?": {
+                      "com.microsoft.kiota.handler.sunset.enable": "boolean, true if the handler is present and enabled",
+                        "Event - com.microsoft.kiota.sunset_header_received?": {
+                          // raised only if a sunset header is present in the response
+                          "sunset_date": "Date at internet date format from the sunset header value",
+                        },
+                        "Request_transport?": {
+                        // this span is present only to measure network latency and deduct it from the middleware pipeline
+                        }
                     }
                 }
               }

README.md

@@ -17,6 +17,7 @@ This repository holds documents related to current and on-going work on Microsof
 | | [Response decompression Handler](middleware/DecompressionHandler.md) |[✓][dotnet_decompressionhandler]|N|N|N|[✓][dotnet_decompressionhandler]| |
 | | [Logging Handler](middleware/LoggingHandler.md) (PowerShell only since other languages implement Observability/OTEL ) |✓| | | |[✓][powershell_logginghandler]| |
 | | [Telemetry Handler](middleware/TelemetryHandler.md) |[✓][dotnet_telemetryhandler]|[✓][java_telemetryhandler]|✓|✓|[✓][powershell_telemetryhandler]| | |[✓][python_telemetryhandler] | [✓][go_telemetryhandler]|
+| | [Sunset Handler](middleware/SunsetHandler.md) | 
 | | Connection Management | | | | | | |
 | | Long Running Operations | | | | | | |
 | | Chaos Handler | |[✓][java_chaoshandler] |O| | | |

middleware/SunsetHandler.md

@@ -0,0 +1,13 @@
+# Sunset Handler
+
+## Objectives
+
+Let application operation teams know that a given operation depends on an API which is slated for removal so they can proactively update the application before a breakage occurs.
+
+## Requirements
+
+- MUST provide an option to disable the behaviour for a given request with a settable default for all requests.
+- Additional observability requirements in [Observability](../Observability.md)
+- MUST create an event under the span (see Observability) whenever an [HTTP sunset header](https://datatracker.ietf.org/doc/html/rfc8594) is encountered in the response.
+- The additional event MUST contain the sunset date value provided by the header as an attribute.
+- The span and event MUST NOT contain the URI since parent spans already offer that tag/attribute and it could contain sensitive information.