Skip to content

Commit

Permalink
Monospace variable names in draft-variants.
Browse files Browse the repository at this point in the history
  • Loading branch information
@jyasskin
jyasskin committed Dec 14, 2018
1 parent 6a1bc67 commit 8908c24
Showing 1 changed file with 65 additions and 65 deletions.
130 changes: 65 additions & 65 deletions draft-ietf-httpbis-variants.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -222,15 +222,15 @@ When more than one Variant-Key value is in a response, the first one present MUS
This algorithm generates a list of normalised strings from Variant-Key, suitable for comparison with
values generated by {{cache}}.

Given stored-headers (a set of headers from a stored response), a normalised list of variant-keys for that message can be generated by following this algorithm:
Given `stored-headers` (a set of headers from a stored response), a normalised list of variant-keys for that message can be generated by following this algorithm:

1. Let variant-keys be an empty list.
2. Let variant-key-header be a string, the result of selecting all field-values of stored-headers whose field-name is "Variant-Key" and joining them with a comma (",").
3. Let value-list be the result of splitting variant-key-header on commas (",").
4. For each value in value-list:
1. Remove all whitespace from value.
2. Append value to variant-keys.
5. Return variant-keys.
1. Let `variant-keys` be an empty list.
2. Let `variant-key-header` be a string, the result of selecting all field-values of `stored-headers` whose field-name is "Variant-Key" and joining them with a comma (",").
3. Let `value-list` be the result of splitting `variant-key-header` on commas (",").
4. For each `value` in `value-list`:
1. Remove all whitespace from `value`.
2. Append `value` to `variant-keys`.
5. Return `variant-keys`.


# Cache Behaviour {#cache}
Expand All @@ -239,23 +239,23 @@ Caches that implement the Variants header field and the relevant semantics of th

They do so by running this algorithm (or its functional equivalent) upon receiving a request:

Given incoming-request (a mapping of field-names to lists of field values), and stored-responses (a list of stored responses suitable for reuse as defined in Section 4 of {{!RFC7234}}, excepting the requirement to calculate a secondary cache key):
Given `incoming-request` (a mapping of field-names to lists of field values), and `stored-responses` (a list of stored responses suitable for reuse as defined in Section 4 of {{!RFC7234}}, excepting the requirement to calculate a secondary cache key):

1. If stored-responses is empty, return an empty list.
2. Order stored-responses by the "Date" header field, most recent to least recent.
3. Let sorted-variants be an empty list.
4. If the freshest member of stored-responses (as per {{!RFC7234}}, Section 4.2) has one or more "Variants" header field(s):
1. Select one member of stored-responses and let variants-header be its "Variants" header field-value(s). This SHOULD be the most recent response, but MAY be from an older one as long as it is still fresh.
3. For each variant in variants-header, parsed according to the ABNF:
1. If variant's field-name corresponds to the request header field identified by a content negotiation mechanism that the implementation supports:
1. Let request-value be the field-value(s) associated with field-name in incoming-request.
2. Let available-values be a list containing all available-value for variant.
3. Let sorted-values be the result of running the algorithm defined by the content negotiation mechanism with request-value and available-values.
4. Append sorted-values to sorted-variants.
1. If `stored-responses` is empty, return an empty list.
2. Order `stored-responses` by the "Date" header field, most recent to least recent.
3. Let `sorted-variants` be an empty list.
4. If the freshest member of `stored-responses` (as per {{!RFC7234}}, Section 4.2) has one or more "Variants" header field(s):
1. Select one member of `stored-responses` and let `variants-header` be its "Variants" header field-value(s). This SHOULD be the most recent response, but MAY be from an older one as long as it is still fresh.
3. For each `variant` in `variants-header`, parsed according to the ABNF:
1. If `variant`'s field-name corresponds to the request header field identified by a content negotiation mechanism that the implementation supports:
1. Let `request-value` be the field-value(s) associated with field-name in `incoming-request`.
2. Let `available-values` be a list containing all available-value for variant.
3. Let `sorted-values` be the result of running the algorithm defined by the content negotiation mechanism with `request-value` and `available-values`.
4. Append `sorted-values` to `sorted-variants`.

At this point, sorted-variants will be a list of lists, each member of the top-level list corresponding to a variant-item in the Variants header field-value, containing zero or more items indicating available-values that are acceptable to the client, in order of preference, greatest to least.
At this point, `sorted-variants` will be a list of lists, each member of the top-level list corresponding to a variant-item in the Variants header field-value, containing zero or more items indicating available-values that are acceptable to the client, in order of preference, greatest to least.

5. Return result of running Compute Possible Keys ({{find}}) on sorted-variants, an empty string and an empty list.
5. Return result of running Compute Possible Keys ({{find}}) on `sorted-variants`, an empty string and an empty list.

This returns a list of strings suitable for comparing to normalised Variant-Keys ({{gen-variant-key}}) that represent possible responses on the server that can be used to satisfy the request, in preference order, provided that their secondary cache key (after removing the headers covered by Variants) matches. {{check_vary}} illustrates one way to do this.

Expand All @@ -264,34 +264,34 @@ This returns a list of strings suitable for comparing to normalised Variant-Keys

This algorithm computes the cross-product of the elements of key-facets.

Given key-facets (a list of lists), and key-stub (a string representing a partial key), and possible-keys (a list):
Given `key-facets` (a list of lists), and `key-stub` (a string representing a partial key), and `possible-keys` (a list):

1. Let values be the first member of key-facets.
2. For each value in values:
1. If key-stub is an empty string, let this-key be a copy of value.
1. Let `values` be the first member of `key-facets`.
2. For each `value` in `values`:
1. If `key-stub` is an empty string, let `this-key` be a copy of `value`.
1. Otherwise:
1. Let this-key be a copy of key-stub.
2. Append a semicolon (";") to this-key.
3. Append value to this-key.
3. Let remaining-facets be a copy of all of the members of key-facets except the first.
4. If remaining-facets is empty, append this-key to possible-keys.
5. Otherwise, run Compute Possible Keys on remaining-facets, this-key and possible-keys.
3. Return possible-keys.
1. Let `this-key` be a copy of `key-stub`.
2. Append a semicolon (";") to `this-key`.
3. Append `value` to `this-key`.
3. Let `remaining-facets` be a copy of all of the members of `key-facets` except the first.
4. If `remaining-facets` is empty, append `this-key` to `possible-keys`.
5. Otherwise, run Compute Possible Keys on `remaining-facets`, `this-key` and `possible-keys`.
3. Return `possible-keys`.


## Check Vary {#check_vary}

This algorithm is an example of how an implementation can meet the requirement to apply the members of the Vary header field that are not covered by Variants.

Given stored-response (a stored response):
Given `stored-response` (a stored response):

1. Let filtered-vary be the field-value(s) of stored-response's "Vary" header field.
2. Let processed-variants be a list containing the request header fields that identify the content negotiation mechanisms supported by the implementation.
3. Remove any member of filtered-vary that is a case-insensitive match for a member of processed-variants.
4. If the secondary cache key (as calculated in {{!RFC7234}}, Section 4.1) for stored_response matches incoming-request, using filtered-vary for the value of the "Vary" response header, return True.
1. Let `filtered-vary` be the field-value(s) of `stored-response`'s "Vary" header field.
2. Let `processed-variants` be a list containing the request header fields that identify the content negotiation mechanisms supported by the implementation.
3. Remove any member of `filtered-vary` that is a case-insensitive match for a member of `processed-variants`.
4. If the secondary cache key (as calculated in {{!RFC7234}}, Section 4.1) for `stored-response` matches incoming-request, using `filtered-vary` for the value of the "Vary" response header, return True.
5. Return False.

This returns a Boolean that indicates whether stored-response can be used to satisfy the request.
This returns a Boolean that indicates whether `stored-response` can be used to satisfy the request.

Note that implementation of the Vary header field varies in practice, and the algorithm above illustrates only one way to apply it. It is equally viable to forward the request if there is a request header listed in Vary but not Variants.

Expand All @@ -311,7 +311,7 @@ Accept-Language: fr;q=1.0, en;q=0.1
Accept-Encoding: gzip
~~~

Then the sorted-variants would be:
Then the `sorted-variants` would be:

~~~ example
[
Expand All @@ -320,7 +320,7 @@ Then the sorted-variants would be:
]
~~~

Which means that the sorted-keys would be:
Which means that the `sorted-keys` would be:

~~~ example
[
Expand Down Expand Up @@ -449,8 +449,8 @@ Here, the cache will need to calculate a secondary cache key as per {{!RFC7234}}
To be usable with Variants, proactive content negotiation mechanisms need to be specified to take advantage of it. Specifically, they:

* MUST define a request header field that advertises the clients preferences or capabilities, whose field-name SHOULD begin with "Accept-".
* MUST define the syntax of an available-value that will occur in Variants and Variant-Key.
* MUST define an algorithm for selecting a result. It MUST return a list of available-values that are suitable for the request, in order of preference, given the value of the request header nominated above and an available-values list from the Variants header. If the result is an empty list, it implies that the cache cannot satisfy the request.
* MUST define the syntax of an `available-value` that will occur in Variants and Variant-Key.
* MUST define an algorithm for selecting a result. It MUST return a list of `available-value`s that are suitable for the request, in order of preference, given the value of the request header nominated above and an `available-values` list from the Variants header. If the result is an empty list, it implies that the cache cannot satisfy the request.

{{backports}} fulfils these requirements for some existing proactive content negotiation mechanisms in HTTP.

Expand Down Expand Up @@ -499,14 +499,14 @@ The syntax of an available-value for Accept is:
accept-available-value = type "/" subtype
~~~

To perform content negotiation for Accept given a request-value and available-values:
To perform content negotiation for Accept given a `request-value` and `available-values`:

1. Let preferred-available be an empty list.
2. Let preferred-types be a list of the types in the request-value, ordered by their weight, highest to lowest, as per Section 5.3.2 of {{!RFC7231}} (omitting any coding with a weight of 0). If "Accept" is not present or empty, preferred-types will be empty. If a type lacks an explicit weight, an implementation MAY assign one.
3. If the first member of available-values is not a member of preferred-types, append it to preferred-types (thus making it the default).
4. For each preferred-type in preferred-types:
1. If any member of available-values matches preferred-type, using the media-range matching mechanism specified in Section 5.3.2 of {{!RFC7231}} (which is case-insensitive), append those members of available-values to preferred-available (preserving the precedence order implied by the media ranges' specificity).
5. Return preferred-available.
1. Let `preferred-available` be an empty list.
2. Let `preferred-types` be a list of the types in the `request-value`, ordered by their weight, highest to lowest, as per Section 5.3.2 of {{!RFC7231}} (omitting any coding with a weight of 0). If "Accept" is not present or empty, `preferred-types` will be empty. If a type lacks an explicit weight, an implementation MAY assign one.
3. If the first member of `available-values` is not a member of `preferred-types`, append it to `preferred-types` (thus making it the default).
4. For each `preferred-type` in `preferred-types`:
1. If any member of `available-values` matches `preferred-type`, using the media-range matching mechanism specified in Section 5.3.2 of {{!RFC7231}} (which is case-insensitive), append those members of `available-values` to `preferred-available` (preserving the precedence order implied by the media ranges' specificity).
5. Return `preferred-available`.

Note that this algorithm explicitly ignores extension parameters on media types (e.g., "charset").

Expand All @@ -521,15 +521,15 @@ The syntax of an available-value for Accept-Encoding is:
accept-encoding-available-value = content-coding / "identity"
~~~

To perform content negotiation for Accept-Encoding given a request-value and available-values:
To perform content negotiation for Accept-Encoding given a `request-value` and `available-values`:

1. Let preferred-available be an empty list.
2. Let preferred-codings be a list of the codings in the request-value, ordered by their weight, highest to lowest, as per Section 5.3.1 of {{!RFC7231}} (omitting any coding with a weight of 0). If "Accept-Encoding" is not present or empty, preferred-codings will be empty. If a coding lacks an explicit weight, an implementation MAY assign one.
3. If "identity" is not a member of preferred-codings, append "identity".
4. Append "identity" to available-values.
5. For each preferred-coding in preferred-codings:
1. If there is a case-insensitive, character-for-character match for preferred-coding in available-values, append that member of available-values to preferred-available.
6. Return preferred-available.
1. Let `preferred-available` be an empty list.
2. Let `preferred-codings` be a list of the codings in the `request-value`, ordered by their weight, highest to lowest, as per Section 5.3.1 of {{!RFC7231}} (omitting any coding with a weight of 0). If "Accept-Encoding" is not present or empty, `preferred-codings` will be empty. If a coding lacks an explicit weight, an implementation MAY assign one.
3. If "identity" is not a member of `preferred-codings`, append "identity".
4. Append "identity" to `available-values`.
5. For each `preferred-coding` in `preferred-codings`:
1. If there is a case-insensitive, character-for-character match for `preferred-coding` in `available-values`, append that member of `available-values` to `preferred-available`.
6. Return `preferred-available`.

Note that the unencoded variant needs to have a Variant-Key header field with a value of "identity" (as defined in Section 5.3.4 of {{!RFC7231}}).

Expand All @@ -543,14 +543,14 @@ The syntax of an available-value for Accept-Language is:
accept-encoding-available-value = language-range
~~~

To perform content negotiation for Accept-Language given a request-value and available-values:
To perform content negotiation for Accept-Language given a `request-value` and `available-values`:

1. Let preferred-available be an empty list.
2. Let preferred-langs be a list of the language-ranges in the request-value, ordered by their weight, highest to lowest, as per Section 5.3.1 of {{!RFC7231}} (omitting any language-range with a weight of 0). If a language-range lacks a weight, an implementation MAY assign one.
3. If the first member of available-values is not a member of preferred-langs, append it to preferred-langs (thus making it the default).
4. For each preferred-lang in preferred-langs:
1. If any member of available-values matches preferred-lang, using either the Basic or Extended Filtering scheme defined in Section 3.3 of {{!RFC4647}}, append those members of available-values to preferred-available (preserving their order).
5. Return preferred-available.
1. Let `preferred-available` be an empty list.
2. Let `preferred-langs` be a list of the language-ranges in the `request-value`, ordered by their weight, highest to lowest, as per Section 5.3.1 of {{!RFC7231}} (omitting any language-range with a weight of 0). If a language-range lacks a weight, an implementation MAY assign one.
3. If the first member of `available-values` is not a member of `preferred-langs`, append it to `preferred-langs` (thus making it the default).
4. For each `preferred-lang` in `preferred-langs`:
1. If any member of `available-values` matches `preferred-lang`, using either the Basic or Extended Filtering scheme defined in Section 3.3 of {{!RFC4647}}, append those members of `available-values` to `preferred-available` (preserving their order).
5. Return `preferred-available`.


# Acknowledgements
Expand Down

0 comments on commit 8908c24

Please sign in to comment.