Specify error mappings

[a-sully]

This came up in web-platform-tests/wpt@b20e834#r85726061

Ideally API errors map uniquely to DOMExceptions, which make them actionable by the site. For example, if NoModificationAllowedError always indicates that a file is locked and NotAllowedError always indicates the site needs to requestPermission()on the handle, the site can respond differently to these errors.

Currently, developers have to figure out this mapping on their own, or read the whole spec and infer this mapping. It would be nice to include a table mapping API errors to DOMExceptions that developers can use as a reference. Is there precedent for having this type of table in a spec?

That being said, it could be tricky to add a mapping that truly guarantees an error corresponds to a given API error (especially outside of the OPFS, where there's a whole host of things that could happen on the underlying OS). At the very least, here's a list of the mappings I'm aware of as a starting point...

• NotAllowedError
  • No permission at the API level (i.e. need to requestPermission())
• NoModificationAllowedError
  • Cannot acquire a lock to the handle
  • Handle lacks read or write permission at the OS level (for example, trying to get write permission on a read-only file). This should only be relevant outside of the OPFS
• InvalidModificationError
  • Attempting to overwrite a file via move()
• QuotaExceededError
  • Operation will exceed quota
• TypeMismatchError
  • The handle type (file/dir) does not match what's on disk
• AbortError
  • Using a not-yet-launched feature (i.e. directory move())
  • Some internal errors
• InvalidStateError
  • Attempting to close an already-closed writable or SyncAccessHandle
  • Some internal errors

Some errors are mostly relevant outside of the OPFS:

• AbortError (in addition to above)
  • Picker selection cancelled
  • File save/move blocked by Safe Browsing
• InvalidStateError (in addition to above)
  • Trying to show a picker in a detached frame
• SecurityError
  • Trying to show picker in sandboxed iframe/opaque origin/third party context/without user gesture

[annevk]

"AbortError" is very specific and mainly for abort signals only. cc @domenic

I'd also recommend considering that implementations might want some flexibility going forward so requiring rather unique exceptions might not be worthwhile if web developers aren't expected to branch on the exception names anyway.

[jesup]

If there's specific action an application might want to take for a specific failure mode, then tightly specifying errors would be useful. Otherwise tightly specifying errors doesn't have much benefit I can see; though specifying them avoids unintentional lock-in by developers who look for a specific (non-specced) error, and then break if it changes -- or if they use a different browser. However, we should be in alignment with how other specs do (or should) specify errors. @annevk ? @domenic ?

We throw SecurityError for some cases that violate security rules.

Instead of AbortError for non-implemented features, maybe NotSupportedError?

[domenic]

So you definitely need to specify the error type, and all browsers need to agree. There's no option of not specifying the error type at all.

But you don't need to make sure every error type is used perfectly and maps to distinct cases, if developers don't need to distinguish between such cases. For example, you could just always throw a TypeError (the web platform's generic error). Or, you could just lump a bunch of error conditions together under "OperationError" DOMException, or "InvalidStateError" DOMException. That's a reasonable option.

Specific error type guidance you should be consistent with, which is unfortunately not written down or consistently applied, is:

• Use "NotAllowedError" DOMException for permissions
• Use "SecurityError" DOMException for security checks
• Use "NotSupportedError" DOMException for not-yet-launched features
• Use "AbortError" DOMException for operations that were aborted, usually in the sense of the developer requesting or causing the abort, usually via an AbortSignal.
• Use "UnknownError" DOMException for internal, implementation-specific issues.

Note that "TypeMismatchError" DOMException is deprecated.

So yeah, there are some improvements you could make here to align better with the rest of the platform.