Add support for _server.yml

Author: thomasp85

DESCRIPTION

@@ -23,7 +23,8 @@ Imports:
     roxygen2,
     stringi,
     svglite,
-    webutils
+    webutils,
+    yaml
 Remotes:
     thomasp85/fiery,
     thomasp85/reqres,
@@ -34,7 +35,6 @@ Suggests:
     htmlwidgets,
     nanoparquet,
     quarto,
-    readr,
-    yaml
+    readr
 VignetteBuilder: quarto
 URL: https://laughing-spoon-ywk3ewq.pages.github.io/

NAMESPACE

@@ -72,6 +72,7 @@ export(api_statics)
 export(api_stop)
 export(api_trace)
 export(api_trace_header)
+export(create_server_yml)
 export(device_formatter)
 export(format_bmp)
 export(format_cat)

R/Plumber.R

@@ -88,7 +88,7 @@ Plumber <- R6Class(
       if (!is.null(doc_type)) {
         private$DOC_TYPE <- arg_match0(
           doc_type,
-          c("rapidoc", "redoc", "swagger")
+          c("rapidoc", "redoc", "swagger", "")
         )
       }
       check_string(doc_path)
@@ -142,7 +142,7 @@ Plumber <- R6Class(
       ...,
       silent = FALSE
     ) {
-      if (length(private$OPENAPI) != 0 && !is.null(private$DOC_TYPE)) {
+      if (length(private$OPENAPI) != 0 && !is.null(private$DOC_TYPE) && private$DOC_TYPE != "") {
         openapi_file <- tempfile(fileext = ".json")
         write_json(private$OPENAPI, openapi_file, auto_unbox = TRUE)
         api_route <- openapi_route(

R/api.R

@@ -5,7 +5,9 @@
 #'
 #' @param ... plumber files or directories containing plumber files to be parsed
 #' in the given order. The order of parsing determines the final order of the
-#' routes in the stack
+#' routes in the stack. If `...` contains a `_server.yml` file then all other
+#' files in `...` will be ignored and the `_server.yml` file will be used as the
+#' basis for the API
 #' @param host A string that is a valid IPv4 address that is owned by this
 #' server
 #' @param port A number or integer that indicates the server port that should be
@@ -61,19 +63,59 @@ api <- function(
   compression_limit = get_opts("compressionLimit", 1e3),
   env = caller_env()
 ) {
-  api <- Plumber$new(
-    host = host,
-    port = port,
-    doc_type = doc_type,
-    doc_path = doc_path,
-    reject_missing_methods = reject_missing_methods,
-    ignore_trailing_slash = ignore_trailing_slash,
-    max_request_size = max_request_size,
-    shared_secret = shared_secret,
-    compression_limit = compression_limit,
-    env = env
-  )
-  api_parse(api, ...)
+  locations <- dots_to_plumber_files(...)
+  if (isTRUE(is_plumber2_server_yml(locations))) {
+    server_yml <- yaml::read_yaml(locations)
+    if (!is.null(server_yml$constructor)) {
+      api <- source(
+        fs::path(
+          fs::path_dir(locations),
+          server_yml$constructor
+        ),
+        verbose = FALSE
+      )
+      if (!is_plumber_api(api)) {
+        cli::cli_abort(
+          "The constructor file in {.file {locations}} did not produce a plumber2 API"
+        )
+      }
+    } else {
+      api <- Plumber$new(
+        host = server_yml$options$host %||% host,
+        port = server_yml$options$port %||% port,
+        doc_type = server_yml$options$docType %||% doc_type,
+        doc_path = server_yml$options$docPath %||% doc_path,
+        reject_missing_methods = server_yml$options$methodNotAllowed %||%
+          reject_missing_methods,
+        ignore_trailing_slash = server_yml$options$ignoreTrailingSlash %||%
+          ignore_trailing_slash,
+        max_request_size = server_yml$options$maxRequestSize %||%
+          max_request_size,
+        shared_secret = shared_secret,
+        compression_limit = server_yml$options$compressionLimit %||%
+          compression_limit,
+        env = env
+      )
+    }
+    locations <- fs::path(
+      fs::path_dir(locations),
+      server_yml$routes
+    )
+  } else {
+    api <- Plumber$new(
+      host = host,
+      port = port,
+      doc_type = doc_type,
+      doc_path = doc_path,
+      reject_missing_methods = reject_missing_methods,
+      ignore_trailing_slash = ignore_trailing_slash,
+      max_request_size = max_request_size,
+      shared_secret = shared_secret,
+      compression_limit = compression_limit,
+      env = env
+    )
+  }
+  api_parse(api, locations)
 }
 #' @rdname api
 #' @param x An object to test for whether it is a plumber api
@@ -85,14 +127,55 @@ is_plumber_api <- function(x) inherits(x, "Plumber")
 #' @param api A plumber2 api object to parse files into
 #' @export
 api_parse <- function(api, ...) {
-  locations <- list2(...)
-  lapply(locations, function(loc) {
+  locations <- dots_to_plumber_files(..., prefer_yml = FALSE)
+  for (loc in locations) {
+    api$parse_file(file)
+  }
+  api
+}
+
+dots_to_plumber_files <- function(..., prefer_yml = TRUE, call = caller_env()) {
+  locations <- unlist(lapply(list2(...), function(loc) {
     if (fs::is_dir(loc)) {
-      loc <- fs::dir_ls(loc)
+      loc <- fs::dir_ls(loc, all = TRUE, recurse = TRUE)
+      server_yml <- is_plumber2_server_yml(loc)
+      if (prefer_yml && any(server_yml)) {
+        loc <- loc[server_yml]
+      } else {
+        loc <- loc[fs::path_ext(loc) %in% c("R", "r")]
+      }
     }
-    for (file in loc) {
-      api$parse_file(file)
+    loc
+  }))
+  if (length(locations) == 0) return(character())
+  if (!all(fs::file_exists(locations))) {
+    cli::cli_abort("{.arg ...} must point to existing files", call = call)
+  }
+  server_yml <- is_plumber2_server_yml(locations)
+  if (prefer_yml && any(server_yml)) {
+    if (sum(server_yml) != 1) {
+      cli::cli_abort(
+        "You can at most use one {.file _server.yml} file to specify your API",
+        call = call
+      )
     }
-  })
-  api
+    if (length(locations) != 1) {
+      cli::cli_warn(
+        "{.file _server.yml} found. Ignoring all other files provided in {.arg ...}",
+        call = call
+      )
+    }
+    locations[server_yml]
+  } else {
+    if (any(server_yml)) {
+      cli::cli_warn(
+        "Ignoring {.file _server.yml} files in {.arg ...}",
+        call = call
+      )
+    }
+    locations[!server_yml]
+  }
 }
+
+# For use by connect etc
+create_server <- api

R/create_server_yml.R

@@ -0,0 +1,70 @@
+#' Create a _server.yml file to describe your API
+#'
+#' While you can manually create a plumber2 API by calling [api()], you will
+#' often need to deploy the api somewhere else. To facilitate this you can
+#' create a `_server.yml` that encapsulates all of your settings and plumber
+#' files. If you call [api()] with a path to such a file the API will be
+#' constructed according to its content.
+#'
+#' @param ... path to files and/or directories that contain annotated plumber
+#' files to be used by your API
+#' @param path The folder to place the generated `_server.yml` file in
+#' @param constructor The path to a file that creates a plumber2 API object. Can
+#' be omitted in which case an API object will be created for you
+#' @param freeze_opt Logical specifying whether any options you currently have
+#' locally (either as environment variables or R options) should be written to
+#' the `_server.yml` file. Shared secret will never be written to the file and
+#' you must find a different way to move that to your deployment server.
+#' @param options_prefix The prefix to use for the options when looking for
+#' options to freeze
+#'
+#' @export
+#' 
+create_server_yml <- function(
+  ...,
+  path = ".",
+  constructor = NULL,
+  freeze_opt = TRUE,
+  options_prefix = "plumber2"
+) {
+  routes <- unlist(list(...))
+  if (!is.null(routes)) {
+    check_character(routes)
+    if (any(!fs::file_exists(routes))) {
+      cli::cli_abort("{.arg ...} must point to existing files or directories")
+    }
+    routes <- fs::path_real(routes)
+    if (!all(fs::path_has_parent(routes, path))) {
+      cli::cli_abort(
+        "{.arg ...} must all point to files placed in subfolders relative to {.arg path}"
+      )
+    }
+    routes <- fs::path_rel(routes, path)
+  }
+  if (
+    !is.null(constructor) &&
+      (!fs::is_file(constructor) || !fs::path_ext(constructor) %in% c("R", "r"))
+  ) {
+    cli::cli_abort("{.arg constructor} must point to an existing R file")
+  }
+  settings <- list(
+    engine = "plumber2",
+    routes = routes,
+    constructor = constructor,
+    options = list()
+  )
+
+  if (freeze_opt) {
+    settings$options <- all_opts(prefix = options_prefix)
+  }
+  yaml::write_yaml(settings, fs::path_join(c(path, "_server.yml")))
+}
+
+is_plumber2_server_yml <- function(path) {
+  vapply(path, function(p) {
+    if (fs::path_file(p) != "_server.yml") {
+      return(FALSE)
+    }
+    isTRUE(tolower(yaml::read_yaml(p)$engine) == "plumber2")
+  }, logical(1))
+}

R/options.R

@@ -26,7 +26,7 @@
 #  )
 #}
 
-get_opts <- function(x, default = NULL, prefix = c("plumber2", "plumber")) {
+get_opts <- function(x, default = NULL, prefix = "plumber2") {
   getOption(paste0(prefix[1], ".", x), default = {
     env_name <- toupper(paste0(prefix[1], "_", x))
     res <- Sys.getenv(env_name)
@@ -44,3 +44,16 @@ get_opts <- function(x, default = NULL, prefix = c("plumber2", "plumber")) {
     res
   })
 }
+
+all_opts <- function(prefix = "plumber2") {
+  compact(list(
+    host = get_opts("host", prefix = prefix),
+    port = get_opts("port", prefix = prefix),
+    docType = get_opts("docType", prefix = prefix),
+    docPath = get_opts("docPath", prefix = prefix),
+    methodNotAllowed = get_opts("methodNotAllowed", prefix = prefix),
+    ignoreTrailingSlash = get_opts("ignoreTrailingSlash", prefix = prefix),
+    maxRequestSize = get_opts("maxRequestSize", prefix = prefix),
+    compressionLimit = get_opts("compressionLimit", prefix = prefix)
+  ))
+}

_pkgdown.yml

@@ -36,6 +36,7 @@ reference:
     contents:
       - api
       - api_run
+      - create_server_yml
   - title: "Adding handlers and routes"
     contents:
       - api_get