Why every method from Location returns a Result<T, JsValue>?

[xeho91]

Hi web-sys maintainers!

I'd like to understand the reasoning behind the setting return value of every methods from the Location with Result<T, JsValue>.

---

Lets take Location::origin(&self) for example.

Following the MDN WebAPI for window.location.origin it never returns an error.

Why then, instead of returning String it is wrapped with Result, and returning JsValue when it fails?
What is JsValue supposed to return exactly?

Trying to study and understand by myself, I found out that window().unwrap().location() doesn't return a Result, which would give me a suggestion that this is related to some conversion mechanism from JavaScript to Rust. But at this point, I am clueless.

[Liamolucko]

web-sys is automatically generated from a pile of 'WebIDL' files here, which is how web APIs define their interfaces. In particular, it decides whether or not a function or getter should return a Result based on whether it's annotated with a [Throws] attribute in WebIDL, which location.origin is:

wasm-bindgen/crates/web-sys/webidls/enabled/Location.webidl

Lines 25 to 26 in bb12058

	[Throws, NeedsSubjectPrincipal]
	readonly attribute USVString origin;

...Except, the [Throws] attribute isn't actually an official part of WebIDL. It's a custom addition used by Firefox, which is where web-sys copied most of its WebIDL from. So, the answer to why it returns Result is pretty much 'because Firefox thought it should back when we copied its WebIDL'.

(Copying Firefox's WebIDL instead of using the versions from the actual standards has led to some issues before, e.g. #3227, although I can't remember any particular cases where something was incorrectly annotated with [Throws]. It might have happened though.)

As for whether or not it should return Result though, I think the answer is yes. My rule of thumb for deciding whether or not a function should be annotated with [Throws] when adding a new API is to check the specification for that function and see if there are any cases where it says to throw an error, since that should be the definitive source. And the spec for location.origin says:

The origin getter steps are:

1. If this's relevant Document is non-null and its origin is not same origin-domain with the entry settings object's origin, then throw a "SecurityError" DOMException.

2. Return the serialization of this's url's origin.

Apparently it can throw a SecurityError in some scenarios, and so Location::origin should return a Result so that it can be properly handled.

[xeho91]

Thanks for such detailed answer, have a good time!