Refactor backend validation helpers into extensible S3 methods

[villegar]

Summary

{dsROCrate} currently mixes standalone backend-specific validation helpers with S3 methods.

As support for additional backends (e.g. Armadillo) is planned, it would be beneficial to standardise backend validation around a fully extensible S3 framework.

This would improve maintainability, reduce backend-specific branching and provide a cleaner abstraction layer for future backend integrations.

---

Current behaviour

Connection validation is currently implemented via a standalone Opal-specific helper:

validate_opal_con <- function(x) {
  tryCatch(
    {
      status <- xptr::is_null_xptr(x$handle$handle)

      if (status) {
        stop("The given connection is not valid!", call. = FALSE)
      }
    },
    error = function(e) {
      stop("The given connection is not valid!", call. = FALSE)
    }
  )
}

while permission validation already uses an S3 generic:

check_permissions <- function(x, ...) {
  UseMethod("check_permissions")
}

with backend-specific implementations such as:

check_permissions.opal <- function(x, ...) {
  ...
}

Typical validation flow currently looks like:

# validate connection object
validate_opal_con(x)

# validate backend permissions
check_permissions(x)

This works well for Opal, but may become harder to maintain as additional backend types are introduced.

---

Proposed enhancement

Refactor connection validation into an S3 generic framework.

For example:

validate_con <- function(x, ...) {
  UseMethod("validate_con")
}

with backend-specific methods such as:

validate_con.opal <- function(x, ...) {
  ...
}

and a default method:

validate_con.default <- function(x, ...) {
  stop(
    sprintf(
      "Unsupported connection type: %s",
      paste(class(x), collapse = ", ")
    ),
    call. = FALSE
  )
}

This would replace backend-specific standalone helpers such as validate_opal_con().

---

Unified validation helper

In addition, it may be useful to introduce a higher-level validation helper to orchestrate all backend validation checks in a single place.

For example:

validate_backend <- function(x, ...) {
  validate_con(x, ...)
  validate_backend_version(x, ...)
  check_permissions(x, ...)

  invisible(TRUE)
}

This would provide a single entry point for backend validation across the auditing suite while still preserving separation of concerns internally.

Audit entry points such as audit(), safe_data(), safe_people(), etc. could then consistently call:

validate_backend(x)

rather than manually coordinating multiple validation calls.

The backend version validation step would only apply where relevant and supported by the backend implementation.

---

Suggested validation structure

The current separation of concerns is already good conceptually:

1. connection validity
2. backend capability/version validation
3. permission validation

This issue proposes standardising the validation architecture around S3 methods while retaining these concerns as separate components internally.

---

Motivation

This refactor would provide:

• cleaner backend abstraction
• easier support for future backends such as Armadillo
• reduced backend-specific branching
• improved extensibility
• more consistent validation APIs
• centralised validation orchestration
• clearer separation between generic validation workflows and backend-specific implementations

---

Related issues

Backend version/capability validation is being discussed separately in:

• Issue Add Opal version validation helper when checking backend connections #22: Add Opal version validation helper when checking backend connections #22

[villegar]

Fixed in 444cec0