client
Click on the red underlined text to get to the source
... bandwidths. The model of centralized, monolithic servers that are
responsible for all aspects of every client's request seems to be
reaching the end of its useful life.
...
... reaching the end of its useful life.
To keep up with the growth in the number of clients, there has been a
move towards architectures that scale better through the use of
...
... side, replication and load-balancing techniques allow the burden of
client requests to be spread out over a myriad of servers. Content
providers have also begun to deploy geographically diverse content
distribution networks that bring origin-servers closer to the "edge ...
... edge"
of the network where clients are attached. These networks of
distributed origin-servers or "surrogates" allow the content provider ...
... ICAP is, in essence, a lightweight protocol for executing a "remote
procedure call" on HTTP messages. It allows ICAP clients to pass
HTTP messages to ICAP servers for some sort of transformation or
...
... transformation service on messages and sends back responses to the
client, usually with modified messages. The adapted messages may be
either HTTP requests or HTTP responses ...
... caches can then
use an ICAP call to a nearby ad-insertion server every time the
page is served to a client.
Other such transformations by edge ...
... content
distribution network), or as a value-added service provided by a
client's network provider (as in a surrogate). Examples of these
...
... surrogate (e.g., a caching proxy). The surrogate, acting as an
ICAP client, can ask an external server to check the executable
for viruses before accepting it into its cache ...
...
o Firewalls or surrogates can act as ICAP clients and send outgoing
requests to a service that checks to make sure the URI ...
... this document specifies how to send an HTTP message from an ICAP
client to an ICAP server, specify the URI of the ICAP resource
requested along with other resource-specific parameters, and receive
...
... the rules for recognizing messages that require adaptation, the URIs
of available adaptation resources, and so on. For ICAP clients and
servers to interoperate, the exact method used to define policy need
not be consistent across implementations, as long as the policy
...
... data formats, size, resolutions) or vary in other ways.
client:
A program that establishes connections for the purpose of sending
...
... service requests by sending back responses. Any given program may
be capable of being both a client and a server; our use of these
terms refers only to the role being performed by the program for a
...
... proxy:
An intermediary program which acts as both a server and a client
for the purpose of making requests on behalf of other clients.
...
... An intermediary program which acts as both a server and a client
for the purpose of making requests on behalf of other clients.
Requests are serviced internally or by passing them on, with
possible translation, to other servers. A proxy ...
... possible translation, to other servers. A proxy MUST implement
both the client and server requirements of this specification.
...
... time and network bandwidth consumption on future, equivalent
requests. Any client or server may include a cache, though a
cache ...
... application services ICAP requests.
ICAP client:
A program that establishes connections to ICAP servers for the
...
... A program that establishes connections to ICAP servers for the
purpose of sending requests. An ICAP client is often, but not
always, a surrogate acting on behalf of a user.
...
...
In "request modification" (reqmod) mode, an ICAP client sends an HTTP
request to an ICAP server. The ICAP server may then:
...
...
1) Send back a modified version of the request. The ICAP client may
then perform the modified request by contacting an origin server;
or, pipeline the modified request to another ICAP server for
...
... 3) Return an error.
ICAP clients MUST be able to handle all three types of responses.
However, in line with the guidance provided for HTTP surrogates in
...
... HTTP surrogates in
Section 13.8 of [4], ICAP client implementors do have flexibility in
handling errors. If the ICAP server returns an error, the ICAP
client ...
... client implementors do have flexibility in
handling errors. If the ICAP server returns an error, the ICAP
client may (for example) return the error to the user, execute the
unadapted request as it arrived from the client, or re-try the
...
... client may (for example) return the error to the user, execute the
unadapted request as it arrived from the client, or re-try the
adaptation again.
...
... filtering. Consider a surrogate that receives a request from a
client for a web page on an origin server. The surrogate, acting as
an ICAP client, sends the client ...
... client for a web page on an origin server. The surrogate, acting as
an ICAP client, sends the client's request to an ICAP server that
performs URI ...
... client for a web page on an origin server. The surrogate, acting as
an ICAP client, sends the client's request to an ICAP server that
performs URI-based content filtering ...
... filtering. If access to the requested URI
is allowed, the request is returned to the ICAP client unmodified.
However, if the ICAP server chooses to disallow access to the
requested resources, it may either:
...
... | |
\|/ | 2
ICAP-client --------------> ICAP-resource
(surrogate) <-------------- on ICAP-server
| /|\ 3
...
... client
1. A client makes a request to a ICAP-capable surrogate (ICAP client)
for an object on an origin server.
...
...
1. A client makes a request to a ICAP-capable surrogate (ICAP client)
for an object on an origin server.
...
... service on the
request and sends the possibly modified request, or a response to
the request back to the ICAP client.
If Step 3 returned a request:
...
...
4. The surrogate sends the request, possibly different from original
client request, to the origin server.
5. The origin server responds to request.
...
...
6. The surrogate sends the reply (from either the ICAP server or the
origin server) to the client.
...
...
In the "response modification" (respmod) mode, an ICAP client sends
an HTTP response to an ICAP server. (The response sent by the ICAP
...
... an HTTP response to an ICAP server. (The response sent by the ICAP
client typically has been generated by an origin server.) The ICAP
server may then:
...
... post-processing
performed on an HTTP response before it is delivered to a client.
Examples include formatting HTML for display on special devices,
...
... | |
\|/ | 4
ICAP-client --------------> ICAP-resource
(surrogate) <-------------- on ICAP-server
| /|\ 5
...
... client
1. A client makes a request to a ICAP-capable surrogate (ICAP client)
for an object on an origin server.
...
...
1. A client makes a request to a ICAP-capable surrogate (ICAP client)
for an object on an origin server.
...
... service on the origin
server's reply and sends the possibly modified reply back to the
ICAP client.
6. The surrogate sends the reply, possibly modified from the original
...
...
6. The surrogate sends the reply, possibly modified from the original
origin server's reply, to the client.
...
... ports may be used. The TCP flow is initiated by the ICAP
client to a passively listening ICAP server.
ICAP messages consist of requests from client ...
... client to a passively listening ICAP server.
ICAP messages consist of requests from client to server and responses
from server to client. Requests and responses use the generic
...
... ICAP messages consist of requests from client to server and responses
from server to client. Requests and responses use the generic
message format of RFC 2822prop ...
... interfaces.
Any arguments that an ICAP client wishes to pass to an ICAP service
to modify the nature of the service ...
... methods are allowed. Before attempting to use
an extension method, an ICAP client SHOULD use the OPTIONS method to
query ...
...
408 - Request timeout. ICAP server gave up waiting for a request
from an ICAP client.
500 - Server error. Error on the ICAP server, such as "out of disk
...
... connection limit associated with this service; the ICAP client
should not exceed this limit in the future.
...
... HTTP, the 4xx class of error codes indicate client errors, and
the 5xx class indicate server errors.
...
... Although this ICAP specification can not mandate how HTTP is used in
communication between HTTP clients and servers, we do suggest a
convention: such headers (if used) SHOULD start ...
... convention: such headers (if used) SHOULD start with "X-ICAP". HTTP
clients with ICAP services SHOULD minimally include an "X-ICAP-
Version ...
... header section (not the encapsulated
message). This allows propagation of client credentials that might
have been sent to the ICAP client ...
... client credentials that might
have been sent to the ICAP client in cases where the ICAP client is
also an HTTP ...
... credentials that might
have been sent to the ICAP client in cases where the ICAP client is
also an HTTP surrogate. Note that this does not contradict HTTP/1.1 ...
... proxy MAY relay the credentials from the
client request to the next proxy if that is the mechanism by which
the proxies ...
...
ICAP REQMOD or RESPMOD requests sent by the ICAP client to the ICAP
server may include a "preview". This feature allows an ICAP server
to see the beginning of a transaction ...
... method (see Section 4.10) to
specify how many bytes of preview are needed for a particular ICAP
application on a per-resource basis. Clients SHOULD be able to
provide Previews of at least 4096 bytes. Clients furthermore SHOULD
...
... application on a per-resource basis. Clients SHOULD be able to
provide Previews of at least 4096 bytes. Clients furthermore SHOULD
provide a Preview when using any ICAP resource that has indicated a
Preview is useful. (This indication might be provided via the
...
... OPTIONS method, or some other "out-of-band" configuration.) Clients
SHOULD NOT provide a larger Preview than a server has indicated it is
willing to accept.
...
... willing to accept.
To effect a Preview, an ICAP client MUST add a "Preview:" header to
its request headers ...
... its request headers indicating the length of the preview. The ICAP
client then sends:
- all of the encapsulated ...
... number of bytes advertised in the Preview (possibly 0).
After the Preview is sent, the client stops and waits for an
intermediate response from the ICAP server before continuing. This
mechanism is similar to the "100-Continue" feature found in HTTP ...
... For example, to effect a Preview consisting of only encapsulated HTTP
headers, the ICAP client would add the following header to the ICAP
request:
...
... Preview: 4096
Indicates that the ICAP client will attempt to send 4096 bytes of
origin server data in the encapsulated body of the ICAP request to
...
... encapsulated body of the ICAP request to
the ICAP server. It is important to note that the actual transfer
may be less, because the ICAP client is acting like a surrogate and
is not looking ahead to find the total length of the origin server
response. The entire ICAP encapsulated ...
... transactions.
After sending the preview, the ICAP client will wait for a response
from the ICAP server. The response MUST be one of the following:
...
...
- 204 No Content. The ICAP server does not want to (or can not)
modify the ICAP client's request. The ICAP client MUST treat this
the same as if it had sent the entire message to the ICAP server
...
... - 204 No Content. The ICAP server does not want to (or can not)
modify the ICAP client's request. The ICAP client MUST treat this
the same as if it had sent the entire message to the ICAP server
and an identical message was returned.
...
... encapsulated HTTP body did not fit
in the preview, the ICAP client MUST send the remainder of its
ICAP message, starting from the first chunk after the preview. If
...
... with 100 Continue.
When an ICAP client is performing a preview, it may not yet know how
many bytes will ultimately be available in the arriving HTTP message
...
... that it is relaying to the HTTP server. Therefore, ICAP defines a
way for ICAP clients to indicate "EOF" to ICAP servers if one
...
... header-only HTTP response
arrives at the ICAP client (i.e., zero bytes of body); only a single
round trip will be needed for the complete ICAP server response ...
... process.
For example, consider an ICAP client that has just received HTTP
response headers from an origin server and initiates an ICAP RESPMOD
...
... not using the Content-Length header. The ICAP client informs the
ICAP server that it will be sending a 1024-byte preview using a
"Preview: 1024" request header ...
... HTTP origin server then
closes its connection to the ICAP client before sending any data
(i.e., it provides a zero-byte body), the corresponding zero-byte
preview for that zero-byte origin response would appear as follows:
...
...
If an ICAP server sees this preview, it knows from the presence of
"ieof" that the client will not be sending any more chunk data. In
this case, the server MUST respond with the modified response or a
204 No Content message right away. It MUST NOT send a 100-Continue
...
... stream.
Note that when offering a Preview, the ICAP client is committing to
temporarily buffer the previewed portion of the message so that it
...
...
An ICAP client MAY choose to honor "204 No Content" responses for an
entire message. This is the decision of the client because it
...
... An ICAP client MAY choose to honor "204 No Content" responses for an
entire message. This is the decision of the client because it
imposes a burden on the client of buffering ...
... entire message. This is the decision of the client because it
imposes a burden on the client of buffering the entire message.
...
... buffering the entire message.
An ICAP client MAY include "Allow: 204" in its request headers,
indicating that the server MAY reply to the message with a "204 No
...
... If an ICAP server receives a request that does not have "Allow: 204",
it MUST NOT reply with a 204. In this case, an ICAP server MUST
return the entire message back to the client, even though it is
identical to the message it received.
...
... for ICAP servers to send a service-specific "cookie" to ICAP clients
that represents a service's current state ...
... service. An ISTag validates that previous ICAP
server responses can still be considered fresh by an ICAP client that
may be caching them. If a change on the ICAP server invalidates
previous responses, the ICAP server can invalidate portions of the
...
... may be caching them. If a change on the ICAP server invalidates
previous responses, the ICAP server can invalidate portions of the
ICAP client's cache by changing its ISTag. The ISTag MUST be
included in every ICAP response from an ICAP server.
...
...
In this method, described in Section 3.1, an ICAP client sends an
HTTP request to an ICAP server. The ICAP server returns a modified
...
... version of the request, an HTTP response, or (if the client indicates
it supports 204 responses) an indication that no modification is
required.
...
...
The response from the ICAP server back to the ICAP client may take
one of four forms:
...
... error indication,
- A 204 indicating that the ICAP client's request requires no
adaptation (see Section 4.6 for limitations of this response),
...
... described in Section 4.3.3. If the return code is a 2XX, the ICAP
client SHOULD continue its normal execution of the request. If the
ICAP client is a surrogate, this may include serving an object from
...
... client SHOULD continue its normal execution of the request. If the
ICAP client is a surrogate, this may include serving an object from
its cache or forwarding the modified request to an origin server.
...
... error response, which in turn should be returned to the
downstream client by the ICAP client.
...
...
For other return codes that indicate an error, the ICAP client MAY
(for example) return the error to the downstream client ...
... client MAY
(for example) return the error to the downstream client or user,
execute the unadapted request as it arrived from the client, or re-
...
... downstream client or user,
execute the unadapted request as it arrived from the client, or re-
try the adaptation again.
...
... The modified request headers, if any, MUST be returned to the ICAP
client using appropriate encapsulation as described in Section 4.4.
...
...
Consider the following example, in which a surrogate receives a
simple GET request from a client. The surrogate, acting as an ICAP
client, then forwards this request to an ICAP server for
...
... simple GET request from a client. The surrogate, acting as an ICAP
client, then forwards this request to an ICAP server for
modification. The ICAP server modifies the request headers and sends
...
... modification. The ICAP server modifies the request headers and sends
them back to the ICAP client. Our hypothetical ICAP server will
modify several headers and strip the cookie ...
...
In this method, described in Section 3.2, an ICAP client sends an
origin server's HTTP response to an ICAP server, and (if available)
...
... origin server's HTTP response to an ICAP server, and (if available)
the original client request that caused that response. Similar to
Request Modification method, the response from the ICAP server can be
...
... HTTP response to be modified MUST be included in the ICAP body.
If available, the header of the original client request SHOULD also
be included. As with the other method, the hop-by-hop headers ...
...
- An HTTP response 204 indicating that the ICAP client's request
requires no adaptation.
...
... described in Section 4.3.3. If the return code is a 2XX, the ICAP
client SHOULD continue its normal execution of the response. The
ICAP client MAY re-examine the headers ...
... client SHOULD continue its normal execution of the response. The
ICAP client MAY re-examine the headers in the response's message
headers in order to make further decisions about the response (e.g.,
...
...
For other return codes that indicate an error, the ICAP client SHOULD
NOT return these directly to downstream client ...
... client SHOULD
NOT return these directly to downstream client, since these errors
only make sense in the ICAP client/server transaction ...
... downstream client, since these errors
only make sense in the ICAP client/server transaction.
...
... The modified response headers, if any, MUST be returned to the ICAP
client using appropriate encapsulation as described in Section 4.4.
...
...
In Example 4, an ICAP client is requesting modification of an entity
that was returned as a result of a client ...
... client is requesting modification of an entity
that was returned as a result of a client GET. The original client
GET was to an origin server at "www.origin-server.com"; the ICAP
...
... entity
that was returned as a result of a client GET. The original client
GET was to an origin server at "www.origin-server.com"; the ICAP
server is at "icap.example.org".
...
...
The ICAP "OPTIONS" method is used by the ICAP client to retrieve
configuration information from the ICAP server. In this method ...
... configuration information from the ICAP server. In this method, the
ICAP client sends a request addressed to a specific ICAP resource and
receives back a response with options that are specific to the
service ...
... If none is specified, the OPTIONS response does not expire. This
header MAY be included in the OPTIONS response. The ICAP client
MAY reissue an OPTIONS request once the Options-TTL expires.
...
... -- Preview:
The number of bytes to be sent by the ICAP client during a
preview. This header MAY be included in the OPTIONS response.
...
...
In example 5, an ICAP Client sends an OPTIONS Request to an ICAP
Service named icap.server.net/sample-service ...
... Host: icap.server.net
User-Agent: BazookaDotCom-ICAP-Client-Library/2.3
----------------------------------------------------------------
...
...
ICAP servers' responses MAY be cached by ICAP clients, just as any
other surrogate might cache HTTP responses ...
... HTTP responses. Similar to HTTP, ICAP
clients MAY always store a successful response (see sections 4.8.2
and 4.9.2) as a cache entry, and MAY return it without validation ...
... HTTP response (NOT in the ICAP
header section). Consequently, the ICAP client SHOULD look for
caching directives in the ICAP headers in case of REQMOD, and in the
...
... different adaptation channels: modification (and satisfaction) of
requests, and modifications of replies. However, an ICAP client
implementation is likely to actually distinguish among four different
classes ...
... classes of adaptation:
1. Adaptation of client requests. This is adaptation done every
time a request arrives from a client. This is adaptation done
...
... 1. Adaptation of client requests. This is adaptation done every
time a request arrives from a client. This is adaptation done
when a request is "on its way into the cache". Factors such as
...
... access
control or authentication services that must be performed on a
per-client basis.
2. Adaptation of requests on their way to an origin server.
...
... cache"; i.e., if a request actually requires that
an origin server be contacted. These adaptation requests are not
necessarily specific to particular clients. An example would be
addition of "Accept:" headers for special devices; these
...
... addition of "Accept:" headers for special devices; these
adaptations can potentially apply to many clients.
3. Adaptations of responses coming from an origin server. This is
...
... other words, this is adaptation that a surrogate might want to
perform on an object before caching it. The adapted object may
subsequently served to many clients. An example of this type of
adaptation is virus checking: a surrogate will want to check an
...
... the cache -- not every time the cached object is served to a
client.
Adaptation of responses coming from the surrogate, heading back
...
...
Adaptation of responses coming from the surrogate, heading back
to the client. Although this type of adaptation, like (3), is
the adaptation of a response, it is client-specific. Client ...
... to the client. Although this type of adaptation, like (3), is
the adaptation of a response, it is client-specific. Client
reply adaptation is adaptation that is required every time an
...
... client. Although this type of adaptation, like (3), is
the adaptation of a response, it is client-specific. Client
reply adaptation is adaptation that is required every time an
object is served to a client ...
... Client
reply adaptation is adaptation that is required every time an
object is served to a client, even if all the replies come from
the same cached object off of disk. Ad insertion is a common
form of this kind of adaptation; e.g., if a popular (cached)
...
... form of this kind of adaptation; e.g., if a popular (cached)
object that rarely changes needs a different ad inserted into it
every time it is served off disk to a client. Note that the
relationship between adaptations of type (3) and (4) is analogous
to the relationship between types (2) and (1).
...
... Although the distinction among these four adaptation points is
critical for ICAP client implementations, the distinction is not
significant for the ICAP protocol itself. From the point of view of
an ICAP server, a request is a request -- the ICAP server doesn't
...
... significant for the ICAP protocol itself. From the point of view of
an ICAP server, a request is a request -- the ICAP server doesn't
care what policy led the ICAP client to generate the request. We
therefore did not make these four channels explicit in ICAP for
...
... interoperability. In
this section, we describe errors that are communicated between ICAP
software and the clients and servers on which they are implemented.
Although such errors are implementation dependent and do not
necessarily need to be standardized because they are "within the
...
... TCP-shutdowns the connection before the ICAP
client can send all the body data.
1002 ICAP_SERVER_RESPONSE_RESET:
...
... An unknown ICAP response code (see Section 4.x) was received by
the ICAP client.
1004 ICAP_SERVER_UNEXPECTED_CLOSE_204:
...
... 1005 ICAP_SERVER_UNEXPECTED_CLOSE:
"ICAP Server closed connection as ICAP client wrote body
preview".
...
... HTTP/1.1
[4]. This requires that ICAP client implementations convert incoming
objects "on the fly" to chunked from whatever transfer-encoding on
...
... - WWW-Authenticate challenges and responses are for end-to-end
authentication between a client (user) and an origin server. As
any proxy, ICAP clients ...
... client (user) and an origin server. As
any proxy, ICAP clients and ICAP servers MUST forward these
headers without modification.
...
...
There are potential applications where a user (as opposed to ICAP
client) might have rights to access an ICAP service. In this version
...
... service. In this version
of the protocol, we assume that ICAP clients and ICAP servers are
under the same administrative domain, and contained in a single trust ...
... domain. Therefore, in these cases, we assume that it is sufficient
for users to authenticate themselves to the ICAP client (which is a
surrogate from the point of view from the user). This type of
authentication ...
... method for a user to
authenticate directly to an ICAP server; the ICAP client MUST be
involved as described above.
...
... network layers, eavesdroppers may be able
to record the unencrypted transactions between ICAP clients and
servers. As described in Section 4.3.1, the Upgrade header MAY be
used to negotiate transport-layer ...
...
Note also that end-to-end encryption between a client and origin
server is likely to preclude the use of value-added services by
...
... services by
intermediaries such as surrogates. An ICAP server that is unable to
decrypt a client's messages will, of course, be unable to perform any
transformations on it.
...
... HTTP is well-understood in the community and has enjoyed significant
investments in software infrastructure (clients, servers, parsers,
etc.). Our initial designs focused on leveraging that existing work;
we hoped that it would be possible to implement ICAP services ...
... features that we considered important were impossible to implement
with HTTP. For example, ICAP clients can stop and wait for a "100
Continue" message in the midst of a message-body; HTTP clients ...
... clients can stop and wait for a "100
Continue" message in the midst of a message-body; HTTP clients may
only wait between the header and body. In addition, certain
...
... First, efficiency is important, and the chunked encoding allows both
the client and server to keep the transport-layer connection open for
...
... standardizing on a single encapsulation mechanism, we avoid the
complexity that would be required in client and server software to
support multiple mechanisms. This simplifies ICAP, particularly in
the "body preview" feature described in Section 4.5.
...
... HTTP message body is being
encapsulated in an ICAP message, the ICAP client (HTTP server) can
copy it directly from the HTTP client ...
... client (HTTP server) can
copy it directly from the HTTP client to the ICAP server without un-
chunking and then re-chunking it. Second, many header-parser
...