research: audit public API layer — logging, validation, error handling

[kolkov]

The public wgpu API layer was the last thing we built, and it shows. The HAL backends have mature logging (73 structured slog calls across Vulkan, Metal, DX12, GLES) and consistent validation — but the public layer that users actually interact with has none of that discipline.

This came up during PR #95 review — a contributor asked about validation style and we realized there isn't one. There are at least 4 different patterns in the same package.

What needs investigation

Logging:

• Public API layer has zero slog calls — no diagnostics at all
• HAL backends log everything (resource creation, errors, debug messages)
• Users debugging issues get nothing from the layer they interact with

Validation:

• WriteBuffer: compact combined nil check
• ReadBuffer: separate checks, different error format
• device.go: sentinel errors + fmt.Errorf mix
• encoder.go: no validation at all, straight passthrough to HAL
• No clear rule on what should be checked where

Error handling:

• Mixed formats: "wgpu: queue not available" vs "wgpu: WriteBuffer: queue or buffer is nil" vs "wgpu: buffer descriptor is nil"
• Some HAL errors wrapped with context, some passed through raw
• Sentinel errors (ErrReleased) used inconsistently

What we need to figure out

1. What should the public API layer actually validate vs delegate to HAL?
2. Should we log at the public layer, and if so — what and at what level?
3. One consistent error message format across all public methods
4. How does Rust wgpu handle this? (spoiler: zero validation in public layer, everything in wgpu-core)
5. Is our current split (public API → HAL) the right architecture, or do we need a core validation layer in between?

Deliverable

Research document + style guide before any code changes. We want to get this right, not just patch it.

Related

• [feat] Add WriteTexture to Queue #95 — WriteTexture PR that exposed the inconsistency
• research: assess type aliases in wgpu public API — problems and recommendations #96 — type aliases research (related public API design question)

[Carmen-Shannon]

If you already have verbose error logging from the backend layer then in my opinion the public API should just continue to propagate those errors up. From a user's perspective it is beneficial to have too much error handling rather than not enough, makes it much easier to debug.

I think basic validation from the public API with context as to what the backend expects is good; if passing a nil instance of a struct will cause a silent failure, the public API should catch that and propagate the error directly. But if your backend handles that same nil struct internally and has it's own error handling, then just propagating that up organically is fine and the public API really wouldn't need to worry about it since at that point you're just stopping a more verbose error from being shown by replacing it with a generic error log.

The issue is that as a contributor, it's not apparent without digging into the backend to see what would silently fail it, so in that regard having all error handling happen on the backend would make more sense to ease contributor's into the codebase. Once the standard is set for no validation on the public API it not only cleans up some boilerplate error checks from the codebase but allows the public API to not care about the backend requirements.

In regards to the current split I don't see any real major benefit to adding an additional validation layer between the public API and the backend, as long as the backend properly handles errors with verbose language then that will always be propagated up to the user when they construct something incorrectly. In my opinion effort is better spent auditing the backend to ensure all error cases are handled gracefully rather than implementing a layer in the middle which would in some cases probably be a duplication of logic.

Just my 2 cents, current usage doesn't feel "bad" or at least the errors I've experienced so far haven't been so ambiguous that I couldn't figure out what I was doing wrong and fix it.

[kolkov]

Hey @Carmen-Shannon, thanks for the thoughtful response! You raise valid points and I appreciate you sharing your perspective as someone actively using the API.

I did some deep research on this after your comment — looked at how Rust wgpu, Vulkan SDK, gRPC-Go, database/sql, Kubernetes client-go, Terraform, and Docker/Moby handle validation layering. Here's what I found and where I think we should land.

Where I agree with you:

• You're absolutely right that duplicating the same validation in two layers is wasteful. If the backend already checks something, repeating it in the public API just adds noise.
• "Effort is better spent auditing the backend" — partially true. Backend error quality matters a lot.
• Your experience that "current usage doesn't feel bad" is genuine feedback and I value that.

Where the research pushed back a bit:

The interesting finding is that every single library I analyzed (8 total) validates at or near the API boundary — zero exceptions. The most relevant one is Rust wgpu itself, which our library mirrors:

• wgpu (public) — thin ergonomic wrapper, minimal checks
• wgpu-core (middle) — exhaustive WebGPU spec validation
• wgpu-hal (bottom) — unsafe, assumes correct input, minimal validation

Their wiki explicitly says: "The responsibility for exhaustive validation always rests with wgpu-core, regardless of what may or may not be checked in wgpu-hal."

The reason is consistency across backends. When I audited our codebase, I found exactly this problem:

• Vulkan returns "vkCreateBuffer failed: -3" (opaque numeric code)
• Software backend performs zero validation on some operations (nil descriptor = panic, zero-size buffer = silent success)
• Same invalid input, completely different behavior per backend

This is what centralized validation in core prevents — consistent behavior and clear errors regardless of which backend is active.

The approach I'm thinking:

Three layers with clear responsibilities (matching Rust wgpu):

1. Public API (wgpu/) — nil/released checks, descriptor translation, error wrapping with "wgpu: " prefix. Thin. No spec logic here.
2. Core (core/) — WebGPU spec validation, state tracking, typed errors (CreateBufferError etc). This is where the real validation lives. Already started — CreateBufferError, EncoderStateError, ValidationError exist.
3. HAL (hal/) — hardware calls only. Defense-in-depth nil checks that log "BUG: reached HAL" (meaning core missed something). No user-facing validation.

The key insight: public API and backend validation serve different audiences. Public API catches "you passed nil" (developer mistake). Core catches "texture dimensions exceed device limits" (spec compliance). HAL catches "Vulkan returned VK_ERROR_OUT_OF_DEVICE_MEMORY" (hardware reality).

So it's not duplication — it's defense in depth with clear scope per layer.

Practical impact:

The audit found 5 methods where nil input causes a panic (CreateBindGroup with nil Layout, Queue.Submit with nil element, Surface.Configure/Present with nil args). These are the kind of things that core-level validation would catch consistently across all backends.

What do you think? Does this three-layer split make sense to you, or do you see potential issues with this approach? I'm genuinely curious if you'd push back on any of this — your contributor perspective is valuable since you're seeing the API from the outside.

[Carmen-Shannon]

The three layer split does make sense and is aligned with what I mentioned about having more error handling.

I can see how it's not duplication in practice and would actually help to see what layer is complaining.

[kolkov]

Thanks for confirming, really appreciate the back-and-forth on this!

So the plan: we'll adopt the three-layer validation model (public API → core → HAL) as the standard approach going forward. I'll create detailed kanban tasks for the implementation phases — this is something we want to have solid before v1.0.0, could start as early as the next release cycle.

Proper validation and error handling is foundational for a stable public API, so it makes sense to get it right before we lock things down for 1.0.

If you're interested in contributing to any of the validation work down the road, you'd be very welcome — you already have a good feel for the public API surface from your WriteTexture work.

[kolkov]

Completed in v0.20.0 (PR #100): core validation layer (VAL-001..004), 7 typed error types, deferred error pattern, HAL defense-in-depth, structured logging via log/slog.