D.3 HTCP Opcodes

only for RuBoard - do not distribute or recompile

HTCP/0.0 defines five opcodes: NOP, TST, MON, SET, and CLR. Note that ICP has different opcodes for queries and replies ”for example, ICP_OP_QUERY and ICP_OP_MISS. HTCP, however, uses the same opcode for both messages. The previously described RR flag indicates whether a given message is a request or a response. The following sections describe each opcode, including how each one uses the OP-DATA field.

D.3.1 NOP

The NOP (null operation) opcode is similar to an ICMP echo or a "ping" message. It can be used to measure network delays between caches, as well as simply to find out if they are alive .

There is no OP-DATA for either NOP queries or responses, and the RESPONSE code is always zero.

D.3.2 TST

The TST (test) opcode is similar to the ICP query operation. It tests for the existence of a cached response in a neighbor cache.

D.3.2.1 TST request

For a TST request, the OP-DATA is a SPECIFIER. Recall that a SPECIFIER includes the HTTP request method, URI, HTTP version, and the client's request headers. The request headers are important because the client may have certain freshness requirements ( Cache-control : max-age or max-stale ).

D.3.2.2 TST response

Table D-2 shows the RESPONSE codes defined for a TST response when F1 is not set.

Table D-2. HTCP TST Response Codes

Code	Description
	Entity is present in responder 's cache.
1	Entity is not present in responder's cache.

Note that the RESPONSE code indicates only the presence or absence of the object and says nothing about its freshness. If the cached object is stale, the server may set the RESPONSE code to either 1 or 0. Setting RESPONSE to 1 forces the client to predict a cache miss for the request. Setting it to 0, however, causes the client to make its own hit/ miss prediction based on the HTTP reply headers included in the TST response. In other words, the client cannot predict a cache hit simply because the RESPONSE code is 0.

When the RESPONSE code is 0, the TST response OP-DATA is a DETAIL that describes the cached response. In particular, it includes the HTTP entity headers ( Expires , Last-modified , Content-length , etc.) and the HTTP response headers ( Age , Vary , etc.). The HTCP client must check the entity headers for freshness information. It may want to collect a number of responses and then choose the cache that has the most recent copy of the object. The DETAIL may also include various cache headers, which are potentially useful bits of information a cache has learned about the resource.

When the RESPONSE code is 1, the TST response OP-DATA consists of CACHE-HDRS (a COUNTSTR) only. Even though the other cache doesn't have a copy of the resource, it might have information that can help to minimize the time to fetch the object.

D.3.3 MON

The MON (monitor) opcode allows caches to inform each other about the objects they add, delete, and update. It is similar to the WIRETAP, ADVERTISE, and UNADVERTISE opcodes of ICP. With the MON opcode, a cache knows which objects its neighbor has stored and therefore may be able to avoid per-request delays caused by TST messages.

The monitoring feature has the potential to expose private information about a cache to third parties. Imagine a clever person being able to find out which web sites the cache users visit. Although authentication is optional with HTCP/0.0, implementations should require authentication for the MON opcode, or at least support address-based access controls.

D.3.3.1 MON request

The MON request message initiates a monitoring session with another cache. That is, the sender asks the receiver to send back a stream of MON responses for some amount of time.

The MON request OP-DATA is simply a one-octet (8 bits) time field. It specifies the duration, in seconds, for the monitoring session. Given the size of this field, the maximum possible value is 255 seconds.

D.3.3.2 MON response

Table D-3 lists the two possible RESPONSE codes for a MON response.

Table D-3. HTCP MON Response Codes

Code	Description
	Request accepted; the OP-DATA field contains useful data.
1	Request refused because too many MON sessions are already active.

When the RESPONSE code is 0, the OP-DATA field has the structure shown in Figure D-8.

Figure D-8. HTCP MON OP-DATA format

These are the parts of the OP-DATA field:

TIME: TIME is the number of seconds remaining for the current monitoring session (identified by the MSG-ID field).
ACTION: ACTION is a numeric code that indicates the action taken on the given object. The valid ACTION codes are given in Table D-4.

Table D-4. HTCP ACTION Values

Code	Description
	The object has been added to the cache.
1	The object in the cache has been refreshed. This corresponds to receiving a 304 Not Modified reply from a validation request.
2	The object in the cache has been replaced . This corresponds to receiving a full response for a cached object. The new response may or may not be different that the cached response. This can occur from a `no-cache` reload, or from a validation request that returns 200 (OK).
3	An entity in the cache has been deleted.

REASON: A numeric code that indicates the reason for the ACTION taking place. The valid reason codes are shown in Table D-5.

Table D-5. HTCP MON Reason Codes

Code	Description
	A reason not covered by any of the other REASON codes.
1	A proxy client requested this resource.
2	A proxy client requested this resource, but caching is disallowed .
3	The proxy prefetched this resource.
4	The resource expired , per the reply headers.
5	The resource was purged because of the cache's storage limits.

D.3.4 SET

The SET opcode allows one cache to push certain updates to another. For example, when a cache issues a validation request and receives a 304 (Not Modified) response, some of the reply headers ( Age , Expires ) are updated. Pushing these updated headers to neighbor caches with a SET message obviates the need for the neighbors to issue validation requests .

SET requests must be handled carefully because they may modify the information stored by a cache. A SET request that incorrectly extends a response's expiration time may cause users to receive a stale page for a long time. Therefore, trust is very important for SET messages. An HTCP server is free to ignore any SET request, for any reason whatsoever. Although not required, an HTCP implementation really should ignore any SET request that does not have a valid AUTH section.

D.3.4.1 SET request

The OP-DATA for a SET request is an IDENTITY structure, which is simply a SPECIFIER and a DETAIL. The SPECIFIER holds information such as the request method, URI, and request headers. The DETAIL contains the updated reply headers.

If the F1 flag is not set, the receiver must not send back a response.

SET requests should be generated due to HTTP transactions only. Caches should not pass SET requests on to their own neighbors due to the strong possibility of flooding a hierarchy with HTCP messages.

D.3.4.2 SET response

A SET response is very simple since it does not include any OP-DATA. Only the RESPONSE code is significant. Table D-6 lists the defined SET response codes.

Table D-6. HTCP SET Response Codes

Code	Description
	IDENTITY was accepted.
1	IDENTITY was ignored; no reason given.

D.3.5 CLR

The CLR (clear) opcode is used to suggest that a neighbor remove an object from its cache storage. This feature may be useful if one cache determines that an object has been updated or removed at the origin server.

As with SET, the CLR opcode is dangerous because it modifies the cache storage. In the worst case, a malicious person could delete most or all of the objects stored in a cache. An HTCP agent may choose to ignore any CLR request for any reason. CLR requests without valid AUTH sections should definitely be ignored.

D.3.5.1 CLR request

A CLR request has the OP-DATA structure shown in Figure D-9. REASON is a 4-bit numeric code that explains why the sender wants the object (specified by the SPECIFIER) to be removed. The allowed reason codes are shown in Table D-7.

Table D-7. HTCP CLR Reasons

Code	Description
	Some reason not better specified by another code.
1	The origin server says the object no longer exists.

Figure D-9. HTCP CLR OP-DATA format

D.3.5.2 CLR response

The CLR response also does not include an OP-DATA section. Only the RESPONSE code is important. Table D-8 describes the defined values and their meanings.

Table D-8. HTCP CLR Response Codes

Code	Description
	I had the object, and I just deleted it.
1	I have the object, and I'm not deleting it.
2	I don't have the object.

only for RuBoard - do not distribute or recompile