RFC 2324
Hyper Text Coffee Pot Control Protocol (HTCPCP/1.0)
Hyper Text Coffee Pot Control Protocol (HTCPCP/1.0) ☕✨
okay bestie 🫶 we're doing RFC 2324 and it is literally the most iconic doc ever 😭 quick title-block tea: it's RFC number 2324, written by L. Masinter, dated 1 April 1998, and it's in the Informational category 💖 It came out through the Network Working Group 🧚 and the header doesn't list anything it obsoletes or updates, so it's not replacing or changing any other RFC 🌸
Status of this Memo ✨
This memo is giving information for the Internet community 🌈 It does not specify an Internet standard of any kind 💅 And distribution of this memo is unlimited 🦋
Copyright Notice 💜
Copyright (C) The Internet Society (1998). All Rights Reserved.
Abstract 🎀
This doc describes HTCPCP, a protocol for controlling, monitoring, and diagnosing coffee pots ☕
1. Rationale and Scope 🌸
okay so there is coffee all over the world ☕🌍 And as computing gets more and more everywhere, the computists want to make coffee too 💻 Coffee brewing is an art, but ngl the distributed intelligence of the web-connected world transcends art 😭 So there's a strong, dark, rich requirement for a protocol designed espressoly for brewing coffee ✨ Coffee gets brewed using coffee pots, and networked coffee pots need a control protocol if they're going to be controlled 🫖
Home and consumer devices are getting connected to the Internet more and more 🏠 Early networking experiments hooked up vending devices for status monitoring [COKE] 🥤 One of the first remotely _operated_ machines to get hooked up to the Internet was the Internet Toaster, which was controlled via SNMP and debuted in 1990 [RFC2235] 🍞 literally iconic behavior
The demand for ubiquitous appliance connectivity is what's causing the consumption of the IPv4 address space 📈 Consumers want remote control of devices like coffee pots so they can wake up to freshly brewed coffee 🌅 or have coffee get prepared at a precise time after dinner prep is done 🍝
This document specifies the Hyper Text Coffee Pot Control Protocol (HTCPCP), which permits the full requests and responses needed to control all devices that can make 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, and the reason is giving "HTTP is everywhere" energy 😌 It could not be so pervasive without being good, so HTTP is good 👑 If you want good coffee, HTCPCP needs to be good, and to make HTCPCP good, it's good to base it on HTTP ☕🫶
Future versions of this protocol may include extensions for espresso machines and similar devices 🚀☕
2. HTCPCP Protocol 🎀
okay so HTCPCP is built on top of HTTP, with 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 get sent from client to coffee server using either the BREW or POST method, with a message body whose Content-Type is set to "application/coffee-pot-command" 📨
A coffee pot server MUST accept both the BREW and POST method equivalently 🫶 However, using POST to make actions happen is deprecated 🙈
Coffee pots heat water with electronic mechanisms, so there's no fire 🔥🚫 That means no firewalls are necessary, and firewall control policy is irrelevant 😌 However, POST may be a trademark for coffee, so the BREW method got added 💖 The BREW method may be used with other HTTP-based protocols, like the Hyper Text Brewery Control Protocol 🍺✨
2.1.2 GET method
In HTTP, the GET method means "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's the produced data that 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 🧠
In HTCPCP though, the resources associated with a coffee pot are physical, not information resources 🫖 The "data" for most coffee URIs contain no caffeine 💀
2.1.3 PROPFIND method
If a cup of coffee is data, then metadata about the brewed resource gets discovered using the PROPFIND method [WEBDAV] 🔍☕
2.1.4 WHEN method
When coffee is poured and milk is offered, the holder of the recipient of milk needs to say "when" at the time when sufficient milk has been introduced into the coffee 🥛 So for this purpose, the "WHEN" method got added to HTCPCP 🎉 Enough? Say WHEN. 🙌
2.2 Coffee Pot Header fields 🎀
okay so 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 an HTTP response header field, "Safe", that can be used to indicate that repeating an HTTP request is safe 🔁 Including a "Safe: Yes" header field lets a client repeat a previous request if the result of the request might be repeated 💖
The actual safety of devices for brewing coffee varies wildly, and it might depend on conditions in the client instead of just the server 🤷♀️ So 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" | tokenThis indication lets user agents handle retries of some safe requests, especially safe POST requests, in a more user-friendly way 🫶
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 that are acceptable for the response 📄 But in HTCPCP, the response might lead to additional actions from the automated pot 🤖 For this reason, HTCPCP adds a brand 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 the special interpretations and the 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 can't 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 📋
In practice though, most automated coffee pots can't 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 🌍
Coffee is international, so 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 )All alternative coffee-scheme forms are equivalent 🫶 However, using coffee-scheme in various languages MAY be interpreted as an indication of the kind of coffee the pot produces ☕✨ Also, while URL scheme names are case-independent, capitalization matters for German, so the initial "K" must be encoded 🇩🇪 (bestie that's so specific and I'm obsessed 😭)
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 info for controlling the coffee pot is carried by the additional headers, the content of "message/coffeepot" only contains a coffee-message-body 🫖
coffee-message-body = "start" | "stop"🧁 Part 1 of 2 wraps here! Section 5 (Operational constraints, including the timing stuff and the Cambridge Coffee Pot 📷☕) is coming up next in part 2 💖
5.2. Crossing firewalls 🔥
okay so in most organizations HTTP traffic slides right through firewalls like it's nothing 💅 Modern coffee pots don't use fire 🙄 but a "firewall" is still useful for protecting any source from any kind of heat, not just fire. Every home computer network SHOULD be protected by a firewall from sources of heat 🛡️ And remote control of coffee pots matters from outside the house too 🫖 So it's super important that HTCPCP can cross firewalls easily ✨
by building HTCPCP on HTTP and using port 80, it gets all of HTTP's firewall-crossing perks 🦋 Sure, home firewalls will need reconfiguring or new versions to handle the HTCPCP-specific methods, headers, and trailers, but those upgrades are easy to add. Most home network admins drink coffee too, so they're totally willing to make room for tunneling HTCPCP ☕💜
6. System management considerations 🧁
coffee pot monitoring over HTTP was one of the earliest applications of the web, no cap 🌐 The very first version ran over ATM networks [CAM], which was a super fitting use 😭
the traditional setup [CAM] was to hook a frame-grabber up to a video camera and feed the images into a web server 📷 It was a perfect match for ATM networks. The coffee pot lived in the Trojan Room at the Cambridge University labs, and that's where the web interface came from, so people could check on a common coffee pot ☕✨ Some of us were doing related research, and being poor, broke academics, we only had one coffee filter machine between us. It lived in the corridor right outside the Trojan Room 💀 But we were highly dedicated, hardworking academics, so we went through a LOT of coffee. And when a fresh pot got brewed, it did not last long 😭🫶
this service was built as the first app to use a brand new RPC mechanism from the Cambridge Computer Laboratory, called MSRPC2 🎀 It runs over MSNL (Multi-Service Network Layer), which is a network layer protocol designed for ATM networks 🧚
coffee pots on the Internet can be managed with 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.
putting coffee grounds into Internet plumbing may clog the plumbing, which would mean calling in an Internet Plumber [PLUMB], who would then need an Internet Plumber's Helper 🛠️💀
access authentication will be discussed in a separate memo 🔑
8. Acknowledgements 🫶
huge thanks to all the many contributors to this standard, including Roy Fielding, Mark Day, Keith Moore, Carl Uno-Manros, Michael Slavitch, and Martin Duerst 🌸 The inspiration came from the Prancing Pony, the CMU Coke Machine, the Cambridge Coffee Pot, the Internet Toaster, and other computer-controlled remote devices, and that's how this valuable creation came to be 👑✨
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>
[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.com11. 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. 🎀
📦 where this page comes from
- ietf: rfc2324 1998-04
- 💖 girlified by claude-haiku-5-5 on : a language model's rewrite of the original, under its terms