A user account is required in order to edit this wiki, but we've had to disable public user registrations due to spam.

To request an account, ask an autoconfirmed user on Chat (such as one of these permanent autoconfirmed members).


From WHATWG Wiki
Revision as of 17:44, 24 February 2013 by Annevk (talk | contribs)
Jump to navigation Jump to search

The contents of this page, Fetch, and all edits made to this page in its history, are hereby released under the CC0 Public Domain Dedication, as described in WHATWG Wiki:Copyrights.


Fetch is fetch.spec.whatwg.org and will define HTML fetch and CORS as a set of coherent algorithms rather than the intertwined mess we have now.


The basic model is Request -> Fetch -> Response.


  • Parsed URL (object)
  • method (probably with restrictions as seen in XHR)
  • UA headers
  • author headers (maybe rename because people get upset with "author", with implicit restrictions as seen in XHR / CORS)
  • entity body
  • origin (object)
  • referrer source (Document / URL)
  • manual redirect flag
  • omit credentials flag (will replace HTML fetch block cookies flag but also has other features)
  • force preflight flag (set for upload progress notifications (to not reveal existence of server in case of POST I suppose; see bug 20322))
  • synchronous flag
  • force same-origin flag (looks identical to No CORS, fail, filed bug 20951)
  • CORS mode
    • No CORS, taint (<link>, <script>, ...); still need to allow the server to opt in to CORS anyway to effectively make the resource CORS same-origin even if not requested as such (HTML does not have this feature
    • No CORS, fail (<track>)
    • Anonymous
    • Credentialed

Basic Fetch

See also URL. Fetch specifics depends on the URL scheme. Where possible fetching happens incrementally. If it completely fails you get a network error. Otherwise a response. A response might be exposed from the moment status/headers are available and the entity body is still loading.


See URL schemes.




Response object as per http://xhr.spec.whatwg.org/#data:-urls-and-http

If the data URL fails to parse however return a network error.


This is by and large platform-specific.


Construct the request per the FTP specification, do the request, and expose the response.

http and https

  • Construct the request per the HTTP specification
  • Do the request
  • Expose the response.

any other scheme

Network error.


Basic Fetch deals with a single request/response whereas Fetch tackles the more complicated setups required by http/https:

  • Redirects
    • We want to follow them if the status code is 301, 302, 303, 307, 308 and there's a Location header (and if there's more than one Location header we need to pick probably), unless a flag is set to not follow redirects).
    • We need to carefully consider what happens if the new Location is not same-origin and especially what if it's not http or https. That might depend on the API.
  • Authentication (challenge request, prompt the user for certain legacy APIs)
  • CORS (preflight requests, marking the response as same-origin or not)
  • Cookies
    • Include them in the request or not?
    • Deal with cookies in the response (before handling redirects and such) and the storage mutex.
  • 304 needs to be turned into a 200 for XMLHttpRequest unless explicitly requested otherwise. We should make it clearer how that works.

For everything else Fetch will simply defer to Basic Fetch, but Fetch will be the algorithm used by the whole platform.


Both intermediate updates (progress, headers received, ...) and final. Also indicates network error / CORS error (exposed as network error), ...

More importantly, it expresses everything in terms of HTTP, regardless of whether the request was for file/blob/data/etc. For this we need to expose:

  • Status code
  • Status text
  • Headers
  • Entity body

User agent advice

For http/https, maybe give advice on proxies, e.g.: "If the user agent allows the end user to configure a proxy it should modify the request appropriately; i.e., connect to the proxy host instead of the origin server, modify the Request-Line and send Proxy-Authorization headers as specified." Though ideally HTTP does this.

For http/https, advice to not include to much random headers, even though it'll happen to some extent anyway.

Python pseudo-code

 def taint(response):
   response.cors = "cross-origin"
   return response
 def fetch(request):
   url = request.url
   origin = request.origin
   if url.scheme in ("about", "blob", "data"):
     return basic_fetch(request)
   elif url.origin == origin:
     return same_origin_fetch(request)
   elif url.scheme == "file":
     return ImplementationSpecific()
   elif url.scheme == "ftp":
     return taint(basic_fetch(request))
   elif ...:
     return potential_cors_fetch(request)
     return cors_fetch_with_preflight(request)
 def basic_fetch(request):
   url = request.url
   if url.scheme == "about":
     if url.scheme_data == "blank":
       return Response({type:"text/html", encoding:"utf-8", body:""})
       return NetworkError()
   elif url.scheme == "blob":
   elif url.scheme == "data":
   elif url.scheme == "file":
   elif url.scheme == "ftp":
   elif url.scheme in ("http", "https"):
     ... count redirects
     return NetworkError()
 def same_origin_fetch (request):
   response = basic_fetch(request)
   response.wait_for_headers() // design something better
   if response.type == "redirect" and response.location.origin != request.url.origin:
     request.url = response.location
     return fetch(request)
   return response
 def potential_cors_fetch(request):
   response = basic_fetch(request)
   if response.type == "redirect":
     if request.url.origin != response.location.origin:
       request.origin = uuid()
     request.url = response.location
     if request.url.username or request.url.password or not cors_check(response):
       request.tainted = True   
     return potential_cors_fetch(request)
   // XXX should this succeed for about: / blob: data: (think redirects) 
   if not request.tainted and cors_check(response):
     response.cors = "same-origin"
   return response
 def cors_fetch_with_preflight(request):
 def cors_check(response):