Feedback on INHIBIT and RESTORE, please?

[Eric J Bowman <[e-mail]>]

INHIBIT and RESTORE Methods for HTTP 



Abstract



Temporarily changing the availability status of a resource, is a common procedure in webserver administration. It is typically accomplished by editing a configuration file, or overloading the POST method by using it to affect changes which fall outside the scope of altering the content of, or creating, a resource. HTTP additionally attaches creation and destruction semantics to PUT and DELETE. This proposal suggests two new HTTP methods, INHIBIT and RESTORE, as a mechanism for clarifying server behavior for intermediaries, and in log files.



Introduction



This proposal defines two extension methods for HTTP server administration, to change the status of a resource to "temporarily unavailable" (INHIBIT); and revert the change in availability status at a later time (RESTORE). Its use is not limited to toggling the 503 response status.



Extension methods are desirable for the temporary off-lining of a resource in a cache-transparent fashion. Replacing a cacheable 200 OK response with a non-cacheable 503 response by editing a configuration file or using a POST request (webhosting control-panel apps) does not address the use-case of immediately suspending access to content involved in a legal dispute, e.g. copyright; or if the temporary status will be 402 Payment Required, etc.



The INHIBIT method indicates that any caches it passes through, MUST mark all variant representations stale; as does the RESTORE method, in cases where the temporary status response is cacheable and the request did not include a Defer-Request header, defined below, which a cache MAY utilize to inform its behavior.



The INHIBIT Method



The availability status of a resource may need to be changed from its regular behavior, for a limited period of time (which may be indefinite). The inhibited behavior could be a paywall for a journal or newspaper article, to make it free content in a collection which defaults to paid content, or vice-versa. An INHIBIT request MAY contain a message body containing the desired end-result status code, and/or the desired response message.



Any media type suitable to expressing a name-value pair may be used for the requested status, as will any media type suitable for expressing the requested message. To send both, a user-agent MUST use the Multipart/Related media type as follows:



Content-Type: Multipart/Related; boundary=message

--message

Content-Type: text/xml; charset=utf-8



<status>503</status>

--message

Content-Type: text/html; charset=utf-8



<p>Down for maintenance, try back later.</p>

--message--



The status code is always the first part, if sent. Subsequent parts may be added, e.g. one for each supported Content-Language. If accepted, the response to an INHIBIT request SHOULD reflect the desired status code and message content, but MAY choose to respond 204 Accepted, particularly in the case of multiple message parts.



The RESTORE Method



The RESTORE method may be invoked at any time to revert an inhibited resource to its prior availability status. If accepted, the origin server SHOULD respond with the normal-operations response status for the resource, e.g. 200 OK, but MAY issue a 204 Accepted response. A user-agent MAY add a defer-request header with a timestamp to inform the origin server when to execute the RESTORE request. A server MAY include this information in the response body of the temporary response status. A cache MAY utilize this information in determining whether or not to expire stale representations.



The Defer-Request Request Header



This header has potential applications which are beyond the scope of this proposal, for example having a server accept a PUT request but delay its application to the identified resource. It is up to the user-agent to convert intentions such as "wait three units of time" into an absolute timestamp.



"Defer-Request" ":" date-time



A cache MUST NOT take any action when processing any request containing a Defer-Request header. This suggests only using it in conjunction with methods where that's the default cache behavior anyway.



IANA Considerations



The Defer-Request header is identical to the Deferred-Delivery header defined in RFC 2156, with a different name to reflect a more general purpose than message delivery. Considering it general-purpose may be deemed to break stuff, but not in the context of the proposed RESTORE method. So maybe just re-use Deferred-Delivery?



I've been using these methods for so long I forgot where I cribbed 'em from. This is my first crack at writing an RFC, just documenting my custom and practice.



-Eric