unpoly-rails 0.62.0 → 2.0.0.pre.rc5

data/lib/assets/javascripts/unpoly/protocol.coffee

@@ -1,298 +0,0 @@
-###**
-Server protocol
-===============
-
-You rarely need to change server-side code
-in order to use Unpoly. There is no need to provide a JSON API, or add
-extra routes for AJAX requests. The server simply renders a series
-of full HTML pages, just like it would without Unpoly.
-
-That said, there is an **optional** protocol your server can use to
-exchange additional information when Unpoly is [updating fragments](/up.link).
-
-While the protocol can help you optimize performance and handle some
-edge cases, implementing it is **entirely optional**. For instance,
-`unpoly.com` itself is a static site that uses Unpoly on the frontend
-and doesn't even have a server component.
-
-## Existing implementations
-
-You should be able to implement the protocol in a very short time.
-There are existing implementations for various web frameworks:
-
-- [Ruby on Rails](/install/rails)
-- [Roda](https://github.com/adam12/roda-unpoly)
-- [Rack](https://github.com/adam12/rack-unpoly) (Sinatra, Padrino, Hanami, Cuba, ...)
-- [Phoenix](https://elixirforum.com/t/unpoly-a-framework-like-turbolinks/3614/15) (Elixir)
-
-
-## Protocol details
-
-\#\#\# Redirect detection for IE11
-
-On Internet Explorer 11, Unpoly cannot detect the final URL after a redirect.
-You can fix this edge case by delivering an additional HTTP header
-with the *last* response in a series of redirects:
-
-```http
-X-Up-Location: /current-url
-```
-
-The **simplest implementation** is to set these headers for every request.
-
-
-\#\#\# Optimizing responses
-
-When [updating a fragment](/up.link), Unpoly will send an
-additional HTTP header containing the CSS selector that is being replaced:
-
-```http
-X-Up-Target: .user-list
-```
-
-Server-side code is free to **optimize its response** by only returning HTML
-that matches the selector. For example, you might prefer to not render an
-expensive sidebar if the sidebar is not targeted.
-
-Unpoly will often update a different selector in case the request fails.
-This selector is also included as a HTTP header:
-
-```
-X-Up-Fail-Target: body
-```
-
-
-\#\#\# Pushing a document title to the client
-
-When [updating a fragment](/up.link), Unpoly will by default
-extract the `<title>` from the server response and update the document title accordingly.
-
-The server can also force Unpoly to set a document title by passing a HTTP header:
-
-```http
-X-Up-Title: My server-pushed title
-```
-
-This is useful when you [optimize your response](#optimizing-responses) and not render
-the application layout unless it is targeted. Since your optimized response
-no longer includes a `<title>`, you can instead use the HTTP header to pass the document title.
-
-
-\#\#\# Signaling failed form submissions
-
-When [submitting a form via AJAX](/form-up-target)
-Unpoly needs to know whether the form submission has failed (to update the form with
-validation errors) or succeeded (to update the `up-target` selector).
-
-For Unpoly to be able to detect a failed form submission, the response must be
-return a non-200 HTTP status code. We recommend to use either
-400 (bad request) or 422 (unprocessable entity).
-
-To do so in [Ruby on Rails](http://rubyonrails.org/), pass a [`:status` option to `render`](http://guides.rubyonrails.org/layouts_and_rendering.html#the-status-option):
-
-    class UsersController < ApplicationController
-
-      def create
-        user_params = params[:user].permit(:email, :password)
-        @user = User.new(user_params)
-        if @user.save?
-          sign_in @user
-        else
-          render 'form', status: :bad_request
-        end
-      end
-
-    end
-
-
-\#\#\# Detecting live form validations
-
-When [validating a form](/input-up-validate), Unpoly will
-send an additional HTTP header containing a CSS selector for the form that is
-being updated:
-
-```http
-X-Up-Validate: .user-form
-```
-
-When detecting a validation request, the server is expected to **validate (but not save)**
-the form submission and render a new copy of the form with validation errors.
-
-Below you will an example for a writing route that is aware of Unpoly's live form
-validations. The code is for [Ruby on Rails](http://rubyonrails.org/),
-but you can adapt it for other languages:
-
-    class UsersController < ApplicationController
-
-      def create
-        user_params = params[:user].permit(:email, :password)
-        @user = User.new(user_params)
-        if request.headers['X-Up-Validate']
-          @user.valid?  # run validations, but don't save to the database
-          render 'form' # render form with error messages
-        elsif @user.save?
-          sign_in @user
-        else
-          render 'form', status: :bad_request
-        end
-      end
-
-    end
-
-
-\#\#\# Signaling the initial request method
-
-If the initial page was loaded  with a non-`GET` HTTP method, Unpoly prefers to make a full
-page load when you try to update a fragment. Once the next page was loaded with a `GET` method,
-Unpoly will restore its standard behavior.
-
-This fixes two edge cases you might or might not care about:
-
-1. Unpoly replaces the initial page state so it can later restore it when the user
-   goes back to that initial URL. However, if the initial request was a POST,
-   Unpoly will wrongly assume that it can restore the state by reloading with GET.
-2. Some browsers have a bug where the initial request method is used for all
-   subsequently pushed states. That means if the user reloads the page on a later
-   GET state, the browser will wrongly attempt a POST request.
-   This issue affects Safari 9-12 (last tested in 2019-03).
-   Modern Firefoxes, Chromes and IE10+ don't have this behavior.
-
-In order to allow Unpoly to detect the HTTP method of the initial page load,
-the server must set a cookie:
-
-```http
-Set-Cookie: _up_method=POST
-```
-
-When Unpoly boots, it will look for this cookie and configure its behavior accordingly.
-The cookie is then deleted in order to not affect following requests.
-
-The **simplest implementation** is to set this cookie for every request that is neither
-`GET` nor contains an [`X-Up-Target` header](/#optimizing-responses). For all other requests
-an existing cookie should be deleted.
-
-
-@module up.protocol
-###
-up.protocol = do ->
-
-  u = up.util
-  e = up.element
-
-  ###**
-  @function up.protocol.locationFromXhr
-  @internal
-  ###
-  locationFromXhr = (xhr) ->
-    xhr.getResponseHeader(config.locationHeader) || xhr.responseURL
-
-  ###**
-  @function up.protocol.titleFromXhr
-  @internal
-  ###
-  titleFromXhr = (xhr) ->
-    xhr.getResponseHeader(config.titleHeader)
-
-  ###**
-  @function up.protocol.methodFromXhr
-  @internal
-  ###
-  methodFromXhr = (xhr) ->
-    if method = xhr.getResponseHeader(config.methodHeader)
-      u.normalizeMethod(method)
-
-  ###**
-  Server-side companion libraries like unpoly-rails set this cookie so we
-  have a way to detect the request method of the initial page load.
-  There is no JavaScript API for this.
-
-  @function up.protocol.initialRequestMethod
-  @internal
-  ###
-  initialRequestMethod = u.memoize ->
-    methodFromServer = up.browser.popCookie(config.methodCookie)
-    (methodFromServer || 'get').toLowerCase()
-
-  # Remove the method cookie as soon as possible.
-  # Don't wait until the first call to initialRequestMethod(),
-  # which might be much later.
-  up.on('up:framework:booted', initialRequestMethod)
-
-  ###**
-  Configures strings used in the optional [server protocol](/up.protocol).
-
-  @property up.protocol.config
-  @param {String} [config.targetHeader='X-Up-Target']
-  @param {String} [config.failTargetHeader='X-Up-Fail-Target']
-  @param {String} [config.locationHeader='X-Up-Location']
-  @param {String} [config.titleHeader='X-Up-Title']
-  @param {String} [config.validateHeader='X-Up-Validate']
-  @param {String} [config.methodHeader='X-Up-Method']
-  @param {String} [config.methodCookie='_up_method']
-    The name of the optional cookie the server can send to
-    [signal the initial request method](/up.protocol#signaling-the-initial-request-method).
-  @param {String} [config.methodParam='_method']
-    The name of the POST parameter when [wrapping HTTP methods](/up.proxy.config#config.wrapMethods)
-    in a `POST` request.
-  @param {String} [config.csrfHeader='X-CSRF-Token']
-    The name of the HTTP header that will include the
-    [CSRF token](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Synchronizer_token_pattern)
-    for AJAX requests.
-  @param {string|Function(): string} [config.csrfParam]
-    The `name` of the hidden `<input>` used for sending a
-    [CSRF token](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Synchronizer_token_pattern) when
-    submitting a default, non-AJAX form. For AJAX request the token is sent as an HTTP header instead.
-
-    The parameter name can be configured as a string or as function that returns the parameter name.
-    If no name is set, no token will be sent.
-
-    Defaults to the `content` attribute of a `<meta>` tag named `csrf-param`:
-
-        <meta name="csrf-param" content="authenticity_token" />
-
-  @param {string|Function(): string} [config.csrfToken]
-    The [CSRF token](https://en.wikipedia.org/wiki/Cross-site_request_forgery#Synchronizer_token_pattern)
-    to send for unsafe requests. The token will be sent as either a HTTP header (for AJAX requests)
-    or hidden form `<input>` (for default, non-AJAX form submissions).
-
-    The token can either be configured as a string or as function that returns the token.
-    If no token is set, no token will be sent.
-
-    Defaults to the `content` attribute of a `<meta>` tag named `csrf-token`:
-
-        <meta name='csrf-token' content='secret12345'>
-
-  @experimental
-  ###
-  config = new up.Config
-    targetHeader: 'X-Up-Target'
-    failTargetHeader: 'X-Up-Fail-Target'
-    locationHeader: 'X-Up-Location'
-    validateHeader: 'X-Up-Validate'
-    titleHeader: 'X-Up-Title'
-    methodHeader: 'X-Up-Method'
-    methodCookie: '_up_method'
-    methodParam: '_method'
-    csrfParam: -> e.metaContent('csrf-param')
-    csrfToken: -> e.metaContent('csrf-token')
-    csrfHeader: 'X-CSRF-Token'
-
-  csrfParam = ->
-    u.evalOption(config.csrfParam)
-
-  csrfToken = ->
-    u.evalOption(config.csrfToken)
-
-  reset = ->
-    config.reset()
-
-  up.on 'up:framework:reset', reset
-
-  config: config
-  reset: reset
-  locationFromXhr: locationFromXhr
-  titleFromXhr: titleFromXhr
-  methodFromXhr: methodFromXhr
-  csrfParam :csrfParam
-  csrfToken: csrfToken
-  initialRequestMethod: initialRequestMethod

data/lib/assets/javascripts/unpoly/proxy.coffee

@@ -1,672 +0,0 @@
-###**
-AJAX acceleration
-=================
-
-Unpoly comes with a number of tricks to shorten the latency between browser and server.
-
-\#\#\# Server responses are cached by default
-
-Unpoly caches server responses for a few minutes,
-making requests to these URLs return instantly.
-All Unpoly functions and selectors go through this cache, unless
-you explicitly pass a `{ cache: false }` option or set an `up-cache="false"` attribute.
-
-The cache holds up to 70 responses for 5 minutes. You can configure the cache size and expiry using
-[`up.proxy.config`](/up.proxy.config), or clear the cache manually using [`up.proxy.clear()`](/up.proxy.clear).
-
-Also the entire cache is cleared with every non-`GET` request (like `POST` or `PUT`).
-
-If you need to make cache-aware requests from your [custom JavaScript](/up.syntax),
-use [`up.request()`](/up.request).
-
-\#\#\# Preloading links
-
-Unpoly also lets you speed up reaction times by [preloading
-links](/a-up-preload) when the user hovers over the click area (or puts the mouse/finger
-down). This way the response will already be cached when
-the user releases the mouse/finger.
-
-\#\#\# Spinners
-
-You can listen to the [`up:proxy:slow`](/up:proxy:slow) event to implement a spinner
-that appears during a long-running request.
-
-\#\#\# More acceleration
-
-Other Unpoly modules contain even more tricks to outsmart network latency:
-
-- [Instantaneous feedback for links that are currently loading](/a.up-active)
-- [Follow links on `mousedown` instead of `click`](/a-up-instant)
-
-@module up.proxy
-###
-up.proxy = do ->
-
-  u = up.util
-  e = up.element
-
-  waitingLink = undefined
-  preloadDelayTimer = undefined
-  slowDelayTimer = undefined
-  pendingCount = undefined
-  slowEventEmitted = undefined
-
-  queuedLoaders = []
-
-  ###**
-  @property up.proxy.config
-  @param {number} [config.preloadDelay=75]
-    The number of milliseconds to wait before [`[up-preload]`](/a-up-preload)
-    starts preloading.
-  @param {number} [config.cacheSize=70]
-    The maximum number of responses to cache.
-    If the size is exceeded, the oldest items will be dropped from the cache.
-  @param {number} [config.cacheExpiry=300000]
-    The number of milliseconds until a cache entry expires.
-    Defaults to 5 minutes.
-  @param {number} [config.slowDelay=300]
-    How long the proxy waits until emitting the [`up:proxy:slow` event](/up:proxy:slow).
-    Use this to prevent flickering of spinners.
-  @param {number} [config.maxRequests=4]
-    The maximum number of concurrent requests to allow before additional
-    requests are queued. This currently ignores preloading requests.
-
-    You might find it useful to set this to `1` in full-stack integration
-    tests (e.g. Selenium).
-
-    Note that your browser might [impose its own request limit](http://www.browserscope.org/?category=network)
-    regardless of what you configure here.
-  @param {Array<string>} [config.wrapMethods]
-    An array of uppercase HTTP method names. AJAX requests with one of these methods
-    will be converted into a `POST` request and carry their original method as a `_method`
-    parameter. This is to [prevent unexpected redirect behavior](https://makandracards.com/makandra/38347).
-  @param {Array<string>} [config.safeMethods]
-    An array of uppercase HTTP method names that are considered [safe](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1).
-    The proxy cache will only cache safe requests and will clear the entire
-    cache after an unsafe request.
-  @stable
-  ###
-  config = new up.Config
-    slowDelay: 300
-    preloadDelay: 75
-    cacheSize: 70
-    cacheExpiry: 1000 * 60 * 5
-    maxRequests: 4
-    wrapMethods: ['PATCH', 'PUT', 'DELETE']
-    safeMethods: ['GET', 'OPTIONS', 'HEAD']
-
-  cache = new up.Cache
-    size: -> config.cacheSize
-    expiry: -> config.cacheExpiry
-    key: (request) -> up.Request.wrap(request).cacheKey()
-    cachable: (request) -> up.Request.wrap(request).isCachable()
-    # logPrefix: 'up.proxy'
-
-  ###**
-  Returns a cached response for the given request.
-
-  Returns `undefined` if the given request is not currently cached.
-
-  @function up.proxy.get
-  @return {Promise<up.Response>}
-    A promise for the response.
-  @experimental
-  ###
-  get = (request) ->
-    request = up.Request.wrap(request)
-    candidates = [request]
-
-    if request.target != 'html'
-      # Since <html> is the root tag, a request for the `html` selector
-      # will contain all other selectors.
-      requestForHtml = request.variant(target: 'html')
-      candidates.push(requestForHtml)
-
-      # Although <body> is not the root tag, we consider it the selector developers
-      # will use when they want to replace the entire page. Hence we consider it
-      # a suitable match for all other selectors, including `html`.
-      if request.target != 'body'
-        requestForBody = request.variant(target: 'body')
-        candidates.push(requestForBody)
-
-    for candidate in candidates
-      if response = cache.get(candidate)
-        return response
-
-  cancelPreloadDelay = ->
-    clearTimeout(preloadDelayTimer)
-    preloadDelayTimer = null
-
-  cancelSlowDelay = ->
-    clearTimeout(slowDelayTimer)
-    slowDelayTimer = null
-
-  reset = ->
-    waitingLink = null
-    cancelPreloadDelay()
-    cancelSlowDelay()
-    pendingCount = 0
-    config.reset()
-    cache.clear()
-    slowEventEmitted = false
-    queuedLoaders = []
-
-  reset()
-
-  ###**
-  Makes an AJAX request to the given URL.
-
-  \#\#\# Example
-
-      up.request('/search', { params: { query: 'sunshine' } }).then(function(response) {
-        console.log('The response text is %o', response.text)
-      }).catch(function() {
-        console.error('The request failed')
-      })
-
-  \#\#\# Caching
-
-  All responses are cached by default. If requesting a URL with a non-`GET` method, the response will
-  not be cached and the entire cache will be cleared.
-
-  You can configure caching with the [`up.proxy.config`](/up.proxy.config) property.
-
-  \#\#\# Events
-
-  If a network connection is attempted, the proxy will emit
-  a [`up:proxy:load`](/up:proxy:load) event with the `request` as its argument.
-  Once the response is received, a [`up:proxy:loaded`](/up:proxy:loaded) event will
-  be emitted.
-  
-  @function up.request
-  @param {string} [url]
-    The URL for the request.
-
-    Instead of passing the URL as a string argument, you can also pass it as an `{ url }` option.
-  @param {string} [options.url]
-    You can omit the first string argument and pass the URL as
-    a `request` property instead.
-  @param {string} [options.method='GET']
-    The HTTP method for the options.
-  @param {boolean} [options.cache]
-    Whether to use a cached response for [safe](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1)
-    requests, if available. If set to `false` a network connection will always be attempted.
-  @param {Object} [options.headers={}]
-    An object of additional HTTP headers.
-  @param {Object|FormData|string|Array} [options.params={}]
-    [Parameters](/up.Params) that should be sent as the request's payload.
-  @param {string} [options.timeout]
-    A timeout in milliseconds.
-
-    If [`up.proxy.config.maxRequests`](/up.proxy.config#config.maxRequests) is set, the timeout
-    will not include the time spent waiting in the queue.
-  @param {string} [options.target='body']
-    The CSS selector that will be sent as an [`X-Up-Target` header](/up.protocol#optimizing-responses).
-  @param {string} [options.failTarget='body']
-    The CSS selector that will be sent as an [`X-Up-Fail-Target` header](/up.protocol#optimizing-responses).
-  @return {Promise<up.Response>}
-    A promise for the response.
-  @stable
-  ###
-  makeRequest = (args...) ->
-    if u.isString(args[0])
-      url = args.shift()
-
-    # We cannot use u.extractOptions() since sometimes the last argument
-    # is an up.Request instead of a basic object.
-    requestOrOptions = args.shift() || {}
-
-    if url
-      requestOrOptions.url = url
-
-    request = up.Request.wrap(requestOrOptions)
-
-    # Non-GET requests always touch the network
-    # unless `request.cache` is explicitly set to `true`.
-    # These requests are never cached.
-    if !request.isSafe()
-      # We clear the entire cache before an unsafe request, since we
-      # assume the user is writing a change.
-      clear()
-
-    ignoreCache = (request.cache == false)
-
-    # If we have an existing promise matching this new request,
-    # we use it unless `request.cache` is explicitly set to `false`.
-    if !ignoreCache && (promise = get(request))
-      up.puts 'Re-using cached response for %s %s', request.method, request.url
-    else
-      # If no existing promise is available, we make a network request.
-      promise = loadOrQueue(request)
-      set(request, promise)
-      # Uncache failed requests
-      promise.catch ->
-        remove(request)
-
-    if !request.preload
-      # This might actually make `pendingCount` higher than the actual
-      # number of outstanding requests. However, we need to cover the
-      # following case:
-      #
-      # - User starts preloading a request.
-      #   This triggers *no* `up:proxy:slow`.
-      # - User starts loading the request (without preloading).
-      #   This triggers `up:proxy:slow`.
-      # - The request finishes.
-      #   This triggers `up:proxy:recover`.
-      loadStarted()
-      u.always promise, loadEnded
-
-    promise
-
-  ###**
-  Makes an AJAX request to the given URL and caches the response.
-
-  The function returns a promise that fulfills with the response text.
-
-  \#\#\# Example
-
-      up.request('/search', { params: { query: 'sunshine' } }).then(function(text) {
-        console.log('The response text is %o', text)
-      }).catch(function() {
-        console.error('The request failed')
-      })
-
-  @function up.ajax
-  @param {string} [url]
-    The URL for the request.
-
-    Instead of passing the URL as a string argument, you can also pass it as an `{ url }` option.
-  @param {string} [request.url]
-    You can omit the first string argument and pass the URL as
-    a `request` property instead.
-  @param {string} [request.method='GET']
-    The HTTP method for the request.
-  @param {boolean} [request.cache]
-    Whether to use a cached response for [safe](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1)
-    requests, if available. If set to `false` a network connection will always be attempted.
-  @param {Object} [request.headers={}]
-    An object of additional header key/value pairs to send along
-    with the request.
-  @param {Object|FormData|string|Array} [options.params]
-    [Parameters](/up.Params) that should be sent as the request's payload.
-
-    On IE 11 and Edge, `FormData` payloads require a [polyfill for `FormData#entries()`](https://github.com/jimmywarting/FormData).
-  @param {string} [request.timeout]
-    A timeout in milliseconds for the request.
-
-    If [`up.proxy.config.maxRequests`](/up.proxy.config#config.maxRequests) is set, the timeout
-    will not include the time spent waiting in the queue.
-  @return {Promise<string>}
-    A promise for the response text.
-  @deprecated
-    Use [`up.request()`](/up.request) instead.
-  ###
-  ajax = (args...) ->
-    up.legacy.warn('up.ajax() has been deprecated. Use up.request() instead.')
-    new Promise (resolve, reject) ->
-      pickResponseText = (response) -> resolve(response.text)
-      makeRequest(args...).then(pickResponseText, reject)
-
-  ###**
-  Returns `true` if the proxy is not currently waiting
-  for a request to finish. Returns `false` otherwise.
-
-  @function up.proxy.isIdle
-  @return {boolean}
-    Whether the proxy is idle
-  @experimental
-  ###
-  isIdle = ->
-    pendingCount == 0
-
-  ###**
-  Returns `true` if the proxy is currently waiting
-  for a request to finish. Returns `false` otherwise.
-
-  @function up.proxy.isBusy
-  @return {boolean}
-    Whether the proxy is busy
-  @experimental
-  ###
-  isBusy = ->
-    pendingCount > 0
-
-  loadStarted = ->
-    pendingCount += 1
-    unless slowDelayTimer
-      # Since the emission of up:proxy:slow might be delayed by config.slowDelay,
-      # we wrap the mission in a function for scheduling below.
-      emission = ->
-        if isBusy() # a fast response might have beaten the delay
-          up.emit('up:proxy:slow', log: 'Proxy is slow to respond')
-          slowEventEmitted = true
-      slowDelayTimer = u.timer(config.slowDelay, emission)
-
-
-  ###**
-  This event is [emitted](/up.emit) when [AJAX requests](/up.request)
-  are taking long to finish.
-
-  By default Unpoly will wait 300 ms for an AJAX request to finish
-  before emitting `up:proxy:slow`. You can configure this time like this:
-
-      up.proxy.config.slowDelay = 150;
-
-  Once all responses have been received, an [`up:proxy:recover`](/up:proxy:recover)
-  will be emitted.
-
-  Note that if additional requests are made while Unpoly is already busy
-  waiting, **no** additional `up:proxy:slow` events will be triggered.
-
-
-  \#\#\# Spinners
-
-  You can [listen](/up.on) to the `up:proxy:slow`
-  and [`up:proxy:recover`](/up:proxy:recover) events to implement a spinner
-  that appears during a long-running request,
-  and disappears once the response has been received:
-
-      <div class="spinner">Please wait!</div>
-
-  Here is the JavaScript to make it alive:
-
-      up.compiler('.spinner', function(element) {
-        show = () => { up.element.show(element) }
-        hide = () => { up.element.hide(element) }
-
-        hide()
-
-        return [
-          up.on('up:proxy:slow', show),
-          up.on('up:proxy:recover', hide)
-        ]
-      })
-
-  The `up:proxy:slow` event will be emitted after a delay of 300 ms
-  to prevent the spinner from flickering on and off.
-  You can change (or remove) this delay by [configuring `up.proxy`](/up.proxy.config) like this:
-
-      up.proxy.config.slowDelay = 150;
-
-
-  @event up:proxy:slow
-  @stable
-  ###
-
-  loadEnded = ->
-    pendingCount -= 1
-
-    if isIdle()
-      cancelSlowDelay()
-      if slowEventEmitted
-        up.emit('up:proxy:recover', log: 'Proxy has recovered from slow response')
-        slowEventEmitted = false
-
-  ###**
-  This event is [emitted](/up.emit) when [AJAX requests](/up.request)
-  have [taken long to finish](/up:proxy:slow), but have finished now.
-
-  See [`up:proxy:slow`](/up:proxy:slow) for more documentation on
-  how to use this event for implementing a spinner that shows during
-  long-running requests.
-
-  @event up:proxy:recover
-  @stable
-  ###
-  loadOrQueue = (request) ->
-    if pendingCount < config.maxRequests
-      load(request)
-    else
-      queue(request)
-
-  queue = (request) ->
-    up.puts('Queuing request for %s %s', request.method, request.url)
-    loader = -> load(request)
-    loader = u.previewable(loader)
-    queuedLoaders.push(loader)
-    loader.promise
-
-  load = (request) ->
-    eventProps =
-      request: request
-      log: ['Loading %s %s', request.method, request.url]
-
-    if up.event.nobodyPrevents('up:proxy:load', eventProps)
-      responsePromise = request.send()
-      u.always responsePromise, responseReceived
-      u.always responsePromise, pokeQueue
-      responsePromise
-    else
-      u.microtask(pokeQueue)
-      Promise.reject(new Error('Event up:proxy:load was prevented'))
-
-  ###**
-  This event is [emitted](/up.emit) before an [AJAX request](/up.request)
-  is sent over the network.
-
-  @event up:proxy:load
-  @param {up.Request} event.request
-  @param event.preventDefault()
-    Event listeners may call this method to prevent the request from being sent.
-  @experimental
-  ###
-
-  registerAliasForRedirect = (response) ->
-    request = response.request
-    if response.url && request.url != response.url
-      newRequest = request.variant(
-        method: response.method
-        url: response.url
-      )
-      up.proxy.alias(request, newRequest)
-
-  responseReceived = (response) ->
-    if response.isFatalError()
-      up.emit 'up:proxy:fatal',
-        log: 'Fatal error during request'
-        request: response.request
-        response: response
-    else
-      registerAliasForRedirect(response) unless response.isError()
-      up.emit 'up:proxy:loaded',
-        log: ['Server responded with HTTP %d (%d bytes)', response.status, response.text.length]
-        request: response.request
-        response: response
-
-  ###**
-  This event is [emitted](/up.emit) when the response to an
-  [AJAX request](/up.request) has been received.
-
-  Note that this event will also be emitted when the server signals an
-  error with an HTTP status like `500`. Only if the request
-  encounters a fatal error (like a loss of network connectivity),
-  [`up:proxy:fatal`](/up:proxy:fatal) is emitted instead.
-
-  @event up:proxy:loaded
-  @param {up.Request} event.request
-  @param {up.Response} event.response
-  @experimental
-  ###
-
-  ###**
-  This event is [emitted](/up.emit) when an [AJAX request](/up.request)
-  encounters fatal error like a timeout or loss of network connectivity.
-
-  Note that this event will *not* be emitted when the server produces an
-  error message with an HTTP status like `500`. When the server can produce
-  any response, [`up:proxy:loaded`](/up:proxy:loaded) is emitted instead.
-
-  @event up:proxy:fatal
-  ###
-
-  pokeQueue = ->
-    queuedLoaders.shift()?()
-    # Don't return the promise from the loader above
-    return undefined
-
-  ###**
-  Makes the proxy assume that `newRequest` has the same response as the
-  already cached `oldRequest`.
-
-  Unpoly uses this internally when the user redirects from `/old` to `/new`.
-  In that case, both `/old` and `/new` will cache the same response from `/new`.
-
-  @function up.proxy.alias
-  @param {Object} oldRequest
-  @param {Object} newRequest
-  @experimental
-  ###
-  alias = cache.alias
-
-  ###**
-  Manually stores a promise for the response to the given request.
-
-  @function up.proxy.set
-  @param {string} request.url
-  @param {string} [request.method='GET']
-  @param {string} [request.target='body']
-  @param {Promise<up.Response>} response
-    A promise for the response.
-  @experimental
-  ###
-  set = cache.set
-
-  ###**
-  Manually removes the given request from the cache.
-
-  You can also [configure](/up.proxy.config) when the proxy
-  automatically removes cache entries.
-
-  @function up.proxy.remove
-  @param {string} request.url
-  @param {string} [request.method='GET']
-  @param {string} [request.target='body']
-  @experimental
-  ###
-  remove = cache.remove
-
-  ###**
-  Removes all cache entries.
-
-  Unpoly also automatically clears the cache whenever it processes
-  a request with an [unsafe](https://www.w3.org/Protocols/rfc2616/rfc2616-sec9.html#sec9.1.1)
-  HTTP method like `POST`.
-
-  @function up.proxy.clear
-  @stable
-  ###
-  clear = cache.clear
-
-  # up.legacy.renamedEvent('up:proxy:received', 'up:proxy:loaded')
-
-  preloadAfterDelay = (link) ->
-    delay = e.numberAttr(link, 'up-delay') || config.preloadDelay
-    unless link == waitingLink
-      waitingLink = link
-      cancelPreloadDelay()
-      curriedPreload = ->
-        u.muteRejection preload(link)
-        waitingLink = null
-      startPreloadDelay(curriedPreload, delay)
-
-  startPreloadDelay = (block, delay) ->
-    preloadDelayTimer = setTimeout(block, delay)
-
-  stopPreload = (link) ->
-    if link == waitingLink
-      waitingLink = undefined
-      cancelPreloadDelay()
-
-  ###**
-  Preloads the given link.
-
-  When the link is clicked later, the response will already be cached,
-  making the interaction feel instant.
-
-  @function up.proxy.preload
-  @param {string|Element|jQuery} linkOrSelector
-    The element whose destination should be preloaded.
-  @param {Object} options
-    Options that will be passed to the function making the HTTP requests.
-  @return
-    A promise that will be fulfilled when the request was loaded and cached
-  @experimental
-  ###
-  preload = (linkOrSelector, options) ->
-    link = e.get(linkOrSelector)
-
-    if up.link.isSafe(link)
-      preloadEventAttrs = { log: ['Preloading link %o', link], target: link }
-      up.event.whenEmitted('up:link:preload', preloadEventAttrs).then ->
-        variant = up.link.followVariantForLink(link)
-        variant.preloadLink(link, options)
-    else
-      Promise.reject(new Error("Won't preload unsafe link"))
-
-  ###**
-  This event is [emitted](/up.emit) before a link is [preloaded](/up.preload).
-
-  @event up:link:preload
-  @param {Element} event.target
-    The link element that will be preloaded.
-  @param event.preventDefault()
-    Event listeners may call this method to prevent the link from being preloaded.
-  @stable
-  ###
-
-  ###**
-  @internal
-  ###
-  isSafeMethod = (method) ->
-    u.contains(config.safeMethods, method)
-
-  ###**
-  @internal
-  ###
-  wrapMethod = (method, params) ->
-    if u.contains(config.wrapMethods, method)
-      params.add(up.protocol.config.methodParam, method)
-      method = 'POST'
-    method
-
-  ###**
-  Links with an `up-preload` attribute will silently fetch their target
-  when the user hovers over the click area, or when the user puts her
-  mouse/finger down (before releasing).
-
-  When the link is clicked later, the response will already be cached,
-  making the interaction feel instant.   
-
-  @selector a[up-preload]
-  @param [up-delay=75]
-    The number of milliseconds to wait between hovering
-    and preloading. Increasing this will lower the load in your server,
-    but will also make the interaction feel less instant.
-  @stable
-  ###
-  up.compiler 'a[up-preload], [up-href][up-preload]', (link) ->
-    if up.link.isSafe(link)
-      link.addEventListener 'mouseenter', (event) ->
-        if up.link.shouldProcessEvent(event, link)
-          preloadAfterDelay(link)
-      link.addEventListener 'mouseleave', ->
-        stopPreload(link)
-
-  up.on 'up:framework:reset', reset
-
-  preload: preload
-  ajax: ajax
-  request: makeRequest
-  get: get
-  alias: alias
-  clear: clear
-  remove: remove
-  isIdle: isIdle
-  isBusy: isBusy
-  isSafeMethod: isSafeMethod
-  wrapMethod: wrapMethod
-  config: config
-
-up.ajax = up.proxy.ajax
-up.request = up.proxy.request