From 4d52ce80abf0e31ec42b87033d06e7055866b68b Mon Sep 17 00:00:00 2001
From: Boris Kolpackov <boris@codesynthesis.com>
Date: Thu, 23 Apr 2015 16:11:22 +0200
Subject: Interface changes

---
 brep/module.cxx |  6 ++++--
 web/module      | 47 ++++++++++++++++++++++++++++++++---------------
 2 files changed, 36 insertions(+), 17 deletions(-)

diff --git a/brep/module.cxx b/brep/module.cxx
index 17790de..5937028 100644
--- a/brep/module.cxx
+++ b/brep/module.cxx
@@ -71,8 +71,10 @@ namespace brep
 
   // Custom copy constructor is required to initialize log_writer_ properly.
   //
+  // @@ Won't log_writer_ be left empty by this implementation?
+  //
   module::
-  module (const module& m): module ()  {verb_ = m.verb_;}
+  module (const module& m): module (), verb_ (m.verb_) {}
 
 // For function func declared like this:
 // using B = std::string (*)(int);
@@ -153,7 +155,7 @@ namespace brep
       // Considered using lambda for mapping but looks too verbose while can
       // be a bit safer in runtime.
       //
-      static int s[] = { APLOG_ERR, APLOG_WARNING, APLOG_INFO, APLOG_TRACE1 };
+      static int s[] = {APLOG_ERR, APLOG_WARNING, APLOG_INFO, APLOG_TRACE1};
 
       for (const auto& e : d)
       {
diff --git a/web/module b/web/module
index 9f1c778..5e5873d 100644
--- a/web/module
+++ b/web/module
@@ -5,13 +5,13 @@
 #ifndef WEB_MODULE
 #define WEB_MODULE
 
-#include <utility>   // move()
-#include <stdexcept> // runtime_error
 #include <string>
 #include <vector>
 #include <iosfwd>
 #include <chrono>
 #include <cstdint>   // uint16_t
+#include <utility>   // move()
+#include <stdexcept> // runtime_error
 
 namespace web
 {
@@ -24,9 +24,14 @@ namespace web
   // This exception is used to signal that the request is invalid
   // (4XX codes) rather than that it could not be processed (5XX).
   // By default 400 is returned, which means the request is malformed.
-  // Non empty description of a caught by the module implementation exception
-  // can be sent to client in http response body with
-  // Content-Type:text/html;charset=utf-8 header.
+  //
+  // If caught by the web server implementation, it will try to return
+  // the specified status and description to the client, if possible.
+  // It is, however, may not be possible if some unbuffered content has
+  // already been written. The behavior in this case is implementation-
+  // specific and may result in no indication of an error being sent to
+  // the client. If description is not empty, then it is assumed to be
+  // encoded in UTF-8.
   //
   struct invalid_request
   {
@@ -45,7 +50,7 @@ namespace web
   //
   struct sequence_error: std::runtime_error
   {
-    sequence_error (std::string d) : std::runtime_error (d) {}
+    sequence_error (std::string d): std::runtime_error (std::move (d)) {}
   };
 
   struct name_value
@@ -70,21 +75,26 @@ namespace web
     //   in name_values.
     //@@ Maybe parameter_list() and parameter_map()?
     //
-    // Throw invalid_request if mime url decode of name or value fail.
+    // Throw invalid_request if decoding of any name or value fails.
     //
     virtual const name_values&
     parameters () = 0;
 
-    // Throw invalid_request if Cookie header is malformed.
+    // Throw invalid_request if cookies are malformed.
     //
     virtual const name_values&
     cookies () = 0;
 
-    // Get stream to read request body data.
+    // Get the stream to read the request content from.
+    //
     // Throw sequence_error if some unbuffered content is already written.
     //
+    // @@ Why can't I write unbuffered content while reading
+    //    the request? Is it so? If so, is it implementation
+    //    details?
+    //
     virtual std::istream&
-    data () = 0;
+    content () = 0;
   };
 
   class response
@@ -109,15 +119,15 @@ namespace web
     virtual std::ostream&
     content (status_code, const std::string& type, bool buffer = true) = 0;
 
-    // Set status code without writing any content.
-    // On status change discards buffered output and throw sequence_error
-    // if output were not buffered.
+    // Set status code without writing any content. On status change,
+    // discard buffered content or throw sequence_error if content was
+    // not buffered.
     //
     virtual void
     status (status_code) = 0;
 
-    // Throw sequence_error if some unbuffered content is already written as
-    // will not be able to send Set-Cookie header.
+    // Throw sequence_error if some unbuffered content has already
+    // been written.
     //
     virtual void
     cookie (const char* name,
@@ -156,6 +166,13 @@ namespace web
   class module
   {
   public:
+    // Any exception other than invalid_request described above that
+    // leaves this function is treated by the web server implementation
+    // as an internal server error (505). Similar to invalid_request,
+    // it will try to return the status and description (obtained by
+    // calling what() on std::exception) to the client, if possible.
+    // The description is assume to be encoded in UTF-8.
+    //
     virtual void
     handle (request&, response&, log&) = 0;
   };
-- 
cgit v1.1