- From: Josh Cohen <josh@mozilla.com>
- Date: Thu, 24 Jul 1997 21:31:37 -0700 (PDT)
- To: Josh Cohen <josh@netscape.com>
- Cc: http-wg%cuckoo.hpl.hp.com@hplb.hpl.hp.com
- Message-Id: <ML-3.3.869805097.7096.josh@birdcage>
I havent gotten a whole lot of feedback on this latest revision, (ie without the regexps), although what I have gotten looks good. For your viewing pleasure, here it is once more...:) I'd really like to see this in the spec, so if you have comments, please share them. thanks josh ----------------------------------------------------------------------------- Josh Cohen Netscape Communications Corp. Netscape Fire Department #include<disclaimer.h> Server Engineering josh@netscape.com http://people.netscape.com/josh/ -----------------------------------------------------------------------------
HTTP Working Group Josh Cohen
Internet-Draft Netscape Communications Corp.
Expires: Six Months 24 July 1997
HTTP/1.1 305 and 306 Response Codes
<draft-cohen-http305036-00.txt>
Status of this Memo
This document is an Internet-Draft. Internet-Drafts are working
documents of the Internet Engineering Task Force (IETF), its areas,
and its working groups. Note that other groups may also distribute
working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet- Drafts as reference
material or to cite them other than as ``work in progress.''
To learn the current status of any Internet-Draft, please check the
``1id-abstracts.txt'' listing contained in the Internet- Drafts
Shadow Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe),
munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or
ftp.isi.edu (US West Coast).
Abstract
The HTTP/1.1 RFC specifies a response code '305 Use Proxy' which is
intended to cause a client to retry the request using a specified
proxy server. This functionality is important, but underspecified in
the current spec. The spec does not specify for how long or which
URLs the redirect applies to, or how proxies can deal with or
generate similar responses. This draft proposes a specification for
both the 305 response and a new response, "306 Switch Proxy".
J. Cohen HTTP/1.1 305 and 306 Response Codes [Page 1]
INTERNET-DRAFT 24 July 1997
Summary
1.0 Response Codes
1.1 305 Use Proxy
1.2 306 Switch Proxy
1.3 506 Redirection Failed
2.0 Headers
2.1 Set-proxy:
2.2 Location:
3.0 Methods
3.1 OPTIONS
4.0 Operational Constraints
5.0 Notes
1.0 Response Codes
1.1 305 Use Proxy
The 305 is generated by an origin server to indicate that the client,
or proxy, should use a proxy to access the requested resource.
The request SHOULD be accompanied by a 'Set-proxy' response header
indicating what proxy is to be used. The client will parse the 'Set-
proxy' header as defined below to decide how long, for what URLs it
should use the specified proxy.
If the 305 response is not accompanied by a 'Set-proxy' header, it
MUST be accompanied by a 'Location' header. The 'Location' header
will specify a URL to the proxy.
If both headers are present in the response, the client SHOULD use
the 'Set-proxy' header only.
1.2 306 Switch Proxy
The 306 response is generated by a proxy server to indicate that the
client or proxy should use the information in the accompanying 'Set-
proxy' header to choose a proxy for subsequent requests.
The 306 response code MUST be accompanied by the 'Set-proxy' response
J. Cohen HTTP/1.1 305 and 306 Response Codes [Page 2]
INTERNET-DRAFT 24 July 1997
header. The client or proxy will parse the 'Set-proxy' header to
determine which proxy to use, how long to use it, and for which URLs
to use it.
The scope in the set-proxy header is considered an optional advisory.
The client or proxy may choose to ignore it, and use it for just this
request, for all requests, or for a scope previously or implicitly
defined by another configuration method or autoconfiguration system.
1.3 506 Redirection Failed
The 506 response is returned when a redirection fails or is refused
by a proxy or client. If the redirection response included a body,
then it SHOULD be included in the 506 response.
2.0 Headers
2.1 'Set-proxy' Response Header
The 'Set-proxy' header is defined as:
Set-proxy: "Set-proxy" ":" action [ ";" parameters ]
parameters = ( "scope" "=" scopePattern ) |
( proxyURI "=" URI ) |
lifetime
lifetime = ( "seconds" "=" integer )
| ( "hits" "=" integer )
action = ( "DIRECT"
| "IPL"
| "SET" )
scopePattern = "*" | "-" | URIpattern
URIpattern = character | "*"
character = Any character legal in the definition
of a URL/URI in the context of RFC2068
An example header:
Set-proxy: SET ; proxyURI = "http://proxy.me.com:8080/",
scope="http://", seconds=5
action
J. Cohen HTTP/1.1 305 and 306 Response Codes [Page 3]
INTERNET-DRAFT 24 July 1997
The first item, "action" specifies the type or mode of the change.
Possible modes are:
DIRECT
Attempt to connect directly, with no proxy
IPL
Initial Program Load, the client or proxy should attempt to revert
back to its default or initial proxy setting. This is meant to
instruct a client to re-fetch its proxy configuration, or PAC file.
When set, the accompanying scope field MUST be "*" A client receiv-
ing this response SHOULD prompt the user for confirmation.
If accompanied by a 'proxyURI' parameter, a proxy or client MAY use
the value as a URL containing a configuration to retrieve. If a
client does so, it MUST prompt the user for confirmation.
SET
Set to parameter "proxyURI". The client should use the URL speci-
fied for "proxyURI" as the proxy. If the SET mode is specified, the
parameter, "proxyURI", MUST be present.
Scope
Scope refers to an expression pattern that specifies which URIs are
subject to this header setting. URIs should be matched against the
scope with this rule :
The scope "*" means all requests
The scope "-" means this EXACT URL ONLY
Otherwise, the URL is compared with the scope in the following
manner.
The Scope is a prefix of matching URLs.
The character "*" is allowed in the dns name portion of a URL, or in
the path portion of the URL, but ONLY when used with a 306, not a
305.
It matches any sequence of characters except '/'.
This is intended to be a simple matching scheme to allow a prefix
match to take place.
J. Cohen HTTP/1.1 305 and 306 Response Codes [Page 4]
INTERNET-DRAFT 24 July 1997
See the examples section in "Operational Constraints"
The lifetime parameter specifies how long the specified proxy should
be used. If lifetime is specified as "seconds" then the proxy set-
ting remains in effect for 'integer' seconds. If lifetime is speci-
fied in 'hits' then the proxy setting remains in effect for
'integer' transactions.
2.2 Location Header
In the original HTTP/1.1 spec, the 'Location' header was used to
indicate the proxy setting. Its use is DEPRECATED by the 'Set-
proxy' header in the context of a 305 response. All new implementa-
tions MUST send the Set-proxy header. Implementations MAY send the
'Location' header so as to allow backward compatibility.
If the 'Location' header is specified, it should contain a URI of
the proxy. If the Set-proxy header is not specified, the client
should use this proxy for just one request, and only for the origi-
nally requested exact URL.
3.0 Methods
A client or proxy receiving a 305 or 306, should use the OPTIONS
method to determine if the server or proxy it is talking to actually
is an HTTP/1.1 server supporting 305 and 306 responses.
J. Cohen HTTP/1.1 305 and 306 Response Codes [Page 5]
INTERNET-DRAFT 24 July 1997
4.0 Operational Constraints
* Both the 305 and 306 response codes are HOP by HOP. A proxy server
MUST not forward a 305 or 306 respose code (unless it generated the
306).
* A webserver MUST NOT send a 306 response under any circumstances
* A proxy server MUST NOT generate a 305 response.
* A client or proxy SHOULD NOT accept a 306 from a proxy that it
learned of via a 305 response code.
* A client or proxy MAY maintain state and allow a lifetime to extend
beyond a session or restart.
* A 'Set-proxy: IPL' SHOULD override any previous 'Set-proxy' header.
* A 305 or 306 response MAY contain a body containing an explanation
of the redirect for clients which do not understand the redirect
* In the absence of any parameter, the following defaults should be
used:
lifetime = this transaction only
scope = this exact URL only
* When receiving a 305 response, the client or proxy will enforce the
following rule with respect to the scope.
The scope specified must be more restrictive than the transformed
URL in question based on the rightmost slash in the URI.
Example: (in order of restrictiveness)
for URI = http://www.ups.com/services/index.html
http://www.ups.com/services/ (allowed)
http://www.ups.com/services/express/ ( allowed )
http://www.ups.com/ (NOT allowed)
J. Cohen HTTP/1.1 305 and 306 Response Codes [Page 6]
INTERNET-DRAFT 24 July 1997
Using "*" in a 306 response set-proxy: header:
The scope may be set to:
http://*.foo.com/
which would apply to all URLs in to domain foo.com
If the scope returned with a 305 response is less restrictive than
the requested URL, the client may reject the redirection and return
506 Redirection Failed. If the client wished to honor the
redirect, it client MUST prompt the user for confirmation before
accepting the new proxy setting.
* Since HTTP/1.0 proxies may unknowingly forward a 305 or 306
response code that was generated maliciously or in good faith, the
client must attempt to ascertain if the proxy with which it is
directly communicating is HTTP/1.1 and if it supports the 'Set-
proxy' header. To determine this, the client or proxy should use
the OPTIONS method to make a request check for this feature. The
extension string should be HDR='set-proxy', or, should this be
defined in the Standard RFC for HTTP/1.1, then the string should be
RFC='rfcXXXX' in the OPTIONS request.
Security Considerations
Great care should be taken when implementing client side actions
based on the 305 or 306. Since older proxies may unknowingly for-
ward either of these reponses, clients should be prepared to check
the validity.
* Please read the section 'Operational Constraints'
* A client or proxy MUST NOT accept a 305 response from a proxy.
* A client or proxy MUST NOT accept a 306 response from an origin
server.
* When receiving a 306 response from a proxy, the client MUST verify
that the proxy supports the 306 response with an OPTIONS request.
5.0 Notes
J. Cohen HTTP/1.1 305 and 306 Response Codes [Page 7]
INTERNET-DRAFT 24 July 1997
Further specification is needed to define exactly how to use
OPTIONSs, or another mechanism to determin if set-proxy is sup-
ported.
Author's Address
Josh Cohen
Netscape Communications Corporation
501 E. Middlefield Rd
Mountain View, CA 94043
Phone (415) 937-4157
EMail: josh@netscape.com
J. Cohen HTTP/1.1 305 and 306 Response Codes [Page 8]
Received on Thursday, 24 July 1997 21:36:02 UTC