Merge pull request #102 from microsoftgraph/feature/sunset

feature/sunset

Observability.md

@@ -75,8 +75,16 @@ 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",
+                          "sunset_link?": "link header with a sunset value for rel (only the URI)"
+                        },
+                        "Request_transport?": {
+                        // this span is present only to measure network latency and deduct it from the middleware pipeline
+                        }
                     }
                 }
               }

README.md

@@ -20,6 +20,7 @@ This repository holds documents related to current and on-going work on Microsof
 | | Connection Management | | | | | |
 | | Long Running Operations | | | | | |
 | | Chaos Handler | |[✓][java_chaoshandler] |O| | |
+| | [Sunset Handler](middleware/SunsetHandler.md) | 
 | | Service Discovery Handler | | | | | |
 | [Content](content/ContentArchitecturalConstraints.md)
 || [Batch Request Content](content/BatchRequestContent.md)     |[✓][dotnet_batchrequestcontent]|[✓][java_batchrequestcontent]|[✓][js_batchrequestcontent]| | |

middleware/RetryHandler.md

@@ -2,7 +2,7 @@
 
 ## Objectives
 
-Provide a reusuable component that provides application developers with effective handling of failed requests that can be retried.
+Provide a reusable component that provides application developers with effective handling of failed requests that can be retried.
 
 ## Requirements
 
@@ -45,7 +45,8 @@ The thread processing a request should not be blocked while waiting for a retry
 [Graph Throttling](https://developer.microsoft.com/en-us/graph/docs/concepts/throttling)
 
 ## Open Issues
+
 - New requests made while an existing request has been queued for retry, should be considered for adding to the queue.  
 - Requests with the exact same URL should be queued.
 - Requests with the same path should be queued.
-- Requests with n matching initial segments should be queued after 5-n throtted requests. e.g. If a there have been 3 throttled requests for requests with the first two segments matching, then the next matching request should be queued.  
+- Requests with n matching initial segments should be queued after 5-n throttled requests. e.g. If a there have been 3 throttled requests for requests with the first two segments matching, then the next matching request should be queued.  

middleware/SunsetHandler.md

@@ -0,0 +1,14 @@
+# 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.
+- The additional event MUST contain the sunset link value (see RFC) if present as an attribute.