This document describes all current ICP OPCODES and FLAGS. Some things are described here, but are NOT in the ICP drafts/RFCs because they were experimental at the time the draft was written. Such items are marked with (*) ============================================================================== 2. ICP Opcodes The following table shows currently defined ICP opcodes: Value Name ----- ----------------- 0 ICP_OP_INVALID 1 ICP_OP_QUERY 2 ICP_OP_HIT 3 ICP_OP_MISS 4 ICP_OP_ERR 5-9 UNUSED 10 ICP_OP_SECHO 11 ICP_OP_DECHO 12 ICP_OP_NOTIFY (*) 13 ICP_OP_INVALIDATE (*) 14 ICP_OP_PURGE (*) 15 ICP_OP_WIRETAP (*) 16-17 UNUSED 18 ICP_OP_MISS_POINTER (*) 19 ICP_OP_ADVERTISE (*) 20 ICP_OP_UNADVERTISE (*) 21 ICP_OP_MISS_NOFETCH 22 ICP_OP_DENIED 23 ICP_OP_HIT_OBJ ICP_OP_INVALID A place holder to detect zero-filled or malformed messages. A cache must never intentionally send an ICP_OP_INVALID message. ICP_OP_ERR should be used instead. ICP_OP_QUERY A query message. NOTE this opcode has a different payload format than most of the others. First is the requester's IPv4 address, followed by a URL. The Requester Host Address is not that of the cache generating the ICP message, but rather the address of the caches's client that originated the request. The Requester Host Address is often zero filled. An ICP message with an all-zero Requester Host Address address should be taken as one where the requester address is not specified; it does not indicate a valid IPv4 address. In response to an ICP_OP_QUERY, the recipient must return one of: ICP_OP_HIT, ICP_OP_MISS, ICP_OP_ERR, ICP_OP_MISS_NOFETCH, ICP_OP_DENIED, or ICP_OP_HIT_OBJ. ICP_OP_SECHO Similar to ICP_OP_QUERY, but for use in simulating a query to an origin server. When ICP is used to select the closest neighbor, the origin server can be included in the algorithm by bouncing an ICP_OP_SECHO message off it's echo port. The payload is simply the null-terminated URL. NOTE: the echo server will not interpret the data (i.e. we could send it anything). This opcode is used to tell the difference between a legitimate query or response, random garbage, and an echo response. ICP_OP_DECHO Similar to ICP_OP_QUERY, but for use in simulating a query to a cache which does not use ICP. When ICP is used to choose the closest neighbor, a non-ICP cache can be included in the algorithm by bouncing an ICP_OP_DECHO message off it's echo port. The pay- load is simply the null-terminated URL. NOTE: one problem with this approach is that while a system's echo port may be functioning perfectly, the cache software may not be running at all. One of the following six ICP opcodes are sent in response to an ICP_OP_QUERY message. Unless otherwise noted, the payload must be the null-terminated URL string. Both the URL string and the Request Number field must be exactly the same as from the ICP_OP_QUERY mes- sage. ICP_OP_HIT An ICP_OP_HIT response indicates that the requested URL exists in this cache and that the requester is allowed to retrieve it. ICP_OP_MISS An ICP_OP_MISS response indicates that the requested URL does not exist in this cache. The querying cache may still choose to fetch the URL from the replying cache. ICP_OP_ERR An ICP_OP_ERR response indicates some kind of error in parsing or handling the query message (e.g. invalid URL). ICP_OP_MISS_NOFETCH An ICP_OP_MISS_NOFETCH response indicates that this cache is up, but is in a state where it does not want to handle cache misses. An example of such a state is during a startup phase where a cache might be rebuilding its object store. A cache in such a mode may wish to return ICP_OP_HIT for cache hits, but not ICP_OP_MISS for misses. ICP_OP_MISS_NOFETCH essentially means ``I am up and run- ning, but please don't fetch this URL from me now.'' Note, ICP_OP_MISS_NOFETCH has a different meaning than ICP_OP_MISS. The ICP_OP_MISS reply is an invitation to fetch the URL from the replying cache (if their relationship allows it), but ICP_OP_MISS_NOFETCH is a request to NOT fetch the URL from the replying cache. ICP_OP_DENIED An ICP_OP_DENIED response indicates that the querying site is not allowed to retrieve the named object from this cache. Caches and proxies may implement complex access controls. This reply must be be interpreted to mean ``you are not allowed to request this par- ticular URL from me at this particular time.'' Caches receiving a high percentage of ICP_OP_DENIED replies are probably misconfigured. Caches should track percentage of all replies which are ICP_OP_DENIED and disable a neighbor which exceeds a certain threshold (e.g. 95% of 100 or more queries). Similarly, a cache should track the percent of ICP_OP_DENIED mes- sages that are sent to a given address. If the percent of denied messages exceeds a certain threshold (e.g. 95% of 100 or more), the cache may choose to ignore all subsequent ICP_OP_QUERY mes- sages from that address until some sort of administrative inter- vention occurs. ICP_OP_HIT_OBJ Just like an ICP_OP_HIT response, but the actual object data has been included in this reply message. Many requested objects are small enough that it is possible to include them in the query response and avoid the need to make a subsequent HTTP request for the object. CAVEAT: ICP_OP_HIT_OBJ has some negative side effects which make its use undesirable. It transfers object data without HTTP and therefore bypasses the standard HTTP processing, including autho- rization and age validation. Another negative side effect is that ICP_OP_HIT_OBJ messages will often be much larger than the path MTU, thereby causing fragmentation to occur on the UDP packet. For these reasons, use of ICP_OP_HIT_OBJ is NOT recommended. A cache must not send an ICP_OP_HIT_OBJ unless the ICP_FLAG_HIT_OBJ flag is set in the query message Options field. The receiving application must check to make sure it actually receives Object Size octets of data. If it does not, then it should treat the ICP_OP_HIT_OBJ reply as though it were a normal ICP_OP_HIT. NOTE: the Object Size field does not necessarily begin on a 32-bit boundary as shown in the diagram above. It begins immediately following the NULL byte of the URL string. ICP_OP_MISS_POINTER (*) This message type is only valid as a response to ICP_OP_QUERY with the ICP_FLAG_POINTER option set. An ICP_OP_MISS_POINTER response indicates that the responder does not have the requested URL, but that it knows of at least one third party cache which is likely to hold the object. The ICP_OP_MISS_POINTER payload consists of a list of (IPv4) addresses of third party caches. The URL is NOT included in the payload. The receiving site can determine request from the unique reqnum field. ICP_OP_MISS_POINTER Payload Format: 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Intermediate Cache Address | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Intermediate Cache Address | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ / / / / +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ ICP_OP_NOTIFY (*) This message is used to notify another (external) application that an HTTP request has been made. The payload format is identical to ICP_OP_QUERY. There is no reply for this message. The ICP_OP_NOTIFY message uses bits in the Option Data field to convey more information about the type of request received. 0x00000008 ICP_NOTIFY_MISS The requested URL does not exist in the local cache. 0x00000004 ICP_NOTIFY_HIT The requested URL exists in the local cache. 0x00000002 ICP_NOTIFY_REFRESH The request included a 'no-cache' header (client reload). 0x00000001 ICP_NOTIFY_IMS The request included an 'If-Modified-Since' header. ICP_OP_INVALIDATE (*) Work in progress. Tell a cache to invalidate (expire?) an object. ICP_OP_PURGE (*) Request a cache to purge (delete) a specific object. The receiver is not obligated to take this action. There is no reply for this message. ICP_OP_ADVERTISE (*) This message is an announcement that the sender holds a specific URL, which is given in the payload. There is no reply for this message. ICP_OP_UNADVERTISE (*) This message is an announcement that the sender no longer holds a specific URL, which is given in the payload. There is no reply for this message. ICP_OP_WIRETAP (*) Instructs any peer who receives this message that the sender would be very appreciative of receiving ICP_OP_NOTIFY, ICP_OP_ADVERTISE, and ICP_OP_UNADVERTISE messages for a duration specified in the query body in a single unsigned 8-bit value (the first 8 bits of the ICP payload). Should the sender already be receiving these notices, it is the expectation that the peer's timeout interval be extended to the amount described above. Added for Skycache (dhankins@mercenary.net). UNRECOGNIZED OPCODES ICP messages with unrecognized or unused opcodes should be ignored, i.e. no reply generated. The application may choose to note the anomalous behaviour in a log file. 3. ICP Option Flags 0x80000000 ICP_FLAG_HIT_OBJ This flag is set in an ICP_OP_QUERY message indicating that it is okay to respond with an ICP_OP_HIT_OBJ message if the object data will fit in the reply. 0x40000000 ICP_FLAG_SRC_RTT This flag is set in an ICP_OP_QUERY message indicating that the requester would like the ICP reply to include the responder's mea- sured RTT to the origin server. Upon receipt of an ICP_OP_QUERY with ICP_FLAG_SRC_RTT bit set, a cache should check an internal database of RTT measurements. If available, the RTT value MUST be expressed as a 16-bit integer, in units of milliseconds. If unavailable, the responder may either set the RTT value to zero, or clear the ICP_FLAG_SRC_RTT bit in the ICP reply. The ICP reply MUST not be delayed while waiting for the RTT measurement to occur. This flag is set in an ICP reply message (ICP_OP_HIT, ICP_OP_MISS, ICP_OP_MISS_NOFETCH, or ICP_OP_HIT_OBJ) to indicate that the low 16-bits of the Option Data field contain the measured RTT to the host given in the requested URL. If ICP_FLAG_SRC_RTT is clear in the query then it MUST also be clear in the reply. If ICP_FLAG_SRC_RTT is set in the query, then it may or may not be set in the reply. 0x20000000 ICP_FLAG_POINTER (*) This flag is set in an ICP_OP_QUERY message indicating that it is okay to respond with an ICP_OP_MISS_POINTER message if the object is not held locally but is known to have been held by a third party within recent history. 0x10000000 ICP_FLAG_PREADVERTISE (*) This flag is set in an ICP_OP_QUERY message indicating that the requesting party is pre-advertising the fact that it holds this URL. This is an optimization, combining the ICP_OP_ADVERTISE and ICP_OP_QUERY messages together, because the requesting party intends to fetch this URL itself if it is unable to discover it in a neighbor cache. A further implication of this flag is that the requester's operations policy allows it to offer this URL to other (some, but not necessarily all) third party caches. 0x08000000 ICP_FLAG_MD5_KEY (*) Instead of a URL in the payload, use an MD5 hash of the URL. There are no known implementations of this option. 0x04000000 ICP_FLAG_DONT_NEED_URL (*) This flag may be set in an ICP_OP_QUERY message to indicate that the querying cache does not require the URL in the reply message. The querying cache can use the reply's REQNUM value to figure out the corresponding URL. 0x02000000 ICP_FLAG_PREFETCH (*) This flag may be set in an ICP_OP_ADVERTISE message to indicate that the sender wants the receiver to prefetch the named URL from the sender. The receiver may or may not elect to prefetch the URL. Added for Skycache (dhankins@mercenary.net).