/*
* Copyright (C) 1996-2018 The Squid Software Foundation and contributors
*
* Squid software is distributed under GPLv2+ license and includes
* contributions from numerous individuals and organizations.
* Please see the COPYING and CONTRIBUTORS files for details.
*/
/**
\defgroup Adaptation Adaptation
\ingroup Components
\section Term Terminology
- Adaptation: 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).
- Master transaction: HTTP request and response sequence with the
addition of adaptation transactions such as ICAP and eCAP exchanges.
- Service: Specific adaptation identified by a URI. For example, an
ICAP server may provide request filtering and virus monitoring services.
- Optional service: An optional service or its adaptation results may
be completely ignored or bypassed if it helps keeping master transaction
alive.
- Optional transaction: Adaptation transactions with optional services
may be called optional.
- Essential service: A service that is not optional. If an essential
service fails (and there are no replacements), the master transaction must
fail.
- Essential transaction: Adaptation transactions with essential
services may be called optional.
- Virgin: 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.
- Adapted: 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: 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.
*/