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Ä <[email protected]> Authored: Tue Dec 3 19:44:19 2013 +0100 Committer: Igor GaliÄ <[email protected]> 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]; + }
