diff options
Diffstat (limited to 'docs/specs/rfc2324.txt')
| -rw-r--r-- | docs/specs/rfc2324.txt | 563 |
1 files changed, 0 insertions, 563 deletions
diff --git a/docs/specs/rfc2324.txt b/docs/specs/rfc2324.txt deleted file mode 100644 index a85921a9..00000000 --- a/docs/specs/rfc2324.txt +++ /dev/null @@ -1,563 +0,0 @@ - - - - - - -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] - |