From f4fd14af2cbc981ac72b7fbdd3d3de2e30fdbb68 Mon Sep 17 00:00:00 2001 From: "Adam C. Foltzer" Date: Wed, 31 Jan 2024 13:09:12 -0800 Subject: [PATCH 1/2] Tweak a few `fields` docs - This patch clarifies the behavior of the various `fields` methods when syntactically invalid inputs are given. Some methods already noted this, but `get` in particular was missing a clarification that an invalid key would result in an empty list result - Removed some text in the doc for `from-list`. While non-UTF-8 values are not preferred for new applications, they are syntactically valid due to the [`obs-text` production](https://www.rfc-editor.org/rfc/rfc9110#section-5.5-2) in the RFC grammar. --- wit/types.wit | 23 +++++++++++++++-------- 1 file changed, 15 insertions(+), 8 deletions(-) diff --git a/wit/types.wit b/wit/types.wit index 755ac6a..70cce55 100644 --- a/wit/types.wit +++ b/wit/types.wit @@ -159,20 +159,18 @@ interface types { /// list with the same key. /// /// The tuple is a pair of the field key, represented as a string, and - /// Value, represented as a list of bytes. In a valid Fields, all keys - /// and values are valid UTF-8 strings. However, values are not always - /// well-formed, so they are represented as a raw list of bytes. + /// Value, represented as a list of bytes. /// - /// An error result will be returned if any header or value was - /// syntactically invalid, or if a header was forbidden. + /// An error result will be returned if any `field-key` or `field-value` is + /// syntactically invalid, or if a field is forbidden. from-list: static func( entries: list> ) -> result; /// Get all of the values corresponding to a key. If the key is not present - /// in this `fields`, an empty list is returned. However, if the key is - /// present but empty, this is represented by a list with one or more - /// empty field-values present. + /// in this `fields` or is syntactically invalid, an empty list is returned. + /// However, if the key is present but empty, this is represented by a list + /// with one or more empty field-values present. get: func(name: field-key) -> list; /// Returns `true` when the key is present in this `fields`. If the key is @@ -183,18 +181,27 @@ interface types { /// key, if they have been set. /// /// Fails with `header-error.immutable` if the `fields` are immutable. + /// + /// Fails with `header-error.invalid-syntax` if the `field-key` or any of + /// the `field-value`s are syntactically invalid. set: func(name: field-key, value: list) -> result<_, header-error>; /// Delete all values for a key. Does nothing if no values for the key /// exist. /// /// Fails with `header-error.immutable` if the `fields` are immutable. + /// + /// Fails with `header-error.invalid-syntax` if the `field-key` is + /// syntactically invalid. delete: func(name: field-key) -> result<_, header-error>; /// Append a value for a key. Does not change or delete any existing /// values for that key. /// /// Fails with `header-error.immutable` if the `fields` are immutable. + /// + /// Fails with `header-error.invalid-syntax` if the `field-key` or + /// `field-value` are syntactically invalid. append: func(name: field-key, value: field-value) -> result<_, header-error>; /// Retrieve the full set of keys and values in the Fields. Like the From 8ef52c2985975c3dc57005c1f678f320ad415e3b Mon Sep 17 00:00:00 2001 From: "Adam C. Foltzer" Date: Wed, 31 Jan 2024 16:15:29 -0800 Subject: [PATCH 2/2] regenerate markdown --- proxy.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/proxy.md b/proxy.md index 5a249a4..93edb93 100644 --- a/proxy.md +++ b/proxy.md @@ -817,11 +817,9 @@ http-related errors.

which have multiple values are represented by multiple entries in this list with the same key.

The tuple is a pair of the field key, represented as a string, and -Value, represented as a list of bytes. In a valid Fields, all keys -and values are valid UTF-8 strings. However, values are not always -well-formed, so they are represented as a raw list of bytes.

-

An error result will be returned if any header or value was -syntactically invalid, or if a header was forbidden.

+Value, represented as a list of bytes.

+

An error result will be returned if any field-key or field-value is +syntactically invalid, or if a field is forbidden.

Params

[method]fields.get: func

Get all of the values corresponding to a key. If the key is not present -in this fields, an empty list is returned. However, if the key is -present but empty, this is represented by a list with one or more -empty field-values present.

+in this fields or is syntactically invalid, an empty list is returned. +However, if the key is present but empty, this is represented by a list +with one or more empty field-values present.

Params
  • self: borrow<fields>
    • @@ -860,6 +858,8 @@ syntactically invalid, false is returned.

    Set all of the values for a key. Clears any existing values for that key, if they have been set.

    Fails with header-error.immutable if the fields are immutable.

    +

    Fails with header-error.invalid-syntax if the field-key or any of +the field-values are syntactically invalid.

    Params
    • self: borrow<fields>
      • @@ -874,6 +874,8 @@ key, if they have been set.

      Delete all values for a key. Does nothing if no values for the key exist.

      Fails with header-error.immutable if the fields are immutable.

      +

      Fails with header-error.invalid-syntax if the field-key is +syntactically invalid.

      Params
      • self: borrow<fields>
        • @@ -887,6 +889,8 @@ exist.

        Append a value for a key. Does not change or delete any existing values for that key.

        Fails with header-error.immutable if the fields are immutable.

        +

        Fails with header-error.invalid-syntax if the field-key or +field-value are syntactically invalid.

        Params