Ruby Video | Error 418 - I'm a Teapot

HTTP

Error 418 - I'm a Teapot

Matthew Lindfield Seager

Error 418 - I'm a Teapot

by Matthew Lindfield Seager

In this engaging talk titled 'Error 418 - I'm a Teapot,' presented by Matthew Lindfield Seager at RubyConf TH 2023, the focus is on implementing an April Fools' joke protocol known as RFC 2324, also referred to humorously as the Hyper Text Coffee Pot Control Protocol (CP Squ). Over the course of his presentation, Seager combines technical detail with humor, making the topic not only educational but also entertaining.

Key Points Discussed:
- The Nature of CP Squ: Seager opens with a light-hearted discussion about the concept of 'wetness' and introduces RFC 2324, explaining that it's an extension to the HTTP protocol specifically for controlling coffee pots.
- HTTP Overview: He provides a concise summary of the HTTP protocol, emphasizing the importance of request-response cycles, methods (GET, POST), and how these are utilized in web communication.
- Request Methods and Headers: Seager dives deeper into HTTP headers and request methods using relatable examples, illustrating how these are fundamental to web interactions.
- Introducing CP Squ: He discusses how CP Squ adds new methods ('Brew' and 'When') and modifies existing ones, all while retaining some humor about the absurdity of its nature, like returning a 418 error if a teapot is requested to brew coffee.
- Implementation Approach: Seager addresses the technicalities of implementing CP Squ, advocating for middleware integration rather than building a new web server. He emphasizes the use of Rack as a way to connect different web frameworks effectively.
- Rack's Role: The speaker emphasizes the versatility of Rack in middleware and its importance in making web applications more modular and adaptable.
- Interactive Naming Game: To enliven the session, he involves the audience in a fun naming activity, showcasing how easy it is to give names in an Aussie-centric way, further emphasizing community engagement.
- Building the CP Squ Middleware: He outlines the practical steps to implement CP Squ within a Ruby application using Rack, explaining how to handle requests and responses, including error handling.
- Conclusion and Future Work: Seager wraps up by summarizing the key lessons learned, expressing intent to continue the project beyond the talk.

Overall, the session effectively combines humor and technical insights, encouraging developers to explore the whimsical side of software while reinforcing the fundamentals of web protocols and middleware integration.

00:00:07.000 In the next 30 minutes, we're going to implement an RFC 2324 server together. Now, that may sound like a fairly dry topic, but RFC 2324 is all about coffee. Coffee is a liquid; liquids are wet, and therefore, this talk is certified not dry. Just in case there are any chemists in the audience, as I was procrastinating while preparing this talk, I started thinking: are all liquids actually wet? What makes something wet, anyway?

00:00:14.360 I consulted multiple experts, and I can tell you now that apparently not all liquids are wet. Both mercury and a certain alloy of gallium and indium feel dry to the touch of human skin. Who knew? And that leads perfectly into a content warning: this talk will contain bad puns, pointless tangents, and pedantry. Or was that ped? I've put it in different ways; it depends on who you ask. Anyway, you've been warned! So, let's talk about hypertext coffee pot control protocol.

00:00:31.480 That name is a bit of a mouthful; even the abbreviation is quite long. So for this talk, I will simplify it by referring to it as 'CP Squ.' CP Squ was published on the 1st of April, 1998, which is a bit of a strange choice. There have been many products announced on the 1st of April that haven't panned out.

00:00:40.480 For example, I'm still waiting for powdered water, edible computer discs, and wipers for BMW badges—not that I have a BMW, but if I did, I’d want wipers for it. Other examples include the chippy music player and left-handed laptops. All of these things were announced on the 1st of April and have not been delivered, which is very disappointing. However, I am pleased to say that CP Squ is still around today, and I think that makes it just as important as some of these other survivors.

00:01:01.600 For instance, Apple Computer was founded on the 1st of April, long ago, and while they are doomed, they're still limping along. Linux and its various distributions are also significant survivors. Next year, it will be big on the desktop too, and of course, we have Gmail, which, with apologies to Winston Churchill, is the worst form of email, except for all the others. Let's not forget CP Squ, which is the subject of international conference talks. Very important!

00:01:18.000 Now, enough prattling; let's get on with RFC 2324. CP Squ is actually an extension to HTTP. So first, we'll go through some background on HTTP to ensure we all understand it. HTTP is used by both browsers and native apps on phones as a protocol for communication. There are other protocols that also extend it, like WebDAV.

00:01:28.480 It's a stateless protocol, meaning that the communication happens through a request-response cycle. There are many different types of requests, and I’ll let you look them up on MDN. For the purpose of this quick overview, we will focus on GET and POST, two of the most common methods.

00:01:43.360 As a general rule, you use GET to fetch web pages or download funny GIFs, while POST is used to submit data, like purchasing a rubber chicken purse or uploading a file. When you visit a web page, your browser likely makes a whole bunch of requests—not only for the main HTML page but also for images, stylesheets, scripts, and so on. Additionally, those scripts can make further requests.

00:02:03.120 Most of you probably know this already, but you can view all the requests being made using the developer tools in your preferred browser. For instance, in Safari, you can check the 'Timelines' tab to see all requests that were made for a particular page, including their method, the scheme used, the status code from the web server, and whether or not it was cached.

00:02:17.360 Here, you can see that most of the requests are GET requests, along with a single POST request to Google Analytics. To see even more details about a particular request, head over to the 'Network' tab. Choose one of the requests from the left, and you can see more information. For example, if you want to see the headers, you can click on the 'Headers' tab. Here, you can view the headers from the request that was sent, as well as the headers from the response that came back.

00:02:33.000 But what are headers? No, not that sort of header! Headers are just metadata about either a request or a response, so they are essentially data about data. When we request an image from a web server, the headers might contain information that seems complicated. However, if you split it across separate lines and order it by Q value, which is just a fancy way of saying preference, you can start to see that the most preferred format is listed first.

00:02:47.679 If that fails, we will accept any other image or video, and failing that, give us whatever you like. The response from the server will tell you what it has provided, so you know which one to decode. For example, if it's an image, you might see a content type of image/png. I did warn you there might be tangents, and it’s time for a quick tangent; if you're a web developer, you sometimes have complex forms that require testing frequently.

00:03:05.040 Instead of filling out the form repeatedly after each change to your app, you can fill it out once and save the request as a cURL command. You can then paste that into your console whenever you make changes or even include it in various testing scripts. One gotcha I discovered when I was testing this out is that if the response comes back compressed, it will present a bunch of binary output that your terminal may struggle to display. There are different ways to get around this.

00:03:21.200 For instance, you can pipe it to Gzip, or add a compression flag at the end, and cURL will handle it for you. Alternatively, you can just remove that Accept-Encoding header that we discussed earlier, so here we're getting rid of gzip, deflate, and br compression. Alright, end of that tangent! Now, something all HTTP requests have in common is that they need a destination. You need to specify where they're going.

00:03:40.440 The destination of a request is specified by the URI, also known as the URL. Although technically, there is overlap, they are different, but for simplicity, I’ll just refer to it as URL for the remainder of the talk. The URL contains different portions: the scheme at the start, which we've mentioned earlier, serves all sorts of various protocols. The colon acts as a separator, and the double slashes are a network path designator, followed by the domain name, which can also be an IP address, and finally, the absolute path to the resource on the server you are requesting.

00:03:58.160 Once the HTTP server receives the request, it sends a response that can fall into one of five different categories, with variations within each category. The server will return a status code and a status text to provide more information. For instance, if you get a 200 OK message, it starts with two, indicating it is in the success bucket. A 301 move permanently starts with a three, indicating it is a redirect. A 404 not found is a client error, because in that case, the client can do something about it—like change the URL and send the request again, at which point it might work.

00:04:17.280 Last, we have a 503 service unavailable as another example. If our web server can’t communicate with our Ruby app server, it might return that, and the client can’t do anything about it; it has to go reboot it or fix whatever is broken. So, that's HTTP. Now, let’s quickly chat about how CP Squ is different from HTTP, other than the obvious changes in hardware.

00:04:35.200 The first difference is that CP Squ adds two different request methods. Specifically, it adds 'Brew,' which is used to tell when the coffee pot should start or stop brewing, and 'When,' which tells it when to stop pouring milk. Great dad joke there! If the coffee pot supports a feature, another change is for the scheme; it uses coffee instead of HTTP or HTTPS.

00:04:51.760 And that leads me to another tangent! The web can sometimes be a bit US-centric, but coffee is international. The developers who designed CP Squ actually came up with a bunch of different translations you can use. For example, the word for coffee in Finland is 'kafe'—excuse my pronunciation. These two URLs are actually equivalent. And since we're in Thailand, we should probably use the Thai word for coffee, which is written over there. Unfortunately, URLs aren't really good at Unicode, unlike Ruby, so you must percent encode it.

00:05:07.760 For the purpose of this talk, I'm going to stick with the 'kafe' pronunciation and spelling. A little tangent ended there! So, what else is different with CP Squ? It has some header changes. For instance, the content type should be 'message/coffee.' The body of the message needs to state 'coffee message body start' or 'coffee message body stop.' The last change is in the responses; there are two new errors, specifically in the 400 series.

00:05:22.800 The first is '406 Not Acceptable,' which gets reused. So if you request cream, syrup, or sugar or something else the coffee pot can't provide, it is supposed to return 'Not Acceptable.' If you request coffee from a teapot, however, you should get the infamous error '418 I'm a Teapot.' According to the specification, the resulting entity body may be short and stout.

00:05:38.960 Alright, so that's the requirements for CP Squ. Now it’s time to implement it! But that begs the question: how are we actually going to implement it? It's fairly straightforward, but should we build our own web server? Probably not. There's already a bunch of great options out there, and building our own web server means we can't use this with other existing applications.

00:06:00.000 For example, if Shopify wants to integrate a coffee brewing service for their patrons, they wouldn’t be able to do that without changing web servers, or maybe Stripe wants to connect CP Squ with one of their internal web services to improve caffeination and employee productivity. That won't work unless they change web servers just for that. By the way, if anyone from Shopify or Stripe is in the audience or watching online, I've got some brilliant ideas—give me a call!

00:06:17.480 Clearly, it makes more sense to build it into one of the web frameworks. The next question is, which one? Here are the four most popular, according to GitHub stars, but I have to say that once I considered integrating CP Squ into each of these, it doesn’t look good. Last year, Hanami joined the anti-liquid crew while Rails spat out coffee five years ago. Sinatra has had a recipes repo since 2011, and in all that time, no one has added a recipe for coffee. I mean, how hard is the recipe for coffee?

00:06:35.320 This means we're relying on Grape to implement it. I’m sure the maintainers of Grape are nice people, but let’s be honest—I figured there was no point even trying. I mean, why press grape when all you're going to get is a little wine? I'll let you think about that one. Thankfully, in Ruby, there is a way to integrate with almost any web server and any web framework, and that way is Rack.

00:06:50.280 Rack is a specification that allows any compatible web framework to run with any compatible server. It's basically a bridge between both systems. The specification also allows us to run additional software in the middle. Unfortunately, that middleware doesn't have a cool name like 'Ultra Connector' or 'Micro Bridge'—the term is simply 'middleware.' Pretty obvious! I noticed that naming stuff can be hard. Personally, I think that if you find naming stuff hard, you’re asking the wrong people. If you want something named, ask an Aussie!

00:07:08.120 To prove that, I'm going to get some help from the audience, and for that, I need to find an Aussie. There’s one surefire way to find an Aussie in any crowd—Aussie! Oi! I heard a few shouts in the audience. If you heard 'Oi' near you, please point to the person who said it. There’s one over here! Anyone who's not a speaker, please come on up!

00:07:24.720 Alright, unmute that! We're going to play a game called 'Name Stuff.' This is going to prove that Aussies are great at naming stuff. Hello, testing one-two! I’m going to show you some slides; you can either look at them here or up there. You've got to come up with a name; I'll also give you a verbal description. Where's the cheat sheet? Alright, so there’s a harbor in Sydney—what's it called? The Sydney Harbor! Well done!

00:07:37.360 There’s a bridge that goes over Sydney Harbor—what's that called? The Sydney Harbor Bridge! Good name! The bridge got a bit crowded, so we built a tunnel underneath—what do we call the tunnel under Sydney Harbor? The Sydney Harbor Tunnel! Well done! Moving on, I’ve got a spider with a red back—what could I call that? A red back spider! Nice. What about a snake that's brown? The brown snake!

00:07:57.920 Alright, I think some people are getting uncomfortable with the venomous things, so let’s move on to some tourist attractions. In Coffs Harbor, there’s a big banana—what would we call it? The Big Banana! Genius. This one’s a bit rare: in Adaminy, there’s a giant trout—what do we call this giant trout? The Giant Trout! Big Trout! Nice!

00:08:08.480 And when the snow melts, it feeds a river—what would we call that river? The Snowy River! Oh, and there’s a famous poem about a man that comes from this region by Banjo Patterson—what’s the poem called? The Man from Snowy River! Genius! 10 out of 10! As a thank you, I’ve got these genuinely Aussie-made lollies; feel free to share them at the after-party tonight.

00:08:21.760 So that’s how naming is done Aussie-style! It’s really not hard at all. Okay, where were we? Oh yes! Rack middleware! Great name—it says it right there on the tin! So, Rack isn’t just one of those specifications that someone made up for an April Fool's gag; it’s an actual specification that’s widely used.

00:08:39.000 Let's take a quick look at how it's used in two popular web frameworks. First, we've got Rails. When you start a new Rails app, you can check all the middleware included by running the command `rails middleware`. So, I did that in Rails 7, and there were 28 middleware objects, rack middleware objects, included by default. Rails has a reputation for being 'batteries included,' so you kind of expect that.

00:08:56.720 On the other end of the extreme, you’ve got Hanami, which has a reputation for letting you pick and choose what you want to include. Hanami even has a similar command: `hanami middleware`, and with a brand new project, it includes some Rack middleware by default—just the one, but still, it shows that Rack is used throughout Ruby.

00:09:14.560 So, if we're going to build CP Squ, we should do it in Rack. But how do we actually go about building something in Rack? The Rack specification is actually fairly straightforward. It requires a Ruby object, not a class, that responds to 'call.' It takes exactly one argument, the environment, and returns a non-frozen array of exactly three values: the status, the headers, and the body.

00:09:31.880 What would that look like in practice? Here’s a diagram showing what it might look like if we didn’t use any middleware; we're just using Rack. We’ve got the web browser, a web server running Puma, and a Ruby app running Sinatra. So when the client sends a GET request, Puma takes that and puts it in the environment, and then it calls 'app.call' to the Sinatra app.

00:09:49.200 Sinatra processes the response and then returns that three-part array to—status code, headers, and body. Then Puma turns that into HTML and sends it back to the client. Pretty straightforward! The clever part of this design is that it allows you to chain applications together.

00:10:04.560 So you can have zero middleware, like we have here, one like Hanami starts off with, or you can have 28 like Rails starts with. If you want, you can even try to add a thousand of your own! Let's do that ourselves. First, we’re going to take that same middleware and modify it slightly. The first thing we need to do is use the initializer to tell it what the next link in the chain is.

00:10:20.880 So, whatever gets passed to the initializer will be the next link, and then whatever we receive from the environment, we can just pass that on to the next link. Sounds simple! Let’s modify that diagram: we now have Rack in the middle. So, Puma still does 'app.call,' but this time it goes to our nullable, do-nothing middleware, which just sends that straight back to Puma.

00:10:38.800 So, what’s the point? Well, it shows the power of Rack middleware—it allows you to make changes. You can make changes on the way to the app server, and you can also make changes on the way back to the client.

00:10:57.360 In my first tangent, I mentioned we could modify our cURL command to remove the Accept-Encoding header. We could actually build a Rack middleware that does exactly that! What would that look like? We take the same app, and all we do is modify the environment before sending it to Sinatra—the next link in the chain. As Matt said earlier, Ruby is awesome; it’s straightforward! You can just use `m.delete('Accept-Encoding')` to remove that header.

00:11:17.760 Another simple example could involve adding timing information. We might want to time how long our Ruby web app takes, and we can do that pretty easily. First, we can use multiple assignments: `status, headers, body` to take those three array items and put them into variables. This allows us to wrap the request in `before and after`, enabling us to calculate the duration and merge it straight into the headers.

00:11:34.360 As you can see, it reads really nicely. You’ve got to love Ruby! This highlights the possibility for change, either direction, and the possibilities here are essentially endless. For example, we could add or remove cookies; we could serve requests from a cache without bothering our Ruby server, or, and I’m guessing this is why most of you are here today, we could build CP Squ ourselves!

00:11:50.000 Alright, let's figure out how to do that. We’ve got our specifications from earlier—let’s build it in Rack! This requires adding one more implicit requirement: we’re going to use Rack middleware to do this. So, first off, let’s add some Rack middleware to an existing app and confirm it’s working.

00:12:09.440 I'm using Rails for this example, but it's fairly similar in other frameworks. The first thing I did was put some `puts` debugging in so I know it’s being loaded and called, then I placed that code in the `lib/middleware` folder—a case of convention over configuration. Once I did that, I modified `config/application.rb` to require that file and to insert the middleware at the head of the queue.

00:12:28.080 I used `config.middleware.insert_before 0, MyCustomMiddleware` to put it right at the top so that nothing else processes the request before I get to deal with it. Also, don't forget to relaunch the app anytime you make a config change or update your Rack middleware—ask me how I figured this out! After I finally got it working and booted it up, I saw the message I was looking for in the logs.

00:12:44.160 When I passed the request along, it logged all of the expected outputs. So now our Rack middleware is working! Now, how do we check for a coffee scheme? To accomplish this, we need to check the environment under `rack.url_scheme` to see if the scheme matches. If it does, we enter our block where we unescape it back to Unicode so we can read it.

00:13:02.560 We log it, then return a placeholder HTTP response to say, 'Got your coffee request.' If it doesn’t contain the coffee scheme, we just pass the request on to the next link in the chain. Once that’s done and we rebuild our server, I made some test coffee requests, and they all worked in different languages. To make sure I hadn’t broken my actual app, I sent a regular request as well, and Rails handled it as expected.

00:13:18.480 In the logs, I can see the three requests processed by my middleware and the one that got passed onto Rails. Alright, looking good! There are only four more requirements to cover. In the interest of time, we won’t go through all four; I’ll just show you one because they’re all actually quite similar.

00:13:34.640 For the first requirement, we want to check for a brew or POST method; otherwise, we will return a 405 method not allowed. We do that by adding a guard clause, which returns early if there’s a problem with the request and returns a 'Method Not Allowed' error unless the HTTP method is valid. It reads just like English, really nice!

00:13:50.960 How do we actually verify that? Again, we check if 'request.method' is set, looking for either Brew or Post. If it’s not set or is neither Brew nor Post, we return false, triggering the clause which returns the HTTP error. Returning this error is just like any other HTTP response; we need that three-item array. So for 405, we add our headers to indicate what is allowed, so the client knows what it should have sent.

00:14:07.440 We can put a human-readable string in the body in case anyone is reading it. That’s the first requirement. The next three are basically the same—three more guard clauses and three more different error types. At this point, I would have loved to show you a working coffee pot control server, but when I pitched this talk, I vastly overestimated my electronics abilities and time.

00:14:21.760 However, I am hoping to complete it one day; maybe there will be a sequel to this talk. For now, I will wrap up by covering what we discussed today. We looked at HTTP with its request-response cycle and some common methods, how URLs work, what headers do, and the different response buckets or categories.

00:14:32.720 We then looked at CP Squ and how it extends HTTP. While that may not be super relevant to implementing this, if you’re working with web dev or doing anything else that extends HTTP, it might come in handy. We also examined Rack—how it works and how it integrates different web servers with different frameworks.

00:14:49.680 Finally, we learned that you can have Rack middleware that lets you chain different requests together, and we implemented our own Rack middleware from scratch to handle the error checking portion of CP Squ. We learned how to integrate it into an existing Ruby web app. That’s all I’ve got for you today! Thank you for your time, and thank you to the organizers for putting together this conference and to all of you for being part of the Ruby community.

00:15:06.480 I hope you enjoyed yourself, and I wish you all the best for the rest of the conference.

RubyConf TH 2023