summaryrefslogtreecommitdiff
path: root/doc/rfc/rfc2324.txt
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rfc/rfc2324.txt')
-rw-r--r--doc/rfc/rfc2324.txt563
1 files changed, 563 insertions, 0 deletions
diff --git a/doc/rfc/rfc2324.txt b/doc/rfc/rfc2324.txt
new file mode 100644
index 0000000..a85921a
--- /dev/null
+++ b/doc/rfc/rfc2324.txt
@@ -0,0 +1,563 @@
+
+
+
+
+
+
+Network Working Group L. Masinter
+Request for Comments: 2324 1 April 1998
+Category: Informational
+
+
+ Hyper Text Coffee Pot Control Protocol (HTCPCP/1.0)
+
+Status of this Memo
+
+ This memo provides information for the Internet community. It does
+ not specify an Internet standard of any kind. Distribution of this
+ memo is unlimited.
+
+Copyright Notice
+
+ Copyright (C) The Internet Society (1998). All Rights Reserved.
+
+Abstract
+
+ This document describes HTCPCP, a protocol for controlling,
+ monitoring, and diagnosing coffee pots.
+
+1. Rationale and Scope
+
+ There is coffee all over the world. Increasingly, in a world in which
+ computing is ubiquitous, the computists want to make coffee. Coffee
+ brewing is an art, but the distributed intelligence of the web-
+ connected world transcends art. Thus, there is a strong, dark, rich
+ requirement for a protocol designed espressoly for the brewing of
+ coffee. Coffee is brewed using coffee pots. Networked coffee pots
+ require a control protocol if they are to be controlled.
+
+ Increasingly, home and consumer devices are being connected to the
+ Internet. Early networking experiments demonstrated vending devices
+ connected to the Internet for status monitoring [COKE]. One of the
+ first remotely _operated_ machine to be hooked up to the Internet,
+ the Internet Toaster, (controlled via SNMP) was debuted in 1990
+ [RFC2235].
+
+ The demand for ubiquitous appliance connectivity that is causing the
+ consumption of the IPv4 address space. Consumers want remote control
+ of devices such as coffee pots so that they may wake up to freshly
+ brewed coffee, or cause coffee to be prepared at a precise time after
+ the completion of dinner preparations.
+
+
+
+
+
+
+
+Masinter Informational [Page 1]
+
+RFC 2324 HTCPCP/1.0 1 April 1998
+
+
+ This document specifies a Hyper Text Coffee Pot Control Protocol
+ (HTCPCP), which permits the full request and responses necessary to
+ control all devices capable of making the popular caffeinated hot
+ beverages.
+
+ HTTP 1.1 ([RFC2068]) permits the transfer of web objects from origin
+ servers to clients. The web is world-wide. HTCPCP is based on HTTP.
+ This is because HTTP is everywhere. It could not be so pervasive
+ without being good. Therefore, HTTP is good. If you want good coffee,
+ HTCPCP needs to be good. To make HTCPCP good, it is good to base
+ HTCPCP on HTTP.
+
+ Future versions of this protocol may include extensions for espresso
+ machines and similar devices.
+
+2. HTCPCP Protocol
+
+ The HTCPCP protocol is built on top of HTTP, with the addition of a
+ few new methods, header fields and return codes. All HTCPCP servers
+ should be referred to with the "coffee:" URI scheme (Section 4).
+
+2.1 HTCPCP Added Methods
+
+2.1.1 The BREW method, and the use of POST
+
+ Commands to control a coffee pot are sent from client to coffee
+ server using either the BREW or POST method, and a message body with
+ Content-Type set to "application/coffee-pot-command".
+
+ A coffee pot server MUST accept both the BREW and POST method
+ equivalently. However, the use of POST for causing actions to happen
+ is deprecated.
+
+ Coffee pots heat water using electronic mechanisms, so there is no
+ fire. Thus, no firewalls are necessary, and firewall control policy
+ is irrelevant. However, POST may be a trademark for coffee, and so
+ the BREW method has been added. The BREW method may be used with
+ other HTTP-based protocols (e.g., the Hyper Text Brewery Control
+ Protocol).
+
+2.1.2 GET method
+
+ In HTTP, the GET method is used to mean "retrieve whatever
+ information (in the form of an entity) identified by the Request-
+ URI." If the Request-URI refers to a data-producing process, it is
+ the produced data which shall be returned as the entity in the
+ response and not the source text of the process, unless that text
+ happens to be the output of the process.
+
+
+
+Masinter Informational [Page 2]
+
+RFC 2324 HTCPCP/1.0 1 April 1998
+
+
+ In HTCPCP, the resources associated with a coffee pot are physical,
+ and not information resources. The "data" for most coffee URIs
+ contain no caffeine.
+
+2.1.3 PROPFIND method
+
+ If a cup of coffee is data, metadata about the brewed resource is
+ discovered using the PROPFIND method [WEBDAV].
+
+2.1.4 WHEN method
+
+ When coffee is poured, and milk is offered, it is necessary for the
+ holder of the recipient of milk to say "when" at the time when
+ sufficient milk has been introduced into the coffee. For this
+ purpose, the "WHEN" method has been added to HTCPCP. Enough? Say
+ WHEN.
+
+2.2 Coffee Pot Header fields
+
+ HTCPCP recommends several HTTP header fields and defines some new
+ ones.
+
+2.2.1 Recommended header fields
+
+2.2.1.1 The "safe" response header field.
+
+ [SAFE] defines a HTTP response header field, "Safe", which can be
+ used to indicate that repeating a HTTP request is safe. The inclusion
+ of a "Safe: Yes" header field allows a client to repeat a previous
+ request if the result of the request might be repeated.
+
+ The actual safety of devices for brewing coffee varies widely, and
+ may depend, in fact, on conditions in the client rather than just in
+ the server. Thus, this protocol includes an extension to the "Safe"
+ response header:
+
+ Safe = "Safe" ":" safe-nature
+ safe-nature = "yes" | "no" | conditionally-safe
+ conditionally-safe = "if-" safe-condition
+ safe-condition = "user-awake" | token
+
+ indication will allow user agents to handle retries of some safe
+ requests, in particular safe POST requests, in a more user-friendly
+ way.
+
+
+
+
+
+
+
+Masinter Informational [Page 3]
+
+RFC 2324 HTCPCP/1.0 1 April 1998
+
+
+2.2.2 New header fields
+
+2.2.2.1 The Accept-Additions header field
+
+ In HTTP, the "Accept" request-header field is used to specify media
+ types which are acceptable for the response. However, in HTCPCP, the
+ response may result in additional actions on the part of the
+ automated pot. For this reason, HTCPCP adds a new header field,
+ "Accept-Additions":
+
+
+ Accept-Additions = "Accept-Additions" ":"
+ #( addition-range [ accept-params ] )
+
+ addition-type = ( "*"
+ | milk-type
+ | syrup-type
+ | sweetener-type
+ | spice-type
+ | alcohol-type
+ ) *( ";" parameter )
+ milk-type = ( "Cream" | "Half-and-half" | "Whole-milk"
+ | "Part-Skim" | "Skim" | "Non-Dairy" )
+ syrup-type = ( "Vanilla" | "Almond" | "Raspberry"
+ | "Chocolate" )
+ alcohol-type = ( "Whisky" | "Rum" | "Kahlua" | "Aquavit" )
+
+2.2.3 Omitted Header Fields
+
+ No options were given for decaffeinated coffee. What's the point?
+
+2.3 HTCPCP return codes
+
+ Normal HTTP return codes are used to indicate difficulties of the
+ HTCPCP server. This section identifies special interpretations and
+ new return codes.
+
+2.3.1 406 Not Acceptable
+
+ This return code is normally interpreted as "The resource identified
+ by the request is only capable of generating response entities which
+ have content characteristics not acceptable according to the accept
+ headers sent in the request. In HTCPCP, this response code MAY be
+ returned if the operator of the coffee pot cannot comply with the
+ Accept-Addition request. Unless the request was a HEAD request, the
+ response SHOULD include an entity containing a list of available
+ coffee additions.
+
+
+
+
+Masinter Informational [Page 4]
+
+RFC 2324 HTCPCP/1.0 1 April 1998
+
+
+ In practice, most automated coffee pots cannot currently provide
+ additions.
+
+2.3.2 418 I'm a teapot
+
+ Any attempt to brew coffee with a teapot should result in the error
+ code "418 I'm a teapot". The resulting entity body MAY be short and
+ stout.
+
+3. The "coffee" URI scheme
+
+ Because coffee is international, there are international coffee URI
+ schemes. All coffee URL schemes are written with URL encoding of the
+ UTF-8 encoding of the characters that spell the word for "coffee" in
+ any of 29 languages, following the conventions for
+ internationalization in URIs [URLI18N].
+
+coffee-url = coffee-scheme ":" [ "//" host ]
+ ["/" pot-designator ] ["?" additions-list ]
+
+coffee-scheme = ( "koffie" ; Afrikaans, Dutch
+ | "q%C3%A6hv%C3%A6" ; Azerbaijani
+ | "%D9%82%D9%87%D9%88%D8%A9" ; Arabic
+ | "akeita" ; Basque
+ | "koffee" ; Bengali
+ | "kahva" ; Bosnian
+ | "kafe" ; Bulgarian, Czech
+ | "caf%C3%E8" ; Catalan, French, Galician
+ | "%E5%92%96%E5%95%A1" ; Chinese
+ | "kava" ; Croatian
+ | "k%C3%A1va ; Czech
+ | "kaffe" ; Danish, Norwegian, Swedish
+ | "coffee" ; English
+ | "kafo" ; Esperanto
+ | "kohv" ; Estonian
+ | "kahvi" ; Finnish
+ | "%4Baffee" ; German
+ | "%CE%BA%CE%B1%CF%86%CE%AD" ; Greek
+ | "%E0%A4%95%E0%A5%8C%E0%A4%AB%E0%A5%80" ; Hindi
+ | "%E3%82%B3%E3%83%BC%E3%83%92%E3%83%BC" ; Japanese
+ | "%EC%BB%A4%ED%94%BC" ; Korean
+ | "%D0%BA%D0%BE%D1%84%D0%B5" ; Russian
+ | "%E0%B8%81%E0%B8%B2%E0%B9%81%E0%B8%9F" ; Thai
+ )
+
+ pot-designator = "pot-" integer ; for machines with multiple pots
+ additions-list = #( addition )
+
+
+
+
+Masinter Informational [Page 5]
+
+RFC 2324 HTCPCP/1.0 1 April 1998
+
+
+ All alternative coffee-scheme forms are equivalent. However, the use
+ of coffee-scheme in various languages MAY be interpreted as an
+ indication of the kind of coffee produced by the coffee pot. Note
+ that while URL scheme names are case-independent, capitalization is
+ important for German and thus the initial "K" must be encoded.
+
+4. The "message/coffeepot" media type
+
+ The entity body of a POST or BREW request MUST be of Content-Type
+ "message/coffeepot". Since most of the information for controlling
+ the coffee pot is conveyed by the additional headers, the content of
+ "message/coffeepot" contains only a coffee-message-body:
+
+ coffee-message-body = "start" | "stop"
+
+5. Operational constraints
+
+ This section lays out some of the operational issues with deployment
+ of HTCPCP ubiquitously.
+
+5.1 Timing Considerations
+
+ A robust quality of service is required between the coffee pot user
+ and the coffee pot service. Coffee pots SHOULD use the Network Time
+ Protocol [NTP] to synchronize their clocks to a globally accurate
+ time standard.
+
+ Telerobotics has been an expensive technology. However, with the
+ advent of the Cambridge Coffee Pot [CAM], the use of the web (rather
+ than SNMP) for remote system monitoring and management has been
+ proven. Additional coffee pot maintenance tasks might be
+ accomplished by remote robotics.
+
+ Web data is normally static. Therefore to save data transmission and
+ time, Web browser programs store each Web page retrieved by a user on
+ the user's computer. Thus, if the user wants to return to that page,
+ it is now stored locally and does not need to be requested again from
+ the server. An image used for robot control or for monitoring a
+ changing scene is dynamic. A fresh version needs to be retrieved from
+ the server each time it is accessed.
+
+5.2 Crossing firewalls
+
+ In most organizations HTTP traffic crosses firewalls fairly easily.
+ Modern coffee pots do not use fire. However, a "firewall" is useful
+ for protection of any source from any manner of heat, and not just
+ fire. Every home computer network SHOULD be protected by a firewall
+ from sources of heat. However, remote control of coffee pots is
+
+
+
+Masinter Informational [Page 6]
+
+RFC 2324 HTCPCP/1.0 1 April 1998
+
+
+ important from outside the home. Thus, it is important that HTCPCP
+ cross firewalls easily.
+
+ By basing HTCPCP on HTTP and using port 80, it will get all of HTTP's
+ firewall-crossing virtues. Of course, the home firewalls will require
+ reconfiguration or new versions in order to accommodate HTCPCP-
+ specific methods, headers and trailers, but such upgrades will be
+ easily accommodated. Most home network system administrators drink
+ coffee, and are willing to accommodate the needs of tunnelling
+ HTCPCP.
+
+6. System management considerations
+
+ Coffee pot monitoring using HTTP protocols has been an early
+ application of the web. In the earliest instance, coffee pot
+ monitoring was an early (and appropriate) use of ATM networks [CAM].
+
+ The traditional technique [CAM] was to attach a frame-grabber to a
+ video camera, and feed the images to a web server. This was an
+ appropriate application of ATM networks. In this coffee pot
+ installation, the Trojan Room of Cambridge University laboratories
+ was used to give a web interface to monitor a common coffee pot. of
+ us involved in related research and, being poor, impoverished
+ academics, we only had one coffee filter machine between us, which
+ lived in the corridor just outside the Trojan Room. However, being
+ highly dedicated and hard-working academics, we got through a lot of
+ coffee, and when a fresh pot was brewed, it often didn't last long.
+
+ This service was created as the first application to use a new RPC
+ mechanism designed in the Cambridge Computer Laboratory - MSRPC2. It
+ runs over MSNL (Multi-Service Network Layer) - a network layer
+ protocol designed for ATM networks.
+
+ Coffee pots on the Internet may be managed using the Coffee Pot MIB
+ [CPMIB].
+
+7. Security Considerations
+
+ Anyone who gets in between me and my morning coffee should be
+ insecure.
+
+ Unmoderated access to unprotected coffee pots from Internet users
+ might lead to several kinds of "denial of coffee service" attacks.
+ The improper use of filtration devices might admit trojan grounds.
+ Filtration is not a good virus protection method.
+
+
+
+
+
+
+Masinter Informational [Page 7]
+
+RFC 2324 HTCPCP/1.0 1 April 1998
+
+
+ Putting coffee grounds into Internet plumbing may result in clogged
+ plumbing, which would entail the services of an Internet Plumber
+ [PLUMB], who would, in turn, require an Internet Plumber's Helper.
+
+ Access authentication will be discussed in a separate memo.
+
+8. Acknowledgements
+
+ Many thanks to the many contributors to this standard, including Roy
+ Fielding, Mark Day, Keith Moore, Carl Uno-Manros, Michael Slavitch,
+ and Martin Duerst. The inspiration of the Prancing Pony, the CMU
+ Coke Machine, the Cambridge Coffee Pot, the Internet Toaster, and
+ other computer controlled remote devices have led to this valuable
+ creation.
+
+9. References
+
+ [RFC2068] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., and T.
+ Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068,
+ January 1997.
+
+ [RFC2186] Wessels, D., and K. Claffy, "Internet Cache Protocol (ICP),
+ version 2," RFC 2186, September 1997
+
+ [CPMIB] Slavitch, M., "Definitions of Managed Objects for Drip-Type
+ Heated Beverage Hardware Devices using SMIv2", RFC 2325, 1 April
+ 1998.
+
+ [HTSVMP] Q. Stafford-Fraser, "Hyper Text Sandwich Van Monitoring
+ Protocol, Version 3.2". In preparation.
+
+ [RFC2295] Holtman, K., and A. Mutz, "Transparent Content Negotiation
+ in HTTP", RFC 2295, March 1998.
+
+ [SAFE] K. Holtman. "The Safe Response Header Field", September 1997.
+
+ [CAM] "The Trojan Room Coffee Machine", D. Gordon and M. Johnson,
+ University of Cambridge Computer Lab,
+ <http://www.cl.cam.ac.uk/coffee/coffee.html>
+
+ [CBIO] "The Trojan Room Coffee Pot, a (non-technical) biography", Q.
+ Stafford-Fraser, University of Cambridge Computer Lab,
+ <http://www.cl.cam.ac.uk/coffee/qsf/coffee.html>.
+
+ [RFC2235] Zakon, R., "Hobbes' Internet Timeline", FYI 32, RFC 2230,
+ November 1997. See also
+ <http://www.internode.com.au/images/toaster2.jpg>
+
+
+
+
+Masinter Informational [Page 8]
+
+RFC 2324 HTCPCP/1.0 1 April 1998
+
+
+ [NTP] Mills, D., "Network Time Protocol (Version 3) Specification,
+ Implementation and Analysis", RFC 1305, March 1992.
+
+ [URLI18N] Masinter, L., "Using UTF8 for non-ASCII Characters in
+ Extended URIs" Work in Progress.
+
+ [PLUMB] B. Metcalfe, "Internet Plumber of the Year: Jim Gettys",
+ Infoworld, February 2, 1998.
+
+ [COKE] D. Nichols, "Coke machine history", C. Everhart, "Interesting
+ uses of networking", <http://www-
+ cse.ucsd.edu/users/bsy/coke.history.txt>.
+
+10. Author's Address
+
+ Larry Masinter
+ Xerox Palo Alto Research Center
+ 3333 Coyote Hill Road
+ Palo Alto, CA 94304
+
+ EMail: masinter@parc.xerox.com
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Masinter Informational [Page 9]
+
+RFC 2324 HTCPCP/1.0 1 April 1998
+
+
+11. Full Copyright Statement
+
+ Copyright (C) The Internet Society (1998). All Rights Reserved.
+
+ This document and translations of it may be copied and furnished to
+ others, and derivative works that comment on or otherwise explain it
+ or assist in its implementation may be prepared, copied, published
+ and distributed, in whole or in part, without restriction of any
+ kind, provided that the above copyright notice and this paragraph are
+ included on all such copies and derivative works. However, this
+ document itself may not be modified in any way, such as by removing
+ the copyright notice or references to the Internet Society or other
+ Internet organizations, except as needed for the purpose of
+ developing Internet standards in which case the procedures for
+ copyrights defined in the Internet Standards process must be
+ followed, or as required to translate it into languages other than
+ English.
+
+ The limited permissions granted above are perpetual and will not be
+ revoked by the Internet Society or its successors or assigns.
+
+ This document and the information contained herein is provided on an
+ "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
+ TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
+ BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
+ HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
+ MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Masinter Informational [Page 10]
+