diff --git a/404.html b/404.html index e44be84f3..73d2ee279 100644 --- a/404.html +++ b/404.html @@ -14,8 +14,8 @@ - - + + diff --git a/CONTRIBUTING.html b/CONTRIBUTING.html index d4c823721..b452eac1a 100644 --- a/CONTRIBUTING.html +++ b/CONTRIBUTING.html @@ -1,5 +1,5 @@ -Contributing • plumberContributing • plumber @@ -67,6 +67,7 @@
Releases
+

We welcome contributions to the plumber package!

To submit a contribution:

  1. Fork the repository and make your changes.

    2. diff --git a/LICENSE-text.html b/LICENSE-text.html index bf07acd09..1c42e85db 100644 --- a/LICENSE-text.html +++ b/LICENSE-text.html @@ -1,5 +1,5 @@ -License • plumberLicense • plumber diff --git a/PULL_REQUEST_TEMPLATE.html b/PULL_REQUEST_TEMPLATE.html index 7294dc341..1ced726e4 100644 --- a/PULL_REQUEST_TEMPLATE.html +++ b/PULL_REQUEST_TEMPLATE.html @@ -1,5 +1,5 @@ -NA • plumberNA • plumber diff --git a/articles/annotations.html b/articles/annotations.html index bdbfb9a51..b7aa85b84 100644 --- a/articles/annotations.html +++ b/articles/annotations.html @@ -15,8 +15,8 @@ - - + + @@ -93,7 +93,8 @@
    Releases
    -
    + +

    Annotations reference

    @@ -107,12 +108,19 @@
    Releases

    Annotations

    -

    Annotations are specially-structured comments used in your plumber file to create an API. A full annotation line starts with #* or #', then the annotation keyword @..., any number of space characters followed by the content. It is recommended to use #* to differentiate them from roxygen2 annotations.

    +

    Annotations are specially-structured comments used in your plumber +file to create an API. A full annotation line starts with +#* or #', then the annotation keyword +@..., any number of space characters followed by the +content. It is recommended to use #* to differentiate them +from roxygen2 annotations.

    Global annotations

    -

    Global annotations can be used anywhere in your plumber file. They are independent from other annotations and do not require an expression.

    +

    Global annotations can be used anywhere in your plumber file. They +are independent from other annotations and do not require an +expression.

    @@ -128,39 +136,47 @@

    Global annotations

    - + - + - + - + - + - + - @@ -201,7 +217,11 @@
    Equivalent programmatic usage

    Block annotations

    -

    A block of annotations is a combination of annotations that create either an endpoint, a filter, a static file handler or a Plumber object modifier. Block annotations are always followed by an expression.

    +

    A block of annotations is a combination of annotations that create +either an endpoint, a +filter, a static file +handler or a Plumber object modifier. Block annotations are always +followed by an expression.

    Endpoint

    @@ -219,65 +239,105 @@

    Endpoint

    - + - + - + - + - - - +
    @apiTitle TitleInfo ObjectInfo +Object
    @apiDescription DescriptionInfo ObjectInfo +Object
    @apiTOS TOS linkInfo ObjectInfo +Object
    @apiContact Contact objectContact ObjectContact +Object
    @apiLicense License objectLicense ObjectLicense +Object
    @apiVersion VersionInfo ObjectInfo +Object
    @apiTag Tag Description Can be repeated to add multiple tags. Quote with " or ’ to use non word character (like spaces) in Tag. Tag Object +Can be repeated to add multiple tags. Quote with ” or ’ to use non +word character (like spaces) in Tag. Tag +Object
    -@get, @post, @put, @use, @delete, @head, @options, @patch +@get, @post, @put, +@use, @delete, @head, +@options, @patch Path -Endpoints, Dynamic Routes, Typed Dynamic Routes +Endpoints, Dynamic Routes, Typed Dynamic +Routes
    @serializer Alias [Args list]]Some serializers accept arguments. See serializers article and serializers reference. Aliases : bmp, cat, contentType, csv, device, feather, format, geojson, html, htmlwidget, jpeg, json, null, octet, parquet, pdf, png, print, rds, svg, text, tiff, tsv, unboxedJSON, yaml from registered_serializers().Some serializers accept arguments. See serializers article and +serializers +reference. Aliases : bmp, cat, +contentType, csv, device, +feather, format, geojson, +html, htmlwidget, jpeg, +json, null, octet, +parquet, pdf, png, +print, rds, svg, +text, tiff, tsv, +unboxedJSON, yaml from registered_serializers().
    @parser Alias [Args list] Some parsers accept arguments. See parsers reference. Can be repeated to allow multiple parsers on the same endpoint. Aliases : all, csv, feather, form, geojson, json, multi, none, octet, parquet, rds, text, tsv, yaml from registered_parsers().Some parsers accept arguments. See parsers +reference. Can be repeated to allow multiple parsers on the same +endpoint. Aliases : all, csv, +feather, form, geojson, +json, multi, none, +octet, parquet, rds, +text, tsv, yaml from registered_parsers().
    @param Name[:Type Description]Enclose Type between square brackets [] to indicate it is an array. Can be repeated to define different parameters.Enclose Type between square brackets [] to +indicate it is an array. Can be repeated to define different +parameters.
    @response Name Description Simple Response object. Can be repeated to define different responses.Simple Response +object. Can be repeated to define different responses.
    @tag TagCan be repeated to add multiple tags. Quote with " or ’ to use non word character (like spaces) in Tag. Tag field +Can be repeated to add multiple tags. Quote with ” or ’ to use non +word character (like spaces) in Tag. Tag +field
    @preempt FilterSpecify that this endpoint has to execute before Filter. Filters +Specify that this endpoint has to execute before +Filter. Filters
    None CommentsFirst line without annotation will be mapped to Summary field subsequent lines will be mapped to Description field.First line without annotation will be mapped to Summary +field subsequent lines will be mapped to Description +field.

    More details on @param

    -

    Types are used to define API inputs. You can use most of them in dynamic routes. Note that Plumber first look in block expression to set endpoint parameters names, types and default value. Then @param annotations and dynamic route/path defined parameters will override Plumber guesses from block expression.

    -

    Query parameters currently need to be explicitly converted as they are pushed as is (character) to block expression. Only dynamic route parameters are converted to specified @param type before being pushed to block expression.

    -

    Plumber parameter type to OpenAPI type reference. For programmatic use, pick the one with an asterisk.

    +

    Types are used to define API inputs. You can use most of them in +dynamic routes. Note that Plumber first look in block expression to set +endpoint parameters names, types and default value. Then +@param annotations and dynamic route/path defined +parameters will override Plumber guesses from block expression.

    +

    Query parameters currently need to be explicitly converted as they +are pushed as is (character) to block expression. Only dynamic route +parameters are converted to specified @param type before +being pushed to block expression.

    +

    Plumber parameter type to OpenAPI type reference. For programmatic +use, pick the one with an asterisk.

    +++++ @@ -295,7 +355,8 @@

    More details on @param

    +chr, str, character, +string* +list, data.frame, df, +object* @@ -402,6 +465,11 @@
    Equivalent programmatic usageFilter
    Type OpenAPI -dbl, double, float, number*, numeric +dbl, double, float, +number*, numeric number format:double @@ -316,7 +377,8 @@

    More details on @param

    		-chr, str, character, string*string query, path @@ -324,7 +386,8 @@

    More details on @param

    		-list, data.frame, df, object*object body
    +++++ @@ -442,6 +510,11 @@
    Equivalent programmatic usageStatic File Handler
    Annotation Argument
    +++++ @@ -451,7 +524,8 @@

    Static File Handler@assets

    - +
    Annotation Arguments Directory [Mount path]Static filesStatic +files
    @@ -468,7 +542,8 @@
    Annotations examplelist()
    -
    Equivalent programmatic usage (note that argument order is reversed) +
    Equivalent programmatic usage (note that argument order is +reversed) 
     pr() %>%
@@ -498,7 +573,11 @@ 
    Plumber Router Modifier
 @plumber
 None
-Modify plumber router from plumber file. The plumber router provided to the function must be returned. In most cases, anonymous functions are used following the #* @plumber annotation. However, named functions can also be used. When a named function is used, it must be referenced without parentheses.
+Modify plumber router from plumber file. The plumber router provided
+to the function must be returned. In most cases,
+anonymous functions are used following the #* @plumber
+annotation. However, named functions can also be used. When a named
+function is used, it must be referenced without parentheses.
 
 
 
    
diff --git a/articles/annotations_files/accessible-code-block-0.0.1/empty-anchor.js b/articles/annotations_files/accessible-code-block-0.0.1/empty-anchor.js
deleted file mode 100644
index ca349fd6a..000000000
--- a/articles/annotations_files/accessible-code-block-0.0.1/empty-anchor.js
+++ /dev/null
@@ -1,15 +0,0 @@
-// Hide empty  tag within highlighted CodeBlock for screen reader accessibility (see https://github.com/jgm/pandoc/issues/6352#issuecomment-626106786) -->
-// v0.0.1
-// Written by JooYoung Seo (jooyoung@psu.edu) and Atsushi Yasumoto on June 1st, 2020.
-
-document.addEventListener('DOMContentLoaded', function() {
-  const codeList = document.getElementsByClassName("sourceCode");
-  for (var i = 0; i < codeList.length; i++) {
-    var linkList = codeList[i].getElementsByTagName('a');
-    for (var j = 0; j < linkList.length; j++) {
-      if (linkList[j].innerHTML === "") {
-        linkList[j].setAttribute('aria-hidden', 'true');
-      }
-    }
-  }
-});
diff --git a/articles/execution-model.html b/articles/execution-model.html
index 2af0481f2..8c5cce934 100644
--- a/articles/execution-model.html
+++ b/articles/execution-model.html
@@ -15,8 +15,8 @@
 
 
 
-
-
+
+
 
 
 
@@ -93,7 +93,8 @@ 
    Releases
    
 
 
 
-
    
+
+
    
   
    
       
    Runtime
    
             
@@ -107,7 +108,9 @@ 
    Releases
    
 
    
 
    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, Plumber calls
+source() on that file which will evaluate any top-level
+code that you have defined.
    
 
     # Global code; gets executed at plumb() time.
 counter <- 0
@@ -117,40 +120,97 @@ 
    Execution Model  # Only gets evaluated when this endpoint is requested.
   counter <<- counter + 1
 }
    
-
    If you call plumb() on this file, the counter variable will be created and will live in the environment created for this API. However, the endpoint defined will not be evaluated until it is invoked in response to an incoming request. Because the endpoint uses <<-, the “double-assignment” operator, it mutates the counter variable that was previously defined when the file was plumb()d. This technique allows all endpoints and filters to share some data defined at the top-level of your API.
    
+
    If you call plumb() on this file, the
+counter variable will be created and will live in the
+environment created for this API. However, the endpoint defined will not
+be evaluated until it is invoked in response to an incoming request.
+Because the endpoint uses <<-, the
+“double-assignment” operator, it mutates the counter
+variable that was previously defined when the file was
+plumb()d. This technique allows all endpoints and filters
+to share some data defined at the top-level of your API.
    
 
    
 
    
 
    Environments
 
    
-
    By default, when you create a new Plumber router (which happens implicitly when you call plumb() on a file), a new environment is created especially for this router. It is in this environment that all expressions will be evaluated and all endpoints invoked.
    
-
    This can become important if you consider mounting routers onto one another. In that case, you may expect that they would be able to share state via their environment, but that will not work by default. If you’re creating your routers programmatically, then you can specify an environment when initializing your Plumber router using the envir parameter. This is the environment in which:
    
+
    By default, when you create a new Plumber router (which happens
+implicitly when you call plumb() on a file), a new
+environment is created especially for this router. It is in this
+environment that all expressions will be evaluated and all endpoints
+invoked.
    
+
    This can become important if you consider mounting routers onto one
+another. In that case, you may expect that they would be able to share
+state via their environment, but that will not work by default. If
+you’re creating your
+routers programmatically, then you can specify an environment when
+initializing your Plumber router using the envir parameter.
+This is the environment in which:
    
 
      
-
    • A decorated R script, if provided, will be source()d.
      • 
+
    • A decorated R script, if provided, will be
+source()d.
      • 
 
    • All expressions will be evaluated.
      • 
 
    • All endpoint and filter functions will be executed.
      • 
 
    
-
    It is important to be aware that subrouters, by default, would each have their own environment. If you want multiple Plumber routers to share an environment, you will need to provide a single, shared environment when you create the routers.
    
+
    It is important to be aware that subrouters, by default, would each
+have their own environment. If you want multiple Plumber routers to
+share an environment, you will need to provide a single, shared
+environment when you create the routers.
    
 
    
 
    
 
    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.
    
-
    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:
    
+
    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.
    
+
    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. 
-
    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 for details on which hosting environments support this feature.
      3. 
+
    3. 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.
      4. 
+
    4. Run multiple R processes to redundantly host a single Plumber API
+and load-balance incoming requests between all available processes. See
+the hosting section for details on which
+hosting environments support this feature.
      5. 
 
    
 
    
 
    
 
    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.
    
-
    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.
    
+
    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.
    
+
    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.
    
 
    
 
    In-Memory
 
    
-
    As shown previous in the Execution Model section, it is possible to share state using the environment associated with the Plumber router.
    
+
    As shown previous in the Execution Model
+section, it is possible to share state using the environment
+associated with the Plumber router.
    
 
     # Global code; gets executed at plumb() time.
 counter <- 0
@@ -160,42 +220,119 @@ 
    In-Memory# Only gets evaluated when this endpoint is requested.
   counter <<- counter + 1
 }
    
-
    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 process, but as you scale your API by adding processes, 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.
    
+
    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 process, but as you scale your API by adding
+processes, 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.
    
-
    It’s also important to ask whether or not the hosting platform 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.
    
+
    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.
    
+
    It’s also important to ask whether or not the hosting platform 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
 
    
-
    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 for details on how to leverage cookies in Plumber.
    
-
    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.
    
-
    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.
    
-
    The most notable concern when considering using cookies to store state is that since your clients are responsible for storing and sending their state, you cannot expect that the state has not been tampered with. Thus, while it may be acceptable to store user preferences like preferredColor="blue", you should not store authentication information like userID=1493, since the user could trivially change that cookie to another user’s ID to impersonate them.
    
-
    If you’d like to use cookies to store information with guarantees that the user cannot either read or modify the state, see the Encrypted Cookies section).
    
+
    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 for details on how to leverage cookies in Plumber.
    
+
    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.
    
+
    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.
    
+
    The most notable concern when considering using cookies to store
+state is that since your clients are responsible for storing and sending
+their state, you cannot expect that the state has not been tampered
+with. Thus, while it may be acceptable to store user preferences like
+preferredColor="blue", you should not store
+authentication information like userID=1493, since the user
+could trivially change that cookie to another user’s ID to impersonate
+them.
    
+
    If you’d like to use cookies to store information with guarantees
+that the user cannot either read or modify the state, see the Encrypted Cookies
+section).
    
 
    
 
    
 
    External Data Store
 
    
-
    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/ or look at some of the resources put together for Shiny as pertains to dealing with databases in a web-accessible R platform.
    
+
    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/
+or look at some of the
+resources
+put
+together 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 use the exit hook to define such a handler.
    
+
    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 use the exit hook to define such
+a handler.
    
 
     pr("plumber.R") %>%
   pr_hook("exit", function(){
     print("Bye bye!")
   }) %>%
   pr_run()
    
-
    When you interrupt the API (for instance by pressing the Escape key or Ctrl+C) you’ll see Bye bye! printed to the console. You can even register multiple exit hooks and they’ll be run in the order in which they were registered.
    
+
    When you interrupt the API (for instance by pressing the
+Escape key or Ctrl+C) you’ll see
+Bye bye! printed to the console. You can even register
+multiple exit hooks and they’ll be run in the order in
+which they were registered.
    
 
    
   
    
diff --git a/articles/execution-model_files/accessible-code-block-0.0.1/empty-anchor.js b/articles/execution-model_files/accessible-code-block-0.0.1/empty-anchor.js
deleted file mode 100644
index ca349fd6a..000000000
--- a/articles/execution-model_files/accessible-code-block-0.0.1/empty-anchor.js
+++ /dev/null
@@ -1,15 +0,0 @@
-// Hide empty  tag within highlighted CodeBlock for screen reader accessibility (see https://github.com/jgm/pandoc/issues/6352#issuecomment-626106786) -->
-// v0.0.1
-// Written by JooYoung Seo (jooyoung@psu.edu) and Atsushi Yasumoto on June 1st, 2020.
-
-document.addEventListener('DOMContentLoaded', function() {
-  const codeList = document.getElementsByClassName("sourceCode");
-  for (var i = 0; i < codeList.length; i++) {
-    var linkList = codeList[i].getElementsByTagName('a');
-    for (var j = 0; j < linkList.length; j++) {
-      if (linkList[j].innerHTML === "") {
-        linkList[j].setAttribute('aria-hidden', 'true');
-      }
-    }
-  }
-});
diff --git a/articles/hosting.html b/articles/hosting.html
index 0c3e406df..3c30280fb 100644
--- a/articles/hosting.html
+++ b/articles/hosting.html
@@ -15,8 +15,8 @@
 
 
 
-
-
+
+
 
 
 
@@ -93,7 +93,8 @@ 
    Releases
    
 
 
 
-
    
+
+
    
   
    
       
    Hosting
    
             
@@ -104,77 +105,199 @@ 
    Releases
    
 
     
     
-
    Once you have developed your Plumber API, the next step is to find a way to host it. If you haven’t dealt with hosting an application on a server before, you may be tempted to run the run() command from an interactive session on your development machine (either your personal desktop or an RStudio Server instance) and direct traffic there. This is a dangerous idea for a number of reasons:
    
+
    Once you have developed your Plumber API, the next step is to find a
+way to host it. If you haven’t dealt with hosting an application on a
+server before, you may be tempted to run the run() command
+from an interactive session on your development machine (either your
+personal desktop or an RStudio Server instance) and direct traffic
+there. This is a dangerous idea for a number of reasons:
    
 
      
-
    1. Your development machine likely has a dynamic IP address. This means that clients may be able to reach you at that address today, but it will likely break on you in the coming weeks/months.
      2. 
-
    2. Networks may leverage firewalls to block incoming traffic to certain networks and machines. Again, it may appear that everything is working for you locally, but other users elsewhere in the network or external clients may not be able to connect to your development machine.
      3. 
-
    3. If your Plumber process crashes (for instance, due to your server running out of memory), the method of running Plumber will not automatically restart the crashed service for you. This means that your API will be offline until you manually login and restart it. Likewise if your development machine gets rebooted, your API will not automatically be started when the machine comes back online.
      4. 
-
    4. This technique relies on having your clients specify a port number manually. Non-technical users may be tripped up by this; some of the other techniques do not require clients specifying the port for an API.
      5. 
-
    5. This approach will eternally run one R process for your API. Some of the other approaches will allow you to load-balance traffic between multiple R processes to handle more requests. RStudio Connect will even dynamically scale the number of running processes for you so that your API isn’t consuming more system resources than is necessary.
      6. 
-
    6. Most importantly, serving public requests from your development environment can be a security hazard. Ideally, you should separate your development instances from the servers that are accessible by others.
      7. 
+
    7. Your development machine likely has a dynamic IP address. This means
+that clients may be able to reach you at that address today, but it will
+likely break on you in the coming weeks/months.
      8. 
+
    8. Networks may leverage firewalls to block incoming traffic to certain
+networks and machines. Again, it may appear that everything is working
+for you locally, but other users elsewhere in the network or external
+clients may not be able to connect to your development machine.
      9. 
+
    9. If your Plumber process crashes (for instance, due to your server
+running out of memory), the method of running Plumber will not
+automatically restart the crashed service for you. This means that your
+API will be offline until you manually login and restart it. Likewise if
+your development machine gets rebooted, your API will not automatically
+be started when the machine comes back online.
      10. 
+
    10. This technique relies on having your clients specify a port number
+manually. Non-technical users may be tripped up by this; some of the
+other techniques do not require clients specifying the port for an
+API.
      11. 
+
    11. This approach will eternally run one R process for your API. Some of
+the other approaches will allow you to load-balance traffic between
+multiple R processes to handle more requests. Posit Connect will even dynamically scale the
+number of running processes for you so that your API isn’t consuming
+more system resources than is necessary.
      12. 
+
    12. Most importantly, serving public requests from your development
+environment can be a security hazard. Ideally, you should separate your
+development instances from the servers that are accessible by
+others.
      13. 
 
    
-
    For these reasons and more, you should consider setting up a separate server on which you can host your Plumber APIs. There are a variety of options that you can consider.
    
+
    For these reasons and more, you should consider setting up a separate
+server on which you can host your Plumber APIs. There are a variety of
+options that you can consider.
    
 
    
-
    RStudio Connect
+
    Posit Connect
 
    
-
    RStudio Connect is an enterprise publishing platform from RStudio. It supports push-button publishing from the RStudio IDE of a variety of R content types including Plumber APIs. Unlike all the other options listed here, RStudio Connect automatically manages the dependent packages and files your API has and recreates an environment closely mimicking your local development environment on the server.
    
-
    RStudio Connect automatically manages the number of R processes necessary to handle the current load and balances incoming traffic across all available processes. It can also shut down idle processes when they’re not in use. This allows you to run the appropriate number of R processes to scale your capacity to accommodate the current load.
    
+
    Posit
+Connect is an enterprise publishing platform from Posit. It supports
+push-button publishing from the RStudio IDE of a variety of R content
+types including Plumber APIs. Unlike all the other options listed here,
+Posit Connect automatically manages the dependent packages and files
+your API has and recreates an environment closely mimicking your local
+development environment on the server.
    
+
    Posit Connect automatically manages the number of R processes
+necessary to handle the current load and balances incoming traffic
+across all available processes. It can also shut down idle processes
+when they’re not in use. This allows you to run the appropriate number
+of R processes to scale your capacity to accommodate the current
+load.
    
 
    
 
    
 
    DigitalOcean
 
    
-
    DigitalOcean is an easy-to-use Cloud Computing provider. They offer a simple way to spin up a Linux virtual machine and access it remotely. You can choose what size machine you want to run – with options ranging from small machines with 512MB of RAM for a few dollars a month up to large machines with dozens of GB of RAM – and only pay for it while it’s online.
    
-
    To deploy your Plumber API to DigitalOcean, please check out the plumber companion package plumberDeploy.
    
+
    DigitalOcean is an
+easy-to-use Cloud Computing provider. They offer a simple way to spin up
+a Linux virtual machine and access it remotely. You can choose what size
+machine you want to run – with options ranging from small machines with
+512MB of RAM for a few dollars a month up to large machines with dozens
+of GB of RAM – and only pay for it while it’s online.
    
+
    To deploy your Plumber API to DigitalOcean, please check out the
+plumber companion package plumberDeploy.
    
 
    
 
    
 
    Docker (Basic)
 
    
-
    Docker is a platform built on top of Linux Containers that allow you to run processes in an isolated environment; that environment might have certain resources/software pre-configured or may emulate a particular Linux environment like Ubuntu 14.04 or CentOS 7.3.
    
-
    We won’t delve into the details of Docker or how to setup or install everything on your system. Docker provides some great resources for those who are looking to get started. Here we’ll assume that you have Docker installed and you’re familiar with the basic commands required to spin up a container.
    
-
    In this article, we’ll take advantage of the rstudio/plumber Docker image that bundles a recent version of R with the most recent version of plumber pre-installed (the underlying R image is courtesy of the rocker project). You can get this image with a
    
-
    docker pull rstudio/plumber
    
-
    Remember that this will get you the current snapshot of Plumber and will continue to use that image until you run pull again.
    
+
    Docker is a platform built on top of
+Linux Containers that allow you to run processes in an isolated
+environment; that environment might have certain resources/software
+pre-configured or may emulate a particular Linux environment like Ubuntu
+14.04 or CentOS 7.3.
    
+
    We won’t delve into the details of Docker or how to setup or install
+everything on your system. Docker provides some great resources for those who are
+looking to get started. Here we’ll assume that you have Docker installed
+and you’re familiar with the basic commands required to spin up a
+container.
    
+
    In this article, we’ll take advantage of the rstudio/plumber
+Docker image that bundles a recent version of R with the most recent
+version of plumber pre-installed (the underlying R image is courtesy of
+the rocker project).
+You can get this image with a
    
+
    docker pull rstudio/plumber
    
+
    Remember that this will get you the current snapshot of Plumber and
+will continue to use that image until you run pull
+again.
    
 
    
 
    Default Dockerfile
 
    
-
    We’ll start by just running a single Plumber application in Docker just to see things at work. By default, the rstudio/plumber image will take the first argument after the image name as the name of the file that you want to plumb() and serve on port 8000. So right away you can run one of the examples that’s included in plumber as it is already installed on the image.
    
-
    docker run --rm -p 8000:8000 rstudio/plumber
    
+
    We’ll start by just running a single Plumber application in Docker
+just to see things at work. By default, the rstudio/plumber
+image will take the first argument after the image name as the name of
+the file that you want to plumb() and serve on port
+8000. So right away you can run one of the examples that’s
+included in plumber as it is already installed on the image.
    
+
    docker run --rm -p 8000:8000 rstudio/plumber
    
 
    which is the same as:
    
-
    docker run --rm -p 8000:8000 rstudio/plumber \
-  /usr/local/lib/R/site-library/plumber/plumber/04-mean-sum/plumber.R
    
+
    docker run --rm -p 8000:8000 rstudio/plumber \
+  /usr/local/lib/R/site-library/plumber/plumber/04-mean-sum/plumber.R
    
 
      
 
    • 
 docker run tells Docker to run a new container
      • 
 
    • 
---rm tells Docker to clean-up after the container when it’s done
      • 
+--rm tells Docker to clean-up after the container when
+it’s done
 
    • 
--p 8000:8000 says to map port 8000 from the plumber container (which is where we’ll run the server) to port 8000 of your local machine
      • 
+-p 8000:8000 says to map port 8000 from the plumber
+container (which is where we’ll run the server) to port 8000 of your
+local machine
 
    • 
-rstudio/plumber is the name of the image we want to run
      • 
+rstudio/plumber is the name of the image we want to
+run
 
    • 
-/usr/local/lib/R/site-library/plumber/plumber/03-mean-sum/plumber.R is the path inside of the Docker container to the Plumber file you want to host. You’ll note that you do not need plumber installed on your host machine for this to work, nor does the path /usr/local/... need to exist on your host machine. This references the path inside of the docker container where the R file you want to plumb() can be found. This mean-sum path is the default path that the image uses if you don’t specify one yourself.
      • 
+/usr/local/lib/R/site-library/plumber/plumber/03-mean-sum/plumber.R
+is the path inside of the Docker container to the
+Plumber file you want to host. You’ll note that you do not need plumber
+installed on your host machine for this to work, nor does the path
+/usr/local/... need to exist on your host machine. This
+references the path inside of the docker container where the R file you
+want to plumb() can be found. This mean-sum
+path is the default path that the image uses if you don’t specify one
+yourself.
 
    
-
    This will ask Plumber to plumb and run the file you specified on port 8000 of that new container. Because you used the -p argument, port 8000 of your local machine will be forwarded into your container. You can test this by running this on the machine where Docker is running: curl localhost:8000/mean, or if you know the IP address of the machine where Docker is running, you could visit it in a web browser. The /mean path is one that’s defined in the plumber file we just specified – you should get an single number in an array back ([-0.1993]).
    
-
    If that works, you can try using one of your own plumber files in this arrangement. Keep in mind that the file you want to run must be available inside of the container and you must specify the path to that file as it exists inside of the container. Keep it simple for now – use a plumber file that doesn’t require any additional R packages or depend on any other files outside of the plumber definition.
    
-
    For instance if you have a plumber file saved in your current directory called api.R, you could use the following command
    
-
    docker run --rm -p 8000:8000 -v `pwd`/api.R:/plumber.R rstudio/plumber /plumber.R
    
-
    You’ll notice that we used the -v argument to specify a “volume” that should be mapped from our host machine into the Docker container. We defined that the location of that file should be at /plumber.R, so that’s the argument we give last to tell the container where to look for the plumber definition. You can use this same technique to share a whole directory instead of just passing in a single R file; this approach is useful if your Plumber API depends on other files.
    
-
    You can also use the rstudio/plumber image just like you use any other. For example, if you want to start a container based on this image and poke around in a bash shell:
    
-
    docker run -it --rm --entrypoint /bin/bash rstudio/plumber
    
-
    This can be a handy way to debug problems. Prepare the command that you think should work then add --entrypoint /bin/bash before rstudio/plumber and explore a bit. Alternatively, you can try to run the R process and spawn the plumber application yourself and see where things go wrong (often a missing package or missing file).
    
+
    This will ask Plumber to plumb and run the
+file you specified on port 8000 of that new container. Because you used
+the -p argument, port 8000 of your local machine will be
+forwarded into your container. You can test this by running this on the
+machine where Docker is running: curl localhost:8000/mean,
+or if you know the IP address of the machine where Docker is running,
+you could visit it in a web browser. The /mean path is one
+that’s defined in the plumber file we just specified – you should get an
+single number in an array back ([-0.1993]).
    
+
    If that works, you can try using one of your own plumber files in
+this arrangement. Keep in mind that the file you want to run
+must be available inside of the container and you must
+specify the path to that file as it exists inside of the container. Keep
+it simple for now – use a plumber file that doesn’t require any
+additional R packages or depend on any other files outside of the
+plumber definition.
    
+
    For instance if you have a plumber file saved in your current
+directory called api.R, you could use the following
+command
    
+
    docker run --rm -p 8000:8000 -v `pwd`/api.R:/plumber.R rstudio/plumber /plumber.R
    
+
    You’ll notice that we used the -v argument to specify a
+“volume” that should be mapped from our host machine into the Docker
+container. We defined that the location of that file should be at
+/plumber.R, so that’s the argument we give last to tell the
+container where to look for the plumber definition. You can use this
+same technique to share a whole directory instead of just passing in a
+single R file; this approach is useful if your Plumber API depends on
+other files.
    
+
    You can also use the rstudio/plumber image just like you
+use any other. For example, if you want to start a container based on
+this image and poke around in a bash shell:
    
+
    docker run -it --rm --entrypoint /bin/bash rstudio/plumber
    
+
    This can be a handy way to debug problems. Prepare the command that
+you think should work then add --entrypoint /bin/bash
+before rstudio/plumber and explore a bit. Alternatively,
+you can try to run the R process and spawn the plumber application
+yourself and see where things go wrong (often a missing package or
+missing file).
    
 
    
 
    
 
    Custom Dockerfiles
 
    
-
    You can build upon the rstudio/plumber image and build your own Docker image by writing your own Dockerfile. Dockerfiles have a vast array of options and possible configurations, so see the official docs if you want to learn more about any of these options.
    
+
    You can build upon the rstudio/plumber image and build
+your own Docker image by writing your own Dockerfile. Dockerfiles have a
+vast array of options and possible configurations, so see the
+official docs if you want to learn more about any of these
+options.
    
 
    A couple of commands that are relevant here:
    
 
      
 
    • 
-RUN runs a command and persists the side-effects in the Docker image you’re building. So if you want to build a new image that has the broom package, you could add a line in your Dockerfile that says RUN R -e "install.packages('broom')" which would make the broom package available in your new Docker image.
      • 
+RUN runs a command and persists the side-effects in the
+Docker image you’re building. So if you want to build a new image that
+has the broom package, you could add a line in your
+Dockerfile that says RUN R -e "install.packages('broom')"
+which would make the broom package available in your new
+Docker image.
 
    • 
-ENTRYPOINT is the command to run when starting the image. rstudio/plumber specifies an entrypoint that starts R, plumb()s a file, then run()s the router. If you want to change how plumber starts, or run some extra commands (like add a global processor) before you run the router, you’ll need to provide a custom ENTRYPOINT.
      • 
+ENTRYPOINT is the command to run when starting the
+image. rstudio/plumber specifies an entrypoint that starts
+R, plumb()s a file, then run()s the router. If
+you want to change how plumber starts, or run some extra commands (like
+add a global processor) before you run the router, you’ll need to
+provide a custom ENTRYPOINT.
 
    • 
-CMD these are the default arguments to provide to ENTRYPOINT. rstudio/plumber uses only the first argument as the name of the file that you want to plumb().
      • 
+CMD these are the default arguments to provide to
+ENTRYPOINT. rstudio/plumber uses only the
+first argument as the name of the file that you want to
+plumb().
 
    
 
    So your custom Dockerfile could be as simple as:
    
 
    FROM rstudio/plumber
@@ -183,45 +306,86 @@ 
    Custom Dockerfiles
    
-
    This Dockerfile would just extend the rstudio/plumber image in two ways. First, it RUNs one additional command to install the broom package. Second, it customizes the default CMD argument that will be used when running the image. In this case, you would be expected to mount a Plumber application into the container at /app/plumber.R
    
-
    You could then build your custom Docker image from this Dockerfile using the command docker build -t mycustomdocker . (where . – the current directory – is the directory where that Dockerfile is stored).
    
-
    Then you’d be able to use docker run --rm -vpwd:/app mycustomdocker to run your custom image, passing in your application’s directory as a volume mounted at /app.
    
+
    This Dockerfile would just extend the rstudio/plumber
+image in two ways. First, it RUNs one additional command to
+install the broom package. Second, it customizes the
+default CMD argument that will be used when running the
+image. In this case, you would be expected to mount a Plumber
+application into the container at /app/plumber.R
    
+
    You could then build your custom Docker image from this Dockerfile
+using the command docker build -t mycustomdocker . (where
+. – the current directory – is the directory where that
+Dockerfile is stored).
    
+
    Then you’d be able to use
+docker run --rm -vpwd:/app mycustomdocker to
+run your custom image, passing in your application’s directory as a
+volume mounted at /app.
    
 
    
 
    
 
    Automatically Run on Restart
 
    
-
    If you want your container to start automatically when your machine is booted, you can use the --restart parameter for docker run.
    
-
    docker run -p 1234:8000 -dit --restart=unless-stopped myCustomDocker would run the custom image you created above automatically every time your machine boots and expose the plumber service on port 1234 of your host machine, unless the container is explicitly stopped. Like all other hosting options, you’ll need to make sure that your firewall allows connections on port 1234 if you want others to be able to access your service.
    
+
    If you want your container to start automatically when your machine
+is booted, you can use the --restart parameter for
+docker run.
    
+
    docker run -p 1234:8000 -dit --restart=unless-stopped myCustomDocker
+would run the custom image you created above automatically every time
+your machine boots and expose the plumber service on port
+1234 of your host machine, unless the container is
+explicitly stopped. Like all other hosting options, you’ll need to make
+sure that your firewall allows connections on port 1234 if
+you want others to be able to access your service.
    
 
    
 
    
 
    
 
    Docker (Advanced)
 
    
-
    If you already have a basic Docker instance running, you may be interested in more advanced configurations capable of hosting multiple plumber applications on a single server and even load-balancing across multiple plumber processes.
    
-
    In order to coordinate and run multiple Plumber processes on one server, you should install docker-compose on your system. This is not included with some installations of Docker, so you will need to follow these instructions if you are not currently able to run docker-compose on the command-line. Docker Compose helps orchestrate multiple Docker containers. If you’re planning to run more than one Plumber process, you’ll want to use Docker Compose to keep them all alive and route traffic between them.
    
+
    If you already have a basic Docker instance
+running, you may be interested in more advanced configurations capable
+of hosting multiple plumber applications on a single server and even
+load-balancing across multiple plumber processes.
    
+
    In order to coordinate and run multiple Plumber processes on one
+server, you should install docker-compose on your
+system. This is not included with some installations of Docker,
+so you will need to follow these
+instructions if you are not currently able to run
+docker-compose on the command-line. Docker Compose helps
+orchestrate multiple Docker containers. If you’re planning to run more
+than one Plumber process, you’ll want to use Docker Compose to keep them
+all alive and route traffic between them.
    
 
    
 
    Multiple Plumber Applications
 
    
-
    We’ll use Docker Compose to help us organize multiple Plumber processes. We won’t go into detail about how to use Docker Compose, so if you’re new you should familiarize yourself using the official docs.
    
-
    You should define a Docker Compose configuration that defines the behavior of every Plumber application that you want to run. You’ll first want to setup a Dockerfile that defines the desired behavior for each of your applications (as we outlined previously. You could use a docker-compose.yml configuration like the following:
    
-
    services:
-  app1:
-    build: ./app1/
-    volumes:
-     - ./data:/data
-     - ./app1:/app
-    restart: always
-    ports:
-     - "7000:8000"
-  app2:
-    image: rstudio/plumber
-    command: /app/plumber.R
-    volumes:
-     - ../app2:/app
-    restart: always
-    ports:
-     - "7001:8000"
    
-
    More detail on what each of these options does and what other options exist can be found here. This configuration defines two Docker containers that should run app1 and app2. The associated files in this case are laid out on disk as follows:
    
+
    We’ll use Docker Compose to help us organize multiple Plumber
+processes. We won’t go into detail about how to use Docker Compose, so
+if you’re new you should familiarize yourself using the official docs.
    
+
    You should define a Docker Compose configuration that defines the
+behavior of every Plumber application that you want to run. You’ll first
+want to setup a Dockerfile that defines the desired behavior for each of
+your applications (as we outlined
+previously. You could use a docker-compose.yml
+configuration like the following:
    
+
    services:
+  app1:
+    build: ./app1/
+    volumes:
+     - ./data:/data
+     - ./app1:/app
+    restart: always
+    ports:
+     - "7000:8000"
+  app2:
+    image: rstudio/plumber
+    command: /app/plumber.R
+    volumes:
+     - ../app2:/app
+    restart: always
+    ports:
+     - "7001:8000"
    
+
    More detail on what each of these options does and what other options
+exist can be found here. This
+configuration defines two Docker containers that should run
+app1 and app2. The associated files in this
+case are laid out on disk as follows:
    
 
    docker-compose.yml
 app1
 ├── Dockerfile
@@ -230,27 +394,63 @@ 
    Multiple Plumber Applicationsplumb(). So we merely use the default plumber Docker image as its image, and then customize the command to specify where the Plumber API definition can be found in the container. Since we’re mapping our host’s ./app2 to /app inside of the container, the definition would be found in /app/plumber.R. We specify that it should always restart if anything ever happens to the container, and we export port 8000 from the container to port 7001 on the host.
    
-
    app1 is our more complicated app. It has some extra data in another directory that needs to be loaded, and it has a custom Dockerfile. This could be because it has additional R packages or system dependencies that it requires.
    
-
    If you now run docker-compose up, Docker Compose will build the referenced images in your config file and then run them. You’ll find that app1 is available on port 7000 of the machine running Docker Compose, and app2 is available on port 7001. If you want these APIs to run in the background and survive restarts of your server, you can use the -d switch just like with docker run.
    
+
    You can see that app2 is the simpler of the two apps; it just has the
+plumber definition that should be run through plumb(). So
+we merely use the default plumber Docker image as its
+image, and then customize the command to
+specify where the Plumber API definition can be found in the container.
+Since we’re mapping our host’s ./app2 to /app
+inside of the container, the definition would be found in
+/app/plumber.R. We specify that it should
+always restart if anything ever happens to the container,
+and we export port 8000 from the container to port
+7001 on the host.
    
+
    app1 is our more complicated app. It has some extra data
+in another directory that needs to be loaded, and it has a custom
+Dockerfile. This could be because it has additional R packages or system
+dependencies that it requires.
    
+
    If you now run docker-compose up, Docker Compose will
+build the referenced images in your config file and then run them.
+You’ll find that app1 is available on port
+7000 of the machine running Docker Compose, and
+app2 is available on port 7001. If you want
+these APIs to run in the background and survive restarts of your server,
+you can use the -d switch just like with
+docker run.
    
 
    
 
    
 
    Multiple Applications on One Port
 
    
-
    It may desirable to run all of your Plumber services on a standard port like 80 (for HTTP) or 443 (for HTTPS). In that case, you’d prefer to have a router running on port 80 that can send traffic to the appropriate Plumber API by distinguishing based on a path prefix. Requests for myserver.com/app1/ could be sent to the app1 container, and myserver.org/app2/ could target the app2 container, but both paths would be available on port 80 on your server.
    
-
    In order to do this, we can use another Docker container running nginx which is configured to route traffic between the two Plumber containers. We’d add the following entry to our docker-compose.yml below the app containers we already have defined.
    
-
      nginx:
-    image: nginx:1.9
-    ports:
-     - "80:80"
-    volumes:
-     - ./nginx.conf:/etc/nginx/nginx.conf:ro
-    restart: always
-    depends_on:
-     - app1
-     - app2
    
-
    This uses the nginx Docker image that will be downloaded for you. In order to run nginx in a meaningful way, we have to provide a configuration file and place it in /etc/nginx/nginx.conf, which we do by mounting a local file at that location on the container.
    
-
    A basic nginx config file could look something like the following:
    
+
    It may desirable to run all of your Plumber services on a standard
+port like 80 (for HTTP) or 443 (for HTTPS). In
+that case, you’d prefer to have a router running on port 80
+that can send traffic to the appropriate Plumber API by distinguishing
+based on a path prefix. Requests for myserver.com/app1/
+could be sent to the app1 container, and
+myserver.org/app2/ could target the app2
+container, but both paths would be available on port 80 on your
+server.
    
+
    In order to do this, we can use another Docker container running nginx which is configured to route
+traffic between the two Plumber containers. We’d add the following entry
+to our docker-compose.yml below the app containers we
+already have defined.
    
+
      nginx:
+    image: nginx:1.9
+    ports:
+     - "80:80"
+    volumes:
+     - ./nginx.conf:/etc/nginx/nginx.conf:ro
+    restart: always
+    depends_on:
+     - app1
+     - app2
    
+
    This uses the nginx Docker image that will be downloaded for you. In
+order to run nginx in a meaningful way, we have to provide a
+configuration file and place it in /etc/nginx/nginx.conf,
+which we do by mounting a local file at that location on the
+container.
    
+
    A basic nginx config file could look something like the
+following:
    
 
    events {
   worker_connections  4096;  ## Default: 1024
 }
@@ -286,76 +486,198 @@ 
    Multiple Applications on One Port
    
-
    You should set the server_name parameter above to be whatever the public address is of your server. You can save this file as nginx.conf in the same directory as your Compose config file.
    
-
    Docker Compose is intelligent enough to know to route traffic for http://app1:8000/ to the app1 container, port 8000, so we can leverage that in our config file. Docker containers are able to contact each other on their non-public ports, so we can go directly to port 8000 for both containers. This proxy configuration will trim the prefix off of the request before it sends it on to the applications, so your applications don’t need to know anything about being hosted publicly at a URL that includes the /app1/ or /app2/ prefixes.
    
-
    We should also get rid of the previous port mappings to ports 7000 and 7001 on our other applications, as we don’t want to expose our APIs on those ports anymore.
    
-
    If you now run docker compose up again, you’ll see your two application servers running but now have a new nginx server running, as well. And you’ll find that if you visit your server on port 80, you’ll see the “welcome to Nginx!” page. If you access /app1 you’ll be sent to app1 just like we had hoped.
    
+
    You should set the server_name parameter above to be
+whatever the public address is of your server. You can save this file as
+nginx.conf in the same directory as your Compose config
+file.
    
+
    Docker Compose is intelligent enough to know to route traffic for
+http://app1:8000/ to the app1 container, port
+8000, so we can leverage that in our config file. Docker
+containers are able to contact each other on their non-public ports, so
+we can go directly to port 8000 for both containers. This
+proxy configuration will trim the prefix off of the request before it
+sends it on to the applications, so your applications don’t need to know
+anything about being hosted publicly at a URL that includes the
+/app1/ or /app2/ prefixes.
    
+
    We should also get rid of the previous port mappings to ports
+7000 and 7001 on our other applications, as we
+don’t want to expose our APIs on those ports anymore.
    
+
    If you now run docker compose up again, you’ll see your
+two application servers running but now have a new nginx server running,
+as well. And you’ll find that if you visit your server on port 80,
+you’ll see the “welcome to Nginx!” page. If you access
+/app1 you’ll be sent to app1 just like we had
+hoped.
    
 
    
 
    
 
    Load Balancing
 
    
-
    If you’re expecting a lot of traffic on one application or have an API that’s particularly computationally complex, you may want to distribute the load across multiple R processes running the same Plumber application. Thankfully, we can use Docker Compose for this, as well.
    
-
    First, we’ll want to create multiple instances of the same application. This is easily accomplished with the docker-compose scale command. You simply run docker-compose scale app1=3 to run three instances of app1. Now we just need to load balance traffic across these three instances.
    
-
    You could setup the nginx configuration that we already have to balance traffic across this pool of workers, but you would need to manually re-configure and update your nginx instance every time that you need to scale the number up or down, which might be a hassle. Luckily, there’s a more elegant solution.
    
-
    We can use the dockercloud/haproxy Docker image to automatically balance HTTP traffic across a pool of workers. This image is intelligent enough to listen for workers in your pool arriving or leaving and will automatically remove/add these containers into their pool. Let’s add a new container into our configuration that defines this load balancer
    
-
      lb:
-    image: 'dockercloud/haproxy:1.2.1'
-    links:
-     - app1
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock
    
-
    The trick that allows this image to listen in to our scaling of app1 is by passing in the docker socket as a shared volume. Note that this particular arrangement will differ based on your host OS. The above configuration is intended for Linux, but MacOS X users would require a slightly different config.
    
-
    We could export port 80 of our new load balancer to port 80 of our host machine if we solely wanted to load-balance a single application. Alternatively, we can actually use both nginx (to handle the routing of various applications) and HAProxy (to handle the load balancing of a particular application). To do that, we’d merely add a new location block to our nginx.conf file that knows how to send traffic to HAProxy, or modify the existing location block to send traffic to the load balancer instead of going directly to the application.
    
+
    If you’re expecting a lot of traffic on one application or have an
+API that’s particularly computationally complex, you may want to
+distribute the load across multiple R processes running the same Plumber
+application. Thankfully, we can use Docker Compose for this, as
+well.
    
+
    First, we’ll want to create multiple instances of the same
+application. This is easily accomplished with the
+docker-compose scale command. You simply run
+docker-compose scale app1=3 to run three instances of
+app1. Now we just need to load balance traffic across these
+three instances.
    
+
    You could setup the nginx configuration that we already have to
+balance traffic across this pool of workers, but you would need to
+manually re-configure and update your nginx instance every time that you
+need to scale the number up or down, which might be a hassle. Luckily,
+there’s a more elegant solution.
    
+
    We can use the dockercloud/haproxy
+Docker image to automatically balance HTTP traffic across a pool of
+workers. This image is intelligent enough to listen for workers in your
+pool arriving or leaving and will automatically remove/add these
+containers into their pool. Let’s add a new container into our
+configuration that defines this load balancer
    
+
      lb:
+    image: 'dockercloud/haproxy:1.2.1'
+    links:
+     - app1
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
    
+
    The trick that allows this image to listen in to our scaling of
+app1 is by passing in the docker socket as a shared volume.
+Note that this particular arrangement will differ based on your host OS.
+The above configuration is intended for Linux, but MacOS X users would
+require a slightly
+different config.
    
+
    We could export port 80 of our new load balancer to port
+80 of our host machine if we solely wanted to load-balance
+a single application. Alternatively, we can actually use both nginx (to
+handle the routing of various applications) and HAProxy (to handle the
+load balancing of a particular application). To do that, we’d merely add
+a new location block to our nginx.conf file
+that knows how to send traffic to HAProxy, or modify the existing
+location block to send traffic to the load balancer instead
+of going directly to the application.
    
 
    So the location /app1/ block becomes:
    
 
    location /app1/ {
   proxy_pass http://lb/;
   proxy_set_header Host $host;
 }
    
-
    Where lb is the name of the HAProxy load balancer that we defined in our Compose configuration.
    
-
    The next time you start/redeploy your Docker Compose cluster, you’ll be balancing your incoming requests to /app1/ across a pool of 1 or more R processes based on whatever you’ve set the scale to be for that application.
    
-
    Do keep in mind that when using load-balancing that it’s not longer guaranteed that subsequent requests for a particular application will land on the same process. This means that if you maintain any state in your Plumber application (like a global counter, or a user’s session state), you can’t expect that to be shared across the processes that the user might encounter. There are at least three possible solutions to this problem:
    
+
    Where lb is the name of the HAProxy load balancer that
+we defined in our Compose configuration.
    
+
    The next time you start/redeploy your Docker Compose cluster, you’ll
+be balancing your incoming requests to /app1/ across a pool
+of 1 or more R processes based on whatever you’ve set the
+scale to be for that application.
    
+
    Do keep in mind that when using load-balancing that it’s not longer
+guaranteed that subsequent requests for a particular application will
+land on the same process. This means that if you maintain any state in
+your Plumber application (like a global counter, or a user’s session
+state), you can’t expect that to be shared across the processes that the
+user might encounter. There are at least three possible solutions to
+this problem:
    
 
      
-
    1. Use a more robust means of maintaining state. You could put the state in a database, for instance, that lives outside of your R processes and your Plumber processes could get and save their state externally.
      2. 
-
    2. You could serialize the state to the user using (encrypted) session cookies, assuming it’s small enough. In this scenario, your workers would write data back to the user in the form of a cookie, then the user would include that same cookie in its subsequent requests. This works best if the state is going to be set rarely and read often (for instance, the cookie could be set when the user logs in, then read on each request to detect the identity of this user).
      3. 
-
    3. You can enable “sticky sessions” in the HAProxy load balancer. This would ensure that each user’s traffic always gets routed to the same worker. The downside of this approach is that it will distribute traffic less evenly. You could end up in a situation in which you have 2 R processes for an application but 90% of your traffic is hitting one of them if it happens the users triggering the majority of the requests are all “stuck” to one particular worker.
      4. 
+
    4. Use a more robust means of maintaining state. You could put the
+state in a database, for instance, that lives outside of your R
+processes and your Plumber processes could get and save their state
+externally.
      5. 
+
    5. You could serialize the state to the user using (encrypted) session
+cookies, assuming it’s small enough. In this scenario, your workers
+would write data back to the user in the form of a cookie, then the user
+would include that same cookie in its subsequent requests. This works
+best if the state is going to be set rarely and read often (for
+instance, the cookie could be set when the user logs in, then read on
+each request to detect the identity of this user).
      6. 
+
    6. You can enable “sticky sessions” in the HAProxy load balancer. This
+would ensure that each user’s traffic always gets routed to the same
+worker. The downside of this approach is that it will distribute traffic
+less evenly. You could end up in a situation in which you have 2 R
+processes for an application but 90% of your traffic is hitting one of
+them if it happens the users triggering the majority of the requests are
+all “stuck” to one particular worker.
      7. 
 
    
 
    
 
    
 
    
 
    pm2
 
    
-
    If you don’t have the luxury of running your Plumber instance on a designated server (as is discussed in the DigitalOcean section) and you’re not comfortable hosting the API in Docker, then you’ll need to find a way to run and manage your Plumber APIs on your server directly.
    
-
    There are a variety of tools that were built to help manage web hosting in a single-threaded environment like R. Some of the most compelling tools were developed around Ruby (like Phusion Passenger) or Node.js (like Node Supervisor, forever or pm2). Thankfully, many of these tools can be adapted to support managing an R process running a Plumber API.
    
-
    pm2 is a process manager initially targeting Node.js. Here we’ll show the commands needed to do this in Ubuntu 14.04, but you can use any Operating System or distribution that is supported by pm2. At the end, you’ll have a server that automatically starts your plumber services when booted, restarts them if they ever crash, and even centralizes the logs for your plumber services.
    
+
    If you don’t have the luxury of running your Plumber instance on a
+designated server (as is discussed in the DigitalOcean section) and you’re not
+comfortable hosting the API in Docker, then you’ll
+need to find a way to run and manage your Plumber APIs on your server
+directly.
    
+
    There are a variety of tools that were built to help manage web
+hosting in a single-threaded environment like R. Some of the most
+compelling tools were developed around Ruby (like Phusion Passenger) or
+Node.js (like Node
+Supervisor, forever or pm2). Thankfully, many of these
+tools can be adapted to support managing an R process running a Plumber
+API.
    
+
    pm2 is a process manager
+initially targeting Node.js. Here we’ll show the commands needed to do
+this in Ubuntu 14.04, but you can use any Operating System or
+distribution that is supported by pm2. At the end, you’ll have a server
+that automatically starts your plumber services when booted, restarts
+them if they ever crash, and even centralizes the logs for your plumber
+services.
    
 
    
 
    Server Deployment and Preparation
 
    
-
    The first thing you’ll need to do, regardless of which process manager you choose, is to deploy the R files containing your plumber applications to the server where they’ll be hosted. Keep in mind that you’ll also need to include any supplemental R files that are source()d in your plumber file, and any other datasets or dependencies that your files have.
    
-
    You’ll also need to make sure that the R packages you need (and the appropriate versions) are available on the remote server. You can either do this manually by installing those packages or you can consider using a tool like Packrat to help with this.
    
-
    There are a myriad of features in pm2 that we won’t cover here. It is a good idea to spend some time reading through their documentation to see which features might be of interest to you and to ensure that you understand all the implications of how pm2 hosts services (which user you want to run your processes as, etc.). Their quick-start guide may be especially relevant. For the sake of simplicity, we will do a basic installation here without customizing many of those options.
    
+
    The first thing you’ll need to do, regardless of which process
+manager you choose, is to deploy the R files containing your plumber
+applications to the server where they’ll be hosted. Keep in mind that
+you’ll also need to include any supplemental R files that are
+source()d in your plumber file, and any other datasets or
+dependencies that your files have.
    
+
    You’ll also need to make sure that the R packages you need (and the
+appropriate versions) are available on the remote server. You can either
+do this manually by installing those packages or you can consider using
+a tool like Packrat to
+help with this.
    
+
    There are a myriad of features in pm2 that we won’t cover here. It is
+a good idea to spend some time reading through their documentation to
+see which features might be of interest to you and to ensure that you
+understand all the implications of how pm2 hosts services (which user
+you want to run your processes as, etc.). Their quick-start
+guide may be especially relevant. For the sake of simplicity, we
+will do a basic installation here without customizing many of those
+options.
    
 
    
 
    
 
    Install pm2
 
    
-
    Now you’re ready to install pm2. pm2 is a package that’s maintained in npm (Node.js’s package management system); it also requires Node.js in order to run. So to start you’ll want to install Node.js. On Ubuntu 14.04, the necessary commands are:
    
-
    sudo apt-get update
-sudo apt-get install nodejs npm
    
-
    Once you have npm and Node.js installed, you’re ready to install pm2.
    
+
    Now you’re ready to install pm2. pm2 is a package that’s maintained
+in npm (Node.js’s package management system); it also
+requires Node.js in order to run. So to start you’ll want to install
+Node.js. On Ubuntu 14.04, the necessary commands are:
    
+
    sudo apt-get update
+sudo apt-get install nodejs npm
    
+
    Once you have npm and Node.js installed, you’re ready to install
+pm2.
    
 
    sudo npm install -g pm2
    
-
    If you find errors like SSL Error: CERT_UNTRUSTED while using npm command, you can bypass the ssl error using:
    
+
    If you find errors like SSL Error: CERT_UNTRUSTED while
+using npm command, you can bypass the ssl error using:
    
 
    npm config set strict-ssl false
    
-
    or set the registry URL from https:// to http://:
    
+
    or set the registry URL from https:// to
+http://:
    
 
    npm config set registry="http://registry.npmjs.org/"
    
-
    This will install pm2 globally (-g) on your server, meaning you should now be able to run pm2 --version and get the version number of pm2 that you’ve installed.
    
-
    In order to get pm2 to startup your services on boot, you should run sudo pm2 startup which will create the necessary files for your system to run pm2 when you boot your machine.
    
+
    This will install pm2 globally (-g) on your server,
+meaning you should now be able to run pm2 --version and get
+the version number of pm2 that you’ve installed.
    
+
    In order to get pm2 to startup your services on boot, you should run
+sudo pm2 startup which will create the necessary files for
+your system to run pm2 when you boot your machine.
    
 
    
 
    
 
    Wrap Your Plumber File
 
    
-
    Once you’ve deployed your Plumber files onto the server, you’ll still need to tell the server how to run your server. You’re probably used to running commands like
    
+
    Once you’ve deployed your Plumber files onto the server, you’ll still
+need to tell the server how to run your server. You’re probably
+used to running commands like
    
 
     pr("myfile.R") %>% pr_run(port=4500)
    
-
    Unfortunately, pm2 doesn’t understand R scripts natively; however, it is possible to specify a custom interpreter. We can use this feature to launch an R-based wrapper for our plumber file using the Rscript scripting front-end that comes with R. The following script will run the two commands listed above.
    
+
    Unfortunately, pm2 doesn’t understand R scripts natively; however, it
+is possible to specify a custom interpreter. We can use this feature to
+launch an R-based wrapper for our plumber file using the
+Rscript scripting front-end that comes with R. The
+following script will run the two commands listed above.
    
 
    #!/usr/bin/env Rscript
 
 library(plumber)
@@ -363,44 +685,114 @@ 
    Wrap Your Plumber File  pr_run(port=4000, host="0.0.0.0")
 # Setting the host option on a VM instance ensures the application can be accessed externally.
 # (This may be only true for Linux users.)
    
-
    Save this R script on your server as something like run-myfile.R. You should also make it executable by changing the permissions on the file using a command like chmod 755 run-myfile.R. You should now execute that file to make sure that it runs the service like you expect. You should be able to make requests to your server on the appropriate port and have the plumber service respond. You can kill the process using Ctrl-c when you’re convinced that it’s working. Make sure the shell script is in a permanent location so that it won’t be erased or modified accidentally. You can consider creating a designated directory for all your plumber services in some directory like /usr/local/plumber, then put all services and their associated Rscript-runners in their own subdirectory like /usr/local/plumber/myfile/.
    
+
    Save this R script on your server as something like
+run-myfile.R. You should also make it executable by
+changing the permissions on the file using a command like
+chmod 755 run-myfile.R. You should now execute that file to
+make sure that it runs the service like you expect. You should be able
+to make requests to your server on the appropriate port and have the
+plumber service respond. You can kill the process using
+Ctrl-c when you’re convinced that it’s working. Make sure
+the shell script is in a permanent location so that it won’t be erased
+or modified accidentally. You can consider creating a designated
+directory for all your plumber services in some directory like
+/usr/local/plumber, then put all services and their
+associated Rscript-runners in their own subdirectory like
+/usr/local/plumber/myfile/.
    
 
    
 
    
 
    Introduce Our Service to pm2
 
    
-
    We’ll now need to teach pm2 about our Plumber API so that we can put it to work. You can register and configure any number of services with pm2; let’s start with our myfile Plumber service.
    
-
    You can use the pm2 list command to see which services pm2 is already running. If you run this command now, you’ll see that pm2 doesn’t have any services that it’s in charge of. Once you have the scripts and code stored in the directory where you want them, use the following command to tell pm2 about your service.
    
-
    pm2 start --interpreter="Rscript" /usr/local/plumber/myfile/run-myfile.R
    
-
    You should see some output about pm2 starting an instance of your service, followed by some status information from pm2. If everything worked properly, you’ll see that your new service has been registered and is running. You can see this same output by executing pm2 list again.
    
-
    Once you’re happy with the pm2 services you have defined, you can use pm2 save to tell pm2 to retain the set of services you have running next time you boot the machine. All of the services you have defined will be automatically restarted for you.
    
-
    At this point, you have a persistent pm2 service created for your Plumber application. This means that you can reboot your server, or find and kill the underlying R process that your plumber application is using and pm2 will automatically bring a new process in to replace it. This should help guarantee that you always have a Plumber process running on the port number you specified in the shell script. It is a good idea to reboot the server to ensure that everything comes back the way you expected.
    
-
    You can repeat this process with all the plumber applications you want to deploy, as long as you give each a unique port to run on. Remember that you can’t have more than one service running on a single port. And be sure to pm2 save every time you add services that you want to survive a restart.
    
-
    Run netstat -tulpn to see how the application is being ran. If you see the application on host 127.0.0.0 or 127.0.0.1, the application cannot be accessed externally. You should change the host parameter to 0.0.0.0, for example: `pr_run(host = “0.0.0.0”).
    
+
    We’ll now need to teach pm2 about our Plumber API so that we can put
+it to work. You can register and configure any number of services with
+pm2; let’s start with our myfile Plumber service.
    
+
    You can use the pm2 list command to see which services
+pm2 is already running. If you run this command now, you’ll see that pm2
+doesn’t have any services that it’s in charge of. Once you have the
+scripts and code stored in the directory where you want them, use the
+following command to tell pm2 about your service.
    
+
    pm2 start --interpreter="Rscript" /usr/local/plumber/myfile/run-myfile.R
    
+
    You should see some output about pm2 starting an instance of your
+service, followed by some status information from pm2. If everything
+worked properly, you’ll see that your new service has been registered
+and is running. You can see this same output by executing
+pm2 list again.
    
+
    Once you’re happy with the pm2 services you have defined, you can use
+pm2 save to tell pm2 to retain the set of services you have
+running next time you boot the machine. All of the services you have
+defined will be automatically restarted for you.
    
+
    At this point, you have a persistent pm2 service created for your
+Plumber application. This means that you can reboot your server, or find
+and kill the underlying R process that your plumber application is using
+and pm2 will automatically bring a new process in to replace it. This
+should help guarantee that you always have a Plumber process running on
+the port number you specified in the shell script. It is a good idea to
+reboot the server to ensure that everything comes back the way you
+expected.
    
+
    You can repeat this process with all the plumber applications you
+want to deploy, as long as you give each a unique port to run on.
+Remember that you can’t have more than one service running on a single
+port. And be sure to pm2 save every time you add services
+that you want to survive a restart.
    
+
    Run netstat -tulpn to see how the application is being
+ran. If you see the application on host 127.0.0.0 or
+127.0.0.1, the application cannot be accessed externally.
+You should change the host parameter to 0.0.0.0, for
+example: `pr_run(host = “0.0.0.0”).
    
 
    
 
    
 
    Logs and Management
 
    
-
    Now that you have your applications defined in pm2, you may want to drill down into them to manage or debug them. If you want to see more information, use the pm2 show command and specify the name of the application from pm2 list. This is usually the same as the name of the shell script you specified, so it may be something like pm2 show run-myfile.
    
-
    You can peruse this information but keep an eye on the restarts count for your applications. If your application has had to restart many times, that implies that the process is crashing often, which is a sign that there’s a problem in your code.
    
-
    Thankfully, pm2 automatically manages the log files from your underlying processes. If you ever need to check the log files of a service, you can just run pm2 logs run-myfile, where myfile is again the name of the service obtained from pm2 list. This command will show you the last few lines logged from your process, and then begin streaming any incoming log lines until you exit (Ctrl-c).
    
-
    If you want a big-picture view of the health of your server and all the pm2 services, you can run pm2 monit which will show you a dashboard of the RAM and CPU usage of all your services.
    
+
    Now that you have your applications defined in pm2, you may want to
+drill down into them to manage or debug them. If you want to see more
+information, use the pm2 show command and specify the name
+of the application from pm2 list. This is usually the same
+as the name of the shell script you specified, so it may be something
+like pm2 show run-myfile.
    
+
    You can peruse this information but keep an eye on the
+restarts count for your applications. If your application
+has had to restart many times, that implies that the process is crashing
+often, which is a sign that there’s a problem in your code.
    
+
    Thankfully, pm2 automatically manages the log files from your
+underlying processes. If you ever need to check the log files of a
+service, you can just run pm2 logs run-myfile, where
+myfile is again the name of the service obtained from
+pm2 list. This command will show you the last few lines
+logged from your process, and then begin streaming any incoming log
+lines until you exit (Ctrl-c).
    
+
    If you want a big-picture view of the health of your server and all
+the pm2 services, you can run pm2 monit which will show you
+a dashboard of the RAM and CPU usage of all your services.
    
 
    
 
    
 
    
 
    systemd
 
    
 
    
-
    systemd is the service manager used by certain Linux distributions including RedHat/CentOS 7, SUSE 12, and Ubuntu versions 16.04 and later.
    
+
    systemd is the service manager used by certain Linux
+distributions including RedHat/CentOS 7, SUSE 12, and Ubuntu versions
+16.04 and later.
    
 
    
-
    If you use a Linux server you can use systemd to run Plumber as a service that can be accessed from your local network or even outside your network depending on your firewall rules. This option is similar to using the Docker method. One of the main advantages of using systemd over using Docker is that systemd won’t bypass firewall rules (Docker does!) and avoids the overhead of running a container.
    
-
    Compared to plumber::do_provision() this option won’t create a new droplet if you use DigitalOcean; it will run on your existing droplet instead.
    
-
    To implement this option you’ll complete the following three steps from the terminal:
    
+
    If you use a Linux server you can use systemd to run
+Plumber as a service that can be accessed from your local network or
+even outside your network depending on your firewall rules. This option
+is similar to using the Docker method. One of the
+main advantages of using systemd over using Docker is that
+systemd won’t bypass firewall rules (Docker does!) and
+avoids the overhead of running a container.
    
+
    Compared to plumber::do_provision() this option won’t
+create a new droplet if you use DigitalOcean; it will run on your existing
+droplet instead.
    
+
    To implement this option you’ll complete the following three steps
+from the terminal:
    
 
      
-
    1. Verify that you have the plumber package available globally on the server:
      2. 
+
    2. Verify that you have the plumber package available
+globally on the server:
      3. 
 
    
 
    R -e 'install.packages("plumber", repos = "https://cran.rstudio.com/")'
    
 
      
-
    1. Run sudo nano /etc/systemd/system/plumber-api.service, then paste and adapt this content:
      2. 
+
    2. Run sudo nano /etc/systemd/system/plumber-api.service,
+then paste and adapt this content:
      3. 
 
    
 
    [Unit]
 Description=Plumber API
@@ -415,11 +807,14 @@ 
    systemd
    
 
      
-
    1. Activate the service (for auto-start on power/reboot) and start it:
      2. 
+
    2. Activate the service (for auto-start on power/reboot) and start
+it:
      3. 
 
    
 
    sudo systemctl enable plumber-api  # automatically start the service when the server boots
 sudo systemctl start plumber-api   # start the service right now
    
-
    To check if your API is running, type systemctl | grep running in the terminal and should display plumber-api.service \ loaded active running Plumber API.
    
+
    To check if your API is running, type
+systemctl | grep running in the terminal and should display
+plumber-api.service \ loaded active running Plumber API.
    
 
    
   
    
diff --git a/articles/hosting_files/accessible-code-block-0.0.1/empty-anchor.js b/articles/hosting_files/accessible-code-block-0.0.1/empty-anchor.js
deleted file mode 100644
index ca349fd6a..000000000
--- a/articles/hosting_files/accessible-code-block-0.0.1/empty-anchor.js
+++ /dev/null
@@ -1,15 +0,0 @@
-// Hide empty  tag within highlighted CodeBlock for screen reader accessibility (see https://github.com/jgm/pandoc/issues/6352#issuecomment-626106786) -->
-// v0.0.1
-// Written by JooYoung Seo (jooyoung@psu.edu) and Atsushi Yasumoto on June 1st, 2020.
-
-document.addEventListener('DOMContentLoaded', function() {
-  const codeList = document.getElementsByClassName("sourceCode");
-  for (var i = 0; i < codeList.length; i++) {
-    var linkList = codeList[i].getElementsByTagName('a');
-    for (var j = 0; j < linkList.length; j++) {
-      if (linkList[j].innerHTML === "") {
-        linkList[j].setAttribute('aria-hidden', 'true');
-      }
-    }
-  }
-});
diff --git a/articles/index.html b/articles/index.html
index 4d5b6bd7f..c5d70f1b0 100644
--- a/articles/index.html
+++ b/articles/index.html
@@ -1,5 +1,5 @@
 
-Articles • plumberArticles • plumber
diff --git a/articles/introduction.html b/articles/introduction.html
index 8c0abc386..5dab9939a 100644
--- a/articles/introduction.html
+++ b/articles/introduction.html
@@ -15,8 +15,8 @@
 
 
 
-
-
+
+
 
 
 
@@ -93,7 +93,8 @@ 
    Releases
    
 
 
 
-
    
+
+
    
   
    
       
    Introduction
    
             
@@ -104,7 +105,13 @@ 
    Releases
    
 
     
     
-
    The R Programming Language has become one of the most dominant programming languages for data analysis and visualization in recent years. At the same time, web services have become a common language for allowing various systems to interact with one another. The plumber R package allows users to expose existing R code as a service available to others on the Web. Plumber is best illustrated with an example:
    
+
    The R Programming Language
+has become one of the most dominant programming languages for data
+analysis and visualization in recent years. At the same time, web
+services have become a common language for allowing various systems to
+interact with one another. The plumber R package allows
+users to expose existing R code as a service available to others on the
+Web. Plumber is best illustrated with an example:
    
 
     # plumber.R
 
@@ -132,18 +139,48 @@ 
    Releases
    
   plot(myData$Sepal.Length, myData$Petal.Length,
        main=title, xlab="Sepal Length", ylab="Petal Length")
 }
    
-
    Even without knowing R, you can probably get a rough idea for what the above Plumber API will do. The first function above defines the /echo endpoint which simply echoes back the text that it was sent. The second function generates a plot based on Edgar Anderson’s famous Iris Dataset; it includes a filter that allows the caller to subset the dataset to a particular species.
    
-
    Plumber makes use of these comment “annotations” above your functions to define the web service. When you feed the above file into Plumber, you’ll get a runnable web service that other systems can interact with over a network.
    
+
    Even without knowing R, you can probably get a rough idea for what
+the above Plumber API will do. The first function above defines the
+/echo endpoint which simply echoes back the text that it
+was sent. The second function generates a plot based on Edgar Anderson’s
+famous Iris Dataset; it includes a filter that allows the caller to
+subset the dataset to a particular species.
    
+
    Plumber makes use of these comment “annotations” above your functions
+to define the web service. When you feed the above file into Plumber,
+you’ll get a runnable web service that other systems can interact with
+over a network.
    
 
    
 
    Web APIs
 
    
-
    The Hypertext Transfer Protocol (HTTP) is the dominant medium by which information is exchanged on the Internet. An Application Programming Interface (API) is a broad term that defines the rules that guide your interaction with some software. In the case of HTTP APIs, you have a defined set of endpoints that accept particular inputs. Plumber translates the annotations you place on your functions into an HTTP API that can be called from other machines on your network. If you execute your Plumber API on a public server, you can even make your API available to the public Internet.
    
-
    HTTP APIs have become the predominant language by which software communicates. By creating an HTTP API, you’ll empower your R code to be leveraged by other services – whether they’re housed inside your organization or hosted on the other side of the world. Here are just a few ideas of the doors that are opened to you when you wrap your R code in a Plumber API:
    
+
    The Hypertext Transfer Protocol (HTTP) is the dominant medium by
+which information is exchanged on the Internet. An Application
+Programming Interface (API) is a broad term that defines the rules that
+guide your interaction with some software. In the case of HTTP APIs, you
+have a defined set of endpoints that accept particular inputs. Plumber
+translates the annotations you place on your functions into an HTTP API
+that can be called from other machines on your network. If you execute
+your Plumber API on a public server, you can even make your API
+available to the public Internet.
    
+
    HTTP APIs have become the predominant language by which software
+communicates. By creating an HTTP API, you’ll empower your R code to be
+leveraged by other services – whether they’re housed inside your
+organization or hosted on the other side of the world. Here are just a
+few ideas of the doors that are opened to you when you wrap your R code
+in a Plumber API:
    
 
      
-
    • Software written in other languages in your organization can run your R code. Your company’s Java application could now pull in a custom ggplot2 graph that you generate on-demand, or a Python client could query a predictive model defined in R.
      • 
-
    • You can have some third-party receive emails on your behalf and then notify your Plumber service when new messages arrive.
      • 
-
    • You could register a “Slash Command” on Slack, enabling you to execute your R function in response to a command being entered in Slack.
      • 
-
    • You can write JavaScript code that queries your Plumber API from a visitor’s web browser. Even further, you could use Plumber exclusively as the back-end of an interactive web application.
      • 
+
    • Software written in other languages in your organization can run
+your R code. Your company’s Java application could now pull in a custom
+ggplot2 graph that you generate on-demand, or a Python client could
+query a predictive model defined in R.
      • 
+
    • You can have some third-party
+receive emails on your behalf and then notify your Plumber service when
+new messages arrive.
      • 
+
    • You could register a “Slash Command” on Slack,
+enabling you to execute your R function in response to a command being
+entered in Slack.
      • 
+
    • You can write JavaScript code that queries your Plumber API from a
+visitor’s web browser. Even further, you could use Plumber exclusively
+as the back-end of an interactive web application.
      • 
 
    
 
    
   
    
diff --git a/articles/introduction_files/accessible-code-block-0.0.1/empty-anchor.js b/articles/introduction_files/accessible-code-block-0.0.1/empty-anchor.js
deleted file mode 100644
index ca349fd6a..000000000
--- a/articles/introduction_files/accessible-code-block-0.0.1/empty-anchor.js
+++ /dev/null
@@ -1,15 +0,0 @@
-// Hide empty  tag within highlighted CodeBlock for screen reader accessibility (see https://github.com/jgm/pandoc/issues/6352#issuecomment-626106786) -->
-// v0.0.1
-// Written by JooYoung Seo (jooyoung@psu.edu) and Atsushi Yasumoto on June 1st, 2020.
-
-document.addEventListener('DOMContentLoaded', function() {
-  const codeList = document.getElementsByClassName("sourceCode");
-  for (var i = 0; i < codeList.length; i++) {
-    var linkList = codeList[i].getElementsByTagName('a');
-    for (var j = 0; j < linkList.length; j++) {
-      if (linkList[j].innerHTML === "") {
-        linkList[j].setAttribute('aria-hidden', 'true');
-      }
-    }
-  }
-});
diff --git a/articles/migration.html b/articles/migration.html
index 100e3e574..eb6146ac0 100644
--- a/articles/migration.html
+++ b/articles/migration.html
@@ -15,8 +15,8 @@
 
 
 
-
-
+
+
 
 
 
@@ -93,7 +93,8 @@ 
    Releases
    
 
 
 
-
    
+
+
    
   
    
       
    Migration Guide
    
             
@@ -107,15 +108,60 @@ 
    Releases
    
 
    
 
    Plumber 0.4.0 Migration Guide
 
    
-
    Plumber underwent a series of breaking changes as a part of the 0.4.0 release. These changes were made as an attempt to rectify some earlier mistakes and as an attempt to take care of all foreseeable breaking changes for the Plumber package.
    
-
    There are a number of changes that users should consider when preparing to upgrade to plumber 0.4.0.
    
+
    Plumber underwent a series of breaking changes as a part of the 0.4.0
+release. These changes were made as an attempt to rectify some earlier
+mistakes and as an attempt to take care of all foreseeable breaking
+changes for the Plumber package.
    
+
    There are a number of changes that users should consider when
+preparing to upgrade to plumber 0.4.0.
    
 
      
 
    1. 
-Plumber no longer accepts external connections by default. The host parameter for the run() method now defaults to 127.0.0.1, meaning that Plumber will only listen for incoming requests from the local machine on which it’s running – not from any other machine on the network. This is done for security reasons so that you don’t accidentally expose a Plumber API that you’re developing to your entire network. To restore the old behavior in which Plumber listened for connections from any machine on the network, use $run(host="0.0.0.0"). Note that if you’re deploying to an environment that includes an HTTP proxy (such as the DigitalOcean servers which use nginx), having Plumber listen only on 127.0.0.1 is likely the right default, as your proxy – not Plumber – is the one receiving external connections.
      2. 
-
    2. Plumber no longer sets the Access-Control-Allow-Origin HTTP header to *. This was previously done for convenience but given the security implications we’re reversing this decision. The previous behavior would have allowed web browsers to make requests of your API from other domains using JavaScript if the request used only standard HTTP headers and were a GET, HEAD, or POST request. These requests will no longer work by default. If you wish to allow an endpoint to be accessible from other origins in a web browser, you can use res$setHeader("Access-Control-Allow-Origin", "*") in an endpoint or filter.
      3. 
-
    3. Rather than setting the default port to 8000, the port is now randomly selected. This ensures that a shared server (like RStudio Server) will be able to support multiple people developing Plumber APIs concurrently without them having to manually identify an available port. This can be controlled by specifying the port parameter in the run() method or by setting the plumber.port option.
      4. 
+Plumber no longer accepts external connections by
+default. The host parameter for the
+run() method now defaults to 127.0.0.1,
+meaning that Plumber will only listen for incoming requests from the
+local machine on which it’s running – not from any other machine on the
+network. This is done for security reasons so that you don’t
+accidentally expose a Plumber API that you’re developing to your entire
+network. To restore the old behavior in which Plumber listened for
+connections from any machine on the network, use
+$run(host="0.0.0.0"). Note that if you’re deploying to an
+environment that includes an HTTP proxy (such as the DigitalOcean servers which use
+nginx), having Plumber listen only on 127.0.0.1 is likely
+the right default, as your proxy – not Plumber – is the one receiving
+external connections.
+
    4. Plumber no longer sets the Access-Control-Allow-Origin
+HTTP header to *. This was previously done for convenience
+but given the security implications we’re reversing this decision. The
+previous behavior would have allowed web browsers to make requests of
+your API from other domains using JavaScript if the request used only
+standard HTTP headers and were a GET, HEAD, or
+POST request. These requests will no longer work by
+default. If you wish to allow an endpoint to be accessible from other
+origins in a web browser, you can use
+res$setHeader("Access-Control-Allow-Origin", "*") in an
+endpoint or filter.
      5. 
+
    5. Rather than setting the default port to 8000,
+the port is now randomly selected. This ensures that a
+shared server (like RStudio Server) will be able to support multiple
+people developing Plumber APIs concurrently without them having to
+manually identify an available port. This can be controlled by
+specifying the port parameter in the run()
+method or by setting the plumber.port option.
      6. 
 
    6. 
-The object-oriented model for Plumber routers has changed. If you’re calling any of the following methods on your Plumber router, you will need to modify your code to use the newer alternatives: addFilter, addEndpoint, addGlobalProcessor, and addAssets. The code around these functions has undergone a major rewrite and some breaking changes have been introduced. These four functions are still supported with a deprecation warning in 0.4.0, but support is only best-effort. Certain parameters on these methods are no longer supported, so you should thoroughly test any Plumber API that leverages any of these methods before deploying version 0.4.0. Updated documentation for using Plumber programmatically is now available.
      7. 
+The object-oriented model for Plumber routers has
+changed. If you’re calling any of the following methods on your
+Plumber router, you will need to modify your code to use the newer
+alternatives: addFilter, addEndpoint,
+addGlobalProcessor, and addAssets. The code
+around these functions has undergone a major rewrite and some breaking
+changes have been introduced. These four functions are still supported
+with a deprecation warning in 0.4.0, but support is only best-effort.
+Certain parameters on these methods are no longer supported, so you
+should thoroughly test any Plumber API that leverages any of these
+methods before deploying version 0.4.0. Updated
+documentation for using Plumber programmatically is now
+available.
 
    
 
    
   
    
diff --git a/articles/migration_files/accessible-code-block-0.0.1/empty-anchor.js b/articles/migration_files/accessible-code-block-0.0.1/empty-anchor.js
deleted file mode 100644
index ca349fd6a..000000000
--- a/articles/migration_files/accessible-code-block-0.0.1/empty-anchor.js
+++ /dev/null
@@ -1,15 +0,0 @@
-// Hide empty  tag within highlighted CodeBlock for screen reader accessibility (see https://github.com/jgm/pandoc/issues/6352#issuecomment-626106786) -->
-// v0.0.1
-// Written by JooYoung Seo (jooyoung@psu.edu) and Atsushi Yasumoto on June 1st, 2020.
-
-document.addEventListener('DOMContentLoaded', function() {
-  const codeList = document.getElementsByClassName("sourceCode");
-  for (var i = 0; i < codeList.length; i++) {
-    var linkList = codeList[i].getElementsByTagName('a');
-    for (var j = 0; j < linkList.length; j++) {
-      if (linkList[j].innerHTML === "") {
-        linkList[j].setAttribute('aria-hidden', 'true');
-      }
-    }
-  }
-});
diff --git a/articles/programmatic-usage.html b/articles/programmatic-usage.html
index 077fb16b2..56c8ae7ff 100644
--- a/articles/programmatic-usage.html
+++ b/articles/programmatic-usage.html
@@ -15,8 +15,8 @@
 
 
 
-
-
+
+
 
 
 
@@ -93,7 +93,8 @@ 
    Releases
    
 
 
 
-
    
+
+
    
   
    
       
    Programmatic Usage
    
             
@@ -104,18 +105,47 @@ 
    Releases
    
 
     
     
-
    Typically, users define APIs using the “annotations,” or special comments in their API source code. It is possible to define a Plumber API programmatically using the same underlying R6 objects that get created automatically when you define your API using annotations. Interacting with Plumber at this level can offer more control and specificity about how you want your API to behave.
    
+
    Typically, users define APIs using the “annotations,” or special
+comments in their API source code. It is possible to define a Plumber
+API programmatically using the same underlying R6 objects that get
+created automatically when you define your API using annotations.
+Interacting with Plumber at this level can offer more control and
+specificity about how you want your API to behave.
    
 
    
 
    Creating and Controlling a Router
 
    
-
    The centerpiece of Plumber is the router. Plumber routers are responsible for coordinating incoming requests from httpuv, dispatching the requests to the appropriate filters/endpoints, serializing the response, and handling errors that might pop up along the way. If you’ve been using annotations to define Plumber APIs, then you’ve already worked with Plumber routers as that’s what the plumb() command produces.
    
-
    To instantiate a new Plumber router programmatically, you can call pr(). This will return a blank Plumber router with no endpoints. You could call pr_run() on the returned object to start the API, but it doesn’t know how to respond to any requests so any incoming traffic would get a 404 response. We’ll see momentarily how to add endpoints and filters onto this empty router. Alternatively, you can pass a file that contains your annotation-based Plumber API as the first parameter to create a router much like you do with plumb().
    
-
    Be aware that Plumber routers do come with a handful of filters pre-configured. These built-in filters are used to do things like process properties of the incoming request like its cookies, POST body, or query string. You can specify which filters you want in your new router by overriding the filters parameter when creating your new router.
    
+
    The centerpiece of Plumber is the router. Plumber routers are
+responsible for coordinating incoming requests from httpuv, dispatching
+the requests to the appropriate filters/endpoints, serializing the
+response, and handling errors that might pop up along the way. If you’ve
+been using annotations to define Plumber APIs, then you’ve already
+worked with Plumber routers as that’s what the plumb()
+command produces.
    
+
    To instantiate a new Plumber router programmatically, you can call
+pr(). This will return a blank Plumber router with no
+endpoints. You could call pr_run() on the returned object
+to start the API, but it doesn’t know how to respond to any requests so
+any incoming traffic would get a 404 response. We’ll see
+momentarily how to add endpoints and filters onto this empty router.
+Alternatively, you can pass a file that contains your annotation-based
+Plumber API as the first parameter to create a router much like you do
+with plumb().
    
+
    Be aware that Plumber routers do come with a handful of filters
+pre-configured. These built-in filters are used to do things like
+process properties of the incoming request like its cookies,
+POST body, or query string. You can specify which filters
+you want in your new router by overriding the filters
+parameter when creating your new router.
    
 
    
 
    
 
    Defining Endpoints
 
    
-
    You can define endpoints on your router by using the pr_handle(), pr_get(), or pr_post(). For instance, to define a Plumber API that response to GET requests on / and POST requests on /submit, you could use the following code:
    
+
    You can define endpoints on your router by using the
+pr_handle(), pr_get(), or
+pr_post(). For instance, to define a Plumber API that
+response to GET requests on / and
+POST requests on /submit, you could use the
+following code:
    
 
     pr() %>%
   pr_get("/", function(req, res){
@@ -124,8 +154,13 @@ 
    Defining Endpointspr_post("/submit", function(req, res){
     # ...
   })
    
-
    The “handler” functions that you define in these calls are identical to the code you would have defined in your plumber.R file if you were using annotations to define your API.
    
-
    The route methods take additional arguments that allow you to control nuanced behavior of the endpoint like which filter it might preempt or which serializer it should use. For instance, the following endpoint would use Plumber’s HTML serializer.
    
+
    The “handler” functions that you define in these calls are identical
+to the code you would have defined in your plumber.R file
+if you were using annotations to define your API.
    
+
    The route methods take additional arguments that allow you to control
+nuanced behavior of the endpoint like which filter it might preempt or
+which serializer it should use. For instance, the following endpoint
+would use Plumber’s HTML serializer.
    
 
     pr() %>%
   pr_get("/", function(){
@@ -135,7 +170,8 @@ 
    Defining Endpoints
 
    Defining Filters
 
    
-
    Use the filter() method of a Plumber router to define a new filter:
    
+
    Use the filter() method of a Plumber router to define a
+new filter:
    
 
     pr() %>%
   pr_filter("myFilter", function(req){
@@ -145,21 +181,38 @@ 
    Defining Filters  pr_get("/", function(req){
     paste("Am I filtered?", req$filtered)
   })
    
-
    You can specify other options such as the serializer to use if the filter returns a value in the pr_filter() method, as well.
    
+
    You can specify other options such as the serializer to use if the
+filter returns a value in the pr_filter() method, as
+well.
    
 
    
 
    
 
    Registering Hooks on a Router
 
    
-
    Plumber routers support the notion of “hooks” that can be registered to execute some code at a particular point in the lifecycle of a request. Plumber routers currently support four hooks:
    
+
    Plumber routers support the notion of “hooks” that can be registered
+to execute some code at a particular point in the lifecycle of a
+request. Plumber routers currently support four hooks:
    
 
      
 
    • preroute(data, req, res)
      • 
 
    • postroute(data, req, res, value)
      • 
 
    • preserialize(data, req, res, value)
      • 
 
    • postserialize(data, req, res, value)
      • 
 
    
-
    In all of the above you have access to a disposable environment in the data parameter that is created as a temporary data store for each request. Hooks can store temporary data in these hooks that can be reused by other hooks processing this same request.
    
-
    One feature when defining hooks in Plumber routers is the ability to modify the returned value. The convention for such hooks is: any function that accepts a parameter named value is expected to return the new value. This could be an unmodified version of the value that was passed in, or it could be a mutated value. But in either case, if your hook accepts a parameter named value, whatever your hook returns will be used as the new value for the response.
    
-
    You can add hooks using the pr_hook method, or you can add multiple hooks at once using the pr_hooks method which takes a name list in which the names are the names of the hooks, and the values are the handlers themselves.
    
+
    In all of the above you have access to a disposable environment in
+the data parameter that is created as a temporary data
+store for each request. Hooks can store temporary data in these hooks
+that can be reused by other hooks processing this same request.
    
+
    One feature when defining hooks in Plumber routers is the ability to
+modify the returned value. The convention for such hooks is: any
+function that accepts a parameter named value is expected
+to return the new value. This could be an unmodified version of the
+value that was passed in, or it could be a mutated value. But in either
+case, if your hook accepts a parameter named value,
+whatever your hook returns will be used as the new value for the
+response.
    
+
    You can add hooks using the pr_hook method, or you can
+add multiple hooks at once using the pr_hooks method which
+takes a name list in which the names are the names of the hooks, and the
+values are the handlers themselves.
    
 
     pr() %>%
   pr_hook("preroute", function(req) {
@@ -180,12 +233,17 @@ 
    Registering Hooks on a Router    }
   )) %>%
   pr_get("/", function(){ 123 })
    
-
    Making a GET request to / will print out various information from the three events for which we registered hooks.
    
+
    Making a GET request to / will print out
+various information from the three events for which we registered
+hooks.
    
 
    
 
    
 
    Mounting & Static File Routers
 
    
-
    Plumber routers can be “nested” by mounting one into another using the mount() method. This allows you to compartmentalize your API by paths which is a great technique for decomposing large APIs into smaller files.
    
+
    Plumber routers can be “nested” by mounting one into another using
+the mount() method. This allows you to compartmentalize
+your API by paths which is a great technique for decomposing large APIs
+into smaller files.
    
 
     root <- pr()
 
@@ -197,24 +255,36 @@ 
    Mounting & Static File Routers  pr_mount("/products", products)
 
 root
    
-
    This is the same approach used for defining routers that serve a directory of static files. Static file routers are just a special case of Plumber routers created using pr_static(). For example
    
+
    This is the same approach used for defining routers that serve a
+directory of static files. Static file routers are just a special case
+of Plumber routers created using pr_static(). For
+example
    
 
     pr() %>%
   pr_static("/assets", "./myfiles") %>%
   pr_run()
    
-
    This will make the files and directories stored in the ./myfiles directory available on your API under the /assets/ path.
    
+
    This will make the files and directories stored in the
+./myfiles directory available on your API under the
+/assets/ path.
    
 
    
 
    
 
    Customizing a Router
 
    
-
    There are a handful of useful methods to be aware of to modify the behavior of a router. Using hooks to alter request processing has already been discussed, but additionally you can modify a router’s behavior using any of the following:
    
+
    There are a handful of useful methods to be aware of to modify the
+behavior of a router. Using hooks to alter
+request processing has already been discussed, but additionally you
+can modify a router’s behavior using any of the following:
    
 
      
 
    • 
-pr_set_serializer() - Sets the default serializer of the router.
      • 
+pr_set_serializer() - Sets the default serializer of
+the router.
 
    • 
-pr_set_error() - Sets the error handler which gets invoked if any filter or endpoint generates an error.
      • 
+pr_set_error() - Sets the error handler which gets
+invoked if any filter or endpoint generates an error.
 
    • 
-pr_set_404() - Sets the handler that gets called if an incoming request can’t be served by any filter, endpoint, or sub-router.
      • 
+pr_set_404() - Sets the handler that gets called if an
+incoming request can’t be served by any filter, endpoint, or
+sub-router.
    diff --git a/pkgdown.yml b/pkgdown.yml index 87b255704..b1a350184 100644 --- a/pkgdown.yml +++ b/pkgdown.yml @@ -1,4 +1,4 @@ -pandoc: 2.7.3 +pandoc: 3.1.2 pkgdown: 2.0.7 pkgdown_sha: ~ articles: @@ -13,7 +13,7 @@ articles: routing-and-input: routing-and-input.html security: security.html tips-and-tricks: tips-and-tricks.html -last_built: 2023-03-08T19:01Z +last_built: 2023-08-11T21:07Z urls: reference: https://www.rplumber.io/reference article: https://www.rplumber.io/articles diff --git a/reference/Hookable.html b/reference/Hookable.html index ec20810da..450441de0 100644 --- a/reference/Hookable.html +++ b/reference/Hookable.html @@ -1,6 +1,6 @@ Hookable — Hookable • plumberHookable — Hookable • plumberPackage Plumber Router — Plumber • plumberPackage Plumber Router — Plumber • plumberPlumber Endpoint — PlumberEndpoint • plumberPlumber Endpoint — PlumberEndpoint • plumberStatic file router — PlumberStatic • plumberStatic file router — PlumberStatic • plumberplumber step R6 class — PlumberStep • plumberplumber step R6 class — PlumberStep • plumberReturn an attachment response — as_attachment • plumberReturn an attachment response — as_attachment • plumberDeprecated functions — addSerializer • plumberDeprecated functions — addSerializer • plumber diff --git a/reference/deprecated_r6.html b/reference/deprecated_r6.html index c7aad6d3f..a11ba6e6b 100644 --- a/reference/deprecated_r6.html +++ b/reference/deprecated_r6.html @@ -2,7 +2,7 @@ Deprecated R6 functions — hookable • plumberDeprecated R6 functions — hookable • plumberDigitalOcean Plumber server — do_provision • plumberDigitalOcean Plumber server — do_provision • plumberEndpoint Serializer with Hooks — endpoint_serializer • plumberEndpoint Serializer with Hooks — endpoint_serializer • plumberForward Request to The Next Handler — forward • plumberRequest character set — get_character_set • plumberRequest character set — get_character_set • plumber diff --git a/reference/include_file.html b/reference/include_file.html index cb96c6720..2e30f8dee 100644 --- a/reference/include_file.html +++ b/reference/include_file.html @@ -1,5 +1,5 @@ -Send File Contents as Response — include_file • plumberSend File Contents as Response — include_file • plumber diff --git a/reference/index.html b/reference/index.html index 87ffc0e9b..252eeb45d 100644 --- a/reference/index.html +++ b/reference/index.html @@ -1,5 +1,5 @@ -Function reference • plumberFunction reference • plumber diff --git a/reference/is_plumber.html b/reference/is_plumber.html index 6c8e2b6e8..b1f446a69 100644 --- a/reference/is_plumber.html +++ b/reference/is_plumber.html @@ -1,5 +1,5 @@ -Determine if Plumber object — is_plumber • plumberDetermine if Plumber object — is_plumber • plumber diff --git a/reference/options_plumber.html b/reference/options_plumber.html index fe7482c6b..15fddeba9 100644 --- a/reference/options_plumber.html +++ b/reference/options_plumber.html @@ -1,7 +1,7 @@ Plumber options — options_plumber • plumberPlumber options — options_plumber • plumberPlumber Parsers — parser_form • plumberPlumber Parsers — parser_form • plumberPipe operator — %>% • plumberPipe operator — %>% • plumber diff --git a/reference/plumb.html b/reference/plumb.html index c13976b4f..79e9cc514 100644 --- a/reference/plumb.html +++ b/reference/plumb.html @@ -1,5 +1,5 @@ -Process a Plumber API — plumb • plumberProcess a Plumber API — plumb • plumber diff --git a/reference/plumb_api.html b/reference/plumb_api.html index 256be5404..d198f810d 100644 --- a/reference/plumb_api.html +++ b/reference/plumb_api.html @@ -1,6 +1,6 @@ Process a Package's Plumber API — plumb_api • plumberProcess a Package's Plumber API — plumb_api • plumberCreate a new Plumber router — pr • plumberCreate a new Plumber router — pr • plumber diff --git a/reference/pr_cookie.html b/reference/pr_cookie.html index 53b0cf506..224de5373 100644 --- a/reference/pr_cookie.html +++ b/reference/pr_cookie.html @@ -1,6 +1,6 @@ Store session data in encrypted cookies. — pr_cookie • plumberStore session data in encrypted cookies. — pr_cookie • plumberAdd a filter to Plumber router — pr_filter • plumberAdd a filter to Plumber router — pr_filter • plumberAdd handler to Plumber router — pr_handle • plumberAdd handler to Plumber router — pr_handle • plumber diff --git a/reference/pr_hook.html b/reference/pr_hook.html index 71ca773ec..7f03bd276 100644 --- a/reference/pr_hook.html +++ b/reference/pr_hook.html @@ -11,7 +11,7 @@ can store temporary data in these hooks that can be reused by other hooks processing this same request. -'>Register a hook — pr_hook • plumberRegister a hook — pr_hook • plumberSet the handler that is called when the incoming request can't be served — pr_set_404 • plumberSet the OpenAPI Specification — pr_set_api_spec • plumberSet the OpenAPI Specification — pr_set_api_spec • plumber diff --git a/reference/pr_set_debug.html b/reference/pr_set_debug.html index 0db7ed445..813f1be95 100644 --- a/reference/pr_set_debug.html +++ b/reference/pr_set_debug.html @@ -1,6 +1,6 @@ Set debug value to include error messages of routes cause an error — pr_set_debug • plumberSet debug value to include error messages of routes cause an error — pr_set_debug • plumberSet the API visual documentation — pr_set_docs • plumberSet the API visual documentation — pr_set_docs • plumberSet the callback to tell where the API visual documentation is located — pr_set_docs_callback • plumberSet the callback to tell where the API visual documentation is located — pr_set_docs_callback • plumberSet the error handler that is invoked if any filter or endpoint generates an -error — pr_set_error • plumberSet the default endpoint parsers for the router — pr_set_parsers • plumberSet the default endpoint parsers for the router — pr_set_parsers • plumberSet the default serializer of the router — pr_set_serializer • plumberSet the default serializer of the router — pr_set_serializer • plumberAdd a static route to the plumber object — pr_static • plumberAdd a static route to the plumber object — pr_static • plumber diff --git a/reference/random_cookie_key.html b/reference/random_cookie_key.html index c1b038ff4..2890b226d 100644 --- a/reference/random_cookie_key.html +++ b/reference/random_cookie_key.html @@ -1,5 +1,5 @@ -Random cookie key generator — random_cookie_key • plumberRandom cookie key generator — random_cookie_key • plumber diff --git a/reference/register_docs.html b/reference/register_docs.html index 6d122002f..b32b8c4b8 100644 --- a/reference/register_docs.html +++ b/reference/register_docs.html @@ -1,7 +1,7 @@ Add visual documentation for plumber to use — register_docs • plumberAdd visual documentation for plumber to use — register_docs • plumberManage parsers — register_parser • plumberManage parsers — register_parser • plumberRegister a Serializer — register_serializer • plumberRegister a Serializer — register_serializer • plumberPlumber Serializers — serializer_headers • plumberPlumber Serializers — serializer_headers • plumberStore session data in encrypted cookies. — session_cookie • plumberStore session data in encrypted cookies. — session_cookie • plumberValidate OpenAPI Spec — validate_api_spec • plumberValidate OpenAPI Spec — validate_api_spec • plumber diff --git a/search.json b/search.json index 1a406e33f..7e4c57d76 100644 --- a/search.json +++ b/search.json @@ -1 +1 @@ -[{"path":"https://www.rplumber.io/CONTRIBUTING.html","id":null,"dir":"","previous_headings":"","what":"Contributing","title":"Contributing","text":"welcome contributions plumber package! submit contribution: Fork repository make changes. Submit pull request. Ensure signed contributor license agreement. appear “Check” PR comment “CLAassistant” also appear explaining whether yet sign. sign, can click “Recheck” link comment check flip reflect ’ve signed.","code":""},{"path":"https://www.rplumber.io/PULL_REQUEST_TEMPLATE.html","id":"pull-request","dir":"","previous_headings":"","what":"Pull Request","title":"NA","text":"submit pull request, please following: Add entry NEWS concisely describing changed. Add unit tests tests/testthat directory. Run Build->Check Package RStudio IDE, devtools::check(), make sure change add messages, warnings, errors. things make easier plumber development team evaluate pull request. Even , may still decide modify code even merge . Factors may prevent us merging pull request include: breaking backward compatibility adding feature consider relevant plumber hard understand hard maintain future computationally expensive intuitive people use try responsive provide feedback case decide merge pull request.","code":""},{"path":"https://www.rplumber.io/PULL_REQUEST_TEMPLATE.html","id":"minimal-reproducible-example","dir":"","previous_headings":"","what":"Minimal reproducible example","title":"NA","text":"Finally, please include minimal reprex. goal reprex make easy possible recreate problem can fix . ’ve never heard reprex , start reading https://github.com/jennybc/reprex#---reprex, follow advice page. include session info unless ’s explicitly asked , ’ve used reprex::reprex(..., si = TRUE) hide away. Delete instructions read . Brief description original problem approach behind solution. PR task list: - [ ] Update NEWS - [ ] Add tests - [ ] Update documentation devtools::document()","code":"reprex::reprex({ library(plumber) # insert reprex here }) # insert reprex here"},{"path":"https://www.rplumber.io/articles/annotations.html","id":"annotations","dir":"Articles","previous_headings":"","what":"Annotations","title":"Annotations reference","text":"Annotations specially-structured comments used plumber file create API. full annotation line starts #* #', annotation keyword @..., number space characters followed content. recommended use #* differentiate roxygen2 annotations.","code":""},{"path":"https://www.rplumber.io/articles/annotations.html","id":"global-annotations","dir":"Articles","previous_headings":"","what":"Global annotations","title":"Annotations reference","text":"Global annotations can used anywhere plumber file. independent annotations require expression.","code":""},{"path":"https://www.rplumber.io/articles/annotations.html","id":"annotations-example","dir":"Articles","previous_headings":"Global annotations","what":"Annotations example","title":"Annotations reference","text":"","code":"#* @apiTitle Sample Pet Store App #* @apiDescription This is a sample server for a pet store. #* @apiTOS http://example.com/terms/ #* @apiContact list(name = \"API Support\", url = \"http://www.example.com/support\", email = \"support@example.com\") #* @apiLicense list(name = \"Apache 2.0\", url = \"https://www.apache.org/licenses/LICENSE-2.0.html\") #* @apiVersion 1.0.1 #* @apiTag pet Pets operations #* @apiTag toy Toys operations #* @apiTag \"toy space\" Toys operations"},{"path":"https://www.rplumber.io/articles/annotations.html","id":"equivalent-programmatic-usage","dir":"Articles","previous_headings":"Global annotations","what":"Equivalent programmatic usage","title":"Annotations reference","text":"","code":"pr() %>% pr_set_api_spec(function(spec) { spec$info <- list( title = \"Sample Pet Store App\", description = \"This is a sample server for a pet store.\", termsOfService = \"http://example.com/terms/\", contact = list(name = \"API Support\", url = \"http://www.example.com/support\", email = \"support@example.com\"), license = list(name = \"Apache 2.0\", url = \"https://www.apache.org/licenses/LICENSE-2.0.html\"), version = \"1.0.1\" ) spec$tags <- list(list(name = \"pet\", description = \"Pets operations\"), list(name = \"toy\", description = \"Toys operations\"), list(name = \"toy space\", description = \"Toys operations\")) spec })"},{"path":"https://www.rplumber.io/articles/annotations.html","id":"block-annotations","dir":"Articles","previous_headings":"","what":"Block annotations","title":"Annotations reference","text":"block annotations combination annotations create either endpoint, filter, static file handler Plumber object modifier. Block annotations always followed expression.","code":""},{"path":[]},{"path":"https://www.rplumber.io/articles/annotations.html","id":"more-details-on-param","dir":"Articles","previous_headings":"Block annotations > Endpoint","what":"More details on @param","title":"Annotations reference","text":"Types used define API inputs. can use dynamic routes. Note Plumber first look block expression set endpoint parameters names, types default value. @param annotations dynamic route/path defined parameters override Plumber guesses block expression. Query parameters currently need explicitly converted pushed (character) block expression. dynamic route parameters converted specified @param type pushed block expression. Plumber parameter type OpenAPI type reference. programmatic use, pick one asterisk.","code":""},{"path":"https://www.rplumber.io/articles/annotations.html","id":"annotations-example-1","dir":"Articles","previous_headings":"Block annotations > Endpoint > More details on @param","what":"Annotations example","title":"Annotations reference","text":"","code":"#* @get /query/parameters #* @serializer text #* @param name:str #* @param age:[int] function(name, age) { # Explicit conversion is required for query parameters age <- as.integer(age) sprintf(\"%s is %i years old\", name, max(age)) } #* @get /dyn///route #* @serializer text #* @parser none #* @response 200 A sentence function(name, age) { sprintf(\"%s is %i years old\", name, age) } #* @post /upload_file #* @serializer rds #* @parser multi #* @parser rds #* @param f:file A file #* Upload an rds file and return the object function(f) { as_attachment(f[[1]], names(f)[1]) }"},{"path":"https://www.rplumber.io/articles/annotations.html","id":"equivalent-programmatic-usage-1","dir":"Articles","previous_headings":"Block annotations > Endpoint > More details on @param","what":"Equivalent programmatic usage","title":"Annotations reference","text":"","code":"text_handler <- function(name, age) { sprintf(\"%s is %i years old\", name, max(age)) } qp_handler <- function(name, age) { age <- as.integer(age); text_handler(name, age) } file_handler <- function(file) { as_attachment(file[[1]], names(file)[1]) } pr() %>% pr_get(path = \"/query/parameters\", handler = qp_handler, serializer = serializer_text(), params = list(\"name\" = list(type = \"string\", required = FALSE, isArray = FALSE), \"age\" = list(type = \"integer\", required = FALSE, isArray = TRUE))) %>% pr_get(path = \"/dyn///route\", handler = text_handler, serializer = serializer_text(), parsers = \"none\", responses = list(\"200\" = list(description = \"A sentence\"))) %>% pr_post(path = \"/upload_file\", handler = file_handler, serializer = serializer_rds(), parsers = c(\"multi\", \"rds\"), params = list(\"file\" = list(type = \"file\", desc = \"A file\", required = FALSE, isArray = FALSE)), comments = \"Upload an rds file and return the object\")"},{"path":[]},{"path":"https://www.rplumber.io/articles/annotations.html","id":"annotations-example-2","dir":"Articles","previous_headings":"Block annotations > Filter","what":"Annotations example","title":"Annotations reference","text":"","code":"#* @filter logger function(req){ cat(as.character(Sys.time()), \"-\", req$REQUEST_METHOD, req$PATH_INFO, \"-\", req$HTTP_USER_AGENT, \"@\", req$REMOTE_ADDR, \"\\n\") plumber::forward() }"},{"path":"https://www.rplumber.io/articles/annotations.html","id":"equivalent-programmatic-usage-2","dir":"Articles","previous_headings":"Block annotations > Filter","what":"Equivalent programmatic usage","title":"Annotations reference","text":"","code":"pr() %>% pr_filter(\"logger\", function(req){ cat(as.character(Sys.time()), \"-\", req$REQUEST_METHOD, req$PATH_INFO, \"-\", req$HTTP_USER_AGENT, \"@\", req$REMOTE_ADDR, \"\\n\") plumber::forward() })"},{"path":[]},{"path":"https://www.rplumber.io/articles/annotations.html","id":"annotations-example-3","dir":"Articles","previous_headings":"Block annotations > Static File Handler","what":"Annotations example","title":"Annotations reference","text":"","code":"#* @assets ./files/static list() #* @assets ./files/static /static list() #* @assets ./files/static / list()"},{"path":"https://www.rplumber.io/articles/annotations.html","id":"equivalent-programmatic-usage-note-that-argument-order-is-reversed","dir":"Articles","previous_headings":"Block annotations > Static File Handler","what":"Equivalent programmatic usage (note that argument order is reversed)","title":"Annotations reference","text":"","code":"pr() %>% pr_static(direc = \"./files/static\") pr() %>% pr_static(\"/static\", \"./files/static\") pr() %>% pr_static(\"/\", \"./files/static\")"},{"path":[]},{"path":"https://www.rplumber.io/articles/annotations.html","id":"annotations-example-4","dir":"Articles","previous_headings":"Block annotations > Plumber Router Modifier","what":"Annotations example","title":"Annotations reference","text":"","code":"#* @plumber function(pr) { pr %>% pr_set_debug(TRUE) %>% pr_set_docs(\"swagger\") } # Named function debug_swagger <- function(pr) { pr %>% pr_set_debug(TRUE) %>% pr_set_docs(\"swagger\") } #* @plumber debug_swagger"},{"path":"https://www.rplumber.io/articles/annotations.html","id":"equivalent-programmatic-usage-3","dir":"Articles","previous_headings":"Block annotations > Plumber Router Modifier","what":"Equivalent programmatic usage","title":"Annotations reference","text":"","code":"pr() %>% pr_set_debug(TRUE) %>% pr_set_docs(\"swagger\")"},{"path":"https://www.rplumber.io/articles/execution-model.html","id":"execution-model","dir":"Articles","previous_headings":"","what":"Execution Model","title":"Runtime","text":"plumb() file, Plumber calls source() file evaluate top-level code defined. call plumb() file, counter variable created live environment created API. However, endpoint defined evaluated invoked response incoming request. endpoint uses <<-, “double-assignment” operator, mutates counter variable previously defined file plumb()d. technique allows endpoints filters share data defined top-level API.","code":"# Global code; gets executed at plumb() time. counter <- 0 #* @get / function(){ # Only gets evaluated when this endpoint is requested. counter <<- counter + 1 }"},{"path":"https://www.rplumber.io/articles/execution-model.html","id":"environments","dir":"Articles","previous_headings":"","what":"Environments","title":"Runtime","text":"default, create new Plumber router (happens implicitly call plumb() file), new environment created especially router. environment expressions evaluated endpoints invoked. can become important consider mounting routers onto one another. case, may expect able share state via environment, work default. ’re creating routers programmatically, can specify environment initializing Plumber router using envir parameter. environment : decorated R script, provided, source()d. expressions evaluated. endpoint filter functions executed. important aware subrouters, default, environment. want multiple Plumber routers share environment, need provide single, shared environment create routers.","code":""},{"path":"https://www.rplumber.io/articles/execution-model.html","id":"performance-request-processing","dir":"Articles","previous_headings":"","what":"Performance & Request Processing","title":"Runtime","text":"R single-threaded programming language, meaning can one task time. still true serving APIs using Plumber, single endpoint takes two seconds generate response, every time endpoint requested, R process unable respond additional incoming requests two seconds. Incoming HTTP requests serviced order appeared, requests coming quickly can processed API, backlog requests accrue. common solutions problem either : Keep API performant. filters endpoints complete quickly long-running complicated tasks done outside API process. Run multiple R processes redundantly host single Plumber API load-balance incoming requests available processes. See hosting section details hosting environments support feature.","code":""},{"path":"https://www.rplumber.io/articles/execution-model.html","id":"managing-state","dir":"Articles","previous_headings":"","what":"Managing State","title":"Runtime","text":"Often, Plumber APIs require coordination state. state may need shared multiple endpoints API (e.g. counter increments every time endpoint invoked). Alternatively, information needs persisted across requests single client (e.g. storing preference setting user). Lastly, might require coordinating multiple Plumber processes running independently behind load-balancer. scenarios unique properties determine solution might appropriate. previously discussed, R single-threaded. Therefore ’s important consider fact may eventually need multiple R processes running parallel handle incoming traffic API. may seem important initially, may thank later designing “horizontally scalable” API (one can scaled adding R processes parallel). key building horizontally scalable API ensure Plumber process “stateless,” meaning persistent state lives outside Plumber process. hosting environments exist today, guaranteed two subsequent requests single client served process. Thus ’s never safe assume information stored -memory available requests horizontally scaled app. options consider coordinate state Plumber API.","code":""},{"path":"https://www.rplumber.io/articles/execution-model.html","id":"in-memory","dir":"Articles","previous_headings":"Managing State","what":"In-Memory","title":"Runtime","text":"shown previous Execution Model section, possible share state using environment associated Plumber router. one approach presented allow Plumber process stateless. approach sufficient coordinating state within single process, scale API adding processes, state longer coordinated . Therefore approach can effective “read-” data – load single, large dataset memory API starts, allow filters endpoints reference dataset moving forward – allow share state across multiple processes scale. want build scalable, stateless application, avoid relying -memory R environment coordinate state pieces API.","code":"# Global code; gets executed at plumb() time. counter <- 0 #* @get / function(){ # Only gets evaluated when this endpoint is requested. counter <<- counter + 1 }"},{"path":"https://www.rplumber.io/articles/execution-model.html","id":"file-system","dir":"Articles","previous_headings":"Managing State","what":"File System","title":"Runtime","text":"Writing files disk often next obvious choice storing state. Plumber APIs modify data frame use write.csv() save data disk, use writeLines() append new data existing file. approaches enable R process stateless, always resilient concurrency issues. instance, ’ve horizontally scaled API five R processes two go write.csv() simultaneously, either see one process’s data get immediately overwritten ’s, – even worse – may end corrupted CSV file can’t read. Unless otherwise stated, ’s safe assume R function writes data disk resilient concurrency contention, rely filesystem coordinate shared state single R process running concurrently. ’s also important ask whether hosting platform ’ll using supports persistent storage disk. instance, Docker may insulate R process hardware allow write outside container. RStudio Connect, , provision new directory every time deploy updated version API discard data written disk point. ’re considering writing state disk long-term, sure hosting environment supports persistent -disk storage ’ve considered concurrency implications code.","code":""},{"path":"https://www.rplumber.io/articles/execution-model.html","id":"state-cookies","dir":"Articles","previous_headings":"Managing State","what":"Cookies","title":"Runtime","text":"HTTP cookies convention allow web servers send state client expectation client include state future requests. See Setting Cookies section details leverage cookies Plumber. modern web browsers support cookies (unless configured ) many clients , well, though clients require additional configuration order . ’re confident intended clients API support cookies consider storing state cookies. approach mitigates concerns horizontal scalability, state written client independently included subsequent requests client. also minimizes infrastructure requirements hosting Plumber APIs since don’t need setup system capable storing state; instead, ’ve commissioned clients store state. One issue maintaining state cookies size kept minimum. Clients impose restrictions differently, plan store 4kB information cookie. realize whatever information gets placed cookie must retransmitted client every request. can significantly increase size HTTP request clients make. notable concern considering using cookies store state since clients responsible storing sending state, expect state tampered . Thus, may acceptable store user preferences like preferredColor=\"blue\", store authentication information like userID=1493, since user trivially change cookie another user’s ID impersonate . ’d like use cookies store information guarantees user either read modify state, see Encrypted Cookies section).","code":""},{"path":"https://www.rplumber.io/articles/execution-model.html","id":"external-data-store","dir":"Articles","previous_headings":"Managing State","what":"External Data Store","title":"Runtime","text":"final option consider coordinating state API leveraging external data store. relational database (like MySQL Amazon RedShift), non-relational database (like MongoDB), transactional data store like Redis. One important consideration options ensure “transactional,” meaning two Plumber processes trying write time won’t overwrite one another. ’re interested pursuing option see solutions.rstudio.com/db/ look resources put together Shiny pertains dealing databases web-accessible R platform.","code":""},{"path":"https://www.rplumber.io/articles/execution-model.html","id":"exit-handlers","dir":"Articles","previous_headings":"","what":"Exit Handlers","title":"Runtime","text":"may useful define function want run API closing – instance, pool database connections need cleaned Plumber process terminated. can use exit hook define handler. interrupt API (instance pressing Escape key Ctrl+C) ’ll see Bye bye! printed console. can even register multiple exit hooks ’ll run order registered.","code":"pr(\"plumber.R\") %>% pr_hook(\"exit\", function(){ print(\"Bye bye!\") }) %>% pr_run()"},{"path":"https://www.rplumber.io/articles/hosting.html","id":"rstudio-connect","dir":"Articles","previous_headings":"","what":"RStudio Connect","title":"Hosting","text":"RStudio Connect enterprise publishing platform RStudio. supports push-button publishing RStudio IDE variety R content types including Plumber APIs. Unlike options listed , RStudio Connect automatically manages dependent packages files API recreates environment closely mimicking local development environment server. RStudio Connect automatically manages number R processes necessary handle current load balances incoming traffic across available processes. can also shut idle processes ’re use. allows run appropriate number R processes scale capacity accommodate current load.","code":""},{"path":"https://www.rplumber.io/articles/hosting.html","id":"digitalocean","dir":"Articles","previous_headings":"","what":"DigitalOcean","title":"Hosting","text":"DigitalOcean easy--use Cloud Computing provider. offer simple way spin Linux virtual machine access remotely. can choose size machine want run – options ranging small machines 512MB RAM dollars month large machines dozens GB RAM – pay ’s online. deploy Plumber API DigitalOcean, please check plumber companion package plumberDeploy.","code":""},{"path":"https://www.rplumber.io/articles/hosting.html","id":"docker","dir":"Articles","previous_headings":"","what":"Docker (Basic)","title":"Hosting","text":"Docker platform built top Linux Containers allow run processes isolated environment; environment might certain resources/software pre-configured may emulate particular Linux environment like Ubuntu 14.04 CentOS 7.3. won’t delve details Docker setup install everything system. Docker provides great resources looking get started. ’ll assume Docker installed ’re familiar basic commands required spin container. article, ’ll take advantage rstudio/plumber Docker image bundles recent version R recent version plumber pre-installed (underlying R image courtesy rocker project). can get image Remember get current snapshot Plumber continue use image run pull .","code":"docker pull rstudio/plumber"},{"path":"https://www.rplumber.io/articles/hosting.html","id":"default-dockerfile","dir":"Articles","previous_headings":"Docker (Basic)","what":"Default Dockerfile","title":"Hosting","text":"’ll start just running single Plumber application Docker just see things work. default, rstudio/plumber image take first argument image name name file want plumb() serve port 8000. right away can run one examples ’s included plumber already installed image. : docker run tells Docker run new container --rm tells Docker clean-container ’s done -p 8000:8000 says map port 8000 plumber container (’ll run server) port 8000 local machine rstudio/plumber name image want run /usr/local/lib/R/site-library/plumber/plumber/03-mean-sum/plumber.R path inside Docker container Plumber file want host. ’ll note need plumber installed host machine work, path /usr/local/... need exist host machine. references path inside docker container R file want plumb() can found. mean-sum path default path image uses don’t specify one . ask Plumber plumb run file specified port 8000 new container. used -p argument, port 8000 local machine forwarded container. can test running machine Docker running: curl localhost:8000/mean, know IP address machine Docker running, visit web browser. /mean path one ’s defined plumber file just specified – get single number array back ([-0.1993]). works, can try using one plumber files arrangement. Keep mind file want run must available inside container must specify path file exists inside container. Keep simple now – use plumber file doesn’t require additional R packages depend files outside plumber definition. instance plumber file saved current directory called api.R, use following command ’ll notice used -v argument specify “volume” mapped host machine Docker container. defined location file /plumber.R, ’s argument give last tell container look plumber definition. can use technique share whole directory instead just passing single R file; approach useful Plumber API depends files. can also use rstudio/plumber image just like use . example, want start container based image poke around bash shell: can handy way debug problems. Prepare command think work add --entrypoint /bin/bash rstudio/plumber explore bit. Alternatively, can try run R process spawn plumber application see things go wrong (often missing package missing file).","code":"docker run --rm -p 8000:8000 rstudio/plumber docker run --rm -p 8000:8000 rstudio/plumber \\ /usr/local/lib/R/site-library/plumber/plumber/04-mean-sum/plumber.R docker run --rm -p 8000:8000 -v `pwd`/api.R:/plumber.R rstudio/plumber /plumber.R docker run -it --rm --entrypoint /bin/bash rstudio/plumber"},{"path":"https://www.rplumber.io/articles/hosting.html","id":"custom-dockerfiles","dir":"Articles","previous_headings":"Docker (Basic)","what":"Custom Dockerfiles","title":"Hosting","text":"can build upon rstudio/plumber image build Docker image writing Dockerfile. Dockerfiles vast array options possible configurations, see official docs want learn options. couple commands relevant : RUN runs command persists side-effects Docker image ’re building. want build new image broom package, add line Dockerfile says RUN R -e \"install.packages('broom')\" make broom package available new Docker image. ENTRYPOINT command run starting image. rstudio/plumber specifies entrypoint starts R, plumb()s file, run()s router. want change plumber starts, run extra commands (like add global processor) run router, ’ll need provide custom ENTRYPOINT. CMD default arguments provide ENTRYPOINT. rstudio/plumber uses first argument name file want plumb(). custom Dockerfile simple : Dockerfile just extend rstudio/plumber image two ways. First, RUNs one additional command install broom package. Second, customizes default CMD argument used running image. case, expected mount Plumber application container /app/plumber.R build custom Docker image Dockerfile using command docker build -t mycustomdocker . (. – current directory – directory Dockerfile stored). ’d able use docker run --rm -vpwd:/app mycustomdocker run custom image, passing application’s directory volume mounted /app.","code":"FROM rstudio/plumber LABEL org.opencontainers.image.authors=\"Docker User \" RUN R -e \"install.packages('broom')\" CMD [\"/app/plumber.R\"]"},{"path":"https://www.rplumber.io/articles/hosting.html","id":"automatically-run-on-restart","dir":"Articles","previous_headings":"Docker (Basic)","what":"Automatically Run on Restart","title":"Hosting","text":"want container start automatically machine booted, can use --restart parameter docker run. docker run -p 1234:8000 -dit --restart=unless-stopped myCustomDocker run custom image created automatically every time machine boots expose plumber service port 1234 host machine, unless container explicitly stopped. Like hosting options, ’ll need make sure firewall allows connections port 1234 want others able access service.","code":""},{"path":"https://www.rplumber.io/articles/hosting.html","id":"docker-advanced","dir":"Articles","previous_headings":"","what":"Docker (Advanced)","title":"Hosting","text":"already basic Docker instance running, may interested advanced configurations capable hosting multiple plumber applications single server even load-balancing across multiple plumber processes. order coordinate run multiple Plumber processes one server, install docker-compose system. included installations Docker, need follow instructions currently able run docker-compose command-line. Docker Compose helps orchestrate multiple Docker containers. ’re planning run one Plumber process, ’ll want use Docker Compose keep alive route traffic .","code":""},{"path":"https://www.rplumber.io/articles/hosting.html","id":"multiple-plumber-applications","dir":"Articles","previous_headings":"Docker (Advanced)","what":"Multiple Plumber Applications","title":"Hosting","text":"’ll use Docker Compose help us organize multiple Plumber processes. won’t go detail use Docker Compose, ’re new familiarize using official docs. define Docker Compose configuration defines behavior every Plumber application want run. ’ll first want setup Dockerfile defines desired behavior applications (outlined previously. use docker-compose.yml configuration like following: detail options options exist can found . configuration defines two Docker containers run app1 app2. associated files case laid disk follows: can see app2 simpler two apps; just plumber definition run plumb(). merely use default plumber Docker image image, customize command specify Plumber API definition can found container. Since ’re mapping host’s ./app2 /app inside container, definition found /app/plumber.R. specify always restart anything ever happens container, export port 8000 container port 7001 host. app1 complicated app. extra data another directory needs loaded, custom Dockerfile. additional R packages system dependencies requires. now run docker-compose , Docker Compose build referenced images config file run . ’ll find app1 available port 7000 machine running Docker Compose, app2 available port 7001. want APIs run background survive restarts server, can use -d switch just like docker run.","code":"services: app1: build: ./app1/ volumes: - ./data:/data - ./app1:/app restart: always ports: - \"7000:8000\" app2: image: rstudio/plumber command: /app/plumber.R volumes: - ../app2:/app restart: always ports: - \"7001:8000\" docker-compose.yml app1 ├── Dockerfile ├── api.R app2 ├── plumber.R data ├── data.csv"},{"path":"https://www.rplumber.io/articles/hosting.html","id":"multiple-applications-on-one-port","dir":"Articles","previous_headings":"Docker (Advanced)","what":"Multiple Applications on One Port","title":"Hosting","text":"may desirable run Plumber services standard port like 80 (HTTP) 443 (HTTPS). case, ’d prefer router running port 80 can send traffic appropriate Plumber API distinguishing based path prefix. Requests myserver.com/app1/ sent app1 container, myserver.org/app2/ target app2 container, paths available port 80 server. order , can use another Docker container running nginx configured route traffic two Plumber containers. ’d add following entry docker-compose.yml app containers already defined. uses nginx Docker image downloaded . order run nginx meaningful way, provide configuration file place /etc/nginx/nginx.conf, mounting local file location container. basic nginx config file look something like following: set server_name parameter whatever public address server. can save file nginx.conf directory Compose config file. Docker Compose intelligent enough know route traffic http://app1:8000/ app1 container, port 8000, can leverage config file. Docker containers able contact non-public ports, can go directly port 8000 containers. proxy configuration trim prefix request sends applications, applications don’t need know anything hosted publicly URL includes /app1/ /app2/ prefixes. also get rid previous port mappings ports 7000 7001 applications, don’t want expose APIs ports anymore. now run docker compose , ’ll see two application servers running now new nginx server running, well. ’ll find visit server port 80, ’ll see “welcome Nginx!” page. access /app1 ’ll sent app1 just like hoped.","code":"nginx: image: nginx:1.9 ports: - \"80:80\" volumes: - ./nginx.conf:/etc/nginx/nginx.conf:ro restart: always depends_on: - app1 - app2 events { worker_connections 4096; ## Default: 1024 } http { default_type application/octet-stream; sendfile on; tcp_nopush on; server_names_hash_bucket_size 128; # this seems to be required for some vhosts server { listen 80 default_server; listen [::]:80 default_server ipv6only=on; root /usr/share/nginx/html; index index.html index.htm; server_name MYSERVER.ORG; location /app1/ { proxy_pass http://app1:8000/; proxy_set_header Host $host; } location /app2/ { proxy_pass http://app2:8000/; proxy_set_header Host $host; } location ~ /\\.ht { deny all; } } }"},{"path":"https://www.rplumber.io/articles/hosting.html","id":"load-balancing","dir":"Articles","previous_headings":"Docker (Advanced)","what":"Load Balancing","title":"Hosting","text":"’re expecting lot traffic one application API ’s particularly computationally complex, may want distribute load across multiple R processes running Plumber application. Thankfully, can use Docker Compose , well. First, ’ll want create multiple instances application. easily accomplished docker-compose scale command. simply run docker-compose scale app1=3 run three instances app1. Now just need load balance traffic across three instances. setup nginx configuration already balance traffic across pool workers, need manually re-configure update nginx instance every time need scale number , might hassle. Luckily, ’s elegant solution. can use dockercloud/haproxy Docker image automatically balance HTTP traffic across pool workers. image intelligent enough listen workers pool arriving leaving automatically remove/add containers pool. Let’s add new container configuration defines load balancer trick allows image listen scaling app1 passing docker socket shared volume. Note particular arrangement differ based host OS. configuration intended Linux, MacOS X users require slightly different config. export port 80 new load balancer port 80 host machine solely wanted load-balance single application. Alternatively, can actually use nginx (handle routing various applications) HAProxy (handle load balancing particular application). , ’d merely add new location block nginx.conf file knows send traffic HAProxy, modify existing location block send traffic load balancer instead going directly application. location /app1/ block becomes: lb name HAProxy load balancer defined Compose configuration. next time start/redeploy Docker Compose cluster, ’ll balancing incoming requests /app1/ across pool 1 R processes based whatever ’ve set scale application. keep mind using load-balancing ’s longer guaranteed subsequent requests particular application land process. means maintain state Plumber application (like global counter, user’s session state), can’t expect shared across processes user might encounter. least three possible solutions problem: Use robust means maintaining state. put state database, instance, lives outside R processes Plumber processes get save state externally. serialize state user using (encrypted) session cookies, assuming ’s small enough. scenario, workers write data back user form cookie, user include cookie subsequent requests. works best state going set rarely read often (instance, cookie set user logs , read request detect identity user). can enable “sticky sessions” HAProxy load balancer. ensure user’s traffic always gets routed worker. downside approach distribute traffic less evenly. end situation 2 R processes application 90% traffic hitting one happens users triggering majority requests “stuck” one particular worker.","code":"lb: image: 'dockercloud/haproxy:1.2.1' links: - app1 volumes: - /var/run/docker.sock:/var/run/docker.sock location /app1/ { proxy_pass http://lb/; proxy_set_header Host $host; }"},{"path":"https://www.rplumber.io/articles/hosting.html","id":"pm2","dir":"Articles","previous_headings":"","what":"pm2","title":"Hosting","text":"don’t luxury running Plumber instance designated server (discussed DigitalOcean section) ’re comfortable hosting API Docker, ’ll need find way run manage Plumber APIs server directly. variety tools built help manage web hosting single-threaded environment like R. compelling tools developed around Ruby (like Phusion Passenger) Node.js (like Node Supervisor, forever pm2). Thankfully, many tools can adapted support managing R process running Plumber API. pm2 process manager initially targeting Node.js. ’ll show commands needed Ubuntu 14.04, can use Operating System distribution supported pm2. end, ’ll server automatically starts plumber services booted, restarts ever crash, even centralizes logs plumber services.","code":""},{"path":"https://www.rplumber.io/articles/hosting.html","id":"server-deployment-and-preparation","dir":"Articles","previous_headings":"pm2","what":"Server Deployment and Preparation","title":"Hosting","text":"first thing ’ll need , regardless process manager choose, deploy R files containing plumber applications server ’ll hosted. Keep mind ’ll also need include supplemental R files source()d plumber file, datasets dependencies files . ’ll also need make sure R packages need (appropriate versions) available remote server. can either manually installing packages can consider using tool like Packrat help . myriad features pm2 won’t cover . good idea spend time reading documentation see features might interest ensure understand implications pm2 hosts services (user want run processes , etc.). quick-start guide may especially relevant. sake simplicity, basic installation without customizing many options.","code":""},{"path":"https://www.rplumber.io/articles/hosting.html","id":"install-pm2","dir":"Articles","previous_headings":"pm2","what":"Install pm2","title":"Hosting","text":"Now ’re ready install pm2. pm2 package ’s maintained npm (Node.js’s package management system); also requires Node.js order run. start ’ll want install Node.js. Ubuntu 14.04, necessary commands : npm Node.js installed, ’re ready install pm2. find errors like SSL Error: CERT_UNTRUSTED using npm command, can bypass ssl error using: set registry URL https:// http://: install pm2 globally (-g) server, meaning now able run pm2 --version get version number pm2 ’ve installed. order get pm2 startup services boot, run sudo pm2 startup create necessary files system run pm2 boot machine.","code":"sudo apt-get update sudo apt-get install nodejs npm sudo npm install -g pm2 npm config set strict-ssl false npm config set registry=\"http://registry.npmjs.org/\""},{"path":"https://www.rplumber.io/articles/hosting.html","id":"wrap-your-plumber-file","dir":"Articles","previous_headings":"pm2","what":"Wrap Your Plumber File","title":"Hosting","text":"’ve deployed Plumber files onto server, ’ll still need tell server run server. ’re probably used running commands like Unfortunately, pm2 doesn’t understand R scripts natively; however, possible specify custom interpreter. can use feature launch R-based wrapper plumber file using Rscript scripting front-end comes R. following script run two commands listed . Save R script server something like run-myfile.R. also make executable changing permissions file using command like chmod 755 run-myfile.R. now execute file make sure runs service like expect. able make requests server appropriate port plumber service respond. can kill process using Ctrl-c ’re convinced ’s working. Make sure shell script permanent location won’t erased modified accidentally. can consider creating designated directory plumber services directory like /usr/local/plumber, put services associated Rscript-runners subdirectory like /usr/local/plumber/myfile/.","code":"pr(\"myfile.R\") %>% pr_run(port=4500) #!/usr/bin/env Rscript library(plumber) pr(\"myfile.R\") %>% pr_run(port=4000, host=\"0.0.0.0\") # Setting the host option on a VM instance ensures the application can be accessed externally. # (This may be only true for Linux users.)"},{"path":"https://www.rplumber.io/articles/hosting.html","id":"introduce-our-service-to-pm2","dir":"Articles","previous_headings":"pm2","what":"Introduce Our Service to pm2","title":"Hosting","text":"’ll now need teach pm2 Plumber API can put work. can register configure number services pm2; let’s start myfile Plumber service. can use pm2 list command see services pm2 already running. run command now, ’ll see pm2 doesn’t services ’s charge . scripts code stored directory want , use following command tell pm2 service. see output pm2 starting instance service, followed status information pm2. everything worked properly, ’ll see new service registered running. can see output executing pm2 list . ’re happy pm2 services defined, can use pm2 save tell pm2 retain set services running next time boot machine. services defined automatically restarted . point, persistent pm2 service created Plumber application. means can reboot server, find kill underlying R process plumber application using pm2 automatically bring new process replace . help guarantee always Plumber process running port number specified shell script. good idea reboot server ensure everything comes back way expected. can repeat process plumber applications want deploy, long give unique port run . Remember can’t one service running single port. sure pm2 save every time add services want survive restart. Run netstat -tulpn see application ran. see application host 127.0.0.0 127.0.0.1, application accessed externally. change host parameter 0.0.0.0, example: `pr_run(host = “0.0.0.0”).","code":"pm2 start --interpreter=\"Rscript\" /usr/local/plumber/myfile/run-myfile.R"},{"path":"https://www.rplumber.io/articles/hosting.html","id":"logs-and-management","dir":"Articles","previous_headings":"pm2","what":"Logs and Management","title":"Hosting","text":"Now applications defined pm2, may want drill manage debug . want see information, use pm2 show command specify name application pm2 list. usually name shell script specified, may something like pm2 show run-myfile. can peruse information keep eye restarts count applications. application restart many times, implies process crashing often, sign ’s problem code. Thankfully, pm2 automatically manages log files underlying processes. ever need check log files service, can just run pm2 logs run-myfile, myfile name service obtained pm2 list. command show last lines logged process, begin streaming incoming log lines exit (Ctrl-c). want big-picture view health server pm2 services, can run pm2 monit show dashboard RAM CPU usage services.","code":""},{"path":"https://www.rplumber.io/articles/hosting.html","id":"systemd","dir":"Articles","previous_headings":"","what":"systemd","title":"Hosting","text":"systemd service manager used certain Linux distributions including RedHat/CentOS 7, SUSE 12, Ubuntu versions 16.04 later. use Linux server can use systemd run Plumber service can accessed local network even outside network depending firewall rules. option similar using Docker method. One main advantages using systemd using Docker systemd won’t bypass firewall rules (Docker !) avoids overhead running container. Compared plumber::do_provision() option won’t create new droplet use DigitalOcean; run existing droplet instead. implement option ’ll complete following three steps terminal: Verify plumber package available globally server: Run sudo nano /etc/systemd/system/plumber-api.service, paste adapt content: Activate service (auto-start power/reboot) start : check API running, type systemctl | grep running terminal display plumber-api.service \\ loaded active running Plumber API.","code":"R -e 'install.packages(\"plumber\", repos = \"https://cran.rstudio.com/\")' [Unit] Description=Plumber API # After=postgresql # (or mariadb, mysql, etc if you use a DB with Plumber, otherwise leave this commented) [Service] ExecStart=/usr/bin/Rscript -e \"library(plumber); pr('/your-dir/your-api-script.R') %>% pr_run(port=8080, host='0.0.0.0')\" Restart=on-abnormal WorkingDirectory=/your-dir/ [Install] WantedBy=multi-user.target sudo systemctl enable plumber-api # automatically start the service when the server boots sudo systemctl start plumber-api # start the service right now"},{"path":"https://www.rplumber.io/articles/introduction.html","id":"web-apis","dir":"Articles","previous_headings":"","what":"Web APIs","title":"Introduction","text":"Hypertext Transfer Protocol (HTTP) dominant medium information exchanged Internet. Application Programming Interface (API) broad term defines rules guide interaction software. case HTTP APIs, defined set endpoints accept particular inputs. Plumber translates annotations place functions HTTP API can called machines network. execute Plumber API public server, can even make API available public Internet. HTTP APIs become predominant language software communicates. creating HTTP API, ’ll empower R code leveraged services – whether ’re housed inside organization hosted side world. just ideas doors opened wrap R code Plumber API: Software written languages organization can run R code. company’s Java application now pull custom ggplot2 graph generate -demand, Python client query predictive model defined R. can third-party receive emails behalf notify Plumber service new messages arrive. register “Slash Command” Slack, enabling execute R function response command entered Slack. can write JavaScript code queries Plumber API visitor’s web browser. Even , use Plumber exclusively back-end interactive web application.","code":""},{"path":"https://www.rplumber.io/articles/migration.html","id":"plumber-0-4-0-migration-guide","dir":"Articles","previous_headings":"","what":"Plumber 0.4.0 Migration Guide","title":"Migration Guide","text":"Plumber underwent series breaking changes part 0.4.0 release. changes made attempt rectify earlier mistakes attempt take care foreseeable breaking changes Plumber package. number changes users consider preparing upgrade plumber 0.4.0. Plumber longer accepts external connections default. host parameter run() method now defaults 127.0.0.1, meaning Plumber listen incoming requests local machine ’s running – machine network. done security reasons don’t accidentally expose Plumber API ’re developing entire network. restore old behavior Plumber listened connections machine network, use $run(host=\"0.0.0.0\"). Note ’re deploying environment includes HTTP proxy (DigitalOcean servers use nginx), Plumber listen 127.0.0.1 likely right default, proxy – Plumber – one receiving external connections. Plumber longer sets Access-Control-Allow-Origin HTTP header *. previously done convenience given security implications ’re reversing decision. previous behavior allowed web browsers make requests API domains using JavaScript request used standard HTTP headers GET, HEAD, POST request. requests longer work default. wish allow endpoint accessible origins web browser, can use res$setHeader(\"Access-Control-Allow-Origin\", \"*\") endpoint filter. Rather setting default port 8000, port now randomly selected. ensures shared server (like RStudio Server) able support multiple people developing Plumber APIs concurrently without manually identify available port. can controlled specifying port parameter run() method setting plumber.port option. object-oriented model Plumber routers changed. ’re calling following methods Plumber router, need modify code use newer alternatives: addFilter, addEndpoint, addGlobalProcessor, addAssets. code around functions undergone major rewrite breaking changes introduced. four functions still supported deprecation warning 0.4.0, support best-effort. Certain parameters methods longer supported, thoroughly test Plumber API leverages methods deploying version 0.4.0. Updated documentation using Plumber programmatically now available.","code":""},{"path":"https://www.rplumber.io/articles/programmatic-usage.html","id":"creating-and-controlling-a-router","dir":"Articles","previous_headings":"","what":"Creating and Controlling a Router","title":"Programmatic Usage","text":"centerpiece Plumber router. Plumber routers responsible coordinating incoming requests httpuv, dispatching requests appropriate filters/endpoints, serializing response, handling errors might pop along way. ’ve using annotations define Plumber APIs, ’ve already worked Plumber routers ’s plumb() command produces. instantiate new Plumber router programmatically, can call pr(). return blank Plumber router endpoints. call pr_run() returned object start API, doesn’t know respond requests incoming traffic get 404 response. ’ll see momentarily add endpoints filters onto empty router. Alternatively, can pass file contains annotation-based Plumber API first parameter create router much like plumb(). aware Plumber routers come handful filters pre-configured. built-filters used things like process properties incoming request like cookies, POST body, query string. can specify filters want new router overriding filters parameter creating new router.","code":""},{"path":"https://www.rplumber.io/articles/programmatic-usage.html","id":"defining-endpoints","dir":"Articles","previous_headings":"","what":"Defining Endpoints","title":"Programmatic Usage","text":"can define endpoints router using pr_handle(), pr_get(), pr_post(). instance, define Plumber API response GET requests / POST requests /submit, use following code: “handler” functions define calls identical code defined plumber.R file using annotations define API. route methods take additional arguments allow control nuanced behavior endpoint like filter might preempt serializer use. instance, following endpoint use Plumber’s HTML serializer.","code":"pr() %>% pr_get(\"/\", function(req, res){ # ... }) %>% pr_post(\"/submit\", function(req, res){ # ... }) pr() %>% pr_get(\"/\", function(){ \"

    Programmatic Plumber!<\/h1><\/html>\" }, serializer = plumber::serializer_html())"},{"path":"https://www.rplumber.io/articles/programmatic-usage.html","id":"defining-filters","dir":"Articles","previous_headings":"","what":"Defining Filters","title":"Programmatic Usage","text":"Use filter() method Plumber router define new filter: can specify options serializer use filter returns value pr_filter() method, well.","code":"pr() %>% pr_filter(\"myFilter\", function(req){ req$filtered <- TRUE forward() }) %>% pr_get(\"/\", function(req){ paste(\"Am I filtered?\", req$filtered) })"},{"path":"https://www.rplumber.io/articles/programmatic-usage.html","id":"router-hooks","dir":"Articles","previous_headings":"","what":"Registering Hooks on a Router","title":"Programmatic Usage","text":"Plumber routers support notion “hooks” can registered execute code particular point lifecycle request. Plumber routers currently support four hooks: preroute(data, req, res) postroute(data, req, res, value) preserialize(data, req, res, value) postserialize(data, req, res, value) access disposable environment data parameter created temporary data store request. Hooks can store temporary data hooks can reused hooks processing request. One feature defining hooks Plumber routers ability modify returned value. convention hooks : function accepts parameter named value expected return new value. unmodified version value passed , mutated value. either case, hook accepts parameter named value, whatever hook returns used new value response. can add hooks using pr_hook method, can add multiple hooks using pr_hooks method takes name list names names hooks, values handlers . Making GET request / print various information three events registered hooks.","code":"pr() %>% pr_hook(\"preroute\", function(req) { cat(\"Routing a request for\", req$PATH_INFO, \"...\\n\") }) %>% pr_hooks(list( preserialize = function(req, value) { print(\"About to serialize this value:\") print(value) # Must return the value since we took one in. Here we're not choosing # to mutate it, but we could. value }, postserialize = function(res) { print(\"We serialized the value as:\") print(res$body) } )) %>% pr_get(\"/\", function(){ 123 })"},{"path":"https://www.rplumber.io/articles/programmatic-usage.html","id":"mount-static","dir":"Articles","previous_headings":"","what":"Mounting & Static File Routers","title":"Programmatic Usage","text":"Plumber routers can “nested” mounting one another using mount() method. allows compartmentalize API paths great technique decomposing large APIs smaller files. approach used defining routers serve directory static files. Static file routers just special case Plumber routers created using pr_static(). example make files directories stored ./myfiles directory available API /assets/ path.","code":"root <- pr() users <- pr(\"users.R\") products <- pr(\"products.R\") root %>% pr_mount(\"/users\", users) %>% pr_mount(\"/products\", products) root pr() %>% pr_static(\"/assets\", \"./myfiles\") %>% pr_run()"},{"path":"https://www.rplumber.io/articles/programmatic-usage.html","id":"customize-router","dir":"Articles","previous_headings":"","what":"Customizing a Router","title":"Programmatic Usage","text":"handful useful methods aware modify behavior router. Using hooks alter request processing already discussed, additionally can modify router’s behavior using following: pr_set_serializer() - Sets default serializer router. pr_set_error() - Sets error handler gets invoked filter endpoint generates error. pr_set_404() - Sets handler gets called incoming request can’t served filter, endpoint, sub-router.","code":""},{"path":"https://www.rplumber.io/articles/quickstart.html","id":"specifying-the-inputs","dir":"Articles","previous_headings":"","what":"Specifying the Inputs","title":"Quickstart","text":"may noticed functions define endpoints accept parameters. parameters allow us customize behavior endpoints. One ways using “query strings” way passing parameters HTTP API. visit http://localhost:8000/plot?spec=setosa, see similar graph one saw , now dataset filtered include “setosa” species iris dataset. might guessed, spec=setosa portion URL sets spec parameter setosa. details Plumber processes inputs available Routing & Input article.","code":""},{"path":"https://www.rplumber.io/articles/quickstart.html","id":"customizing-the-output","dir":"Articles","previous_headings":"","what":"Customizing The Output","title":"Quickstart","text":"previous example, saw one endpoint rendered JSON one produced image. Unless instructed otherwise, Plumber attempt render whatever endpoint function returns JSON. However, can specify alternative “serializers” instruct Plumber render output format HTML (@serializer html), PNG (@serializer png), JPEG (@serializer jpeg). endpoint produce something like following, visited. also sets appropriate Content-Type header browser visits page know render result HTML. can even provide custom serializers define translate R object produced endpoint bits produce Plumber’s HTTP response. can find details Rendering & Output article.","code":"#* @get /hello #* @serializer html function(){ \"

    hello world<\/h1><\/html>\" }

    hello world<\/h1><\/html>"},{"path":"https://www.rplumber.io/articles/rendering-output.html","id":"response-object","dir":"Articles","previous_headings":"","what":"The Response Object","title":"Rendering Output","text":"plumber response object stored environment, much like request object. response object, accessible res within plumber functions, contains following objects: response object also contains following methods can invoked: methods (clone, initialize, serializer) directly invoked response object.","code":""},{"path":"https://www.rplumber.io/articles/rendering-output.html","id":"serializers","dir":"Articles","previous_headings":"","what":"Serializers","title":"Rendering Output","text":"order send response R API client, object must “serialized” format client can understand. JavaScript Object Notation (JSON) one standard commonly used web APIs. JSON serialization translates R objects like list(=123, b=\"hi!\") JSON text resembling {: 123, b: \"hi!\"}. JSON appropriate every situation, however. want API render HTML page might viewed browser, instance, need different serializer. Likewise, want return image rendered R, likely want use standard image format like PNG JPEG rather JSON. default, Plumber serializes objects JSON via jsonlite R package. However, variety serializers built package. can also pass arguments certain serializers modify behavior like example . See Serialization article details.","code":"#* @serializer json list(na=\"string\")"},{"path":"https://www.rplumber.io/articles/rendering-output.html","id":"boxed-vs-unboxed-json","dir":"Articles","previous_headings":"Serializers","what":"Boxed vs Unboxed JSON","title":"Rendering Output","text":"may noticed API responses generated Plumber render singular values (“scalars”) arrays. instance: value element, though ’s singular, still rendered array. may surprise initially, done keep output consistent. JSON differentiates scalar vector objects, R . creates ambiguity serializing R object JSON since unclear whether particular element rendered atomic value JSON array. Consider following API returns letters lexicographically “higher” given letter. example API , instance, produces scalar, instances produces vector. Visiting http://localhost:8000/boxed?letter=U http://localhost:8000/unboxed?letter=U return identical responses: However, http://localhost:8000/boxed?letter=Y produce: http://localhost:8000/unboxed?letter=Y produce: /boxed endpoint, name implies, produces “boxed” JSON output length-1 vectors still rendered array. Conversely, /unboxed endpoint sets auto_unbox=TRUE call jsonlite::toJSON, causing length-1 R vectors rendered JSON scalars. R doesn’t distinguish scalars vectors, API clients may respond differently encountering JSON array versus atomic value. may find API clients respond gracefully object expected vector becomes scalar one call. reason, Plumber inherits jsonlite::toJSON default setting auto_unbox=FALSE result length-1 vectors still rendered JSON arrays. can configure endpoint use unboxedJSON serializer (shown ) want alter behavior particular endpoint. couple functions aware around feature set. using boxed JSON serialization, jsonlite::unbox() can used force length-1 object R presented JSON scalar. using unboxed JSON serialization, () cause length-1 R object present JSON array.","code":"jsonlite::toJSON(list(a=5)) #> {\"a\":[5]} #* Get letters after a given letter #* @get /boxed function(letter=\"A\"){ LETTERS[LETTERS > letter] } #* Get letters after a given letter #* @serializer unboxedJSON #* @get /unboxed function(letter=\"A\"){ LETTERS[LETTERS > letter] } [\"V\", \"W\", \"X\", \"Y\", \"Z\"] [\"Z\"] \"Z\""},{"path":"https://www.rplumber.io/articles/rendering-output.html","id":"customizing-image-serializers","dir":"Articles","previous_headings":"Serializers","what":"Customizing Image Serializers","title":"Rendering Output","text":"@serializer jpeg @serializer png annotations cause graphical output endpoint written file returned client using jpeg() png() functions, respectively. functions accept variety additional options customize output including width, height, bg among others. version 0.4.3 plumber, annotations now accept additional arguments passed functions. enables creation endpoints like: lower level, arguments inside parentheses used arguments list() call. Meaning R code can prefixed list form valid R expression can used. example, #' @serializer png (width=2^10 + 1) valid annotation. code evaluated API plumb()d. approach can used statically define size image, work dynamic sizing image. wish dynamically size images, need render capture graphical output return contents appropriate Content-Type header. See existing image renderers model .","code":"#* Example of customizing graphical output #* @serializer png list(width = 400, height = 500) #* @get / function(){ plot(1:10) }"},{"path":"https://www.rplumber.io/articles/rendering-output.html","id":"bypassing-serialization","dir":"Articles","previous_headings":"Serializers","what":"Bypassing Serialization","title":"Rendering Output","text":"instances may desirable return value directly R without serialization. can bypass serialization returning response object endpoint. example, consider following API. response returned endpoint contain body Literal text ! Content-Type header without additional serialization. Similarly, can leverage @serializer contentType annotation serialization response specifies contentType header. can use annotation want control response send. Running API visiting http://localhost:8000/pdf download PDF generated R (display PDF natively, client supports ).","code":"#* Endpoint that bypasses serialization #* @get / function(res){ res$body <- \"Literal text here!\" res } #* @serializer contentType list(type=\"application/pdf\") #* @get /pdf function(){ tmp <- tempfile() pdf(tmp) plot(1:10, type=\"b\") text(4, 8, \"PDF from plumber!\") text(6, 2, paste(\"The time is\", Sys.time())) dev.off() readBin(tmp, \"raw\", n=file.info(tmp)$size) }"},{"path":"https://www.rplumber.io/articles/rendering-output.html","id":"error-handling","dir":"Articles","previous_headings":"","what":"Error Handling","title":"Rendering Output","text":"Plumber wraps endpoint invocation can gracefully capture errors. run API visit http://localhost:8000/simple, ’ll notice two things: HTTP response status code 500 (“internal server error”) sent client. see error message resembling: {\"error\":[\"500 - Internal server error\"],\"message\":[\"Error (function () : error!\\n\"]} similar error printed terminal ’re running Plumber API. means possible intentionally stop() endpoint filter way communicate problem user. However, may preferable render errors API consistent format helpful error messages. custom error handler can set using setErrorHandler() method: run API visit http://localhost:8000/simple, ’ll notice custom error message provided error handler included browser. Since didn’t anything actual error message, nothing printed console. wanted include error console, following: function passed setErrorHandler invoked anytime R execution fails error.","code":"#* Example of throwing an error #* @get /simple function(){ stop(\"I'm an error!\") } #* Generate a friendly error #* @get /friendly function(res){ msg <- \"Your request did not include a required parameter.\" res$status <- 400 # Bad request list(error=jsonlite::unbox(msg)) } { \"error\": \"Your request did not include a required parameter.\" } pr() %>% pr_get(\"/simple\", function() stop(\"I'm an error!\")) %>% pr_set_error(function(req, res, err){ res$status <- 500 list(error = \"An error occurred. Please contact your administrator.\") }) %>% pr_run() pr() %>% pr_get(\"/simple\", function() stop(\"I'm an error!\")) %>% pr_set_error(function(req, res, err){ print(err) res$status <- 500 list(error = \"An error occurred. Please contact your administrator.\") }) %>% pr_run()"},{"path":"https://www.rplumber.io/articles/rendering-output.html","id":"setting-cookies","dir":"Articles","previous_headings":"","what":"Setting Cookies","title":"Rendering Output","text":"part fulfilling request, Plumber API can choose set HTTP cookies client. HTTP APIs don’t implicitly contain notion “session.” Without additional information, Plumber way ascertaining whether two HTTP requests come associated user. Cookies offer way commission client store state behalf selected data can outlive single HTTP request; full implications using cookies track state API discussed . two forms Plumber cookies – plain-text encrypted – discussed following sections. make cookies important part API’s security model, sure understand section security considerations working cookies.","code":""},{"path":"https://www.rplumber.io/articles/rendering-output.html","id":"setting-unencrypted-cookies","dir":"Articles","previous_headings":"Setting Cookies","what":"Setting Unencrypted Cookies","title":"Rendering Output","text":"Plumber can set receive plaint-text cookies. API endpoint return random letter, remembers preferences whether like capitalized lower-case letters. Since API using PUT request test API, ’ll use curl command line test . (’s nothing cookies necessitates PUT requests; just easily modify API use GET request.) can start visiting /letter endpoint ’ll see API defaults lower-case alphabet. curl http://localhost:8000/letter send PUT request specify capital parameter, cookie set client allow server accommodate preference future requests. curl, need specify file want save cookies using -c option. good reminder clients handle cookies differently – won’t support – sure clients intend support API play nicely cookies want use . send PUT request, setting parameter capital 1, invoke: curl -c cookies.txt -X PUT --data 'capital=1' \"http://localhost:8000/preferences\". print cookies.txt file, now see contains single cookie called capitalize value 1. can make another GET request /letter see accommodates preferences. ’ll need tell curl use cookies file just created sending request using -b switch: curl -b cookies.txt http://localhost:8000/letter. now see API returning random capitalized letter. setCookie method accepts variety additional options customize cookie handled client. default, cookies set session lifetime, meaning cookie persist user’s browser client closes tab point cookie deleted. can customize setting expiration parameter setCookie using either number seconds future cookie expire. Alternatively, can provide object class POSIXt, case interpreted time cookie expire. options can set cookie include path (path domain cookie installed client); http (controls whether cookie accessible JavaScript running domain – TRUE means cookie HTTP-, accessible JavaScript); secure (TRUE, instructs browser send cookie HTTPS, insecure HTTP. ’re using cookies infer security-sensitive properties (identify user, determine resources client access ), sure see Security article – particular section security implications cookies.","code":"#* @put /preferences function(res, capital){ if (missing(capital)){ stop(\"You must specify a value for the 'capital' preference.\") } res$setCookie(\"capitalize\", capital) } #* @get /letter function(req) { capitalize <- req$cookies$capitalize # Default to lower-case unless user preference is capitalized alphabet <- letters # The capitalize cookie will initially be empty (NULL) if (!is.null(capitalize) && capitalize == \"1\"){ alphabet <- LETTERS } list( letter = sample(alphabet, 1) ) } { \"letter\": [\"o\"] }"},{"path":"https://www.rplumber.io/articles/rendering-output.html","id":"encrypted-cookies","dir":"Articles","previous_headings":"Setting Cookies","what":"Setting Encrypted Cookies","title":"Rendering Output","text":"addition storing plain-text cookies, Plumber also supports handling cookies encrypted. Encrypted cookies prevent users seeing stored inside also sign contents users can’t modify stored. use feature, must explicitly add router constructing . example, run following sequence commands create router supports encrypted session cookies. ’ll notice example using session_cookie hooks come Plumber. adding registering hooks router, ’ll ensure req$session object made available incoming requests persisted cookie named cookieName response ready sent user. example, key used encrypt data \"mySecretHere\", obviously weak secret key. Unlike res$setHeader(), values attached req$session serialized via jsonlite; ’re free use complex data structures like lists session. Also unlike res$setHeaders(), req$session encrypts data using secret key provide first argument session_cookie() function. example, ’ll store encrypted cookie counts many times client visited particular endpoint: , need register session_cookie() hooks router code work. inspect cookie set browser, ’ll find value encrypted time gets client. time arrives Plumber, cookie available regular R list can read modified.","code":"pr(\"myfile.R\") %>% pr_cookie(\"mySecretHere\", \"cookieName\") %>% pr_run() #* @get /sessionCounter function(req){ count <- 0 if (!is.null(req$session$counter)){ count <- as.numeric(req$session$counter) } req$session$counter <- count + 1 return(paste0(\"This is visit #\", count)) }"},{"path":"https://www.rplumber.io/articles/routing-and-input.html","id":"endpoints","dir":"Articles","previous_headings":"","what":"Endpoints","title":"Routing & Input","text":"Endpoints terminal step process serving request. endpoint can simply viewed logic ultimately responsible generating response particular request. request checked available endpoint finds endpoint willing serve point stops looking; .e. request ever processed one endpoint. create endpoint annotating function like : annotation specifies function responsible generating response GET request /hello. value returned function used response request (run serializer e.g. convert response JSON). case, GET response /hello return content [\"hello world\"] JSON Content-Type. annotations generate endpoint include: @get @post @put @delete @head map HTTP methods API client might send along request. default open page web browser, sends GET request API. can use API clients (even JavaScript inside web browser) form HTTP requests using methods listed . conventions around methods used can read . Note conventions carry security implications, ’s good idea follow recommended uses method fully understand might deviate . Note single endpoint can support multiple verbs. following function used service incoming GET, POST, PUT request /cars.","code":"#* Return \"hello world\" #* @get /hello function(){ \"hello world\" } #* @get /cars #* @post /cars #* @put /cars function(){ ... }"},{"path":"https://www.rplumber.io/articles/routing-and-input.html","id":"filters","dir":"Articles","previous_headings":"","what":"Filters","title":"Routing & Input","text":"Plumber filters can used define “pipeline” handling incoming requests. allows API authors break complex logic sequence independent, understandable steps. Unlike endpoints, request may go multiple Plumber filters response generated. Typically, Plumber router pass request defined filters attempts find endpoint satisfy request. However, endpoints can “preempt” particular filters want considered execution filter(s) registered router. Filters can one three things handling request: Forward control onto next handler, potentially mutating request. Return response forward subsequent handlers Throw error three options, might desired, discussed .","code":""},{"path":"https://www.rplumber.io/articles/routing-and-input.html","id":"forward-to-another-handler","dir":"Articles","previous_headings":"Filters","what":"Forward to Another Handler","title":"Routing & Input","text":"common behavior filter pass request next handler mutating incoming request invoking external side-effect. One common use case use filter request logger: filter straightforward: invokes external action (logging) calls forward() pass control next handler pipeline (another filter endpoint). req res parameters Plumber based R environments, exhibit “pass--reference” behavior. means changes made one filter req res object visible filters endpoints also touching request response. similar filter may mutate state request response object ’s given. case, req object going extended additional property named username represents value looked cookie. req$username property available subsequent filters endpoints processing request. (Note example secure system authentication; see section using cookies store state longer discussion .) modified request object, passes control next handler using forward().","code":"#* Log some information about the incoming request #* @filter logger function(req){ cat(as.character(Sys.time()), \"-\", req$REQUEST_METHOD, req$PATH_INFO, \"-\", req$HTTP_USER_AGENT, \"@\", req$REMOTE_ADDR, \"\\n\") plumber::forward() } #* @filter setuser function(req){ un <- req$cookies$user # Make req$username available to endpoints req$username <- un plumber::forward() }"},{"path":"https://www.rplumber.io/articles/routing-and-input.html","id":"return-a-response","dir":"Articles","previous_headings":"Filters","what":"Return a Response","title":"Routing & Input","text":"also possible filters return response. may want check request satisfies constraint (like authentication) – certain cases – return response without invoking additional handlers. example, filter used check user authenticated. common cause errors Plumber APIs forgetting invoke forward() filters. filter, result last line silently returned response incoming request. can cause API exhibit odd behavior depending ’s returned. ’re using filters, sure carefully audit code paths ensure ’re either calling forward(), causing error, intentionally returning value.","code":"#* @filter checkAuth function(req, res){ if (is.null(req$username)){ res$status <- 401 # Unauthorized return(list(error=\"Authentication required\")) } else { plumber::forward() } }"},{"path":"https://www.rplumber.io/articles/routing-and-input.html","id":"throw-an-error","dir":"Articles","previous_headings":"Filters","what":"Throw an Error","title":"Routing & Input","text":"Finally, filter can throw error. can occur mistake made code defining filter filter intentionally invokes stop() trigger error. case, request processed subsequent handlers immediately sent router’s error handler. See router customization details customize error handler.","code":""},{"path":"https://www.rplumber.io/articles/routing-and-input.html","id":"dynamic-routes","dir":"Articles","previous_headings":"","what":"Dynamic Routes","title":"Routing & Input","text":"addition hard-coded routes like /hello, Plumber endpoints can dynamic routes. Dynamic routes allow endpoints define flexible set paths match. common REST convention include identifier object API paths associated . lookup information user #13, might make GET request path /users/13. Rather register routes every user API might possibly encounter, can use dynamic route associate endpoint variety paths. API uses dynamic path /users/ match request form /users/ followed path element like number letters. case, return information user user associated ID found, empty object . can name dynamic path elements however ’d like, note name used dynamic path must match name parameter function (case, id). can even complex dynamic routes like: hard-coded dynamic examples given , parameters provided function character string.","code":"users <- data.frame( uid=c(12,13), username=c(\"kim\", \"john\") ) #* Lookup a user #* @get /users/ function(id){ subset(users, uid %in% id) } #* @get /user//connect/ function(from, to){ # Do something with the `from` and `to` variables... }"},{"path":"https://www.rplumber.io/articles/routing-and-input.html","id":"typed-dynamic-routes","dir":"Articles","previous_headings":"","what":"Typed Dynamic Routes","title":"Routing & Input","text":"Unless otherwise instructed, parameters passed plumber endpoints query strings dynamic paths character strings. example, consider following API. Visiting http://localhost:8000/types/14 return: intend support particular data type particular parameter dynamic route, can specify desired type route . Specifying type dynamic path element also narrow paths match endpoint. instance, path /users/123 match first endpoint, /users/8e3k , since 8e3k integer. following details mapping type names can use dynamic types map R data types.","code":"#* @get /type/ function(id){ list( id = id, type = typeof(id) ) } { \"id\": [\"14\"], \"type\": [\"character\"] } #* @get /user/ function(id){ next <- id + 1 # ... } #* @post /user/activated/ function(active){ if (!active){ # ... } }"},{"path":"https://www.rplumber.io/articles/routing-and-input.html","id":"static-file-handler","dir":"Articles","previous_headings":"","what":"Static File Handler","title":"Routing & Input","text":"Plumber includes static file server can used host directories static assets JavaScript, CSS, HTML files. servers fairly simple configure integrate plumber application. example expose local directory ./files/static default /public path server. file ./files/static/branding.html, available Plumber server /public/branding.html. can optionally provide additional argument configure public path used server. instance expose local directory files/static /public, /static. Likewise, serve main index.html, can also map /files/static / using enables serve /files/static/index.html http://localhost:8000/ root URL. “implementation” server examples just empty list(). can also specify function() like plumber annotations. point, implementation doesn’t alter behavior static server. Eventually, list function may provide opportunity configure server changing things like cache control settings. ’re configuring Plumber router programmatically, can instantiate special static file router mount onto another router discussed static file router section.","code":"#* @assets ./files/static list() #* @assets ./files/static /static list() #* @assets ./files/static / list()"},{"path":"https://www.rplumber.io/articles/routing-and-input.html","id":"input-handling","dir":"Articles","previous_headings":"","what":"Input Handling","title":"Routing & Input","text":"Plumber routes requests based exclusively path method incoming HTTP request, requests can contain much information just . might include additional HTTP headers, query string, request body. fields may viewed “inputs” Plumber API.","code":""},{"path":"https://www.rplumber.io/articles/routing-and-input.html","id":"the-request-object","dir":"Articles","previous_headings":"Input Handling","what":"The Request Object","title":"Routing & Input","text":"HTTP requests Plumber stored environments satisfy Rook interface. expected objects HTTP requests following.","code":""},{"path":"https://www.rplumber.io/articles/routing-and-input.html","id":"query-strings","dir":"Articles","previous_headings":"Input Handling","what":"Query Strings","title":"Routing & Input","text":"query string may appended URL order convey additional information beyond just request route. Query strings allow encoding character string keys values. example, URL https://duckduckgo.com/?q=bread&pretty=1, everything following ? constitutes query string. case, two variables (q pretty) set (bread 1, respectively). Plumber automatically forward information query string function executed aligning name query string name function parameter. following example defines search API mimics example DuckDuckGo merely prints receives. Visiting http://localhost:8000/?q=bread&pretty=1 print: equivalent calling search(q=\"bread\", pretty=\"1\"). parameter specified query string, just omitted invocation endpoint. example http://localhost:8000/?q=cereal equivalent search(q=\"cereal\"). function fall back default value pretty parameter (0), since defined function signature. Including additional query string arguments map parameter function effect. instance http://localhost:8000/?test=123 return results calling search(). (Note raw query string available req$QUERY_STRING.) web browsers impose limitations length URL. Internet Explorer, particular, caps query string 2,048 characters. need send large amounts data client API, likely better idea send request body.","code":"#* @get / search <- function(q=\"\", pretty=0){ paste0(\"The q parameter is '\", q, \"'. \", \"The pretty parameter is '\", pretty, \"'.\") } [\"The q parameter is 'bread'. The pretty parameter is '1'.\"] [\"The q parameter is 'cereal'. The pretty parameter is '0'.\"] [\"The q parameter is ''. The pretty parameter is '0'.\"]"},{"path":"https://www.rplumber.io/articles/routing-and-input.html","id":"request-body","dir":"Articles","previous_headings":"Input Handling","what":"Request Body","title":"Routing & Input","text":"Another way provide additional information inside HTTP request using message body. Effectively, client specifies metadata request (path ’s trying reach, HTTP headers, etc.) can provide message body. maximum size request body depends largely technologies involved (client, proxies, etc.) typically least 2MB – much larger query string. approach commonly seen PUT POST requests, though encounter HTTP methods. Plumber attempt parse request body one using allowed parsers. fields provided message body passed parameters function.","code":""},{"path":"https://www.rplumber.io/articles/routing-and-input.html","id":"files-handling-note","dir":"Articles","previous_headings":"Input Handling > Request Body","what":"Files handling note","title":"Routing & Input","text":"dealing binary parameters, Plumber return named list raw vector. names list original uploaded filenames. Raw values binary content file. Unfortunately, crafting request message body requires bit work making GET request query string web browser, can use tools like curl command line httr R package. ’ll use curl examples . Running curl --data \"id=123&name=Jennifer\" \"http://localhost:8000/user\" return: Alternatively, echo {\"id\":123, \"name\": \"Jennifer\"} > call.json & curl --data @call.json \"http://localhost:8000/user\" -H \"content-type: application/json\" (formatting body JSON) effect. demonstrated , raw request body made available req$bodyRaw parsed request body available req$body. multiple parameters matched endpoint formals, error thrown. Due nature multiple values can matched argument, recommended POST endpoints function definition accepts formals req, res, .... endpoint arguments processed like list, available req$argsBody, arguments req$args. req$args combination list(req = req, res = res), req$argsPath, req$argsBody, req$argsQuery.","code":"#* @post /user function(req, id, name) { list( id = id, name = name, body = req$body, raw = req$bodyRaw ) } { \"id\": [123], \"name\": [\"Jennifer\"], \"body\": { \"id\": [123], \"name\": [\"Jennifer\"] }, \"raw\": [\"aWQ9MTIzJm5hbWU9SmVubmlmZXI=\"] }"},{"path":"https://www.rplumber.io/articles/routing-and-input.html","id":"read-cookies","dir":"Articles","previous_headings":"Input Handling","what":"Cookies","title":"Routing & Input","text":"cookies attached incoming request, ’ll made available via req$cookies. contain list cookies included request. names list correspond names cookies value element character string. See Setting Cookies section details set cookies Plumber. ’ve set encrypted cookies (discussed Encrypted Cookies section), session decrypted made available req$session.","code":""},{"path":"https://www.rplumber.io/articles/routing-and-input.html","id":"headers","dir":"Articles","previous_headings":"Input Handling","what":"Headers","title":"Routing & Input","text":"HTTP headers attached incoming request attached request object. prefixed HTTP_, name header capitalized, hyphens substituted underscores. e.g. Content-Type HTTP header can found req$HTTP_CONTENT_TYPE. Running curl --header \"customheader: abc123\" http://localhost:8000 return: can print names properties attached request running print(ls(req)) inside endpoint.","code":"#* Return the value of a custom header #* @get / function(req){ list( val = req$HTTP_CUSTOMHEADER ) } { \"val\": [\"abc123\"] }"},{"path":"https://www.rplumber.io/articles/security.html","id":"networking","dir":"Articles","previous_headings":"","what":"Networking & Firewalls","title":"Security","text":"networking standpoint, two fundamentally different approaches developing R code. can develop locally using tool like RStudio Desktop. case, R session (Plumber APIs run()) housed local machine. can develop remote machine using tool like RStudio Server. , R session running remote server accessed across network. first case, ’s typically little consider networking perspective. APIs accessible http://127.0.0.1:8000 default (localhost synonymous local IP address 127.0.0.1) likely won’t need concern firewalls network proxies. second case, however, may need consider network environment server running API. considerations ’ll need make hosting API server production use. particular, investigate whether firewalls server hosting Plumber API clients want able connect. Firewalls way block undesired network traffic. desktop computers many servers come firewalls enabled ---box. means want expose API running port 8000, need configure firewall accept incoming connections port. Firewalls can also configured network intermediaries, may need configure multiple firewalls allow traffic order expose desired port API clients.","code":""},{"path":"https://www.rplumber.io/articles/security.html","id":"https","dir":"Articles","previous_headings":"","what":"HTTPS","title":"Security","text":"HTTPS secure form HTTP. Many people now aware check browser displays padlock associated HTTPS enter sensitive information like credit card number. HTTPS important consider developing Plumber APIs, well. HTTPS primarily offers two protections: encrypts information sent API client Plumber process using TLS (often still referred predecessor, “SSL”). prevents others network able read information sent back forth. gives API client confidence ’s communicating Plumber process, opposed imposter. two assurances critical API handling sensitive data performing actions intended authenticated users. hosting options support serving HTTP HTTPS simultaneously. secure configuration redirect incoming HTTP traffic HTTPS hosting option. added layer protection, can consider enabling HTTP Strict Transport Security (HSTS). HSTS way instruct clients – future – refuse connect server unsecure HTTP. ensures imposter server able trick client connecting insecure HTTP future. Unfortunately, Plumber implement HTTPS support natively, documented hosting options offer ways deploy HTTPS HSTS front Plumber API.","code":""},{"path":"https://www.rplumber.io/articles/security.html","id":"dos","dir":"Articles","previous_headings":"","what":"Denial Of Service (DoS)","title":"Security","text":"Denial service (DoS) attacks employed order temporarily shut server service overwhelming traffic. DoS scenario caused single ignorant user unintentionally making request ask server impossible task, intentionally introduced malicious actor leveraging vast number machines repeatedly make requests expensive server respond . later form often called distributed denial service attack (DDoS) typically requires special infrastructure network capacity beyond scope ’ll discuss . However, practices employ designing Plumber API put safety guards around work API request might instigate. expected output harmless plot. plot takes negligible amount time create. However, plots points take time create. plot, 10,000 points added, took 0.155 seconds generate. doesn’t sound like much, exposed API publicly Internet, attacker easily generate enough traffic endpoint overwhelm Plumber process. Even worse, attacker make request endpoint millions billions points might cause server run memory consume much CPU deprives important system resources. Either case result Plumber process crashing altogether. solution, case, ensure reasonable safety guards place user input. can see allow user request graph 1,000 points. requests exceeding limit immediately terminated without computation. attentive resources consumed filters endpoints. Consider various values user provide API endpoint’s parameters ensure behavior system reasonable cases. API endpoints require extensive computation, consider protect endpoints (perhaps exposing authenticated users) prevent malicious user abusing system.","code":"#* This is an example of an UNSAFE endpoint which #* is vulnerable to a DOS attack. #* @get / #* @serializer png function(pts=10) { # An example of an UNSAFE endpoint. plot(1:pts) } #* This is an example of an safe endpoint which #* checks user input to avoid a DOS attack #* @get / #* @serializer png function(pts=10) { if (pts > 1000 & pts > 0){ stop(\"pts must be between 1 and 1,000\") } plot(1:pts) }"},{"path":"https://www.rplumber.io/articles/security.html","id":"sanitization","dir":"Articles","previous_headings":"","what":"Sanitization & Injection","title":"Security","text":"time accept input user code, plan worst-case scenario. , example, API endpoint allows user specify name file read particular directory returns contents, might naively implement like . Unfortunately, API endpoint properly sanitize user input. user set file parameter ../plumber.R now endpoint return source code Plumber API. course just easy attempt read files might contain API keys sensitive data. One solution case strip special characters user input prevent users able escape different directory. File paths opportunity malicious input damage system, however. Another way user input can dangerous attack known “cross site scripting,” “XSS.” attack can leveraged whenever user input may rendered user’s browser. instance endpoint allows users comment page later displays comments users, attacked craft comment : can see, comment JavaScript embedded within , case used popup message user. course JavaScript used harmful way redirecting users malicious site, instance, uploading data special access server destination. user input might included HTML page properly escaped (see htmltools::html_escape help). Lastly, user input can used “injection attack,” user injects malicious commands might sent another system. best known family SQL injection attacks, user input meant included SQL query executed database might contain additional SQL commands leak data damage database. details SQL injection attacks mitigation strategies R available . summary, sure separate “trusted” “untrusted” objects API implementation. Anything user provides considered “untrusted” escaped sanitized. point can consider object “trusted” proceed take actions .","code":"#* This is an example of an UNSAFE endpoint which #* does not sanitize user input #* @get / function(file) { # An example of an UNSAFE endpoint. path <- file.path(\"./datasets\", file) readLines(path) } #* This is an example of an endpoint which #* checks user input. #* @get / function(file) { # Strip all \"non-word\" characters from user input sanitizedFile <- gsub(\"\\\\W\", \"\", file) path <- file.path(\"./datasets\", sanitizedFile) readLines(path) } \"This is a comment with JavaScript!