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..3f85636 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,7 +13,9 @@ 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) @@ -27,18 +30,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 +53,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 +108,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..9309317 100644 --- a/NEWS.md +++ b/NEWS.md @@ -1,3 +1,37 @@ +# 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. + +## 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. + +## 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. + # 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..f5bb185 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") } @@ -58,32 +66,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..20f0b96 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, ...) @@ -76,38 +98,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..079a8e8 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 @@ -57,9 +54,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." ) } @@ -80,7 +78,7 @@ report.list <- function( max_line_length = 200 ) { # local bindings - asset <- id <- name <- permission <- project <- server <- user <- NULL + asset <- name <- permission <- project <- server <- user <- NULL # validate that all the objects in the list, `x`, are valid RO-Crates sapply(x, rocrateR::is_rocrate) @@ -118,8 +116,7 @@ report.list <- function( ## 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) + safe_project_data_all <- safe_project_all # if data permissions were found, then combine with project-data details and # generate new overview table @@ -177,11 +174,6 @@ report.list <- function( 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") @@ -207,10 +199,11 @@ report.list <- function( # extract current RO-Crate rocrate <- x[i][[1]] # check if the input object has a `path` attribute - if (!is.null(attr(rocrate, "path"))) { + roc_path <- get_crate_context(rocrate, "path") + if (!is.null(roc_path)) { # check if any of the entities with `@type = 'File'` have empty `content` rocrate <- rocrate |> - load_content(roc_path = attr(rocrate, "path")) + load_content(roc_path = roc_path) } report_contents <- .markdown_report_rocrate( @@ -319,9 +312,8 @@ report.rocrate <- function( 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 + asset <- asset_id <- fx <- encodingFormat <- name <- permission <- NULL + perm_id <- project <- timestamp <- person_id <- user <- NULL # validate RO-Crate ---- rocrateR::is_rocrate(x) @@ -349,10 +341,11 @@ report.rocrate <- function( } # check if the input object has a `path` attribute - if (!is.null(attr(x, "path"))) { + 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 = attr(x, "path")) + load_content(roc_path = roc_path) } # pre-processing ---- @@ -475,10 +468,7 @@ report.rocrate <- function( # 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) + dplyr::left_join(safe_project_tbl, by = c("asset_id", "asset")) } else { overview_tbl <- flatten_safe_people(safe_people_rocrate) |> purrr::pmap(function(person_id, name, ...) { @@ -542,11 +532,6 @@ report.rocrate <- function( 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") @@ -640,7 +625,6 @@ report.rocrate <- function( 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 @@ -672,7 +656,7 @@ report.rocrate <- function( diag_height ) { # local bindings - fx <- name <- permission <- project <- asset <- NULL + fx <- permission <- NULL ## initialise `vars` and `labelvar` vars <- c("project", "asset") @@ -728,35 +712,13 @@ report.rocrate <- function( 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( @@ -765,11 +727,7 @@ report.rocrate <- function( ) } - # # 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)) + list(diag_lst = diagram_lst, diag_path = diagram_filepath) } #' Create tidy version of the overview table @@ -844,11 +802,9 @@ report.rocrate <- function( } } - tidy_overview_tbl <- tidy_overview_tbl |> + tidy_overview_tbl |> dplyr::select(dplyr::all_of(varslab)) |> dplyr::distinct() - - return(tidy_overview_tbl) } @@ -868,7 +824,7 @@ report.rocrate <- function( )) 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) + ## init. markdown header (see https://rmarkdown.rstudio.com/lesson-9.html) paste0( "---\n", paste0("title: ", title), @@ -895,9 +851,9 @@ report.rocrate <- function( " - \\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')), + " - \\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 ", @@ -926,13 +882,13 @@ report.rocrate <- function( ), "## 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]{", + "\\includegraphics[height = 0.75\\textheight, keepaspectratio, ", + "width = 0.9\\textwidth]{", diagram_filepath, "}", "\\caption{RO-Crate Overview}\n", @@ -1043,7 +999,7 @@ report.rocrate <- function( ) } - return(report_contents) + report_contents } #' Embed RO-Crate in Markdown report @@ -1084,7 +1040,7 @@ report.rocrate <- function( substr(x, nchar(x) - 10, nchar(x)) )) } - return(x) + x }) report_contents <- c( report_contents, 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..57903cb 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,6 +115,12 @@ 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 @@ -128,7 +128,7 @@ safe_data.opal <- function( # ---- tables ---- if ("tables" %in% include) { - tbl_assets <- get_project_assets(x, project, "tables") + tbl_assets <- project_context_assets(context, "tables") if (!is.null(tbl_assets)) { if (!is.null(tables)) { tbl_assets <- dplyr::filter(tbl_assets, name %in% tables) @@ -139,7 +139,7 @@ safe_data.opal <- function( # ---- 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) @@ -203,17 +203,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 +223,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..70b417d 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 + 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) @@ -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..dc261aa 100644 --- a/R/utils-opal.R +++ b/R/utils-opal.R @@ -101,27 +101,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) ) } @@ -156,14 +162,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 +191,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 +212,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 +364,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 +437,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 +450,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 +465,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 +483,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..ef54bd4 --- /dev/null +++ b/R/utils-project-context.R @@ -0,0 +1,128 @@ +#' 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) +} 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/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/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..a2a47b6 --- /dev/null +++ b/tests/testthat/test-backend-opal.R @@ -0,0 +1,163 @@ +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) +}) 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..069b493 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", { @@ -292,7 +289,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 +335,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 +374,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, 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..7322c89 --- /dev/null +++ b/tests/testthat/test-shared-project-context.R @@ -0,0 +1,197 @@ +# 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_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") +}) 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..1883ceb 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,336 @@ 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) + ) +}) diff --git a/tests/testthat/test-utils-project-context.R b/tests/testthat/test-utils-project-context.R new file mode 100644 index 0000000..a4078cd --- /dev/null +++ b/tests/testthat/test-utils-project-context.R @@ -0,0 +1,209 @@ +# 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") +}) 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"),