path: root/doc/rfc/rfc7168.txt

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]
^L
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]
^L
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]
^L
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]
^L
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]
^L
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]
^L
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]
^L