all child fields are immutable, add header-error.immutable error

and update the doc strings throughout to specify which give a mutable
fields and which give an immutable fields. also, add missed text that
a future-trailers gives a child resource fields

Co-authored-by:  Trevor Elliott <telliott@fastly.com>

Author: Pat Hickey

wit/types.wit

@@ -117,6 +117,10 @@ interface types {
     /// This error indicates that a forbidden `field-key` was used when trying
     /// to set a header in a `fields`.
     forbidden,
+
+    /// This error indicates that the operation on the `fields` was not
+    /// permitted because the fields are immutable.
+    immutable,
   }
 
   /// Field keys are always strings.
@@ -130,13 +134,24 @@ interface types {
   /// This following block defines the `fields` resource which corresponds to
   /// HTTP standard Fields. Fields are a common representation used for both
   /// Headers and Trailers.
+  ///
+  /// A `fields` may be mutable or immutable. A `fields` created using the
+  /// constructor, `from-list`, or `clone` will be mutable, but a `fields`
+  /// resource given by other means (including, but not limited to,
+  /// `incoming-request.headers`, `outgoing-request.headers`) might be be
+  /// immutable. In an immutable fields, the `set`, `append`, and `delete`
+  /// operations will fail with `header-error.immutable`.
   resource fields {
 
     /// Construct an empty HTTP Fields.
+    ///
+    /// The resulting `fields` is mutable.
     constructor();
 
     /// Construct an HTTP Fields.
     ///
+    /// The resulting `fields` is mutable.
+    ///
     /// The list represents each key-value pair in the Fields. Keys
     /// which have multiple values are represented by multiple entries in this
     /// list with the same key.
@@ -157,14 +172,20 @@ interface types {
 
     /// 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.
     set: func(name: field-key, value: list<field-value>) -> 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.
     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.
     append: func(name: field-key, value: field-value) -> result<_, header-error>;
 
     /// Retrieve the full set of keys and values in the Fields. Like the
@@ -176,7 +197,8 @@ interface types {
     entries: func() -> list<tuple<field-key,field-value>>;
 
     /// Make a deep copy of the Fields. Equivelant in behavior to calling the
-    /// `fields` constructor on the return value of `entries` 
+    /// `fields` constructor on the return value of `entries`. The resulting
+    /// `fields` is mutable.
     clone: func() -> fields;
   }
 
@@ -201,7 +223,10 @@ interface types {
     /// Returns the authority from the request, if it was present.
     authority: func() -> option<string>;
 
-    /// Returns the `headers` from the request.
+    /// Get the `headers` associated with the request.
+    ///
+    /// The returned `headers` resource is immutable: `set`, `append`, and
+    /// `delete` operations will fail with `header-error.immutable`.
     ///
     /// The `headers` returned are a child resource: it must be dropped before
     /// the parent `incoming-request` is dropped. Dropping this
@@ -272,6 +297,9 @@ interface types {
 
     /// Get the headers associated with the Request.
     ///
+    /// The returned `headers` resource is immutable: `set`, `append`, and
+    /// `delete` operations will fail with `header-error.immutable`.
+    ///
     /// This headers resource is a child: it must be dropped before the parent
     /// `outgoing-request` is dropped, or its ownership is transfered to
     /// another component by e.g. `outgoing-handler.handle`.
@@ -344,6 +372,12 @@ interface types {
     status: func() -> status-code;
 
     /// Returns the headers from the incoming response.
+    ///
+    /// The returned `headers` resource is immutable: `set`, `append`, and
+    /// `delete` operations will fail with `header-error.immutable`.
+    ///
+    /// This headers resource is a child: it must be dropped before the parent
+    /// `incoming-response` is dropped.
     headers: func() -> headers;
 
     /// Returns the incoming body. May be called at most once. Returns error
@@ -405,6 +439,11 @@ interface types {
     /// as well as any trailers, were received successfully, or that an error
     /// occured receiving them. The optional `trailers` indicates whether or not
     /// trailers were present in the body.
+    ///
+    /// When some `trailers` are returned by this method, the `trailers`
+    /// resource is immutable, and a child. Use of the `set`, `append`, or
+    /// `delete` methods will return an error, and the resource must be
+    /// dropped before the parent `future-trailers` is dropped.
     get: func() -> option<result<option<trailers>, error-code>>;
   }
 
@@ -427,6 +466,9 @@ interface types {
 
     /// Get the headers associated with the Request.
     ///
+    /// The returned `headers` resource is immutable: `set`, `append`, and
+    /// `delete` operations will fail with `header-error.immutable`.
+    ///
     /// This headers resource is a child: it must be dropped before the parent
     /// `outgoing-request` is dropped, or its ownership is transfered to
     /// another component by e.g. `outgoing-handler.handle`.