You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafficserver.apache.org by ig...@apache.org on 2013/12/03 19:48:27 UTC
[4/4] git commit: TS-2397: correct formatting and fix links
TS-2397: correct formatting and fix links
add the graphviz extension to conf.py
indent the digraph so it is actually picked up by sphinx
give it a nicer name, 'g' is too generic! Give it a nicer alt text,
because otherwise we end up with the digraph code.
Consistent formatting & links.
Outstanding: TS_HTTP_REQUEST_TRANSFORM_HOOK and
TS_HTTP_RESPONSE_TRANSFORM_HOOK still need to link to the correct
constants in doc/reference
Project: http://git-wip-us.apache.org/repos/asf/trafficserver/repo
Commit: http://git-wip-us.apache.org/repos/asf/trafficserver/commit/12b687f4
Tree: http://git-wip-us.apache.org/repos/asf/trafficserver/tree/12b687f4
Diff: http://git-wip-us.apache.org/repos/asf/trafficserver/diff/12b687f4
Branch: refs/heads/master
Commit: 12b687f4d92b21b9584a68970d5ef2fa087857cd
Parents: b977ca5
Author: Igor Galić <i....@brainsware.org>
Authored: Tue Dec 3 19:44:19 2013 +0100
Committer: Igor Galić <i....@brainsware.org>
Committed: Tue Dec 3 19:44:19 2013 +0100
----------------------------------------------------------------------
doc/conf.py | 2 +-
doc/sdk/http-hooks-and-transactions.en.rst | 143 ++++++++++++------------
2 files changed, 74 insertions(+), 71 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/12b687f4/doc/conf.py
----------------------------------------------------------------------
diff --git a/doc/conf.py b/doc/conf.py
index d04c26a..6b19426 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -42,7 +42,7 @@ sys.path.insert(0, os.path.abspath('ext'))
# Add any Sphinx extension module names here, as strings. They can be extensions
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.intersphinx', 'sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode', 'traffic-server' ]
+extensions = ['sphinx.ext.graphviz', 'sphinx.ext.intersphinx', 'sphinx.ext.autodoc', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.pngmath', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode', 'traffic-server' ]
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
http://git-wip-us.apache.org/repos/asf/trafficserver/blob/12b687f4/doc/sdk/http-hooks-and-transactions.en.rst
----------------------------------------------------------------------
diff --git a/doc/sdk/http-hooks-and-transactions.en.rst b/doc/sdk/http-hooks-and-transactions.en.rst
index d23227d..916a8af 100644
--- a/doc/sdk/http-hooks-and-transactions.en.rst
+++ b/doc/sdk/http-hooks-and-transactions.en.rst
@@ -42,7 +42,8 @@ The Set of Hooks
To understand hooks and transactions, you should be familiar with the
following terminology:
-***HTTP Transaction***
+HTTP Transaction
+----------------
A **transaction** consists of a single HTTP request from a client and
the response Traffic Server sends to that client. Thus, a transaction
@@ -54,88 +55,90 @@ state machines follow a complex set of states involved in sophisticated
caching and document retrieval (taking into account, for example,
alternate selection, freshness criteria, and hierarchical caching). The
Traffic Server API provides hooks to a subset of these states, as
-illustrated in the `HTTP Transaction State
-Diagram <#HHTTPTxStateDiag>`__ below.
+illustrated in the :ref:`http-txn-state-diagram` below.
-***Transform hooks***
+Transform hooks
+---------------
The two **transform hooks**, ``TS_HTTP_REQUEST_TRANSFORM_HOOK`` and
``TS_HTTP_RESPONSE_TRANSFORM_HOOK``, are called in the course of an HTTP
transform. To see where in the HTTP transaction they are called, look
-for the "set up transform" ovals in the `HTTP Transaction State
-Diagram <#HHTTPTxStateDiag>`__ below.
+for the "set up transform" ovals in the :ref:`http-txn-state-diagram` below.
-***HTTP session***
+HTTP session
+------------
A **session** consists of a single client connection to Traffic Server;
it may consist of a single transaction or several transactions in
succession. The session starts when the client connection opens and ends
when the connection closes.
-**HTTP Transaction State Diagram**
+.. _http-txn-state-diagram:
+HTTP Transaction State Diagram
+------------------------------
.. graphviz::
-digraph g{
- accept -> TS_HTTP_TXN_START_HOOK;
- TS_HTTP_TXN_START_HOOK -> "read req hdrs";
- "read req hdrs" -> TS_HTTP_READ_REQUEST_HDR_HOOK;
- TS_HTTP_READ_REQUEST_HDR_HOOK -> TS_HTTP_PRE_REMAP_HOOK;
- TS_HTTP_PRE_REMAP_HOOK -> "remap request";
- "remap request" -> TS_HTTP_POST_REMAP_HOOK;
- TS_HTTP_POST_REMAP_HOOK -> "cache lookup";
- "cache lookup" -> DNS [label = "miss"];
- DNS -> TS_HTTP_OS_DNS_HOOK;
- TS_HTTP_OS_DNS_HOOK -> TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK;
- "cache lookup" -> TS_HTTP_SELECT_ALT_HOOK [label = "hit"];
- TS_HTTP_SELECT_ALT_HOOK -> "cache match";
- "cache match" -> TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK [label="no match"];
- "cache match" -> TS_HTTP_READ_CACHE_HDR_HOOK [label = "cache fresh"];
- TS_HTTP_READ_CACHE_HDR_HOOK -> "cache fresh";
- "cache fresh" -> TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK;
- TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK -> "lock URL in cache" [label = "miss"];
- TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK -> "lock URL in cache" [label = "no match "];
- TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK -> "lock URL in cache" [label = "stale"];
- TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK -> "send cached hdrs" [label = "fresh"];
- "send cached hdrs" -> "set up transform";
- "lock URL in cache" -> "pick address";
- "pick address" -> "try connect" [label = " "];
- "try connect" -> "pick address" [label = "fail"];
- "try connect" -> TS_HTTP_SEND_REQUEST_HDR_HOOK [label = "success"];
- TS_HTTP_SEND_REQUEST_HDR_HOOK -> "send req hdrs";
- "send req hdrs" -> "set up POST/PUT read" [label = "POST/PUT"];
- "send req hdrs" -> "read reply hdrs" [label = "GET"];
- "set up POST/PUT read" -> "set up req transform";
- "set up req transform" -> "tunnel req body";
- "tunnel req body" -> "read reply hdrs";
- "read reply hdrs" -> TS_HTTP_READ_RESPONSE_HDR_HOOK;
- TS_HTTP_READ_RESPONSE_HDR_HOOK -> "check valid";
- "check valid" -> "setup server read" [label = "yes"];
- "check valid" -> "pick address" [label = "no"];
- "setup server read" -> "set up cache write" [label = "cacheable"];
- "setup server read" -> "set up transform" [label = "uncacheable"];
- "set up cache write" -> "set up transform";
- "set up transform" -> TS_HTTP_SEND_RESPONSE_HDR_HOOK;
- TS_HTTP_SEND_RESPONSE_HDR_HOOK -> "send reply hdrs";
- "send reply hdrs" -> "tunnel response";
- "tunnel response" -> TS_HTTP_TXN_CLOSE_HOOK;
- TS_HTTP_TXN_CLOSE_HOOK -> accept;
-
- TS_HTTP_TXN_START_HOOK [shape=box];
- TS_HTTP_READ_REQUEST_HDR_HOOK [shape = box];
- TS_HTTP_PRE_REMAP_HOOK [shape = box];
- TS_HTTP_POST_REMAP_HOOK [shape = box];
- TS_HTTP_OS_DNS_HOOK [shape = box];
- TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK[shape = box];
- TS_HTTP_SELECT_ALT_HOOK [shape = box];
- TS_HTTP_READ_CACHE_HDR_HOOK [shape = box];
- TS_HTTP_SEND_REQUEST_HDR_HOOK [shape = box];
- "set up req transform" [tooltip = "req transform takes place here"];
- TS_HTTP_READ_RESPONSE_HDR_HOOK [shape = box];
- "set up transform" [tooltip = "response transform takes place here"];
- TS_HTTP_SEND_RESPONSE_HDR_HOOK [shape = box];
- TS_HTTP_TXN_CLOSE_HOOK [shape = box];
-}
-
-
+ :alt: HTTP Transaction State Diagram
+
+ digraph http_txn_state_diagram{
+ accept -> TS_HTTP_TXN_START_HOOK;
+ TS_HTTP_TXN_START_HOOK -> "read req hdrs";
+ "read req hdrs" -> TS_HTTP_READ_REQUEST_HDR_HOOK;
+ TS_HTTP_READ_REQUEST_HDR_HOOK -> TS_HTTP_PRE_REMAP_HOOK;
+ TS_HTTP_PRE_REMAP_HOOK -> "remap request";
+ "remap request" -> TS_HTTP_POST_REMAP_HOOK;
+ TS_HTTP_POST_REMAP_HOOK -> "cache lookup";
+ "cache lookup" -> DNS [label = "miss"];
+ DNS -> TS_HTTP_OS_DNS_HOOK;
+ TS_HTTP_OS_DNS_HOOK -> TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK;
+ "cache lookup" -> TS_HTTP_SELECT_ALT_HOOK [label = "hit"];
+ TS_HTTP_SELECT_ALT_HOOK -> "cache match";
+ "cache match" -> TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK [label="no match"];
+ "cache match" -> TS_HTTP_READ_CACHE_HDR_HOOK [label = "cache fresh"];
+ TS_HTTP_READ_CACHE_HDR_HOOK -> "cache fresh";
+ "cache fresh" -> TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK;
+ TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK -> "lock URL in cache" [label = "miss"];
+ TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK -> "lock URL in cache" [label = "no match "];
+ TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK -> "lock URL in cache" [label = "stale"];
+ TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK -> "send cached hdrs" [label = "fresh"];
+ "send cached hdrs" -> "set up transform";
+ "lock URL in cache" -> "pick address";
+ "pick address" -> "try connect" [label = " "];
+ "try connect" -> "pick address" [label = "fail"];
+ "try connect" -> TS_HTTP_SEND_REQUEST_HDR_HOOK [label = "success"];
+ TS_HTTP_SEND_REQUEST_HDR_HOOK -> "send req hdrs";
+ "send req hdrs" -> "set up POST/PUT read" [label = "POST/PUT"];
+ "send req hdrs" -> "read reply hdrs" [label = "GET"];
+ "set up POST/PUT read" -> "set up req transform";
+ "set up req transform" -> "tunnel req body";
+ "tunnel req body" -> "read reply hdrs";
+ "read reply hdrs" -> TS_HTTP_READ_RESPONSE_HDR_HOOK;
+ TS_HTTP_READ_RESPONSE_HDR_HOOK -> "check valid";
+ "check valid" -> "setup server read" [label = "yes"];
+ "check valid" -> "pick address" [label = "no"];
+ "setup server read" -> "set up cache write" [label = "cacheable"];
+ "setup server read" -> "set up transform" [label = "uncacheable"];
+ "set up cache write" -> "set up transform";
+ "set up transform" -> TS_HTTP_SEND_RESPONSE_HDR_HOOK;
+ TS_HTTP_SEND_RESPONSE_HDR_HOOK -> "send reply hdrs";
+ "send reply hdrs" -> "tunnel response";
+ "tunnel response" -> TS_HTTP_TXN_CLOSE_HOOK;
+ TS_HTTP_TXN_CLOSE_HOOK -> accept;
+
+ TS_HTTP_TXN_START_HOOK [shape=box];
+ TS_HTTP_READ_REQUEST_HDR_HOOK [shape = box];
+ TS_HTTP_PRE_REMAP_HOOK [shape = box];
+ TS_HTTP_POST_REMAP_HOOK [shape = box];
+ TS_HTTP_OS_DNS_HOOK [shape = box];
+ TS_HTTP_CACHE_LOOKUP_COMPLETE_HOOK[shape = box];
+ TS_HTTP_SELECT_ALT_HOOK [shape = box];
+ TS_HTTP_READ_CACHE_HDR_HOOK [shape = box];
+ TS_HTTP_SEND_REQUEST_HDR_HOOK [shape = box];
+ "set up req transform" [tooltip = "req transform takes place here"];
+ TS_HTTP_READ_RESPONSE_HDR_HOOK [shape = box];
+ "set up transform" [tooltip = "response transform takes place here"];
+ TS_HTTP_SEND_RESPONSE_HDR_HOOK [shape = box];
+ TS_HTTP_TXN_CLOSE_HOOK [shape = box];
+ }