diff --git a/DESCRIPTION b/DESCRIPTION index 53b120b..685c60d 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,26 +1,26 @@ Package: proofr Title: Client for the PROOF API -Version: 0.2.0.94 +Version: 0.2.1.91 Authors@R: person("Scott", "Chamberlain", , "sachamber@fredhutch.org", role = c("aut", "cre"), comment = c(ORCID = "0000-0003-1444-9135")) Description: Client for the PROOF API. -URL: http://getwilds.org/proofr/ (website) - https://github.com/getwilds/proofr (devel) +URL: http://getwilds.org/proofr/, https://github.com/getwilds/proofr License: MIT + file LICENSE Encoding: UTF-8 Roxygen: list(markdown = TRUE) -RoxygenNote: 7.2.3 +RoxygenNote: 7.3.2 +Depends: R (>= 4.1.0) Imports: cli, glue, - httr + httr2 Suggests: jsonlite, knitr, rmarkdown, testthat (>= 3.0.0), - webmockr, + webmockr (>= 1.0.0), withr Config/testthat/edition: 3 VignetteBuilder: knitr diff --git a/NAMESPACE b/NAMESPACE index 4e55711..12b374a 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -3,18 +3,18 @@ export(proof_authenticate) export(proof_cancel) export(proof_header) +export(proof_info) export(proof_start) export(proof_status) export(proof_timeout) importFrom(cli,cli_progress_bar) importFrom(cli,cli_progress_update) -importFrom(httr,DELETE) -importFrom(httr,GET) -importFrom(httr,POST) -importFrom(httr,add_headers) -importFrom(httr,content) -importFrom(httr,http_error) -importFrom(httr,http_status) -importFrom(httr,status_code) -importFrom(httr,stop_for_status) -importFrom(httr,timeout) +importFrom(httr2,req_body_json) +importFrom(httr2,req_error) +importFrom(httr2,req_headers) +importFrom(httr2,req_method) +importFrom(httr2,req_perform) +importFrom(httr2,req_timeout) +importFrom(httr2,request) +importFrom(httr2,resp_body_json) +importFrom(httr2,resp_status) diff --git a/R/auth.R b/R/auth.R index ad2046f..e801645 100644 --- a/R/auth.R +++ b/R/auth.R @@ -12,11 +12,12 @@ find_token <- function(token = NULL) { #' Get header for PROOF API calls #' #' @export +#' @param req An `httr2` request. required #' @param token (character) PROOF API token. optional -#' @return A `request` S3 class with the HTTP header that can be passed -#' to `httr::GET()`, `httr::POST()`, etc. -proof_header <- function(token = NULL) { - add_headers(Authorization = paste0("Bearer ", find_token(token))) +#' @return An `httr2_request` S3 class adding an HTTP header for +#' `Authorization` with the value in `token` +proof_header <- function(req, token = NULL) { + req_headers(req, Authorization = paste0("Bearer ", find_token(token))) } #' Authenticate with PROOF API @@ -27,20 +28,21 @@ proof_header <- function(token = NULL) { #' @inheritSection proof_status Timeout #' @return A single token (character) for bearer authentication with #' the PROOF API +#' @details We strongly recommend to not supply `password` as plain text like +#' `proof_authenticate(username = "jane", password = "mypassword")`, but rather +#' pull in your password from an environment variable stored outside of R like +#' `proof_authenticate(username = "jane", password = Sys.getenv("HUTCH_PWD"))` proof_authenticate <- function(username, password) { assert(username, "character") assert(password, "character") - response <- POST(make_url("authenticate"), - body = list( + response <- request(make_url("authenticate")) |> + req_body_json(list( username = username, password = password - ), - encode = "json", - timeout(proofr_env$timeout_sec) - ) - stop_for_status(response) - parsed <- content(response, as = "parsed") - token <- parsed$token - token + )) |> + req_timeout(proofr_env$timeout_sec) |> + req_perform() |> + resp_body_json() + response$token } diff --git a/R/cancel.R b/R/cancel.R index 5bad958..41c7202 100644 --- a/R/cancel.R +++ b/R/cancel.R @@ -2,18 +2,17 @@ #' #' @export #' @inheritParams proof_start -#' @references #' @inheritSection proof_status Timeout #' @return On success, a list with a single field: #' - `message` (character) #' #' If run when there's no Cromwell server running, an HTTP error proof_cancel <- function(token = NULL) { - response <- DELETE( - make_url("cromwell-server"), - proof_header(token), - timeout(proofr_env$timeout_sec) - ) - stop_for_message(response) - content(response, as = "parsed") + request(make_url("cromwell-server")) |> + req_method("DELETE") |> + proof_header(token) |> + req_timeout(proofr_env$timeout_sec) |> + req_error(body = error_body) |> + req_perform() |> + resp_body_json() } diff --git a/R/http.R b/R/http.R index c431700..bdf5497 100644 --- a/R/http.R +++ b/R/http.R @@ -1,13 +1,6 @@ -stop_for_message <- function(response) { - if (http_error(response)) { - parsed <- tryCatch(content(response), error = function(e) e) - if (inherits(parsed, "error")) stop_for_status(response) - if (!is.list(parsed)) stop_for_status(response) - msg <- glue::glue( - "{http_status(response)$reason}", - " (HTTP {status_code(response)})", - " {parsed$message}" - ) - stop(msg, call. = FALSE) - } +error_body <- function(response) { + parsed <- resp_body_json(response) + glue::glue( + "Additional context: {parsed$message}" + ) } diff --git a/R/info.R b/R/info.R new file mode 100644 index 0000000..cd0bd33 --- /dev/null +++ b/R/info.R @@ -0,0 +1,16 @@ +#' Get information about PROOF server +#' +#' @export +#' @return A list with fields: +#' - `branch` (character): git branch of API +#' - `commit_sha` (character): SHA of the git commit of the API +#' - `short_commit_sha` (character): the first eight characters of `commit_sha` +#' - `commit_message` (character): commit message of API's most recent commit +#' - `tag` (character): tag of most recent commit/release version +proof_info <- function() { + request(make_url("info")) |> + req_timeout(proofr_env$timeout_sec) |> + req_error(body = error_body) |> + req_perform() |> + resp_body_json() +} diff --git a/R/proofr-package.R b/R/proofr-package.R index 801d48c..8f80a62 100644 --- a/R/proofr-package.R +++ b/R/proofr-package.R @@ -1,9 +1,14 @@ #' @keywords internal +#' @section Base URL for PROOF API: +#' The base URL for the PROOF API can be changed by setting the environment +#' variable `PROOF_API_BASE_URL`. It can be set for an R session or for +#' function by function use as we check that env var in each function call +#' to the API "_PACKAGE" ## usethis namespace: start -#' @importFrom httr GET POST DELETE add_headers content -#' stop_for_status timeout http_status status_code -#' http_error +#' @importFrom httr2 request req_perform req_headers +#' req_timeout req_body_json req_method req_error +#' resp_status resp_body_json ## usethis namespace: end NULL diff --git a/R/start.R b/R/start.R index f105cc7..27c6d0e 100644 --- a/R/start.R +++ b/R/start.R @@ -10,11 +10,9 @@ #' here as a string. Either pass it using [Sys.getenv()] or save your #' token as an env var and then passing nothing to this param and we'll find #' it -#' @references #' @details Does not return PROOF/Cromwell server URL, for that you have to #' periodically call [proof_status()], or wait for the email from the -#' PROOF API. See the link to proof-api for more details about the -#' slurm account. +#' PROOF API #' @inheritSection proof_status Timeout #' @section Cromwell Server uptime: #' The Cromwell server started by this function will run for 7 days @@ -26,13 +24,11 @@ #' - `job_id` (character) - the job ID #' - `info` (character) - message proof_start <- function(slurm_account = NULL, token = NULL) { - response <- POST( - make_url("cromwell-server"), - proof_header(token), - body = list(slurm_account = slurm_account), - encode = "json", - timeout(proofr_env$timeout_sec) - ) - stop_for_message(response) - content(response, as = "parsed") + request(make_url("cromwell-server")) |> + req_body_json(list(slurm_account = slurm_account)) |> + proof_header(token) |> + req_timeout(proofr_env$timeout_sec) |> + req_error(body = error_body) |> + req_perform() |> + resp_body_json() } diff --git a/R/status.R b/R/status.R index 1e7761b..a484c17 100644 --- a/R/status.R +++ b/R/status.R @@ -6,7 +6,6 @@ #' @param wait (logical) if `TRUE` wait for the server to be ready to #' interact with. if `FALSE` return immediately, then you'll want to call #' this function again until you get the server URL -#' @references #' @section Timeout: #' If the PROOF API is unavailable, this function will timeout after #' 5 seconds. Contact the package maintainer if you get a timeout error. @@ -25,13 +24,12 @@ proof_status <- function(wait = FALSE, token = NULL) { } fetch_status <- function(token = NULL) { - response <- GET( - make_url("cromwell-server"), - proof_header(token), - timeout(proofr_env$timeout_sec) - ) - stop_for_message(response) - content(response, as = "parsed") + request(make_url("cromwell-server")) |> + proof_header(token) |> + req_timeout(proofr_env$timeout_sec) |> + req_error(body = error_body) |> + req_perform() |> + resp_body_json() } fetch_wait <- function(token) { diff --git a/R/timeout.R b/R/timeout.R index f898e9b..6bb7941 100644 --- a/R/timeout.R +++ b/R/timeout.R @@ -2,10 +2,10 @@ #' #' @export #' @param sec (integer/numeric) number of seconds after which -#' requests will timeout. default: 5 sec (5000 ms) +#' requests will timeout. default: 10 sec (10000 ms) #' @references #' @return nothing, side effect of setting the timeout for requests -proof_timeout <- function(sec = 5) { +proof_timeout <- function(sec = 10) { assert(sec, c("integer", "numeric")) proofr_env$timeout_sec <- sec } diff --git a/R/utils.R b/R/utils.R index da08a5f..890df18 100644 --- a/R/utils.R +++ b/R/utils.R @@ -1,7 +1,8 @@ - make_url <- function(...) { - proof_base <- Sys.getenv("PROOF_API_BASE_URL", - "https://proof-api.fredhutch.org") + proof_base <- Sys.getenv( + "PROOF_API_BASE_URL", + "https://proof-api.fredhutch.org" + ) file.path(proof_base, ...) } diff --git a/README.Rmd b/README.Rmd index 60ef240..2b2a7d9 100644 --- a/README.Rmd +++ b/README.Rmd @@ -41,6 +41,7 @@ To get started with `proofr`, see the [Getting Started vignette](https://getwild ## Notes - There are no plans to submit this package to CRAN. Therefore, you should not depend on this package in any packages you have on CRAN. +- Base URL: The base URL for the PROOF API can be changed by setting the environment variable `PROOF_API_BASE_URL`. It can be set for an R session or for function by function use as we check that env var in each function call to the API. ## Bugs? Features? diff --git a/README.md b/README.md index 63662b4..a65bcd3 100644 --- a/README.md +++ b/README.md @@ -33,6 +33,7 @@ To get started with `proofr`, see the [Getting Started vignette](https://getwild ## Notes - There are no plans to submit this package to CRAN. Therefore, you should not depend on this package in any packages you have on CRAN. +- Base URL: The base URL for the PROOF API can be changed by setting the environment variable `PROOF_API_BASE_URL`. It can be set for an R session or for function by function use as we check that env var in each function call to the API. ## Bugs? Features? diff --git a/man/proof_authenticate.Rd b/man/proof_authenticate.Rd index 1203fa2..c1705ef 100644 --- a/man/proof_authenticate.Rd +++ b/man/proof_authenticate.Rd @@ -18,6 +18,12 @@ the PROOF API \description{ Authenticate with PROOF API } +\details{ +We strongly recommend to not supply \code{password} as plain text like +\code{proof_authenticate(username = "jane", password = "mypassword")}, but rather +pull in your password from an environment variable stored outside of R like +\code{proof_authenticate(username = "jane", password = Sys.getenv("HUTCH_PWD"))} +} \section{Timeout}{ If the PROOF API is unavailable, this function will timeout after diff --git a/man/proof_cancel.Rd b/man/proof_cancel.Rd index ba4eec2..3b53b81 100644 --- a/man/proof_cancel.Rd +++ b/man/proof_cancel.Rd @@ -31,6 +31,3 @@ If the PROOF API is unavailable, this function will timeout after See \code{\link[=proof_timeout]{proof_timeout()}}. } -\references{ -\url{https://github.com/FredHutch/proof-api#delete-cromwell-server} -} diff --git a/man/proof_header.Rd b/man/proof_header.Rd index 13c374a..f5a8ad9 100644 --- a/man/proof_header.Rd +++ b/man/proof_header.Rd @@ -4,14 +4,16 @@ \alias{proof_header} \title{Get header for PROOF API calls} \usage{ -proof_header(token = NULL) +proof_header(req, token = NULL) } \arguments{ +\item{req}{An \code{httr2} request. required} + \item{token}{(character) PROOF API token. optional} } \value{ -A \code{request} S3 class with the HTTP header that can be passed -to \code{httr::GET()}, \code{httr::POST()}, etc. +An \code{httr2_request} S3 class adding an HTTP header for +\code{Authorization} with the value in \code{token} } \description{ Get header for PROOF API calls diff --git a/man/proof_info.Rd b/man/proof_info.Rd new file mode 100644 index 0000000..1fafdb1 --- /dev/null +++ b/man/proof_info.Rd @@ -0,0 +1,21 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/info.R +\name{proof_info} +\alias{proof_info} +\title{Get information about PROOF server} +\usage{ +proof_info() +} +\value{ +A list with fields: +\itemize{ +\item \code{branch} (character): git branch of API +\item \code{commit_sha} (character): SHA of the git commit of the API +\item \code{short_commit_sha} (character): the first eight characters of \code{commit_sha} +\item \code{commit_message} (character): commit message of API's most recent commit +\item \code{tag} (character): tag of most recent commit/release version +} +} +\description{ +Get information about PROOF server +} diff --git a/man/proof_start.Rd b/man/proof_start.Rd index d531a2d..e6c77f8 100644 --- a/man/proof_start.Rd +++ b/man/proof_start.Rd @@ -31,8 +31,7 @@ Start PROOF Cromwell server \details{ Does not return PROOF/Cromwell server URL, for that you have to periodically call \code{\link[=proof_status]{proof_status()}}, or wait for the email from the -PROOF API. See the link to proof-api for more details about the -slurm account. +PROOF API } \section{Cromwell Server uptime}{ @@ -50,6 +49,3 @@ If the PROOF API is unavailable, this function will timeout after See \code{\link[=proof_timeout]{proof_timeout()}}. } -\references{ -\url{https://github.com/FredHutch/proof-api/#post-cromwell-server} -} diff --git a/man/proof_status.Rd b/man/proof_status.Rd index 6c08371..283455d 100644 --- a/man/proof_status.Rd +++ b/man/proof_status.Rd @@ -40,6 +40,3 @@ If the PROOF API is unavailable, this function will timeout after See \code{\link[=proof_timeout]{proof_timeout()}}. } -\references{ -\url{https://github.com/FredHutch/proof-api#get-cromwell-server} -} diff --git a/man/proof_timeout.Rd b/man/proof_timeout.Rd index 5dd22ab..67adb7a 100644 --- a/man/proof_timeout.Rd +++ b/man/proof_timeout.Rd @@ -4,11 +4,11 @@ \alias{proof_timeout} \title{Set the timeout for all requests to the PROOF API} \usage{ -proof_timeout(sec = 5) +proof_timeout(sec = 10) } \arguments{ \item{sec}{(integer/numeric) number of seconds after which -requests will timeout. default: 5 sec (5000 ms)} +requests will timeout. default: 10 sec (10000 ms)} } \value{ nothing, side effect of setting the timeout for requests diff --git a/man/proofr-package.Rd b/man/proofr-package.Rd index 7df68ec..92f4e28 100644 --- a/man/proofr-package.Rd +++ b/man/proofr-package.Rd @@ -8,10 +8,19 @@ \description{ Client for the PROOF API. } +\section{Base URL for PROOF API}{ + +The base URL for the PROOF API can be changed by setting the environment +variable \code{PROOF_API_BASE_URL}. It can be set for an R session or for +function by function use as we check that env var in each function call +to the API +} + \seealso{ Useful links: \itemize{ - \item \url{http://getwilds.org/proofr/ (website) https://github.com/getwilds/proofr (devel)} + \item \url{http://getwilds.org/proofr/} + \item \url{https://github.com/getwilds/proofr} } } diff --git a/tests/testthat/helper-stubs.R b/tests/testthat/helper-stubs.R index e5162ca..b7ad9f9 100644 --- a/tests/testthat/helper-stubs.R +++ b/tests/testthat/helper-stubs.R @@ -57,3 +57,11 @@ response_authenticate_success <- list( job_id = NULL, token_creation_date = NULL ) + +response_info_success <- list( + branch = "main", + commit_sha = "c4b85200632c2f9bd5e8173179208c3b32c7db7a", + short_commit_sha = "c4b85200", + commit_message = "two-eye lamb, as a so", + tag = "v.0.1.0" +) diff --git a/tests/testthat/test-proof_cancel.R b/tests/testthat/test-proof_cancel.R index 9f864b5..b6f4d58 100644 --- a/tests/testthat/test-proof_cancel.R +++ b/tests/testthat/test-proof_cancel.R @@ -1,12 +1,11 @@ test_that("proof_cancel - success", { stub_registry_clear() - stub_request("delete", make_url("cromwell-server")) %>% + stub_request("delete", make_url("cromwell-server")) |> to_return( body = jsonlite::toJSON(response_cancel_success, auto_unbox = TRUE), status = 200L, headers = list("Content-type" = "application/json") ) - stub_registry() enable(quiet = TRUE) @@ -24,7 +23,7 @@ test_that("proof_cancel - success", { }) test_that("proof_cancel - not running, can not cancel", { - stub_request("delete", make_url("cromwell-server")) %>% + stub_request("delete", make_url("cromwell-server")) |> to_return( body = jsonlite::toJSON(response_cancel_conflict, auto_unbox = TRUE), status = 409L, @@ -34,7 +33,8 @@ test_that("proof_cancel - not running, can not cancel", { enable(quiet = TRUE) withr::with_envvar(c("PROOF_TOKEN" = "notarealtoken"), { - expect_error(proof_cancel(), "Job is not running, nothing to delete") + expect_error(proof_cancel(), "HTTP 409 Conflict") + expect_error(proof_cancel(), "Additional context") }) diff --git a/tests/testthat/test-proof_header.R b/tests/testthat/test-proof_header.R index 26f812c..4a8403c 100644 --- a/tests/testthat/test-proof_header.R +++ b/tests/testthat/test-proof_header.R @@ -2,13 +2,16 @@ test_that("proof_header", { # errors if no env var set and no string supplied - expect_error(proof_header(), "token not found") + expect_error(proof_header(request("")), "token not found") # returns token if given - expect_match(proof_header("adf")$headers[[1]], "adf") + expect_match(proof_header(request(""), "adf")$headers[[1]], "adf") # If PROOF_TOKEN env var set, fxn can find it withr::with_envvar(c("PROOF_TOKEN" = "notarealtoken"), { - expect_match(proof_header()$headers[[1]], "notarealtoken") + expect_match( + proof_header(request(""))$headers[[1]], + "notarealtoken" + ) }) }) diff --git a/tests/testthat/test-proof_info.R b/tests/testthat/test-proof_info.R new file mode 100644 index 0000000..e7819cd --- /dev/null +++ b/tests/testthat/test-proof_info.R @@ -0,0 +1,25 @@ +test_that("proof_info - success", { + stub_request("get", make_url("info")) %>% + to_return( + body = jsonlite::toJSON(response_info_success, auto_unbox = TRUE), + status = 200L, + headers = list("Content-type" = "application/json") + ) + + enable(quiet = TRUE) + + withr::with_envvar(c("PROOF_TOKEN" = "notarealtoken"), { + info_res <- proof_info() + }) + + expect_type(info_res, "list") + + # also works w/o token as it's not needed for this fxn + info_res_wo_token <- proof_info() + + expect_type(info_res_wo_token, "list") + + + stub_registry_clear() + disable(quiet = TRUE) +}) diff --git a/tests/testthat/test-proof_start.R b/tests/testthat/test-proof_start.R index 66e4e45..2830ec7 100644 --- a/tests/testthat/test-proof_start.R +++ b/tests/testthat/test-proof_start.R @@ -1,5 +1,5 @@ test_that("proof_start - success", { - stub_request("post", make_url("cromwell-server")) %>% + stub_request("post", make_url("cromwell-server")) |> to_return( body = jsonlite::toJSON(response_start_success, auto_unbox = TRUE), status = 200L, @@ -22,7 +22,7 @@ test_that("proof_start - success", { }) test_that("proof_start - already running", { - stub_request("post", make_url("cromwell-server")) %>% + stub_request("post", make_url("cromwell-server")) |> to_return( body = jsonlite::toJSON(response_start_conflict, auto_unbox = TRUE), status = 409L, @@ -32,7 +32,8 @@ test_that("proof_start - already running", { enable(quiet = TRUE) withr::with_envvar(c("PROOF_TOKEN" = "notarealtoken"), { - expect_error(proof_start(), "Job is already running") + expect_error(proof_start(), "409") + expect_error(proof_cancel(), "Job is already running") }) diff --git a/tests/testthat/test-proof_status.R b/tests/testthat/test-proof_status.R index e26429e..3211ba7 100644 --- a/tests/testthat/test-proof_status.R +++ b/tests/testthat/test-proof_status.R @@ -1,5 +1,5 @@ test_that("proof_status - server IS running", { - stub_request("get", make_url("cromwell-server")) %>% + stub_request("get", make_url("cromwell-server")) |> to_return( body = jsonlite::toJSON( response_status_running, @@ -30,7 +30,7 @@ test_that("proof_status - server IS running", { }) test_that("proof_status - server IS NOT running", { - stub_request("get", make_url("cromwell-server")) %>% + stub_request("get", make_url("cromwell-server")) |> to_return( body = jsonlite::toJSON( response_status_not_running, diff --git a/vignettes/proofr.Rmd b/vignettes/proofr.Rmd index f295c2f..95a590b 100644 --- a/vignettes/proofr.Rmd +++ b/vignettes/proofr.Rmd @@ -12,17 +12,18 @@ vignette: > Load `proofr` -```r +``` r library(proofr) ``` ## Authenticate with the PROOF API -Run the function `proof_authenticate()`, which calls the PROOF API with your username and password, and returns an API token (an alphanumeric string). +Run the function `proof_authenticate()`, which calls the PROOF API with your HutchNet username and password, and returns an API token (an alphanumeric string). +We strongly recommend to not supply `password` to `proof_authenticate` as plain text like, and instead pull in your password from an environment variable stored outside of R. For a description of different options for where to store your HutchNet password see the [R Startup chapter](https://rstats.wtf/r-startup) in the book _What They Forgot to Teach You About R_. -```r -my_proof_token <- proof_authenticate("username", "password") +``` r +my_proof_token <- proof_authenticate(username = "username", password = Sys.getenv("HUTCHNET_PWD")) my_proof_token #> xyGKibGctQ92rmMKKb39q43XgPxGCmrWoX7NZtamTjDP ``` @@ -32,16 +33,18 @@ my_proof_token Alternatively, save your API token directly as an environment variable named `PROOF_TOKEN` so that it can be used by other `proofr` functions without exposing your token in your code. To do so, run the following: -```r +``` r Sys.setenv("PROOF_TOKEN" = proof_authenticate("username", "password")) ``` +Instead of just setting your token for the current R session, you can set a token that can be used across sessions by putting your token in a file that is read in by R when it starts up. Create a `~/.Renviron` file (if it doesn't exist already) that contains `PROOF_TOKEN=your-token-here` and it will be available in your R session. Run `chmod 0400 ~/.Renviron` to make sure only you can see its contents. Make sure to restart your R session after any changes to this file so the changes are picked up. + ## Start a PROOF Server Start a PROOF server using the `proof_start()` function: -```r +``` r proof_start() ``` Note: `proofr` assumes you only have one server running; if you've started a server using the app, you'll need to stop that server before starting one in R via `proofr`. @@ -49,7 +52,7 @@ Note: `proofr` assumes you only have one server running; if you've started a ser Get metadata about the PROOF server you have started, including the URL of the API, using `wait=TRUE` so that it doesn't return data until the server is fully ready to use. -```r +``` r metadata <- proof_status(wait = TRUE) cromwell_url <- metadata$cromwellUrl cromwell_url @@ -60,10 +63,10 @@ cromwell_url Load `rcromwell` -```r +``` r if (!requireNamespace("rcromwell", quietly=TRUE)) { install.packages("pak") - pak::pak("rcromwell") + pak::pak("getwilds/rcromwell") } library(rcromwell) library(httr) @@ -74,21 +77,21 @@ There are two options for setting the URL in `rcromwell`. The first option is to set the Cromwell server URL to be recognized by `rcromwell` with `cromwell_config` -```r +``` r cromwell_config(cromwell_url) ``` The other option is to pass the url to each function, for example: -```r +``` r cromwell_jobs(url = cromwell_url) ``` In addition to setting the Cromwell URL, your PROOF API token is also required for HTTP requests to your server. After getting your PROOF token you can set it as the env var `PROOF_TOKEN`, or pass it to the `rcromwell` functions, for example: -```r +``` r cromwell_jobs(url = cromwell_url, token = my_proof_token) ``` @@ -98,7 +101,7 @@ cromwell_jobs(url = cromwell_url, token = my_proof_token) As an example, `cromwell_version()` checks the version of your Cromwell server -```r +``` r cromwell_version() #> $cromwell #> [1] "84" diff --git a/vignettes/proofr.Rmd.og b/vignettes/proofr.Rmd.og index bb6de78..0d5e5d9 100644 --- a/vignettes/proofr.Rmd.og +++ b/vignettes/proofr.Rmd.og @@ -23,10 +23,12 @@ library(proofr) ## Authenticate with the PROOF API -Run the function `proof_authenticate()`, which calls the PROOF API with your username and password, and returns an API token (an alphanumeric string). +Run the function `proof_authenticate()`, which calls the PROOF API with your HutchNet username and password, and returns an API token (an alphanumeric string). + +We strongly recommend to not supply `password` to `proof_authenticate` as plain text like, and instead pull in your password from an environment variable stored outside of R. For a description of different options for where to store your HutchNet password see the [R Startup chapter](https://rstats.wtf/r-startup) in the book _What They Forgot to Teach You About R_. ```{r auth} -my_proof_token <- proof_authenticate("username", "password") +my_proof_token <- proof_authenticate(username = "username", password = Sys.getenv("HUTCHNET_PWD")) my_proof_token #> xyGKibGctQ92rmMKKb39q43XgPxGCmrWoX7NZtamTjDP ``` @@ -39,6 +41,8 @@ Alternatively, save your API token directly as an environment variable named `PR Sys.setenv("PROOF_TOKEN" = proof_authenticate("username", "password")) ``` +Instead of just setting your token for the current R session, you can set a token that can be used across sessions by putting your token in a file that is read in by R when it starts up. Create a `~/.Renviron` file (if it doesn't exist already) that contains `PROOF_TOKEN=your-token-here` and it will be available in your R session. Run `chmod 0400 ~/.Renviron` to make sure only you can see its contents. Make sure to restart your R session after any changes to this file so the changes are picked up. + ## Start a PROOF Server Start a PROOF server using the `proof_start()` function: @@ -63,7 +67,7 @@ Load `rcromwell` ```{r setup-rcromwell} if (!requireNamespace("rcromwell", quietly=TRUE)) { install.packages("pak") - pak::pak("rcromwell") + pak::pak("getwilds/rcromwell") } library(rcromwell) library(httr)