[thirdparty/squid.git] / src / adaptation / notes.dox

/**
\defgroup Adaptation
\ingroup Components
 

\section Term Terminology

- <b>Adaptation</b>: Message (header and/or body) inspection, recording, or
  modification outside of Squid core functionality. These notes cover two
  adaptation APIs: ICAP (RFC 3507) and eCAP (www.e-cap.org).

- <b>Master transaction</b>: HTTP request and response sequence with the
  addition of adaptation transactions such as ICAP and eCAP exchanges.

- <b>Service</b>: Specific adaptation identified by a URI. For example, an
  ICAP server may provide request filtering and virus monitoring services.

- <b>Optional service</b>: An optional service or its adaptation results may
  be completely ignored or bypassed if it helps keeping master transaction
  alive.

- <b>Optional transaction</b>: Adaptation transactions with optional services
  may be called optional.

- <b>Essential service</b>: A service that is not optional. If an essential
  service fails (and there are no replacements), the master transaction must
  fail.

- <b>Essential transaction</b>: Adaptation transactions with essential
  services may be called optional.

- <b>Virgin</b>: Being sent or related to something being sent to the
  adaptation service. In a service chain environment, only the first link
  receives its virgin message from the master transaction.

- <b>Adapted</b>: Being received or related to something being received from
  the adaptation service. In a service chain environment, only the last link
  sends the adapted message to the master transaction.


\section ServiceGroups Service sets and chains

Service sets and chains are implemented as ServiceGroup class kids. They are
very similar in most code aspects. The primary external difference is that
ServiceSet can "replace" a service and ServiceChain can find the "next"
service.  The internal group maintenance code is implemented in ServiceGroup
and is parametrized by the kids (see the allServicesSame member).

If an ICAP service with the routing=1 option in squid.conf returns an ICAP
X-Next-Services response header during a successful REQMOD or RESPMOD
transaction, Squid abandones the original adaptation plan and forms a new
adaptation chain consisting of services identified in the X-Next-Services
header value (using a comma-separated list of adaptation service names from
squid.conf).  The dynamically created chain is destroyed once the new plan is
completed or replaced.


\section Layers Adaptation layers

Here is a typical adaptation code sequence:

- Master caller (client- or server-side): Checks ACL and starts
  Adaptation::Iterator for the ACL-selected ServiceGroup.

- Adaptation::Iterator: Creates ServicePlan and executes it, launching one
  service adaptation per step. Abandons the original plan and builds a dynamic
  chain if requested by an eligible service. Aborts adaptations with the
  number of steps exceeding adaptation_service_iteration_limit. This layer
  focus is service set and chain support.

- Transactions Launchers (Adaptation::Icap::Launcher and
  Adaptation::Ecap::XactionRep). Start an ICAP or eCAP transaction(s). ICAP
  Launcher retries or repeats ICAP transactions if needed.  ICAP retries or
  repeats have a single-service scope and are invisible to
  Adaptation::Iterator. See below for eCAP which lacks this layer.

- Adaptation::Icap::ModXact and Adaptation::Ecap::XactionRep: Communicates
  with ICAP or eCAP service to perform the actual adaptation. For optional
  services, handles some failures by short-circuiting adaptation (i.e.,
  cloning the virgin message).

All of the above classes except master callers are Adaptation::Initiate kids.
All of the above classes except transactions are Adaptation::Initiator kids.

*/
Commit	Line	Data
a22e6cd3 AR	1	/**
	2	\defgroup Adaptation
	3	\ingroup Components
	4
	5
	6	\section Term Terminology
	7
	8	- <b>Adaptation</b>: Message (header and/or body) inspection, recording, or
	9	modification outside of Squid core functionality. These notes cover two
	10	adaptation APIs: ICAP (RFC 3507) and eCAP (www.e-cap.org).
	11
	12	- <b>Master transaction</b>: HTTP request and response sequence with the
	13	addition of adaptation transactions such as ICAP and eCAP exchanges.
	14
	15	- <b>Service</b>: Specific adaptation identified by a URI. For example, an
	16	ICAP server may provide request filtering and virus monitoring services.
	17
	18	- <b>Optional service</b>: An optional service or its adaptation results may
	19	be completely ignored or bypassed if it helps keeping master transaction
	20	alive.
	21
	22	- <b>Optional transaction</b>: Adaptation transactions with optional services
	23	may be called optional.
	24
	25	- <b>Essential service</b>: A service that is not optional. If an essential
	26	service fails (and there are no replacements), the master transaction must
	27	fail.
	28
	29	- <b>Essential transaction</b>: Adaptation transactions with essential
	30	services may be called optional.
	31
	32	- <b>Virgin</b>: Being sent or related to something being sent to the
	33	adaptation service. In a service chain environment, only the first link
	34	receives its virgin message from the master transaction.
	35
	36	- <b>Adapted</b>: Being received or related to something being received from
	37	the adaptation service. In a service chain environment, only the last link
	38	sends the adapted message to the master transaction.
	39
	40
	41	\section ServiceGroups Service sets and chains
	42
	43	Service sets and chains are implemented as ServiceGroup class kids. They are
	44	very similar in most code aspects. The primary external difference is that
	45	ServiceSet can "replace" a service and ServiceChain can find the "next"
	46	service. The internal group maintenance code is implemented in ServiceGroup
	47	and is parametrized by the kids (see the allServicesSame member).
	48
	49	If an ICAP service with the routing=1 option in squid.conf returns an ICAP
	50	X-Next-Services response header during a successful REQMOD or RESPMOD
	51	transaction, Squid abandones the original adaptation plan and forms a new
	52	adaptation chain consisting of services identified in the X-Next-Services
	53	header value (using a comma-separated list of adaptation service names from
	54	squid.conf). The dynamically created chain is destroyed once the new plan is
	55	completed or replaced.
	56
	57
	58	\section Layers Adaptation layers
	59
	60	Here is a typical adaptation code sequence:
	61
	62	- Master caller (client- or server-side): Checks ACL and starts
	63	Adaptation::Iterator for the ACL-selected ServiceGroup.
	64
65	- Adaptation::Iterator: Creates ServicePlan and executes it, launching one
66	service adaptation per step. Abandons the original plan and builds a dynamic
67	chain if requested by an eligible service. Aborts adaptations with the
68	number of steps exceeding adaptation_service_iteration_limit. This layer
69	focus is service set and chain support.
70
71	- Transactions Launchers (Adaptation::Icap::Launcher and
72	Adaptation::Ecap::XactionRep). Start an ICAP or eCAP transaction(s). ICAP
73	Launcher retries or repeats ICAP transactions if needed. ICAP retries or
74	repeats have a single-service scope and are invisible to
75	Adaptation::Iterator. See below for eCAP which lacks this layer.
76
77	- Adaptation::Icap::ModXact and Adaptation::Ecap::XactionRep: Communicates
78	with ICAP or eCAP service to perform the actual adaptation. For optional
79	services, handles some failures by short-circuiting adaptation (i.e.,
80	cloning the virgin message).
81
82	All of the above classes except master callers are Adaptation::Initiate kids.
83	All of the above classes except transactions are Adaptation::Initiator kids.
84
85	*/