aboutsummaryrefslogtreecommitdiff
path: root/web
diff options
context:
space:
mode:
Diffstat (limited to 'web')
-rw-r--r--web/module47
1 files changed, 32 insertions, 15 deletions
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;
};