From c8752e511824fed8fccd04076891da8afd57cf87 Mon Sep 17 00:00:00 2001
From: Erich Gubler <erichdongubler@gmail.com>
Date: Thu, 14 Nov 2024 14:50:01 -0500
Subject: [PATCH] feat(types): add `error::{ErrorType, WebGpuError}` APIs

---
 CHANGELOG.md            |  3 +++
 wgpu-types/src/error.rs | 46 +++++++++++++++++++++++++++++++++++++++++
 wgpu-types/src/lib.rs   |  1 +
 3 files changed, 50 insertions(+)
 create mode 100644 wgpu-types/src/error.rs

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 4b1a1cf6d..6fb701bc8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -58,6 +58,9 @@ Bottom level categories:
 - Add extra acceleration structure vertex formats. By @Vecvec in [#7580](https://github.com/gfx-rs/wgpu/pull/7580).
 - Add acceleration structure limits. By @Vecvec in [#7845](https://github.com/gfx-rs/wgpu/pull/7845).
 - Add support for clip-distances feature for Vulkan and GL backends. By @dzamkov in [#7730](https://github.com/gfx-rs/wgpu/pull/7730)
+- Added `wgpu_types::error::{ErrorType, WebGpuError}` for classification of errors according to WebGPU's [`GPUError`]'s classification scheme. This allows users of `wgpu-core` to offload error classification onto the WGPU ecosystem, rather than having to do it themselves without sufficient information. By @ErichDonGubler in [#6547](https://github.com/gfx-rs/wgpu/pull/6547).
+
+[`GPUError`]: https://www.w3.org/TR/webgpu/#gpuerror
 
 #### Vulkan
 
diff --git a/wgpu-types/src/error.rs b/wgpu-types/src/error.rs
new file mode 100644
index 000000000..33b2601ae
--- /dev/null
+++ b/wgpu-types/src/error.rs
@@ -0,0 +1,46 @@
+//! Shared types for WebGPU errors. See also:
+//! <https://gpuweb.github.io/gpuweb/#errors-and-debugging>
+
+use crate::DeviceLostReason;
+
+/// A classification of WebGPU error for implementers of the WebGPU API to use in their own error
+/// layer(s).
+///
+/// Strongly correlates to the [`GPUError`] and [`GPUErrorFilter`] types in the WebGPU API, with an
+/// additional [`Self::DeviceLost`] variant.
+///
+/// [`GPUError`]: https://gpuweb.github.io/gpuweb/#gpuerror
+/// [`GPUErrorFilter`]: https://gpuweb.github.io/gpuweb/#enumdef-gpuerrorfilter
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+#[cfg_attr(feature = "serde", derive(serde::Deserialize, serde::Serialize))]
+pub enum ErrorType {
+    /// A [`GPUInternalError`].
+    ///
+    /// [`GPUInternalError`]: https://gpuweb.github.io/gpuweb/#gpuinternalerror
+    Internal,
+    /// A [`GPUOutOfMemoryError`].
+    ///
+    /// [`GPUOutOfMemoryError`]: https://gpuweb.github.io/gpuweb/#gpuoutofmemoryerror
+    OutOfMemory,
+    /// A [`GPUValidationError`].
+    ///
+    /// [`GPUValidationError`]: https://gpuweb.github.io/gpuweb/#gpuvalidationerror
+    Validation,
+    /// Indicates that device loss occurred. In JavaScript, this means the [`GPUDevice.lost`]
+    /// property should be `resolve`d.
+    ///
+    /// [`GPUDevice.lost`]: https://www.w3.org/TR/webgpu/#dom-gpudevice-lost
+    DeviceLost {
+        /// The reason the device was lost.
+        reason: DeviceLostReason,
+    },
+}
+
+/// A trait for querying the [`ErrorType`] classification of an error.
+///
+/// This is intended to be used as a convenience by implementations of WebGPU to classify errors
+/// returned by [`wgpu_core`](crate).
+pub trait WebGpuError: core::error::Error + 'static {
+    /// Determine the classification of this error as a WebGPU [`ErrorType`].
+    fn webgpu_error_type(&self) -> ErrorType;
+}
diff --git a/wgpu-types/src/lib.rs b/wgpu-types/src/lib.rs
index 3cd9fa547..d0f014e22 100644
--- a/wgpu-types/src/lib.rs
+++ b/wgpu-types/src/lib.rs
@@ -36,6 +36,7 @@ pub mod assertions;
 mod cast_utils;
 mod counters;
 mod env;
+pub mod error;
 mod features;
 pub mod instance;
 pub mod math;