doc: Add RFC documents

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]
+