Internet Cache Protocol Specification 1.4
Major Document Sections
This document describes the protocol to be used for exchanging
information among caches, and for application programs
that need guaranteed reliable transmission of binary objects.
A separate
document describes a simpler, ascii-based protocol
for applications to use in accessing a cache.
One major use of this protocol is to enable caches at
lower levels in the cache architecture to retrieve objects
from caches at higher levels, allowing a cache hierarchy
to be constructed.
The architecture supports not only tree structured hierarchies
but any non-cyclical graph.
It also allows a given cache to retrieve objects from more than
one higher level cache.
A mechanism is provided allowing a client to query several
caches and to base the decision of where the object should be
retrieved from on the results of those queries.
Additional goals of the protocol design are to provide
enough information to gather statistics for debugging and
performance tuning, authentication, and retrieval of parameter settings.
The protocol follows a simple request-response style of
interaction.
For the remainder of this document,
the requester is referred to as the client,
while the target of the request is called the server.
In practice, the client may be another
cache or an application, while the server will be a cache.
The term owning server is used to describe the host
which is specified in the URL and on which the original copy
of the object resides.
Responses may include data, which may be large. Response
messages may therefore be sent as a sequence of data "packets",
which must be assembled at the receiving end.
It should be noted however that large responses are actually
sent over a reliable stream connection, so the "packets"
will in fact arrive in order. The packet abstraction simply
provides a way to mark the end of a data transmission so
that the receiver can detect failures in the communications links.
Also, note that each message described below has at most one variable length
field, so that the size of this field is always obtainable
by subtracting the sizes of the other fixed length fields
from the total packet size.
Each packet includes the following fields:
Name Size(bytes) Description
opcode 1 Numeric code indicating type of message
version 1 Version of the protocol being used
length 2 Total length of packet
reqnum 4 Request number assigned by client
authenticator 8 Authentication information (future)
senderid 4 Identification (host id) of sender
Message Types
The following list briefly describes each of the message types which
can occur. A more detailed description follows.
Name Value Description
query 1 Query a cache do determine hit/miss
hit 2 Cache has a copy of the queried object
miss 3 Cache does not have a copy of the queried object
err 4 Some type of error occurred at the server
send 5 Send object to client (retrieve if necessary)
senda 6 Send/validate object to client (retrieve if necessary)
databeg 7 Denotes the beginning of object data
data 8 Denotes the next segment of the object data
dataend 9 Denotes the final segment of the object data
Format
Name Size(bytes) Description
common header 16 Common header
requester 4 Host id of original requester URL
url variable URL whose status is to be checked
Description
This message is used by clients to discover if a cache has
a copy of the object in its resident set.
Typically, it is sent in a single UDP datagram to
one or more servers to see if any have the object in their cache.
The requester field is used to identify the ultimate destination
of the response.
It can be sent over a TCP connection.
This can be used for analyzing the
flow of information through the cache organization.
Responses
Servers may respond with a
Hit,
Miss, or an
Error
message indicating a malformed URL, negative cache hit, etc.
Format
Name Size(bytes) Description
common header 16 Common header
url variable URL whose status is to be checked
Description
This message is sent as a reply by servers that have the
requested object in their caches.
Format
Name Size(bytes) Description
common header 16 Common header
url variable URL whose status is to be checked
Description
This message is sent as a reply by servers that do not have
the requested object in their caches.
Format
Name Size(bytes) Description
common header 16 Common header
error code 2 Numeric error code.
message variable Textual error message.
Description
Errors can be sent in response to
Query,
Send,
or a Senda messages.
The error code gives a way of quickly checking to see
what type of error has occurred and the variable
length message allows the server to send individualized
messages for any error which occurs.
Errors which can Occur
- Bad Version
The server does not support the version which the client is
using for this request.
- Invalid URL
In some cases the server will be able to detect syntax
errors in the URL send with a Query or Send Object
request. This error message should be sent as a reply;
negative caching can by done.
- Timeout
The cache could not retrieve the object in a reasonable amount
of time. This can occur when the host where the object exists
(i.e., the host specified in the URL) is non-responsive.
- Access Denied
The requester does not have appropriate access privileges
for the requested object.
- Service unavailable
The URL specifies an access protocol which the cache server
(or one of the cache servers in the hierarchy) does not support.
- Internal
Some type of internal error occurred on the server which
caused the transmission of the object to fail.
Format
Name Size(bytes) Description
common header 16 Common header
requester 4 Host id of original requester URL
url variable URL whose status is to be checked
Description
This request message is sent by clients to a server, to
request that the specified object be sent as a reply. If
the server does not have the object in its local cache, it
must retrieve the object either from another cache or the
primary source. This object can only be used on a TCP
connection.
Responses
The server will normally respond with a
Data Begin message
but can respond with a
Error message if an
error occurs.
Format
Name Size(bytes) Description
common header 16 Common header
requester 4 Host id of original requester URL
url variable URL whose status is to be checked
Description
This request message is sent by clients to a server, to
request that the specified object be sent as a reply.
If the server does not have the object in its local cache, it
must retrieve the object either from another cache or the
primary source. If the object is located in the cache,
the object is verified to insure that it hasn't been
changed and if it has, the object is invalidated and
refetched. This message can only be sent over a TCP connection.
Responses
The server will normally respond with a
Data Begin message
but can respond with a
Error message if an
error occurs.
Format
Name Size(bytes) Description
common header 16 Common header
size 4 Object size (in bytes) if known; -1 otherwise
ttl 4 Time to live for this object, in seconds
timestamp 4 Time this object was originally obtained
data variable The first segment of data from the object
Description
This message is used by servers to begin send the actual
contents of an object, in response to a
Send or
Send Authoritative message.
It represents the data at offset zero inside the object.
The size field specifies the size of the object if it
is known at the time of the transmission or is set to -1
if the size is not known.
The ttl field is the time, in seconds, since midnight GMT,
of January 1, 1970 (see time(3)) at which the object should be eliminated
from the cache.
The timestamp field is the time that the object was retrieved
from the owning server. This field is the time, in seconds,
since midnight GMT, of January 1, 1970 (see time(3)) when the
object was retrieved. This value is passed, unchanged, down
the cache hierarchy.
Format
Name Size(bytes) Description
common header 16 Common header
offset 4 Offset of this data from beginning of object
data variable A segment of data from the object
Description
This message is used by servers to send a portion
of an object, in response to a Send Object request.
The offset field describes the location, within the object,
which the data in this message represents.
Format
Name Size(bytes) Description
common header 16 Common header
offset 4 Offset of this data from beginning of object
data variable The last segment of an object
Description
This message is used to send the final (possibly zero length) segment
of data to the client.
The offset field describes the location, within the object,
which the data in this message represents.
Given the set of messages specified above, many conversations
are possible between clients and servers. This
flexibility allows different applications to perform different
functions while still using a single protocol. The two common
types of operations are
queries and
retrievals
and are described below.
Query operations are used to determine where a particular client
should go to actually perform the retrieval of the object. One
scenario is to query a set of caches located near the client
in the larger cache hierarchy. One possible implementation of
this would consist of sending a
Query Message
to each of these cache servers using a single, connected UDP
datagram socket. The client then waits for the responses to
arrive on that socket.
Each of these servers will respond with a
Hit or a
Miss message.
When the client receives the first hit message, it selects that
cache to do the
retrieval operation.
If all the caches respond with misses, the cache with the
lowest round-trip time is selected.
When a retrieval is attempted, three things can occur.
- ERROR. This can occur if the cache has some sort of internal
error or if for some reason the cache is refusing to retrieve the
specified object.
- HIT. If the first level cache has the object in its resident
set, the data object is simply supplied to the client.
- MISS. If the first level cache doesn't have the object in its
resident set, it is up to the cache to retrieve the data and supply
it to the client. This retrieval may require the cache to contact
the host specified in the URL itself or may require the cache to
contact another cache up the hierarchy.
Following are descriptions of three cache configurations ranging
from simple to complex. For each configuration, the transmissions
are described for a cache miss. When a miss occurs, the
cache queries all caches up the hierarchy (if any) as well as the
host from the URL being retrieved. The host with the minimum
round trip time is chosen for the retrieval. In all cases, assume
that the url being requested is http://ftp.cs.colorado.edu/pub/info.
Note that in all cases, only some of the clients are shown. Typically
there will be many clients for a particular cache.
Non-Hierarchical Single Cache
The following two diagrams show a very simple cache hierarchy (i.e., no
hierarchy at all) and the message transfers which occur when a cache
miss occurs. The cache, returning a miss for the query and then
processing the send request, contacts the URL host using FTP.
The data is transferred to the cache and forwarded to the client
using the ICP protocol.
Tree Structured Hierarchy
The following two diagrams show a cache hierarchy which is two levels
deep and tree structured. The middle client shown requests an object
from Cache-1 and gets a Miss message back. This cache is then
chosen for the retrieval. Cache-1 then queries up the hierarchy
to Cache-2 and also gets a Miss response. Cache-2 is
then requested to send the data. Cache-2, being at the top
of the hierarchy, retrieves the data from the URL host and forwards
the data as it arrives to Cache-1, who in turns forwards the
data to the client.
Load Balanced Graph Hierarchy
The following two diagrams show a cache hierarchy (only one level deep)
and the message sequences which occur
with the load balanced between two caches. The client queries
each of the two and chooses the cache which has the lowest round-trip
time. In the example shown below, both caches respond with a Miss
message and then Cache-1 is chosen for the retrieval.
This protocol was developed jointly through NSF support
under the NSF Small-Scale Infrastructure Grant award
#CDA-9216321 at the University of Southern California and
through ARPA support under the
New Internet Services for Scalable Resource Discovery
contract #DABT63-93-C-0062 at the University of Colorado-Boulder.
arpa-rd@latour.cs.colorado.edu