kcar.rl: more comments explaining write_value;

This function can get intimidating to new users

1 files changed, 14 insertions, 0 deletions

diff --git a/ext/kcar/kcar.rl b/ext/kcar/kcar.rl
index 5acaa49..e53de45 100644
--- a/ext/kcar/kcar.rl
+++ b/ext/kcar/kcar.rl
@@ -191,6 +191,12 @@ static void write_value(VALUE hdr, struct http_parser *hp,
   f = rb_str_new(fptr, flen);
   v = rb_str_new(vptr, vlen);
 
+  /* needs more tests for error-checking here */
+  /*
+   * TODO:
+   * some of these tests might be too strict for real-world HTTP servers,
+   * report real-world examples as we find them:
+   */
   if (STR_CSTR_CASE_EQ(f, "connection")) {
     hp_keepalive_connection(hp, v);
   } else if (STR_CSTR_CASE_EQ(f, "content-length")) {
@@ -240,6 +246,7 @@ static void write_value(VALUE hdr, struct http_parser *hp,
       e = rb_funcall(hdr, id_sq, 1, f);
 
     if (NIL_P(e)) {
+      /* new value, freeze it since it speeds up MRI slightly */
       OBJ_FREEZE(f);
 
       if (hclass == rb_cHash)
@@ -249,6 +256,13 @@ static void write_value(VALUE hdr, struct http_parser *hp,
 
       hp->cont = v;
     } else {
+      /*
+       * existing value, append to it, Rack 1.x uses newlines to represent
+       * repeated cookies:
+       *    { 'Set-Cookie' => "a=b\nc=d" }
+       * becomes:
+       *    "Set-Cookie: a=b\r\nSet-Cookie: c=d\r\n"
+       */
       rb_str_buf_cat(e, "\n", 1);
       hp->cont = rb_str_buf_append(e, v);
     }