Split up user and developer documentation.

1 files changed, 153 insertions, 0 deletions

diff --git a/devdoc/CCCwork.txt b/devdoc/CCCwork.txt
new file mode 100644
index 00000000..1ea5d20e
--- /dev/null
+++ b/devdoc/CCCwork.txt
@@ -0,0 +1,153 @@
+Last review: August 04, 2009 --jcid
+
+
+----------------------------
+Internal working for the CCC
+----------------------------
+
+
+HTTP protocol
+-------------
+
+
+      Query:                              |
+                                          .
+          1B --> 1B  1B --> 1B      -->   |  -------------.
+      .----.     .----.     .----.        .               |
+I     |Capi|     |http|     | IO |        |               |
+      '----'     '----'     '----'        .               |
+          1F <-- 1F  1F <-- 1F            |               V
+                                          .
+                                          |           [Server]
+      Answer:                             .
+
+          2B --> 2B  2B --> 2B            |               |
+      .----.     .----.     .----.        .               |
+II    |Capi|     |Dpi |     | IO |        |               |
+      '----'     '----'     '----'        .               |
+          2F <-- 2F  2F <-- 2F      <--   |  <------------'
+                                          .
+                                          |
+
+*  a_Capi_open_url()  builds  both the Answer and Query chains at
+once  (Answer  first  then  Query), to ensure a uniform structure
+that avoids complexity (e.g. race conditions).
+
+*  Http_get()  sets  a  callback  for  the  DNS hostname resolve.
+Normally  it  comes  later, but may also by issued immediately if
+the hostname is cached.
+
+*  The  socket FD is passed by means of OpSend by the http module
+once the remote IP is known and the socket is connected.
+
+
+
+Function calls for HTTP CCC
+---------------------------
+
+  a_Capi_open_url
+    if (reload)
+      Capi OpStart 2B (answer)    [Capi] --> [dpi]  --> [IO]
+      Capi OpStart 1B (query)     [Capi] --> [http] --> [IO]
+        Http_get
+    a_Cache_open_url
+      if URL_E2EReload -> prepare reload
+      if cached
+        client enqueue
+        delayed process queue
+      else
+        Cache_entry_add
+        client enqueue
+
+    -//->
+    a_Http_dns_cb
+      Http_connect_socket
+        OpSend FD, BCK
+        OpSend FD, FWD
+        Http_send_query
+          a_Http_make_query_str
+            OpSend, BCK
+              IO_submit
+                a_IOwatch_add_fd (DIO_WRITE, ...)
+
+
+  Note about 'web' structures. They're created using a_Web_new().
+The  web.c  module  keeps a list of valid webs, so anytime you're
+unsure  of  a  weak  reference  to  'web', it can be checked with
+a_Web_valid(web).
+
+
+
+------------
+Dpi protocol
+------------
+
+
+      Query:                              |
+                                          .
+          1B --> 1B  1B --> 1B      -->   |  -------------.
+      .----.     .----.     .----.        .               |
+I     |Capi|     |Dpi |     | IO |        |               |
+      '----'     '----'     '----'        .               |
+          1F <-- 1F  1F <-- 1F            |               V
+                                          .
+                                          |           [Server]
+                                          .
+      Answer (same as HTTP):              |               |
+                                          .               |
+          2B --> 2B  2B --> 2B            |               |
+      .----.     .----.     .----.        .               |
+II    |Capi|     |Dpi |     | IO |        |               |
+      '----'     '----'     '----'        .               |
+          2F <-- 2F  2F <-- 2F      <--   |  <------------'
+                                          .
+                                          |
+
+
+CCC Construction:
+
+  a_Capi_open_url()  calls  a_Capi_dpi_send_cmd()  when  the  URL
+belongs to a dpi and it is not cached.
+
+  a_Capi_dpi_send_cmd()  builds  both the Answer and Query chains
+at  once (Answer first then Query), in the same way as HTTP does.
+Note  that  the  answer chain is the same for both, and the query
+chain only differs in the module in the middle ([http] or [dpi]).
+
+
+Function calls for DPI CCC
+--------------------------
+
+  a_Capi_open_url
+    a_Capi_dpi_send_cmd
+      Capi OpStart 2B (answer)    [Capi] --> [dpi]  --> [IO]
+      Capi OpStart 1B (query)     [Capi] --> [http] --> [IO]
+      a_Cache_open_url
+        [...]
+
+
+Normal termination:
+
+  When  the dpi server is done, it closes the FD, and OpEnd flows
+from  IO  to  Capi (answer branch). When in Capi, capi propagates
+OpEnd to the query branch.
+
+Abnormal termination:
+
+  The  transfer may be aborted by a_Capi_conn_abort_by_url(). The
+OpAbort is not yet standardized and has an ad-hoc implementation.
+One idea is to have OpAbort always propagate BCK and then FWD and
+to jump into the other chain when it gets to [Capi].
+
+
+Debugging CCC
+-------------
+
+  A  simple way to "look" inside it, is to "#define VERBOSE 1" in
+chain.c,  and  then to follow its work with a printed copy of the
+diagrams in this document.
+
+  Each new data request generates a CCC, so if you want to debug,
+it's  good  to refine the testcase to the minimum possible number
+of connections.
+