rfc3507.txt | rfc3507-fixed.txt | |||
---|---|---|---|---|
skipping to change at page 11, line 28 | skipping to change at page 11, line 28 | |||
ICAP uses TCP/IP as a transport protocol. The default port is 1344, | ICAP uses TCP/IP as a transport protocol. The default port is 1344, | |||
but other ports may be used. The TCP flow is initiated by the ICAP | but other ports may be used. The TCP flow is initiated by the ICAP | |||
client to a passively listening ICAP server. | client to a passively listening ICAP server. | |||
ICAP messages consist of requests from client to server and responses | ICAP messages consist of requests from client to server and responses | |||
from server to client. Requests and responses use the generic | from server to client. Requests and responses use the generic | |||
message format of RFC 2822 [3] -- that is, a start-line (either a | message format of RFC 2822 [3] -- that is, a start-line (either a | |||
request line or a status line), a number of header fields (also known | request line or a status line), a number of header fields (also known | |||
as "headers"), an empty line (i.e., a line with nothing preceding the | as "headers"), an empty line (i.e., a line with nothing preceding the | |||
CRLF) indicating the end of the header fields, and a message-body. | CRLF) indicating the end of the header fields, and possibly a | |||
message-body. | ||||
The presence of a message-body is determined exclusively by the | ||||
presence and value of the Encapsulated header documented in Section | ||||
4.4. Thus, the sender MUST include the Encapsulated header in every | ||||
ICAP message with message-body. The message-body syntax and semantics | ||||
are determined by the value of the Encapsulated header. | ||||
The header lines of an ICAP message specify the ICAP resource being | The header lines of an ICAP message specify the ICAP resource being | |||
requested as well as other meta-data such as cache control | requested as well as other meta-data such as cache control | |||
information. The message body of an ICAP request contains the | information. The message body of an ICAP request contains the | |||
(encapsulated) HTTP messages that are being modified. | (encapsulated) HTTP messages that are being modified. | |||
As in HTTP/1.1, a single transport connection MAY (perhaps even | As in HTTP/1.1, a single transport connection MAY (perhaps even | |||
SHOULD) be re-used for multiple request/response pairs. The rules | SHOULD) be re-used for multiple request/response pairs. The rules | |||
for doing so in ICAP are the same as described in Section 8.1.2.2 of | for doing so in ICAP are the same as described in Section 8.1.2.2 of | |||
[4]. Specifically, requests are matched up with responses by | [4]. Specifically, requests are matched up with responses by | |||
allowing only one outstanding request on a transport connection at a | allowing only one outstanding request on a transport connection at a | |||
time. Multiple parallel connections MAY be used as in HTTP. | time. Multiple parallel connections MAY be used as in HTTP. | |||
An ICAP client sending a message-body MUST monitor the transport | ||||
connection for an early ICAP response (i.e., the response that comes | ||||
while the client is still transmitting the request). Such a response | ||||
may be a successful (e.g., 200 "OK") response or not (e.g., 400 "Bad | ||||
Request"). Just like HTTP rules in Section 8.2.2 of [4], this | ||||
requirement eliminates a deadlock when neither client nor server can | ||||
send more data. However, correct early response handling is more | ||||
important (and not limited to errors) for ICAP because ICAP servers | ||||
often have to respond early to avoid buffering the entire | ||||
encapsulated message. Early responses may also decrease end-user | ||||
perceived latency if the client pipelines received content to the | ||||
end-user. | ||||
Regardless of the early response meaning and timing, the ICAP client | ||||
SHOULD finish sending the request. If the client chooses not to | ||||
finish the request, it MUST terminate the transport connection after | ||||
receiving the early response because the ICAP server would not be | ||||
able to detect the end of the ICAP request otherwise. ICAP | ||||
extensions (not defined in this document) MAY supersede these | ||||
requirements by documenting ways to abort the request without | ||||
terminating the transport connection abnormally. | ||||
4.2 ICAP URIs | 4.2 ICAP URIs | |||
All ICAP requests specify the ICAP resource being requested from the | All ICAP requests specify the ICAP resource being requested from the | |||
server using an ICAP URI. This MUST be an absolute URI that | server using an ICAP URI. This MUST be an absolute URI that | |||
specifies both the complete hostname and the path of the resource | specifies both the complete hostname and the path of the resource | |||
being requested. For definitive information on URL syntax and | being requested. For definitive information on URL syntax and | |||
semantics, see "Uniform Resource Identifiers (URI): Generic Syntax | semantics, see "Uniform Resource Identifiers (URI): Generic Syntax | |||
and Semantics," RFC 2396 [1], Section 3. The URI structure defined | and Semantics," RFC 2396 [1], Section 3. The URI structure defined | |||
by ICAP is roughly: | by ICAP is roughly: | |||
skipping to change at page 14, line 50 | skipping to change at page 14, line 50 | |||
400 - Bad request. | 400 - Bad request. | |||
404 - ICAP Service not found. | 404 - ICAP Service not found. | |||
405 - Method not allowed for service (e.g., RESPMOD requested for | 405 - Method not allowed for service (e.g., RESPMOD requested for | |||
service that supports only REQMOD). | service that supports only REQMOD). | |||
408 - Request timeout. ICAP server gave up waiting for a request | 408 - Request timeout. ICAP server gave up waiting for a request | |||
from an ICAP client. | from an ICAP client. | |||
418 - Bad composition. ICAP server needs encapsulated sections | ||||
different from those in the request. | ||||
500 - Server error. Error on the ICAP server, such as "out of disk | 500 - Server error. Error on the ICAP server, such as "out of disk | |||
space". | space". | |||
501 - Method not implemented. This response is illegal for an | 501 - Method not implemented. This response is illegal for an | |||
OPTIONS request since implementation of OPTIONS is mandatory. | OPTIONS request since implementation of OPTIONS is mandatory. | |||
502 - Bad Gateway. This is an ICAP proxy and proxying produced an | 502 - Bad Gateway. This is an ICAP proxy and proxying produced an | |||
error. | error. | |||
503 - Service overloaded. The ICAP server has exceeded a maximum | 503 - Service overloaded. The ICAP server has exceeded a maximum | |||
skipping to change at page 16, line 25 | skipping to change at page 16, line 25 | |||
or bodies of HTTP messages. | or bodies of HTTP messages. | |||
Encapsulated bodies MUST be transferred using the "chunked" | Encapsulated bodies MUST be transferred using the "chunked" | |||
transfer-coding described in Section 3.6.1 of [4]. However, | transfer-coding described in Section 3.6.1 of [4]. However, | |||
encapsulated headers MUST NOT be chunked. In other words, an ICAP | encapsulated headers MUST NOT be chunked. In other words, an ICAP | |||
message-body switches from being non-chunked to chunked as the body | message-body switches from being non-chunked to chunked as the body | |||
passes from the encapsulated header to encapsulated body section. | passes from the encapsulated header to encapsulated body section. | |||
(See Examples in Sections 4.8.3 and 4.9.3.). The motivation behind | (See Examples in Sections 4.8.3 and 4.9.3.). The motivation behind | |||
this decision is described in Section 8.2. | this decision is described in Section 8.2. | |||
HTTP chunked transfer-coding may include a trailer area containing | ||||
HTTP entity-header fields. Since ICAP requires support for chunked | ||||
transfer-coding, an ICAP agent MUST accept an encapsulated trailer, | ||||
if any (i.e., the presence of a trailer must not prevent ICAP | ||||
recipient from correctly parsing and handling an ICAP message). | ||||
Similar to other HTTP message parts, an ICAP server MUST send the | ||||
received trailer back to the ICAP client unless the ICAP server | ||||
modifies or strips trailers as a part of server content adaptation | ||||
actions. | ||||
An ICAP agent MUST NOT send an ICAP header in a trailer area of the | ||||
ICAP message-body encoding unless it knows the recipient expects such | ||||
a header. This document does not define how such an expectation is | ||||
negotiated. In general, sending ICAP headers in the trailer makes it | ||||
impossible for the trailer recipient to distinguish HTTP headers from | ||||
ICAP headers. | ||||
4.4.1 The "Encapsulated" Header | 4.4.1 The "Encapsulated" Header | |||
The offset of each encapsulated section's start relative to the start | The offset of each encapsulated section's start relative to the start | |||
of the encapsulating message's body is noted using the "Encapsulated" | of the encapsulating message's body is noted using the "Encapsulated" | |||
header. This header MUST be included in every ICAP message. For | header. For example, the header | |||
example, the header | ||||
Encapsulated: req-hdr=0, res-hdr=45, res-body=100 | Encapsulated: req-hdr=0, res-hdr=45, res-body=100 | |||
indicates a message that encapsulates a group of request headers, a | indicates a message that encapsulates a group of request headers, a | |||
group of response headers, and then a response body. Each of these | group of response headers, and then a response body. Each of these | |||
is included at the byte-offsets listed. The byte-offsets are in | is included at the byte-offsets listed. The byte-offsets are in | |||
decimal notation for consistency with HTTP's Content-Length header. | decimal notation for consistency with HTTP's Content-Length header. | |||
The special entity "null-body" indicates there is no encapsulated | The special entity "null-body" indicates there is no encapsulated | |||
body in the ICAP message. | HTTP body in the ICAP message. An Encapsulated header value of | |||
"null-body=0" describes a message-body of zero length, which is | ||||
syntactically equivalent to having no message-body. A value of | ||||
"null-body=0" is common for OPTIONS responses, for example. | ||||
The syntax of an Encapsulated header is: | The syntax of an Encapsulated header is: | |||
encapsulated_header: "Encapsulated: " encapsulated_list | encapsulated_header: "Encapsulated: " encapsulated_list | |||
encapsulated_list: encapsulated_entity | | encapsulated_list: encapsulated_entity | | |||
encapsulated_entity ", " encapsulated_list | encapsulated_entity ", " encapsulated_list | |||
encapsulated_entity: reqhdr | reshdr | reqbody | resbody | optbody | encapsulated_entity: reqhdr | reshdr | reqbody | resbody | optbody | |||
reqhdr = "req-hdr" "=" (decimal integer) | reqhdr = "req-hdr" "=" (decimal integer) | |||
reshdr = "res-hdr" "=" (decimal integer) | reshdr = "res-hdr" "=" (decimal integer) | |||
reqbody = { "req-body" | "null-body" } "=" (decimal integer) | reqbody = { "req-body" | "null-body" } "=" (decimal integer) | |||
resbody = { "res-body" | "null-body" } "=" (decimal integer) | resbody = { "res-body" | "null-body" } "=" (decimal integer) | |||
optbody = { "opt-body" | "null-body" } "=" (decimal integer) | optbody = { "opt-body" | "null-body" } "=" (decimal integer) | |||
There are semantic restrictions on Encapsulated headers beyond the | There are semantic restrictions on Encapsulated headers beyond the | |||
syntactic restrictions. The order in which the encapsulated parts | syntactic restrictions. The order in which the encapsulated parts | |||
appear in the encapsulating message-body MUST be the same as the | appear in the encapsulating message-body MUST be the same as the | |||
order in which the parts are named in the Encapsulated header. In | order in which the parts are named in the Encapsulated header. In | |||
other words, the offsets listed in the Encapsulated line MUST be | other words, the offsets listed in the Encapsulated line MUST be | |||
monotonically increasing. In addition, the legal forms of the | monotonically increasing. | |||
Encapsulated header depend on the method being used (REQMOD, RESPMOD, | ||||
or OPTIONS). Specifically: | In addition, the legal forms of the Encapsulated header value depend | |||
on the request method. The value MUST use the following grammar for | ||||
matching requests and 200 "OK" responses to those requests. | ||||
REQMOD request encapsulated_list: [reqhdr] reqbody | REQMOD request encapsulated_list: [reqhdr] reqbody | |||
REQMOD response encapsulated_list: {[reqhdr] reqbody} | | REQMOD response encapsulated_list: {[reqhdr] reqbody} | | |||
{[reshdr] resbody} | {[reshdr] resbody} | |||
RESPMOD request encapsulated_list: [reqhdr] [reshdr] resbody | RESPMOD request encapsulated_list: [reqhdr] [reshdr] resbody | |||
RESPMOD response encapsulated_list: [reshdr] resbody | RESPMOD response encapsulated_list: [reshdr] resbody | |||
OPTIONS request encapsulated_list: [optbody] | ||||
OPTIONS response encapsulated_list: optbody | OPTIONS response encapsulated_list: optbody | |||
In the above grammar, note that encapsulated headers are always | In the above grammar, note that encapsulated headers are always | |||
optional. At most one body per encapsulated message is allowed. If | OPTIONAL. At most one encapsulated body per ICAP message is allowed. | |||
no encapsulated body is presented, the "null-body" header is used | If no encapsulated body is presented, the "null-body" header is used | |||
instead; this is useful because it indicates the length of the header | instead; this is useful because it indicates the length of the header | |||
section. | section. | |||
Interpretation of a message-body depends on the Encapsulated header | ||||
value. This specification defines Encapsulated value semantics for | ||||
three request methods and 200 "OK" responses to those requests. The | ||||
sender MUST NOT include a message-body in any other message unless it | ||||
knows the recipient can handle it; the mechanism to obtain such | ||||
knowledge is beyond the scope of this document. For example, requests | ||||
using extension methods and responses other than 200 "OK" must not | ||||
include a message-body unless the recipient knows how to interpret | ||||
it. | ||||
An ICAP server receiving encapsulated_list that does not match server | ||||
needs MAY respond with a 418 "Bad Composition" error. This situation | ||||
may happen, for example, when the server does not receive | ||||
encapsulated HTTP requests headers in a RESPMOD request but needs | ||||
them to process the encapsulated HTTP response. | ||||
Examples of legal Encapsulated headers: | Examples of legal Encapsulated headers: | |||
/* REQMOD request: This encapsulated HTTP request's headers start | /* REQMOD request: This encapsulated HTTP request's headers start | |||
* at offset 0; the HTTP request body (e.g., in a POST) starts | * at offset 0; the HTTP request body (e.g., in a POST) starts | |||
* at 412. */ | * at 412. */ | |||
Encapsulated: req-hdr=0, req-body=412 | Encapsulated: req-hdr=0, req-body=412 | |||
/* REQMOD request: Similar to the above, but no request body is | /* REQMOD request: Similar to the above, but no request body is | |||
* present (e.g., a GET). We use the null-body directive instead. | * present (e.g., a GET). We use the null-body directive instead. | |||
* In both this case and the previous one, we can tell from the | * In both this case and the previous one, we can tell from the | |||
skipping to change at page 20, line 49 | skipping to change at page 20, line 49 | |||
original request. See Section 4.8.2 and 4.9.2 for the format of | original request. See Section 4.8.2 and 4.9.2 for the format of | |||
reqmod and respmod responses. | reqmod and respmod responses. | |||
- 100 Continue. If the entire encapsulated HTTP body did not fit | - 100 Continue. If the entire encapsulated HTTP body did not fit | |||
in the preview, the ICAP client MUST send the remainder of its | in the preview, the ICAP client MUST send the remainder of its | |||
ICAP message, starting from the first chunk after the preview. If | ICAP message, starting from the first chunk after the preview. If | |||
the entire message fit in the preview (detected by the "EOF" | the entire message fit in the preview (detected by the "EOF" | |||
symbol explained below), then the ICAP server MUST NOT respond | symbol explained below), then the ICAP server MUST NOT respond | |||
with 100 Continue. | with 100 Continue. | |||
As prescribed in Section 4.1.1, 100 "Continue" and 204 "No Content" | ||||
responses must not have message-bodies by default. | ||||
When an ICAP client is performing a preview, it may not yet know how | 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 | many bytes will ultimately be available in the arriving HTTP message | |||
that it is relaying to the HTTP server. Therefore, ICAP defines a | that it is relaying to the HTTP server. Therefore, ICAP defines a | |||
way for ICAP clients to indicate "EOF" to ICAP servers if one | way for ICAP clients to indicate "EOF" to ICAP servers if one | |||
unexpectedly arrives during the preview process. This is a | unexpectedly arrives during the preview process. This is a | |||
particularly useful optimization if a header-only HTTP response | particularly useful optimization if a header-only HTTP response | |||
arrives at the ICAP client (i.e., zero bytes of body); only a single | 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. | round trip will be needed for the complete ICAP server response. | |||
We define an HTTP chunk-extension of "ieof" to indicate that an ICAP | We define an HTTP chunk-extension of "ieof" to indicate that an ICAP | |||
skipping to change at page 22, line 9 | skipping to change at page 22, line 9 | |||
<204 or modified response> (100 Continue disallowed due to ieof) | <204 or modified response> (100 Continue disallowed due to ieof) | |||
If the preview is 1024 bytes and the origin response is 1025 bytes | If the preview is 1024 bytes and the origin response is 1025 bytes | |||
(and the ICAP server responds with 100-continue), then these chunks | (and the ICAP server responds with 100-continue), then these chunks | |||
would appear on the wire: | would appear on the wire: | |||
200\r\n | 200\r\n | |||
<512 bytes of data>\r\n | <512 bytes of data>\r\n | |||
200\r\n | 200\r\n | |||
<512 bytes of data>\r\n | <512 bytes of data>\r\n | |||
0\r\n | 0\r\n\r\n | |||
<100 Continue Message> | <100 Continue Message> | |||
1\r\n | 1\r\n | |||
<1 byte of data>\r\n | <1 byte of data>\r\n | |||
0\r\n\r\n <no ieof because we are no longer in preview mode> | 0\r\n\r\n <no ieof because we are no longer in preview mode> | |||
Once the ICAP server receives the eof indicator, it finishes reading | Once the ICAP server receives the eof indicator, it finishes reading | |||
the current chunk stream. | the current chunk stream. | |||
skipping to change at page 23, line 45 | skipping to change at page 23, line 45 | |||
4.8 Request Modification Mode | 4.8 Request Modification Mode | |||
In this method, described in Section 3.1, an ICAP client sends an | 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 | HTTP request to an ICAP server. The ICAP server returns a modified | |||
version of the request, an HTTP response, or (if the client indicates | version of the request, an HTTP response, or (if the client indicates | |||
it supports 204 responses) an indication that no modification is | it supports 204 responses) an indication that no modification is | |||
required. | required. | |||
4.8.1 Request | 4.8.1 Request | |||
In REQMOD mode, the ICAP request MUST contain an encapsulated HTTP | In REQMOD mode, the ICAP request contains an encapsulated HTTP | |||
request. The headers and body (if any) MUST both be encapsulated, | request. An HTTP request has at most two parts: HTTP request headers | |||
except that hop-by-hop headers are not encapsulated. | (including HTTP Request-Line) and possibly an HTTP request body. An | |||
ICAP client MUST encapsulate at least one part. If the request body | ||||
is not encapsulated, the client MUST use the "null-body" entity. | ||||
To improve interoperability, an ICAP client SHOULD encapsulate all | ||||
available HTTP request parts unless it knows the ICAP server expects | ||||
just one part. Note that an HTTP trailer, if any, is a part of the | ||||
chunked HTTP request body and, hence, may be present in an ICAP | ||||
REQMOD request even if HTTP request headers are not encapsulated. | ||||
An ICAP client MUST NOT encapsulate HTTP hop-by-hop request headers. | ||||
4.8.2 Response | 4.8.2 Response | |||
The response from the ICAP server back to the ICAP client may take | The response from the ICAP server back to the ICAP client may take | |||
one of four forms: | one of four forms: | |||
- An error indication, | - An error indication, | |||
- A 204 indicating that the ICAP client's request requires no | - A 204 indicating that the ICAP client's request requires no | |||
adaptation (see Section 4.6 for limitations of this response), | adaptation (see Section 4.6 for limitations of this response), | |||
skipping to change at page 27, line 38 | skipping to change at page 27, line 38 | |||
In this method, described in Section 3.2, an ICAP client sends an | 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 | the original client request that caused that response. Similar to | |||
Request Modification method, the response from the ICAP server can be | Request Modification method, the response from the ICAP server can be | |||
an adapted HTTP response, an error, or a 204 response code indicating | an adapted HTTP response, an error, or a 204 response code indicating | |||
that no adaptation is required. | that no adaptation is required. | |||
4.9.1 Request | 4.9.1 Request | |||
Using encapsulation described in Section 4.4, the header and body of | In RESPMOD mode, the ICAP request contains optional encapsulated HTTP | |||
the HTTP response to be modified MUST be included in the ICAP body. | request headers and an encapsulated HTTP response. An HTTP response | |||
If available, the header of the original client request SHOULD also | has at most two parts: HTTP response headers (including HTTP | |||
be included. As with the other method, the hop-by-hop headers of the | Status-Line) and possibly an HTTP response body. An ICAP client MUST | |||
encapsulated messages MUST NOT be forwarded. The Encapsulated header | encapsulate at least one of those two parts. If the HTTP response | |||
MUST indicate the byte-offsets of the beginning of each of these four | body is not encapsulated, the client MUST use the "null-body" entity. | |||
parts. | ||||
To improve interoperability, an ICAP client SHOULD encapsulate HTTP | ||||
request headers and all available HTTP response parts unless it knows | ||||
the ICAP server expects something else. Note that an HTTP trailer, | ||||
if any, is a part of the chunked HTTP response body and, hence, may | ||||
be present in an ICAP RESPMOD request even if HTTP response headers | ||||
are not encapsulated. | ||||
An ICAP client MUST NOT encapsulate HTTP hop-by-hop response headers. | ||||
4.9.2 Response | 4.9.2 Response | |||
The response from the ICAP server looks just like a reply in the | The response from the ICAP server looks just like a reply in the | |||
Request Modification method (Section 4.8); that is, | Request Modification method (Section 4.8); that is, | |||
- An error indication, | - An error indication, | |||
- An encapsulated and potentially modified HTTP response header and | - An encapsulated and potentially modified HTTP response header and | |||
response body, or | response body, or | |||
skipping to change at page 29, line 49 | skipping to change at page 29, line 49 | |||
ICAP client sends a request addressed to a specific ICAP resource and | ICAP client sends a request addressed to a specific ICAP resource and | |||
receives back a response with options that are specific to the | receives back a response with options that are specific to the | |||
service named by the URI. All OPTIONS requests MAY also return | service named by the URI. All OPTIONS requests MAY also return | |||
options that are global to the server (i.e., apply to all services). | options that are global to the server (i.e., apply to all services). | |||
4.10.1 OPTIONS Request | 4.10.1 OPTIONS Request | |||
The OPTIONS method consists of a request-line, as described in | The OPTIONS method consists of a request-line, as described in | |||
Section 4.3.2, such as the following example: | Section 4.3.2, such as the following example: | |||
OPTIONS icap://icap.server.net/sample-service ICAP/1.0 User-Agent: | OPTIONS icap://icap.server.net/sample-service ICAP/1.0 | |||
ICAP-client-XYZ/1.001 | User-Agent: ICAP-client-XYZ/1.001 | |||
Other headers are also allowed as described in Section 4.3.1 and | Other headers are also allowed as described in Section 4.3.1 and | |||
Section 4.3.2 (for example, Host). | Section 4.3.2 (for example, Host). | |||
Some ICAP servers may not be able to handle OPTIONS requests with | ||||
message-body because earlier protocol specifications did not | ||||
explicitly allow or prohibit such requests. An ICAP client MUST NOT | ||||
send an OPTIONS request with a message-body, unless the client knows | ||||
that the server can handle such a request. | ||||
4.10.2 OPTIONS Response | 4.10.2 OPTIONS Response | |||
The OPTIONS response consists of a status line as described in | The OPTIONS response consists of a status line as described in | |||
section 4.3.3 followed by a series of header field names-value pairs | section 4.3.3 followed by a series of header field names-value pairs | |||
optionally followed by an opt-body. Multiple values in the value | optionally followed by an opt-body. Multiple values in the value | |||
field MUST be separated by commas. If an opt-body is present in the | field MUST be separated by commas. If an opt-body is present in the | |||
OPTIONS response, the Opt-body-type header describes the format of | OPTIONS response, the Opt-body-type header describes the format of | |||
the opt-body. | the opt-body. | |||
The OPTIONS headers supported in this version of the protocol are: | The OPTIONS headers supported in this version of the protocol are: | |||
skipping to change at page 37, line 11 | skipping to change at page 37, line 11 | |||
1005 ICAP_SERVER_UNEXPECTED_CLOSE: | 1005 ICAP_SERVER_UNEXPECTED_CLOSE: | |||
"ICAP Server closed connection as ICAP client wrote body | "ICAP Server closed connection as ICAP client wrote body | |||
preview". | preview". | |||
6.3 Use of Chunked Transfer-Encoding | 6.3 Use of Chunked Transfer-Encoding | |||
For simplicity, ICAP messages MUST use the "chunked" transfer- | For simplicity, ICAP messages MUST use the "chunked" transfer- | |||
encoding within the encapsulated body section as defined in HTTP/1.1 | encoding within the encapsulated body section as defined in HTTP/1.1 | |||
[4]. This requires that ICAP client implementations convert incoming | [4]. This requires that ICAP client implementations convert incoming | |||
objects "on the fly" to chunked from whatever transfer-encoding on | objects "on the fly" to chunked from whatever transfer-encoding on | |||
which they arrive. However, the transformation is simple: | which they arrive. A straightforward conversion approach is | |||
highlighted below. | ||||
- For objects arriving using "Content-Length" headers, one big chunk | As object content comes in, the ICAP client converts all available | |||
can be created of the same size as indicated in the Content-Length | content bytes into a single chunk to be sent to the ICAP server. If | |||
header. | incoming content is chunked-encoded, the client decodes the encoding | |||
first, to get access to object content. The client follows HTTP rules | ||||
to detect the end of the incoming HTTP message. For example, if the | ||||
client gets an HTTP message with Content-Length of 100KB and gets the | ||||
first 100 bytes of that message content, the client can send the | ||||
first 100 bytes as a single complete chunk. The client should neither | ||||
(a) wait a long time for all 100KB to arrive or (b) announce a 100KB | ||||
chunk but send the first 100 bytes only. | ||||
- For objects arriving using a TCP close to signal the end of the | The above straightforward process can be optimized to minimize | |||
object, each incoming group of bytes read from the OS can be | copying of content bytes, even if the incoming content is chunked. | |||
converted into a chunk (by writing the length of the bytes read, | For example, an implementation can wait a little for more HTTP | |||
followed by the bytes themselves) | content (or the entire HTTP chunk) to become available before forming | |||
and sending a chunk to the ICAP server. | ||||
- For objects arriving using chunked encoding, they can be | When object content length is known a priori, it is tempting to | |||
retransmitted as is (without re-chunking). | declare a single chunk of matching size and then forward incoming | |||
object data as it comes in, without any additional encoding efforts. | ||||
Similarly, it is tempting to forward already chunked content "as is", | ||||
without re-chunking it first. | ||||
However, unrecoverable errors may occur when an ICAP client promises | ||||
to send chunk content that it does not yet have because the promised | ||||
data may never arrive due to origin server or network errors. | ||||
Chunked coding does not have a mechanism to terminate a chunk | ||||
prematurely; the ICAP server would expect all promised bytes. Thus, | ||||
if ICAP client receives fewer than expected HTTP bytes, it has no | ||||
other choice but to close the ICAP connection. A straightforward | ||||
approach described above does not make false promises and avoids the | ||||
problem. | ||||
6.4 Distinct URIs for Distinct Services | 6.4 Distinct URIs for Distinct Services | |||
ICAP servers SHOULD assign unique URIs to each service they provide, | ICAP servers SHOULD assign unique URIs to each service they provide, | |||
even if such services might theoretically be differentiated based on | even if such services might theoretically be differentiated based on | |||
their method. In other words, a REQMOD and RESPMOD service should | their method. In other words, a REQMOD and RESPMOD service should | |||
never have the same URI, even if they do something that is | never have the same URI, even if they do something that is | |||
conceptually the same. | conceptually the same. | |||
This situation in ICAP is similar to that found in HTTP where it | This situation in ICAP is similar to that found in HTTP where it | |||
End of changes. | ||||
This html diff was produced by rfcdiff 1.15e, available from http://www.levkowetz.com/ietf/tools/rfcdiff/ |