doc: Add RFC documents

1 files changed, 619 insertions, 0 deletions

diff --git a/doc/rfc/rfc8594.txt b/doc/rfc/rfc8594.txt
new file mode 100644
index 0000000..13d636f
--- /dev/null
+++ b/doc/rfc/rfc8594.txt
@@ -0,0 +1,619 @@
+
+
+
+
+
+
+Internet Engineering Task Force (IETF)                          E. Wilde
+Request for Comments: 8594                                      May 2019
+Category: Informational
+ISSN: 2070-1721
+
+
+                      The Sunset HTTP Header Field
+
+Abstract
+
+   This specification defines the Sunset HTTP response header field,
+   which indicates that a URI is likely to become unresponsive at a
+   specified point in the future.  It also defines a sunset link
+   relation type that allows linking to resources providing information
+   about an upcoming resource or service sunset.
+
+Status of This Memo
+
+   This document is not an Internet Standards Track specification; it is
+   published for informational purposes.
+
+   This document is a product of the Internet Engineering Task Force
+   (IETF).  It represents the consensus of the IETF community.  It has
+   received public review and has been approved for publication by the
+   Internet Engineering Steering Group (IESG).  Not all documents
+   approved by the IESG are candidates for any level of Internet
+   Standard; see Section 2 of RFC 7841.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   https://www.rfc-editor.org/info/rfc8594.
+
+Copyright Notice
+
+   Copyright (c) 2019 IETF Trust and the persons identified as the
+   document authors.  All rights reserved.
+
+   This document is subject to BCP 78 and the IETF Trust's Legal
+   Provisions Relating to IETF Documents
+   (https://trustee.ietf.org/license-info) in effect on the date of
+   publication of this document.  Please review these documents
+   carefully, as they describe your rights and restrictions with respect
+   to this document.  Code Components extracted from this document must
+   include Simplified BSD License text as described in Section 4.e of
+   the Trust Legal Provisions and are provided without warranty as
+   described in the Simplified BSD License.
+
+
+
+
+
+Wilde                         Informational                     [Page 1]
+
+RFC 8594                      Sunset Header                     May 2019
+
+
+Table of Contents
+
+   1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
+     1.1.  Temporary Resources . . . . . . . . . . . . . . . . . . .   3
+     1.2.  Migration . . . . . . . . . . . . . . . . . . . . . . . .   3
+     1.3.  Retention . . . . . . . . . . . . . . . . . . . . . . . .   3
+     1.4.  Deprecation . . . . . . . . . . . . . . . . . . . . . . .   3
+   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   4
+   3.  The Sunset HTTP Response Header Field . . . . . . . . . . . .   4
+   4.  Sunset and Caching  . . . . . . . . . . . . . . . . . . . . .   5
+   5.  Sunset Scope  . . . . . . . . . . . . . . . . . . . . . . . .   6
+   6.  The Sunset Link Relation Type . . . . . . . . . . . . . . . .   6
+   7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   7
+     7.1.  The Sunset Response Header Field  . . . . . . . . . . . .   7
+     7.2.  The Sunset Link Relation Type . . . . . . . . . . . . . .   8
+   8.  Security Considerations . . . . . . . . . . . . . . . . . . .   8
+   9.  Example . . . . . . . . . . . . . . . . . . . . . . . . . . .   9
+   10. References  . . . . . . . . . . . . . . . . . . . . . . . . .  10
+     10.1.  Normative References . . . . . . . . . . . . . . . . . .  10
+     10.2.  Informative References . . . . . . . . . . . . . . . . .  10
+   Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  10
+   Author's Address  . . . . . . . . . . . . . . . . . . . . . . . .  11
+
+1.  Introduction
+
+   As a general rule, URIs should be stable and persistent so that
+   applications can use them as stable and persistent identifiers for
+   resources.  However, there are many scenarios where, for a variety of
+   reasons, URIs have a limited lifetime.  In some of these scenarios,
+   this limited lifetime is known in advance.  In this case, it can be
+   useful for clients if resources make this information about their
+   limited lifetime known.  This specification defines the Sunset HTTP
+   response header field, which indicates that a URI is likely to become
+   unresponsive at a specified point in the future.
+
+   This specification also defines a sunset link relation type that
+   allows information to be provided about 1) the sunset policy of a
+   resource or a service, and/or 2) upcoming sunsets, and/or 3) possible
+   mitigation scenarios for resource/service users.  This specification
+   does not place any constraints on the nature of the linked resource,
+   which can be targeted to humans, machines, or both.
+
+   Possible scenarios for known lifetimes of resources include, but are
+   not limited to, the following scenarios.
+
+
+
+
+
+
+
+Wilde                         Informational                     [Page 2]
+
+RFC 8594                      Sunset Header                     May 2019
+
+
+1.1.  Temporary Resources
+
+   Some resources may have a limited lifetime by definition.  For
+   example, a pending shopping order represented by a resource may
+   already list all order details, but it may only exist for a limited
+   time unless it is confirmed and only then becomes an acknowledged
+   shopping order.  In such a case, the service managing the pending
+   shopping order can make this limited lifetime explicit, allowing
+   clients to understand that the pending order, unless confirmed, will
+   disappear at some point in time.
+
+1.2.  Migration
+
+   If resources are changing identity because a service migrates them,
+   then this may be known in advance.  While it may not yet be
+   appropriate to use HTTP redirect status codes (3xx), it may be
+   interesting for clients to learn about the service's plan to take
+   down the original resource.
+
+1.3.  Retention
+
+   There are many cases where regulation or legislation require that
+   resources are kept available for a certain amount of time.  However,
+   in many cases there is also a requirement for those resources to be
+   permanently deleted after some period of time.  Since the deletion of
+   the resource in this scenario is governed by well-defined rules, it
+   could be made explicit for clients interacting with the resource.
+
+1.4.  Deprecation
+
+   For Web APIs one standard scenario is that an API or specific subsets
+   of an API may get deprecated.  Deprecation often happens in two
+   stages: the first stage being that the API is not the preferred or
+   recommended version anymore and the second stage being that the API
+   or a specific version of the API gets decommissioned.
+
+   For the first stage (the API is not the preferred or recommended
+   version anymore), the Sunset header field is not appropriate: at this
+   stage, the API remains operational and can still be used.  Other
+   mechanisms can be used for signaling that first stage that might help
+   with more visible deprecation management, but the Sunset header field
+   does not aim to represent that information.
+
+   For the second stage (the API or a specific version of the API gets
+   decommissioned), the Sunset header field is appropriate: that is when
+   the API or a version does become unresponsive.  From the Sunset
+   header field's point of view, it does not matter that the API may not
+
+
+
+
+Wilde                         Informational                     [Page 3]
+
+RFC 8594                      Sunset Header                     May 2019
+
+
+   have been the preferred or recommended version anymore.  The only
+   thing that matters is that it will become unresponsive and that this
+   time can be advertised using the Sunset header field.
+
+   In this scenario, the announced sunset date typically affects all of
+   the deprecated API or parts of it (i.e., just deprecated sets of
+   resources), and not just a single resource.  In this case, it makes
+   sense for the API to define rules about how an announced sunset on a
+   specific resource (such as the API's home/start resource) implies the
+   sunsetting of the whole API or parts of it (i.e., sets of resources),
+   and not just the resource returning the sunset header field.
+   Section 5 discusses how the scope of the Sunset header field may
+   change because of how a resource is using it.
+
+2.  Terminology
+
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
+   "OPTIONAL" in this document are to be interpreted as described in
+   BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all
+   capitals, as shown here.
+
+3.  The Sunset HTTP Response Header Field
+
+   The Sunset HTTP response header field allows a server to communicate
+   the fact that a resource is expected to become unresponsive at a
+   specific point in time.  It provides information for clients that
+   they can use to control their usage of the resource.
+
+   The Sunset header field contains a single timestamp that advertises
+   the point in time when the resource is expected to become
+   unresponsive.  The Sunset value is an HTTP-date timestamp, as defined
+   in Section 7.1.1.1 of [RFC7231], and SHOULD be a timestamp in the
+   future.
+
+   It is safest to consider timestamps in the past mean the present
+   time, meaning that the resource is expected to become unavailable at
+   any time.
+
+   Sunset = HTTP-date
+
+   For example:
+
+   Sunset: Sat, 31 Dec 2018 23:59:59 GMT
+
+
+
+
+
+
+
+Wilde                         Informational                     [Page 4]
+
+RFC 8594                      Sunset Header                     May 2019
+
+
+   Clients SHOULD treat Sunset timestamps as hints: it is not guaranteed
+   that the resource will, in fact, be available until that time and
+   will not be available after that time.  However, since this
+   information is provided by the resource itself, it does have some
+   credibility.
+
+   After the Sunset time has arrived, it is likely that interactions
+   with the resource will result in client-side errors (HTTP 4xx status
+   codes), redirect responses (HTTP 3xx status codes), or the client
+   might not be able to interact with the resource at all.  The Sunset
+   header field does not expose any information about which of those
+   behaviors can be expected.
+
+   Clients not interpreting an existing Sunset header field can operate
+   as usual and simply may experience the resource becoming unavailable
+   without recognizing any notification about it beforehand.
+
+4.  Sunset and Caching
+
+   It should be noted that the Sunset HTTP response header field serves
+   a different purpose than HTTP caching [RFC7234].  HTTP caching is
+   concerned with making resource representations (i.e., represented
+   resource state) reusable so that they can be used more efficiently.
+   This is achieved by using header fields that allow clients and
+   intermediaries to better understand when a resource representation
+   can be reused or when resource state (and, thus, the representation)
+   may have changed.
+
+   The Sunset header field is not concerned with resource state at all.
+   It only signals that a resource is expected to become unavailable at
+   a specific point in time.  There are no assumptions about if, when,
+   or how often a resource may change state in the meantime.
+
+   For these reasons, the Sunset header field and HTTP caching should be
+   seen as complementary and not as overlapping in scope and
+   functionality.
+
+   This also means that applications acting as intermediaries, such as
+   search engines or archives that make resources discoverable, should
+   treat Sunset information differently from caching information.  These
+   applications may use Sunset information for signaling to users that a
+   resource may become unavailable.  But they still have to account for
+   the fact that resource state can change in the meantime and that
+   Sunset information is a hint and, thus, future resource availability
+   may differ from the advertised timestamp.
+
+
+
+
+
+
+Wilde                         Informational                     [Page 5]
+
+RFC 8594                      Sunset Header                     May 2019
+
+
+5.  Sunset Scope
+
+   The Sunset header field applies to the resource that returns it,
+   meaning that it announces the upcoming sunset of that specific
+   resource.  However, as discussed in Section 1.4, there may be
+   scenarios where the scope of the announced Sunset information is
+   larger than just the single resource where it appears.
+
+   Resources are free to define such an increased scope, and usually
+   this scope will be documented by the resource so that consumers of
+   the resource know about the increased scope and can behave
+   accordingly.  However, it is important to take into account that such
+   increased scoping is invisible for consumers who are unaware of the
+   increased scoping rules.  This means that these consumers will not be
+   aware of the increased scope, and they will not interpret Sunset
+   information different from its standard meaning (i.e., it applies to
+   the resource only).
+
+   Using such an increased scope still may make sense, as Sunset
+   information is only a hint anyway; thus, it is optional information
+   that cannot be depended on, and clients should always be implemented
+   in ways that allow them to function without Sunset information.
+   Increased scope information may help clients to glean additional
+   hints from resources (e.g., concluding that an API is being
+   deprecated because its home/start resource announces a Sunset) and,
+   thus, might allow them to implement behavior that allows them to make
+   educated guesses about resources becoming unavailable.
+
+6.  The Sunset Link Relation Type
+
+   The Sunset HTTP header field indicates the upcoming retirement of a
+   resource or a service.  In addition, a resource may want to make
+   information available that provides additional information about how
+   retirement will be handled for resources or services.  This
+   information can be broadly described by the following three topics:
+
+   Sunset policy:  The policy for which resources and in which way
+         sunsets may occur may be published as part of service's
+         description.  Sunsets may only/mostly affect a subset of a
+         service's resources, and they may be exposed according to a
+         certain policy (e.g., one week in advance).
+
+   Upcoming sunset:  There may be additional information about an
+         upcoming sunset, which can be published as a resource that can
+         be consumed by those looking for this additional information.
+
+
+
+
+
+
+Wilde                         Informational                     [Page 6]
+
+RFC 8594                      Sunset Header                     May 2019
+
+
+   Sunset mitigation:  There may be information about possible
+         mitigation/migration strategies, such as possible ways how
+         resource users can switch to alternative resources/services.
+
+   Any information regarding the above issues (and possibly additional
+   ones) can be made available through a URI that then can be linked to
+   using the sunset link relation type.  This specification places no
+   constraints on the scope or the type of the linked resource.  The
+   scope can be for a resource or for a service.  The type is determined
+   by the media type of the linked resource and can be targeted to
+   humans, machines, or both.
+
+   If the linked resource does provide machine-readable information,
+   consumers should be careful before acting on this information.  Such
+   information may, for example, instruct consumers to use a migration
+   rule so that sunset resources can be accessed at new URIs.  However,
+   this kind of information amounts to a possibly large-scale identity
+   migration of resources, so it is crucial that the migration
+   information is authentic and accurate.
+
+7.  IANA Considerations
+
+7.1.  The Sunset Response Header Field
+
+   The Sunset response header field has been added to the "Permanent
+   Message Header Field Names" registry (see [RFC3864]), taking into
+   account the guidelines given by HTTP/1.1 [RFC7231].
+
+      Header Field Name: Sunset
+
+      Protocol: http
+
+      Status: informational
+
+      Author/Change controller: IETF
+
+      Reference: RFC 8594
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Wilde                         Informational                     [Page 7]
+
+RFC 8594                      Sunset Header                     May 2019
+
+
+7.2.  The Sunset Link Relation Type
+
+   The sunset link relation type has been added to the permanent "Link
+   Relation Types" registry according to Section 4.2 of [RFC8288]:
+
+      Relation Name: sunset
+
+      Description: Identifies a resource that provides information about
+      the context's retirement policy.
+
+      Reference: RFC 8594
+
+8.  Security Considerations
+
+   Generally speaking, information about upcoming sunsets can leak
+   information that otherwise might not be available.  For example, a
+   resource representing a registration can leak information about the
+   expiration date when it exposes sunset information.  For this reason,
+   any use of sunset information where the sunset represents an
+   expiration or allows the calculation of another date (such as
+   calculating a creation date because it is known that resources expire
+   after one year) should be treated in the same way as if this
+   information would be made available directly in the resource's
+   representation.
+
+   The Sunset header field SHOULD be treated as a resource hint, meaning
+   that the resource is indicating (and not guaranteeing with certainty)
+   its potential retirement.  The definitive test whether or not the
+   resource in fact is available will be to attempt to interact with it.
+   Applications should never treat an advertised Sunset date as a
+   definitive prediction of what is going to happen at the specified
+   point in time: the Sunset indication may have been inserted by an
+   intermediary or the advertised date may get changed or withdrawn by
+   the resource owner.
+
+   The main purpose of the Sunset header field is to signal intent so
+   that applications using resources may get a warning ahead of time and
+   can react accordingly.  What an appropriate reaction is (such as
+   switching to a different resource or service), what it will be based
+   on (such as machine-readable formats that allow the switching to be
+   done automatically), and when it will happen (such as ahead of the
+   advertised date or only when the resource in fact becomes
+   unavailable) is outside the scope of this specification.
+
+   In cases where a sunset policy is linked by using the sunset link
+   relation type, clients SHOULD be careful about taking any actions
+   based on this information.  It SHOULD be verified that the
+   information is authentic and accurate.  Furthermore, it SHOULD be
+
+
+
+Wilde                         Informational                     [Page 8]
+
+RFC 8594                      Sunset Header                     May 2019
+
+
+   tested that this information is only applied to resources that are
+   within the scope of the policy, making sure that sunset policies
+   cannot "hijack" resources by for example providing migration
+   information for them.
+
+9.  Example
+
+   If a resource has been created in an archive that, for management or
+   compliance reasons, stores resources for ten years and permanently
+   deletes them afterwards, the Sunset header field can be used to
+   expose this information.  If such a resource has been created on
+   November 11, 2016, then the following header field can be included in
+   responses:
+
+   Sunset: Wed, 11 Nov 2026 11:11:11 GMT
+
+   This allows clients that are aware of the Sunset header field to
+   understand that the resource likely will become unavailable at the
+   specified point in time.  Clients can decide to ignore this
+   information, adjust their own behavior accordingly, or alert
+   applications or users about this timestamp.
+
+   Even though the Sunset header field is made available by the resource
+   itself, there is no guarantee that the resource indeed will become
+   unavailable, and if so, how the response will look like for requests
+   made after that timestamp.  In case of the archive used as an example
+   here, the resource indeed may be permanently deleted, and requests
+   for the URI after the Sunset timestamp may receive a "410 Gone" HTTP
+   response.  (This is assuming that the archive keeps track of the URIs
+   that it had previously assigned; if not, the response may be a more
+   generic "404 Not Found".)
+
+   Before the Sunset header field even appears for the first time (it
+   may not appear from the very beginning), it is possible that the
+   resource (or possibly just the "home" resource of the service
+   context) communicates its sunset policy by using the sunset link
+   relation type.  If communicated as an HTTP header field, it might
+   look as follows:
+
+   Link: <http://example.net/sunset>;rel="sunset";type="text/html"
+
+   In this case, the linked resource provides sunset policy information
+   about the service context.  It may be documentation aimed at
+   developers, for example, informing them that the lifetime of a
+   certain class of resources is ten years after creation and that
+   Sunset header fields will be served as soon as the sunset date is
+
+
+
+
+
+Wilde                         Informational                     [Page 9]
+
+RFC 8594                      Sunset Header                     May 2019
+
+
+   less than some given period of time.  It may also inform developers
+   whether the service will respond with 410 or 404 after the sunset
+   time, as discussed above.
+
+10.  References
+
+10.1.  Normative References
+
+   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119,
+              DOI 10.17487/RFC2119, March 1997,
+              <https://www.rfc-editor.org/info/rfc2119>.
+
+   [RFC3864]  Klyne, G., Nottingham, M., and J. Mogul, "Registration
+              Procedures for Message Header Fields", BCP 90, RFC 3864,
+              DOI 10.17487/RFC3864, September 2004,
+              <https://www.rfc-editor.org/info/rfc3864>.
+
+   [RFC7231]  Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer
+              Protocol (HTTP/1.1): Semantics and Content", RFC 7231,
+              DOI 10.17487/RFC7231, June 2014,
+              <https://www.rfc-editor.org/info/rfc7231>.
+
+   [RFC8174]  Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
+              2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
+              May 2017, <https://www.rfc-editor.org/info/rfc8174>.
+
+   [RFC8288]  Nottingham, M., "Web Linking", RFC 8288,
+              DOI 10.17487/RFC8288, October 2017,
+              <https://www.rfc-editor.org/info/rfc8288>.
+
+10.2.  Informative References
+
+   [RFC7234]  Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke,
+              Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching",
+              RFC 7234, DOI 10.17487/RFC7234, June 2014,
+              <https://www.rfc-editor.org/info/rfc7234>.
+
+Acknowledgements
+
+   Thanks for comments and suggestions provided by Ben Campbell, Alissa
+   Cooper, Benjamin Kaduk, Mirja Kuhlewind, Adam Roach, Phil Sturgeon,
+   and Asbjorn Ulsberg.
+
+
+
+
+
+
+
+
+Wilde                         Informational                    [Page 10]
+
+RFC 8594                      Sunset Header                     May 2019
+
+
+Author's Address
+
+   Erik Wilde
+
+   Email: erik.wilde@dret.net
+   URI:   http://dret.net/netdret/
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Wilde                         Informational                    [Page 11]
+