Add support for SurrealDB v3 structured error handling

Introduce ServerError type for SurrealDB v3 structured errors (Kind,
Details, Cause) while preserving backward compatibility with the
existing RPCError and QueryError types.

```go
_, err := surrealdb.Select[map[string]any](context.Background(), db,
	models.Table("nonexistent_table_for_test"),
)

// Use ServerError on SurrealDB v3
var se surrealdb.ServerError
if errors.As(err, &se) {
	// Get access to new error fields like Kind, Details and Cause
}
```

Author: mumoshu

contrib/surrealrestore/restore_test.go

@@ -39,6 +39,16 @@ func TestRestorerFull(t *testing.T) {
 		t.Fatalf("Failed to init source db: %v", err)
 	}
 
+	// Check if this is SurrealDB 3.x - skip due to changefeed behavior changes
+	// This may be revisited once 3.0 GA is out and changefeed behavior is stable
+	v, vErr := testenv.GetVersion(ctx, sourceDB)
+	if vErr != nil {
+		t.Fatalf("Failed to get SurrealDB version: %v", vErr)
+	}
+	if v.IsV3OrLater() {
+		t.Skip("Skipping incremental dump/restore test on SurrealDB 3.x - changefeed behavior has changed significantly")
+	}
+
 	// Insert test data
 	type TestRecord struct {
 		ID   string `json:"id,omitempty"`

contrib/testenv/structured_errors_integration_test.go

@@ -0,0 +1,56 @@
+package surrealdb_test
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	surrealdb "github.com/surrealdb/surrealdb.go"
+	"github.com/surrealdb/surrealdb.go/contrib/testenv"
+	"github.com/surrealdb/surrealdb.go/pkg/models"
+)
+
+// ExampleUpsert_server_error demonstrates extracting a *ServerError from
+// an RPC error on SurrealDB v3 using errors.As.
+//
+// On SurrealDB v2, the error is still an *RPCError (backward compatible),
+// but errors.As(err, &se) also works because RPCError.Unwrap() returns
+// a *ServerError. On v2 servers, se.Kind will be empty.
+func ExampleUpsert_server_error() {
+	db := testenv.MustNew("surrealdbexamples", "server_error", "person")
+
+	type Person struct {
+		Name string `json:"name"`
+	}
+
+	if _, err := surrealdb.Query[any](
+		context.Background(),
+		db,
+		`DEFINE TABLE person SCHEMAFUL;
+		 DEFINE FIELD name ON person TYPE string;`,
+		nil,
+	); err != nil {
+		panic(err)
+	}
+
+	_, err := surrealdb.Upsert[Person](
+		context.Background(),
+		db,
+		models.Table("person"),
+		map[string]any{
+			"id":   models.NewRecordID("person", "a"),
+			"name": 123,
+		},
+	)
+	if err != nil {
+		// v2 backward compat: RPCError is still matchable
+		fmt.Printf("Error is RPCError: %v\n", errors.Is(err, &surrealdb.RPCError{}))
+
+		// v3 migration path: extract ServerError for structured info
+		fmt.Printf("Error is ServerError: %v\n", errors.Is(err, surrealdb.ServerError{}))
+	}
+
+	// Output:
+	// Error is RPCError: true
+	// Error is ServerError: true
+}

example_server_error_test.go

@@ -101,6 +101,7 @@ type StubResponse struct {
 	// Result is the successful RPCResponse result to return (mutually exclusive with Error)
 	Result any
 	// Error is the error to return (mutually exclusive with Result)
+	//nolint:staticcheck //v2 backward compat with RPCError
 	Error *connection.RPCError
 	// Failures defines failure injection configurations for this response
 	Failures []FailureConfig
@@ -567,6 +568,7 @@ func (h *Handler) sendResponse(socket *gws.Conn, id, result any) {
 func (h *Handler) sendError(socket *gws.Conn, id any, code int, message string) {
 	var resp connection.RPCResponse[any]
 	resp.ID = id
+	//nolint:staticcheck // intentionally testing v2 backward compat with RPCError
 	resp.Error = &connection.RPCError{
 		Code:    code,
 		Message: message,
@@ -630,6 +632,7 @@ func SimpleStubResponse(method string, response any) StubResponse {
 func ErrorStubResponse(method string, code int, message string) StubResponse {
 	return StubResponse{
 		Matcher: MatchMethod(method),
+		//nolint:staticcheck // v2 backward compat with RPCError
 		Error: &connection.RPCError{
 			Code:    code,
 			Message: message,

internal/fakesdb/server.go

@@ -147,6 +147,7 @@ func TestHandleResponse_ErrorWithoutID(t *testing.T) {
 	mockUnmarshal := &mockUnmarshaler{
 		unmarshalFunc: func(data []byte, v any) error {
 			if res, ok := v.(*connection.RPCResponse[cbor.RawMessage]); ok {
+				//nolint:staticcheck // v2 backward compat with RPCError
 				res.Error = &connection.RPCError{
 					Code:    -32600,
 					Message: "Invalid Request",

pkg/connection/gorillaws/connection_test.go

@@ -1,10 +1,70 @@
 package connection
 
-// RPCError represents a JSON-RPC error
+import (
+	"errors"
+	"reflect"
+
+	"github.com/fxamacker/cbor/v2"
+)
+
+// wireDecMode is a CBOR decode mode that decodes maps with string keys
+// to map[string]any instead of map[any]any. This ensures the Details field
+// in wireError is always map[string]any for consistent detail helper behavior.
+var wireDecMode cbor.DecMode
+
+//nolint:gochecknoinits // init is used to set up the CBOR decode mode for wireError
+func init() {
+	var err error
+	wireDecMode, err = cbor.DecOptions{
+		DefaultMapType: reflect.TypeOf(map[string]any(nil)),
+	}.DecMode()
+	if err != nil {
+		panic(err)
+	}
+}
+
+// RPCError represents a JSON-RPC error from the SurrealDB server.
+//
+// On SurrealDB v3 servers, use errors.As to extract a *ServerError for richer
+// structured error information (Kind, Details, Cause).
+//
+// Deprecated: Use [ServerError] instead on SurrealDB v3 for richer error information.
+// TODO(v2-compat): Remove in next major release.
 type RPCError struct {
-	Code        int    `json:"code"`
-	Message     string `json:"message,omitempty"`
+	// Code is the JSON-RPC numeric error code.
+	// SurrealDB v2 and v3: Always present for RPC-level errors.
+	Code int `json:"code"`
+
+	// Message is the error message from the server.
+	// SurrealDB v2 and v3: Always present.
+	Message string `json:"message,omitempty"`
+
+	// Description is a human-readable description of the error.
+	// SurrealDB v2 only: Not populated by v3 servers.
+	// Use ServerError on SurrealDB v3 instead.
+	//
+	// Deprecated: Not populated by SurrealDB v3 servers.
+	// TODO(v2-compat): Remove in next major release.
 	Description string `json:"description,omitempty"`
+
+	// wire stores the full deserialized error data (v2 and v3 fields).
+	// RPCError.As delegates to wireError.As for errors.As extraction of *ServerError.
+	wire *wireError
+}
+
+// UnmarshalCBOR deserializes the RPC error from CBOR.
+// It first deserializes into wireError (capturing all v2+v3 fields),
+// then populates the v2 public fields and creates a ServerError for the v3 view.
+func (r *RPCError) UnmarshalCBOR(data []byte) error {
+	w := &wireError{}
+	if err := wireDecMode.Unmarshal(data, w); err != nil {
+		return err
+	}
+	r.Code = w.Code
+	r.Message = w.Message
+	r.Description = w.Description
+	r.wire = w
+	return nil
 }
 
 func (r RPCError) Error() string {
@@ -15,12 +75,16 @@ func (r RPCError) Error() string {
 }
 
 func (r *RPCError) Is(target error) bool {
-	if target == nil {
-		return r == nil
+	switch target.(type) {
+	case RPCError, *RPCError, ServerError, *ServerError:
+		return true
+	default:
+		return false
 	}
+}
 
-	_, ok := target.(*RPCError)
-	return ok
+func (r *RPCError) As(err any) bool {
+	return errors.As(r.wire, err)
 }
 
 // RPCRequest represents an incoming JSON-RPC request.

pkg/connection/model.go

@@ -0,0 +1,70 @@
+package connection
+
+// ServerError represents a structured error from SurrealDB v3.
+// Only use this when you know you are running against a SurrealDB v3 server.
+//
+// Extract from RPC errors using errors.As:
+//
+//	var se *connection.ServerError
+//	if errors.As(err, &se) {
+//	    fmt.Println(se.Kind, se.Details)
+//	}
+//
+// ServerError carries structured information including Kind, Details, and a cause chain.
+// Use the helper functions in the surrealdb package (IsNotAllowed, IsNotFound, etc.)
+// for ergonomic kind checking, or inspect Kind directly.
+type ServerError struct {
+	// Code is the JSON-RPC numeric error code.
+	Code int
+
+	// Message is the error message.
+	Message string
+
+	// Kind is the structured error kind (e.g. "NotFound", "NotAllowed").
+	Kind string
+
+	// Details contains kind-specific structured error details.
+	// SurrealDB v3 only. nil for v2 servers.
+	//
+	// In SurrealDB v3, this follows the { "kind": "...", "details": ... } format (internally-tagged).
+	// In older versions, this may be a string (unit variants) or a map with the
+	// variant name as key (externally-tagged format).
+	Details any
+
+	// Cause is the underlying error in the cause chain.
+	Cause *ServerError
+}
+
+// Error implements the error interface.
+// When a cause chain is present, the messages are joined with ": ".
+func (e ServerError) Error() string {
+	if e.Cause == nil {
+		return e.Message
+	}
+	return e.Message + ": " + e.Cause.Error()
+}
+
+func (e ServerError) Is(target error) bool {
+	_, ok := target.(ServerError)
+	return ok
+}
+
+func (e *ServerError) As(err any) bool {
+	switch dst := err.(type) {
+	case *ServerError:
+		*dst = *e
+		return true
+	case **ServerError:
+		*dst = e
+		return true
+	default:
+		return false
+	}
+}
+
+// Unwrap implements the Go errors.Unwrap interface, enabling
+// errors.Unwrap(), errors.Is(), and errors.As() to traverse the
+// server error cause chain.
+func (e ServerError) Unwrap() error {
+	return e.Cause
+}

pkg/connection/server_error.go

@@ -0,0 +1,71 @@
+package connection
+
+import "errors"
+
+// wireError is an unexported deserialization target that captures ALL v2+v3 wire fields.
+// It is used as the intermediate representation during RPCError.UnmarshalCBOR,
+// before populating the v2 public fields on RPCError and creating a ServerError for the v3 view.
+type wireError struct {
+	Code        int        `json:"code"`
+	Message     string     `json:"message,omitempty"`
+	Description string     `json:"description,omitempty"` // SurrealDB v2 only
+	Kind        string     `json:"kind,omitempty"`        // SurrealDB v3 only
+	Details     any        `json:"details,omitempty"`     // SurrealDB v3 only
+	Cause       *wireError `json:"cause,omitempty"`       // SurrealDB v3 only
+}
+
+func (w *wireError) Error() string {
+	if w == nil {
+		return "<nil>"
+	}
+	return w.Message
+}
+
+func (r *wireError) As(err any) bool {
+	if r == nil {
+		return false
+	}
+	switch e := err.(type) {
+	case *ServerError:
+		e.Message = r.Message
+		e.Kind = r.Kind
+		e.Code = r.Code
+		e.Details = r.Details
+
+		var cause ServerError
+		if errors.As(r.Cause, &cause) {
+			e.Cause = &cause
+		}
+
+		return true
+	case **ServerError:
+		se := &ServerError{
+			Message: r.Message,
+			Kind:    r.Kind,
+			Code:    r.Code,
+			Details: r.Details,
+		}
+
+		var cause ServerError
+		if errors.As(r.Cause, &cause) {
+			se.Cause = &cause
+		}
+
+		*e = se
+		return true
+	case *RPCError:
+		e.Code = r.Code
+		e.Message = r.Message
+		e.Description = r.Description
+		return true
+	case **RPCError:
+		rpcErr := &RPCError{
+			Code:        r.Code,
+			Message:     r.Message,
+			Description: r.Description,
+		}
+		*e = rpcErr
+		return true
+	}
+	return false
+}