some naming updates

thomasp85 · thomasp85 · commit f76f7cd2bc28 · 2025-04-22T17:54:03.000+02:00
diff --git a/R/Plumber2.R b/R/Plumber2.R
@@ -2,14 +2,14 @@
 #'
 #' @description
 #' This class encapsulates all of the logic of a plumber2 api, and is what gets
-#' passed around in the functional api of plumber2. The Plumber2 class is a
+#' passed around in the functional api of plumber2. The `Plumber2` class is a
 #' subclass of the [fiery::Fire] class. Please consult the documentation for
 #' this for additional information on what this type of server is capable of.
-#' Note that the Plumber2 objects are reference objects, meaning that any change
-#' to it will change all instances of the object.
+#' Note that the `Plumber2` objects are reference objects, meaning that any
+#' change to it will change all instances of the object.
 #'
 #' ## Initialization
-#' A new 'Plumber2'-object is initialized using the `new()` method on the
+#' A new `Plumber2`-object is initialized using the `new()` method on the
 #' generator:
 #'
 #' \tabular{l}{
@@ -176,7 +176,7 @@ Plumber2 <- R6Class(
 
       if (!silent)
         cli::cli_text(
-          "Plumber2 server started at http://{self$host}:{self$port}"
+          "plumber2 server started at http://{self$host}:{self$port}"
         )
       super$ignite(block = block, showcase = showcase, ..., silent = TRUE)
     },
diff --git a/R/api.R b/R/api.R
@@ -1,6 +1,6 @@
 #' Create a new plumber API, optionally based on one or more plumber files
 #'
-#' This is the main way to create a new Plumber2 object that encapsulates your
+#' This is the main way to create a new [Plumber2] object that encapsulates your
 #' full api. It is also possible to add files to the API after creation using
 #' `api_parse()`
 #'
diff --git a/R/api_logger.R b/R/api_logger.R
@@ -1,6 +1,6 @@
 #' Set logging function and access log format for the API
 #'
-#' Plumber2 has a build-in logging facility that takes care of logging any
+#' plumber2 has a build-in logging facility that takes care of logging any
 #' conditions that are caught, as well as access logs. Further it is possible to
 #' log custom messages using the `log()` method on the api object. However, the
 #' actual logging is handled by a customizable function that can be set. You can
diff --git a/README.Rmd b/README.Rmd
@@ -118,7 +118,7 @@ get type checked and default value imputed if missing.
 
 For the `/plot` handler you can also see that it specifies multiple serializers.
 Doing so will allow the client to request its preferred response format using
-the `Accept` header. Plumber2 will then perform content negotiation to figure
+the `Accept` header. plumber2 will then perform content negotiation to figure
 out the best response format based on what it supports and what the client
 prefers.
 
diff --git a/README.md b/README.md
@@ -111,7 +111,7 @@ checked and default value imputed if missing.
 
 For the `/plot` handler you can also see that it specifies multiple
 serializers. Doing so will allow the client to request its preferred
-response format using the `Accept` header. Plumber2 will then perform
+response format using the `Accept` header. plumber2 will then perform
 content negotiation to figure out the best response format based on what
 it supports and what the client prefers.
 
diff --git a/man/Plumber2.Rd b/man/Plumber2.Rd
diff --git a/man/api.Rd b/man/api.Rd
diff --git a/man/api_logger.Rd b/man/api_logger.Rd
diff --git a/vignettes/_ex-mailgun.qmd b/vignettes/_ex-mailgun.qmd
@@ -24,7 +24,7 @@ Once you have a domain setup, you just add a route that tells mailgun what to do
 
 ![](files/images/mailgun-routes.png)
 
-## Plumber API
+## Plumber2 API
 
 This example will auto-refresh every 3 seconds with the latest emails the API has received. Try sending an email to <a href="mailto:mailgun@plumber.tres.tl">mailgun@plumber.tres.tl</a> to see the API at work.
 
diff --git a/vignettes/annotations.qmd b/vignettes/annotations.qmd
@@ -350,7 +350,7 @@ api() %>%
   api_statics("/", "./assets/static_files", except = "/secret_files")
 ```
 
-## Plumber annotation {#plumber-block-annotations}
+## plumber2 annotation {#plumber-block-annotations}
 
 | Annotation | Arguments | Description/References |
 |-------------------|-------------------|----------------------------------|
diff --git a/vignettes/execution-model.qmd b/vignettes/execution-model.qmd
@@ -28,7 +28,7 @@ readLines <- function(x) base::readLines(file.path(me, x))
 
 ## Execution Model {#execution-model}
 
-When you `plumb()` a file, Plumber calls `source()` on that file which will evaluate any top-level code that you have defined.
+When you `plumb()` a file, plumber2 calls `source()` on that file which will evaluate any top-level code that you have defined.
 
 ```{r}
 #| eval: false
@@ -43,45 +43,45 @@ When you create a plumber API using `api()` you can provide an environment to th
 
 ## Performance & Request Processing
 
-R is a single-threaded programming language, meaning that it can only do one task at a time. This is still true when serving APIs using Plumber, so if you have a single endpoint that takes two seconds to generate a response, then every time that endpoint is requested, your R process will be unable to respond to any additional incoming requests for those two seconds.
+R is a single-threaded programming language, meaning that it can only do one task at a time. This is still true when serving APIs using plumber2, so if you have a single endpoint that takes two seconds to generate a response, then every time that endpoint is requested, your R process will be unable to respond to any additional incoming requests for those two seconds.
 
 Incoming HTTP requests are serviced in the order in which they appeared, but if requests are coming in more quickly than they can be processed by the API, a backlog of requests will accrue. The common solutions to this problem are to do either or both of:
 
 1.  Keep your API performant. All filters and endpoints should complete very quickly and any long-running or complicated tasks should be done outside of the API process.
-2.  Run multiple R processes to redundantly host a single Plumber API and load-balance incoming requests between all available processes. See the [hosting section](./hosting.html) for details on which hosting environments support this feature.
+2.  Run multiple R processes to redundantly host a single plumber2 API and load-balance incoming requests between all available processes. See the [hosting section](./hosting.html) for details on which hosting environments support this feature.
 
 ## Managing State
 
-Often, Plumber APIs will require coordination of some state. This state may need to be shared between multiple endpoints in the same API (e.g. a counter that increments every time an endpoint is invoked). Alternatively, it could be information that needs to be persisted across requests from a single client (e.g. storing a preference or setting for some user). Lastly, it might require coordinating between multiple Plumber processes running independently behind a load-balancer. Each of these scenarios have unique properties that determine which solution might be appropriate.
+Often, plumber2 APIs will require coordination of some state. This state may need to be shared between multiple endpoints in the same API (e.g. a counter that increments every time an endpoint is invoked). Alternatively, it could be information that needs to be persisted across requests from a single client (e.g. storing a preference or setting for some user). Lastly, it might require coordinating between multiple plumber2 processes running independently behind a load-balancer. Each of these scenarios have unique properties that determine which solution might be appropriate.
 
 As previously discussed, R is single-threaded. Therefore it's important that you consider the fact that you may eventually need multiple R processes running in parallel to handle the incoming traffic of your API. While this may not seem important initially, you may thank yourself later for designing a "horizontally scalable" API (or one that can be scaled by adding more R processes in parallel).
 
-The key to building a horizontally scalable API is to ensure that each Plumber process is "stateless," meaning that any persistent state lives outside of the Plumber process. In any of the hosting environments that exist today, it is not guaranteed that two subsequent requests from a single client will be served by the same process. Thus it's never safe to assume that information stored in-memory will be available between requests for a horizontally scaled app. Below are a few options to consider to coordinate state for a Plumber API.
+The key to building a horizontally scalable API is to ensure that each plumber2 process is "stateless," meaning that any persistent state lives outside of the plumber2 process. In any of the hosting environments that exist today, it is not guaranteed that two subsequent requests from a single client will be served by the same process. Thus it's never safe to assume that information stored in-memory will be available between requests for a horizontally scaled app. Below are a few options to consider to coordinate state for a plumber2 API.
 
 ### In-Memory
 
-As shown previous in the [Execution Model section](#execution-model), it is possible to share state using the environment associated with the Plumber router.
+As shown previous in the [Execution Model section](#execution-model), it is possible to share state using the environment associated with the plumber2 router.
 
 ```{r}
 #| eval: false
 #| code: !expr readLines("files/apis/05-01-scope.R")
 ```
 
-This is the one approach presented that does not allow your Plumber process to be stateless. The approach is sufficient for coordinating state within a single route in a single process, but as you scale your API by adding processes or routes, this state will no longer be coordinated between them.
+This is the one approach presented that does not allow your plumber2 process to be stateless. The approach is sufficient for coordinating state within a single route in a single process, but as you scale your API by adding processes or routes, this state will no longer be coordinated between them.
 
 Therefore this approach can be effective for "read-only" data -- such as if you were to load a single, large dataset into memory when the API starts, then allow all filters and endpoints to reference that dataset moving forward -- but it will not allow you to share state across multiple processes as you scale. If you want to build a scalable, stateless application, you should avoid relying on the in-memory R environment to coordinate state between the pieces of your API.
 
 ### File System
 
-Writing to files on disk is often the next most obvious choice for storing state. Plumber APIs could modify a data frame then use `write.csv()` to save that data to disk, or use `writeLines()` to append some new data to an existing file. These approaches enable your R process to be stateless, but are not always resilient to concurrency issues. For instance, if you've horizontally scaled your API to five R processes and two go to `write.csv()` simultaneously, you will either see one process's data get immediately overwritten by the other's, or -- even worse -- you may end up with a corrupted CSV file which can't be read. Unless otherwise stated, it's safe to assume that any R function that writes data to disk is not resilient to concurrency contention, so you should not rely on the filesystem to coordinate shared state for any more than a single R process running concurrently.
+Writing to files on disk is often the next most obvious choice for storing state. plumber2 APIs could modify a data frame then use `write.csv()` to save that data to disk, or use `writeLines()` to append some new data to an existing file. These approaches enable your R process to be stateless, but are not always resilient to concurrency issues. For instance, if you've horizontally scaled your API to five R processes and two go to `write.csv()` simultaneously, you will either see one process's data get immediately overwritten by the other's, or -- even worse -- you may end up with a corrupted CSV file which can't be read. Unless otherwise stated, it's safe to assume that any R function that writes data to disk is not resilient to concurrency contention, so you should not rely on the filesystem to coordinate shared state for any more than a single R process running concurrently.
 
 It's also important to ask whether or not the [hosting platform](./hosting.html) you'll be using supports persistent storage on disk. For instance, Docker may insulate your R process from your hardware and not allow you to write outside of your container. RStudio Connect, too, will provision a new directory every time you deploy an updated version of your API which will discard any data you had written to disk up to that point. So if you're considering writing your state to disk long-term, be sure that your hosting environment supports persistent on-disk storage and that you've considered the concurrency implications of your code.
 
 ### Cookies {#state-cookies}
 
-HTTP cookies are a convention that allow web servers to send some state to a client with the expectation that the client would then include that state in future requests. See the [Setting Cookies section](./rendering-output.html#setting-cookies) for details on how to leverage cookies in Plumber.
+HTTP cookies are a convention that allow web servers to send some state to a client with the expectation that the client would then include that state in future requests. See the [Setting Cookies section](./rendering-output.html#setting-cookies) for details on how to leverage cookies in plumber2.
 
-All modern web browsers support cookies (unless configured not to) and many other clients do, as well, though some clients require additional configuration in order to do so. If you're confident that the intended clients for your API support cookies then you could consider storing some state in cookies. This approach mitigates concerns about horizontal scalability, as the state is written to each client independently and then included in subsequent requests from that client. This also minimizes the infrastructure requirements for hosting your Plumber APIs since you don't need to setup a system capable of storing all of this state; instead, you've commissioned your clients to store their own state.
+All modern web browsers support cookies (unless configured not to) and many other clients do, as well, though some clients require additional configuration in order to do so. If you're confident that the intended clients for your API support cookies then you could consider storing some state in cookies. This approach mitigates concerns about horizontal scalability, as the state is written to each client independently and then included in subsequent requests from that client. This also minimizes the infrastructure requirements for hosting your plumber2 APIs since you don't need to setup a system capable of storing all of this state; instead, you've commissioned your clients to store their own state.
 
 One issue with maintaining state in cookies is that their size should be kept to a minimum. Clients impose restrictions differently, but you should not plan to store more than 4kB of information in a cookie. And realize that whatever information gets placed in the cookie must be retransmitted by the client with *every* request. This can significantly increase the size of each HTTP request that your clients make.
 
@@ -93,11 +93,11 @@ If you'd like to use cookies to store information with guarantees that the user
 
 The final option to consider when coordinating state for an API is leveraging an external data store. This could be a relational database (like MySQL or Amazon RedShift), a non-relational database (like MongoDB), or an transactional data store like Redis.
 
-One important consideration for any of these options is to ensure that they are "transactional," meaning that two Plumber processes trying to write at the same time won't overwrite one another. If you're interested in pursuing this option you should see [solutions.rstudio.com/db/](https://solutions.rstudio.com/db/) or look at [some](http://shiny.rstudio.com/articles/overview.html) of the [resources](http://shiny.rstudio.com/articles/sql-injections.html) [put together](http://shiny.rstudio.com/articles/pool-basics.html) for Shiny as pertains to dealing with databases in a web-accessible R platform.
+One important consideration for any of these options is to ensure that they are "transactional," meaning that two plumber2 processes trying to write at the same time won't overwrite one another. If you're interested in pursuing this option you should see [solutions.rstudio.com/db/](https://solutions.rstudio.com/db/) or look at [some](http://shiny.rstudio.com/articles/overview.html) of the [resources](http://shiny.rstudio.com/articles/sql-injections.html) [put together](http://shiny.rstudio.com/articles/pool-basics.html) for Shiny as pertains to dealing with databases in a web-accessible R platform.
 
 ## Exit Handlers
 
-It may be useful to define a function that you want to run as your API is closing -- for instance, if you have a pool of database connections that need to be cleaned up when your Plumber process is being terminated. You can add a handler to the `"end"` event to do this.
+It may be useful to define a function that you want to run as your API is closing -- for instance, if you have a pool of database connections that need to be cleaned up when your plumber2 process is being terminated. You can add a handler to the `"end"` event to do this.
 
 ``` r
 api("plumber.R") |>
diff --git a/vignettes/hosting.qmd b/vignettes/hosting.qmd
