Changes between Version 1 and Version 2 of soc/2007/cgi

Timestamp:

May 22, 2007, 3:02:24 PM (15 years ago)

Author:

Darren Garvey

Comment:

starting off the page

soc/2007/cgi

@@ -1 @@
-In a week, after my exams, the current design decisions about this library will be put up here. If anyone stumbles on here in the meantime, feel free to put up some bullet points.
+== About ==
 
-Past discussion can be found (starting) here:[[BR]]
-http://lists.boost.org/Archives/boost/2007/04/120191.php [[BR]]
-http://lists.boost.org/Archives/boost/2007/04/119565.php
+Below is a partial list of things this project aims to provide:
+ * Simple access to standard CGI environment variables and input data
+ * Clean access to request meta-data (ie. 'environment vars') and input data using alternative protocols, such as FastCGI
+ * Asynchronous read/write support
+ * A clean way to write to clients without knowledge of the underlying protocol in use
+
+== Usage ==
+
+First, a standard CGI example:
+{{{
+#!cpp
+int main()
+{
+  cgi::request req;   // set up the request
+  cgi::response resp; // see Design Ideas for more about this
+
+  resp<< "Hello, " << req.param<cgi::GET>("user_name") << "!";
+  resp.send(req);
+  
+  return 0;
+}
+}}}
+Using an alternate protocol (FastCGI in this case) will alter the above like so:
+{{{
+#!cpp
+int sub_main(cgi::request req)
+{
+  cgi::response resp; // see Design Notes for more about this
+
+  resp<< "Hello, " << req.param<cgi::GET>("user_name") << "!";
+  resp.send(req);
+
+  return 0;
+}
+
+int main()
+{
+  cgi::fcgi_service service(&sub_main);
+  service.run();
+  
+  return 0;
+}
+}}}
+
+
+== Design Notes == 
+
+    ''Past discussion can be found (starting) here:[[BR]]
+    http://lists.boost.org/Archives/boost/2007/04/120191.php [[BR]]
+    http://lists.boost.org/Archives/boost/2007/04/119565.php''
+
+'''Separation of ```cgi::request``` and ```cgi::response```''':
+
+This separation is only a recent change. The main reasoning is that meta-data exists for both the request and the response. Using getters/setters is one idea, although in a large program, there could be a situation where you set a response header and then need to check it later. If everything was done with the ```request``` object then there'd be no way to achieve this.
+
+Having two objects has other advantages:
+ * Code is clearer, without being too verbose
+ * Response caching is easier to implement; code can just cache a ```cgi::response``` since it holds no data relevant to the specific request (note: response caching isn't really part of this project, although ```cgi::session``` will probably provide basic facilities)
+
+
+== Main Classes ==
+
+=== ```cgi::basic_request<>``` ===
+This holds the data corresponding to the request. It will be specific to a Protocol type and will be aware of how to receive, send and parse data for that Protocol. There will be ```typedef```s for typical usage.
+
+=== ```cgi::request``` ===
+By default, this provides a general (as opposed to generic) access point to any type of request. If constructed with a service object, then the request takes a request from the queue (or blocks until one is available). Default construction initialises a standard cgi environment.
+
+This generality is achieved using runtime linkage in a similar way to boost::any, although static linking can be forced using a choice of macros which turn ```cgi::request``` into a ```typedef``` for a particular ```cgi::basic_request<>```.
+
+=== ```cgi::response``` ===
+This simply holds headers and the content of the response and provides various ways to write to it. Up until it is sent to the user, it is unaware of what it's a response to. This helps keep code - both library and user code - clean and explicit, without being overly verbose and aids significantly with response caching (something this library won't address for now).
+
+=== ```cgi::session``` ===
+This will provide simple session data caching. 
+
+=== ```cgi::basic_service<>``` ===
+This is the main class in the library. There should be specializations for each Protocol and the underlying structure should be generic enough to allow for any type of cgi-like protocol to be 'serviced', without sacrificing efficiency, clarity of code or any of the aims stated in the Design Notes.
+
+
+
+Since the cache could reside in process memory, shared memory, files or a database, the class should be flexible. The actual data will be held in a ```std::map<std::string, T>```. T should theoretically be generic, so could be ```boost::any``` - this