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( - "\"RO-Crate\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( + "\"RO-Crate\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"),