RFC 7168

The Hyper Text Coffee Pot Control Protocol for Tea Efflux Appliances (HTCPCP-TEA)

📅 published April 2014, from ietf

RFC 7168: The Hyper Text Coffee Pot Control Protocol for Tea Efflux Appliances (HTCPCP-TEA) 🫖💖

Part 1 of 2 ✨ (this covers the title block through Section 2.3.3, and part 2 picks up at Section 3 🧚)

RFC number: 7168, Request for Comments 🎀
Author: I. Nazar 💅
Date: 1 April 2014 🌸
Category: Informational, as an Independent Submission 📚
Updates: RFC 2324 (the original HTCPCP spec) 🔥
ISSN: 2070-1721

Abstract 🫖

Okay so the Hyper Text Coffee Pot Control Protocol (HTCPCP) spec does not let you brew tea at all, even though tea is so varied and complex 😭. This paper adds an extension to HTCPCP so pots can offer networked tea-brewing, and it's giving main character energy 💅✨.

Status of This Memo 📝

This document is not an Internet Standards Track specification. It's published for informational purposes 🦋.

This is a contribution to the RFC Series, independent of any other RFC stream. The RFC Editor chose to publish it at their discretion, and they make 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, so see Section 2 of RFC 5741 🫶.

Info about the current status of this document, any errata, and how to give feedback can be found at http://www.rfc-editor.org/info/rfc7168 💜.

Copyright Notice ©️

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) as in effect on the date of publication. Please review those documents carefully, because they describe your rights and restrictions with respect to this document 🧾.

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 ☕🫖

Okay so, as HTCPCP [HTCPCP] points out, coffee is famous worldwide as an artfully brewed caffeinated drink 😌☕. But coffee shares that vibe with lots of other drinks made by filtering plant material 🌿. The biggest group of those is brews made by straining water through prepared leaves from a tea tree 🍃✨. We're not going to go through the whole history of the tea genus here, but evidence shows tea production existed many thousands of years ago 🏺💅.

Here's the tea (lol 🫖): HTCPCP is kind of failing tea right now 💀. The only rule it gives for networked teapots is that they don't respond to requests to make coffee. That's honestly reasonable 🙈, but it doesn't let anyone talk to the teapot for what it's actually for 😤.

This paper specifies an extension to HTCPCP so you can talk to networked tea-production devices and teapots 🧚. The additions in here let you send the requests and responses needed to control every device that can make what's arguably the most popular caffeinated hot drink 👑🔥.

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 changes how certain HTCPCP methods work 🦋.

2.1. BREW and POST Methods 🫖💫

Okay, so controlling a TEA-capable pot works the same way as the base HTCPCP spec describes: you send BREW requests 📨. POST requests are treated the same way, but they're still deprecated 🙅‍♀️. The main difference with tea is that people usually get to pick a tea before it gets brewed, so the pot is expected to offer a choice first 🍓. For that reason, a TEA-capable pot that gets a BREW message with content type "message/teapot" MUST respond according to the URI requested, like below 🎀.

2.1.1. The "/" URI 🌸

For the URI "/", brewing won't start 🛑. Instead, an Alternates header, as defined in RFC 2295 [RFC2295], MUST be sent, with the available tea bags and/or leaf varieties as the entries 🍃. Here's what that response looks like:

Alternates: {"/darjeeling" {type message/teapot}},
            {"/earl-grey" {type message/teapot}},
            {"/peppermint" {type message/teapot}}

This next example shows how a TEA-capable pot that also follows the base HTCPCP spec can work with both 🤝✨:

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 that comes back from a BREW request 👀, and then give a specific URI for any later requests of the "message/teapot" type 🎯.

A request to the "/" URI with a Content-Type header of "message/coffeepot" SHOULD also get a response with an Alternates header in the format above 💅. That way, TEA-capable clients still get to show the user the tea options if they accidentally asked for an inferior caffeinated drink 😭☕.

2.1.2. Variety-Specific URIs 🍓

TEA-capable pots follow the base HTCPCP spec when they get a BREW request for a specific tea variety 📜. Pots SHOULD follow the brewing-strength recommendations given for each variety and stop brewing once that strength is reached 💪. It's suggested that the strength be measured by detecting how opaque the beverage under brew is 🔍✨.

TEA-capable clients SHOULD mark the end of brewing by sending a BREW request with an entity body containing "stop" 🛑. The pot MAY keep brewing past the recommended strength until it gets that "stop" 🫠. If the client doesn't send "stop", the tea-to-water proportion in the pot can end up inverted, and some pots may report that as a negative strength 🙃💀.

If a BREW command with an entity body containing "stop" arrives before the recommended strength is reached, the pot MUST abort brewing and serve the drink at a lesser strength 🚨. Finding your preferred strength with this override depends on the time between the TEA-capable pot receiving a "start" request and the later "stop" ⏱️✨. Clients SHOULD be ready to make multiple attempts to hit the strength they like 🔁💖.

2.2. Modified Header Fields 📬

HTCPCP-TEA changes the definition of one header field from the base HTCPCP spec 🎀.

2.2.1. The Accept-Additions Header Field 🥛

It's been noticed that some people who drink blended teas occasionally want their tea brewed as an emulsion of cane sugar with hints of water 🍯💕. To cover this, the Accept-Additions header field defined in the base HTCPCP spec is updated to allow the following options 🙌:

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 using the Sugar addition too much may make the BREW request go over the segment size the transport layer allows. That causes fragmentation and a delay in brewing 🥴⏳.

2.3. Response Codes 🚦

HTCPCP-TEA uses normal HTTP error codes, plus the ones defined in the base HTCPCP spec 💜.

2.3.1. 300 Multiple Options 🔀

A BREW request to the "/" URI, as defined in Section 2.1.1, returns an Alternates header that lists the URIs of the available tea varieties 🍵. It is RECOMMENDED that this response be served with a 300 status code 🎯. That tells the client that brewing hasn't started yet and that further options have to 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 tea variety 🚫. They can do that if the service decides the combination of additions is against what a consensus of drinkers would want for that variety 🤔☕.

How you'd collect and combine consensus signals on the most viable addition combinations for each variety to serve is outside the scope of this document 📋🌈.

2.3.3. 418 I'm a Teapot 🫖🎀

TEA-capable pots that aren't set up to brew coffee may return either a 503 status code, which means coffee is temporarily unavailable ⏳☕, or a 418 code as defined in the base HTCPCP spec 🫖. The 418 says, more permanently, "I'm a teapot" 🙈💖.

5. Security Considerations 🔒✨

okay bestie, security time, and I need you to really lock in 🫶 Most TEA-capable pots are expected to heat water with electric elements, which means they aren't anywhere near fire. So no firewalls are needed for talking to these pots to work 💖

BUT this extension does support fired pots 🔥, and those can need heat retention and control policies. Be careful here! Coal-fired pots and electrically heated kettles should not be on the same network, or a pot might start calling the kettles on the network "darkened" or "otherwise smoke driven" 💀 literally the drama nobody asked for.

6. Acknowledgements 🙏🎀

This extension would not exist without the base HTCPCP specification, and without the research on networked beverage production that came before it 🍓 The author gives a huge shoutout to Larry Masinter for his sterling work on the leading protocol for coffee pot communication. Iconic ☕👑

Thanks also to Kevin Waterson and Pete Davis, who gave guidance and suggestions while this document was being drafted 🫶💅

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

📦 where this page comes from

ietf: rfc7168 2014-04
💖 girlified by claude-haiku-5-5 on 2026-10-18: a language model's rewrite of the original, under its terms