Merge pull request #75 from vic-ma/update-stage-9

Update compression 1 instructions

Author: rohitpaulk

course-definition.yml

@@ -638,68 +638,87 @@ stages:
 
   - slug: "df4"
     primary_extension_slug: "http-compression"
-    name: "Content-Encoding header"
+    name: "Compression headers"
     difficulty: easy
     description_md: |
-      Welcome to the HTTP Compression Extension! In this extension, you'll add [Compression](https://en.wikipedia.org/wiki/HTTP_compression) support to your HTTP Server implementation.
+      Welcome to the HTTP Compression extension! In this extension, you'll add support for [compression](https://en.wikipedia.org/wiki/HTTP_compression) to your HTTP server.
 
-      In this stage, you'll add support for the Content-Encoding header based on what the client sends.
+      In this stage, you'll add support for the `Accept-Encoding` and `Content-Encoding` headers.
 
-      ### Tests
+      ### `Accept-Encoding` and `Content-Encoding`
 
-      The tester will execute your program like this:
+      An HTTP client uses the `Accept-Encoding` header to specify the compression schemes it supports. In the following example, the client specifies that it supports the `gzip` compression scheme:
+      ```
+      > GET /echo/foo HTTP/1.1
+      > Host: localhost:4221
+      > User-Agent: curl/7.81.0
+      > Accept: */*
+      > Accept-Encoding: gzip  // Client specifies it supports the gzip compression scheme.
+      ```
 
-      ```bash
-      ./your_server.sh
+      The server then chooses one of the compression schemes listed in `Accept-Encoding` and compresses the response body with it.
+
+      Then, the server sends a response with the compressed body and a `Content-Encoding` header. `Content-Encoding` specifies the compression scheme that was used.
+
+      In the following example, the response body is compressed with `gzip`:
+      ```
+      < HTTP/1.1 200 OK
+      < Content-Encoding: gzip    // Server specifies that the response body is compressed with gzip.
+      < Content-Type: text/plain  // Original media type of the body.
+      < Content-Length: 23        // Size of the compressed body.
+      < ...                       // Compressed body.
       ```
 
-      It'll then send an HTTP `GET` request to the `/echo/<a-random-string>` endpoint. In the request, it'll include an Accept-Encoding header like: `Accept-Encoding: gzip`.
-      As an example, here's a request you might receive:
+      If the server doesn't support any of the compression schemes specified by the client, then it will not compress the response body. Instead, it will send a standard response and omit the `Content-Encoding` header.
 
+      For this extension, assume that your server only supports the `gzip` compression scheme.
+
+      For this stage, you don't need to compress the body. You'll implement compression in a later stage.
+
+      ### Tests
+
+      The tester will execute your program like this:
       ```
-      GET /echo/foo HTTP/1.1
-      Host: localhost:4221
-      User-Agent: curl/7.64.1
-      Accept-Encoding: gzip
+      $ ./your_server.sh
       ```
 
-      Your server must respond with a `200 OK` response. The response should have a `Content-Encoding: gzip` header present. The response body will not be tested in this stage. (We will tackle the actual compression in a later stage)
-      Here's the response you're expected to send back:
+      The tester will then send two `GET` requests to the `/echo/{str}` endpoint on your server.
+
+      #### First request
+
+      First, the tester will send a request with this header: `Accept-Encoding: gzip`.
+      ```
+      $ curl -v -H "Accept-Encoding: gzip" http://localhost:4221/echo/abc
+      ```
 
+      Your server's response must contain this header: `Content-Encoding: gzip`.
       ```
       HTTP/1.1 200 OK
-      Content-Encoding: gzip
       Content-Type: text/plain
-      Content-Length: 3
+      Content-Encoding: gzip
 
-      foo
+      ...  // Body omitted.
       ```
 
-      It'll then send another HTTP `GET` request to the `/echo/<a-random-string>` endpoint. In the request, it'll include an Accept-Encoding header like: `Accept-Encoding: invalid-encoding`.
-      But this time the Accept-Encoding header will be set to an invalid value (i.e. an encoding that your server doesn't support).
-      As an example, here's a request you might receive:
+      #### Second request
 
+      Next, the tester will send a request with this header: `Accept-Encoding: invalid-encoding`.
       ```
-      GET /echo/bar HTTP/1.1
-      Host: localhost:4221
-      User-Agent: curl/7.64.1
-      Accept-Encoding: invalid-encoding
+      $ curl -v -H "Accept-Encoding: invalid-encoding" http://localhost:4221/echo/abc
       ```
 
-      Your server must respond with a `200 OK` response. The response should NOT have a `Content-Encoding` header present. The response body will not be tested in this stage.
-      Here's the response you're expected to send back:
-
+      Your server's response must not contain a `Content-Encoding` header:
       ```
       HTTP/1.1 200 OK
       Content-Type: text/plain
-      Content-Length: 3
 
-      bar
+      ...  // Body omitted.
       ```
 
       ### Notes
 
-      1.  Header names are case-insensitive, i.e. `accept-encoding: gzip` and `Accept-Encoding: gzip` are equivalent. We won't test this explicitly in this challenge, but it's a good practice to lowercase your header names before comparison.
+      - You'll add support for `Accept-Encoding` headers with multiple compression schemes in a later stage.
+      - There's another method for HTTP compression that uses the `TE` and `Transfer-Encoding` headers. We won't cover that method in this extension.
     marketing_md: |
       In this stage, you'll add support for reading the `Accept-Encoding` header sent by clients, and respond with `Content-Encoding` header in your response.