summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc7168.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc7168.txt')
-rw-r--r--doc/rfc/rfc7168.txt395
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]
+