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