fix(runtime): implement spec-compliant HeadersIterator for Headers API (#5003)

## Summary

Fix `Headers.entries()`, `Headers.keys()`, and `Headers.values()` so
they return proper iterator objects instead of arrays.

Closes #4989

## Problem

`Headers.entries()`, `Headers.keys()`, and `Headers.values()` were not
returning iterator objects.

Current behavior before this change:
- `entries()` returned an array
- `keys()` and `values()` returned collected values without a callable
`.next()`
- `Headers[Symbol.iterator]()` already worked through a workaround

Because of this, calls like `headers.entries().next()` failed.

## What changed

- Added a `HeadersIterator` implementation for fetch headers
- Updated `Headers.entries()`, `Headers.keys()`, and `Headers.values()`
to return iterator objects
- Kept `Headers[Symbol.iterator]()` aligned with iterator behavior
- Added regression tests covering iterator behavior and `for...of` usage

## Tests

Added/updated tests for:
- `entries()` returns an iterator
- `keys()` returns an iterator
- `values()` returns an iterator
- iterator results have the correct `{ value, done }` shape
- `[Symbol.iterator]()` still works
- `for...of` works with headers iteration

Ran locally:

```bash
cargo test
```
## Specification

According to the Fetch Standard, `Headers.entries()`, `Headers.keys()`,
and
`Headers.values()` must return iterator objects.

Reference:
https://fetch.spec.whatwg.org/#headers-class

This change aligns Boa's `Headers` implementation with the expected
iterator
semantics used by other JavaScript runtimes.

Author: iammdzaidalam

core/runtime/src/fetch/headers.rs

@@ -3,8 +3,9 @@
 //! See <https://developer.mozilla.org/en-US/docs/Web/API/Headers>.
 #![allow(clippy::needless_pass_by_value)]
 
+use super::headers_iterator::{HeadersIterator, IterationKind};
 use boa_engine::interop::JsClass;
-use boa_engine::object::builtins::{JsArray, TypedJsFunction};
+use boa_engine::object::builtins::TypedJsFunction;
 use boa_engine::value::{Convert, TryFromJs};
 use boa_engine::{
     Context, Finalize, JsData, JsObject, JsResult, JsString, JsValue, Trace, boa_class, js_error,
@@ -49,7 +50,7 @@ fn to_header_value(value: impl AsRef<str>) -> JsResult<HeaderValue> {
 #[derive(Debug, Default, Clone, JsData, Trace, Finalize)]
 pub struct JsHeaders {
     #[unsafe_ignore_trace]
-    headers: Rc<RefCell<HttpHeaderMap>>,
+    pub(crate) headers: Rc<RefCell<HttpHeaderMap>>,
 }
 
 impl TryFromJs for JsHeaders {
@@ -159,21 +160,13 @@ impl JsHeaders {
     }
 
     /// Returns an iterator allowing to go through all key/value pairs contained in this object.
-    // TODO: This should return a JsIterator, but not such thing exists yet.
-    pub fn entries(&self, context: &mut Context) -> JsValue {
-        JsArray::from_iter(
-            self.headers
-                .borrow()
-                .iter()
-                .map(|(k, v)| {
-                    let k: JsValue = JsString::from(k.as_str()).into();
-                    let v: JsValue = JsString::from(v.to_str().unwrap_or_default()).into();
-                    JsArray::from_iter([k, v], context).into()
-                })
-                .collect::<Vec<_>>(),
-            context,
-        )
-        .into()
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the headers iterator cannot be created.
+    #[boa(method)]
+    pub fn entries(this: JsClass<Self>, context: &mut Context) -> JsResult<JsValue> {
+        HeadersIterator::create_headers_iterator(this.inner(), IterationKind::KeyAndValue, context)
     }
 
     /// Executes a provided function once for each key/value pair in the Headers object.
@@ -246,13 +239,13 @@ impl JsHeaders {
 
     /// Returns an iterator allowing you to go through all keys of the key/value pairs
     /// contained in this object.
-    #[allow(clippy::unused_self)]
-    fn keys(&self) -> Vec<JsString> {
-        self.headers
-            .borrow()
-            .keys()
-            .map(|k| JsString::from(k.as_str()))
-            .collect()
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the headers iterator cannot be created.
+    #[boa(method)]
+    fn keys(this: JsClass<Self>, context: &mut Context) -> JsResult<JsValue> {
+        HeadersIterator::create_headers_iterator(this.inner(), IterationKind::Key, context)
     }
 
     /// Sets a new value for an existing header inside a Headers object, or adds the
@@ -264,11 +257,24 @@ impl JsHeaders {
         Ok(())
     }
 
-    fn values(&self) -> Vec<JsString> {
-        self.headers
-            .borrow()
-            .values()
-            .map(|v| JsString::from(v.to_str().unwrap_or("")))
-            .collect()
+    /// Returns an iterator allowing you to go through all values of the key/value pairs
+    /// contained in this object.
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the headers iterator cannot be created.
+    #[boa(method)]
+    fn values(this: JsClass<Self>, context: &mut Context) -> JsResult<JsValue> {
+        HeadersIterator::create_headers_iterator(this.inner(), IterationKind::Value, context)
+    }
+
+    /// `[Symbol.iterator]()` is an alias for `entries()`
+    ///
+    /// # Errors
+    ///
+    /// Returns an error if the headers iterator cannot be created.
+    #[boa(symbol = "iterator")]
+    fn symbol_iterator(this: JsClass<Self>, context: &mut Context) -> JsResult<JsValue> {
+        HeadersIterator::create_headers_iterator(this.inner(), IterationKind::KeyAndValue, context)
     }
 }

core/runtime/src/fetch/headers_iterator.rs

@@ -0,0 +1,122 @@
+//! This module implements the `HeadersIterator` object.
+//!
+//! More information:
+//!  - [Fetch specification][spec]
+//!
+//! [spec]: https://fetch.spec.whatwg.org/#headers-class
+
+use boa_engine::{
+    Context, JsData, JsResult, JsString, JsValue, boa_class,
+    builtins::iterable::create_iter_result_object, error::JsNativeError, interop::JsClass,
+    object::JsObject, object::builtins::JsArray,
+};
+use boa_gc::{Finalize, Trace};
+
+use super::headers::JsHeaders;
+
+/// The `IterationKind` enum represents the different kinds of iteration that can be performed.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub(crate) enum IterationKind {
+    /// Iterates over the keys.
+    Key,
+    /// Iterates over the values.
+    Value,
+    /// Iterates over the keys and values.
+    KeyAndValue,
+}
+
+/// The Headers Iterator object represents an iteration over a Headers object.
+/// It implements the iterator protocol.
+///
+/// More information:
+///  - [Fetch specification][spec]
+///
+/// [spec]: https://fetch.spec.whatwg.org/#headers-class
+#[derive(Debug, Finalize, Trace, JsData)]
+pub(crate) struct HeadersIterator {
+    iterated_headers: JsObject<JsHeaders>,
+    next_index: usize,
+    #[unsafe_ignore_trace]
+    iteration_kind: IterationKind,
+}
+
+#[boa_class(rename = "Headers Iterator")]
+impl HeadersIterator {
+    /// Prevent direct construction — `HeadersIterator` instances are only
+    /// created internally via [`HeadersIterator::create_headers_iterator`].
+    #[boa(constructor)]
+    fn constructor() -> JsResult<Self> {
+        Err(JsNativeError::typ()
+            .with_message("Illegal constructor")
+            .into())
+    }
+
+    /// `%HeadersIteratorPrototype%.next()`
+    ///
+    /// Advances the iterator and returns the next `{ value, done }` result.
+    #[boa(method)]
+    fn next(&mut self, context: &mut Context) -> JsValue {
+        let item_kind = self.iteration_kind;
+
+        let element = self
+            .iterated_headers
+            .borrow()
+            .data()
+            .headers
+            .borrow()
+            .iter()
+            .nth(self.next_index)
+            .map(|(k, v)| {
+                (
+                    JsValue::from(JsString::from(k.as_str())),
+                    JsValue::from(JsString::from(v.to_str().unwrap_or(""))),
+                )
+            });
+
+        if let Some((key, value)) = element {
+            self.next_index += 1;
+
+            return match item_kind {
+                IterationKind::Key => create_iter_result_object(key, false, context),
+                IterationKind::Value => create_iter_result_object(value, false, context),
+                IterationKind::KeyAndValue => {
+                    let result = JsArray::from_iter([key, value], context);
+                    create_iter_result_object(result.into(), false, context)
+                }
+            };
+        }
+
+        create_iter_result_object(JsValue::undefined(), true, context)
+    }
+
+    /// Returns `this`, making the iterator itself iterable (`for...of` support).
+    #[boa(method)]
+    #[boa(symbol = "iterator")]
+    fn symbol_iterator(this: JsClass<Self>) -> JsValue {
+        this.inner().into()
+    }
+}
+
+impl HeadersIterator {
+    /// Creates a new iterator over the given `Headers` object.
+    pub(crate) fn create_headers_iterator(
+        headers: JsObject<JsHeaders>,
+        kind: IterationKind,
+        context: &mut Context,
+    ) -> JsResult<JsValue> {
+        let iter = Self {
+            iterated_headers: headers,
+            next_index: 0,
+            iteration_kind: kind,
+        };
+
+        let proto = context
+            .realm()
+            .get_class::<Self>()
+            .ok_or_else(|| boa_engine::js_error!(Error: "Headers Iterator not registered"))?
+            .prototype();
+
+        let headers_iterator = JsObject::from_proto_and_data(proto, iter);
+        Ok(headers_iterator.into())
+    }
+}

core/runtime/src/fetch/mod.rs

@@ -8,11 +8,11 @@
 //! [mdn]: https://developer.mozilla.org/en-US/docs/Web/API/fetch
 
 use crate::fetch::headers::JsHeaders;
+use crate::fetch::headers_iterator::{HeadersIterator, IterationKind};
 use crate::fetch::request::{JsRequest, RequestInit};
 use crate::fetch::response::JsResponse;
 use boa_engine::class::Class;
 use boa_engine::object::FunctionObjectBuilder;
-use boa_engine::object::builtins::JsArray;
 use boa_engine::property::PropertyDescriptor;
 use boa_engine::realm::Realm;
 use boa_engine::{
@@ -25,6 +25,7 @@ use std::cell::RefCell;
 use std::rc::Rc;
 
 pub mod headers;
+pub mod headers_iterator;
 pub mod request;
 pub mod response;
 pub mod tests;
@@ -188,6 +189,7 @@ pub mod js_module {
     type JsHeaders = super::JsHeaders;
     type JsRequest = super::JsRequest;
     type JsResponse = super::JsResponse;
+    type HeadersIterator = super::headers_iterator::HeadersIterator;
 
     /// The `fetch` function.
     ///
@@ -207,21 +209,22 @@ pub mod js_module {
     }
 }
 
-#[doc(inline)]
-pub use js_module::fetch;
-
-fn headers_iterator(this: &JsValue, _: &[JsValue], context: &mut Context) -> JsResult<JsValue> {
-    let this_object = this.as_object();
-    let headers = this_object
-        .as_ref()
-        .and_then(JsObject::downcast_ref::<JsHeaders>)
-        .ok_or_else(|| {
-            js_error!(TypeError: "`Headers.prototype[Symbol.iterator]` requires a `Headers` object")
-        })?;
-
-    let entries = headers.entries(context);
-    let entries_array = JsArray::from_object(entries.to_object(context)?)?;
-    entries_array.values(context)
+fn headers_symbol_iterator(
+    this: &JsValue,
+    _: &[JsValue],
+    context: &mut Context,
+) -> JsResult<JsValue> {
+    let this_object = this.as_object().ok_or_else(
+        || js_error!(TypeError: "`Headers.prototype[Symbol.iterator]` requires a `Headers` object"),
+    )?;
+
+    let Ok(headers) = this_object.clone().downcast::<JsHeaders>() else {
+        return Err(
+            js_error!(TypeError: "`Headers.prototype[Symbol.iterator]` requires a `Headers` object"),
+        );
+    };
+
+    HeadersIterator::create_headers_iterator(headers, IterationKind::KeyAndValue, context)
 }
 
 /// Register the `fetch` function in the realm, as well as ALL supporting classes.
@@ -252,7 +255,7 @@ pub fn register<F: Fetcher>(
 
     let iterator = FunctionObjectBuilder::new(
         context.realm(),
-        NativeFunction::from_fn_ptr(headers_iterator),
+        NativeFunction::from_fn_ptr(headers_symbol_iterator),
     )
     .name(js_string!("[Symbol.iterator]"))
     .length(0)

core/runtime/src/fetch/tests/headers.rs

@@ -119,3 +119,30 @@ fn headers_invalid_inputs_throw_type_error_objects() {
         ),
     ]);
 }
+
+#[test]
+fn headers_iterator_throws_on_invalid_this() {
+    run_test_actions([
+        TestAction::harness(),
+        TestAction::inspect_context(register),
+        TestAction::run(
+            r#"
+                try {
+                    const iterator = Headers.prototype[Symbol.iterator].call({});
+                    throw Error("expected the call above to throw");
+                } catch (e) {
+                    assert(e instanceof TypeError);
+                    assertEq(e.message, "`Headers.prototype[Symbol.iterator]` requires a `Headers` object");
+                }
+
+                try {
+                    const iterator = Headers.prototype[Symbol.iterator].call(1);
+                    throw Error("expected the call above to throw");
+                } catch (e) {
+                    assert(e instanceof TypeError);
+                    assertEq(e.message, "`Headers.prototype[Symbol.iterator]` requires a `Headers` object");
+                }
+            "#,
+        ),
+    ]);
+}