doc: Add RFC documents

1 files changed, 395 insertions, 0 deletions

diff --git a/doc/rfc/rfc7168.txt b/doc/rfc/rfc7168.txt
new file mode 100644
index 0000000..e516664
--- /dev/null
+++ b/doc/rfc/rfc7168.txt
@@ -0,0 +1,395 @@
+
+
+
+
+
+
+Independent Submission                                          I. Nazar
+Request for Comments: 7168                                  1 April 2014
+Updates: 2324
+Category: Informational
+ISSN: 2070-1721
+
+
+               The Hyper Text Coffee Pot Control Protocol
+                 for Tea Efflux Appliances (HTCPCP-TEA)
+
+Abstract
+
+   The Hyper Text Coffee Pot Control Protocol (HTCPCP) specification
+   does not allow for the brewing of tea, in all its variety and
+   complexity.  This paper outlines an extension to HTCPCP to allow for
+   pots to provide networked tea-brewing facilities.
+
+Status of This Memo
+
+   This document is not an Internet Standards Track specification; it is
+   published for informational purposes.
+
+   This is a contribution to the RFC Series, independently of any other
+   RFC stream.  The RFC Editor has chosen to publish this document at
+   its discretion and makes no statement about its value for
+   implementation or deployment.  Documents approved for publication by
+   the RFC Editor are not a candidate for any level of Internet
+   Standard; see Section 2 of RFC 5741.
+
+   Information about the current status of this document, any errata,
+   and how to provide feedback on it may be obtained at
+   http://www.rfc-editor.org/info/rfc7168.
+
+Copyright Notice
+
+   Copyright (c) 2014 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
+   (http://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.
+
+
+
+
+
+
+
+Nazar                         Informational                     [Page 1]
+
+RFC 7168                       HTCPCP-TEA                   1 April 2014
+
+
+Table of Contents
+
+   1. Introduction  . . . . . . . . . . . . . . . . . . . . . . . . .  2
+     1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . .  3
+   2. HTCPCP-TEA Protocol Additions . . . . . . . . . . . . . . . . .  3
+     2.1. BREW and POST Methods . . . . . . . . . . . . . . . . . . .  3
+       2.1.1. The "/" URI . . . . . . . . . . . . . . . . . . . . . .  3
+       2.1.2. Variety-Specific URIs . . . . . . . . . . . . . . . . .  4
+     2.2. Modified Header Fields  . . . . . . . . . . . . . . . . . .  4
+       2.2.1. The Accept-Additions Header Field . . . . . . . . . . .  4
+     2.3. Response Codes  . . . . . . . . . . . . . . . . . . . . . .  5
+       2.3.1. 300 Multiple Options  . . . . . . . . . . . . . . . . .  5
+       2.3.2. 403 Forbidden . . . . . . . . . . . . . . . . . . . . .  5
+       2.3.3. 418 I'm a Teapot  . . . . . . . . . . . . . . . . . . .  5
+   3. The "message/teapot" Media Type . . . . . . . . . . . . . . . .  6
+   4. Environmental Considerations  . . . . . . . . . . . . . . . . .  6
+   5. Security Considerations . . . . . . . . . . . . . . . . . . . .  6
+   6. Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . .  7
+   7. References  . . . . . . . . . . . . . . . . . . . . . . . . . .  7
+     7.1. Normative References  . . . . . . . . . . . . . . . . . . .  7
+     7.2. Informative References  . . . . . . . . . . . . . . . . . .  7
+
+1.  Introduction
+
+   As noted in the Hyper Text Coffee Pot Control Protocol [HTCPCP],
+   coffee is renowned worldwide as an artfully brewed caffeinated
+   beverage, but coffee shares this quality with many other varied
+   preparations based on the filtration of plant material.  Foremost,
+   among these are the category of brews based on the straining of water
+   through prepared leaves from a tea tree: the lineage and history of
+   the tea genus will not be recounted as part of this paper, but
+   evidence shows that the production of tea existed many thousands of
+   years ago.
+
+   The deficiency of HTCPCP in addressing the networked production of
+   such a venerable beverage as tea is noteworthy: indeed, the only
+   provision given for networked teapots is that they not respond to
+   requests for the production of coffee, which, while eminently
+   reasonable, does not allow for communication with the teapot for its
+   intended purpose.
+
+   This paper specifies an extension to HTCPCP to allow communication
+   with networked tea production devices and teapots.  The additions to
+   the protocol specified herein permit the requests and responses
+   necessary to control all devices capable of making, arguably, the
+   most popular caffeinated hot beverage.
+
+
+
+
+
+Nazar                         Informational                     [Page 2]
+
+RFC 7168                       HTCPCP-TEA                   1 April 2014
+
+
+1.1.  Terminology
+
+   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
+   "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+   document are to be interpreted as described in RFC 2119 [KEYWORDS].
+
+2.  HTCPCP-TEA Protocol Additions
+
+   The TEA extension to HTCPCP adapts the operation of certain HTCPCP
+   methods.
+
+2.1.  BREW and POST Methods
+
+   Control of a TEA-capable pot is performed, as described in the base
+   HTCPCP specification, through the sending of BREW requests.  POST
+   requests are treated equivalently, but they remain deprecated.  Tea
+   production differs from coffee, however, in that a choice of teas is
+   often provided for client selection before the tea is brewed.  To
+   this end, a TEA-capable pot that receives a BREW message of content
+   type "message/teapot" MUST respond in accordance with the URI
+   requested, as below.
+
+2.1.1.  The "/" URI
+
+   For the URI "/", brewing will not commence.  Instead, an Alternates
+   header as defined in RFC 2295 [RFC2295] MUST be sent, with the
+   available tea bags and/or leaf varieties as entries.  An example of
+   such a response is as follows:
+
+      Alternates: {"/darjeeling" {type message/teapot}},
+                  {"/earl-grey" {type message/teapot}},
+                  {"/peppermint" {type message/teapot}}
+
+   The following example demonstrates the possibility of
+   interoperability of a TEA-capable pot that also complies with the
+   base HTCPCP specification:
+
+      Alternates: {"/" {type message/coffeepot}},
+                  {"/pot-0/darjeeling" {type message/teapot}},
+                  {"/pot-0/earl-grey" {type message/teapot}},
+                  {"/pot-1/peppermint" {type message/teapot}}
+
+   TEA-capable HTCPCP clients MUST check the contents of the Alternates
+   header returned by a BREW request, and provide a specific URI for
+   subsequent requests of the "message/teapot" type.
+
+
+
+
+
+
+Nazar                         Informational                     [Page 3]
+
+RFC 7168                       HTCPCP-TEA                   1 April 2014
+
+
+   A request to the "/" URI with a Content-Type header of
+   "message/coffeepot" SHOULD also be responded to with an Alternates
+   header in the above format, to allow TEA-capable clients the
+   opportunity to present the selection of teas to the user if inferior
+   caffeinated beverages have initially been requested.
+
+2.1.2.  Variety-Specific URIs
+
+   TEA-capable pots follow the base HTCPCP specification when presented
+   with a BREW request for a specific variety of tea.  Pots SHOULD
+   follow the recommendations for brewing strength given by each
+   variety, and stop brewing when this strength is reached; it is
+   suggested that the strength be measured by detection of the opacity
+   of the beverage currently under brew by the pot.
+
+   TEA-capable clients SHOULD indicate the end of brewing by sending a
+   BREW request with an entity body containing "stop"; the pot MAY
+   continue brewing beyond the recommended strength until this is
+   received.  If the "stop" request is not sent by the client, this may
+   result in a state inversion in the proportion of tea to water in the
+   brewing pot, which may be reported by some pots as a negative
+   strength.
+
+   If a BREW command with an entity body containing "stop" is received
+   before the recommended strength is achieved, the pot MUST abort
+   brewing and serve the resultant beverage at lesser strength.  Finding
+   the preferred strength of beverage when using this override is a
+   function of the time between the TEA-capable pot receiving a "start"
+   request and the subsequent "stop".  Clients SHOULD be prepared to
+   make multiple attempts to reach the preferred strength.
+
+2.2.  Modified Header Fields
+
+   HTCPCP-TEA modifies the definition of one header field from the base
+   HTCPCP specification.
+
+2.2.1.  The Accept-Additions Header Field
+
+   It has been observed that some users of blended teas have an
+   occasional preference for teas brewed as an emulsion of cane sugar
+   with hints of water.  To allow for this circumstance, the Accept-
+   Additions header field defined in the base HTCPCP specification is
+   updated to allow the following options:
+
+
+
+
+
+
+
+
+Nazar                         Informational                     [Page 4]
+
+RFC 7168                       HTCPCP-TEA                   1 April 2014
+
+
+      addition-type   = ( "*"
+                        | milk-type
+                        | syrup-type
+                        | sweetener-type
+                        | spice-type
+                        | alcohol-type
+                        | sugar-type
+                        ) *( ";" parameter )
+      sugar-type      = ( "Sugar" | "Xylitol" | "Stevia" )
+
+   Implementers should be aware that excessive use of the Sugar addition
+   may cause the BREW request to exceed the segment size allowed by the
+   transport layer, causing fragmentation and a delay in brewing.
+
+2.3.  Response Codes
+
+   HTCPCP-TEA makes use of normal HTTP error codes and those defined in
+   the base HTCPCP specification.
+
+2.3.1.  300 Multiple Options
+
+   A BREW request to the "/" URI, as defined in Section 2.1.1, will
+   return an Alternates header indicating the URIs of the available
+   varieties of tea to brew.  It is RECOMMENDED that this response be
+   served with a status code of 300, to indicate that brewing has not
+   commenced and further options must be chosen by the client.
+
+2.3.2.  403 Forbidden
+
+   Services that implement the Accept-Additions header field MAY return
+   a 403 status code for a BREW request of a given variety of tea, if
+   the service deems the combination of additions requested to be
+   contrary to the sensibilities of a consensus of drinkers regarding
+   the variety in question.
+
+   A method of garnering and collating consensus indicators of the most
+   viable combinations of additions for each variety to be served is
+   outside the scope of this document.
+
+2.3.3.  418 I'm a Teapot
+
+   TEA-capable pots that are not provisioned to brew coffee may return
+   either a status code of 503, indicating temporary unavailability of
+   coffee, or a code of 418 as defined in the base HTCPCP specification
+   to denote a more permanent indication that the pot is a teapot.
+
+
+
+
+
+
+Nazar                         Informational                     [Page 5]
+
+RFC 7168                       HTCPCP-TEA                   1 April 2014
+
+
+3.  The "message/teapot" Media Type
+
+   To distinguish messages destined for TEA-capable HTCPCP services from
+   pots compliant with the base HTCPCP specification, a new MIME media
+   type is defined by this document.  The Content-Type header of a POST
+   or BREW request sent to a TEA-capable pot MUST be "message/teapot" if
+   tea is to be requested.
+
+4.  Environmental Considerations
+
+   As noted in Section 2.1, a BREW request with a Content-Type header
+   field of "message/teapot" to a TEA-capable pot will result in an
+   Alternates header being sent with the response, and a pot will not be
+   brewed.  However, if the BREW request has a Content-Type of
+   "message/coffeepot", and the pot is capable of brewing coffee, the
+   service's behavior will fall back to the base HTCPCP specification
+   and a pot will be brewed.
+
+   If the entity returned by the server when brewing commences contains
+   a TEA-compliant Alternates header indicating "message/coffeepot" and
+   the client does not want coffee, the client SHOULD then send a BREW
+   request with an entity body containing "stop".  This will result in
+   wasted coffee; whether this is regarded as a bad thing is user-
+   defined.
+
+   Such waste can be prevented by TEA-capable clients, by first
+   requesting a BREW of type "message/teapot" and then allowing
+   selection of an available beverage.
+
+5.  Security Considerations
+
+   As with the base HTCPCP specification, most TEA-capable pots are
+   expected to heat water through the use of electric elements, and as
+   such will not be in proximity to fire.  Therefore, no firewalls are
+   necessary for communication with these pots to proceed.
+
+   This extension does support communication with fired pots, however,
+   which may require heat retention and control policies.  Care should
+   be taken so that coal-fired pots and electrically heated kettles are
+   not connected to the same network, to prevent pots from referring to
+   any kettles on the network as darkened or otherwise smoke driven.
+
+
+
+
+
+
+
+
+
+
+Nazar                         Informational                     [Page 6]
+
+RFC 7168                       HTCPCP-TEA                   1 April 2014
+
+
+6.  Acknowledgements
+
+   This extension to the HTCPCP specification would not be possible
+   without the base specification, and research on networked beverage
+   production leading up thereto.  In that vein, the author wishes to
+   acknowledge the sterling work of Larry Masinter in the development of
+   the leading protocol for coffee pot communication.
+
+   Many thanks also to Kevin Waterson and Pete Davis, for providing
+   guidance and suggestions during the drafting of this document.
+
+7.  References
+
+7.1.  Normative References
+
+   [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate
+              Requirement Levels", BCP 14, RFC 2119, March 1997.
+
+7.2.  Informative References
+
+   [HTCPCP]   Masinter, L., "Hyper Text Coffee Pot Control Protocol
+              (HTCPCP/1.0)", RFC 2324, April 1 1998.
+
+   [RFC2295]  Holtman, K. and A. Mutz, "Transparent Content Negotiation
+              in HTTP", RFC 2295, March 1998.
+
+Author's Address
+
+   Imran Nazar
+   deviantART Inc.
+   7095 Hollywood Blvd
+   Hollywood, CA 90028
+
+   EMail: inazar@deviantart.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Nazar                         Informational                     [Page 7]
+