diff --git a/.Rbuildignore b/.Rbuildignore
index 7217209..82a4353 100644
--- a/.Rbuildignore
+++ b/.Rbuildignore
@@ -14,3 +14,6 @@
^CRAN-SUBMISSION$
^\.positai$
^\.claude$
+^sonar-fixes\.json$
+^quality\.html$
+^\.lintr$
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
new file mode 100644
index 0000000..5ace460
--- /dev/null
+++ b/.github/dependabot.yml
@@ -0,0 +1,6 @@
+version: 2
+updates:
+ - package-ecosystem: "github-actions"
+ directory: "/"
+ schedule:
+ interval: "weekly"
diff --git a/.github/workflows/lint.yaml b/.github/workflows/lint.yaml
new file mode 100644
index 0000000..325f974
--- /dev/null
+++ b/.github/workflows/lint.yaml
@@ -0,0 +1,31 @@
+# Workflow derived from https://github.com/r-lib/actions/tree/v2/examples
+# Need help debugging build failures? Start at https://github.com/r-lib/actions#where-to-find-help
+on:
+ push:
+ branches: [main, master]
+ pull_request:
+
+name: lint.yaml
+
+permissions: read-all
+
+jobs:
+ lint:
+ runs-on: ubuntu-latest
+ env:
+ GITHUB_PAT: ${{ secrets.GITHUB_TOKEN }}
+ steps:
+ - uses: actions/checkout@v6
+
+ - uses: r-lib/actions/setup-r@v2
+
+ - uses: r-lib/actions/setup-r-dependencies@v2
+ with:
+ extra-packages: any::lintr, local::.
+ needs: lint
+
+ - name: Lint
+ run: lintr::lint_package()
+ shell: Rscript {0}
+ env:
+ LINTR_ERROR_ON_LINT: true
diff --git a/.gitignore b/.gitignore
index 6899798..026b55f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -42,3 +42,6 @@ inst/R.ignore
cran-comments.md
CRAN-SUBMISSION
.positai
+docs
+sonar-fixes.json
+quality.html
diff --git a/.lintr b/.lintr
new file mode 100644
index 0000000..4810b0a
--- /dev/null
+++ b/.lintr
@@ -0,0 +1,7 @@
+linters: linters_with_defaults(
+ object_name_linter = lintr::object_name_linter(
+ styles = c("snake_case", "camelCase", "dotted.case"),
+ regexes = c("^[A-Z][[:alnum:]_]*$", "^@timestamp$", "%||%")
+ ))
+encoding: "UTF-8"
+exclusions: list("inst/R.ignore")
diff --git a/DESCRIPTION b/DESCRIPTION
index b4dcf73..e2c175e 100644
--- a/DESCRIPTION
+++ b/DESCRIPTION
@@ -1,6 +1,6 @@
Package: dsROCrate
Title: 'DataSHIELD' RO-Crate Governance Functions
-Version: 0.2.4
+Version: 0.2.4.9000
Authors@R: c(
person(given = "Roberto",
family = "Villegas-Diaz",
@@ -30,6 +30,7 @@ Suggests:
dsBaseClient,
DSI,
DSOpal,
+ DSMolgenisArmadillo,
fs,
knitr,
MolgenisArmadillo,
@@ -42,7 +43,6 @@ Roxygen: list(markdown = TRUE)
Imports:
digest,
dplyr,
- DSMolgenisArmadillo,
jsonlite,
opalr (>= 3.6.1),
purrr,
@@ -57,6 +57,6 @@ Imports:
Depends:
R (>= 4.1.0)
VignetteBuilder: knitr
-URL: https://github.com/FederatedMethods/dsROCrate
+URL: https://github.com/FederatedMethods/dsROCrate, https://federatedmethods.github.io/dsROCrate
BugReports: https://github.com/FederatedMethods/dsROCrate/issues
-Config/roxygen2/version: 8.1.0
+Config/roxygen2/version: 8.1.1
diff --git a/NAMESPACE b/NAMESPACE
index 753fa43..c4ea86b 100644
--- a/NAMESPACE
+++ b/NAMESPACE
@@ -2,6 +2,7 @@
S3method(as.data.frame,safe_call)
S3method(as.data.frame,symbol_registry)
+S3method(as_tibble,safe_symbol)
S3method(audit,ArmadilloCredentials)
S3method(audit,character)
S3method(audit,cr8tor)
@@ -12,12 +13,15 @@ S3method(audit,rocrate)
S3method(audit_engine,cr8tor)
S3method(audit_engine,default)
S3method(audit_engine,opal)
+S3method(backend_can_audit,opal)
S3method(backend_logs,opal)
+S3method(backend_name,opal)
S3method(backend_options,opal)
S3method(backend_packages,opal)
S3method(backend_profile_exists,opal)
S3method(backend_project,opal)
S3method(backend_project_exists,opal)
+S3method(backend_project_members,opal)
S3method(backend_project_perms,opal)
S3method(backend_projects,opal)
S3method(backend_resource_perms,opal)
@@ -27,18 +31,14 @@ S3method(backend_table_perms,opal)
S3method(backend_tables,opal)
S3method(backend_user_exists,opal)
S3method(backend_users,opal)
+S3method(backend_validated,opal)
S3method(check_permissions,ArmadilloCredentials)
S3method(check_permissions,default)
S3method(check_permissions,opal)
-S3method(extract_safe_data,opal)
S3method(extract_safe_data,rocrate)
-S3method(extract_safe_output,opal)
S3method(extract_safe_output,rocrate)
-S3method(extract_safe_people,opal)
S3method(extract_safe_people,rocrate)
-S3method(extract_safe_project,opal)
S3method(extract_safe_project,rocrate)
-S3method(extract_safe_setting,opal)
S3method(extract_safe_setting,rocrate)
S3method(filter_safe_people,opal)
S3method(flatten_safe_data,default)
@@ -54,8 +54,6 @@ S3method(flatten_safe_setting,rocrate)
S3method(init,ArmadilloCredentials)
S3method(init,opal)
S3method(init,rocrate)
-S3method(is_admin_con,opal)
-S3method(is_audit_con,opal)
S3method(parse_user_profiles,ArmadilloCredentials)
S3method(parse_user_profiles,opal)
S3method(print,cr8tor_bundle)
@@ -111,4 +109,5 @@ export(safe_people)
export(safe_project)
export(safe_setting)
importFrom(rocrateR,get_entity)
+importFrom(tibble,as_tibble)
importFrom(utils,write.csv)
diff --git a/NEWS.md b/NEWS.md
index c16ed78..88f9eb3 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -1,3 +1,58 @@
+# dsROCrate (development version)
+
+## Bug fixes
+
+* Restored the internal `%||%` helper, removed in 0.2.4. Base R only provides
+ `%||%` from 4.4.0, so the Opal workflow failed on R 4.1 to 4.3. Tables and
+ resources without a description get the fallback description again (it had
+ become an empty string).
+* Fixed `dateCreated`/`dateModified` of tables and resources being shifted by
+ the local UTC offset.
+* `dateModified` of the `safe_output()` entities is now a UTC string, and the
+ time stamps in the log file names use UTC.
+* `report()` for a list of RO-Crates failed when none of them had permissions on
+ the tables, and left the servers without permissions out of the overview when
+ others had some. These servers are now included, with an empty access level.
+* `report()` for a path to an RO-Crate (its directory or its
+ `ro-crate-metadata.json` file) now loads the files it references (e.g., the
+ logs and mappings), so the Safe Output details are included in the report.
+* `report()` for a list of RO-Crates now checks the file path like it does for a
+ single RO-Crate: it no longer overwrites an existing file unless
+ `overwrite = TRUE`. If the list has no names, the servers are named
+ `server_1`, `server_2`, etc.
+* The error shown when the directory of the report does not exist now has the
+ missing spaces in the suggested command.
+
+## Changes
+
+* Errors for unsupported classes and not yet implemented backends are now
+ consistent across `audit()`, `check_permissions()`, `init()`, `report()` and
+ the `safe_*()` functions.
+* `report()`: the date in the report header is now in UTC.
+* `report()` for a list of RO-Crates returns the Safe Project table as
+ `safe_project`, like it does for a single RO-Crate (`safe_project_tbl` is kept
+ for now). The unused `diag_width` and `diag_height` arguments were removed.
+
+## Internal Changes
+
+* The requests about a project (if it exists, and its tables and resources) are
+ made once and shared by `safe_project()` and `safe_data()` through the
+ RO-Crate, instead of once per function. For `init() |> safe_project() |>
+ safe_data()` this means 1 request to check the project (was 5) and 1 to list
+ its tables and resources (was 2 each). The shared requests last as long as the
+ RO-Crate: run `init()` again to refresh them.
+* Added `backend_can_audit()`, replacing `is_admin_con()` and `is_audit_con()`:
+ checking that a connection can audit now takes 1 request instead of 4.
+* `validate_backend()` skips the checks when the RO-Crate was already validated
+ for the same connection, so `audit()` and `init() |> safe_*()` validate once.
+* Added `backend_name()`, `set_crate_context()` and shared error helpers.
+* `report()` for a list of RO-Crates reuses the code of the report for a single
+ RO-Crate: the tables of each RO-Crate are extracted once (they used to be
+ extracted by a full report of each RO-Crate, which also built a diagram and
+ wrote a file each time), and the overview of the servers is the combination
+ of the overview of each RO-Crate. For a list of 2 RO-Crates, 1 diagram is
+ built (was 3) and 2 RO-Crates are written in the report (was 4).
+
# dsROCrate 0.2.4
## Bug fixes
diff --git a/R/audit.R b/R/audit.R
index 5da290e..ecb3de7 100644
--- a/R/audit.R
+++ b/R/audit.R
@@ -57,22 +57,17 @@ audit <- function(x, ...) {
#' @export
audit.default <- function(x, ...) {
- stop(
- sprintf(
- "No `audit()` method exists for objects of class: %s.",
- paste(class(x), collapse = ", ")
- ),
- call. = FALSE
+ s3_method_not_available(
+ "audit",
+ class = class(x),
+ hint = "Please provide a supported backend connection object."
)
}
#' @rdname audit
#' @export
audit.ArmadilloCredentials <- function(x, ..., intent = NULL) {
- stop(
- "The `audit()` for the Armadillo backend is not currently implemented!",
- call. = FALSE
- )
+ s3_method_not_implemented("audit", backend = "Armadillo")
}
#' @rdname audit
diff --git a/R/audit_engine.R b/R/audit_engine.R
index bed6794..77d069d 100644
--- a/R/audit_engine.R
+++ b/R/audit_engine.R
@@ -35,12 +35,10 @@ audit_engine <- function(x, ...) {
#' @export
audit_engine.default <- function(x, ...) {
- stop(
- sprintf(
- "No `audit_engine()` method exists for objects of class: %s.",
- paste(class(x), collapse = ", ")
- ),
- call. = FALSE
+ s3_method_not_available(
+ "audit_engine",
+ class = class(x),
+ hint = "Please provide a supported backend connection object."
)
}
diff --git a/R/backend-generic.R b/R/backend-generic.R
index d9873bf..a7c1c9c 100644
--- a/R/backend-generic.R
+++ b/R/backend-generic.R
@@ -1,7 +1,15 @@
+backend_can_audit <- function(x, ...) {
+ UseMethod("backend_can_audit")
+}
+
backend_logs <- function(x, ...) {
UseMethod("backend_logs")
}
+backend_name <- function(x, ...) {
+ UseMethod("backend_name")
+}
+
backend_options <- function(x, ...) {
UseMethod("backend_options")
}
@@ -22,6 +30,10 @@ backend_project_exists <- function(x, ...) {
UseMethod("backend_project_exists")
}
+backend_project_members <- function(x, ...) {
+ UseMethod("backend_project_members")
+}
+
backend_project_perms <- function(x, ...) {
UseMethod("backend_project_perms")
}
@@ -58,32 +70,8 @@ backend_users <- function(x, ...) {
UseMethod("backend_users")
}
-#' Verify if connection was created by an administrator user
-#'
-#' @inheritParams validate_con
-#' @param ... Unused, extra arguments.
-#'
-#' @returns Boolean flag to indicate whether the given connection was created
-#' by an administrator user.
-#' @keywords internal
-#'
-#' @noRd
-is_admin_con <- function(x, ...) {
- UseMethod("is_admin_con")
-}
-
-#' Verify if connection was created by an auditor user
-#'
-#' @inheritParams validate_con
-#' @param ... Unused, extra arguments.
-#'
-#' @returns Boolean flag to indicate whether the given connection was created
-#' by an auditor user.
-#' @keywords internal
-#'
-#' @noRd
-is_audit_con <- function(x, ...) {
- UseMethod("is_audit_con")
+backend_validated <- function(x, ...) {
+ UseMethod("backend_validated")
}
#' Validate backend version
diff --git a/R/backend-opal.R b/R/backend-opal.R
index 8d50199..78e5064 100644
--- a/R/backend-opal.R
+++ b/R/backend-opal.R
@@ -1,3 +1,20 @@
+#' @export
+backend_can_audit.opal <- function(x, ..., role = FALSE) {
+ res <- .try_load(backend_profile_exists(x, "default"))
+ out <- list(ok = !is.null(res$value), role = NA_character_, error = res$error)
+ # the extra probe is only needed to report the role
+ if (role && out$ok) {
+ out$role <- if (
+ is.null(.try_load(backend_user_exists(x, x$username))$error)
+ ) {
+ "administrator"
+ } else {
+ "auditor"
+ }
+ }
+ out
+}
+
#' @export
backend_logs.opal <- function(x, ...) {
logs <- suppressMessages(opalr::dsadmin.log(x, ...))
@@ -5,6 +22,11 @@ backend_logs.opal <- function(x, ...) {
logs
}
+#' @export
+backend_name.opal <- function(x, ...) {
+ "OBiBa's Opal"
+}
+
#' @export
backend_options.opal <- function(x, ...) {
opalr::dsadmin.get_options(x, ...)
@@ -30,6 +52,71 @@ backend_project_exists.opal <- function(x, ...) {
opalr::opal.project_exists(x, ...)
}
+#' @export
+backend_project_members.opal <- function(
+ x,
+ ...,
+ project,
+ tables = NULL,
+ resources = NULL,
+ permissions = NULL
+) {
+ # local bindings
+ permission <- subject <- type <- NULL
+
+ # `NULL` means all the assets of the project, an empty vector means none
+ if (is.null(tables)) {
+ tables <- get_project_assets(x, project, "tables")$name
+ }
+ if (is.null(resources)) {
+ resources <- get_project_assets(x, project, "resources")$name
+ }
+
+ # by default, the permissions are requested to the backend, a function can be
+ # given to retrieve them in another way (e.g., from a cache)
+ if (is.null(permissions)) {
+ permissions <- function(type, asset = NULL) {
+ switch(
+ type,
+ project = backend_project_perms(x, project),
+ table = backend_table_perms(x, project, asset),
+ resource = backend_resource_perms(x, project, asset)
+ )
+ }
+ }
+
+ project_level <- permissions("project") |>
+ dplyr::transmute(
+ subject,
+ type,
+ permission,
+ via = "project",
+ asset = NA_character_
+ )
+
+ asset_level <- function(assets, via) {
+ purrr::map(assets, \(a) {
+ p <- permissions(via, a)
+ if (length(p$subject)) {
+ tibble::tibble(
+ subject = p$subject,
+ type = p$type,
+ permission = p$permission,
+ via = via,
+ asset = a
+ )
+ }
+ }) |>
+ dplyr::bind_rows()
+ }
+
+ project_level |>
+ dplyr::bind_rows(
+ asset_level(tables, "table"),
+ asset_level(resources, "resource")
+ )
+}
+
#' @export
backend_project_perms.opal <- function(x, ...) {
opalr::opal.project_perm(x, ...)
@@ -76,38 +163,10 @@ backend_users.opal <- function(x, ...) {
}
#' @export
-is_admin_con.opal <- function(x, ...) {
- # condition 1: admin users have access to `backend_user_exists`
- cond1 <- .try_load(backend_user_exists(x, x$username))
- # condition 2: admin users have access to `backend_profile_exists`
- cond2 <- .try_load(backend_profile_exists(x, "default"))
-
- # check all the conditions are met
- result <- all(!is.null(cond1$value), !is.null(cond2$value))
- attr(result, "error") <- list(
- user_exists = cond1$error,
- profile_exists = cond2$error
- )
- result
-}
-
-#' @export
-is_audit_con.opal <- function(x, ...) {
- # condition 1: admin users have access to `backend_user_exists`
- cond1 <- .try_load(backend_user_exists(x, x$username))
- # condition 2: admin users have access to `backend_profile_exists`
- cond2 <- .try_load(backend_profile_exists(x, "default"))
-
- # check all the conditions are met
- # cond1 is met when the call *errored* (no admin access, as expected of
- # a pure auditor); cond2 is met when the call *succeeded* - the returned
- # values don't matter either way
- result <- all(!is.null(cond1$error), !is.null(cond2$value))
- attr(result, "error") <- list(
- user_exists = NULL, # an error here is expected/correct for an auditor,
- profile_exists = cond2$error
- )
- result
+backend_validated.opal <- function(x, ..., rocrate = NULL) {
+ # validate both the `backend_validated` flag and the connection object
+ isTRUE(attr(rocrate, "backend_validated")) &&
+ identical(x, attr(rocrate, "connection"))
}
#' @export
diff --git a/R/check_permissions.R b/R/check_permissions.R
index 603a70a..15e08ff 100644
--- a/R/check_permissions.R
+++ b/R/check_permissions.R
@@ -24,47 +24,26 @@ check_permissions <- function(x, ...) {
# @rdname check_permissions
#' @export
check_permissions.default <- function(x, ...) {
- stop(
- sprintf(
- paste0(
- "No `check_permissions()` method exists for objects of class: %s.\n",
- "Please provide a supported backend connection object."
- ),
- paste(class(x), collapse = ", ")
- ),
- call. = FALSE
+ s3_method_not_available(
+ "check_permissions",
+ class = class(x),
+ hint = "Please provide a supported backend connection object."
)
}
#' @rdname check_permissions
#' @export
check_permissions.ArmadilloCredentials <- function(x, ...) {
- stop(
- paste0(
- "`check_permissions()` for the Armadillo backend is ",
- "not currently implemented!"
- ),
- call. = FALSE
- )
+ s3_method_not_implemented("check_permissions", backend = "Armadillo")
}
#' @rdname check_permissions
#' @export
check_permissions.opal <- function(x, ..., verbose = FALSE) {
- is_admin <- FALSE
- is_audit <- FALSE
-
- is_admin <- tryCatch(
- is_admin_con(x),
- error = function(e) FALSE
- )
-
- is_audit <- tryCatch(
- is_audit_con(x),
- error = function(e) FALSE
- )
+ # check if the backend user has at least audit permissions
+ res <- backend_can_audit(x)
- if (isTRUE(is_admin) || isTRUE(is_audit)) {
+ if (isTRUE(res$ok)) {
if (verbose) {
message("You are ready to audit this system!")
}
diff --git a/R/dsROCrate.R b/R/dsROCrate.R
index 02620c4..6f9ce17 100644
--- a/R/dsROCrate.R
+++ b/R/dsROCrate.R
@@ -43,10 +43,7 @@ init <- function(x, ...) {
#' @rdname init
#' @export
init.ArmadilloCredentials <- function(x, ...) {
- stop(
- "`init()` for the Armadillo backend is not currently implemented!",
- call. = FALSE
- )
+ s3_method_not_implemented("init", backend = "Armadillo")
}
#' @rdname init
@@ -63,18 +60,23 @@ init.opal <- function(
user = NULL
) {
# validate backend
- validate_backend(x, ...)
+ validate_backend(x, ..., rocrate = rocrate)
- # attach input arguments as attributes
- attr(rocrate, "connection") <- x
- attr(rocrate, "path") <- path
- attr(rocrate, "profile") <- profile
- attr(rocrate, "project") <- project
- attr(rocrate, "resources") <- resources
- attr(rocrate, "tables") <- tables
- attr(rocrate, "user") <- user
+ # attach input arguments as attributes (and discard any shared requests)
+ rocrate <- rocrate |>
+ reset_project_context() |>
+ set_crate_context(
+ connection = x,
+ path = path,
+ profile = profile,
+ project = project,
+ resources = resources,
+ tables = tables,
+ user = user,
+ validated = TRUE
+ )
- return(rocrate)
+ rocrate
}
#' @rdname init
@@ -82,13 +84,13 @@ init.opal <- function(
init.rocrate <- function(
x,
...,
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables"),
- user = attr(x, "user")
+ connection = get_crate_context(x, "connection"),
+ path = get_crate_context(x, "path"),
+ profile = get_crate_context(x, "profile"),
+ project = get_crate_context(x, "project"),
+ resources = get_crate_context(x, "resources"),
+ tables = get_crate_context(x, "tables"),
+ user = get_crate_context(x, "user")
) {
init(
connection,
diff --git a/R/report.R b/R/report.R
index 50d4c02..9c75d76 100644
--- a/R/report.R
+++ b/R/report.R
@@ -12,10 +12,7 @@ report <- function(x, ...) {
#' @rdname report
#' @export
report.ArmadilloCredentials <- function(x, ...) {
- stop(
- "The `report()` for the Armadillo backend is not currently implemented!",
- call. = FALSE
- )
+ s3_method_not_implemented("report", backend = "Armadillo")
}
#' @rdname report
@@ -30,12 +27,11 @@ report.character <- function(
overwrite = FALSE,
include_user_perm = TRUE,
diag_title = "DataSHIELD server",
- diag_width = NULL,
- diag_height = NULL,
max_line_length = 200
) {
- # attempt loading the RO-Crate
- rocrate <- rocrateR::load_rocrate(x)
+ # attempt loading the RO-Crate and set the Crate context
+ rocrate <- rocrateR::load_rocrate(x) |>
+ set_crate_context(path = .crate_root(x))
# call the next generic method
rocrate |>
@@ -47,8 +43,6 @@ report.character <- function(
overwrite = overwrite,
include_user_perm = include_user_perm,
diag_title = diag_title,
- diag_width = diag_width,
- diag_height = diag_height,
max_line_length = max_line_length,
...
)
@@ -57,9 +51,10 @@ report.character <- function(
# @rdname report
#' @export
report.default <- function(x, ...) {
- stop(
- "Unknown class, please try either a file path or",
- " an object with `rocrate` class!"
+ s3_method_not_available(
+ "report",
+ class = class(x),
+ hint = "Please try either a file path or an object with `rocrate` class."
)
}
@@ -75,214 +70,48 @@ report.list <- function(
overwrite = FALSE,
include_user_perm = TRUE,
diag_title = "DataSHIELD server",
- diag_width = NULL,
- diag_height = NULL,
max_line_length = 200
) {
- # local bindings
- asset <- id <- name <- permission <- project <- server <- user <- NULL
-
# validate that all the objects in the list, `x`, are valid RO-Crates
sapply(x, rocrateR::is_rocrate)
- # generate individual reports for each RO-Crate
- report_outputs <- lapply(
- x,
- report,
- title = title,
- filepath = filepath,
- render = FALSE,
- doc_format = doc_format,
- overwrite = TRUE,
- include_user_perm = include_user_perm,
- diag_title = diag_title,
- diag_width = diag_width,
- diag_height = diag_height
- )
-
- # combine reports ----
- ## Safe People
- safe_people_all <- .extract_srvr_comp(report_outputs, "safe_people")
- ## Safe Data
- safe_data_all <- .extract_srvr_comp(report_outputs, "safe_data")
- ## Safe Projects
- safe_project_all <- .extract_srvr_comp(report_outputs, "safe_project")
- ## Safe Settings
- safe_setting_all <- .extract_srvr_comp(report_outputs, "safe_setting")
- ## Safe Outputs
- safe_output_all <- .extract_srvr_comp(report_outputs, "safe_output")
- ## Safe Data permissions (optional)
- safe_data_permissions_all <- report_outputs |>
- .extract_srvr_comp("safe_data_permissions")
-
- ## overview table ----
- overview_data_all <- tibble::tibble()
- ## combine aggregated data to generate new overview table
- safe_project_data_all <- safe_project_all #|>
- # dplyr::rename(asset = asset_name)
-
- # if data permissions were found, then combine with project-data details and
- # generate new overview table
- if (!is.null(safe_data_permissions_all)) {
- overview_data_all <- safe_data_permissions_all |>
- dplyr::left_join(safe_people_all, by = c("person_id", "server")) |>
- dplyr::left_join(safe_project_data_all, by = c("asset_id", "server")) |>
- dplyr::select(server, project, asset, permission, user = name)
+ # ensure the given file path is valid
+ .validate_report_path(filepath, overwrite)
- # if any Safe Outputs were found in the inputs, include in the overview
- if (!is.null(safe_output_all) && nrow(safe_output_all)) {
- overview_data_all <- overview_data_all |>
- dplyr::left_join(
- safe_output_all,
- by = c("server", "project", "asset", "user")
- )
- }
- } else {
- # extract previous overview table
- overview_data_all <- tryCatch(
- {
- report_outputs |>
- # extract each component per server
- lapply(getElement, name = "overview_data") |>
- # attach the server name as a new column
- purrr::imap(~ dplyr::mutate(.x, server = .y)) |>
- # combine rows
- dplyr::bind_rows()
- },
- error = function(e) {
- NULL
- }
- )
+ # the names of the list are used as the names of the servers
+ if (is.null(names(x))) {
+ names(x) <- paste0("server_", seq_along(x))
}
- ## overview diagram ----
- overview_lst <- overview_data_all |>
- dplyr::rename(name = user) |>
- .overview_diagram(
- include_user_perm,
- filepath,
- render,
- diag_title,
- diag_width,
- diag_height
- )
-
- ## create tidy overview table ----
- tidy_overview_tbl <- overview_data_all |>
- dplyr::rename(name = user) |>
- .tidy_overview(include_user_perm = include_user_perm)
+ # extract the tables from each RO-Crate (and load their contents)
+ crate_tables <- lapply(x, .report_tables)
- ## create markdown report ----
- ## header and overview table
- report_contents <- c(
- .markdown_report_header(title, overview_data_all, overview_lst$diag_path),
- tidy_overview_tbl |>
- # # tidy up duplicated values in `project` and `asset`
- # dplyr::mutate(
- # Project = unfill_vec(Project),
- # Data = unfill_vec(Data)
- # ) |>
- dplyr::distinct() |>
- knitr::kable() |>
- paste0(collapse = "\n")
- )
+ # combine the tables of the RO-Crates (one per server)
+ combined_tables <- .combine_report_tables(crate_tables)
- ## attach entities for 5 safes
- report_contents <- .markdown_report_body(
- report_contents = report_contents,
- overview_tbl = overview_data_all,
- safe_people_tbl = safe_people_all,
- safe_project_tbl = safe_project_all,
- safe_data_tbl = safe_data_all,
- safe_user_perm_tbl = safe_data_permissions_all,
- safe_setting_tbl = safe_setting_all,
- safe_output_tbl = safe_output_all,
+ res <- .generate_report(
+ overview_tbl = combined_tables$overview_tbl,
+ safe_people_tbl = combined_tables$safe_people,
+ safe_project_tbl = combined_tables$safe_project,
+ safe_data_tbl = combined_tables$safe_data,
+ safe_user_perm_tbl = combined_tables$safe_data_permissions,
+ safe_setting_tbl = combined_tables$safe_setting,
+ safe_output_tbl = combined_tables$safe_output,
+ rocrates = lapply(crate_tables, getElement, name = "rocrate"),
+ title = title,
+ filepath = filepath,
+ render = render,
+ doc_format = doc_format,
+ overwrite = overwrite,
+ include_user_perm = include_user_perm,
+ diag_title = diag_title,
+ max_line_length = max_line_length,
break_by = "server"
)
- report_contents <- c(report_contents, "\n
\n")
-
- ## append RO-Crates ----
- for (i in seq_along(x)) {
- # extract current RO-Crate
- rocrate <- x[i][[1]]
- # check if the input object has a `path` attribute
- if (!is.null(attr(rocrate, "path"))) {
- # check if any of the entities with `@type = 'File'` have empty `content`
- rocrate <- rocrate |>
- load_content(roc_path = attr(rocrate, "path"))
- }
-
- report_contents <- .markdown_report_rocrate(
- report_contents = report_contents,
- rocrate = rocrate,
- section_txt = ifelse(
- i == 1,
- paste0("## RO-Crates\n### '", names(x)[i], "' server"),
- paste0("### '", names(x)[i], "' server")
- ),
- max_line_length = max_line_length
- )
- }
-
- ## write contents inside file
- ### delete previous version
- if (overwrite) {
- unlink(filepath, recursive = TRUE, force = TRUE)
- }
- writeLines(report_contents, filepath)
-
- ## render document
- if (render) {
- if (tolower(doc_format) %in% c("html", "html_document")) {
- suppressWarnings({
- rmarkdown::render(
- filepath,
- "html_document",
- sub(".md$", ".html", filepath)
- )
- utils::browseURL(paste0("file://", sub(".md$", ".html", filepath)))
- })
- } else if (tolower(doc_format) %in% c("pdf", "pdf_document")) {
- suppressWarnings({
- rmarkdown::render(
- filepath,
- "pdf_document",
- sub(".md$", ".pdf", filepath)
- )
- utils::browseURL(paste0("file://", sub(".md$", ".pdf", filepath)))
- })
- } else {
- stop("The format `", doc_format, "` is not valid! Try 'html' or 'pdf'.")
- }
- } else {
- return(invisible(
- list(
- overview_diagram = overview_lst$diag_lst,
- overview_data = tidy_overview_tbl,
- safe_people = safe_people_all,
- safe_project_tbl = safe_project_all,
- safe_data = safe_data_all,
- safe_data_permissions = safe_data_permissions_all,
- safe_setting = safe_setting_all,
- safe_output = safe_output_all
- )
- ))
- }
-
- message("A report has been written to:\n ", filepath)
-
- # return list of data frames with Safe People, Projects, Data, etc.
- invisible(
- list(
- safe_people = safe_people_all,
- safe_project_tbl = safe_project_all,
- safe_data = safe_data_all,
- safe_data_permissions = safe_data_permissions_all,
- safe_setting = safe_setting_all,
- safe_output = safe_output_all
- )
- )
+ # `safe_project_tbl` was the name used by previous versions
+ res$safe_project_tbl <- res$safe_project
+ invisible(res)
}
#' @param title String with title for the report (default: 'DataSHIELD Report').
@@ -296,10 +125,6 @@ report.list <- function(
#' permissions in the report overview's diagram.
#' @param diag_title String with title for the 'root' of the diagram (default:
#' 'DataSHIELD server').
-#' @param diag_width Numeric value with width (in inches) for the report
-#' overview's diagram (default: `NULL`, estimated based on number of nodes).
-#' @param diag_height Numeric value with height (in inches) for the report
-#' overview's diagram (default: `NULL`, estimated based on number of nodes).
#' @param max_line_length Integer with the maximum number of characters per line
#' in the RO-Crate to be printed in the report.
#' @rdname report
@@ -314,821 +139,34 @@ report.rocrate <- function(
overwrite = FALSE,
include_user_perm = TRUE,
diag_title = "DataSHIELD server",
- diag_width = NULL,
- diag_height = NULL,
max_line_length = 200
) {
- # local bindings ----
- actionStatus <- asset <- asset_id <- description <- fx <- NULL
- encodingFormat <- id <- name <- permission <- perm_id <- project <- NULL
- table_name <- timestamp <- type <- person_id <- user <- NULL
-
- # validate RO-Crate ----
+ # validate RO-Crate
rocrateR::is_rocrate(x)
- # ensure the given file path exists
- if (!dir.exists(dirname(filepath))) {
- stop(
- "The given file path directory does not exist. Try running the following",
- "command first:\n\t`mkdir -p",
- dirname(filepath),
- "`",
- call. = FALSE
- )
- }
-
- # check if the filepath points to an existing file
- if (file.exists(filepath)) {
- if (!overwrite) {
- stop(
- "The given file path points to an existing file. Try setting ",
- "`overwrite = TRUE` or changing the file path!",
- call. = FALSE
- )
- }
- }
-
- # check if the input object has a `path` attribute
- if (!is.null(attr(x, "path"))) {
- # check if any of the entities with `@type = 'File'` have empty `content`
- x <- x |>
- load_content(roc_path = attr(x, "path"))
- }
-
- # pre-processing ----
- ## Safe People ----
- # attempt to extract Safe People details
- safe_people_rocrate <- tryCatch(
- {
- extract_safe_people(x)
- },
- error = function(e) {
- NULL
- }
- )
-
- ## Safe Data ----
- # attempt to extract Safe Data details
- safe_data_rocrate <- tryCatch(
- {
- extract_safe_data(x)
- },
- error = function(e) {
- NULL
- }
- )
-
- # attempt to extract user permission entities
- user_perm_entity_lst <- tryCatch(
- {
- .get_entity(
- x,
- type = c("ReadAction", "WriteAction", "ControlAction")
- )
- },
- error = function(e) {
- NULL
- }
- )
-
- ## Safe Projects ----
- # extract project IDs from the Safe People RO-Crate
- member_of <- tryCatch(
- {
- safe_people_rocrate |>
- .get_entity(type = "Person") |>
- sapply(\(x) getElement(x, "memberOf")) |>
- unlist()
- },
- error = function(e) {
- NULL
- }
- )
-
- # attempt to extract Safe Project details
- safe_project_rocrate <- tryCatch(
- {
- extract_safe_project(x, id = member_of)
- },
- error = function(e) {
- NULL
- }
- )
-
- ## Safe Settings ----
- # attempt to extract Safe Setting details
- safe_setting_rocrate <- tryCatch(
- {
- extract_safe_setting(x)
- },
- error = function(e) {
- NULL
- }
- )
-
- ## Safe Outputs ----
- # attempt to extract Safe Output details
- safe_outputs_rocrate <- tryCatch(
- {
- extract_safe_output(x)
- },
- error = function(e) {
- NULL
- }
- )
-
- # verify contents of RO-Crate ----
- has_project_ents <- !is.null(safe_project_rocrate)
- has_data_ents <- !is.null(safe_data_rocrate)
- has_people_ents <- !is.null(safe_people_rocrate)
-
- # if not all these flags are `TRUE`, return error message
- if (!all(has_project_ents, has_data_ents, has_people_ents)) {
- stop(
- paste0(
- "The given RO-Crate is missing the following:",
- ifelse(has_project_ents, "", " - Project entity (`@type = 'Project'`)"),
- ifelse(has_data_ents, "", " - Data entity (`@type = 'Dataset'`)"),
- ifelse(has_people_ents, "", " - People entity (`type = 'Person'`)"),
- collapse = "\n"
- ),
- call. = FALSE
- )
- }
-
- # create overview ----
- overview_tbl <- tibble::tibble()
- ### extract (if available) table with user permissions
- user_perm_tbl <- flatten_user_perm_entity(user_perm_entity_lst)
- ### extract table with Safe People details
- safe_people_tbl <- flatten_safe_people(safe_people_rocrate)
- ### extract table with Safe Project details
- safe_project_tbl <- flatten_safe_project(safe_project_rocrate)
- ### extract table with Safe Data details
- safe_data_tbl <- flatten_safe_data(safe_data_rocrate)
- if (!is.null(user_perm_tbl) && nrow(user_perm_tbl) > 0) {
- overview_tbl <- user_perm_tbl |>
- # combine with Safe People details
- dplyr::left_join(safe_people_tbl, by = "person_id") |>
- # subset columns of interest
- dplyr::select(perm_id, person_id, name, asset_id, permission) |>
- # combine with Safe Data details
- dplyr::left_join(safe_data_tbl, by = "asset_id") |>
- # combine with Safe Project details
- dplyr::left_join(safe_project_tbl, by = c("asset_id", "asset")) #|>
- # # drop unused columns
- # dplyr::select(-id, -person_id, -asset_id, -type) |>
- # dplyr::rename(asset = asset_name)
- } else {
- overview_tbl <- flatten_safe_people(safe_people_rocrate) |>
- purrr::pmap(function(person_id, name, ...) {
- tibble::tibble(person_id, name) |>
- dplyr::bind_cols(flatten_safe_project(safe_project_rocrate))
- }) |>
- purrr::list_c()
- }
-
- # attempt extracting list of functions executed by the users from Safe Outputs
- safe_output_tbl <- flatten_safe_output(safe_outputs_rocrate) |>
- # extract only entities with mappings and functions, stored in CSV format
- dplyr::filter(encodingFormat == "text/csv") |>
- # extract content
- purrr::pluck("content", .default = list()) |>
- purrr::list_flatten() |>
- purrr::map(tibble::as_tibble) |>
- purrr::list_rbind()
-
- # initialise safe_output_tbl_v2, to be included in the returned outputs
- safe_output_tbl_v2 <- tibble::tibble()
-
- if (!is.null(safe_output_tbl) && nrow(safe_output_tbl) > 0) {
- # split `asset` into `project` and `asset`
- safe_output_tbl_v2 <- safe_output_tbl |>
- dplyr::mutate(
- project = gsub("(?=\\.).*$", "", asset, perl = TRUE),
- asset = gsub("^.*(?<=\\.)", "", asset, perl = TRUE)
- ) |>
- dplyr::distinct(project, asset, user, fx, timestamp)
-
- # append the list of functions to the overview table
- overview_tbl <- overview_tbl |>
- dplyr::left_join(
- safe_output_tbl_v2,
- by = c("project" = "project", "asset" = "asset", "name" = "user")
- ) |>
- # replace 'NA' in fx & timestamp with empty string
- dplyr::mutate(
- timestamp = dplyr::case_when(is.na(timestamp) ~ "", TRUE ~ timestamp),
- fx = dplyr::case_when(is.na(fx) ~ "", TRUE ~ fx)
- )
- }
-
- # overview diagram ----
- overview_lst <- .overview_diagram(
- overview_tbl,
- include_user_perm,
- filepath,
- render,
- diag_title,
- diag_width,
- diag_height
- )
-
- # create tidy overview table ----
- tidy_overview_tbl <- .tidy_overview(overview_tbl, include_user_perm)
-
- # create markdown report ----
- ## header and overview table
- report_contents <- c(
- .markdown_report_header(title, overview_tbl, overview_lst$diag_path),
- tidy_overview_tbl |>
- # # tidy up duplicated values in `project` and `asset`
- # dplyr::mutate(
- # Project = unfill_vec(Project),
- # Data = unfill_vec(Data)
- # ) |>
- dplyr::distinct() |>
- knitr::kable() |>
- paste0(collapse = "\n")
- )
-
- ## attach entities for 5 safes
- report_contents <- .markdown_report_body(
- report_contents = report_contents,
- overview_tbl = overview_tbl,
- safe_people_tbl = flatten_safe_people(safe_people_rocrate),
- safe_project_tbl = flatten_safe_project(safe_project_rocrate),
- safe_data_tbl = flatten_safe_data(safe_data_rocrate),
- safe_user_perm_tbl = flatten_user_perm_entity(user_perm_entity_lst),
- safe_setting_tbl = flatten_safe_setting(safe_setting_rocrate),
- safe_output_tbl = safe_output_tbl_v2
- )
-
- report_contents <- c(report_contents, "\n
\n")
-
- # append input RO-Crate ----
- report_contents <- .markdown_report_rocrate(
- report_contents = report_contents,
- rocrate = x,
- section_txt = "## RO-Crate",
- max_line_length = max_line_length
- )
-
- ## write contents inside file
- ### delete previous version
- if (overwrite) {
- unlink(filepath, recursive = TRUE, force = TRUE)
- }
- writeLines(report_contents, filepath)
-
- ## render document
- if (render) {
- if (tolower(doc_format) %in% c("html", "html_document")) {
- suppressWarnings({
- rmarkdown::render(
- filepath,
- "html_document",
- sub(".md$", ".html", filepath)
- )
- utils::browseURL(paste0("file://", sub(".md$", ".html", filepath)))
- })
- } else if (tolower(doc_format) %in% c("pdf", "pdf_document")) {
- suppressWarnings({
- rmarkdown::render(
- filepath,
- "pdf_document",
- sub(".md$", ".pdf", filepath)
- )
- utils::browseURL(paste0("file://", sub(".md$", ".pdf", filepath)))
- })
- } else {
- stop("The format `", doc_format, "` is not valid! Try 'html' or 'pdf'.")
- }
- } else {
- return(invisible(
- list(
- overview_diagram = overview_lst$diag_lst,
- overview_data = tidy_overview_tbl,
- safe_people = flatten_safe_people(safe_people_rocrate),
- safe_project = flatten_safe_project(safe_project_rocrate),
- safe_data = flatten_safe_data(safe_data_rocrate),
- safe_data_permissions = flatten_user_perm_entity(user_perm_entity_lst),
- safe_setting = flatten_safe_setting(safe_setting_rocrate),
- safe_output = safe_output_tbl_v2
- )
- ))
- }
-
- message("A report has been written to:\n ", filepath)
-
- # return list of data frames with Safe People, Projects, Data, etc.
- invisible(
- list(
- safe_people = flatten_safe_people(safe_people_rocrate),
- safe_project = flatten_safe_project(safe_project_rocrate),
- safe_data = flatten_safe_data(safe_data_rocrate),
- safe_data_permissions = flatten_user_perm_entity(user_perm_entity_lst),
- safe_setting = flatten_safe_setting(safe_setting_rocrate),
- safe_output = safe_output_tbl_v2
- )
- )
-}
-
-.extract_srvr_comp <- function(x, component) {
- tryCatch(
- {
- x |>
- # extract each component per server
- purrr::map(component) |>
- # lapply(getElement, name = component) |>
- # filter out NULL elements
- purrr::keep(\(x) !is.null(x)) |>
- # attach the server name as a new column
- purrr::imap(~ dplyr::mutate(.x, server = .y)) |>
- # combine rows
- dplyr::bind_rows()
- },
- error = function(e) {
- NULL
- }
- )
-}
-
-#' Create diagram for RO-Crate overview
-#'
-#' @param overview_tbl Data frame with overview details for the RO-Crate.
-#' @inheritParams report
-#'
-#' @returns Diagram object
-#' @keywords internal
-#' @noRd
-.overview_diagram <- function(
- overview_tbl,
- include_user_perm,
- filepath,
- render,
- diag_title,
- diag_width,
- diag_height
-) {
- # local bindings
- fx <- name <- permission <- project <- asset <- NULL
-
- ## initialise `vars` and `labelvar`
- vars <- c("project", "asset")
- labelvar <- c(project = "Project", asset = "Data")
-
- # check if `overview_tbl` has `permission` field AND include_user_perm = TRUE
- if ("permission" %in% colnames(overview_tbl) && include_user_perm) {
- vars <- c(vars, "permission")
- labelvar <- c(labelvar, permission = "Access Level")
- }
-
- # attach name/user and label it 'People'
- vars <- c(vars, "name")
- labelvar <- c(labelvar, name = "People")
-
- # check if `overview_tbl` has a `fx` field
- if ("fx" %in% colnames(overview_tbl)) {
- vars <- c(vars, "fx")
- labelvar <- c(labelvar, fx = "Function")
-
- # replace 'NA' with empty string for `fx`
- overview_tbl <- overview_tbl |>
- dplyr::mutate(fx = ifelse(is.na(fx), "", fx))
- }
-
- # attach 'server' if found in `overview_tbl`
- if ("server" %in% colnames(overview_tbl)) {
- vars <- c("server", vars)
- labelvar <- c(server = "Server", labelvar)
- }
-
- # aggregate the data if `permission` exists in `overview_tbl`
- if ("permission" %in% colnames(overview_tbl)) {
- overview_agg <- overview_tbl |>
- dplyr::group_by(dplyr::pick(vars[vars != "permission"])) |>
- dplyr::reframe(
- permission = paste0(unique(permission), collapse = " & "),
- )
- } else {
- overview_agg <- overview_tbl
- }
-
- ## generate diagram
- diagram_lst <- overview_agg |>
- vtree::vtree(
- vars = vars,
- labelvar = labelvar,
- showpct = FALSE,
- showcount = FALSE,
- horiz = FALSE,
- varnamebold = TRUE,
- splitwidth = 1,
- vsplitwidth = 1,
- folder = dirname(filepath),
- title = diag_title,
- # imageFileOnly = render,
- pngknit = render,
- # pxheight = min(80 * nrow(overview_tbl), 500),
- # pxwidth = 200 * nrow(overview_tbl),
- prune = list(fx = "")
- )
-
- ## if `render = TRUE`, then render diagram as PNG
- diagram_filepath <- NULL
- ### estimate number of nodes
- dot <- diagram_lst$x$diagram
- nodes <- dot |>
- gregexpr(pattern = "Node_[A-Za-z0-9_]+", perl = TRUE) |>
- (\(.) regmatches(dot, .))() |>
- unlist() |>
- unique()
- num_nodes <- length(nodes)
- ### scale width/height based on nodes
- scale_factor <- 0.5 # inches per node
- if (is.null(diag_width)) {
- width <- max(12, num_nodes * scale_factor)
- } else {
- width <- diag_width
- }
- if (is.null(diag_height)) {
- height <- max(6, num_nodes * scale_factor)
- } else {
- height <- diag_height
- }
- if (render) {
- diagram_filepath <- diagram_lst |>
- vtree::grVizToImageFile(
- folder = dirname(filepath),
- filename = gsub("md$", "png", basename(filepath))
- )
- }
-
- # # find path to latest PNG generated with `vtree`
- # diagram_filepath <- list.files(dirname(filepath), "^vtree")
- # diagram_filepath <- diagram_filepath[length(diagram_filepath)]
-
- return(list(diag_lst = diagram_lst, diag_path = diagram_filepath))
-}
-
-#' Create tidy version of the overview table
-#'
-#' @inheritParams .overview_diagram
-#'
-#' @returns Data frame with tidy overview table.
-#' @keywords internal
-#' @noRd
-.tidy_overview <- function(overview_tbl, include_user_perm) {
- # local bindings
- fx <- permission <- timestamp <- NULL
-
- ## initialise `vars` and `varslab`
- vars <- c("project", "asset")
- varslab <- c("Project" = "project", "Data" = "asset")
-
- # check if `overview_tbl` has `permission` field AND include_user_perm = TRUE
- if ("permission" %in% colnames(overview_tbl) && include_user_perm) {
- vars <- c(vars, "permission")
- varslab <- c(varslab, "Access Level" = "permission")
- }
-
- # attach name/user and label it 'People'
- vars <- c(vars, "name")
- varslab <- c(varslab, "People" = "name")
-
- # check if `overview_tbl` has a `fx` field
- if ("fx" %in% colnames(overview_tbl)) {
- vars <- c(vars, "fx", "timestamp")
- varslab <- c(
- varslab,
- "Function" = "fx",
- "Timestamp" = "timestamp"
- )
-
- # replace 'NA' with empty string for `fx` and `timestamp`
- overview_tbl <- overview_tbl |>
- dplyr::mutate(
- fx = ifelse(is.na(fx), "", fx),
- timestamp = ifelse(is.na(timestamp), "", timestamp)
- )
- }
-
- # attach 'server' if found in `overview_tbl`
- if ("server" %in% colnames(overview_tbl)) {
- vars <- c("server", vars)
- varslab <- c("Server" = "server", varslab)
- }
-
- # create tidy data frame
- tidy_overview_tbl <- overview_tbl |>
- dplyr::distinct(dplyr::pick(dplyr::all_of(vars)))
-
- if ("permission" %in% colnames(overview_tbl)) {
- if ("fx" %in% colnames(overview_tbl)) {
- vars_agg <- vars[!vars %in% c("permission", "fx", "timestamp")]
- tidy_overview_tbl <- tidy_overview_tbl |>
- dplyr::group_by(dplyr::pick(vars_agg)) |>
- dplyr::reframe(
- permission = paste0(unique(permission), collapse = " & "),
- fx = fx,
- timestamp = timestamp,
- .groups = "drop"
- )
- } else {
- tidy_overview_tbl <- tidy_overview_tbl |>
- dplyr::group_by(dplyr::pick(vars[vars != "permission"])) |>
- dplyr::reframe(
- permission = paste0(unique(permission), collapse = " & ")
- )
- }
- }
-
- tidy_overview_tbl <- tidy_overview_tbl |>
- dplyr::select(dplyr::all_of(varslab)) |>
- dplyr::distinct()
-
- return(tidy_overview_tbl)
-}
-
-
-#' Generate Markdown report's header
-#'
-#' @inheritParams .overview_diagram
-#' @inheritParams report
-#'
-#' @returns String with report's header
-#' @keywords internal
-#' @noRd
-.markdown_report_header <- function(title, overview_tbl, diagram_filepath) {
- # initialise variables for the report header
- unique_users_vct <- unique(c(
- getElement(overview_tbl, "name"),
- getElement(overview_tbl, "user")
- ))
- unique_project_vct <- unique(getElement(overview_tbl, "project"))
- unique_servers_vct <- unique(getElement(overview_tbl, "server"))
- ## initialise markdown header (see https://rmarkdown.rstudio.com/lesson-9.html)
- paste0(
- "---\n",
- paste0("title: ", title),
- "\noutput:\n",
- " pdf_document:\n",
- " df_print: kable\n",
- " highlight: tango\n",
- " html_document: default\n",
- "fontsize: 11pt\n",
- "geometry:\n",
- " - margin=.5in\n",
- " - landscape\n",
- "header-includes: \n",
- " - \\usepackage{array}\n",
- " - \\usepackage{longtable}\n",
- " - \\usepackage{xurl}\n",
- " - \\usepackage{hyphenat}\n",
- " - \\usepackage{microtype}\n",
- " - \\sloppy\n",
- " - \\setlength{\\emergencystretch}{3em}\n",
- " - \\usepackage{float}\n",
- " - \\usepackage{titling}\n",
- " - \\setlength{\\droptitle}{-1.5cm}\n",
- " - \\usepackage[breakable]{tcolorbox}\n",
- " - \\usepackage{tcolorbox}\n",
- " - \\tcbuselibrary{breakable}\n",
- " - \\renewenvironment{Shaded}{\\begin{tcolorbox}[breakable,boxrule=0pt,",
- "colback=gray!10]}{\\end{tcolorbox}}\n",
- paste0("date: ", format(Sys.time(), '%Y-%m-%d %H:%M:%S')),
- "\n---\n",
- paste0(
- "This report contains details for ",
- length(unique_users_vct),
- " user",
- ifelse(length(unique_users_vct) > 1, "s", ""),
- " and ",
- length(unique_project_vct),
- " project",
- ifelse(length(unique_project_vct) > 1, "s", ""),
- ". In addition, the tables they have access to within",
- ifelse(length(unique_project_vct) > 1, " a ", " the "),
- "project. \n",
- ifelse(
- "server" %in% colnames(overview_tbl),
- paste0(
- "\n**Note:** the data shown in this report was extracted from ",
- length(unique_servers_vct),
- " server",
- ifelse(length(unique_servers_vct) > 1, "s", ""),
- "."
- ),
- ""
- ),
- "\n\n"
- ),
- "## Overview\n\n",
- "\n",
- # "::: {style=\"text-align: center;\"}\n",
- "\n",
- "```{=latex}\n",
- paste0(
- "\\begin{figure}[H]\n",
- "\\centering\n",
- "\\includegraphics[height=0.75\\textheight, keepaspectratio, width=0.9\\textwidth]{",
- diagram_filepath,
- "}",
- "\\caption{RO-Crate Overview}\n",
- "\\end{figure}\n```\n"
- ),
- "",
- "```{=html}\n",
- paste0(
- "

\n"
- ),
- "```\n
\n\n\\newpage"
- )
-}
-
-#' Generate Markdown report's body
-#'
-#' @inheritParams .overview_diagram
-#' @param report_contents String with Markdown report (e.g., header).
-#' @param safe_people_tbl Data frame with Safe People details.
-#' @param safe_project_tbl Data frame with Safe Project details.
-#' @param safe_data_tbl Data frame with Safe Data details.
-#' @param safe_user_perm_tbl Data frame with Safe Data user permissions.
-#' @param safe_setting_tbl Data frame with Safe Setting details.
-#' @param safe_output_tbl Data frame with Safe Output details.
-#' @param break_by Optional string with variable to be used for breaking down
-#' each table (e.g., server), as opposed to display all the results in a
-#' single table.
-#'
-#' @returns String with updated Markdown report.
-#' @keywords internal
-#' @noRd
-.markdown_report_body <- function(
- report_contents,
- overview_tbl,
- safe_people_tbl,
- safe_project_tbl,
- safe_data_tbl,
- safe_user_perm_tbl,
- safe_setting_tbl,
- safe_output_tbl,
- break_by = NULL
-) {
- # local bindings
- actionStatus <- description <- permission <- NULL
-
- report_contents <- c(report_contents, "\n
\n", "## Entities")
-
- ## append Safe People details
- report_contents <- c(
- report_contents,
- "\n### People\n",
- safe_people_tbl |>
- .break_tibble(varname = break_by) |>
- paste0(collapse = "\n")
- )
-
- ## append Safe Project & Safe Data details
- report_contents <- c(
- report_contents,
- "### Project(s)\n",
- safe_project_tbl |>
- .break_tibble(varname = break_by) |>
- paste0(collapse = "\n")
- )
-
- ## append Safe Data details
- report_contents <- c(
- report_contents,
- "### Data\n",
- safe_data_tbl |>
- .break_tibble(varname = break_by) |>
- paste0(collapse = "\n")
- )
-
- ## append Safe Data permissions
- #### check if `overview_tbl` has `permission` field
- if ("permission" %in% colnames(overview_tbl)) {
- report_contents <- c(
- report_contents,
- "#### Data permissions\n",
- safe_user_perm_tbl |>
- dplyr::select(-actionStatus, -description, -permission) |>
- .break_tibble(varname = break_by) |>
- paste0(collapse = "\n")
- )
- }
-
- ## append Safe Settings details
- report_contents <- c(
- report_contents,
- "### Settings\n",
- safe_setting_tbl |>
- .break_tibble(varname = break_by) |>
- paste0(collapse = "\n")
- )
-
- if (!is.null(safe_output_tbl) && nrow(safe_output_tbl) > 0) {
- ## append Safe Outputs details
- report_contents <- c(
- report_contents,
- "### Outputs\n",
- safe_output_tbl |>
- .break_tibble(varname = break_by) |>
- paste0(collapse = "\n")
- )
- }
-
- return(report_contents)
-}
-
-#' Embed RO-Crate in Markdown report
-#'
-#' @inheritParams .markdown_report_body
-#' @param rocrate RO-Crate object (see [rocrateR::rocrate]).
-#' @param section_txt String with to be used as the section header
-#' (e.g., RO-Crate).
-#'
-#' @returns String with update Markdown report.
-#' @keywords internal
-#' @noRd
-.markdown_report_rocrate <- function(
- report_contents,
- rocrate,
- section_txt,
- max_line_length = 200
-) {
- # save the input into intermediate JSON file
- tmp_file <- tempfile(fileext = ".json")
- # delete temporary file
- on.exit(unlink(tmp_file, recursive = TRUE, force = TRUE))
- # store RO-Crate in JSON format
- jsonlite::write_json(
- rocrate,
- path = tmp_file,
- pretty = TRUE,
- auto_unbox = TRUE
- )
- # load formatted RO-Crate as text
- rocrate_txt <- readLines(tmp_file) |>
- # shorten long lines, beyond `max_line_length`
- sapply(function(x) {
- if (nchar(x) > max_line_length && max_line_length > 10) {
- return(paste0(
- substr(x, 1, max_line_length - 10),
- "... ...",
- substr(x, nchar(x) - 10, nchar(x))
- ))
- }
- return(x)
- })
- report_contents <- c(
- report_contents,
- "\n\\newpage\n",
- section_txt,
- "\n```json",
- # display formatted RO-Crate
- rocrate_txt,
- "\n```"
+ # ensure the given file path is valid
+ .validate_report_path(filepath, overwrite)
+
+ # extract the tables from the RO-Crate (and load its contents)
+ crate_tables <- .report_tables(x)
+
+ .generate_report(
+ overview_tbl = crate_tables$overview_tbl,
+ safe_people_tbl = crate_tables$safe_people,
+ safe_project_tbl = crate_tables$safe_project,
+ safe_data_tbl = crate_tables$safe_data,
+ safe_user_perm_tbl = crate_tables$safe_data_permissions,
+ safe_setting_tbl = crate_tables$safe_setting,
+ safe_output_tbl = crate_tables$safe_output,
+ rocrates = list(crate_tables$rocrate),
+ title = title,
+ filepath = filepath,
+ render = render,
+ doc_format = doc_format,
+ overwrite = overwrite,
+ include_user_perm = include_user_perm,
+ diag_title = diag_title,
+ max_line_length = max_line_length,
+ break_by = NULL
)
}
-
-#' Break tibble by group, `varname`
-#'
-#' @param df Data frame to be broken down into groups.
-#' @param varname String with variable name
-#'
-#' @returns String with data frame rendered with `kable`.
-#' @keywords internal
-#' @noRd
-.break_tibble <- function(df, varname) {
- # local bindings
- temp <- NULL
-
- # if `varname` is NULL or not a column in `df`, render all the data
- if (is.null(varname) || !(varname %in% colnames(df))) {
- return(knitr::kable(df))
- }
-
- # extract unique values for `varname` in `df`
- unique_vals <- unique(getElement(df, varname))
-
- # render data frame based on groups
- sapply(unique_vals, function(v) {
- c(
- paste0("\n#### '", v, "' ", varname, "\n"),
- df |>
- dplyr::rename(temp = !!varname) |>
- dplyr::filter(temp == v) |>
- dplyr::select(-temp) |>
- # drop out empty columns, equivalent to `janitor::remove_empty`
- Filter(f = function(x) any(!is.na(x))) |>
- knitr::kable()
- ) |>
- paste0(collapse = "\n")
- })
-}
diff --git a/R/safe-symbol.R b/R/safe-symbol.R
index 2058a62..3cb3d64 100644
--- a/R/safe-symbol.R
+++ b/R/safe-symbol.R
@@ -1,3 +1,5 @@
+#' @importFrom tibble as_tibble
+#' @export
as_tibble.safe_symbol <- function(x, ...) {
tibble::tibble(
id = x$id,
diff --git a/R/safe_data.R b/R/safe_data.R
index fadd915..dfd96cc 100644
--- a/R/safe_data.R
+++ b/R/safe_data.R
@@ -11,8 +11,8 @@
#' identified, such as names and addresses, is either removed or replaced with
#' a random code. Researchers are not processing personal data when using data
#' prepared in this way and when the other Safes are in place. Find out more
-#' about de-identification:
-#'
+#' about de-identification, 'What is data de-identification?':
+#'
#'
#' @param x This can be a connection to a 'DataSHIELD' server (e.g., object with
#' the `opal` or `ArmadilloCredentials` classes), an RO-Crate
@@ -32,7 +32,7 @@
#' @source
#' \itemize{
#' \item Research Data Scotland, 2025. "What is the Five Safes framework?".
-#'
+#'
#' }
safe_data <- function(x, ...) {
UseMethod("safe_data")
@@ -41,19 +41,13 @@ safe_data <- function(x, ...) {
# @rdname safe_data
#' @export
safe_data.default <- function(x, ...) {
- stop(
- "Unknown class, please try either a file path or",
- " an object with `rocrate` class!"
- )
+ s3_method_not_available("safe_data", class = class(x))
}
#' @rdname safe_data
#' @export
safe_data.ArmadilloCredentials <- function(x, ...) {
- stop(
- "`safe_data()` for the Armadillo backend is not currently implemented!",
- call. = FALSE
- )
+ s3_method_not_implemented("safe_data", backend = "Armadillo")
}
#' @rdname safe_data
@@ -61,15 +55,15 @@ safe_data.ArmadilloCredentials <- function(x, ...) {
safe_data.character <- function(
x,
...,
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables"),
asset_id_suffix = "#asset:",
project_id_suffix = "#project:",
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- user = attr(x, "user")
+ connection = NULL,
+ path = NULL,
+ profile = "default",
+ project = NULL,
+ resources = NULL,
+ tables = NULL,
+ user = NULL
) {
# attempt loading the RO-Crate
rocrate <- rocrateR::load_rocrate(x)
@@ -105,11 +99,11 @@ safe_data.opal <- function(
path = NULL,
user = NULL
) {
- # declare local bindings
- created <- lastUpdate <- name <- new_dataset_entity <- subject <- NULL
+ # local bindings
+ name <- NULL
# validate backend
- validate_backend(x, ...)
+ validate_backend(x, ..., rocrate = rocrate)
# match the assets to be included
include <- match.arg(include, several.ok = TRUE)
@@ -121,25 +115,33 @@ safe_data.opal <- function(
stop("`project` must be a single value!", call. = FALSE)
}
+ # get the context for `project`, to share requests with the other safe_*()
+ context <- get_project_context(x, project, rocrate)
+
+ # check if the given `project` exists
+ project_context_exists(context)
+
project_id <- id_hash(project_id_suffix, project)
- # extract assets for the given project
+ # extract assets from the shared project context
all_assets <- list()
# ---- tables ----
if ("tables" %in% include) {
- tbl_assets <- get_project_assets(x, project, "tables")
- if (!is.null(tbl_assets)) {
- if (!is.null(tables)) {
- tbl_assets <- dplyr::filter(tbl_assets, name %in% tables)
- }
+ tbl_assets <- project_context_assets(context, "tables")
+
+ if (!is.null(tbl_assets) && !is.null(tables)) {
+ tbl_assets <- dplyr::filter(tbl_assets, name %in% tables)
+ }
+
+ if (!is.null(tbl_assets) && nrow(tbl_assets) > 0) {
all_assets$tables <- tbl_assets
}
}
# ---- resources ----
if ("resources" %in% include) {
- res_assets <- get_project_assets(x, project, "resources")
+ res_assets <- project_context_assets(context, "resources")
if (!is.null(res_assets)) {
if (!is.null(resources)) {
res_assets <- dplyr::filter(res_assets, name %in% resources)
@@ -192,7 +194,8 @@ safe_data.opal <- function(
x,
project,
assets_tbl,
- id_lookup
+ id_lookup,
+ context
)
# add asset entities to the RO-Crate
@@ -203,17 +206,19 @@ safe_data.opal <- function(
overwrite = TRUE
)
- # attach input arguments as attributes
- attr(rocrate, "connection") <- x
- attr(rocrate, "path") <- path
- attr(rocrate, "profile") <- profile
- attr(rocrate, "project") <- project
- attr(rocrate, "resources") <- resources
- attr(rocrate, "tables") <- tables
- attr(rocrate, "user") <- user
-
- # return RO-Crate with the new entity
- return(rocrate)
+ # attach input arguments as attributes and return RO-Crate
+ rocrate |>
+ set_project_context(context) |>
+ set_crate_context(
+ connection = x,
+ path = path,
+ profile = profile,
+ project = project,
+ resources = resources,
+ tables = tables,
+ user = user,
+ validated = TRUE
+ )
}
#' @rdname safe_data
@@ -221,15 +226,15 @@ safe_data.opal <- function(
safe_data.rocrate <- function(
x,
...,
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables"),
asset_id_suffix = "#asset:",
project_id_suffix = "#project:",
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- user = attr(x, "user")
+ connection = get_crate_context(x, "connection"),
+ path = get_crate_context(x, "path"),
+ profile = get_crate_context(x, "profile"),
+ project = get_crate_context(x, "project"),
+ resources = get_crate_context(x, "resources"),
+ tables = get_crate_context(x, "tables"),
+ user = get_crate_context(x, "user")
) {
# check if the connection was given
if (is.null(connection)) {
diff --git a/R/safe_output.R b/R/safe_output.R
index a353218..a547c17 100644
--- a/R/safe_output.R
+++ b/R/safe_output.R
@@ -25,7 +25,7 @@
#' @source
#' \itemize{
#' \item Research Data Scotland, 2025. "What is the Five Safes framework?".
-#'
+#'
#' }
safe_output <- function(x, ...) {
UseMethod("safe_output")
@@ -34,19 +34,13 @@ safe_output <- function(x, ...) {
# @rdname safe_output
#' @export
safe_output.default <- function(x, ...) {
- stop(
- "Unknown class, please try either a file path or",
- " an object with `rocrate` class!"
- )
+ s3_method_not_available("safe_output", class = class(x))
}
#' @rdname safe_output
#' @export
safe_output.ArmadilloCredentials <- function(x, ...) {
- stop(
- "`safe_output()` for the Armadillo backend is not currently implemented!",
- call. = FALSE
- )
+ s3_method_not_implemented("safe_output", backend = "Armadillo")
}
#' @rdname safe_output
@@ -54,15 +48,15 @@ safe_output.ArmadilloCredentials <- function(x, ...) {
safe_output.character <- function(
x,
...,
- path = attr(x, "path"),
- user = attr(x, "user"),
logs_to = Sys.time(),
logs_from = logs_to - 24 * 60^2,
- connection = attr(x, "connection"),
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables")
+ connection = NULL,
+ path = NULL,
+ profile = "default",
+ project = NULL,
+ resources = NULL,
+ tables = NULL,
+ user = NULL
) {
# attempt loading the RO-Crate
rocrate <- rocrateR::load_rocrate(x)
@@ -100,9 +94,9 @@ safe_output.opal <- function(
) {
# local bindings
`@timestamp` <- backend <- logger_name <- safe_people_id <- username <- NULL
- ds_action <- ds_eval <- ds_id <- ds_function <- ds_symbol <- ds_table <- NULL
- asset <- action <- is_placeholder <- kind <- symbol_id <- timestamp <- NULL
- ds_profile <- expr <- fx <- log_id <- r_cmd <- session <- symbol <- NULL
+ ds_action <- ds_eval <- ds_id <- ds_function <- ds_symbol <- NULL
+ asset <- action <- kind <- symbol_id <- timestamp <- NULL
+ ds_profile <- expr <- fx <- r_cmd <- session <- symbol <- NULL
column <- created_at <- created_by <- id <- uuid <- NULL
if (is.null(profile)) {
@@ -125,7 +119,7 @@ safe_output.opal <- function(
logs_to_formatted <- fmt_limit(logs_to)
# validate backend
- validate_backend(x, ...)
+ validate_backend(x, ..., rocrate = rocrate)
# verify if `user` is NULL, if so, retrieve information from the RO-crate
if (is.null(user)) {
@@ -235,7 +229,7 @@ safe_output.opal <- function(
}
log_filename <- paste0(
- format(Sys.time(), "%Y%m%dT%H%M%S"),
+ format(Sys.time(), "%Y%m%dT%H%M%S", tz = "UTC"),
"-dslogs-",
user,
".log"
@@ -245,7 +239,7 @@ safe_output.opal <- function(
log_entity <- rocrateR::entity(
id = basename(log_filename),
type = "File",
- dateModified = Sys.time(),
+ dateModified = format_utc(Sys.time()),
name = basename(log_filename),
description = paste0(
"This file contains the raw logs for the user: `",
@@ -311,11 +305,11 @@ safe_output.opal <- function(
symbol = ds_symbol,
kind = ifelse(
is_expr,
- 'expression',
+ "expression",
ifelse(
is_resource,
- 'resource',
- ifelse(is_table, 'table', NA_character_)
+ "resource",
+ ifelse(is_table, "table", NA_character_)
)
),
asset = ifelse(
@@ -326,11 +320,11 @@ safe_output.opal <- function(
expr = ifelse(is_expr, ds_eval, NA_character_),
created_by = ifelse(
is_expr,
- 'DSI::datashield.assign.expr',
+ "DSI::datashield.assign.expr",
ifelse(
is_resource,
- 'DSI::datashield.assign.resource',
- ifelse(is_table, 'DSI::datashield.assign.table', NA_character_)
+ "DSI::datashield.assign.resource",
+ ifelse(is_table, "DSI::datashield.assign.table", NA_character_)
)
),
created_at = userlogs_assign_tbl$`@timestamp`[[i]],
@@ -402,7 +396,7 @@ safe_output.opal <- function(
),
expr = NA_character_,
session = ds_id,
- backend = "OBiBa's Opal"
+ backend = backend_name(x)
)
}
@@ -414,7 +408,6 @@ safe_output.opal <- function(
# parse aggregate function calls into list of safe_call objects
calls_lst <- userlogs_tbl |>
dplyr::filter((ds_action %in% c("AGGREGATE"))) |>
- # dplyr::filter(!is.na(ds_eval)) |>
purrr::pmap(function(ds_eval, ...) {
safe_call(ds_eval, ...) |>
enrich_call(registry = registry)
@@ -492,7 +485,7 @@ safe_output.opal <- function(
)
) |>
# add column with backend
- dplyr::mutate(backend = "OBiBa's Opal") |>
+ dplyr::mutate(backend = backend_name(x)) |>
# subset columns
dplyr::select(
id,
@@ -506,7 +499,6 @@ safe_output.opal <- function(
kind,
asset,
expr,
- # table = ds_table,
session,
backend
)
@@ -518,11 +510,11 @@ safe_output.opal <- function(
dplyr::mutate(
# format timestamp
timestamp = format_utc(`@timestamp`),
- # attach session ID, `ds_id`, if `ds_action == 'OPEN'`
+ # attach session ID, `ds_id`, if `ds_action == "OPEN"`
ds_eval = paste0("Open session: ", ds_id),
- # set `ds_function = 'DSI::datashield.login'`
+ # set `ds_function = "DSI::datashield.login"`
ds_function = "DSI::datashield.login",
- backend = "OBiBa's Opal"
+ backend = backend_name(x)
) |>
dplyr::select(
id,
@@ -555,7 +547,7 @@ safe_output.opal <- function(
asset,
expr,
session,
- backend = "OBiBa's Opal"
+ backend = backend_name(x)
)
# combine the logs
@@ -568,11 +560,11 @@ safe_output.opal <- function(
dplyr::distinct() |>
dplyr::arrange(as.numeric(id), timestamp) |>
# regenerate unique operation IDs
- (\(.) {
+ (\(x) {
dplyr::left_join(
- .,
+ x,
tibble::tibble(
- id = unique(.$id),
+ id = unique(x$id),
uuid = uuid::UUIDgenerate(n = length(id))
),
by = "id"
@@ -582,7 +574,7 @@ safe_output.opal <- function(
dplyr::select(-uuid)
log_maps_filename <- paste0(
- format(Sys.time(), "%Y%m%dT%H%M%S"),
+ format(Sys.time(), "%Y%m%dT%H%M%S", tz = "UTC"),
"-dslogs-",
user,
"_mappings.csv"
@@ -592,7 +584,7 @@ safe_output.opal <- function(
log_maps_entity <- rocrateR::entity(
id = basename(log_maps_filename),
type = "File",
- dateModified = Sys.time(),
+ dateModified = format_utc(Sys.time()),
name = basename(log_maps_filename),
description = "This file contains mappings and evaluated functions",
encodingFormat = "text/csv"
@@ -645,17 +637,18 @@ safe_output.opal <- function(
overwrite = TRUE
)
- # attach input arguments as attributes
- attr(rocrate, "connection") <- x
- attr(rocrate, "path") <- path
- attr(rocrate, "profile") <- profile
- attr(rocrate, "project") <- project
- attr(rocrate, "resources") <- resources
- attr(rocrate, "tables") <- tables
- attr(rocrate, "user") <- user
-
- # return RO-Crate with the new entity
- return(rocrate)
+ # attach input arguments as attributes and return RO-Crate
+ rocrate |>
+ set_crate_context(
+ connection = x,
+ path = path,
+ profile = profile,
+ project = project,
+ resources = resources,
+ tables = tables,
+ user = user,
+ validated = TRUE
+ )
}
#' @rdname safe_output
@@ -663,15 +656,15 @@ safe_output.opal <- function(
safe_output.rocrate <- function(
x,
...,
- path = attr(x, "path"),
- user = attr(x, "user"),
logs_to = Sys.time(),
logs_from = logs_to - 24 * 60^2,
- connection = attr(x, "connection"),
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables")
+ connection = get_crate_context(x, "connection"),
+ path = get_crate_context(x, "path"),
+ profile = get_crate_context(x, "profile"),
+ project = get_crate_context(x, "project"),
+ resources = get_crate_context(x, "resources"),
+ tables = get_crate_context(x, "tables"),
+ user = get_crate_context(x, "user")
) {
# check if the connection was given
if (is.null(connection)) {
diff --git a/R/safe_people.R b/R/safe_people.R
index e3da1c2..425b33e 100644
--- a/R/safe_people.R
+++ b/R/safe_people.R
@@ -22,7 +22,7 @@
#' @source
#' \itemize{
#' \item Research Data Scotland, 2025. "What is the Five Safes framework?".
-#'
+#'
#' }
safe_people <- function(x, ...) {
UseMethod("safe_people")
@@ -31,19 +31,13 @@ safe_people <- function(x, ...) {
# @rdname safe_people
#' @export
safe_people.default <- function(x, ...) {
- stop(
- "Unknown class, please try either a file path or",
- " an object with `rocrate` class!"
- )
+ s3_method_not_available("safe_people", class = class(x))
}
#' @rdname safe_people
#' @export
safe_people.ArmadilloCredentials <- function(x, ...) {
- stop(
- "`safe_people()` for the Armadillo backend is not currently implemented!",
- call. = FALSE
- )
+ s3_method_not_implemented("safe_people", backend = "Armadillo")
}
#' @rdname safe_people
@@ -51,16 +45,16 @@ safe_people.ArmadilloCredentials <- function(x, ...) {
safe_people.character <- function(
x,
...,
- user = attr(x, "user"),
- user_id_suffix = "#person:",
set_author = TRUE,
set_project = TRUE,
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables")
+ user_id_suffix = "#person:",
+ connection = NULL,
+ path = NULL,
+ profile = "default",
+ project = NULL,
+ resources = NULL,
+ tables = NULL,
+ user = NULL
) {
# attempt loading the RO-Crate
rocrate <- rocrateR::load_rocrate(x)
@@ -98,7 +92,7 @@ safe_people.opal <- function(
tables = NULL
) {
# validate backend
- validate_backend(x, ...)
+ validate_backend(x, ..., rocrate = rocrate)
# attempt to retrieve project entity
project_id <- id_hash("#project:", project)
@@ -182,17 +176,18 @@ safe_people.opal <- function(
)
}
- # attach input arguments as attributes
- attr(rocrate, "connection") <- x
- attr(rocrate, "path") <- path
- attr(rocrate, "profile") <- profile
- attr(rocrate, "project") <- project
- attr(rocrate, "resources") <- resources
- attr(rocrate, "tables") <- tables
- attr(rocrate, "user") <- user
-
- # return RO-Crate with the new entity
- return(rocrate)
+ # attach input arguments as attributes and return RO-Crate
+ rocrate |>
+ set_crate_context(
+ connection = x,
+ path = path,
+ profile = profile,
+ project = project,
+ resources = resources,
+ tables = tables,
+ user = user,
+ validated = TRUE
+ )
}
#' @rdname safe_people
@@ -200,16 +195,16 @@ safe_people.opal <- function(
safe_people.rocrate <- function(
x,
...,
- user = attr(x, "user"),
- user_id_suffix = "#person:",
set_author = TRUE,
set_project = TRUE,
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables")
+ user_id_suffix = "#person:",
+ connection = get_crate_context(x, "connection"),
+ path = get_crate_context(x, "path"),
+ profile = get_crate_context(x, "profile"),
+ project = get_crate_context(x, "project"),
+ resources = get_crate_context(x, "resources"),
+ tables = get_crate_context(x, "tables"),
+ user = get_crate_context(x, "user")
) {
# check if the connection was given
if (is.null(connection)) {
diff --git a/R/safe_project.R b/R/safe_project.R
index 2317956..b8045d9 100644
--- a/R/safe_project.R
+++ b/R/safe_project.R
@@ -18,7 +18,7 @@
#' @source
#' \itemize{
#' \item Research Data Scotland, 2025. "What is the Five Safes framework?".
-#'
+#'
#' }
safe_project <- function(x, ...) {
UseMethod("safe_project")
@@ -27,10 +27,7 @@ safe_project <- function(x, ...) {
# @rdname safe_project
#' @export
safe_project.default <- function(x, ...) {
- stop(
- "Unknown class, please try either a file path or",
- " an object with `rocrate` class!"
- )
+ s3_method_not_available("safe_project", class = class(x))
}
#' @rdname safe_project
@@ -48,6 +45,8 @@ safe_project.ArmadilloCredentials <- function(
tables = NULL,
user = NULL
) {
+ .require_armadillo("MolgenisArmadillo")
+
# check if the given `project` exists
project_exists(x, project = project)
@@ -63,15 +62,15 @@ safe_project.ArmadilloCredentials <- function(
safe_project.character <- function(
x,
...,
- profile = attr(x, "profile"),
- project = attr(x, "project"),
asset_id_suffix = "#asset:",
project_id_suffix = "#project:",
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables"),
- user = attr(x, "user")
+ connection = NULL,
+ path = NULL,
+ profile = "default",
+ project = NULL,
+ resources = NULL,
+ tables = NULL,
+ user = NULL
) {
# attempt loading the RO-Crate
rocrate <- rocrateR::load_rocrate(x)
@@ -107,10 +106,10 @@ safe_project.opal <- function(
user = NULL
) {
# declare local bindings
- created <- lastUpdate <- type <- NULL
+ subject <- type <- NULL
# validate backend
- validate_backend(x, ...)
+ validate_backend(x, ..., rocrate = rocrate)
# enforce that `project` is a single value
if (is.null(project)) {
@@ -119,8 +118,11 @@ safe_project.opal <- function(
stop("`project` must be a single value!", call. = FALSE)
}
+ # get the context for `project`, to share requests with the other safe_*()
+ context <- get_project_context(x, project, rocrate)
+
# check if the given `project` exists
- project_exists(x, project = project)
+ project_context_exists(context)
# create project @id
project_id <- id_hash(project_id_suffix, project)
@@ -153,14 +155,14 @@ safe_project.opal <- function(
rocrateR::add_entity(project_entity, overwrite = TRUE)
# Opal permissions ----
- # TODO(#42): derive project membership with `backend_project_members()` and
- # share it (and the assets) across the safe_*() functions.
- perms <- backend_project_perms(x, project)
+ # project members: users with permissions on the project or on any of the
+ # (audited) tables and resources, requested once and shared with safe_data()
+ members <- project_context_members(context, tables, resources)
- project_users <- perms |>
+ project_users <- members |>
dplyr::filter(type == "user") |>
- purrr::pmap_chr(\(subject, ...) subject) |>
- stats::na.omit()
+ dplyr::pull(subject) |>
+ unique()
# link existing Person entities ----
people <- .get_entity(rocrate, type = "Person")
@@ -180,8 +182,8 @@ safe_project.opal <- function(
# link existing asset entities ----
# extract assets for the given project
- project_tbl_assets <- get_project_assets(x, project, "tables")
- project_res_assets <- get_project_assets(x, project, "resources")
+ project_tbl_assets <- project_context_assets(context, "tables")
+ project_res_assets <- project_context_assets(context, "resources")
# combine assets
proj_assets_tbl <- dplyr::bind_rows(project_tbl_assets, project_res_assets)
@@ -200,17 +202,19 @@ safe_project.opal <- function(
}
}
- # attach input arguments as attributes
- attr(rocrate, "connection") <- x
- attr(rocrate, "path") <- path
- attr(rocrate, "profile") <- profile
- attr(rocrate, "project") <- project
- attr(rocrate, "resources") <- resources
- attr(rocrate, "tables") <- tables
- attr(rocrate, "user") <- user
-
- # return RO-Crate with the new entity
- return(rocrate)
+ # attach input arguments as attributes and return RO-Crate
+ rocrate |>
+ set_project_context(context) |>
+ set_crate_context(
+ connection = x,
+ path = path,
+ profile = profile,
+ project = project,
+ resources = resources,
+ tables = tables,
+ user = user,
+ validated = TRUE
+ )
}
#' @rdname safe_project
@@ -218,15 +222,15 @@ safe_project.opal <- function(
safe_project.rocrate <- function(
x,
...,
- profile = attr(x, "profile"),
- project = attr(x, "project"),
asset_id_suffix = "#asset:",
project_id_suffix = "#project:",
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables"),
- user = attr(x, "user")
+ connection = get_crate_context(x, "connection"),
+ path = get_crate_context(x, "path"),
+ profile = get_crate_context(x, "profile"),
+ project = get_crate_context(x, "project"),
+ resources = get_crate_context(x, "resources"),
+ tables = get_crate_context(x, "tables"),
+ user = get_crate_context(x, "user")
) {
# check if the connection was given
if (is.null(connection)) {
diff --git a/R/safe_setting.R b/R/safe_setting.R
index a72e3c2..f104275 100644
--- a/R/safe_setting.R
+++ b/R/safe_setting.R
@@ -27,7 +27,7 @@
#' @source
#' \itemize{
#' \item Research Data Scotland, 2025. "What is the Five Safes framework?".
-#'
+#'
#' }
safe_setting <- function(x, ...) {
UseMethod("safe_setting")
@@ -36,19 +36,13 @@ safe_setting <- function(x, ...) {
# @rdname safe_setting
#' @export
safe_setting.default <- function(x, ...) {
- stop(
- "Unknown class, please try either a file path or",
- " an object with `rocrate` class!"
- )
+ s3_method_not_available("safe_setting", class = class(x))
}
#' @rdname safe_setting
#' @export
safe_setting.ArmadilloCredentials <- function(x, ...) {
- stop(
- "`safe_setting()` for the Armadillo backend is not currently implemented!",
- call. = FALSE
- )
+ s3_method_not_implemented("safe_setting", backend = "Armadillo")
}
#' @rdname safe_setting
@@ -56,13 +50,13 @@ safe_setting.ArmadilloCredentials <- function(x, ...) {
safe_setting.character <- function(
x,
...,
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- tables = attr(x, "tables"),
- resources = attr(x, "resources"),
- user = attr(x, "user")
+ connection = NULL,
+ path = NULL,
+ profile = "default",
+ project = NULL,
+ resources = NULL,
+ tables = NULL,
+ user = NULL
) {
# attempt loading the RO-Crate
rocrate <- rocrateR::load_rocrate(x)
@@ -159,7 +153,7 @@ safe_setting.opal <- function(
Package <- NULL
# validate backend
- validate_backend(x, ...)
+ validate_backend(x, ..., rocrate = rocrate)
# validate profile ----
if (!backend_profile_exists(x, profile)) {
@@ -237,7 +231,7 @@ safe_setting.opal <- function(
)
# extract version of dsBase / DataSHIELD server
- dsBase_version <- tryCatch(
+ ds_version <- tryCatch(
pkg_tbl |>
dplyr::filter(Package == "dsBase") |>
(\(x) x$Version)(),
@@ -245,7 +239,7 @@ safe_setting.opal <- function(
)
software_env <- rocrateR::entity(
- id = id_hash("#env:software_stack:", paste0(opal_version, dsBase_version)),
+ id = id_hash("#env:software_stack:", paste0(opal_version, ds_version)),
type = "CreativeWork",
name = "Approved Analytical Software Environment",
description = paste(
@@ -342,17 +336,18 @@ safe_setting.opal <- function(
# link Safe Settings with safe Projects
rocrate <- link_safe_settings_to_projects(rocrate)
- # attach input arguments as attributes
- attr(rocrate, "connection") <- x
- attr(rocrate, "path") <- path
- attr(rocrate, "profile") <- profile
- attr(rocrate, "project") <- project
- attr(rocrate, "resources") <- resources
- attr(rocrate, "tables") <- tables
- attr(rocrate, "user") <- user
-
- # return RO-Crate with the new entity
- return(rocrate)
+ # attach input arguments as attributes and return RO-Crate
+ rocrate |>
+ set_crate_context(
+ connection = x,
+ path = path,
+ profile = profile,
+ project = project,
+ resources = resources,
+ tables = tables,
+ user = user,
+ validated = TRUE
+ )
}
#' @rdname safe_setting
@@ -360,13 +355,13 @@ safe_setting.opal <- function(
safe_setting.rocrate <- function(
x,
...,
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables"),
- user = attr(x, "user")
+ connection = get_crate_context(x, "connection"),
+ path = get_crate_context(x, "path"),
+ profile = get_crate_context(x, "profile"),
+ project = get_crate_context(x, "project"),
+ resources = get_crate_context(x, "resources"),
+ tables = get_crate_context(x, "tables"),
+ user = get_crate_context(x, "user")
) {
# check if the connection was given
if (is.null(connection)) {
diff --git a/R/utils-S3.R b/R/utils-S3.R
new file mode 100644
index 0000000..0809157
--- /dev/null
+++ b/R/utils-S3.R
@@ -0,0 +1,22 @@
+s3_method_not_available <- function(generic, class = NULL, hint = NULL) {
+ msg <- sprintf("No `%s()` method exists", generic)
+ if (!is.null(class)) {
+ class <- paste(class, collapse = ", ")
+ msg <- sprintf("%s for objects of class: %s", msg, class)
+ }
+ msg <- paste0(msg, "!")
+ if (!is.null(hint)) {
+ msg <- paste(msg, hint, sep = "\n")
+ }
+ stop(msg, call. = FALSE)
+}
+
+s3_method_not_implemented <- function(generic, backend = NULL, class = NULL) {
+ msg <- sprintf("`%s()` for the", generic)
+ if (!is.null(backend)) {
+ msg <- sprintf("%s %s backend", msg, backend)
+ } else if (!is.null(class)) {
+ msg <- sprintf("%s %s class", msg, class)
+ }
+ stop(paste(msg, "is not currently implemented!"), call. = FALSE)
+}
diff --git a/R/utils-armadillo.R b/R/utils-armadillo.R
index a9f2068..bccc22c 100644
--- a/R/utils-armadillo.R
+++ b/R/utils-armadillo.R
@@ -1,3 +1,15 @@
+.require_armadillo <- function(package) {
+ if (!requireNamespace(package, quietly = TRUE)) {
+ stop(
+ sprintf("Package '%s' is required for the Armadillo backend. ", package),
+ "Please install it first.",
+ call. = FALSE
+ )
+ }
+
+ invisible(TRUE)
+}
+
#' Login to a MOLGENIS' Armadillo server
#'
#' Login to a MOLGENIS' Armadillo server. Wrapper for the function
@@ -10,13 +22,19 @@
#'
#' @examples
#' \dontrun{
-#' armadillo_login("https://armadillo-playground.molgenis.net/")
+#' armadillo_login("https://armadillo-playground.molgenis.net/")
#' }
armadillo_login <- function(server) {
+ .require_armadillo("DSMolgenisArmadillo")
+ .require_armadillo("MolgenisArmadillo")
+
conn <- DSMolgenisArmadillo::armadillo.get_credentials(server)
+
ns <- loadNamespace("MolgenisArmadillo")
pkgenv <- get(".pkgglobalenv", envir = ns)
+
assign("armadillo_url", server, envir = pkgenv)
assign("auth_token", getElement(conn, "access_token"), envir = pkgenv)
- return(invisible(conn))
+
+ invisible(conn)
}
diff --git a/R/utils-base-R.R b/R/utils-base-R.R
new file mode 100644
index 0000000..dc20f6d
--- /dev/null
+++ b/R/utils-base-R.R
@@ -0,0 +1,14 @@
+#' Wrapper for binary operator OR
+#'
+#' Wrapper for binary operator OR (only introduced in R v4.4)
+#'
+#' @param x Left hand side object
+#' @param y Right hand side object (default if `x` missing)
+#'
+#' @returns `x` if not missing, `y` otherwise.
+#' @keywords internal
+#'
+#' @noRd
+`%||%` <- function(x, y) {
+ if (is.null(x)) y else x
+}
diff --git a/R/utils-connection.R b/R/utils-connection.R
index c7222e1..6a07e6f 100644
--- a/R/utils-connection.R
+++ b/R/utils-connection.R
@@ -17,7 +17,7 @@ parse_user_profiles <- function(x, ...) {
#' @export
parse_user_profiles.ArmadilloCredentials <- function(x, ..., user) {
- message("PLACEHOLDER!")
+ s3_method_not_implemented("parse_user_profiles", backend = "Armadillo")
}
#' @export
@@ -46,7 +46,7 @@ parse_user_profiles.opal <- function(x, ..., user) {
})
)
}
- return(user_prof_tbl)
+ user_prof_tbl
}
#' Verify if project exists
@@ -72,11 +72,13 @@ project_exists.ArmadilloCredentials <-
...,
project
) {
+ .require_armadillo("MolgenisArmadillo")
+
if (!(project %in% MolgenisArmadillo::armadillo.list_projects())) {
stop(
- sprintf(
- "The `project = '%s'` was not found in the given Armadillo connection!",
- project
+ paste0(
+ sprintf("The `project = '%s'`", project),
+ "was not found in the given Armadillo connection!"
),
call. = FALSE
)
@@ -104,11 +106,16 @@ project_exists.opal <- function(x, ..., project) {
#'
#' @param x DataSHIELD backend connection object.
#' @param ... Optional params.
+#' @param rocrate RO-crate object.
#'
#' @returns Nothing, call for its side effect.
#' @keywords internal
#' @noRd
-validate_backend <- function(x, ...) {
+validate_backend <- function(x, ..., rocrate = NULL) {
+ # check if the backend has been validated, status stored in `rocrate` context
+ if (backend_validated(x, ..., rocrate = rocrate)) {
+ return(invisible(TRUE))
+ }
# validate connection object
validate_con(x, ...)
# validate backend version
diff --git a/R/utils-cr8tor.R b/R/utils-cr8tor.R
index 05b3b0d..b744911 100644
--- a/R/utils-cr8tor.R
+++ b/R/utils-cr8tor.R
@@ -11,7 +11,7 @@
#'
#' @return Updated RO-Crate
#' @noRd
-add_safe_people_entities_cr8tor <- function(rc, people_tbl, membership_tbl) {
+add_safe_people_ents_cr8tor <- function(rc, people_tbl, membership_tbl) {
# local bindings
project <- username <- NULL
@@ -59,11 +59,11 @@ add_safe_people_entities_cr8tor <- function(rc, people_tbl, membership_tbl) {
#'
#' @return Updated RO-Crate
#' @noRd
-add_safe_project_entities_cr8tor <- function(rc, proj_tbl, data_tbl) {
+add_safe_project_ents_cr8tor <- function(rc, proj_tbl, data_tbl) {
# local bindings
asset <- project <- NULL
- now <- format(Sys.time(), "%Y-%m-%dT%H:%M:%OS3Z", tz = "UTC")
+ now <- format_utc(Sys.time())
for (i in seq_len(nrow(proj_tbl))) {
project_id <- proj_tbl$project_id[i]
@@ -196,7 +196,7 @@ add_permission_entities_cr8tor <- function(rc, perm_expanded_tbl) {
#'
#' @return Updated RO-Crate
#' @noRd
-add_safe_setting_entities_cr8tor <- function(rc, tbl) {
+add_safe_setting_ents_cr8tor <- function(rc, tbl) {
for (i in seq_len(nrow(tbl))) {
nm <- names(tbl)[i]
@@ -221,7 +221,7 @@ add_safe_setting_entities_cr8tor <- function(rc, tbl) {
#'
#' @return Updated RO-Crate
#' @noRd
-add_safe_output_entities_cr8tor <- function(rc, tbl) {
+add_safe_output_ents_cr8tor <- function(rc, tbl) {
rc |>
rocrateR::add_entity(
rocrateR::entity(
@@ -263,7 +263,7 @@ as_rocrate_audit <- function(audit) {
# ---- Safe People ----
rc <- rc |>
add_group_entities_cr8tor(audit$groups) |>
- add_safe_people_entities_cr8tor(
+ add_safe_people_ents_cr8tor(
audit$safe_people$users,
audit$user_projects
) |>
@@ -271,7 +271,7 @@ as_rocrate_audit <- function(audit) {
# ---- Safe Projects ----
rc <- rc |>
- add_safe_project_entities_cr8tor(
+ add_safe_project_ents_cr8tor(
audit$safe_projects,
audit$safe_data$assets
)
@@ -283,7 +283,7 @@ as_rocrate_audit <- function(audit) {
# ---- Permissions ----
rc <- rc |>
add_permission_entities_cr8tor(
- expand_group_permissions_to_users(
+ expand_group_perms_to_users(
perm_tbl = audit$permissions |>
dplyr::left_join(
audit$safe_projects,
@@ -297,11 +297,11 @@ as_rocrate_audit <- function(audit) {
# ---- Safe Settings ----
rc <- rc |>
- add_safe_setting_entities_cr8tor(audit$safe_settings)
+ add_safe_setting_ents_cr8tor(audit$safe_settings)
# ---- Safe Outputs ----
rc <- rc |>
- add_safe_output_entities_cr8tor(audit$safe_outputs)
+ add_safe_output_ents_cr8tor(audit$safe_outputs)
rc
}
@@ -345,7 +345,7 @@ dedupe_effective_permissions <- function(perm_tbl) {
#'
#' @return Tibble with username, project, asset, permission
#' @noRd
-expand_group_permissions_to_users <- function(
+expand_group_perms_to_users <- function(
perm_tbl,
membership_tbl,
data_tbl
@@ -450,8 +450,7 @@ extract_safe_data_cr8tor <- function(bundle) {
}
ing_yaml <- yaml::yaml.load(paste(ing$content[[1]], collapse = "\n"))
- # extract groups and projects
- group_tbl <- extract_groups_cr8tor(bundle)
+ # extract projects
proj_tbl <- extract_safe_projects_cr8tor(bundle)
assets <- ing_yaml$datasets |>
@@ -544,7 +543,7 @@ extract_user_groups_cr8tor <- function(bundle) {
purrr::map(user_docs, function(doc) {
username <- doc$spec$username
- groups <- doc$spec$groups #%||% list()
+ groups <- doc$spec$groups # %||% list()
if (length(groups) == 0) {
return(NULL)
@@ -580,7 +579,7 @@ extract_user_projects_cr8tor <- function(bundle) {
purrr::map(user_docs, function(doc) {
username <- doc$spec$username
- groups <- doc$spec$groups # %||% list()
+ groups <- doc$spec$groups
if (length(groups) == 0) {
return(NULL)
@@ -763,7 +762,7 @@ find_bagit_root <- function(path) {
}
}
- return(NULL)
+ NULL
}
#' Link people entities to the RO-Crate root
diff --git a/R/utils-date.R b/R/utils-date.R
index 8049173..7b9e79a 100644
--- a/R/utils-date.R
+++ b/R/utils-date.R
@@ -22,13 +22,12 @@ parse_utc <- function(x) {
# offset in seconds (no offset or "Z" means UTC)
digits <- gsub("[^0-9]", "", offset)
+ dig_2 <- as.numeric(substr(digits, 1, 2))
+ dig_3 <- as.numeric(substr(digits, 3, 4)) * 60
offset_secs <- ifelse(
offset == "Z",
0,
- ifelse(startsWith(offset, "-"), -1, 1) *
- (as.numeric(substr(digits, 1, 2)) *
- 3600 +
- as.numeric(substr(digits, 3, 4)) * 60)
+ ifelse(startsWith(offset, "-"), -1, 1) * (dig_2 * 3600 + dig_3)
)
as.POSIXct(datetime, format = "%Y-%m-%dT%H:%M:%OS", tz = "UTC") - offset_secs
diff --git a/R/utils-opal.R b/R/utils-opal.R
index 47968b0..540358b 100644
--- a/R/utils-opal.R
+++ b/R/utils-opal.R
@@ -7,6 +7,8 @@
#' @param project Project identifier.
#' @param person User identifier.
#' @param assets Vector of strings with asset identifiers.
+#' @param context Project context, to share the permissions with the other
+#' `safe_*()` functions (default: `NULL`, requested to the backend).
#'
#' @return Updated RO-Crate.
#'
@@ -16,7 +18,8 @@ add_asset_permissions_to_crate <- function(
x,
project,
assets_tbl,
- id_lookup
+ id_lookup,
+ context = NULL
) {
# retrieve users (if any), safe_people.* should be executed first
safe_people_tbl <- flatten_safe_people(rocrate)
@@ -28,7 +31,13 @@ add_asset_permissions_to_crate <- function(
asset_type <- asset$asset_type
# retrieve asset permissions
- perms <- get_asset_permissions(x, project, asset_type, asset$name)
+ perms <- get_asset_permissions(
+ x,
+ project,
+ asset_type,
+ asset$name,
+ context
+ )
if (is.null(perms)) {
next
@@ -101,27 +110,33 @@ add_lineage_relations <- function(rocrate, lineage_df, id_lookup) {
build_asset_entities <- function(assets_tbl, project_id, asset_id_suffix) {
purrr::pmap(
assets_tbl,
- function(
- asset_type,
- project,
- name,
- description,
- created,
- updated,
- url,
- meta
- ) {
- rocrateR::entity(
- id = id_hash(asset_id_suffix, paste0(project, name)),
- type = map_asset_type(asset_type, meta, url),
- name = name,
- description = safe_desc(description, name, asset_type),
- url = url,
- dateCreated = safe_time(created),
- dateModified = safe_time(updated),
- isPartOf = list(`@id` = project_id)
- )
- }
+ .build_asset_entities,
+ project_id = project_id,
+ asset_id_suffix = asset_id_suffix
+ )
+}
+
+.build_asset_entities <- function(
+ asset_type,
+ project,
+ name,
+ description,
+ created,
+ updated,
+ url,
+ meta,
+ project_id,
+ asset_id_suffix
+) {
+ rocrateR::entity(
+ id = id_hash(asset_id_suffix, paste0(project, name)),
+ type = map_asset_type(asset_type, meta, url),
+ name = name,
+ description = safe_desc(description, name, asset_type),
+ url = url,
+ dateCreated = safe_time(created),
+ dateModified = safe_time(updated),
+ isPartOf = list(`@id` = project_id)
)
}
@@ -129,13 +144,24 @@ build_asset_entities <- function(assets_tbl, project_id, asset_id_suffix) {
#'
#' @param x Connection to DataSHIELD server (e.g., OBiBa's Opal server).
#' @param project String with project name.
-#' @param asset_type String with type of asset, either `tables` or `resources`.
+#' @param asset_type String with type of asset, either `table` or `resource`.
+#' @param context Project context, to share the permissions with the other
+#' `safe_*()` functions (default: `NULL`, requested to the backend).
#' @param name String with asset name.
#'
#' @returns Tibble with project asset permissions
#' @noRd
-get_asset_permissions <- function(x, project, asset_type, name) {
- if (asset_type == "table") {
+get_asset_permissions <- function(
+ x,
+ project,
+ asset_type,
+ name,
+ context = NULL
+) {
+ if (!is.null(context)) {
+ # shared with the other safe_*() functions
+ perms <- project_context_permissions(context, asset_type, name)
+ } else if (asset_type == "table") {
perms <- backend_table_perms(x, project, name)
} else {
perms <- backend_resource_perms(x, project, name)
@@ -156,14 +182,24 @@ get_asset_permissions <- function(x, project, asset_type, name) {
#' @param x Connection to DataSHIELD server (e.g., OBiBa's Opal server).
#' @param project String with project name.
#' @param type Type of assets to extract, either `tables` or `resources`.
+#' @param check Boolean flag to indicate if the existence of `project` should be
+#' verified (default: `TRUE`). Set to `FALSE` when the caller has already
+#' verified it, to avoid repeating the request.
#'
#' @returns Tibble with project assets details.
#' @noRd
-get_project_assets <- function(x, project, type = c("tables", "resources")) {
+get_project_assets <- function(
+ x,
+ project,
+ type = c("tables", "resources"),
+ check = TRUE
+) {
type <- match.arg(type)
# verify if project exists
- project_exists(x, project = project)
+ if (check) {
+ project_exists(x, project = project)
+ }
if (type == "tables") {
prj <- backend_tables(x, project, df = FALSE)
@@ -175,15 +211,15 @@ get_project_assets <- function(x, project, type = c("tables", "resources")) {
tibble::tibble(
asset_type = "table",
project = project,
- name = vapply(prj, \(x) x$name %||% "", ""),
- description = vapply(prj, \(x) x$description %||% "", ""),
+ name = vapply(prj, \(x) x$name %||% "", character(1)),
+ description = vapply(prj, \(x) x$description %||% "", character(1)),
created = vapply(prj, \(x) safe_time(x$timestamps$created), character(1)),
updated = vapply(
prj,
\(x) safe_time(x$timestamps$lastUpdate),
character(1)
),
- url = vapply(prj, \(x) x$link %||% NA_character_, ""),
+ url = vapply(prj, \(x) x$link %||% NA_character_, character(1)),
meta = vector("list", length(prj))
)
} else if (type == "resources") {
@@ -196,11 +232,15 @@ get_project_assets <- function(x, project, type = c("tables", "resources")) {
tibble::tibble(
asset_type = "resource",
project = project,
- name = vapply(res, \(x) x$name %||% "", ""),
- description = vapply(res, \(x) x$description %||% "", ""),
+ name = vapply(res, \(x) x$name %||% "", character(1)),
+ description = vapply(res, \(x) x$description %||% "", character(1)),
created = vapply(res, \(x) safe_time(x$created), character(1)),
updated = vapply(res, \(x) safe_time(x$updated), character(1)),
- url = vapply(res, function(x) x$resource$url %||% NA_character_, ""),
+ url = vapply(
+ res,
+ function(x) x$resource$url %||% NA_character_,
+ character(1)
+ ),
meta = parse_resource_params(
vapply(res, `[[`, "", "parameters")
)
@@ -344,17 +384,22 @@ parse_resource_params <- function(params_json) {
}
safe_desc <- function(desc, name, type) {
- desc %||% paste(type, name)
+ if (is.null(desc) || is.na(desc) || !nzchar(desc)) {
+ paste(type, name)
+ } else {
+ desc
+ }
}
safe_time <- function(x) {
- if (is.null(x) || is.na(x)) {
+ if (is.null(x) || length(x) != 1 || is.na(x)) {
return(character(1))
}
- tryCatch(
- format_utc(as.POSIXct(x)),
- error = function(e) character(1)
+ out <- tryCatch(
+ format_utc(parse_utc(x)),
+ error = function(e) NA_character_
)
+ if (is.na(out)) character(1) else out
}
#' @noRd
@@ -412,7 +457,10 @@ user_perm_entity <- function(
if (permission == "view") {
comb_id <- paste0(comb_id, "-dict-summary-read")
type <- "ReadAction"
- description <- "User may view table dictionary and summary statistics only; access to individual values is restricted."
+ description <- paste(
+ "User may view table dictionary and summary",
+ "statistics only; access to individual values is restricted."
+ )
} else if (permission == "view-values") {
comb_id <- paste0(comb_id, "-read-all")
type <- "ReadAction"
@@ -422,7 +470,10 @@ user_perm_entity <- function(
type <- c("WriteAction", "ReadAction")
description <- c(
"User may edit the table dictionary but cannot view individual values.",
- "User may view summary statistics only; access to individual values is restricted."
+ paste(
+ "User may view summary statistics only; access to individual",
+ "values is restricted."
+ )
)
} else if (permission == "edit-values") {
comb_id <- paste0(comb_id, c("-write-dict", "-read-all"))
@@ -434,7 +485,10 @@ user_perm_entity <- function(
} else if (permission == "administrate") {
comb_id <- paste0(comb_id, "-admin-table")
type <- "ControlAction"
- description <- "User has full administrative rights: view/edit dictionary and view/edit individual values."
+ description <- paste(
+ "User has full administrative rights: view/edit",
+ "dictionary and view/edit individual values."
+ )
} else {
return(NULL)
}
@@ -449,11 +503,5 @@ user_perm_entity <- function(
description = description
)
- # seq_len(nrow(permission_entities_tbl)) |>
- # lapply(function(i) {
- # rocrateR::entity(permission_entities_tbl$`id`[i],
- # type = permission_entities_tbl$type[i])
- # })
purrr::pmap(permission_entities_tbl, rocrateR::entity)
- # rocrateR::entity(as.list(permission_entities_tbl))
}
diff --git a/R/utils-project-context.R b/R/utils-project-context.R
new file mode 100644
index 0000000..044a5b8
--- /dev/null
+++ b/R/utils-project-context.R
@@ -0,0 +1,216 @@
+#' Project context
+#'
+#' A project context keeps the requests made to the backend about a project, so
+#' they are made once and shared across the `safe_*()` functions (e.g., if the
+#' project exists, its tables and its resources).
+#'
+#' The context is stored in the RO-Crate (see `set_project_context()`) and it is
+#' only reused for the same project and the same connection. It lives as long as
+#' the RO-Crate: run `init()` again to refresh it. Functions that are called
+#' without a context (e.g., with a new RO-Crate) create their own.
+#'
+#' @param connection Connection to DataSHIELD server (e.g., OBiBa's Opal
+#' server).
+#' @param project String with project name.
+#'
+#' @returns Project context object.
+#' @keywords internal
+#' @noRd
+new_project_context <- function(connection, project) {
+ context <- new.env(parent = emptyenv())
+ context$connection <- connection
+ context$project <- project
+ # requests already made, e.g., `exists`, `tables` and `resources`
+ context$cache <- new.env(parent = emptyenv())
+ class(context) <- "project_context"
+ context
+}
+
+#' @param x Object to be tested.
+#' @noRd
+is_project_context <- function(x) {
+ inherits(x, "project_context")
+}
+
+#' Get project context
+#'
+#' @param x Connection to DataSHIELD server (e.g., OBiBa's Opal server).
+#' @param project String with project name (a single value).
+#' @param rocrate RO-Crate object, that may contain the context for `project`.
+#'
+#' @returns The project context stored in `rocrate`, if it was created for the
+#' same `project` and connection. Otherwise, a new project context.
+#' @keywords internal
+#' @noRd
+get_project_context <- function(x, project, rocrate = NULL) {
+ context <- attr(rocrate, "project_context", exact = TRUE)[[project]]
+
+ if (is_project_context(context) && identical(context$connection, x)) {
+ return(context)
+ }
+
+ new_project_context(x, project)
+}
+
+#' Store project context in an RO-Crate
+#'
+#' @param rocrate RO-Crate object.
+#' @param context Project context object.
+#'
+#' @returns Updated `rocrate` object. The contexts of other projects are kept.
+#' @keywords internal
+#' @noRd
+set_project_context <- function(rocrate, context) {
+ contexts <- attr(rocrate, "project_context", exact = TRUE)
+ if (is.null(contexts)) {
+ contexts <- list()
+ }
+ contexts[[context$project]] <- context
+ attr(rocrate, "project_context") <- contexts
+ rocrate
+}
+
+#' Remove the project contexts from an RO-Crate
+#'
+#' @param rocrate RO-Crate object.
+#'
+#' @returns Updated `rocrate` object.
+#' @keywords internal
+#' @noRd
+reset_project_context <- function(rocrate) {
+ attr(rocrate, "project_context") <- NULL
+ rocrate
+}
+
+#' Verify that the project exists (once)
+#'
+#' Only successful checks are remembered, so a missing project is reported every
+#' time.
+#'
+#' @param context Project context object.
+#'
+#' @returns `TRUE`, invisibly. If the project does not exist, an error is
+#' thrown.
+#' @keywords internal
+#' @noRd
+project_context_exists <- function(context) {
+ if (!isTRUE(context$cache$exists)) {
+ project_exists(context$connection, project = context$project)
+ assign("exists", TRUE, envir = context$cache)
+ }
+ invisible(TRUE)
+}
+
+#' Get the project assets (once)
+#'
+#' @inheritParams project_context_exists
+#' @param type Type of assets to extract, either `tables` or `resources`.
+#'
+#' @returns Tibble with project assets details, or `NULL` if there are none.
+#' @keywords internal
+#' @noRd
+project_context_assets <- function(context, type = c("tables", "resources")) {
+ type <- match.arg(type)
+
+ if (!exists(type, envir = context$cache, inherits = FALSE)) {
+ project_context_exists(context)
+ assets <- get_project_assets(
+ context$connection,
+ context$project,
+ type,
+ check = FALSE
+ )
+ # NOTE: `NULL` (no assets) is also remembered
+ assign(type, assets, envir = context$cache)
+ }
+
+ get(type, envir = context$cache, inherits = FALSE)
+}
+
+
+#' Get the permissions of a project, or of one of its assets (once)
+#'
+#' @inheritParams project_context_exists
+#' @param type Type of permissions to extract: `project`, `table` or
+#' `resource`.
+#' @param asset String with the name of the table or resource (required for
+#' `type` `table` or `resource`).
+#'
+#' @returns Data frame with the permissions (`subject`, `type` and
+#' `permission`).
+#' @keywords internal
+#' @noRd
+project_context_permissions <- function(
+ context,
+ type = c("project", "table", "resource"),
+ asset = NULL
+) {
+ type <- match.arg(type)
+
+ if (type != "project" && (is.null(asset) || length(asset) != 1)) {
+ stop("A single `asset` name is required for `", type, "`!", call. = FALSE)
+ }
+
+ key <- if (type == "project") {
+ "project_permissions"
+ } else {
+ paste0(type, "_permissions_", asset)
+ }
+
+ if (!exists(key, envir = context$cache, inherits = FALSE)) {
+ permissions <- switch(
+ type,
+ project = backend_project_perms(
+ context$connection,
+ context$project
+ ),
+ table = backend_table_perms(
+ context$connection,
+ context$project,
+ asset
+ ),
+ resource = backend_resource_perms(
+ context$connection,
+ context$project,
+ asset
+ )
+ )
+
+ assign(key, permissions, envir = context$cache)
+ }
+
+ get(key, envir = context$cache, inherits = FALSE)
+}
+
+#' Get the users with access to a project
+#'
+#' The permissions are retrieved from the context, so they are requested once
+#' and shared with the other `safe_*()` functions.
+#'
+#' @inheritParams project_context_exists
+#' @param tables,resources Vector of strings with the names of the tables or
+#' resources to consider (default: `NULL`, all of them).
+#'
+#' @returns Tibble with columns `subject`, `type`, `permission`, `via` and
+#' `asset`: the permissions on the project and on the selected tables and
+#' resources (see `backend_project_members()`).
+#' @keywords internal
+#' @noRd
+project_context_members <- function(context, tables = NULL, resources = NULL) {
+ # names of the assets to consider (`character(0)` if there are none)
+ asset_names <- function(type, selected) {
+ assets <- project_context_assets(context, type)
+ names <- if (is.null(assets)) character(0) else assets$name
+ if (is.null(selected)) names else intersect(names, selected)
+ }
+
+ backend_project_members(
+ context$connection,
+ project = context$project,
+ tables = asset_names("tables", tables),
+ resources = asset_names("resources", resources),
+ permissions = \(type, asset = NULL) {
+ project_context_permissions(context, type, asset)
+ }
+ )
+}
diff --git a/R/utils-report.R b/R/utils-report.R
new file mode 100644
index 0000000..4363204
--- /dev/null
+++ b/R/utils-report.R
@@ -0,0 +1,872 @@
+#' Break tibble by group, `varname`
+#'
+#' @param df Data frame to be broken down into groups.
+#' @param varname String with variable name
+#'
+#' @returns String with data frame rendered with `kable`.
+#' @keywords internal
+#' @noRd
+.break_tibble <- function(df, varname) {
+ # local bindings
+ temp <- NULL
+
+ # if `varname` is NULL or not a column in `df`, render all the data
+ if (is.null(varname) || !(varname %in% colnames(df))) {
+ return(knitr::kable(df))
+ }
+
+ # extract unique values for `varname` in `df`
+ unique_vals <- unique(getElement(df, varname))
+
+ # render data frame based on groups
+ sapply(unique_vals, function(v) {
+ c(
+ paste0("\n#### '", v, "' ", varname, "\n"),
+ df |>
+ dplyr::rename(temp = !!varname) |>
+ dplyr::filter(temp == v) |>
+ dplyr::select(-temp) |>
+ # drop out empty columns, equivalent to `janitor::remove_empty`
+ Filter(f = function(x) any(!is.na(x))) |>
+ knitr::kable()
+ ) |>
+ paste0(collapse = "\n")
+ })
+}
+
+#' Get the root directory of an RO-Crate stored on disk
+#'
+#' The files referenced by the RO-Crate (e.g., logs) are stored in the root
+#' directory, next to the metadata file.
+#'
+#' @param x String with the path to an RO-Crate: either its metadata file
+#' (`.json`) or its directory.
+#'
+#' @returns String with the path to the root directory of the RO-Crate, or
+#' `NULL` if it cannot be determined (e.g., for archives).
+#' @keywords internal
+#' @noRd
+.crate_root <- function(x) {
+ if (!is.character(x) || length(x) != 1) {
+ return(NULL)
+ }
+
+ if (dir.exists(x)) {
+ # the files of BagIt directories are not stored in the root directory
+ if (file.exists(file.path(x, "bagit.txt"))) {
+ return(NULL)
+ }
+ return(x)
+ }
+
+ if (grepl("\\.json$", x)) {
+ return(dirname(x))
+ }
+
+ NULL
+}
+
+
+#' Combine the report tables of several RO-Crates (one per server)
+#'
+#' @param crate_tables Named list with the output of `.report_tables()` for
+#' each RO-Crate. The names are used as the server names.
+#'
+#' @returns List with the combined tables (each with a `server` column):
+#' `overview_tbl`, `safe_people`, `safe_project`, `safe_data`,
+#' `safe_data_permissions`, `safe_setting` and `safe_output`.
+#' @keywords internal
+#' @noRd
+.combine_report_tables <- function(crate_tables) {
+ # local bindings
+ permission <- NULL
+
+ # the overview table of each server already combines its permissions, people
+ # and projects, so the servers only need to be put together
+ overview_tbl <- crate_tables |>
+ lapply(getElement, name = "overview_tbl") |>
+ # attach the server name as a new column
+ purrr::imap(~ dplyr::mutate(.x, server = .y)) |>
+ # combine rows
+ dplyr::bind_rows()
+
+ # servers without permissions have no access level
+ if ("permission" %in% colnames(overview_tbl)) {
+ overview_tbl <- overview_tbl |>
+ dplyr::mutate(permission = dplyr::coalesce(permission, ""))
+ }
+
+ list(
+ overview_tbl = overview_tbl,
+ safe_people = .extract_srvr_comp(crate_tables, "safe_people"),
+ safe_project = .extract_srvr_comp(crate_tables, "safe_project"),
+ safe_data = .extract_srvr_comp(crate_tables, "safe_data"),
+ safe_data_permissions = .extract_srvr_comp(
+ crate_tables,
+ "safe_data_permissions"
+ ),
+ safe_setting = .extract_srvr_comp(crate_tables, "safe_setting"),
+ safe_output = .extract_srvr_comp(crate_tables, "safe_output")
+ )
+}
+
+.extract_srvr_comp <- function(x, component) {
+ tryCatch(
+ {
+ x |>
+ # extract each component per server
+ purrr::map(component) |>
+ # filter out NULL elements
+ purrr::keep(\(x) !is.null(x)) |>
+ # attach the server name as a new column
+ purrr::imap(~ dplyr::mutate(.x, server = .y)) |>
+ # combine rows
+ dplyr::bind_rows()
+ },
+ error = function(e) {
+ NULL
+ }
+ )
+}
+
+#' Helper to generate report
+#' @noRd
+.generate_report <- function(
+ overview_tbl,
+ safe_people_tbl,
+ safe_project_tbl,
+ safe_data_tbl,
+ safe_user_perm_tbl,
+ safe_setting_tbl,
+ safe_output_tbl,
+ rocrates,
+ title = "DataSHIELD Report",
+ filepath = tempfile(fileext = ".md"),
+ render = TRUE,
+ doc_format = "html",
+ overwrite = FALSE,
+ include_user_perm = TRUE,
+ diag_title = "DataSHIELD server",
+ max_line_length = 200,
+ break_by = NULL
+) {
+ # generate overview diagram
+ overview_lst <- .overview_diagram(
+ overview_tbl,
+ include_user_perm,
+ filepath,
+ render,
+ diag_title
+ )
+
+ # generate tidy overview
+ tidy_overview_tbl <- .tidy_overview(overview_tbl, include_user_perm)
+
+ # generate Markdown header
+ report_contents <- c(
+ .markdown_report_header(title, overview_tbl, overview_lst$diag_path),
+ tidy_overview_tbl |>
+ dplyr::distinct() |>
+ knitr::kable() |>
+ paste0(collapse = "\n")
+ )
+
+ # generate Markdown body
+ ## attach entities for 5 safes
+ report_contents <- .markdown_report_body(
+ report_contents = report_contents,
+ overview_tbl = overview_tbl,
+ safe_people_tbl = safe_people_tbl,
+ safe_project_tbl = safe_project_tbl,
+ safe_data_tbl = safe_data_tbl,
+ safe_user_perm_tbl = safe_user_perm_tbl,
+ safe_setting_tbl = safe_setting_tbl,
+ safe_output_tbl = safe_output_tbl,
+ break_by = break_by
+ )
+
+ report_contents <- c(report_contents, "\n
\n")
+
+ # append RO-Crates (the contents were already loaded)
+ for (i in seq_along(rocrates)) {
+ # a single RO-Crate (without name) is not labelled as a server
+ section_txt <- "## RO-Crate"
+ if (!is.null(names(rocrates))) {
+ section_txt <- ifelse(
+ i == 1,
+ paste0("## RO-Crates\n### '", names(rocrates)[i], "' server"),
+ paste0("### '", names(rocrates)[i], "' server")
+ )
+ }
+
+ report_contents <- .markdown_report_rocrate(
+ report_contents = report_contents,
+ rocrate = rocrates[[i]],
+ section_txt = section_txt,
+ max_line_length = max_line_length
+ )
+ }
+
+ # write Markdown
+ ### delete previous version
+ if (overwrite) {
+ unlink(filepath, recursive = TRUE, force = TRUE)
+ }
+ writeLines(report_contents, filepath)
+
+ # render document
+ if (render) {
+ if (tolower(doc_format) %in% c("html", "html_document")) {
+ suppressWarnings({
+ rmarkdown::render(
+ filepath,
+ "html_document",
+ sub(".md$", ".html", filepath)
+ )
+ utils::browseURL(paste0("file://", sub(".md$", ".html", filepath)))
+ })
+ } else if (tolower(doc_format) %in% c("pdf", "pdf_document")) {
+ suppressWarnings({
+ rmarkdown::render(
+ filepath,
+ "pdf_document",
+ sub(".md$", ".pdf", filepath)
+ )
+ utils::browseURL(paste0("file://", sub(".md$", ".pdf", filepath)))
+ })
+ } else {
+ stop("The format `", doc_format, "` is not valid! Try 'html' or 'pdf'.")
+ }
+ } else {
+ return(invisible(
+ list(
+ overview_diagram = overview_lst$diag_lst,
+ overview_data = tidy_overview_tbl,
+ safe_people = safe_people_tbl,
+ safe_project = safe_project_tbl,
+ safe_data = safe_data_tbl,
+ safe_data_permissions = safe_user_perm_tbl,
+ safe_setting = safe_setting_tbl,
+ safe_output = safe_output_tbl
+ )
+ ))
+ }
+
+ message("A report has been written to:\n ", filepath)
+
+ # return list of data frames with Safe People, Projects, Data, etc.
+ invisible(
+ list(
+ safe_people = safe_people_tbl,
+ safe_project = safe_project_tbl,
+ safe_data = safe_data_tbl,
+ safe_data_permissions = safe_user_perm_tbl,
+ safe_setting = safe_setting_tbl,
+ safe_output = safe_output_tbl
+ )
+ )
+}
+
+#' Generate Markdown report's header
+#'
+#' @inheritParams .overview_diagram
+#' @inheritParams report
+#'
+#' @returns String with report's header
+#' @keywords internal
+#' @noRd
+.markdown_report_header <- function(title, overview_tbl, diagram_filepath) {
+ # initialise variables for the report header
+ unique_users_vct <- unique(c(
+ getElement(overview_tbl, "name"),
+ getElement(overview_tbl, "user")
+ ))
+ unique_project_vct <- unique(getElement(overview_tbl, "project"))
+ unique_servers_vct <- unique(getElement(overview_tbl, "server"))
+ ## init. markdown header (see https://rmarkdown.rstudio.com/lesson-9.html)
+ paste0(
+ "---\n",
+ paste0("title: ", title),
+ "\noutput:\n",
+ " pdf_document:\n",
+ " df_print: kable\n",
+ " highlight: tango\n",
+ " html_document: default\n",
+ "fontsize: 11pt\n",
+ "geometry:\n",
+ " - margin=.5in\n",
+ " - landscape\n",
+ "header-includes: \n",
+ " - \\usepackage{array}\n",
+ " - \\usepackage{longtable}\n",
+ " - \\usepackage{xurl}\n",
+ " - \\usepackage{hyphenat}\n",
+ " - \\usepackage{microtype}\n",
+ " - \\sloppy\n",
+ " - \\setlength{\\emergencystretch}{3em}\n",
+ " - \\usepackage{float}\n",
+ " - \\usepackage{titling}\n",
+ " - \\setlength{\\droptitle}{-1.5cm}\n",
+ " - \\usepackage[breakable]{tcolorbox}\n",
+ " - \\usepackage{tcolorbox}\n",
+ " - \\tcbuselibrary{breakable}\n",
+ " - \\renewenvironment{Shaded}{\\begin{tcolorbox}[breakable, ",
+ "boxrule = 0pt, colback = gray!10]}{\\end{tcolorbox}}\n",
+ paste0("date: ", format(Sys.time(), "%Y-%m-%d %H:%M:%S", tz = "UTC")),
+ "\n---\n",
+ paste0(
+ "This report contains details for ",
+ length(unique_users_vct),
+ " user",
+ ifelse(length(unique_users_vct) > 1, "s", ""),
+ " and ",
+ length(unique_project_vct),
+ " project",
+ ifelse(length(unique_project_vct) > 1, "s", ""),
+ ". In addition, the tables they have access to within",
+ ifelse(length(unique_project_vct) > 1, " a ", " the "),
+ "project. \n",
+ ifelse(
+ "server" %in% colnames(overview_tbl),
+ paste0(
+ "\n**Note:** the data shown in this report was extracted from ",
+ length(unique_servers_vct),
+ " server",
+ ifelse(length(unique_servers_vct) > 1, "s", ""),
+ "."
+ ),
+ ""
+ ),
+ "\n\n"
+ ),
+ "## Overview\n\n",
+ "\n",
+ "\n",
+ "```{=latex}\n",
+ paste0(
+ "\\begin{figure}[H]\n",
+ "\\centering\n",
+ "\\includegraphics[height = 0.75\\textheight, keepaspectratio, ",
+ "width = 0.9\\textwidth]{",
+ diagram_filepath,
+ "}",
+ "\\caption{RO-Crate Overview}\n",
+ "\\end{figure}\n```\n"
+ ),
+ "",
+ "```{=html}\n",
+ paste0(
+ "

\n"
+ ),
+ "```\n
\n\n\\newpage"
+ )
+}
+
+#' Generate Markdown report's body
+#'
+#' @inheritParams .overview_diagram
+#' @param report_contents String with Markdown report (e.g., header).
+#' @param safe_people_tbl Data frame with Safe People details.
+#' @param safe_project_tbl Data frame with Safe Project details.
+#' @param safe_data_tbl Data frame with Safe Data details.
+#' @param safe_user_perm_tbl Data frame with Safe Data user permissions.
+#' @param safe_setting_tbl Data frame with Safe Setting details.
+#' @param safe_output_tbl Data frame with Safe Output details.
+#' @param break_by Optional string with variable to be used for breaking down
+#' each table (e.g., server), as opposed to display all the results in a
+#' single table.
+#'
+#' @returns String with updated Markdown report.
+#' @keywords internal
+#' @noRd
+.markdown_report_body <- function(
+ report_contents,
+ overview_tbl,
+ safe_people_tbl,
+ safe_project_tbl,
+ safe_data_tbl,
+ safe_user_perm_tbl,
+ safe_setting_tbl,
+ safe_output_tbl,
+ break_by = NULL
+) {
+ # local bindings
+ actionStatus <- description <- permission <- NULL
+
+ report_contents <- c(report_contents, "\n
\n", "## Entities")
+
+ ## append Safe People details
+ report_contents <- c(
+ report_contents,
+ "\n### People\n",
+ safe_people_tbl |>
+ .break_tibble(varname = break_by) |>
+ paste0(collapse = "\n")
+ )
+
+ ## append Safe Project & Safe Data details
+ report_contents <- c(
+ report_contents,
+ "### Project(s)\n",
+ safe_project_tbl |>
+ .break_tibble(varname = break_by) |>
+ paste0(collapse = "\n")
+ )
+
+ ## append Safe Data details
+ report_contents <- c(
+ report_contents,
+ "### Data\n",
+ safe_data_tbl |>
+ .break_tibble(varname = break_by) |>
+ paste0(collapse = "\n")
+ )
+
+ ## append Safe Data permissions
+ #### check if `overview_tbl` has `permission` field
+ if ("permission" %in% colnames(overview_tbl)) {
+ report_contents <- c(
+ report_contents,
+ "#### Data permissions\n",
+ safe_user_perm_tbl |>
+ dplyr::select(-actionStatus, -description, -permission) |>
+ .break_tibble(varname = break_by) |>
+ paste0(collapse = "\n")
+ )
+ }
+
+ ## append Safe Settings details
+ report_contents <- c(
+ report_contents,
+ "### Settings\n",
+ safe_setting_tbl |>
+ .break_tibble(varname = break_by) |>
+ paste0(collapse = "\n")
+ )
+
+ if (!is.null(safe_output_tbl) && nrow(safe_output_tbl) > 0) {
+ ## append Safe Outputs details
+ report_contents <- c(
+ report_contents,
+ "### Outputs\n",
+ safe_output_tbl |>
+ .break_tibble(varname = break_by) |>
+ paste0(collapse = "\n")
+ )
+ }
+
+ report_contents
+}
+
+#' Embed RO-Crate in Markdown report
+#'
+#' @inheritParams .markdown_report_body
+#' @param rocrate RO-Crate object (see [rocrateR::rocrate]).
+#' @param section_txt String with to be used as the section header
+#' (e.g., RO-Crate).
+#'
+#' @returns String with update Markdown report.
+#' @keywords internal
+#' @noRd
+.markdown_report_rocrate <- function(
+ report_contents,
+ rocrate,
+ section_txt,
+ max_line_length = 200
+) {
+ # save the input into intermediate JSON file
+ tmp_file <- tempfile(fileext = ".json")
+ # delete temporary file
+ on.exit(unlink(tmp_file, recursive = TRUE, force = TRUE))
+ # store RO-Crate in JSON format
+ jsonlite::write_json(
+ rocrate,
+ path = tmp_file,
+ pretty = TRUE,
+ auto_unbox = TRUE
+ )
+ # load formatted RO-Crate as text
+ rocrate_txt <- readLines(tmp_file) |>
+ # shorten long lines, beyond `max_line_length`
+ sapply(function(x) {
+ if (nchar(x) > max_line_length && max_line_length > 10) {
+ return(paste0(
+ substr(x, 1, max_line_length - 10),
+ "... ...",
+ substr(x, nchar(x) - 10, nchar(x))
+ ))
+ }
+ x
+ })
+ report_contents <- c(
+ report_contents,
+ "\n\\newpage\n",
+ section_txt,
+ "\n```json",
+ # display formatted RO-Crate
+ rocrate_txt,
+ "\n```"
+ )
+}
+
+#' Create diagram for RO-Crate overview
+#'
+#' @param overview_tbl Data frame with overview details for the RO-Crate.
+#' @inheritParams report
+#'
+#' @returns Diagram object
+#' @keywords internal
+#' @noRd
+.overview_diagram <- function(
+ overview_tbl,
+ include_user_perm,
+ filepath,
+ render,
+ diag_title
+) {
+ # local bindings
+ fx <- permission <- NULL
+
+ ## initialise `vars` and `labelvar`
+ vars <- c("project", "asset")
+ labelvar <- c(project = "Project", asset = "Data")
+
+ # check if `overview_tbl` has `permission` field AND include_user_perm = TRUE
+ if ("permission" %in% colnames(overview_tbl) && include_user_perm) {
+ vars <- c(vars, "permission")
+ labelvar <- c(labelvar, permission = "Access Level")
+ }
+
+ # attach name/user and label it 'People'
+ vars <- c(vars, "name")
+ labelvar <- c(labelvar, name = "People")
+
+ # check if `overview_tbl` has a `fx` field
+ if ("fx" %in% colnames(overview_tbl)) {
+ vars <- c(vars, "fx")
+ labelvar <- c(labelvar, fx = "Function")
+
+ # replace 'NA' with empty string for `fx`
+ overview_tbl <- overview_tbl |>
+ dplyr::mutate(fx = ifelse(is.na(fx), "", fx))
+ }
+
+ # attach 'server' if found in `overview_tbl`
+ if ("server" %in% colnames(overview_tbl)) {
+ vars <- c("server", vars)
+ labelvar <- c(server = "Server", labelvar)
+ }
+
+ # aggregate the data if `permission` exists in `overview_tbl`
+ if ("permission" %in% colnames(overview_tbl)) {
+ overview_agg <- overview_tbl |>
+ dplyr::group_by(dplyr::pick(vars[vars != "permission"])) |>
+ dplyr::reframe(
+ permission = paste0(unique(permission), collapse = " & "),
+ )
+ } else {
+ overview_agg <- overview_tbl
+ }
+
+ ## generate diagram
+ diagram_lst <- overview_agg |>
+ vtree::vtree(
+ vars = vars,
+ labelvar = labelvar,
+ showpct = FALSE,
+ showcount = FALSE,
+ horiz = FALSE,
+ varnamebold = TRUE,
+ splitwidth = 1,
+ vsplitwidth = 1,
+ folder = dirname(filepath),
+ title = diag_title,
+ pngknit = render,
+ prune = list(fx = "")
+ )
+
+ ## if `render = TRUE`, then render diagram as PNG
+ diagram_filepath <- NULL
+
+ if (render) {
+ diagram_filepath <- diagram_lst |>
+ vtree::grVizToImageFile(
+ folder = dirname(filepath),
+ filename = gsub("md$", "png", basename(filepath))
+ )
+ }
+
+ list(diag_lst = diagram_lst, diag_path = diagram_filepath)
+}
+
+#' Extract the tables needed to report on an RO-Crate
+#'
+#' Extracts the Five Safes details from an RO-Crate and combines them in an
+#' overview table. This is shared by the reports for a single RO-Crate and for
+#' a list of RO-Crates.
+#'
+#' @param x RO-Crate object. If it has a `path` attribute, the contents of its
+#' `File` entities are loaded from that directory.
+#'
+#' @returns List with the elements `rocrate` (RO-Crate with the contents
+#' loaded), `overview_tbl` (overview table), `safe_people`, `safe_project`,
+#' `safe_data`, `safe_data_permissions`, `safe_setting` and `safe_output`
+#' (tables).
+#' @keywords internal
+#' @noRd
+.report_tables <- function(x) {
+ # local bindings
+ asset <- encodingFormat <- fx <- name <- permission <- NULL
+ perm_id <- person_id <- project <- timestamp <- user <- NULL
+ asset_id <- NULL
+
+ # check if the input object has a `path` attribute
+ roc_path <- get_crate_context(x, "path")
+ if (!is.null(roc_path)) {
+ # check if any of the entities with `@type = 'File'` have empty `content`
+ x <- x |>
+ load_content(roc_path = roc_path)
+ }
+
+ # extract details for ... ----
+ ## Safe People ----
+ safe_people_rocrate <- .try_load(extract_safe_people(x))$value
+
+ ## Safe Data ----
+ safe_data_rocrate <- .try_load(extract_safe_data(x))$value
+
+ # attempt to extract user permission entities
+ user_perm_entity_lst <- .try_load(
+ x |>
+ .get_entity(type = c("ReadAction", "WriteAction", "ControlAction"))
+ )$value
+
+ ## Safe Projects ----
+ # extract project IDs from the Safe People RO-Crate
+ member_of <- .try_load(
+ safe_people_rocrate |>
+ .get_entity(type = "Person") |>
+ sapply(\(x) getElement(x, "memberOf")) |>
+ unlist()
+ )$value
+
+ # use Safe People membership to extract Project details
+ safe_project_rocrate <- .try_load(
+ extract_safe_project(x, id = member_of)
+ )$value
+
+ ## Safe Settings ----
+ safe_setting_rocrate <- .try_load(extract_safe_setting(x))$value
+
+ ## Safe Outputs ----
+ safe_outputs_rocrate <- .try_load(extract_safe_output(x))$value
+
+ # verify contents of RO-Crate ----
+ has_project_ents <- !is.null(safe_project_rocrate)
+ has_data_ents <- !is.null(safe_data_rocrate)
+ has_people_ents <- !is.null(safe_people_rocrate)
+
+ # if not all these flags are `TRUE`, return error message
+ if (!all(has_project_ents, has_data_ents, has_people_ents)) {
+ stop(
+ paste0(
+ "The given RO-Crate is missing the following:",
+ ifelse(has_project_ents, "", " - Project entity (`@type = 'Project'`)"),
+ ifelse(has_data_ents, "", " - Data entity (`@type = 'Dataset'`)"),
+ ifelse(has_people_ents, "", " - People entity (`type = 'Person'`)"),
+ collapse = "\n"
+ ),
+ call. = FALSE
+ )
+ }
+
+ # flatten the entities into tables ----
+ ### extract (if available) table with user permissions
+ user_perm_tbl <- flatten_user_perm_entity(user_perm_entity_lst)
+ ### extract table with Safe People details
+ safe_people_tbl <- flatten_safe_people(safe_people_rocrate)
+ ### extract table with Safe Project details
+ safe_project_tbl <- flatten_safe_project(safe_project_rocrate)
+ ### extract table with Safe Data details
+ safe_data_tbl <- flatten_safe_data(safe_data_rocrate)
+
+ # create overview ----
+ overview_tbl <- tibble::tibble()
+ if (!is.null(user_perm_tbl) && nrow(user_perm_tbl) > 0) {
+ overview_tbl <- user_perm_tbl |>
+ # combine with Safe People details
+ dplyr::left_join(safe_people_tbl, by = "person_id") |>
+ # subset columns of interest
+ dplyr::select(perm_id, person_id, name, asset_id, permission) |>
+ # combine with Safe Data details
+ dplyr::left_join(safe_data_tbl, by = "asset_id") |>
+ # combine with Safe Project details
+ dplyr::left_join(safe_project_tbl, by = c("asset_id", "asset"))
+ } else {
+ overview_tbl <- safe_people_tbl |>
+ purrr::pmap(function(person_id, name, ...) {
+ tibble::tibble(person_id, name) |>
+ dplyr::bind_cols(safe_project_tbl)
+ }) |>
+ purrr::list_c()
+ }
+
+ # attempt extracting list of functions executed by the users from Safe Outputs
+ safe_output_tbl <- flatten_safe_output(safe_outputs_rocrate) |>
+ # extract only entities with mappings and functions, stored in CSV format
+ dplyr::filter(encodingFormat == "text/csv") |>
+ # extract content
+ purrr::pluck("content", .default = list()) |>
+ purrr::list_flatten() |>
+ purrr::map(tibble::as_tibble) |>
+ purrr::list_rbind()
+
+ # initialise safe_output_tbl_v2, to be included in the returned outputs
+ safe_output_tbl_v2 <- tibble::tibble()
+
+ if (!is.null(safe_output_tbl) && nrow(safe_output_tbl) > 0) {
+ # split `asset` into `project` and `asset`
+ safe_output_tbl_v2 <- safe_output_tbl |>
+ dplyr::mutate(
+ project = gsub("(?=\\.).*$", "", asset, perl = TRUE),
+ asset = gsub("^.*(?<=\\.)", "", asset, perl = TRUE)
+ ) |>
+ dplyr::distinct(project, asset, user, fx, timestamp)
+
+ # append the list of functions to the overview table
+ overview_tbl <- overview_tbl |>
+ dplyr::left_join(
+ safe_output_tbl_v2,
+ by = c("project" = "project", "asset" = "asset", "name" = "user")
+ ) |>
+ # replace 'NA' in fx & timestamp with empty string
+ dplyr::mutate(
+ timestamp = dplyr::case_when(is.na(timestamp) ~ "", TRUE ~ timestamp),
+ fx = dplyr::case_when(is.na(fx) ~ "", TRUE ~ fx)
+ )
+ }
+
+ list(
+ rocrate = x,
+ overview_tbl = overview_tbl,
+ safe_people = safe_people_tbl,
+ safe_project = safe_project_tbl,
+ safe_data = safe_data_tbl,
+ safe_data_permissions = user_perm_tbl,
+ safe_setting = flatten_safe_setting(safe_setting_rocrate),
+ safe_output = safe_output_tbl_v2
+ )
+}
+
+#' Create tidy version of the overview table
+#'
+#' @inheritParams .overview_diagram
+#'
+#' @returns Data frame with tidy overview table.
+#' @keywords internal
+#' @noRd
+.tidy_overview <- function(overview_tbl, include_user_perm) {
+ # local bindings
+ fx <- permission <- timestamp <- NULL
+
+ ## initialise `vars` and `varslab`
+ vars <- c("project", "asset")
+ varslab <- c("Project" = "project", "Data" = "asset")
+
+ # check if `overview_tbl` has `permission` field AND include_user_perm = TRUE
+ if ("permission" %in% colnames(overview_tbl) && include_user_perm) {
+ vars <- c(vars, "permission")
+ varslab <- c(varslab, "Access Level" = "permission")
+ }
+
+ # attach name/user and label it 'People'
+ vars <- c(vars, "name")
+ varslab <- c(varslab, "People" = "name")
+
+ # check if `overview_tbl` has a `fx` field
+ if ("fx" %in% colnames(overview_tbl)) {
+ vars <- c(vars, "fx", "timestamp")
+ varslab <- c(
+ varslab,
+ "Function" = "fx",
+ "Timestamp" = "timestamp"
+ )
+
+ # replace 'NA' with empty string for `fx` and `timestamp`
+ overview_tbl <- overview_tbl |>
+ dplyr::mutate(
+ fx = ifelse(is.na(fx), "", fx),
+ timestamp = ifelse(is.na(timestamp), "", timestamp)
+ )
+ }
+
+ # attach 'server' if found in `overview_tbl`
+ if ("server" %in% colnames(overview_tbl)) {
+ vars <- c("server", vars)
+ varslab <- c("Server" = "server", varslab)
+ }
+
+ # create tidy data frame
+ tidy_overview_tbl <- overview_tbl |>
+ dplyr::distinct(dplyr::pick(dplyr::all_of(vars)))
+
+ if ("permission" %in% colnames(overview_tbl)) {
+ if ("fx" %in% colnames(overview_tbl)) {
+ vars_agg <- vars[!vars %in% c("permission", "fx", "timestamp")]
+ tidy_overview_tbl <- tidy_overview_tbl |>
+ dplyr::group_by(dplyr::pick(dplyr::all_of(vars_agg))) |>
+ dplyr::reframe(
+ permission = paste0(unique(permission), collapse = " & "),
+ fx = fx,
+ timestamp = timestamp,
+ .groups = "drop"
+ )
+ } else {
+ tidy_overview_tbl <- tidy_overview_tbl |>
+ dplyr::group_by(dplyr::pick(vars[vars != "permission"])) |>
+ dplyr::reframe(
+ permission = paste0(unique(permission), collapse = " & ")
+ )
+ }
+ }
+
+ tidy_overview_tbl |>
+ dplyr::select(dplyr::all_of(varslab)) |>
+ dplyr::distinct()
+}
+
+#' Validate the file path of a report
+#'
+#' @param filepath String with the path to the report (markdown) file.
+#' @param overwrite Boolean flag to indicate if an existing file can be
+#' overwritten.
+#'
+#' @returns `TRUE`, invisibly. If the path is not valid, an error is thrown.
+#' @keywords internal
+#' @noRd
+.validate_report_path <- function(filepath, overwrite) {
+ # ensure the given file path exists
+ if (!dir.exists(dirname(filepath))) {
+ stop(
+ "The given file path directory does not exist. Try running the ",
+ "following command first:\n\t`mkdir -p ",
+ dirname(filepath),
+ "`",
+ call. = FALSE
+ )
+ }
+
+ # check if the filepath points to an existing file
+ if (file.exists(filepath) && !overwrite) {
+ stop(
+ "The given file path points to an existing file. Try setting ",
+ "`overwrite = TRUE` or changing the file path!",
+ call. = FALSE
+ )
+ }
+
+ invisible(TRUE)
+}
diff --git a/R/utils-rocrate.R b/R/utils-rocrate.R
index 3b2e978..2ff3d13 100644
--- a/R/utils-rocrate.R
+++ b/R/utils-rocrate.R
@@ -3,7 +3,7 @@
#' @param rocrate Object with the [rocrate][rocrateR::rocrate()] class.
#' @param roc_path String with path to the root of the RO-Crate.
#'
-#' @returns Update `rocrate` object.
+#' @returns Updated `rocrate` object.
#' @keywords internal
#' @noRd
load_content <- function(rocrate, roc_path) {
@@ -41,5 +41,91 @@ load_content <- function(rocrate, roc_path) {
}
}
- return(rocrate)
+ rocrate
+}
+
+#' Get RO-Crate context/attributes
+#'
+#' Reads the context stored in an RO-Crate by `set_crate_context()`, e.g., the
+#' connection and the Five Safes details given to [init()].
+#'
+#' @param rocrate RO-Crate object.
+#' @param which String with the name of a single context value to extract (one
+#' of `attrs`). If `NULL` (default), all the values are
+#' returned.
+#'
+#' @returns The requested value (`NULL` if it was not set) or, if `which` is
+#' `NULL`, a named list with all the context values.
+#' @keywords internal
+#' @noRd
+get_crate_context <- function(rocrate, which = NULL) {
+ attrs <- c(
+ "connection",
+ "path",
+ "profile",
+ "project",
+ "resources",
+ "tables",
+ "user",
+ "backend_validated"
+ )
+ if (is.null(which)) {
+ ctx <- attrs |>
+ lapply(\(field) attr(rocrate, field, exact = TRUE))
+ return(stats::setNames(ctx, attrs))
+ }
+
+ if (!is.character(which) || length(which) != 1 || !which %in% attrs) {
+ stop(
+ sprintf(
+ "`which` must be one of: %s.",
+ paste0("`", attrs, "`", collapse = ", ")
+ ),
+ call. = FALSE
+ )
+ }
+
+ # NOTE: no partial matching, e.g., `path` must not match `pathway`
+ attr(rocrate, which, exact = TRUE)
+}
+
+#' Set RO-Crate context/attributes
+#'
+#' Stores the connection and the Five Safes details in the attributes of an
+#' RO-Crate, so that the `safe_*()` functions need no further arguments.
+#' Values that are `NULL` remove the corresponding attribute.
+#'
+#' @param rocrate RO-Crate object.
+#' @param connection,path,profile,project,resources,tables,user Context values
+#' (see `attrs`).
+#' @param validated Boolean flag to indicate that the backend `connection` has
+#' been validated (see `validate_backend()`). It must only be `TRUE` when
+#' the caller has validated the connection (default: `FALSE`, so the
+#' connection is validated again by the next function).
+#'
+#' @returns Updated `rocrate` object.
+#' @keywords internal
+#' @noRd
+set_crate_context <- function(
+ rocrate,
+ connection = NULL,
+ path = NULL,
+ profile = NULL,
+ project = NULL,
+ resources = NULL,
+ tables = NULL,
+ user = NULL,
+ validated = FALSE
+) {
+ # attach input arguments as attributes
+ attr(rocrate, "connection") <- connection
+ attr(rocrate, "path") <- path
+ attr(rocrate, "profile") <- profile
+ attr(rocrate, "project") <- project
+ attr(rocrate, "resources") <- resources
+ attr(rocrate, "tables") <- tables
+ attr(rocrate, "user") <- user
+ # only trusted when the caller validated the backend connection
+ attr(rocrate, "backend_validated") <- isTRUE(validated)
+ rocrate
}
diff --git a/R/utils-safe_data.R b/R/utils-safe_data.R
index 2782ce7..01249c4 100644
--- a/R/utils-safe_data.R
+++ b/R/utils-safe_data.R
@@ -12,24 +12,6 @@ extract_safe_data <- function(x, ...) {
UseMethod("extract_safe_data")
}
-#' @export
-extract_safe_data.opal <- function(x, ..., rocrate = rocrateR::rocrate_5s()) {
- # extract list with all projects
- ds <- backend_projects(x)
-
- # extract project names and ignore NAs
- projects <- ds$name[!is.na(ds$name) & !is.null(ds$name)]
-
- # create RO-Crate with Safe Data details for the projects found on the server
- purrr::reduce(
- projects,
- \(crate, p) {
- safe_data(crate, connection = x, project = p)
- },
- .init = rocrate
- )
-}
-
#' @export
extract_safe_data.rocrate <- function(
x,
@@ -86,7 +68,7 @@ flatten_safe_data <- function(x, ...) {
#' @export
flatten_safe_data.default <- function(x, ...) {
- return(tibble::tibble())
+ tibble::tibble()
}
#' @export
@@ -97,7 +79,7 @@ flatten_safe_data.rocrate <- function(
asset_id_suffix = "#asset:"
) {
# local bindings
- asset_id <- person_id <- NULL
+ asset_id <- NULL
tryCatch(
{
diff --git a/R/utils-safe_output.R b/R/utils-safe_output.R
index d8fc080..f8f4ebe 100644
--- a/R/utils-safe_output.R
+++ b/R/utils-safe_output.R
@@ -36,13 +36,11 @@ calls_to_tbl <- function(calls, registry) {
fx = paste0(x$package, x$namespace, x$fx),
args = list(x$args),
symbol = NA_character_,
- table = x$args |>
- purrr::map(function(x) {
- if (!inherits(x, "safe_reference")) {
- return(NA_character_)
- }
- resolve_symbol_asset(x$symbol_id, registry)
- }),
+ table = list(
+ x$args |>
+ purrr::keep(\(arg) inherits(arg, "safe_reference")) |>
+ purrr::map_chr(\(arg) resolve_symbol_asset(arg$symbol_id, registry))
+ ),
session = x$session,
profile = x$profile
)
@@ -65,30 +63,6 @@ extract_safe_output <- function(x, ...) {
UseMethod("extract_safe_output")
}
-#' @export
-extract_safe_output.opal <- function(
- x,
- ...,
- path = NULL,
- user = NULL,
- logs_to = Sys.time(),
- logs_from = logs_to - 24 * 60^2,
- rocrate = rocrateR::rocrate_5s()
-) {
- # extract all the Safe Outputs for the current Opal connection
- rocrate <- safe_output(
- x,
- path = path,
- user = user,
- logs_to = logs_to,
- logs_from = logs_from,
- rocrate = rocrate
- )
-
- # return RO-Crate with Safe Output details
- return(rocrate)
-}
-
#' @export
extract_safe_output.rocrate <- function(
x,
@@ -129,14 +103,12 @@ extract_safe_output.rocrate <- function(
)
}
- # add entities to the RO-Crate
+ # add entities to the RO-Crate &
+ # return RO-Crate with the Safe Output details
suppressWarnings({
- rocrate <- rocrate |>
+ rocrate |>
rocrateR::add_entity(entities_lst, verbose = FALSE)
})
-
- # return RO-Crate with the Safe Output details
- return(rocrate)
}
#' Flatten object with Safe Output details
@@ -155,7 +127,7 @@ flatten_safe_output <- function(x, ...) {
#' @export
flatten_safe_output.default <- function(x, ...) {
- return(tibble::tibble())
+ tibble::tibble()
}
#' @export
@@ -164,7 +136,7 @@ flatten_safe_output.rocrate <- function(x, ..., id = NULL) {
{
# extract entities
entities_tbl <- .get_entity(x, type = "File") |>
- # extract @id, name, description, encodingFormat and content for each entity
+ # extract @id, name, description, encodingFormat & content for each ent.
lapply(function(ent) {
tibble::tibble(
id = getElement(ent, "@id"),
diff --git a/R/utils-safe_people.R b/R/utils-safe_people.R
index e3bda56..6388fc3 100644
--- a/R/utils-safe_people.R
+++ b/R/utils-safe_people.R
@@ -12,26 +12,6 @@ extract_safe_people <- function(x, ...) {
UseMethod("extract_safe_people")
}
-#' @export
-extract_safe_people.opal <- function(x, ..., rocrate = rocrateR::rocrate_5s()) {
- # extract non-admin and non-auditor users
- opal_users <- filter_safe_people(x)
-
- # cycle through the data source (x) and extract project details
- for (i in seq_len(nrow(opal_users))) {
- username <- opal_users[i, "name"]
- if (!is.na(username) && !is.null(username)) {
- suppressWarnings({
- rocrate <- rocrate |>
- safe_people(user = username, connection = x, set_author = FALSE)
- })
- }
- }
-
- # return RO-Crate with Safe Project details
- return(rocrate)
-}
-
#' @export
extract_safe_people.rocrate <- function(
x,
@@ -77,18 +57,10 @@ extract_safe_people.rocrate <- function(
)
}
- # add entities to the RO-Crate
- rocrate <- rocrate |>
- rocrateR::add_entity(entities_lst_v2, overwrite = TRUE, verbose = FALSE)
- # # link new user entity @id to the root (./) author property
- # rocrateR::add_entity_value(
- # id = "./",
- # key = "author",
- # value = list(`@id` = getElement(entities_lst_v2, "@id"))
- # )
-
+ # add entities to the RO-Crate &
# return RO-Crate with the Safe People details
- return(rocrate)
+ rocrate |>
+ rocrateR::add_entity(entities_lst_v2, overwrite = TRUE, verbose = FALSE)
}
#' Filter Safe People (excluding admin/auditor accounts)
@@ -168,7 +140,7 @@ flatten_safe_people <- function(x, ...) {
#' @export
flatten_safe_people.default <- function(x, ...) {
- return(tibble::tibble())
+ tibble::tibble()
}
#' @export
diff --git a/R/utils-safe_project.R b/R/utils-safe_project.R
index bc40bec..07d9dfd 100644
--- a/R/utils-safe_project.R
+++ b/R/utils-safe_project.R
@@ -13,30 +13,6 @@ extract_safe_project <- function(x, ...) {
UseMethod("extract_safe_project")
}
-#' @export
-extract_safe_project.opal <- function(
- x,
- ...,
- rocrate = rocrateR::rocrate_5s()
-) {
- # extract list with all projects
- ds <- backend_projects(x)
-
- # cycle through the data source (x) and extract project details
- for (i in seq_len(nrow(ds))) {
- project <- ds$name[i]
- if (!is.na(project) && !is.null(project)) {
- suppressWarnings({
- rocrate <- rocrate |>
- safe_project(project = project, connection = x)
- })
- }
- }
-
- # return RO-Crate with Safe Project details
- return(rocrate)
-}
-
#' @export
extract_safe_project.rocrate <- function(
x,
@@ -93,7 +69,7 @@ extract_safe_project.rocrate <- function(
})
# return RO-Crate with the Safe Data details
- return(rocrate)
+ rocrate
}
#' Flatten object with Safe Project details
@@ -114,7 +90,7 @@ flatten_safe_project <- function(x, ...) {
#' @export
flatten_safe_project.default <- function(x, ...) {
- return(tibble::tibble())
+ tibble::tibble()
}
#' @export
@@ -146,12 +122,12 @@ flatten_safe_project.rocrate <- function(x, ..., y = x) {
return(proj_assets_tbl)
}
- return(tibble::tibble(
+ tibble::tibble(
project_id = project_id,
project = project,
asset_id = NA,
asset = NA
- ))
+ )
}) |>
dplyr::bind_rows()
},
diff --git a/R/utils-safe_setting.R b/R/utils-safe_setting.R
index 9b34118..575e4b8 100644
--- a/R/utils-safe_setting.R
+++ b/R/utils-safe_setting.R
@@ -1,7 +1,7 @@
#' Extract Safe Setting entity(ies)
#'
#' @inheritParams safe_data
-#' @param rocrate (Optional) RO-Crate object to update with Safe Setting details.
+#' @param rocrate (Optional) RO-Crate to be updated with Safe Setting details.
#' @param id (Optional) Vector with `@id` strings for Safe Setting entity(ies).
#'
#' @returns RO-Crate with Safe Setting entity(ies).
@@ -11,19 +11,6 @@ extract_safe_setting <- function(x, ...) {
UseMethod("extract_safe_setting")
}
-#' @export
-extract_safe_setting.opal <- function(
- x,
- ...,
- rocrate = rocrateR::rocrate_5s()
-) {
- # extract all the Safe Settings for the current Opal connection
- rocrate <- safe_setting(x, rocrate = rocrate)
-
- # return RO-Crate with Safe Setting details
- return(rocrate)
-}
-
#' @export
extract_safe_setting.rocrate <- function(
x,
@@ -47,11 +34,7 @@ extract_safe_setting.rocrate <- function(
purrr::map("hasPart") |>
purrr::list_c() |>
purrr::map(`[[`, "@id") |>
- # purrr::map(~ purrr::map(.x, "@id")) |>
purrr::list_c()
- # ss_root_ids <- ss_root[[1]]$hasPart |>
- # purrr::map(`[[`, "@id") |>
- # purrr::list_c()
# extract sub-entities linked to entities directly linked to the root entity
if (length(part_ids) == 0) {
@@ -117,7 +100,7 @@ flatten_safe_setting <- function(x, ...) {
#' @export
flatten_safe_setting.default <- function(x, ...) {
- return(tibble::tibble())
+ tibble::tibble()
}
#' @export
diff --git a/R/zzz.R b/R/zzz.R
deleted file mode 100644
index 67d4658..0000000
--- a/R/zzz.R
+++ /dev/null
@@ -1,3 +0,0 @@
-.onLoad <- function(libname, pkgname) {
- # methods::setOldClass("ArmadilloCredentials")
-}
diff --git a/_pkgdown.yml b/_pkgdown.yml
new file mode 100644
index 0000000..bf9b0ff
--- /dev/null
+++ b/_pkgdown.yml
@@ -0,0 +1,39 @@
+url: https://federatedmethods.github.io/dsROCrate/ # confirm once Pages is enabled
+
+template:
+ bootstrap: 5
+
+reference:
+ - title: Audit a DataSHIELD server
+ desc: Check an account, audit a project in one call, and create the report.
+ contents:
+ - check_permissions
+ - audit
+ - report
+ - title: Build the RO-Crate step by step
+ desc: Initialise the crate, then add the Five Safes, in this order.
+ contents:
+ - init
+ - safe_people
+ - safe_project
+ - safe_data
+ - safe_setting
+ - safe_output
+ - title: Backends
+ desc: Support for MOLGENIS Armadillo is in development.
+ contents:
+ - armadillo_login
+
+articles:
+ - title: Start here
+ navbar: ~
+ contents:
+ - getting-started
+ - audit-permissions
+ - title: Go further
+ contents:
+ - building-crates
+ - auditing-studies
+ - title: Set up a test server
+ contents:
+ - deploy-local-datashield-server-with-opal
diff --git a/man/armadillo_login.Rd b/man/armadillo_login.Rd
index 47c0376..01cdd51 100644
--- a/man/armadillo_login.Rd
+++ b/man/armadillo_login.Rd
@@ -18,6 +18,6 @@ Login to a MOLGENIS' Armadillo server. Wrapper for the function
}
\examples{
\dontrun{
- armadillo_login("https://armadillo-playground.molgenis.net/")
+armadillo_login("https://armadillo-playground.molgenis.net/")
}
}
diff --git a/man/dsROCrate-package.Rd b/man/dsROCrate-package.Rd
index a352c93..0ed66c5 100644
--- a/man/dsROCrate-package.Rd
+++ b/man/dsROCrate-package.Rd
@@ -14,6 +14,7 @@ Tools for wrapping 'DataSHIELD' analyses into RO-Crate (Research Object Crate) o
Useful links:
\itemize{
\item \url{https://github.com/FederatedMethods/dsROCrate}
+ \item \url{https://federatedmethods.github.io/dsROCrate}
\item Report bugs at \url{https://github.com/FederatedMethods/dsROCrate/issues}
}
diff --git a/man/init.Rd b/man/init.Rd
index 6a6797e..5824c95 100644
--- a/man/init.Rd
+++ b/man/init.Rd
@@ -26,13 +26,13 @@ init(x, ...)
\method{init}{rocrate}(
x,
...,
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables"),
- user = attr(x, "user")
+ connection = get_crate_context(x, "connection"),
+ path = get_crate_context(x, "path"),
+ profile = get_crate_context(x, "profile"),
+ project = get_crate_context(x, "project"),
+ resources = get_crate_context(x, "resources"),
+ tables = get_crate_context(x, "tables"),
+ user = get_crate_context(x, "user")
)
}
\arguments{
diff --git a/man/report.Rd b/man/report.Rd
index b23953e..b99d347 100644
--- a/man/report.Rd
+++ b/man/report.Rd
@@ -22,8 +22,6 @@ report(x, ...)
overwrite = FALSE,
include_user_perm = TRUE,
diag_title = "DataSHIELD server",
- diag_width = NULL,
- diag_height = NULL,
max_line_length = 200
)
@@ -37,8 +35,6 @@ report(x, ...)
overwrite = FALSE,
include_user_perm = TRUE,
diag_title = "DataSHIELD server",
- diag_width = NULL,
- diag_height = NULL,
max_line_length = 200
)
@@ -52,8 +48,6 @@ report(x, ...)
overwrite = FALSE,
include_user_perm = TRUE,
diag_title = "DataSHIELD server",
- diag_width = NULL,
- diag_height = NULL,
max_line_length = 200
)
}
@@ -82,12 +76,6 @@ permissions in the report overview's diagram.}
\item{diag_title}{String with title for the 'root' of the diagram (default:
'DataSHIELD server').}
-\item{diag_width}{Numeric value with width (in inches) for the report
-overview's diagram (default: \code{NULL}, estimated based on number of nodes).}
-
-\item{diag_height}{Numeric value with height (in inches) for the report
-overview's diagram (default: \code{NULL}, estimated based on number of nodes).}
-
\item{max_line_length}{Integer with the maximum number of characters per line
in the RO-Crate to be printed in the report.}
}
diff --git a/man/safe_data.Rd b/man/safe_data.Rd
index b7aca47..7c33b28 100644
--- a/man/safe_data.Rd
+++ b/man/safe_data.Rd
@@ -10,7 +10,7 @@
\source{
\itemize{
\item Research Data Scotland, 2025. "What is the Five Safes framework?".
-\url{https://www.researchdata.scot/engage-and-learn/data-explainers/what-is-the-five-safes-framework/}
+\url{https://www.researchdata.scot/engage-and-learn/data-explainers/}
}
}
\usage{
@@ -21,15 +21,15 @@ safe_data(x, ...)
\method{safe_data}{character}(
x,
...,
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables"),
asset_id_suffix = "#asset:",
project_id_suffix = "#project:",
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- user = attr(x, "user")
+ connection = NULL,
+ path = NULL,
+ profile = "default",
+ project = NULL,
+ resources = NULL,
+ tables = NULL,
+ user = NULL
)
\method{safe_data}{opal}(
@@ -50,15 +50,15 @@ safe_data(x, ...)
\method{safe_data}{rocrate}(
x,
...,
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables"),
asset_id_suffix = "#asset:",
project_id_suffix = "#project:",
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- user = attr(x, "user")
+ connection = get_crate_context(x, "connection"),
+ path = get_crate_context(x, "path"),
+ profile = get_crate_context(x, "profile"),
+ project = get_crate_context(x, "project"),
+ resources = get_crate_context(x, "resources"),
+ tables = get_crate_context(x, "tables"),
+ user = get_crate_context(x, "user")
)
}
\arguments{
@@ -70,18 +70,6 @@ RO-Crate.}
\item{...}{Further arguments passed on to the methods, which are documented
as separate arguments below.}
-\item{profile}{String with profile name.}
-
-\item{project}{String with the name of the \link[=safe_project]{Safe Project}.}
-
-\item{resources}{Vector of strings with the names of the resources, part of
-\code{project}. Optional, if not provided, all the resources associated to
-\code{project} will be included in the RO-Crate.}
-
-\item{tables}{Vector of strings with the names of the tables/datasets, part
-of \code{project}. Optional, if not provided, all the tables/datasets
-associated to \code{project} will be included in the RO-Crate.}
-
\item{asset_id_suffix}{String with ID suffix for the tables/datasets
entities in the RO-Crate (default: \code{"#asset:"}).}
@@ -96,6 +84,18 @@ set to a connection object. If so, then \code{rocrate} is required.}
be used to store log files. If not provided, logs will be stored within
the RO-Crate returned by this function.}
+\item{profile}{String with profile name.}
+
+\item{project}{String with the name of the \link[=safe_project]{Safe Project}.}
+
+\item{resources}{Vector of strings with the names of the resources, part of
+\code{project}. Optional, if not provided, all the resources associated to
+\code{project} will be included in the RO-Crate.}
+
+\item{tables}{Vector of strings with the names of the tables/datasets, part
+of \code{project}. Optional, if not provided, all the tables/datasets
+associated to \code{project} will be included in the RO-Crate.}
+
\item{user}{List (or \link[rocrateR:entity]{entity} object) with details for
the Safe People, it must include \verb{@id} and \code{name} entries. Alternatively,
this can be a string with the \code{name} of the current user.}
@@ -123,6 +123,6 @@ This means any sensitive information that might lead to an individual being
identified, such as names and addresses, is either removed or replaced with
a random code. Researchers are not processing personal data when using data
prepared in this way and when the other Safes are in place. Find out more
-about de-identification:
-\url{https://www.researchdata.scot/engage-and-learn/data-explainers/what-is-data-de-identification/}
+about de-identification, 'What is data de-identification?':
+\url{https://www.researchdata.scot/engage-and-learn/data-explainers/}
}
diff --git a/man/safe_output.Rd b/man/safe_output.Rd
index 35f0490..8cf4d6c 100644
--- a/man/safe_output.Rd
+++ b/man/safe_output.Rd
@@ -10,7 +10,7 @@
\source{
\itemize{
\item Research Data Scotland, 2025. "What is the Five Safes framework?".
-\url{https://www.researchdata.scot/engage-and-learn/data-explainers/what-is-the-five-safes-framework/}
+\url{https://www.researchdata.scot/engage-and-learn/data-explainers/}
}
}
\usage{
@@ -21,15 +21,15 @@ safe_output(x, ...)
\method{safe_output}{character}(
x,
...,
- path = attr(x, "path"),
- user = attr(x, "user"),
logs_to = Sys.time(),
logs_from = logs_to - 24 * 60^2,
- connection = attr(x, "connection"),
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables")
+ connection = NULL,
+ path = NULL,
+ profile = "default",
+ project = NULL,
+ resources = NULL,
+ tables = NULL,
+ user = NULL
)
\method{safe_output}{opal}(
@@ -49,15 +49,15 @@ safe_output(x, ...)
\method{safe_output}{rocrate}(
x,
...,
- path = attr(x, "path"),
- user = attr(x, "user"),
logs_to = Sys.time(),
logs_from = logs_to - 24 * 60^2,
- connection = attr(x, "connection"),
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables")
+ connection = get_crate_context(x, "connection"),
+ path = get_crate_context(x, "path"),
+ profile = get_crate_context(x, "profile"),
+ project = get_crate_context(x, "project"),
+ resources = get_crate_context(x, "resources"),
+ tables = get_crate_context(x, "tables"),
+ user = get_crate_context(x, "user")
)
}
\arguments{
@@ -69,14 +69,6 @@ RO-Crate.}
\item{...}{Further arguments passed on to the methods, which are documented
as separate arguments below.}
-\item{path}{String with path pointing to the root of the RO-Crate. This will
-be used to store log files. If not provided, logs will be stored within
-the RO-Crate returned by this function.}
-
-\item{user}{List (or \link[rocrateR:entity]{entity} object) with details for
-the Safe People, it must include \verb{@id} and \code{name} entries. Alternatively,
-this can be a string with the \code{name} of the current user.}
-
\item{logs_to}{Upper limit timestamp to filter out the outputs generated
(default: \code{Sys.time()}, current system time).}
@@ -87,6 +79,10 @@ this can be a string with the \code{name} of the current user.}
values will be extracted from (e.g., OBiBa's Opal). Optional, if \code{x} is
set to a connection object. If so, then \code{rocrate} is required.}
+\item{path}{String with path pointing to the root of the RO-Crate. This will
+be used to store log files. If not provided, logs will be stored within
+the RO-Crate returned by this function.}
+
\item{profile}{String with profile name.}
\item{project}{String with the name of the \link[=safe_project]{Safe Project}.}
@@ -99,6 +95,10 @@ set to a connection object. If so, then \code{rocrate} is required.}
of \code{project}. Optional, if not provided, all the tables/datasets
associated to \code{project} will be included in the RO-Crate.}
+\item{user}{List (or \link[rocrateR:entity]{entity} object) with details for
+the Safe People, it must include \verb{@id} and \code{name} entries. Alternatively,
+this can be a string with the \code{name} of the current user.}
+
\item{rocrate}{RO-Crate object. Optional, if \code{x} is either an RO-Crate
object or a path to a valid RO-Crate. If so, then \code{connection} is
required (default: \code{rocrateR::rocrate_5s()}).}
diff --git a/man/safe_people.Rd b/man/safe_people.Rd
index 7a3611d..a88cd51 100644
--- a/man/safe_people.Rd
+++ b/man/safe_people.Rd
@@ -10,7 +10,7 @@
\source{
\itemize{
\item Research Data Scotland, 2025. "What is the Five Safes framework?".
-\url{https://www.researchdata.scot/engage-and-learn/data-explainers/what-is-the-five-safes-framework/}
+\url{https://www.researchdata.scot/engage-and-learn/data-explainers/}
}
}
\usage{
@@ -21,16 +21,16 @@ safe_people(x, ...)
\method{safe_people}{character}(
x,
...,
- user = attr(x, "user"),
- user_id_suffix = "#person:",
set_author = TRUE,
set_project = TRUE,
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables")
+ user_id_suffix = "#person:",
+ connection = NULL,
+ path = NULL,
+ profile = "default",
+ project = NULL,
+ resources = NULL,
+ tables = NULL,
+ user = NULL
)
\method{safe_people}{opal}(
@@ -51,16 +51,16 @@ safe_people(x, ...)
\method{safe_people}{rocrate}(
x,
...,
- user = attr(x, "user"),
- user_id_suffix = "#person:",
set_author = TRUE,
set_project = TRUE,
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables")
+ user_id_suffix = "#person:",
+ connection = get_crate_context(x, "connection"),
+ path = get_crate_context(x, "path"),
+ profile = get_crate_context(x, "profile"),
+ project = get_crate_context(x, "project"),
+ resources = get_crate_context(x, "resources"),
+ tables = get_crate_context(x, "tables"),
+ user = get_crate_context(x, "user")
)
}
\arguments{
@@ -72,19 +72,15 @@ RO-Crate.}
\item{...}{Further arguments passed on to the methods, which are documented
as separate arguments below.}
-\item{user}{List (or \link[rocrateR:entity]{entity} object) with details for
-the Safe People, it must include \verb{@id} and \code{name} entries. Alternatively,
-this can be a string with the \code{name} of the current user.}
-
-\item{user_id_suffix}{String with ID suffix for the people/user
-entities in the RO-Crate (default: \code{"#person:"}).}
-
\item{set_author}{Boolean flag to indicate if the current user should be
set as the author of the RO-Crate.}
\item{set_project}{Boolean flag to indicate if any \code{Project} entities found
in \code{x} should be linked to the Safe People entity.}
+\item{user_id_suffix}{String with ID suffix for the people/user
+entities in the RO-Crate (default: \code{"#person:"}).}
+
\item{connection}{Connection object for the 'DataSHIELD' server where the
values will be extracted from (e.g., OBiBa's Opal). Optional, if \code{x} is
set to a connection object. If so, then \code{rocrate} is required.}
@@ -105,6 +101,10 @@ the RO-Crate returned by this function.}
of \code{project}. Optional, if not provided, all the tables/datasets
associated to \code{project} will be included in the RO-Crate.}
+\item{user}{List (or \link[rocrateR:entity]{entity} object) with details for
+the Safe People, it must include \verb{@id} and \code{name} entries. Alternatively,
+this can be a string with the \code{name} of the current user.}
+
\item{rocrate}{RO-Crate object. Optional, if \code{x} is either an RO-Crate
object or a path to a valid RO-Crate. If so, then \code{connection} is
required (default: \code{rocrateR::rocrate_5s()}).}
diff --git a/man/safe_project.Rd b/man/safe_project.Rd
index 3a2a0eb..1b723f2 100644
--- a/man/safe_project.Rd
+++ b/man/safe_project.Rd
@@ -10,7 +10,7 @@
\source{
\itemize{
\item Research Data Scotland, 2025. "What is the Five Safes framework?".
-\url{https://www.researchdata.scot/engage-and-learn/data-explainers/what-is-the-five-safes-framework/}
+\url{https://www.researchdata.scot/engage-and-learn/data-explainers/}
}
}
\usage{
@@ -33,15 +33,15 @@ safe_project(x, ...)
\method{safe_project}{character}(
x,
...,
- profile = attr(x, "profile"),
- project = attr(x, "project"),
asset_id_suffix = "#asset:",
project_id_suffix = "#project:",
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables"),
- user = attr(x, "user")
+ connection = NULL,
+ path = NULL,
+ profile = "default",
+ project = NULL,
+ resources = NULL,
+ tables = NULL,
+ user = NULL
)
\method{safe_project}{opal}(
@@ -61,15 +61,15 @@ safe_project(x, ...)
\method{safe_project}{rocrate}(
x,
...,
- profile = attr(x, "profile"),
- project = attr(x, "project"),
asset_id_suffix = "#asset:",
project_id_suffix = "#project:",
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables"),
- user = attr(x, "user")
+ connection = get_crate_context(x, "connection"),
+ path = get_crate_context(x, "path"),
+ profile = get_crate_context(x, "profile"),
+ project = get_crate_context(x, "project"),
+ resources = get_crate_context(x, "resources"),
+ tables = get_crate_context(x, "tables"),
+ user = get_crate_context(x, "user")
)
}
\arguments{
diff --git a/man/safe_setting.Rd b/man/safe_setting.Rd
index 54a365b..d058e85 100644
--- a/man/safe_setting.Rd
+++ b/man/safe_setting.Rd
@@ -11,7 +11,7 @@
\source{
\itemize{
\item Research Data Scotland, 2025. "What is the Five Safes framework?".
-\url{https://www.researchdata.scot/engage-and-learn/data-explainers/what-is-the-five-safes-framework/}
+\url{https://www.researchdata.scot/engage-and-learn/data-explainers/}
}
}
\usage{
@@ -22,13 +22,13 @@ safe_setting(x, ...)
\method{safe_setting}{character}(
x,
...,
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- tables = attr(x, "tables"),
- resources = attr(x, "resources"),
- user = attr(x, "user")
+ connection = NULL,
+ path = NULL,
+ profile = "default",
+ project = NULL,
+ resources = NULL,
+ tables = NULL,
+ user = NULL
)
\method{safe_setting}{cr8tor}(x, ..., rocrate = rocrateR::rocrate_5s())
@@ -48,13 +48,13 @@ safe_setting(x, ...)
\method{safe_setting}{rocrate}(
x,
...,
- connection = attr(x, "connection"),
- path = attr(x, "path"),
- profile = attr(x, "profile"),
- project = attr(x, "project"),
- resources = attr(x, "resources"),
- tables = attr(x, "tables"),
- user = attr(x, "user")
+ connection = get_crate_context(x, "connection"),
+ path = get_crate_context(x, "path"),
+ profile = get_crate_context(x, "profile"),
+ project = get_crate_context(x, "project"),
+ resources = get_crate_context(x, "resources"),
+ tables = get_crate_context(x, "tables"),
+ user = get_crate_context(x, "user")
)
}
\arguments{
@@ -78,14 +78,14 @@ the RO-Crate returned by this function.}
\item{project}{String with the name of the \link[=safe_project]{Safe Project}.}
-\item{tables}{Vector of strings with the names of the tables/datasets, part
-of \code{project}. Optional, if not provided, all the tables/datasets
-associated to \code{project} will be included in the RO-Crate.}
-
\item{resources}{Vector of strings with the names of the resources, part of
\code{project}. Optional, if not provided, all the resources associated to
\code{project} will be included in the RO-Crate.}
+\item{tables}{Vector of strings with the names of the tables/datasets, part
+of \code{project}. Optional, if not provided, all the tables/datasets
+associated to \code{project} will be included in the RO-Crate.}
+
\item{user}{List (or \link[rocrateR:entity]{entity} object) with details for
the Safe People, it must include \verb{@id} and \code{name} entries. Alternatively,
this can be a string with the \code{name} of the current user.}
diff --git a/tests/testthat/helper-opal_demo_server.R b/tests/testthat/helper-opal_demo_server.R
index 089cfa0..c80831c 100644
--- a/tests/testthat/helper-opal_demo_server.R
+++ b/tests/testthat/helper-opal_demo_server.R
@@ -6,8 +6,8 @@
#' @returns Connection object to OBiBa's Opal demo server with extra attributes.
opal_demo_con <- function(admin = TRUE) {
# Skip tests if offline or on CRAN
- skip_on_cran()
- skip_if_offline()
+ testthat::skip_on_cran()
+ testthat::skip_if_offline()
## Opal server access
USERNAME <- "administrator"
@@ -47,5 +47,5 @@ opal_demo_con <- function(admin = TRUE) {
attr(opal_con, "PROJECT") <- PROJECT
attr(opal_con, "TABLES") <- TABLES
- return(opal_con)
+ opal_con
}
diff --git a/tests/testthat/helper-report-crates.R b/tests/testthat/helper-report-crates.R
new file mode 100644
index 0000000..c751503
--- /dev/null
+++ b/tests/testthat/helper-report-crates.R
@@ -0,0 +1,112 @@
+# Create an RO-Crate with the Five Safes, using mocked requests to the backend.
+#
+# - `table_perm_subjects`: users with permissions on the tables of the project.
+# - `with_outputs`: if `TRUE`, the logs of `dsuser` are included (Safe Output).
+# - `path`: directory where the files of the RO-Crate (e.g., logs) are stored.
+mock_report_crate <- function(
+ project = "P1",
+ table_perm_subjects = "dsuser",
+ with_outputs = FALSE,
+ path = NULL
+) {
+ timestamps <- list(
+ created = "2026-10-13T04:26:14.076Z",
+ lastUpdate = "2026-10-13T14:17:32.082Z"
+ )
+ no_perms <- data.frame(
+ subject = character(),
+ type = character(),
+ permission = character(),
+ stringsAsFactors = FALSE
+ )
+ table_perms <- no_perms
+ if (length(table_perm_subjects)) {
+ table_perms <- data.frame(
+ subject = table_perm_subjects,
+ type = "user",
+ permission = "view",
+ stringsAsFactors = FALSE
+ )
+ }
+ logs <- tibble::tibble(
+ `@timestamp` = as.POSIXct(
+ c(
+ "2026-09-24 10:00:00",
+ "2026-09-24 10:00:01",
+ "2026-09-24 10:00:02",
+ "2026-09-24 10:00:03"
+ ),
+ tz = "UTC"
+ ),
+ logger_name = "datashield.user",
+ level = "INFO",
+ message = c("Session opened", "Resolved", "Assigned", "Aggregate"),
+ ds_action = c("OPEN", "RESOLVE", "ASSIGN", "AGGREGATE"),
+ ds_id = "session-1",
+ ds_profile = "default",
+ username = "dsuser",
+ ds_symbol = c(NA, "D", "D", NA),
+ ds_table = c(NA, paste0(project, ".T1"), paste0(project, ".T1"), NA),
+ ds_resource = NA_character_,
+ ds_eval = c(NA, NA, NA, "meanDS(D$AGE)")
+ )
+
+ # nolint start
+ testthat::with_mocked_bindings(
+ suppressWarnings(suppressMessages({
+ crate <- init(
+ fake_opal_con("auditor"),
+ project = project,
+ user = "dsuser",
+ path = path
+ ) |>
+ safe_people() |>
+ safe_project() |>
+ safe_data()
+
+ if (with_outputs) {
+ crate <- safe_output(
+ crate,
+ logs_from = as.POSIXct("2026-09-24 09:59:00", tz = "UTC"),
+ logs_to = as.POSIXct("2026-09-24 10:01:00", tz = "UTC")
+ )
+ }
+ crate
+ })),
+ validate_backend = function(x, ...) invisible(TRUE),
+ validate_backend_version = function(x, ..., minimum = "5.7.2") {
+ invisible(TRUE)
+ },
+ project_exists = function(x, ...) invisible(TRUE),
+ backend_users = function(x, ...) {
+ list(list(principal = "dsuser", groups = list("g1")))
+ },
+ backend_project = function(x, project, ...) {
+ list(name = project, timestamps = timestamps)
+ },
+ backend_project_perms = function(x, project, ...) {
+ data.frame(subject = "dsuser", type = "user", permission = "view")
+ },
+ backend_tables = function(x, project, ...) {
+ list(
+ list(name = "T1", timestamps = timestamps),
+ list(name = "T2", timestamps = timestamps)
+ )
+ },
+ backend_resources = function(x, project, ...) list(),
+ backend_table_perms = function(x, project, ...) table_perms,
+ backend_resource_perms = function(x, project, ...) no_perms,
+ backend_logs = function(x, ...) logs
+ )
+ # nolint end
+}
+
+# Skip the (slow) overview diagram, which also needs `{vtree}`
+local_mock_overview_diagram <- function(.env = parent.frame()) {
+ testthat::local_mocked_bindings(
+ .overview_diagram = function(...) {
+ list(diag_lst = "diagram", diag_path = "diagram.png")
+ },
+ .env = .env
+ )
+}
diff --git a/tests/testthat/test-audit_engine.R b/tests/testthat/test-audit_engine.R
index b7cb801..8e4936a 100644
--- a/tests/testthat/test-audit_engine.R
+++ b/tests/testthat/test-audit_engine.R
@@ -181,7 +181,7 @@ test_that("audit_engine.opal errors if the `user` filter matches nobody", {
)
})
-test_that("audit_engine.opal aborts if Safe People details cannot be obtained", {
+test_that("audit_engine.opal aborts if Safe People dets cannot be obtained", {
# simulates e.g. a permissions-lookup failure on the server:
# `filter_safe_people()` falls back to an empty table internally, and
# since an audit is not meaningful without Safe People details,
diff --git a/tests/testthat/test-backend-opal.R b/tests/testthat/test-backend-opal.R
new file mode 100644
index 0000000..eca34a3
--- /dev/null
+++ b/tests/testthat/test-backend-opal.R
@@ -0,0 +1,276 @@
+test_that("validate_backend() validates an unvalidated crate", {
+ con <- fake_opal_con()
+ crate <- structure(list(), class = "rocrate")
+ calls <- new.env(parent = emptyenv())
+ calls$con <- 0L
+ calls$version <- 0L
+ calls$permissions <- 0L
+
+ local_mocked_bindings(
+ validate_con = function(x, ...) {
+ calls$con <- calls$con + 1L
+ invisible(TRUE)
+ },
+ validate_backend_version = function(x, ...) {
+ calls$version <- calls$version + 1L
+ invisible(TRUE)
+ },
+ check_permissions = function(x, ...) {
+ calls$permissions <- calls$permissions + 1L
+ invisible(TRUE)
+ }
+ )
+
+ expect_invisible(validate_backend(con, rocrate = crate))
+ expect_identical(calls$con, 1L)
+ expect_identical(calls$version, 1L)
+ expect_identical(calls$permissions, 1L)
+})
+
+test_that("validated crates skip checks with the same connection", {
+ con <- fake_opal_con()
+ crate <- structure(list(), class = "rocrate")
+ attr(crate, "connection") <- con
+ attr(crate, "backend_validated") <- TRUE
+
+ local_mocked_bindings(
+ validate_con = function(...) {
+ testthat::fail("validate_con() should not be called")
+ },
+ validate_backend_version = function(...) {
+ testthat::fail("validate_backend_version() should not be called")
+ },
+ check_permissions = function(...) {
+ testthat::fail("check_permissions() should not be called")
+ }
+ )
+
+ expect_invisible(validate_backend(con, rocrate = crate))
+})
+
+test_that("a crate is validated when the connection differs", {
+ original_con <- fake_opal_con(username = "original")
+ new_con <- fake_opal_con(username = "different")
+ crate <- structure(list(), class = "rocrate")
+ attr(crate, "connection") <- original_con
+ attr(crate, "backend_validated") <- TRUE
+
+ calls <- new.env(parent = emptyenv())
+ calls$con <- 0L
+ calls$version <- 0L
+ calls$permissions <- 0L
+
+ local_mocked_bindings(
+ validate_con = function(x, ...) {
+ calls$con <- calls$con + 1L
+ expect_identical(x, new_con)
+ invisible(TRUE)
+ },
+ validate_backend_version = function(x, ...) {
+ calls$version <- calls$version + 1L
+ expect_identical(x, new_con)
+ invisible(TRUE)
+ },
+ check_permissions = function(x, ...) {
+ calls$permissions <- calls$permissions + 1L
+ expect_identical(x, new_con)
+ invisible(TRUE)
+ }
+ )
+
+ expect_invisible(validate_backend(new_con, rocrate = crate))
+ expect_identical(calls$con, 1L)
+ expect_identical(calls$version, 1L)
+ expect_identical(calls$permissions, 1L)
+})
+
+test_that("validate_backend() does not continue after a validation failure", {
+ con <- fake_opal_con()
+ crate <- structure(list(), class = "rocrate")
+ calls <- new.env(parent = emptyenv())
+ calls$version <- 0L
+ calls$permissions <- 0L
+
+ local_mocked_bindings(
+ validate_con = function(x, ...) stop("connection invalid", call. = FALSE),
+ validate_backend_version = function(x, ...) {
+ calls$version <- calls$version + 1L
+ invisible(TRUE)
+ },
+ check_permissions = function(x, ...) {
+ calls$permissions <- calls$permissions + 1L
+ invisible(TRUE)
+ }
+ )
+
+ expect_error(validate_backend(con, rocrate = crate), "connection invalid")
+ expect_identical(calls$version, 0L)
+ expect_identical(calls$permissions, 0L)
+})
+
+test_that("crate validation requires a TRUE flag and an identical connection", {
+ con <- fake_opal_con()
+ other_con <- fake_opal_con(username = "other")
+ crate <- structure(list(), class = "rocrate")
+
+ expect_false(backend_validated(con, rocrate = crate))
+
+ attr(crate, "backend_validated") <- TRUE
+ expect_false(backend_validated(con, rocrate = crate))
+
+ attr(crate, "connection") <- con
+ expect_true(backend_validated(con, rocrate = crate))
+ expect_false(backend_validated(other_con, rocrate = crate))
+
+ attr(crate, "backend_validated") <- NA
+ expect_false(backend_validated(con, rocrate = crate))
+})
+
+test_that("a crating session validates once and reuses the context flag", {
+ con <- fake_opal_con()
+ crate <- structure(list(), class = "rocrate")
+ calls <- new.env(parent = emptyenv())
+ calls$con <- 0L
+ calls$version <- 0L
+ calls$permissions <- 0L
+
+ local_mocked_bindings(
+ validate_con = function(x, ...) {
+ calls$con <- calls$con + 1L
+ invisible(TRUE)
+ },
+ validate_backend_version = function(x, ...) {
+ calls$version <- calls$version + 1L
+ invisible(TRUE)
+ },
+ check_permissions = function(x, ...) {
+ calls$permissions <- calls$permissions + 1L
+ invisible(TRUE)
+ }
+ )
+
+ # Initialisation validates the connection before marking the crate context.
+ expect_invisible(validate_backend(con, rocrate = crate))
+ crate <- set_crate_context(crate, connection = con, validated = TRUE)
+
+ # Subsequent operations in the same session reuse the validation result.
+ expect_invisible(validate_backend(con, rocrate = crate))
+ expect_invisible(validate_backend(con, rocrate = crate))
+
+ expect_identical(calls$con, 1L)
+ expect_identical(calls$version, 1L)
+ expect_identical(calls$permissions, 1L)
+})
+
+# helper: mock the requests made to get the members of a project
+mock_members_requests <- function(.env = parent.frame()) {
+ calls <- new.env(parent = emptyenv())
+ calls$exists <- 0L
+ calls$tables <- 0L
+ calls$resources <- 0L
+ calls$perms <- character()
+ perms <- function(subject) {
+ data.frame(
+ subject = subject,
+ type = "user",
+ permission = "view",
+ stringsAsFactors = FALSE
+ )
+ }
+
+ testthat::local_mocked_bindings(
+ project_exists = function(x, ...) {
+ calls$exists <- calls$exists + 1L
+ invisible(TRUE)
+ },
+ backend_tables = function(x, project, ...) {
+ calls$tables <- calls$tables + 1L
+ list(list(name = "T1"))
+ },
+ backend_resources = function(x, project, ...) {
+ calls$resources <- calls$resources + 1L
+ list(list(name = "R1", parameters = ""))
+ },
+ backend_project_perms = function(x, project, ...) {
+ calls$perms <- c(calls$perms, "project")
+ perms("admin")
+ },
+ backend_table_perms = function(x, project, table, ...) {
+ calls$perms <- c(calls$perms, paste0("table:", table))
+ perms("table_user")
+ },
+ backend_resource_perms = function(x, project, resource, ...) {
+ calls$perms <- c(calls$perms, paste0("resource:", resource))
+ perms("resource_user")
+ },
+ .env = .env
+ )
+
+ calls
+}
+
+test_that("backend_project_members() combines project and asset permissions", {
+ mock_members_requests()
+
+ res <- backend_project_members(fake_opal_con(), project = "P1")
+
+ expect_equal(res$subject, c("admin", "table_user", "resource_user"))
+ expect_equal(res$via, c("project", "table", "resource"))
+ expect_equal(res$asset, c(NA, "T1", "R1"))
+ expect_named(res, c("subject", "type", "permission", "via", "asset"))
+})
+
+test_that("backend_project_members() lists the assets if none are given", {
+ calls <- mock_members_requests()
+
+ backend_project_members(fake_opal_con(), project = "P1")
+
+ expect_equal(calls$tables, 1L)
+ expect_equal(calls$resources, 1L)
+ expect_equal(calls$perms, c("project", "table:T1", "resource:R1"))
+})
+
+test_that("backend_project_members() uses the given assets as they are", {
+ calls <- mock_members_requests()
+
+ # `character(0)` means no tables, it is not the same as `NULL` (all of them)
+ res <- backend_project_members(
+ fake_opal_con(),
+ project = "P1",
+ tables = character(0),
+ resources = "R2"
+ )
+
+ expect_equal(calls$tables, 0L)
+ expect_equal(calls$resources, 0L)
+ expect_equal(calls$exists, 0L)
+ expect_equal(calls$perms, c("project", "resource:R2"))
+ expect_equal(res$via, c("project", "resource"))
+})
+
+test_that("backend_project_members() can get the permissions from elsewhere", {
+ calls <- mock_members_requests()
+ requested <- list()
+
+ res <- backend_project_members(
+ fake_opal_con(),
+ project = "P1",
+ tables = "T1",
+ resources = character(0),
+ permissions = function(type, asset = NULL) {
+ requested[[length(requested) + 1]] <<- list(type = type, asset = asset)
+ data.frame(subject = "cached", type = "user", permission = "view")
+ }
+ )
+
+ expect_equal(res$subject, c("cached", "cached"))
+ expect_equal(
+ requested,
+ list(
+ list(type = "project", asset = NULL),
+ list(type = "table", asset = "T1")
+ )
+ )
+ # the backend is not requested
+ expect_length(calls$perms, 0)
+})
diff --git a/tests/testthat/test-project_exists.R b/tests/testthat/test-project_exists.R
deleted file mode 100644
index f13545b..0000000
--- a/tests/testthat/test-project_exists.R
+++ /dev/null
@@ -1,41 +0,0 @@
-# test_that("project_exists.opal() succeeds when project exists", {
-# # setup
-# opal_con <- opal_demo_con()
-#
-# expect_silent(
-# dsROCrate:::project_exists(opal_con, project = attr(opal_con, "PROJECT"))
-# )
-# })
-#
-# test_that("project_exists.opal() errors when project does not exist", {
-# expect_error(
-# project_exists(opal_con, project = "THIS_PROJECT_DOES_NOT_EXIST"),
-# "was not found in the given Opal connection!"
-# )
-# })
-#
-# test_that("project_exists() dispatches to opal method", {
-# expect_silent(
-# project_exists(opal_con, project = attr(opal_con, "PROJECT"))
-# )
-# })
-#
-# test_that("project_exists() works for armadillo objects", {
-# skip_if_not_installed("MolgenisArmadillo")
-#
-# arm <- methods::new("armadillo")
-#
-# local_mocked_bindings(
-# armadillo.list_projects = function() c("proj1", "proj2"),
-# .package = "MolgenisArmadillo"
-# )
-#
-# expect_silent(
-# project_exists(arm, project = "proj1")
-# )
-#
-# expect_error(
-# project_exists(arm, project = "missing"),
-# "was not found in the given Armadillo connection!"
-# )
-# })
diff --git a/tests/testthat/test-report.R b/tests/testthat/test-report.R
index 6b12b5f..c11be52 100644
--- a/tests/testthat/test-report.R
+++ b/tests/testthat/test-report.R
@@ -1,8 +1,5 @@
test_that("report.default errors", {
- expect_error(
- report(123),
- "Unknown class"
- )
+ expect_error(report(123))
})
test_that("report.character errors for invalid path", {
@@ -183,54 +180,224 @@ test_that("report.rocrate prevents overwrite", {
)
})
-test_that("report.list aggregates multiple servers", {
- fake_rocrate <- structure(list(), class = "rocrate")
+test_that("report.list() reports on a list of RO-Crates", {
+ local_mock_overview_diagram()
+ crates <- list(
+ site_a = mock_report_crate("P1", with_outputs = TRUE),
+ site_b = mock_report_crate("P2", with_outputs = TRUE)
+ )
- server_output <- list(
- safe_people = tibble::tibble(id_person = "u1", name = "dsuser"),
- safe_project = tibble::tibble(
- id_project = "p1",
- project = "P1",
- asset_id = "t1",
- asset = "T1"
- ),
- safe_data = tibble::tibble(asset_id = "t1", asset = "T1"),
- safe_data_permissions = NULL,
- safe_setting = tibble::tibble(),
- safe_output = tibble::tibble(),
- overview_data = tibble::tibble(
- project = "P1",
- asset = "T1",
- person = "dsuser"
+ res <- suppressMessages(
+ report(crates, render = FALSE, filepath = tempfile(fileext = ".md"))
+ )
+
+ expect_named(
+ res,
+ c(
+ "overview_diagram",
+ "overview_data",
+ "safe_people",
+ "safe_project",
+ "safe_data",
+ "safe_data_permissions",
+ "safe_setting",
+ "safe_output",
+ "safe_project_tbl"
)
)
+ expect_equal(res$safe_people$server, c("site_a", "site_b"))
+ expect_equal(unique(res$safe_project$project), c("P1", "P2"))
+ expect_equal(unique(res$safe_output$server), c("site_a", "site_b"))
+ # name used by previous versions
+ expect_identical(res$safe_project_tbl, res$safe_project)
+ expect_equal(unique(res$overview_data$Server), c("site_a", "site_b"))
+})
- testthat::local_mocked_bindings(
- is_rocrate = function(...) TRUE,
- .package = "rocrateR"
+test_that("report.list() writes a section for each server", {
+ local_mock_overview_diagram()
+ filepath <- tempfile(fileext = ".md")
+ crates <- list(
+ site_a = mock_report_crate("P1"),
+ site_b = mock_report_crate("P2")
)
- testthat::with_mocked_bindings(
- report = function(...) server_output,
- .overview_diagram = function(...) list(diag_lst = "diag", diag_path = NULL),
- .tidy_overview = function(...) tibble::tibble(Project = "P1"),
- .markdown_report_header = function(...) "HEADER",
- .markdown_report_body = function(...) "BODY",
- .markdown_report_rocrate = function(...) "ROCRATE",
- code = {
- result <- report(
- list(server1 = fake_rocrate, server2 = fake_rocrate),
- render = FALSE,
- filepath = tempfile(fileext = ".md")
- )
+ suppressMessages(report(crates, render = FALSE, filepath = filepath))
+ md <- readLines(filepath)
- expect_type(result, "list")
- expect_true("safe_people" %in% names(result))
+ expect_true("## RO-Crates" %in% md)
+ expect_true("### 'site_a' server" %in% md)
+ expect_true("### 'site_b' server" %in% md)
+})
+
+test_that("report.list() names the servers if the list has no names", {
+ local_mock_overview_diagram()
+ filepath <- tempfile(fileext = ".md")
+ crates <- list(mock_report_crate("P1"), mock_report_crate("P2"))
+
+ res <- suppressMessages(report(crates, render = FALSE, filepath = filepath))
+
+ expect_equal(res$safe_people$server, c("server_1", "server_2"))
+ expect_true("### 'server_2' server" %in% readLines(filepath))
+})
+
+test_that("report.list() works if the RO-Crates have no permissions", {
+ local_mock_overview_diagram()
+ crates <- list(
+ a = mock_report_crate("P1", table_perm_subjects = character()),
+ b = mock_report_crate("P2", table_perm_subjects = character())
+ )
+
+ res <- suppressMessages(
+ report(crates, render = FALSE, filepath = tempfile(fileext = ".md"))
+ )
+
+ expect_equal(res$overview_data$Server, c("a", "a", "b", "b"))
+ expect_equal(res$overview_data$People, rep("dsuser", 4))
+ expect_equal(nrow(res$safe_data_permissions), 0)
+})
+
+test_that("report.list() keeps the servers without permissions", {
+ local_mock_overview_diagram()
+ crates <- list(
+ a = mock_report_crate("P1", table_perm_subjects = "dsuser"),
+ b = mock_report_crate("P2", table_perm_subjects = character())
+ )
+
+ res <- suppressMessages(
+ report(crates, render = FALSE, filepath = tempfile(fileext = ".md"))
+ )
+
+ expect_equal(unique(res$overview_data$Server), c("a", "b"))
+ # the server without permissions has no access level (and no `NA`)
+ expect_equal(res$overview_data[["Access Level"]], c("read", "read", "", ""))
+})
+
+test_that("report.list() builds the diagram once and each RO-Crate once", {
+ n_diagrams <- 0L
+ n_crates <- 0L
+ original <- .markdown_report_rocrate
+ local_mocked_bindings(
+ .overview_diagram = function(...) {
+ n_diagrams <<- n_diagrams + 1L
+ list(diag_lst = "diagram", diag_path = "diagram.png")
},
- .package = "dsROCrate"
+ .markdown_report_rocrate = function(...) {
+ n_crates <<- n_crates + 1L
+ original(...)
+ }
+ )
+ crates <- list(
+ a = mock_report_crate("P1"),
+ b = mock_report_crate("P2"),
+ c = mock_report_crate("P3")
+ )
+
+ suppressMessages(
+ report(crates, render = FALSE, filepath = tempfile(fileext = ".md"))
+ )
+
+ expect_equal(n_diagrams, 1L)
+ expect_equal(n_crates, 3L)
+})
+
+test_that("report.list() does not overwrite files unless told to", {
+ local_mock_overview_diagram()
+ filepath <- tempfile(fileext = ".md")
+ writeLines("previous version", filepath)
+ crates <- list(a = mock_report_crate("P1"), b = mock_report_crate("P2"))
+
+ expect_error(
+ report(crates, render = FALSE, filepath = filepath),
+ "points to an existing file"
+ )
+ expect_equal(readLines(filepath), "previous version")
+
+ suppressMessages(
+ report(crates, render = FALSE, filepath = filepath, overwrite = TRUE)
+ )
+ expect_gt(length(readLines(filepath)), 1)
+})
+
+test_that("report.list() fails if the directory of the file does not exist", {
+ crates <- list(a = mock_report_crate("P1"))
+ filepath <- file.path(withr::local_tempdir(), "nope", "report.md")
+
+ expect_error(
+ report(crates, render = FALSE, filepath = filepath),
+ "directory does not exist"
)
})
+test_that("report.list() and report.rocrate() agree on a single RO-Crate", {
+ local_mock_overview_diagram()
+ crate <- mock_report_crate("P1", with_outputs = TRUE)
+
+ single <- suppressMessages(
+ report(crate, render = FALSE, filepath = tempfile(fileext = ".md"))
+ )
+ listed <- suppressMessages(
+ report(
+ list(site = crate),
+ render = FALSE,
+ filepath = tempfile(fileext = ".md")
+ )
+ )
+
+ # same tables (the list also has the name of the server)
+ for (name in c("safe_people", "safe_project", "safe_data", "safe_output")) {
+ expect_equal(
+ dplyr::select(listed[[name]], -server),
+ single[[name]],
+ info = name
+ )
+ }
+ expect_equal(
+ dplyr::select(listed$safe_data_permissions, -server),
+ single$safe_data_permissions
+ )
+})
+
+test_that("report.rocrate() labels the RO-Crate, not a server", {
+ local_mock_overview_diagram()
+ filepath <- tempfile(fileext = ".md")
+
+ suppressMessages(
+ report(mock_report_crate(), render = FALSE, filepath = filepath)
+ )
+ md <- readLines(filepath)
+
+ expect_true("## RO-Crate" %in% md)
+ expect_false(any(grepl("server$", md[grepl("^#+ '", md)])))
+ expect_false("## RO-Crates" %in% md)
+})
+
+test_that("report.character() loads the files of an RO-Crate directory", {
+ local_mock_overview_diagram()
+ dir <- withr::local_tempdir()
+ crate <- mock_report_crate(with_outputs = TRUE, path = dir)
+ rocrateR::write_rocrate(crate, file.path(dir, "ro-crate-metadata.json"))
+
+ res <- suppressMessages(
+ report(dir, render = FALSE, filepath = tempfile(fileext = ".md"))
+ )
+
+ expect_gt(nrow(res$safe_output), 0)
+})
+
+test_that("report.character() loads the files from the metadata file", {
+ local_mock_overview_diagram()
+ dir <- withr::local_tempdir()
+ crate <- mock_report_crate(with_outputs = TRUE, path = dir)
+ metadata <- file.path(dir, "ro-crate-metadata.json")
+ rocrateR::write_rocrate(crate, metadata)
+
+ res <- suppressMessages(
+ report(metadata, render = FALSE, filepath = tempfile(fileext = ".md"))
+ )
+
+ expect_gt(nrow(res$safe_output), 0)
+})
+
test_that(".tidy_overview collapses permissions correctly", {
df <- tibble::tibble(
project = "P1",
@@ -292,7 +459,7 @@ test_that("report works end-to-end with real dsROCrate audit outputs", {
out_file <- file.path(tmp_dir, "report.md")
- # ignore warnings about missing permission entities (e.g., @type = 'ControlAction')
+ # ignore warnings about missing permission entities
suppressWarnings(
result <- report(
roc,
@@ -338,7 +505,7 @@ test_that("report.character loads crate from disk", {
out_file <- file.path(tmp_dir, "report.md")
- # ignore warnings about missing permission entities (e.g., @type = 'ControlAction')
+ # ignore warnings about missing permission entities
suppressWarnings(
result <- report(
path_to_rocrate_bag,
@@ -377,7 +544,7 @@ test_that("report.list aggregates outputs from a study audit", {
out_file <- file.path(tmp_dir, "report.md")
- # ignore warnings about missing permission entities (e.g., @type = 'ControlAction')
+ # ignore warnings about missing permission entities
suppressWarnings(
result <- report(
roc,
@@ -396,23 +563,19 @@ test_that("report.list aggregates outputs from a study audit", {
})
test_that("report.list handles missing outputs from a study audit", {
- # create temporary file
- tmp_dir <- file.path(tempdir(), "dsROCRate_tests")
- dir.create(tmp_dir, recursive = TRUE)
- on.exit(unlink(tmp_dir, recursive = TRUE, force = TRUE))
- out_file <- file.path(tmp_dir, "report.md")
-
- testthat::with_mocked_bindings(
- report = function(...) list(),
- code = {
- result <- report(
- list(server1 = rocrateR::rocrate_5s()),
- render = FALSE,
- filepath = out_file
- )
+ local_mock_overview_diagram()
+ # RO-Crates without Safe Outputs (e.g., no activity from the users)
+ crates <- list(
+ server1 = mock_report_crate("P1", with_outputs = FALSE),
+ server2 = mock_report_crate("P2", with_outputs = FALSE)
+ )
- expect_type(result, "list")
- },
- .package = "dsROCrate"
+ result <- suppressMessages(
+ report(crates, render = FALSE, filepath = tempfile(fileext = ".md"))
)
+
+ expect_type(result, "list")
+ expect_equal(nrow(result$safe_output), 0)
+ expect_false("fx" %in% names(result$overview_data))
+ expect_equal(unique(result$overview_data$Server), c("server1", "server2"))
})
diff --git a/tests/testthat/test-safe-call.R b/tests/testthat/test-safe-call.R
index 4b8f737..d9ccfc0 100644
--- a/tests/testthat/test-safe-call.R
+++ b/tests/testthat/test-safe-call.R
@@ -39,7 +39,7 @@ test_that("as.data.frame.safe_call returns the expected columns", {
expect_equal(res$args[[1]], x$args)
})
-test_that("as.data.frame.safe_call keeps a stable 'args' column regardless of arity", {
+test_that("as.data.frame.safe_call keeps a stable 'args' column regardless", {
# regression test: `args = x$args` inside data.frame() lets R recurse into
# the named list and expand/rename it, so a single-argument call collapses
# the "args" column into a column named after that argument (e.g. "x" for
@@ -72,7 +72,7 @@ test_that("as.data.frame.safe_call keeps a stable 'args' column regardless of ar
expect_true("args" %in% names(as.data.frame(two_arg)))
})
-test_that("as.data.frame.safe_call is not shadowed by a conflicting definition", {
+test_that("as.data.frame.safe_call is not shadowed by a conflicting def.", {
# regression test: safe-call.R and safe-call-utils.R previously both
# defined `as.data.frame.safe_call()` with different (incompatible) sets
# of columns; whichever file was sourced last silently won. This checks
diff --git a/tests/testthat/test-safe-people.R b/tests/testthat/test-safe-people.R
index c8ecdae..dfd2494 100644
--- a/tests/testthat/test-safe-people.R
+++ b/tests/testthat/test-safe-people.R
@@ -1,7 +1,7 @@
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -#
# - - - - - - - - - - - - - - - - - ERRORS - - - - - - - - - - - - - - - - - #
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -#
-test_that("safe_people fails when attempt calling function with invalid class", {
+test_that("safe_people fails when calling function with invalid class", {
expect_error(
dsROCrate::safe_people(structure(list(), class = "InvalidClass"))
)
diff --git a/tests/testthat/test-safe-project.R b/tests/testthat/test-safe-project.R
index f5988aa..36d8f02 100644
--- a/tests/testthat/test-safe-project.R
+++ b/tests/testthat/test-safe-project.R
@@ -1,7 +1,7 @@
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -#
# - - - - - - - - - - - - - - - - - ERRORS - - - - - - - - - - - - - - - - - #
# - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -#
-test_that("safe_project fails when attempt calling function with invalid class", {
+test_that("safe_project fails when calling function with invalid class", {
expect_error(
dsROCrate::safe_project(
structure(list(), class = "InvalidClass"),
diff --git a/tests/testthat/test-safe_output.R b/tests/testthat/test-safe_output.R
index c0d54fd..286c32e 100644
--- a/tests/testthat/test-safe_output.R
+++ b/tests/testthat/test-safe_output.R
@@ -18,7 +18,7 @@ test_that("safe_output fails when attempt calling with invalid connection", {
)
})
-test_that("safe_output warns when calling with RO-Crate without Safe People details", {
+test_that("safe_output warns when RO-Crate is missing Safe People details", {
# setup
## open connection to OBiBa's Opal demo server
opal_con <- opal_demo_con()
@@ -34,7 +34,7 @@ test_that("safe_output warns when calling with RO-Crate without Safe People deta
opalr::opal.logout(opal_con)
})
-test_that("safe_output warns when attempt setting multiple users as the RO-Crate authors", {
+test_that("safe_output warns when setting multiple users as the authors", {
# setup
## open connection to OBiBa's Opal demo server
opal_con <- opal_demo_con()
diff --git a/tests/testthat/test-set_crate_context.R b/tests/testthat/test-set_crate_context.R
new file mode 100644
index 0000000..8b67dd9
--- /dev/null
+++ b/tests/testthat/test-set_crate_context.R
@@ -0,0 +1,84 @@
+context_attrs <- c(
+ "connection",
+ "path",
+ "profile",
+ "project",
+ "resources",
+ "tables",
+ "user",
+ "backend_validated"
+)
+
+test_that("set_crate_context() attaches the context as attributes", {
+ con <- fake_opal_con()
+ crate <- structure(list(`@graph` = list()), class = "rocrate")
+
+ res <- set_crate_context(
+ crate,
+ connection = con,
+ path = "path/to/crate",
+ profile = "default",
+ project = "CNSIM",
+ resources = c("RSRC1", "RSRC2"),
+ tables = "CNSIM1",
+ user = "dsuser"
+ )
+
+ expect_identical(attr(res, "connection"), con)
+ expect_equal(attr(res, "path"), "path/to/crate")
+ expect_equal(attr(res, "profile"), "default")
+ expect_equal(attr(res, "project"), "CNSIM")
+ expect_equal(attr(res, "resources"), c("RSRC1", "RSRC2"))
+ expect_equal(attr(res, "tables"), "CNSIM1")
+ expect_equal(attr(res, "user"), "dsuser")
+})
+
+test_that("set_crate_context() leaves the crate itself untouched", {
+ crate <- structure(
+ list(`@graph` = list(list(`@id` = "a"))),
+ class = "rocrate"
+ )
+
+ res <- set_crate_context(crate, project = "CNSIM")
+
+ expect_s3_class(res, "rocrate")
+ expect_equal(unclass(res)$`@graph`, unclass(crate)$`@graph`)
+ # the input object is not modified
+ expect_null(attr(crate, "project"))
+})
+
+test_that("set_crate_context() removes the attributes that are set to NULL", {
+ crate <- structure(list(), class = "rocrate")
+ crate <- set_crate_context(crate, project = "CNSIM", tables = "CNSIM1")
+
+ res <- set_crate_context(crate, project = "CNSIM")
+
+ expect_equal(attr(res, "project"), "CNSIM")
+ expect_null(attr(res, "tables"))
+})
+
+test_that("set_crate_context() preserves all attributes, not part of context", {
+ crate <- structure(list(), class = "rocrate", custom = "keep me")
+
+ res <- set_crate_context(crate, user = "dsuser")
+
+ expect_equal(attr(res, "custom"), "keep me")
+ expect_s3_class(res, "rocrate")
+})
+
+test_that("set_crate_context() only sets the documented attributes", {
+ crate <- structure(list(), class = "rocrate")
+
+ res <- set_crate_context(
+ crate,
+ connection = fake_opal_con(),
+ path = "p",
+ profile = "default",
+ project = "CNSIM",
+ resources = "R",
+ tables = "T",
+ user = "u"
+ )
+
+ expect_setequal(setdiff(names(attributes(res)), "class"), context_attrs)
+})
diff --git a/tests/testthat/test-shared-project-context.R b/tests/testthat/test-shared-project-context.R
new file mode 100644
index 0000000..837433f
--- /dev/null
+++ b/tests/testthat/test-shared-project-context.R
@@ -0,0 +1,254 @@
+# helper: mock all the backend requests made by `safe_project()` and
+# `safe_data()`, and count them
+mock_project_backend <- function(.env = parent.frame()) {
+ calls <- new.env(parent = emptyenv())
+ for (name in c(
+ "validate",
+ "exists",
+ "project",
+ "project_perms",
+ "tables",
+ "resources",
+ "table_perms",
+ "resource_perms"
+ )) {
+ calls[[name]] <- 0L
+ }
+ count <- function(name) {
+ calls[[name]] <- calls[[name]] + 1L
+ }
+ timestamps <- list(
+ created = "2026-10-13T04:26:14.076Z",
+ lastUpdate = "2026-10-13T14:17:32.082Z"
+ )
+
+ testthat::local_mocked_bindings(
+ validate_backend = function(x, ...) {
+ count("validate")
+ invisible(TRUE)
+ },
+ project_exists = function(x, ...) {
+ count("exists")
+ invisible(TRUE)
+ },
+ backend_users = function(x, ...) {
+ list(list(principal = "dsuser", groups = list()))
+ },
+ backend_project = function(x, project, ...) {
+ count("project")
+ list(name = project, timestamps = timestamps)
+ },
+ backend_project_perms = function(x, project, ...) {
+ count("project_perms")
+ data.frame(
+ subject = "administrator",
+ type = "user",
+ permission = "administrate",
+ stringsAsFactors = FALSE
+ )
+ },
+ backend_tables = function(x, project, ...) {
+ count("tables")
+ list(
+ list(name = "T1", timestamps = timestamps),
+ list(name = "T2", timestamps = timestamps)
+ )
+ },
+ backend_resources = function(x, project, ...) {
+ count("resources")
+ list()
+ },
+ backend_table_perms = function(x, project, ...) {
+ count("table_perms")
+ data.frame(
+ subject = "dsuser",
+ type = "user",
+ permission = "view",
+ stringsAsFactors = FALSE
+ )
+ },
+ backend_resource_perms = function(x, project, ...) {
+ count("resource_perms")
+ data.frame(
+ subject = character(),
+ type = character(),
+ permission = character(),
+ stringsAsFactors = FALSE
+ )
+ },
+ .env = .env
+ )
+
+ calls
+}
+
+test_that("safe_project() and safe_data() share requests about a project", {
+ calls <- mock_project_backend()
+ con <- fake_opal_con()
+
+ crate <- init(con, project = "CNSIM") |>
+ safe_project() |>
+ safe_data()
+
+ expect_equal(calls$exists, 1L)
+ expect_equal(calls$tables, 1L)
+ expect_equal(calls$resources, 1L)
+ # the permissions of each table are still requested (see issue #42)
+ expect_equal(calls$table_perms, 2L)
+ expect_s3_class(crate, "rocrate")
+})
+
+test_that("safe_project() alone requests the project and assets once", {
+ calls <- mock_project_backend()
+ con <- fake_opal_con()
+
+ safe_project(con, project = "CNSIM")
+
+ expect_equal(calls$exists, 1L)
+ expect_equal(calls$tables, 1L)
+ expect_equal(calls$resources, 1L)
+})
+
+test_that("safe_data() alone requests the project and assets once", {
+ calls <- mock_project_backend()
+ con <- fake_opal_con()
+
+ safe_data(con, project = "CNSIM")
+
+ expect_equal(calls$exists, 1L)
+ expect_equal(calls$tables, 1L)
+ expect_equal(calls$resources, 1L)
+})
+
+test_that("functions called with a new RO-Crate do not share requests", {
+ calls <- mock_project_backend()
+ con <- fake_opal_con()
+
+ safe_project(con, project = "CNSIM")
+ safe_data(con, project = "CNSIM")
+
+ expect_equal(calls$exists, 2L)
+ expect_equal(calls$tables, 2L)
+ expect_equal(calls$resources, 2L)
+})
+
+test_that("each project in the RO-Crate has its own shared requests", {
+ calls <- mock_project_backend()
+ con <- fake_opal_con()
+
+ crate <- init(con) |>
+ safe_project(project = "P1") |>
+ safe_project(project = "P2") |>
+ safe_data(project = "P1") |>
+ safe_data(project = "P2")
+
+ expect_equal(calls$exists, 2L)
+ expect_equal(calls$tables, 2L)
+ expect_equal(calls$resources, 2L)
+ expect_equal(sort(names(attr(crate, "project_context"))), c("P1", "P2"))
+})
+
+test_that("init() discards the requests shared by a previous initialisation", {
+ calls <- mock_project_backend()
+ con <- fake_opal_con()
+
+ crate <- init(con, project = "CNSIM") |> safe_project()
+ expect_equal(calls$tables, 1L)
+
+ crate <- init(con, rocrate = crate, project = "CNSIM")
+ expect_null(attr(crate, "project_context"))
+
+ safe_data(crate)
+ expect_equal(calls$tables, 2L)
+})
+
+test_that("the requests are not shared with a different connection", {
+ calls <- mock_project_backend()
+ crate <- init(fake_opal_con("user_a"), project = "CNSIM") |> safe_project()
+
+ safe_data(fake_opal_con("user_b"), rocrate = crate, project = "CNSIM")
+
+ expect_equal(calls$tables, 2L)
+})
+
+test_that("sharing the requests does not change the RO-Crate", {
+ mock_project_backend()
+ con <- fake_opal_con()
+
+ shared <- init(con, project = "CNSIM") |>
+ safe_project() |>
+ safe_data()
+
+ # same steps, without sharing the requests
+ separate <- init(con, project = "CNSIM") |>
+ safe_project() |>
+ reset_project_context() |>
+ safe_data()
+
+ expect_equal(shared$`@graph`, separate$`@graph`)
+})
+
+test_that("a missing project is reported by every function", {
+ local_mocked_bindings(
+ validate_backend = function(x, ...) invisible(TRUE),
+ project_exists = function(x, ...) stop("project not found", call. = FALSE)
+ )
+ con <- fake_opal_con()
+
+ expect_error(safe_project(con, project = "NOPE"), "project not found")
+ expect_error(safe_data(con, project = "NOPE"), "project not found")
+})
+
+test_that("safe_project() and safe_data() share the permissions", {
+ calls <- mock_project_backend()
+ con <- fake_opal_con()
+
+ init(con, project = "CNSIM") |>
+ safe_project() |>
+ safe_data()
+
+ # requested by safe_project(), to get the members of the project
+ expect_equal(calls$project_perms, 1L)
+ expect_equal(calls$table_perms, 2L)
+ expect_equal(calls$resource_perms, 0L)
+})
+
+test_that("the permissions are not shared between new RO-Crates", {
+ calls <- mock_project_backend()
+ con <- fake_opal_con()
+
+ safe_project(con, project = "CNSIM")
+ safe_data(con, project = "CNSIM")
+
+ expect_equal(calls$project_perms, 1L)
+ expect_equal(calls$table_perms, 4L)
+})
+
+test_that("safe_project() only requests the permissions of audited tables", {
+ calls <- mock_project_backend()
+ con <- fake_opal_con()
+
+ init(con, project = "CNSIM", tables = "T1") |>
+ safe_project() |>
+ safe_data()
+
+ expect_equal(calls$tables, 1L)
+ # (the permissions of `T2` are not needed)
+ expect_equal(calls$table_perms, 1L)
+})
+
+test_that("users with permissions on a table are members of the project", {
+ # `dsuser` only has permissions on the tables, not on the project
+ mock_project_backend()
+ con <- fake_opal_con()
+
+ crate <- init(con, project = "CNSIM", user = "dsuser") |>
+ safe_people() |>
+ safe_project()
+
+ person <- .get_entity(crate, type = "Person")[[1]]
+ project <- .get_entity(crate, type = "Project")[[1]]
+
+ expect_equal(person$name, "dsuser")
+ expect_true(project[["@id"]] %in% unlist(person$memberOf))
+})
diff --git a/tests/testthat/test-symbol-registry.R b/tests/testthat/test-symbol-registry.R
index 4c9ebf0..b620d14 100644
--- a/tests/testthat/test-symbol-registry.R
+++ b/tests/testthat/test-symbol-registry.R
@@ -17,7 +17,7 @@ test_that("register_symbol adds a symbol to an empty registry", {
expect_equal(registry$symbols$version, 1L)
})
-test_that("as.data.frame.symbol_registry does not error on a populated registry", {
+test_that("as.data.frame.symbol_registry does not error on a pop. registry", {
# regression test: as.data.frame.symbol_registry previously used
# `lapply(x$symbols, function(sym) ...)`, which iterates over the
# *columns* of the underlying tibble rather than its rows, so `sym`
@@ -41,7 +41,7 @@ test_that("as.data.frame.symbol_registry does not error on a populated registry"
expect_equal(nrow(res), 1)
})
-test_that("as.data.frame.symbol_registry returns the expected, correctly-populated columns", {
+test_that("as.data.frame.symbol_registry returns the expected cols", {
# regression test: the id column was previously populated from
# `sym$symbol` instead of `sym$id`, and the method referenced
# non-existent `parent`/`column` fields.
@@ -80,7 +80,7 @@ test_that("as.data.frame.symbol_registry returns the expected, correctly-populat
expect_false(identical(res$id, res$symbol))
})
-test_that("as.data.frame.symbol_registry returns an empty data frame for an empty registry", {
+test_that("as.data.frame.symbol_registry handles empty registries", {
registry <- symbol_registry()
res <- as.data.frame(registry)
diff --git a/tests/testthat/test-utils-armadillo.R b/tests/testthat/test-utils-armadillo.R
index bdd547f..bff6dbe 100644
--- a/tests/testthat/test-utils-armadillo.R
+++ b/tests/testthat/test-utils-armadillo.R
@@ -21,7 +21,7 @@ test_that("armadillo_login returns invisible connection object", {
expect_equal(result, mock_conn)
})
-test_that("armadillo_login calls armadillo.get_credentials with correct server", {
+test_that("armadillo_login calls `get_credentials` with correct server", {
skip_if_not_installed("MolgenisArmadillo")
called_server <- NULL
@@ -43,8 +43,7 @@ test_that("armadillo_login calls armadillo.get_credentials with correct server",
# -------------------------------------------------------------------------
# Side-effect tests: namespace global assignments
# -------------------------------------------------------------------------
-
-test_that("armadillo_login assigns armadillo_url in MolgenisArmadillo namespace", {
+test_that("armadillo_login assigns armadillo_url in the correct namespace", {
skip_if_not_installed("MolgenisArmadillo")
pkgenv <- get_pkgenv()
diff --git a/tests/testthat/test-utils-base-R.R b/tests/testthat/test-utils-base-R.R
new file mode 100644
index 0000000..96f52be
--- /dev/null
+++ b/tests/testthat/test-utils-base-R.R
@@ -0,0 +1,48 @@
+test_that("the package defines its own %||% (base R only has it from 4.4.0)", {
+ # on R >= 4.4 the base version would hide a missing definition, so check
+ # the package namespace directly
+ expect_true(
+ exists("%||%", envir = asNamespace("dsROCrate"), inherits = FALSE)
+ )
+})
+
+test_that("%||% returns x when it is not NULL", {
+ expect_equal("a" %||% "b", "a")
+ expect_equal(1L %||% 2L, 1L)
+ expect_equal(list(a = 1) %||% list(), list(a = 1))
+})
+
+test_that("%||% only treats NULL as missing", {
+ # unlike the helper used before 0.2.4, NA and "" are kept
+ expect_identical(NA %||% "b", NA)
+ expect_identical(NA_character_ %||% "b", NA_character_)
+ expect_identical("" %||% "b", "")
+ expect_identical(FALSE %||% TRUE, FALSE)
+ expect_identical(0 %||% 1, 0)
+ expect_identical(character(0) %||% "b", character(0))
+})
+
+test_that("%||% returns y when x is NULL", {
+ expect_equal(NULL %||% "b", "b")
+ expect_equal(NULL %||% list(), list())
+ expect_null(NULL %||% NULL)
+})
+
+test_that("%||% works with vectors longer than one", {
+ # the old helper used `&&` and errored for these on R >= 4.3
+ expect_equal(c("a", "b") %||% "z", c("a", "b"))
+})
+
+test_that("%||% evaluates y lazily", {
+ expect_equal("a" %||% stop("y must not be evaluated"), "a")
+ expect_error(NULL %||% stop("y is evaluated"), "y is evaluated")
+})
+
+test_that("%||% agrees with base R's version", {
+ skip_if(getRversion() < "4.4.0")
+ base_or <- get("%||%", envir = baseenv())
+
+ for (x in list(NULL, "a", NA, "", character(0), 1:3)) {
+ expect_identical(x %||% "y", base_or(x, "y"))
+ }
+})
diff --git a/tests/testthat/test-utils-connection.R b/tests/testthat/test-utils-connection.R
index 69e793e..7b8ccc4 100644
--- a/tests/testthat/test-utils-connection.R
+++ b/tests/testthat/test-utils-connection.R
@@ -35,26 +35,6 @@ test_that("project_exists() dispatches to opal method", {
opalr::opal.logout(opal_con)
})
-# test_that("project_exists() works for armadillo objects", {
-# skip_if_not_installed("MolgenisArmadillo")
-#
-# arm <- methods::new("ArmadilloCredentials")
-#
-# local_mocked_bindings(
-# armadillo.list_projects = function() c("proj1", "proj2"),
-# .package = "MolgenisArmadillo"
-# )
-#
-# expect_silent(
-# project_exists(arm, project = "proj1")
-# )
-#
-# expect_error(
-# project_exists(arm, project = "missing"),
-# "was not found in the given Armadillo connection!"
-# )
-# })
-
test_that("parse_user_profiles() dispatches to opal method", {
opal_con <- structure(list(), class = "opal")
@@ -71,7 +51,7 @@ test_that("parse_user_profiles() dispatches to opal method", {
expect_equal(res$principal, "user1")
})
-test_that("parse_user_profiles.opal() returns empty tibble when no matching users", {
+test_that("parse_user_profiles.opal() handles no matching users", {
opal_con <- structure(list(), class = "opal")
local_mocked_bindings(
diff --git a/tests/testthat/test-utils-opal.R b/tests/testthat/test-utils-opal.R
index ab1a03d..a389798 100644
--- a/tests/testthat/test-utils-opal.R
+++ b/tests/testthat/test-utils-opal.R
@@ -8,19 +8,6 @@ test_that("validate_con works with real Opal connection", {
opalr::opal.logout(opal_con)
})
-test_that("is_admin_con detects admin connection correctly", {
- # open connection to OBiBa's Opal demo server
- opal_con <- opal_demo_con()
-
- res <- is_admin_con(opal_con)
-
- expect_type(res, "logical")
- expect_true(res)
-
- # close connection to OBiBa's Opal demo server
- opalr::opal.logout(opal_con)
-})
-
test_that("validate_con errors on invalid connection object", {
bad_con <- list(handle = list(handle = NULL))
@@ -70,3 +57,390 @@ test_that("user_perm_entity returns NULL for unknown 'permission'", {
expect_length(output_tbl, 1)
expect_type(output_tbl, "list")
})
+
+test_that("safe_desc() returns the description when there is one", {
+ expect_equal(
+ safe_desc("Baseline cohort", "CNSIM1", "table"),
+ "Baseline cohort"
+ )
+})
+
+test_that("safe_desc() falls back to ' ' for missing values", {
+ expect_equal(safe_desc(NULL, "CNSIM1", "table"), "table CNSIM1")
+ expect_equal(safe_desc(NA, "CNSIM1", "table"), "table CNSIM1")
+ expect_equal(safe_desc(NA_character_, "CNSIM1", "table"), "table CNSIM1")
+ expect_equal(safe_desc("", "CNSIM1", "table"), "table CNSIM1")
+})
+
+test_that("safe_desc() uses the asset type in the fallback", {
+ expect_equal(safe_desc("", "RSRC", "resource"), "resource RSRC")
+})
+
+test_that("safe_desc() returns a single string", {
+ res <- safe_desc("", "CNSIM1", "table")
+
+ expect_type(res, "character")
+ expect_length(res, 1)
+})
+
+test_that("get_project_assets() keeps missing table fields as empty values", {
+ local_mocked_bindings(
+ project_exists = function(x, project, ...) TRUE,
+ backend_tables = function(x, project, ...) {
+ list(
+ # no `description`, as returned by the demo server
+ list(
+ name = "CNSIM1",
+ link = "/datasource/CNSIM/table/CNSIM1",
+ timestamps = list(
+ created = "2026-10-13T04:26:14.076Z",
+ lastUpdate = "2026-10-13T14:17:32.082Z"
+ )
+ ),
+ # no `link`, but a description
+ list(
+ name = "CNSIM2",
+ description = "Second table",
+ timestamps = list(
+ created = "2026-10-13T04:26:14.076Z",
+ lastUpdate = "2026-10-13T14:17:32.082Z"
+ )
+ )
+ )
+ }
+ )
+
+ assets <- get_project_assets(fake_opal_con(), "CNSIM", "tables")
+
+ expect_equal(assets$name, c("CNSIM1", "CNSIM2"))
+ expect_equal(assets$description, c("", "Second table"))
+ expect_false(is.na(assets$url[1]))
+ expect_true(is.na(assets$url[2]))
+})
+
+test_that("tables without a description get the fallback in the entity", {
+ local_mocked_bindings(
+ project_exists = function(x, project, ...) TRUE,
+ backend_tables = function(x, project, ...) {
+ list(
+ list(name = "CNSIM1", timestamps = list()),
+ list(name = "CNSIM2", description = "Second table", timestamps = list())
+ )
+ }
+ )
+
+ assets <- get_project_assets(fake_opal_con(), "CNSIM", "tables")
+ entities <- build_asset_entities(
+ assets,
+ project_id = "#project:abc",
+ asset_id_suffix = "#dataset:"
+ )
+
+ expect_equal(entities[[1]]$description, "table CNSIM1")
+ expect_equal(entities[[2]]$description, "Second table")
+})
+
+# shape of `opal.tables(df = FALSE)` / `opal.resources(df = FALSE)` on the Opal
+# demo server (project CNSIM).
+fixture_opal_tables <- function() {
+ list(
+ list(
+ name = "CNSIM1",
+ entityType = "Participant",
+ link = "/datasource/CNSIM/table/CNSIM1",
+ datasourceName = "CNSIM",
+ timestamps = list(
+ created = "2026-10-13T04:26:14.076Z",
+ lastUpdate = "2026-10-13T14:17:32.082Z"
+ ),
+ status = "READY"
+ ),
+ list(
+ name = "CNSIM2",
+ entityType = "Participant",
+ link = "/datasource/CNSIM/table/CNSIM2",
+ datasourceName = "CNSIM",
+ timestamps = list(
+ created = "2026-10-13T04:26:14.076Z",
+ lastUpdate = "2026-10-13T14:17:32.082Z"
+ ),
+ status = "READY"
+ )
+ )
+}
+
+# time zones on both sides of UTC, with and without daylight saving
+test_zones <- c("UTC", "America/New_York", "Europe/London", "Pacific/Auckland")
+
+test_that("safe_time() reads backend timestamps as UTC in any time zone", {
+ inputs <- c(
+ z = "2026-10-13T04:26:14Z",
+ fraction = "2026-10-13T04:26:14.076Z",
+ nanoseconds = "2026-10-13T04:26:14.076468641Z",
+ plus_0000 = "2026-10-13T04:26:14+0000",
+ plus_offset = "2026-10-13T06:26:14+02:00",
+ minus_offset = "2026-10-12T23:26:14-0500",
+ space_separator = "2026-10-13 04:26:14"
+ )
+
+ for (tz in test_zones) {
+ withr::with_timezone(tz, {
+ for (nm in names(inputs)) {
+ expect_equal(
+ safe_time(inputs[[nm]]),
+ "2026-10-13T04:26:14Z",
+ info = paste(tz, nm)
+ )
+ }
+ })
+ }
+})
+
+test_that("safe_time() accepts POSIXct values, whatever their time zone", {
+ withr::local_timezone("America/New_York")
+
+ utc <- as.POSIXct("2026-10-13 04:26:14", tz = "UTC")
+ ny <- as.POSIXct("2026-10-13 00:26:14", tz = "America/New_York")
+
+ expect_equal(safe_time(utc), "2026-10-13T04:26:14Z")
+ expect_equal(safe_time(ny), "2026-10-13T04:26:14Z")
+})
+
+test_that("safe_time() returns an empty string for missing or invalid input", {
+ withr::local_timezone("America/New_York")
+
+ expect_identical(safe_time(NULL), "")
+ expect_identical(safe_time(NA), "")
+ expect_identical(safe_time(NA_character_), "")
+ expect_identical(safe_time(""), "")
+ expect_identical(safe_time("not a date"), "")
+ expect_identical(safe_time(c("2026-10-13T04:26:14Z", "x")), "")
+})
+
+test_that("safe_time() handles to be applied twice to asset timestamps", {
+ for (tz in test_zones) {
+ withr::with_timezone(tz, {
+ once <- safe_time("2026-10-13T04:26:14.076Z")
+
+ expect_equal(safe_time(once), once, info = tz)
+ expect_identical(safe_time(safe_time(NULL)), "", info = tz)
+ })
+ }
+})
+
+test_that("safe_time() gives the same result in every time zone", {
+ results <- vapply(
+ test_zones,
+ function(tz) {
+ withr::with_timezone(tz, safe_time("2026-10-13T04:26:14.076Z"))
+ },
+ character(1)
+ )
+
+ expect_length(unique(results), 1)
+})
+
+test_that("get_project_assets() returns UTC timestamps for tables", {
+ local_mocked_bindings(
+ project_exists = function(x, project, ...) TRUE,
+ backend_tables = function(x, project, ...) fixture_opal_tables()
+ )
+
+ for (tz in test_zones) {
+ withr::with_timezone(tz, {
+ assets <- get_project_assets(fake_opal_con(), "CNSIM", "tables")
+
+ expect_equal(
+ assets$created,
+ rep("2026-10-13T04:26:14Z", 2),
+ info = tz
+ )
+ expect_equal(
+ assets$updated,
+ rep("2026-10-13T14:17:32Z", 2),
+ info = tz
+ )
+ })
+ }
+})
+
+test_that("table entities have dateCreated/dateModified in UTC", {
+ local_mocked_bindings(
+ project_exists = function(x, project, ...) TRUE,
+ backend_tables = function(x, project, ...) fixture_opal_tables()
+ )
+
+ for (tz in test_zones) {
+ withr::with_timezone(tz, {
+ assets <- get_project_assets(fake_opal_con(), "CNSIM", "tables")
+ entities <- build_asset_entities(
+ assets,
+ project_id = "#project:abc",
+ asset_id_suffix = "#dataset:"
+ )
+
+ expect_length(entities, 2)
+ for (e in entities) {
+ expect_equal(e$dateCreated, "2026-10-13T04:26:14Z", info = tz)
+ expect_equal(e$dateModified, "2026-10-13T14:17:32Z", info = tz)
+ }
+ })
+ }
+})
+
+test_that("resource entities have dateCreated/dateModified in UTC", {
+ local_mocked_bindings(
+ project_exists = function(x, project, ...) TRUE,
+ backend_resources = function(x, project, ...) {
+ list(
+ list(
+ name = "RSRC1",
+ created = "2026-10-13T04:26:14.076Z",
+ updated = "2026-10-13T14:17:32.082Z",
+ parameters = "",
+ resource = list(url = "https://example.org/data.csv")
+ )
+ )
+ }
+ )
+
+ for (tz in test_zones) {
+ withr::with_timezone(tz, {
+ assets <- get_project_assets(fake_opal_con(), "CNSIM", "resources")
+ entities <- build_asset_entities(
+ assets,
+ project_id = "#project:abc",
+ asset_id_suffix = "#dataset:"
+ )
+
+ expect_equal(entities[[1]]$dateCreated, "2026-10-13T04:26:14Z", info = tz)
+ expect_equal(
+ entities[[1]]$dateModified,
+ "2026-10-13T14:17:32Z",
+ info = tz
+ )
+ })
+ }
+})
+
+test_that("assets without timestamps get empty dates, not NA", {
+ local_mocked_bindings(
+ project_exists = function(x, project, ...) TRUE,
+ backend_tables = function(x, project, ...) {
+ list(list(name = "CNSIM1", timestamps = list()))
+ }
+ )
+ withr::local_timezone("America/New_York")
+
+ assets <- get_project_assets(fake_opal_con(), "CNSIM", "tables")
+ entities <- build_asset_entities(assets, "#project:abc", "#dataset:")
+
+ expect_identical(entities[[1]]$dateCreated, "")
+ expect_identical(entities[[1]]$dateModified, "")
+})
+
+test_that("get_project_assets() verifies the project by default", {
+ n_exists <- 0L
+ local_mocked_bindings(
+ project_exists = function(x, ...) {
+ n_exists <<- n_exists + 1L
+ invisible(TRUE)
+ },
+ backend_tables = function(x, project, ...) list(list(name = "T1")),
+ backend_resources = function(x, project, ...) list()
+ )
+
+ get_project_assets(fake_opal_con(), "P1", "tables")
+ expect_equal(n_exists, 1L)
+
+ get_project_assets(fake_opal_con(), "P1", "resources")
+ expect_equal(n_exists, 2L)
+})
+
+test_that("get_project_assets(check = FALSE) skips the project check", {
+ n_exists <- 0L
+ local_mocked_bindings(
+ project_exists = function(x, ...) {
+ n_exists <<- n_exists + 1L
+ invisible(TRUE)
+ },
+ backend_tables = function(x, project, ...) list(list(name = "T1")),
+ backend_resources = function(x, project, ...) list()
+ )
+
+ tbls <- get_project_assets(fake_opal_con(), "P1", "tables", check = FALSE)
+ res <- get_project_assets(fake_opal_con(), "P1", "resources", check = FALSE)
+
+ expect_equal(n_exists, 0L)
+ expect_equal(tbls$name, "T1")
+ expect_null(res)
+})
+
+test_that("get_project_assets() errors for unknown projects if checked", {
+ local_mocked_bindings(
+ project_exists = function(x, ...) stop("project not found", call. = FALSE),
+ backend_tables = function(x, project, ...) list(list(name = "T1"))
+ )
+
+ expect_error(
+ get_project_assets(fake_opal_con(), "P1", "tables"),
+ "project not found"
+ )
+ expect_no_error(
+ get_project_assets(fake_opal_con(), "P1", "tables", check = FALSE)
+ )
+})
+
+test_that("get_asset_permissions() requests the permissions to the backend", {
+ n_table <- 0L
+ n_resource <- 0L
+ local_mocked_bindings(
+ backend_table_perms = function(x, project, table, ...) {
+ n_table <<- n_table + 1L
+ data.frame(subject = "dsuser", type = "user", permission = "view")
+ },
+ backend_resource_perms = function(x, project, resource, ...) {
+ n_resource <<- n_resource + 1L
+ data.frame(
+ subject = character(),
+ type = character(),
+ permission = character()
+ )
+ }
+ )
+ con <- fake_opal_con()
+
+ tbl <- get_asset_permissions(con, "P1", "table", "T1")
+ get_asset_permissions(con, "P1", "table", "T1")
+ res <- get_asset_permissions(con, "P1", "resource", "R1")
+
+ expect_equal(tbl$person, "dsuser")
+ expect_equal(tbl$permission, "view")
+ # no permissions
+ expect_null(res)
+ # not shared without a context
+ expect_equal(n_table, 2L)
+ expect_equal(n_resource, 1L)
+})
+
+test_that("get_asset_permissions() shares the permissions of a context", {
+ n_table <- 0L
+ local_mocked_bindings(
+ backend_table_perms = function(x, project, table, ...) {
+ n_table <<- n_table + 1L
+ data.frame(subject = "dsuser", type = "user", permission = "view")
+ }
+ )
+ con <- fake_opal_con()
+ context <- new_project_context(con, "P1")
+
+ first <- get_asset_permissions(con, "P1", "table", "T1", context)
+ second <- get_asset_permissions(con, "P1", "table", "T1", context)
+ # already requested by another function
+ project_context_permissions(context, "table", "T2")
+ get_asset_permissions(con, "P1", "table", "T2", context)
+
+ expect_identical(first, second)
+ expect_equal(first$person, "dsuser")
+ expect_equal(n_table, 2L)
+})
diff --git a/tests/testthat/test-utils-project-context.R b/tests/testthat/test-utils-project-context.R
new file mode 100644
index 0000000..f9f2486
--- /dev/null
+++ b/tests/testthat/test-utils-project-context.R
@@ -0,0 +1,398 @@
+# helper: mock the backend requests about a project and count them
+mock_asset_requests <- function(.env = parent.frame()) {
+ calls <- new.env(parent = emptyenv())
+ calls$exists <- 0L
+ calls$tables <- 0L
+ calls$resources <- 0L
+
+ testthat::local_mocked_bindings(
+ project_exists = function(x, ...) {
+ calls$exists <- calls$exists + 1L
+ invisible(TRUE)
+ },
+ backend_tables = function(x, project, ...) {
+ calls$tables <- calls$tables + 1L
+ list(list(name = "T1"), list(name = "T2"))
+ },
+ backend_resources = function(x, project, ...) {
+ calls$resources <- calls$resources + 1L
+ list()
+ },
+ .env = .env
+ )
+
+ calls
+}
+
+test_that("get_project_context() creates a context for the project", {
+ con <- fake_opal_con()
+
+ context <- get_project_context(con, "P1")
+
+ expect_true(is_project_context(context))
+ expect_equal(context$project, "P1")
+ expect_identical(context$connection, con)
+})
+
+test_that("get_project_context() creates a context without an RO-Crate", {
+ con <- fake_opal_con()
+ crate <- structure(list(), class = "rocrate")
+
+ expect_true(is_project_context(get_project_context(con, "P1", NULL)))
+ expect_true(is_project_context(get_project_context(con, "P1", crate)))
+})
+
+test_that("get_project_context() reuses the context stored in the RO-Crate", {
+ con <- fake_opal_con()
+ crate <- structure(list(), class = "rocrate")
+ context <- get_project_context(con, "P1", crate)
+ crate <- set_project_context(crate, context)
+
+ expect_identical(get_project_context(con, "P1", crate), context)
+})
+
+test_that("get_project_context() does not reuse another project's context", {
+ con <- fake_opal_con()
+ crate <- structure(list(), class = "rocrate")
+ crate <- set_project_context(crate, get_project_context(con, "P1", crate))
+
+ other <- get_project_context(con, "P2", crate)
+
+ expect_equal(other$project, "P2")
+ expect_false(identical(other, get_project_context(con, "P1", crate)))
+})
+
+test_that("get_project_context() does not reuse another connection's one", {
+ crate <- structure(list(), class = "rocrate")
+ context <- get_project_context(fake_opal_con("user_a"), "P1", crate)
+ crate <- set_project_context(crate, context)
+
+ other <- get_project_context(fake_opal_con("user_b"), "P1", crate)
+
+ expect_false(identical(other, context))
+ expect_equal(other$connection$username, "user_b")
+})
+
+test_that("set_project_context() keeps the contexts of other projects", {
+ con <- fake_opal_con()
+ crate <- structure(list(), class = "rocrate")
+ context_1 <- new_project_context(con, "P1")
+ context_2 <- new_project_context(con, "P2")
+
+ crate <- crate |>
+ set_project_context(context_1) |>
+ set_project_context(context_2)
+
+ expect_identical(get_project_context(con, "P1", crate), context_1)
+ expect_identical(get_project_context(con, "P2", crate), context_2)
+ expect_equal(sort(names(attr(crate, "project_context"))), c("P1", "P2"))
+})
+
+test_that("set_project_context() leaves the crate and its context untouched", {
+ con <- fake_opal_con()
+ crate <- structure(
+ list(`@graph` = list(list(`@id` = "a"))),
+ class = "rocrate"
+ )
+ crate <- set_crate_context(crate, connection = con, project = "P1")
+
+ res <- set_project_context(crate, new_project_context(con, "P1"))
+
+ expect_s3_class(res, "rocrate")
+ expect_equal(unclass(res)$`@graph`, unclass(crate)$`@graph`)
+ expect_equal(get_crate_context(res, "project"), "P1")
+ # the input object is not modified
+ expect_null(attr(crate, "project_context"))
+})
+
+test_that("reset_project_context() removes the stored contexts", {
+ con <- fake_opal_con()
+ crate <- structure(list(), class = "rocrate")
+ crate <- set_project_context(crate, new_project_context(con, "P1"))
+
+ res <- reset_project_context(crate)
+
+ expect_null(attr(res, "project_context"))
+ expect_false(
+ identical(
+ get_project_context(con, "P1", res),
+ get_project_context(con, "P1", crate)
+ )
+ )
+})
+
+test_that("project_context_exists() asks the backend only once", {
+ calls <- mock_asset_requests()
+ context <- new_project_context(fake_opal_con(), "P1")
+
+ expect_invisible(project_context_exists(context))
+ project_context_exists(context)
+ project_context_exists(context)
+
+ expect_equal(calls$exists, 1L)
+})
+
+test_that("project_context_exists() does not remember a missing project", {
+ calls <- new.env(parent = emptyenv())
+ calls$exists <- 0L
+ local_mocked_bindings(
+ project_exists = function(x, ...) {
+ calls$exists <- calls$exists + 1L
+ stop("project not found", call. = FALSE)
+ }
+ )
+ context <- new_project_context(fake_opal_con(), "P1")
+
+ expect_error(project_context_exists(context), "project not found")
+ expect_error(project_context_exists(context), "project not found")
+ expect_equal(calls$exists, 2L)
+})
+
+test_that("project_context_assets() lists each type of asset once", {
+ calls <- mock_asset_requests()
+ context <- new_project_context(fake_opal_con(), "P1")
+
+ first <- project_context_assets(context, "tables")
+ second <- project_context_assets(context, "tables")
+ project_context_assets(context, "resources")
+ project_context_assets(context, "resources")
+
+ expect_identical(first, second)
+ expect_equal(first$name, c("T1", "T2"))
+ expect_equal(calls$tables, 1L)
+ expect_equal(calls$resources, 1L)
+ # ... and the project is verified only once
+ expect_equal(calls$exists, 1L)
+})
+
+test_that("project_context_assets() remembers that there are no assets", {
+ calls <- mock_asset_requests()
+ context <- new_project_context(fake_opal_con(), "P1")
+
+ expect_null(project_context_assets(context, "resources"))
+ expect_null(project_context_assets(context, "resources"))
+
+ expect_equal(calls$resources, 1L)
+})
+
+test_that("project_context_assets() verifies the project before listing", {
+ calls <- new.env(parent = emptyenv())
+ calls$tables <- 0L
+ local_mocked_bindings(
+ project_exists = function(x, ...) stop("project not found", call. = FALSE),
+ backend_tables = function(x, project, ...) {
+ calls$tables <- calls$tables + 1L
+ list(list(name = "T1"))
+ }
+ )
+ context <- new_project_context(fake_opal_con(), "P1")
+
+ expect_error(project_context_assets(context, "tables"), "project not found")
+ expect_equal(calls$tables, 0L)
+})
+
+test_that("filtering the shared assets does not change them", {
+ mock_asset_requests()
+ context <- new_project_context(fake_opal_con(), "P1")
+
+ assets <- project_context_assets(context, "tables")
+ filtered <- dplyr::filter(assets, name == "T1")
+
+ expect_equal(nrow(filtered), 1)
+ expect_equal(project_context_assets(context, "tables")$name, c("T1", "T2"))
+})
+
+test_that("project_context_assets() requires a valid type", {
+ context <- new_project_context(fake_opal_con(), "P1")
+
+ expect_error(project_context_assets(context, "users"), "should be one of")
+})
+
+# helper: mock the permission requests of a project and count them
+mock_permission_requests <- function(.env = parent.frame()) {
+ calls <- new.env(parent = emptyenv())
+ calls$exists <- 0L
+ calls$tables <- 0L
+ calls$resources <- 0L
+ calls$project_perms <- 0L
+ calls$table_perms <- 0L
+ calls$resource_perms <- 0L
+ perms <- function(subject, permission) {
+ data.frame(
+ subject = subject,
+ type = "user",
+ permission = permission,
+ stringsAsFactors = FALSE
+ )
+ }
+
+ testthat::local_mocked_bindings(
+ project_exists = function(x, ...) {
+ calls$exists <- calls$exists + 1L
+ invisible(TRUE)
+ },
+ backend_tables = function(x, project, ...) {
+ calls$tables <- calls$tables + 1L
+ list(list(name = "T1"), list(name = "T2"))
+ },
+ backend_resources = function(x, project, ...) {
+ calls$resources <- calls$resources + 1L
+ list(list(name = "R1", parameters = ""))
+ },
+ backend_project_perms = function(x, project, ...) {
+ calls$project_perms <- calls$project_perms + 1L
+ perms("admin", "administrate")
+ },
+ backend_table_perms = function(x, project, table, ...) {
+ calls$table_perms <- calls$table_perms + 1L
+ perms(paste0("user_", table), "view")
+ },
+ backend_resource_perms = function(x, project, resource, ...) {
+ calls$resource_perms <- calls$resource_perms + 1L
+ perms(paste0("user_", resource), "view")
+ },
+ .env = .env
+ )
+
+ calls
+}
+
+test_that("project_context_permissions() requests each permission once", {
+ calls <- mock_permission_requests()
+ context <- new_project_context(fake_opal_con(), "P1")
+
+ project_context_permissions(context, "project")
+ project_context_permissions(context, "project")
+ first <- project_context_permissions(context, "table", "T1")
+ second <- project_context_permissions(context, "table", "T1")
+ project_context_permissions(context, "table", "T2")
+ project_context_permissions(context, "resource", "R1")
+ project_context_permissions(context, "resource", "R1")
+
+ expect_identical(first, second)
+ expect_equal(first$subject, "user_T1")
+ expect_equal(calls$project_perms, 1L)
+ expect_equal(calls$table_perms, 2L)
+ expect_equal(calls$resource_perms, 1L)
+})
+
+test_that("project_context_permissions() separates tables and resources", {
+ mock_permission_requests()
+ context <- new_project_context(fake_opal_con(), "P1")
+
+ # same name, different type of asset
+ table <- project_context_permissions(context, "table", "X")
+ resource <- project_context_permissions(context, "resource", "X")
+
+ expect_equal(table$subject, "user_X")
+ expect_equal(resource$subject, "user_X")
+ expect_equal(
+ sort(ls(context$cache)),
+ c("resource_permissions_X", "table_permissions_X")
+ )
+})
+
+test_that("project_context_permissions() needs the name of the asset", {
+ calls <- mock_permission_requests()
+ context <- new_project_context(fake_opal_con(), "P1")
+
+ expect_error(
+ project_context_permissions(context, "table"),
+ "`asset` name is required"
+ )
+ expect_error(
+ project_context_permissions(context, "resource", c("R1", "R2")),
+ "`asset` name is required"
+ )
+ expect_error(project_context_permissions(context, "users"), "should be one")
+ expect_equal(calls$table_perms + calls$resource_perms, 0L)
+})
+
+test_that("project_context_members() combines the permissions", {
+ mock_permission_requests()
+ context <- new_project_context(fake_opal_con(), "P1")
+
+ res <- project_context_members(context)
+
+ expect_equal(
+ res$subject,
+ c("admin", "user_T1", "user_T2", "user_R1")
+ )
+ expect_equal(res$via, c("project", "table", "table", "resource"))
+ expect_equal(res$asset, c(NA, "T1", "T2", "R1"))
+})
+
+test_that("project_context_members() requests everything once", {
+ calls <- mock_permission_requests()
+ context <- new_project_context(fake_opal_con(), "P1")
+
+ first <- project_context_members(context)
+ second <- project_context_members(context)
+
+ expect_identical(first, second)
+ expect_equal(calls$exists, 1L)
+ expect_equal(calls$tables, 1L)
+ expect_equal(calls$resources, 1L)
+ expect_equal(calls$project_perms, 1L)
+ expect_equal(calls$table_perms, 2L)
+ expect_equal(calls$resource_perms, 1L)
+})
+
+test_that("project_context_members() does not list the assets again", {
+ # projects without resources must not trigger another request: `NULL` means
+ # that the assets are unknown, not that there are none
+ calls <- new.env(parent = emptyenv())
+ calls$exists <- 0L
+ calls$resources <- 0L
+ local_mocked_bindings(
+ project_exists = function(x, ...) {
+ calls$exists <- calls$exists + 1L
+ invisible(TRUE)
+ },
+ backend_tables = function(x, project, ...) list(list(name = "T1")),
+ backend_resources = function(x, project, ...) {
+ calls$resources <- calls$resources + 1L
+ list()
+ },
+ backend_project_perms = function(x, project, ...) {
+ data.frame(subject = "admin", type = "user", permission = "administrate")
+ },
+ backend_table_perms = function(x, project, table, ...) {
+ data.frame(subject = "dsuser", type = "user", permission = "view")
+ }
+ )
+ context <- new_project_context(fake_opal_con(), "P1")
+
+ res <- project_context_members(context)
+
+ expect_equal(res$subject, c("admin", "dsuser"))
+ expect_equal(calls$exists, 1L)
+ expect_equal(calls$resources, 1L)
+})
+
+test_that("project_context_members() only considers the selected assets", {
+ calls <- mock_permission_requests()
+ context <- new_project_context(fake_opal_con(), "P1")
+
+ res <- project_context_members(
+ context,
+ tables = c("T2", "unknown"),
+ resources = character(0)
+ )
+
+ expect_equal(res$subject, c("admin", "user_T2"))
+ expect_equal(calls$table_perms, 1L)
+ expect_equal(calls$resource_perms, 0L)
+})
+
+test_that("project_context_members() shares the permissions it requested", {
+ calls <- mock_permission_requests()
+ context <- new_project_context(fake_opal_con(), "P1")
+
+ project_context_members(context, tables = "T1")
+ # ... for a selection of the assets, and for the rest
+ project_context_members(context, tables = c("T1", "T2"))
+
+ expect_equal(calls$table_perms, 2L)
+ expect_equal(calls$project_perms, 1L)
+})
diff --git a/tests/testthat/test-utils-report.R b/tests/testthat/test-utils-report.R
new file mode 100644
index 0000000..313f5e2
--- /dev/null
+++ b/tests/testthat/test-utils-report.R
@@ -0,0 +1,198 @@
+test_that(".validate_report_path() accepts a new file in a directory", {
+ filepath <- file.path(withr::local_tempdir(), "report.md")
+
+ expect_invisible(.validate_report_path(filepath, overwrite = FALSE))
+ expect_true(.validate_report_path(filepath, overwrite = FALSE))
+})
+
+test_that(".validate_report_path() errors if the directory does not exist", {
+ filepath <- file.path(withr::local_tempdir(), "nope", "report.md")
+
+ expect_error(
+ .validate_report_path(filepath, overwrite = TRUE),
+ "directory does not exist"
+ )
+ # the suggested command can be copied and pasted
+ expect_error(
+ .validate_report_path(filepath, overwrite = TRUE),
+ paste0("following command first:\n\t`mkdir -p ", dirname(filepath), "`"),
+ fixed = TRUE
+ )
+})
+
+test_that(".validate_report_path() only overwrites existing files if asked", {
+ filepath <- file.path(withr::local_tempdir(), "report.md")
+ writeLines("previous version", filepath)
+
+ expect_error(
+ .validate_report_path(filepath, overwrite = FALSE),
+ "points to an existing file"
+ )
+ expect_true(.validate_report_path(filepath, overwrite = TRUE))
+})
+
+test_that(".crate_root() returns the directory of a metadata file", {
+ expect_equal(
+ .crate_root("path/to/crate/ro-crate-metadata.json"),
+ "path/to/crate"
+ )
+})
+
+test_that(".crate_root() returns an RO-Crate directory as it is", {
+ dir <- withr::local_tempdir()
+
+ expect_equal(.crate_root(dir), dir)
+})
+
+test_that(".crate_root() does not guess the root of other RO-Crate formats", {
+ # BagIt directory
+ bag <- withr::local_tempdir()
+ writeLines("BagIt-Version: 1.0", file.path(bag, "bagit.txt"))
+ expect_null(.crate_root(bag))
+
+ # archive
+ expect_null(.crate_root("path/to/crate.zip"))
+ expect_null(.crate_root(NULL))
+ expect_null(.crate_root(c("a.json", "b.json")))
+})
+
+test_that(".report_tables() extracts the tables from an RO-Crate", {
+ crate <- mock_report_crate(with_outputs = TRUE)
+
+ res <- .report_tables(crate)
+
+ expect_named(
+ res,
+ c(
+ "rocrate",
+ "overview_tbl",
+ "safe_people",
+ "safe_project",
+ "safe_data",
+ "safe_data_permissions",
+ "safe_setting",
+ "safe_output"
+ )
+ )
+ expect_s3_class(res$rocrate, "rocrate")
+ expect_equal(res$safe_people$name, "dsuser")
+ expect_equal(res$safe_project$project, c("P1", "P1"))
+ # one permission per table
+ expect_equal(nrow(res$safe_data_permissions), 2)
+ expect_true(
+ all(
+ c("name", "project", "asset", "permission") %in% names(res$overview_tbl)
+ )
+ )
+ expect_equal(unique(res$overview_tbl$asset), c("T1", "T2"))
+ # ... with the functions executed by the user
+ expect_true("fx" %in% names(res$overview_tbl))
+ expect_gt(nrow(res$safe_output), 0)
+ expect_true(any(res$overview_tbl$fx != ""))
+})
+
+test_that(".report_tables() combines people and projects without permissions", {
+ crate <- mock_report_crate(table_perm_subjects = character())
+
+ res <- .report_tables(crate)
+
+ expect_equal(nrow(res$safe_data_permissions %||% tibble::tibble()), 0)
+ expect_false("permission" %in% names(res$overview_tbl))
+ expect_equal(res$overview_tbl$name, c("dsuser", "dsuser"))
+ expect_equal(res$overview_tbl$project, c("P1", "P1"))
+})
+
+test_that(".report_tables() reports which entities are missing", {
+ expect_error(
+ .report_tables(rocrateR::rocrate_5s()),
+ "RO-Crate is missing the following"
+ )
+})
+
+test_that(".report_tables() loads the contents from the path of the RO-Crate", {
+ crate <- mock_report_crate()
+ crate <- set_crate_context(crate, path = "path/to/crate")
+ loaded_from <- NULL
+ local_mocked_bindings(
+ load_content = function(rocrate, roc_path, ...) {
+ loaded_from <<- roc_path
+ rocrate
+ }
+ )
+
+ .report_tables(crate)
+
+ expect_equal(loaded_from, "path/to/crate")
+})
+
+test_that(".report_tables() does not load contents without a path", {
+ crate <- mock_report_crate()
+ n_calls <- 0L
+ local_mocked_bindings(
+ load_content = function(rocrate, ...) {
+ n_calls <<- n_calls + 1L
+ rocrate
+ }
+ )
+
+ .report_tables(crate)
+
+ expect_equal(n_calls, 0L)
+})
+
+test_that(".combine_report_tables() puts the servers together", {
+ tables <- list(
+ site_a = .report_tables(mock_report_crate("P1", with_outputs = TRUE)),
+ site_b = .report_tables(mock_report_crate("P2", with_outputs = TRUE))
+ )
+
+ res <- .combine_report_tables(tables)
+
+ expect_named(
+ res,
+ c(
+ "overview_tbl",
+ "safe_people",
+ "safe_project",
+ "safe_data",
+ "safe_data_permissions",
+ "safe_setting",
+ "safe_output"
+ )
+ )
+ expect_equal(unique(res$overview_tbl$server), c("site_a", "site_b"))
+ expect_equal(unique(res$overview_tbl$project), c("P1", "P2"))
+ expect_equal(
+ unique(res$overview_tbl[res$overview_tbl$server == "site_b", ]$project),
+ "P2"
+ )
+ expect_equal(res$safe_people$server, c("site_a", "site_b"))
+ expect_equal(unique(res$safe_project$server), c("site_a", "site_b"))
+ expect_equal(unique(res$safe_output$server), c("site_a", "site_b"))
+})
+
+test_that(".combine_report_tables() works if no server has permissions", {
+ tables <- list(
+ a = .report_tables(mock_report_crate("P1", character())),
+ b = .report_tables(mock_report_crate("P2", character()))
+ )
+
+ res <- .combine_report_tables(tables)
+
+ expect_equal(res$overview_tbl$server, c("a", "a", "b", "b"))
+ expect_equal(res$overview_tbl$name, rep("dsuser", 4))
+ expect_false("permission" %in% names(res$overview_tbl))
+})
+
+test_that(".combine_report_tables() keeps servers without permissions", {
+ tables <- list(
+ a = .report_tables(mock_report_crate("P1", "dsuser")),
+ b = .report_tables(mock_report_crate("P2", character()))
+ )
+
+ res <- .combine_report_tables(tables)
+
+ expect_equal(unique(res$overview_tbl$server), c("a", "b"))
+ # no access level for the server without permissions (and no `NA`)
+ expect_equal(res$overview_tbl$permission, c("read", "read", "", ""))
+})
diff --git a/tests/testthat/test-utils-safe_data.R b/tests/testthat/test-utils-safe_data.R
index c9036db..303e3b6 100644
--- a/tests/testthat/test-utils-safe_data.R
+++ b/tests/testthat/test-utils-safe_data.R
@@ -1,66 +1,3 @@
-test_that("extract_safe_data.opal returns a valid RO-Crate with datasets", {
- # open connection to OBiBa's Opal demo server
- opal_con <- opal_demo_con()
- # terminate connection when done with tests
- withr::defer(opalr::opal.logout(opal_con))
-
- # create local mock binding, to avoid long run times
- local_mocked_bindings(
- opal.datasources = function(...) {
- tibble::tibble(name = attr(opal_con, "PROJECT"))
- },
- .package = "opalr"
- )
-
- # ignore warning of project not having tables associated
- suppressWarnings(
- roc <- extract_safe_data(opal_con)
- )
-
- # validate rocrate structure
- expect_no_error(rocrateR::is_rocrate(roc))
-
- # should contain Dataset entities (if demo server has datasources)
- datasets <- rocrateR::get_entity(roc, type = "Dataset")
-
- expect_type(datasets, "list")
- expect_true(length(datasets) >= 1)
-
- # close connection to OBiBa's Opal demo server
- opalr::opal.logout(opal_con)
-})
-
-test_that("extract_safe_data.opal updates an existing RO-Crate", {
- # open connection to OBiBa's Opal demo server
- opal_con <- opal_demo_con()
- # terminate connection when done with tests
- withr::defer(opalr::opal.logout(opal_con))
-
- base_roc <- rocrateR::rocrate_5s()
-
- # create local mock binding, to avoid long run times
- local_mocked_bindings(
- opal.datasources = function(...) {
- tibble::tibble(name = attr(opal_con, "PROJECT"))
- },
- .package = "opalr"
- )
-
- # ignore warning of project not having tables associated
- suppressWarnings(
- roc <- extract_safe_data(opal_con, rocrate = base_roc)
- )
-
- # validate rocrate structure
- expect_no_error(rocrateR::is_rocrate(roc))
-
- datasets <- rocrateR::get_entity(roc, type = "Dataset")
- expect_true(length(datasets) >= 1)
-
- # close connection to OBiBa's Opal demo server
- opalr::opal.logout(opal_con)
-})
-
test_that("extract_safe_data.rocrate copies Dataset entities", {
# create source crate with Dataset entities
src <- rocrateR::rocrate_5s()
diff --git a/tests/testthat/test-utils-safe_output.R b/tests/testthat/test-utils-safe_output.R
index daf7b41..b4d8fc1 100644
--- a/tests/testthat/test-utils-safe_output.R
+++ b/tests/testthat/test-utils-safe_output.R
@@ -38,7 +38,7 @@ test_that("flatten_safe_output default returns empty tibble", {
})
# -------------------------------------------------------------------------
-# extract_safe_output.rocrate()
+# extract_safe_output.rocrate
# -------------------------------------------------------------------------
test_that("extract_safe_output.rocrate errors when no File entities", {
# create basic RO-Crate
@@ -185,7 +185,7 @@ test_that("extract_safe_output.rocrate filters by both id and user", {
expect_equal(getElement(files[[1]], "@id"), "outputs/user1/report.csv")
})
-test_that("extract_safe_output.rocrate errors when filters remove all entities", {
+test_that("extract_safe_output.rocrate works when filters remove everything", {
# create an RO-Crate with File entities
rocrate <- rocrateR::rocrate_5s() |>
rocrateR::add_entity(
@@ -252,7 +252,7 @@ test_that("extract_safe_output.rocrate validates rocrate input", {
})
# -------------------------------------------------------------------------
-# flatten_safe_output.rocrate()
+# flatten_safe_output.rocrate
# -------------------------------------------------------------------------
test_that("flatten_safe_output.rocrate returns tibble with correct columns", {
# create an RO-Crate with File entities
@@ -356,49 +356,3 @@ test_that("flatten_safe_output.rocrate returns empty tibble on error", {
expect_s3_class(out, "tbl_df")
expect_equal(nrow(out), 0)
})
-
-# -------------------------------------------------------------------------
-# extract_safe_output.opal() (Integration style with safe mocking)
-# -------------------------------------------------------------------------
-test_that("extract_safe_output.opal calls safe_output and returns rocrate", {
- # dummy opal-like object
- opal_con <- structure(list(), class = "opal")
-
- # Mock safe_output to avoid real server dependency
- mock_safe_output <- function(x, ..., rocrate) {
- file <- rocrateR::entity(
- id = "outputs/mock/user/file.txt",
- type = "File",
- name = "file.txt"
- )
- rocrateR::add_entity(rocrate, file)
- }
-
- with_mocked_bindings(
- safe_output = mock_safe_output,
- {
- out <- extract_safe_output.opal(opal_con)
- }
- )
-
- expect_s3_class(out, "rocrate")
-
- files <- .get_entity(out, type = "File")
- expect_true(length(files) >= 1)
-})
-
-# -------------------------------------------------------------------------
-# Optional TRUE Opal demo integration (dsROCrate audit realism)
-# -------------------------------------------------------------------------
-
-test_that("extract_safe_output.opal works with Opal demo server (if available)", {
- con <- try(opal_demo_con(), silent = TRUE)
- skip_if(inherits(con, "try-error"), "Opal demo server not available")
-
- # ignore warning about missing `path` to write outputs
- suppressWarnings(
- rocrate <- extract_safe_output(con, user = attr(con, "PEOPLE"))
- )
-
- expect_s3_class(rocrate, "rocrate")
-})
diff --git a/tests/testthat/test-utils-safe_people.R b/tests/testthat/test-utils-safe_people.R
index eb28f6e..e87dd09 100644
--- a/tests/testthat/test-utils-safe_people.R
+++ b/tests/testthat/test-utils-safe_people.R
@@ -1,118 +1,3 @@
-test_that("extract_safe_people.opal returns a valid RO-Crate with Person entities", {
- # open connection to OBiBa's Opal demo server
- opal_con <- opal_demo_con()
- # terminate connection when done with tests
- withr::defer(opalr::opal.logout(opal_con))
-
- roc <- extract_safe_people(opal_con)
-
- # validate rocrate structure
- expect_no_error(rocrateR::is_rocrate(roc))
-
- people <- rocrateR::get_entity(roc, type = "Person")
-
- expect_type(people, "list")
- expect_true(length(people) >= 1)
-
- # close connection to OBiBa's Opal demo server
- opalr::opal.logout(opal_con)
-})
-
-test_that("extract_safe_people.opal updates an existing RO-Crate", {
- # open connection to OBiBa's Opal demo server
- opal_con <- opal_demo_con()
- # terminate connection when done with tests
- withr::defer(opalr::opal.logout(opal_con))
-
- base_roc <- rocrateR::rocrate_5s()
-
- roc <- extract_safe_people(opal_con, rocrate = base_roc)
-
- # validate rocrate structure
- expect_no_error(rocrateR::is_rocrate(roc))
-
- people <- rocrateR::get_entity(roc, type = "Person")
- expect_true(length(people) >= 1)
-
- # close connection to OBiBa's Opal demo server
- opalr::opal.logout(opal_con)
-})
-
-test_that("extract_safe_people.opal excludes admin and administrator accounts", {
- # the real OBiBa demo server doesn't set the `administrate` permission on
- # its `administrator` account, so this can't be exercised against it -
- # simulate a server where the exclusion actually has something to catch
- local_mocked_bindings(
- backend_users = function(x, ..., df = FALSE) {
- list(
- list(principal = "alice", groups = list("auditor")),
- list(principal = "bob_admin", groups = list("admin"))
- )
- },
- backend_sys_perms = function(x, ...) {
- tibble::tibble(
- subject = c("alice", "bob_admin"),
- permission = c("view", "administrate"),
- type = c("user", "user")
- )
- }
- )
-
- # records which users actually got passed into `safe_people()`, without
- # needing `<<-` - environments are mutable by reference
- calls <- new.env()
- calls$safe_people <- character()
-
- local_mocked_bindings(
- `safe_people.rocrate` = function(
- x,
- ...,
- connection,
- user,
- set_author = TRUE,
- set_project = TRUE
- ) {
- calls$safe_people <- c(
- calls$safe_people,
- as.character(unlist(user, use.names = FALSE))
- )
- x
- }
- )
-
- con <- fake_opal_con()
- roc <- extract_safe_people(con)
-
- print(calls$safe_people)
-
- # `administrator` never reaches `safe_people()` because it's excluded
- # upstream, in `filter_safe_people()`, before the Person entity would
- # ever be created
- expect_false(any(tolower(calls$safe_people) %in% c("admin", "administrator")))
- expect_equal(calls$safe_people, "alice")
- expect_s3_class(roc, "rocrate")
-})
-
-test_that("extract_safe_people.opal iterates over all returned subject profiles", {
- # open connection to OBiBa's Opal demo server
- opal_con <- opal_demo_con()
- # terminate connection when done with tests
- withr::defer(opalr::opal.logout(opal_con))
-
- users_raw <- backend_users(opal_con, df = FALSE)
- users_tbl <- dplyr::bind_rows(users_raw)
-
- expect_true(nrow(users_tbl) >= 1)
-
- roc <- extract_safe_people(opal_con)
-
- # validate rocrate structure
- expect_no_error(rocrateR::is_rocrate(roc))
-
- # close connection to OBiBa's Opal demo server
- opalr::opal.logout(opal_con)
-})
-
test_that("extract_safe_people.rocrate copies Person entities", {
src <- rocrateR::rocrate_5s()
@@ -200,7 +85,7 @@ test_that("extract_safe_people.rocrate infers ids from root Dataset author", {
expect_equal(getElement(ents[[1]], "@id"), "#author1")
})
-test_that("extract_safe_people.rocrate errors when no matching Person entities found", {
+test_that("extract_safe_people.rocrate handles missing Person ents. found", {
src <- rocrateR::rocrate_5s()
# ignore warning about not finding People entities
@@ -264,7 +149,7 @@ test_that("flatten_safe_people.rocrate filters by id argument", {
expect_equal(res$person_id, "#p2")
})
-test_that("flatten_safe_people.rocrate returns empty tibble on malformed input", {
+test_that("flatten_safe_people.rocrate handles malformed input", {
bad_obj <- list() # not a rocrate
res <- flatten_safe_people.rocrate(bad_obj)
diff --git a/tests/testthat/test-utils-safe_project.R b/tests/testthat/test-utils-safe_project.R
index a733d2c..e330dd7 100644
--- a/tests/testthat/test-utils-safe_project.R
+++ b/tests/testthat/test-utils-safe_project.R
@@ -21,9 +21,8 @@ test_that("flatten_safe_project dispatches default method", {
})
# -------------------------------------------------------------------------
-# extract_safe_project.rocrate()
+# extract_safe_project.rocrate
# -------------------------------------------------------------------------
-
test_that("extract_safe_project.rocrate errors when no project entities", {
rocrate <- rocrateR::rocrate_5s()
@@ -36,7 +35,7 @@ test_that("extract_safe_project.rocrate errors when no project entities", {
)
})
-test_that("extract_safe_project.rocrate returns rocrate with project entities", {
+test_that("extract_safe_project.rocrate returns rocrate with project ents.", {
# create an RO-Crate with Project entities
rocrate <- rocrateR::rocrate_5s() |>
rocrateR::add_entity(
@@ -181,9 +180,8 @@ test_that("extract_safe_project.rocrate adds linked dataset entities", {
})
# -------------------------------------------------------------------------
-# flatten_safe_project.rocrate()
+# flatten_safe_project.rocrate
# -------------------------------------------------------------------------
-
test_that("flatten_safe_project.rocrate returns tibble", {
# create an RO-Crate with a Project and two Dataset entities
rocrate <- rocrateR::rocrate_5s() |>
@@ -298,22 +296,3 @@ test_that("flatten_safe_project.rocrate returns empty tibble on error", {
expect_s3_class(out, "tbl_df")
})
-
-# -------------------------------------------------------------------------
-# extract_safe_project.opal() (INTEGRATION - demo server)
-# -------------------------------------------------------------------------
-
-test_that("extract_safe_project.opal works with demo Opal server", {
- # Skip if demo server is unreachable
- con <- try(opal_demo_con(), silent = TRUE)
- skip_if(inherits(con, "try-error"), "Opal demo server not available")
-
- rocrate <- extract_safe_project(con)
-
- expect_s3_class(rocrate, "rocrate")
-
- projects <- rocrateR::get_entity(rocrate, type = "Project")
-
- # CNSIM project should exist on demo server
- expect_true(length(projects) >= 1)
-})
diff --git a/tests/testthat/test-utils-safe_setting.R b/tests/testthat/test-utils-safe_setting.R
index 0a06db5..7be09c6 100644
--- a/tests/testthat/test-utils-safe_setting.R
+++ b/tests/testthat/test-utils-safe_setting.R
@@ -42,7 +42,7 @@ test_that("flatten_safe_setting.default returns empty tibble", {
})
# -------------------------------------------------------------------------
-# extract_safe_setting.rocrate()
+# extract_safe_setting.rocrate
# -------------------------------------------------------------------------
test_that("extract_safe_setting.rocrate errors when no matching entities", {
rocrate <- rocrateR::rocrate_5s()
@@ -56,7 +56,7 @@ test_that("extract_safe_setting.rocrate errors when no matching entities", {
)
})
-test_that("extract_safe_setting.rocrate extracts PropertyValue and SoftwareApplication", {
+test_that("extract_safe_setting.rocrate extracts target entities", {
# create an RO-Crate with setting entities
software_ent <- rocrateR::entity(
id = "#software-1",
@@ -220,7 +220,7 @@ test_that("extract_safe_setting.rocrate validates rocrate input", {
})
# -------------------------------------------------------------------------
-# flatten_safe_setting.rocrate()
+# flatten_safe_setting.rocrate
# -------------------------------------------------------------------------
test_that("flatten_safe_setting.rocrate returns tibble with correct columns", {
# create an RO-Crate with setting entities
@@ -339,46 +339,3 @@ test_that("flatten_safe_setting.rocrate returns empty tibble on error", {
expect_s3_class(out, "tbl_df")
expect_equal(nrow(out), 0)
})
-
-# -------------------------------------------------------------------------
-# extract_safe_setting.opal() (unit + integration strategy)
-# -------------------------------------------------------------------------
-test_that("extract_safe_setting.opal calls safe_setting and returns rocrate", {
- # dummy opal-like object (S3 dispatch target)
- opal_con <- structure(list(), class = "opal")
-
- # mock safe_setting to avoid real server dependency
- mock_safe_setting <- function(x, rocrate) {
- setting <- rocrateR::entity(
- id = "#mock-setting",
- type = "PropertyValue",
- name = "mock.option",
- value = "TRUE"
- )
- rocrateR::add_entity(rocrate, setting)
- }
-
- with_mocked_bindings(
- safe_setting = mock_safe_setting,
- {
- out <- extract_safe_setting.opal(opal_con)
- }
- )
-
- expect_s3_class(out, "rocrate")
-
- pv <- .get_entity(out, type = "PropertyValue")
- expect_true(length(pv) >= 1)
-})
-
-# -------------------------------------------------------------------------
-# optional TRUE Opal demo integration (matches your demo server workflow)
-# -------------------------------------------------------------------------
-test_that("extract_safe_setting.opal works with Opal demo server (if available)", {
- con <- try(opal_demo_con(), silent = TRUE)
- skip_if(inherits(con, "try-error"), "Opal demo server not available")
-
- rocrate <- extract_safe_setting(con)
-
- expect_s3_class(rocrate, "rocrate")
-})
diff --git a/vignettes/building-crates.Rmd b/vignettes/building-crates.Rmd
index 83c2df4..1e9485e 100644
--- a/vignettes/building-crates.Rmd
+++ b/vignettes/building-crates.Rmd
@@ -18,7 +18,7 @@ SERVER <- "https://opal-demo.obiba.org"
# The examples need OBiBa's public Opal demo server. If it cannot be reached
# (e.g., when building offline), the code is shown but not run.
-demo_available <- local({
+demo <- local({
old <- options(timeout = 5)
on.exit(options(old))
tryCatch(
@@ -31,7 +31,7 @@ demo_available <- local({
warning = function(w) FALSE
)
})
-knitr::opts_chunk$set(eval = demo_available)
+knitr::opts_chunk$set(eval = demo)
# the DataSHIELD client packages are only needed to generate some activity
ds_clients_available <- all(
@@ -116,7 +116,7 @@ recent activity from the audited user. If you are using your own server and
already have activity, skip this section. Here we log in as `dsuser`, assign
a table and run two functions:
-```{r activity, eval = demo_available && ds_clients_available, results = "hide"}
+```{r activity, eval = demo && ds_clients_available, results = "hide"}
# registers the OpalDriver class in the current session
DSOpal::Opal()
@@ -229,7 +229,7 @@ path_to_rocrate_bag <- crate |>
and its contents explored with:
-```{r unbag, eval = demo_available && requireNamespace("fs", quietly = TRUE)}
+```{r unbag, eval = demo && requireNamespace("fs", quietly = TRUE)}
path_to_rocrate_bag |>
rocrateR::unbag_rocrate(
output = file.path(tmp_path_bag, "ROC"),