plumber (development version)
- Added support for Arrow IPC Streams (@josiahparry #968)
plumber 1.3.0
CRAN release: 2025-02-19
The port many now be specified as an environment variable. User-provided ports must be between 1024 and 49151 (following IANA guidelines) and may not be a known unsafe port. plumber will now throw an error if an invalid port is requested. (@shikokuchuo @gadenbuie #963)
Added support for graphic devices provided by {ragg} and {svglite} (@thomasp85 #964).
parse_rds(),parse_feather(), andparse_parquet()no longer writes data to disk during parsing (@thomasp85, #942).Returning error messages are now turned off by default rather than being turned on if running interactively and turned off if not (@thomasp85, #962).
-
New serializers:
-
serializer_excel(): Return an object serialized bywritexl::write_xlsx(@r2evans, #973).
-
-
New request body parsers:
-
parser_excel(): Parse request body as an excel workbook usingreadxl::read_excel(@r2evans, #973). This defaults to loading in the first worksheet only, you can use@parse excel list(sheet=NA)to import all worksheets. This always returns a list of frames, even if there is just one worksheet.
-
Mounts now have a dynamic
req$PATH_INFOinstead of a pre-computed value. (#888)validate_api_spec()now uses@redocly/clito validate the API spec. (#986)Added
operationIdto each operation within the auto-generated OpenAPI output. The value is similar to thePATH-VERB, e.g./users/create-POST. (#986)Added support for graphic devices provided by ragg and svglite (@thomasp85 #964)
plumber 1.2.0
CRAN release: 2022-07-09
New features
Static file handler now serves HEAD requests. (#798)
Introduces new GeoJSON serializer and parser. GeoJSON objects are parsed into
sfobjects andsforsfcobjects will be serialized into GeoJSON. (@josiahparry, #830)Add new Octet-Stream serializer. This is a wrapper around the Content Type serializer with type
application/octet-stream. (#864)Update feather serializer to use the arrow package. The new default feather MIME type is
application/vnd.apache.arrow.file. (@pachadotdev #849)Add parquet serializer and parser by using the arrow package (@pachadotdev #849)
Updated example
14-futureto usepromises::future_promise()and added an endpoint that uses coro to write simpler async / promises code (#785)Add
pathargument topr_cookie()allowing Secure cookies to define where they are served (@jtlandis #850)
Bug fixes
OpenAPI specification collision when using
examples. (@meztez #820)Static handler returns Last-Modified response header. (#798)
OpenAPI response type detection had a scoping issue. Use serializer defined
Content-Typeheader instead. (@meztez, #789)The default shared secret filter returns error responses without throwing an error. (#808)
Remove response bodies (and therefore the Content-Length header) for status codes which forbid it under the HTTP specification (e.g. 1xx, 204, 304). (@atheriel #758, @meztez #760)
Decode path URI before attempting to serve static assets (@meztez #754).
plumber 1.1.0
CRAN release: 2021-03-24
Breaking changes
Force json serialization of endpoint error responses instead of using endpoint serializer. (@meztez, #689)
When plumbing a Plumber file and using a Plumber router modifier (
#* @plumber), an error will be thrown if the original router is not returned. (#738)options_plumber()now requires that all options are named. If no option name is provided, an error with be thrown. (#746)
New features
Added option
plumber.trailingSlash. This option (which is disabled by default) allows routes to be redirected to route definitions with a trailing slash. For example, if aGETrequest is submitted to/test?a=1with no/testroute is defined, but aGET/test/route definition does exist, then the original request will respond with a307to reattempt againstGET/test/?a=1. This option will be enabled by default in a future release. This logic executed for before calling the404handler. (#746)Added an experimental option
plumber.methodNotAllowed. This option (which is enabled by default) allows for a status of405to be returned if an invalid method is used when requesting a valid route. This logic executed for before calling the default404handler. (#746)Passing
edit = TRUEtoplumb_api()will open the API source file. (#699)OpenAPI Specification can be set using a file path. (@meztez #696)
Guess OpenAPI response content type from serializer. (@meztez #684)
-
Undeprecated
Plumber$run(debug=, swaggerCallback=)and added the parameters forPlumber$run(docs=, quiet=)andpr_run(debug=, docs=, swaggerCallback=, quiet=). Now, all four parameters will not produce lingering effects on thePlumberrouter. (@jcheng5 #765)- Setting
quiet = TRUEwill suppress routine startup messages. - Setting
debug = TRUE, will display information when an error occurs. Seepr_set_debug(). - Setting
docswill update the visual documentation. Seepr_set_docs(). - Set
swaggerCallbackto a function which will be called with a url to the documentation, orNULLto do nothing. Seepr_set_docs_callback().
- Setting
To update a
PlumberEndpointpath after initialization, call the newPlumberEndpoint$setPath(path). This will update internal path matching meta data. (Active bindings were not used to avoid breaking changes.) (@blairj09 #770)PlumberStep(andPlumberEndpointandPlumberFilter) received a new field$srcrefand method$getFunc().$srcrefwill contain the correspondingsrcrefinformation from original source file.$getFunc()will return the evaluated function. (#782)Allow for spaces in
@apiTagand@tagwhen tag is surrounded by single or double quotes. (#685)
Bug fixes
Block parsing comments, tags and responses ordering match plumber api ordering. (#722)
Fixed bug where
httpuvwould return a status of500with bodyAn exception occurredif no headers were set on the response object. (#745)Fixed bug where all
pr_*()returned invisibly. Now allpr_*()methods will print the router if displayed in the console. (#740)When calling
Plumber$handle()and defining a newPlumberEndpoint,...will be checked for invalid names. (@meztez, #677)/__swagger__/now always redirects to/__docs__/, even when Swagger isn’t the selected interface. Useoptions(plumber.legacyRedirects = FALSE)to disable this behavior. (@blairj09 #694)Fixed
available_apis()bug where all packages printed all available APIs. (@meztez #708)Fixed Plumber
$routesresolution bugs. Routes are now returned in lexicographical order. (@meztez #702)Plumber will now display a circular reference if one is found while printing. (#738)
Changed
future::plan()frommultiprocesstomultisessionin example API14-futureas “Strategy ‘multiprocess’ is deprecated in future (>= 1.20.0)”. (#747)Setting options
plumber.docs.callbacktoNULLwill also set deprecated but supported optionplumber.swagger.url. (#766)
plumber 1.0.0
CRAN release: 2020-09-14
New features
Plumber router
Added support for promises in endpoints, filters, and hooks. This allows for multi-core execution when paired with
future. Seeplumb_api("plumber", "13-promises")andplumb_api("plumber", "14-future")for example implementations. (#248)Added a Tidy API for more natural usage with magrittr’s
%>%. For example, a plumber object can now be initiated and run withpr() %>% pr_run(port = 8080). For more examples, see here (@blairj09, #590)Added support for
#' @plumbertag to gain programmatic access to theplumberrouter viafunction(pr) {....}. Seesystem.file("plumber/06-sessions/plumber.R", package = "plumber")and how it adds cookie support from withinplumber.R. (@meztez and @blairj09, #568)Added
plumb_api()for standardizing where to locate (inst/plumber) and how to run (plumb_api(package, name)) plumber apis inside an R package. To view the available Plumber APIs, callavailable_apis(). (#631)-
Improved argument handling in Plumber Endpoint route definitions. See
system.file("plumber/17-arguments/plumber.R", package = "plumber")to view an example with expected output andplumb_api("plumber", "17-arguments")to retrieve the api. Improvements include:- The value supplied to
reqandresarguments in a route definition are now always Plumber request and response objects. In the past, this was not guaranteed. (#666, #637) - To assist with conflicts in argument names deriving from different locations,
req$argsQuery,req$argsPath, andreq$argsBodyhave been added to access query, path, andreq$bodyparameters, respectively. For this reason, we suggest defining routes with onlyreqandres(i.e.,function(req, res) {}) and accessing argument(s) under these new fields to avoid naming conflicts. (#637) - An error is no longer thrown if multiple arguments are matched to an Plumber Endpoint route definition. Instead, Plumber now retains the first named argument according to the highest priority match (
req$argsQueryis 1st priority, thenreq$argsPath, thenreq$argsBody). (#666) - Unnamed elements that are added to
req$argsby filters or creatingreq$argsBodywill no longer throw an error. They will only be passed through via...(#666)
- The value supplied to
OpenAPI
API Documentation is now hosted at
/__docs__. Ifswaggerdocumentation is being used,/__swagger__will redirect to/__docs__. (#654)Added OpenAPI support for array parameters using syntax
name:[type]and new typelist(synonym df, data.frame). (@meztez, #532)Added user provided OpenAPI Specification handler to Plumber router. Use
$setApiSpec()to provide a function to alter the Plumber generated OpenAPI Specification returned by Plumber router method$getApiSpec(). This also affects/openapi.jsonand/openapi.yaml(#365)(@meztez, #562)Added
validate_api_spec()to validate a Plumber API produces a valid OpenAPI Specification. (Experimental!) (#633)
Serializers
Added
as_attachment(value, filename)method which allows routes to return a file attachment with a custom name. (#585)Serializer functions can now return
PlumberEndpointpreexecandpostexechooks in addition to aserializerfunction by usingendpoint_serializer(). This allows for image serializers to turn on their corresponding graphics device before the route executes and turn the graphics device off after the route executes. (#630)PNG, JPEG, and SVG image serializers have been exported in methods
serializer_png(),serializer_jpeg(), andserializer_svg()respectively. In addition to these methods,serializer_tiff(),serializer_bmp(), andserializer_pdf()have been added. Each graphics device serializer wraps aroundserializer_device(), which should be used when making more graphics device serializers. (#630)-
New serializers
-
serializer_yaml(): Return an object serialized byyaml(@meztez, #556) -
serializer_csv(): Return a comma separated value (@pachamaltese, #520) -
serializer_tsv(): Return a tab separated value (#630) -
serializer_feather(): Return a object serialized byfeather(#626) -
serializer_text(): Return text content (#585) -
serializer_cat(): Return text content after callingcat()(#585) -
serializer_print(): Return text content after callingprint()(#585) -
serializer_format(): Return text content after callingformat()(#585) -
serializer_svg(): Return an image saved as an SVG (@pachamaltese, #398) -
serializer_headers(header_list): Method which sets a list of static headers for each serialized value. Heavily inspired from @ycphs (#455). (#585) -
serializer_write_file(): Method which wrapsserializer_content_type(), but orchestrates creating, writing serialized content to, reading from, and removing a temp file. (#660)
-
Body parsing
-
New request body parsers
-
parser_csv(): Parse request body as a commas separated value (#584) -
parser_json(): Parse request body as JSON (@meztez, #532) -
parser_multi(): Parse multi part request bodies (@meztez, #532) and (#663) -
parser_octet(): Parse request body octet stream (@meztez, #532) -
parser_form(): Parse request body as form input (@meztez, #532) -
parser_rds(): Parse request body as RDS file input (@meztez, #532) -
parser_text(): Parse request body plain text (@meztez, #532) -
parser_tsv(): Parse request body a tab separated value (#584) -
parser_yaml(): Parse request body asyaml(#584) -
parser_none(): Do not parse the request body (#584) -
parser_yaml(): Parse request body (@meztez, #556) -
parser_feather(): Parse request body usingfeather(#626) - Pseudo parser named
"all"to allow for using all parsers. (Not recommended in production!) (#584)
-
The parsed request body values is stored at
req$body. (#663)If
multipart/*content is parsed,req$bodywill contain named output fromwebutils::parse_multipart()and add the parsed value to each part. Look here for access to all provided information (e.g.,name,filename,content_type, etc). In addition,req$argsBody(which is used for route argument matching) will contain a named reduced form of this information whereparsedvalues (andfilenames) are combined on the samename. (#663)
Visual Documentation
Generalize user interface integration. Plumber can now use other OpenAPI compatible user interfaces like
RapiDoc(https://github.com/mrin9/RapiDoc) andRedoc(https://github.com/Redocly/redoc). Pending CRAN approbations, development R packages are available from https://github.com/meztez/rapidoc/ and https://github.com/meztez/redoc/. (@meztez, #562)Changed Swagger UI to use swagger R package to display the swagger page. (#365)
Added support for swagger for mounted routers (@bradleyhd, #274).
Security improvements
Secret session cookies are now encrypted using
sodium. All priorreq$sessioninformation will be lost. Please see?session_cookiefor more information. (#404)Session cookies set the
HttpOnlyflag by default to mitigate cross-site scripting (XSS). Please see?session_cookiefor more information. (#404)Wrap
jsonlite::fromJSONto ensure thatjsonlitenever reads input as a remote address (such as a file path or URL) and attempts to parse that. The only known way to exploit this behavior in plumber unless an API were using encrypted cookies and an attacker knew the encryption key in order to craft arbitrary cookies. (#325)
Breaking changes
When
plumb()ing a file (orPlumber$new(file)), the working directory is set to the file’s directory before parsing the file. When running the Plumber API, the working directory will be set to file’s directory before running.(#631)Plumber’s OpenAPI Specification is now defined using OpenAPI 3, upgrading from Swagger Specification. (#365)
Plumber router
$run()method argumentsswagger,swaggerCallbackanddebugare now deprecated. User interface and url callback are now enabled by default and managed through Plumber router$setDocs(),$setDocsCallback(), and$setDebug()methods and optionsplumber.docsandplumber.docs.callback. (@meztez, #562)plumb()now returns an object of class"Plumber"(previously"plumber"). To check if an object is a Plumber router, use new methodis_plumber(). (#653)PlumberStaticobjects now have a class of"PlumberStatic"(previously"plumberstatic"). (#653)The source files used in plumber must use the UTF-8 encoding if they contain non-ASCII characters (@shrektan, #312, #328).
options(plumber.debug)is not set anymore when running the plumber application. Instead retrieve the debug value using$getDebug()on the Plumber router directly. Ex:function(req, res) { req$pr$getDebug() }. (#639)PlumberEndpoint’s method$exec()now has a shape of$exec(req, res)(vs$exec(...)). This allows for fine tune control over the arguments being sent to the endpoint function.When creating a
PlumberFilterorPlumberEndpoint, an error will be thrown ifexprdoes not evaluate to a function. (#666)
Deprecations
Shorthand serializers are now deprecated.
@html,@json,@png,@jpeg,@svgshould be replaced with the@serializersyntax. Ex:@serializer htmlor@serializer jpeg(#630)plumberR6 object has been deprecated and renamed toPlumber.PlumberStatic’sinherited class has been updated toPlumber. (#653)hookableR6 object has been deprecated and renamed toHookable.PlumberandPlumberStep’sinherited class has been updated toHookable. (#653)addSerializer()has been deprecated in favor ofregister_serializer()(#584)getCharacterSet()has been deprecated in favor ofget_character_set()(#651)randomCookieKey()has been deprecated in favor ofrandom_cookie_key()(#651)sessionCookie()has been deprecated in favor ofsession_cookie()(#651)DigitalOcean helper functions are now defunct (
do_*()). The functionality and documentation on how to deploy to DigitalOcean has been moved toplumberDeploy(by @meztez) (#649)
Minor new features and improvements
Documentation is updated and now presented using
pkgdown(#570)New hex logo! Thank you @allisonhorst ! (#570)
Added helper method
is_plumber(pr)to determine if an object is a Plumber router. (#653)Added support for the
SameSiteCookie attribute. (@chris-dudley, #640)When calling
include_file(), thecontent_typeis automatically inferred from the file extension ifcontent_typeis not provided. (#631)When
plumb()ing a file, arguments supplied to parsers and serializers may be values defined earlier in the file. (@meztez, #620)Updated Docker files. New Docker repo is now
rstudio/plumber. Updates heavily inspired from @mskyttner (#459). (#589)Attached the Plumber router to the incoming request object at
req$pr. (@meztez, #554)Documented plumber options. Added
options_plumber(). (@meztez, #555)Fix
plumb()function whenplumb()ing a directory so thatplumber.Ris not a requirement if a validentrypoint.Rfile is found. (@blairj09, #471).If cookie information is too large (> 4093 bytes), a warning will be displayed. (#404)
Added new shorthand types for url parameters. (@byzheng, #388)
Plumber files are now only evaluated once. Prior plumber behavior sourced endpoint functions twice and non-endpoint code blocks once. (#328)
Improve speed of
canServe()method of thePlumberEndpointclass (@atheriel, #484)Get more file extension content types using the
mimepackage. (#660)Endpoints that produce images within a
promises::promise()will now use the expected graphics device. (#669)
Bug fixes
Handle plus signs in URI as space characters instead of actual plus signs (@meztez, #618)
Paths that are missing a leading
/have a/prepended to the path location. (#656)Fix possible bugs due to mounted routers without leading slashes (@atheriel, #476 #501).
Modified images serialization to use content-type serializer. Fixes issue with images pre/postserialize hooks (@meztez, #518).
Fix bug preventing error handling when a serializer fails (@antoine-sachet, #490)
Fix URL-decoding of query parameters and URL-encoding/decoding of cookies. Both now use
httpuv::decodeURIComponentinstead ofhttpuv::decodeURI. (@antoine-sachet, #462)Fixed bug where functions defined earlier in the file could not be found when
plumb()ing a file. (#416)A multiline request body is now collapsed to a single line (@robertdj, #270 #297).
Bumped version of httpuv to >= 1.4.5.9000 to address an unexpected segfault (@shapenaji, #289)
Date response header is now supplied by httpuv and not plumber. Fixes non standard date response header issues when using different locales. (@shrektan, #319, #380)
Due to incompatibilities with
multipartbody values,req$postBodywill only be calculated if accessed. It is strongly recommended to usereq$bodyRawwhen trying to create content from the input body. (#665)
plumber 0.4.6
CRAN release: 2018-06-05
- BUGFIX: Hooks that accept a
valueargument (postroute,preserialize, andpostserialize) now modify the incoming value as documented. - BUGFIX: The
postserializehook is now given the serialized data as itsvalueparameter. - BUGFIX: properly handle cookie expiration values (#216).
- Add support for tags in Swagger docs (#230).
- Optional
swaggerCallbackparameter forrun()to supply a callback function for reporting the url for swagger page. - Add RStudio Project Template to package.
plumber 0.4.4
CRAN release: 2017-12-01
- Support Expiration, HTTPOnly, and Secure flags on cookies (#87). EDIT: see #216 which prevented expiration from working.
- BUGFIX: properly handle named query string and post body arguments in mounted subrouters.
- Added support for static sizing of images.
@pngand@jpegnow accept a parenthetical list of arguments that will be passed into thepng()orjpeg()call. This enables annotations like#' @png (width = 200, height=500). - Enable
ByteCompileflag - Set working directory for DigitalOcean APIs.
- Respect
setErrorHandler - BUGFIX: export
PlumberStatic - Case-insensitive matching on
plumber.randentrypoint.rwhenplumb()ing a directory. - Support query strings with keys that appear more than once (#165)
- Fix the validation error warning at the bottom of deployed Swagger files which would have appeared any time your
swagger.jsonfile was hosted in such a way that a hosted validator service would not have been able to access it. For now we just suppress validation of swagger.json files. (#149) - Support for floating IPs in DNS check that occurs in
do_configure_https() - Make adding swap file idempotent in
do_provision()so you can now call that on a single droplet multiple times. - Support an
exithook which can define a function that will be evaluated when the API is interrupted. e.g.pr <- plumb("plumber.R"); pr$registerHook("exit", function(){ print("Bye bye!") }) - Fixed bug in which a single function couldn’t support multiple paths for a single verb (#203).
- Support negative numbers in numeric path segments (#212)
- Support
.in string path segments
plumber 0.4.2
CRAN release: 2017-07-24
- Development version for 0.4.2. Will be working to move to even/odd release cycles, but I had prematurely bumped to 0.4.0 so that one might get skipped, making the next CRAN release 0.4.2.
plumber 0.4.0
- BREAKING: Listen on localhost instead of listening publicly by default.
- BREAKING: We no longer set the
Access-Control-Allow-OriginHTTP header to*. This was previously done for convenience but we’ve decided to prioritize security here by removing this default. You can still add this header to any route you want to be accessible from other origins. - BREAKING: Listen on a random port by default instead of always on 8000. This can be controlled using the
portparameter inrun(), or by setting theplumber.portoption. - BREAKING: Removed
PlumberProcessorclass and replaced with a notion of hooks. SeeregisterHookandregisterHookson the Plumber router. - BREAKING:
addGlobalProcessormethod on Plumber routers now takes a list which are added as hooks instead of a Processor. Note thatsessionCookiehas also been updated to behave accordingly, meaning that the convention ofpr$addGlobalProcessor(sessionCookie("secret", "cookieName"))will continue to work for this release. - BREAKING:
sessionCookienow returns a list instead of a Processor. Note thataddGlobalProcessorhas also been updated to behave accordingly, meaning that the convention ofpr$addGlobalProcessor(sessionCookie("secret", "cookieName"))will continue to work for this release. - DEPRECATION: Deprecated the
addAssetsmethod on Plumber routers. UsePlumberStaticand themountmethod to attach a static router. - DEPRECATION: Deprecated the
addEndpointmethod in favor of thehandlemethod for Plumber routers. Removed support for theprocessors,params, andcommentsparameters are no longer supported. - DEPRECATION: Deprecated the
addFiltermethod on Plumber routers in favor of the newfiltermethod. Removed support for the processor parameter. - DEPRECATION: Deprecated the
addGlobalProcessormethod on Plumber routers. - The undocumented
setDefaultErrorHandlermethod on Plumber routers now takes a function that returns the error handler function. The top-level function takes a single param nameddebugwhich is managed by thedebugparameter in therun()method. - Added support for
OPTIONSHTTP requests via the@optionsannotation. - Add support for
entrypoint.Rwhenplumb()ing a directory. If this file exists, it is expected to return a Plumber router representing the API contained in this directory. If it doesn’t exist, the behavior is unaltered. If bothplumber.Randentrypoint.Rexist,entrypoint.Rtakes precedence. -
plumb()the current directory by default if no arguments are provided. - Added a
debugparameter to therunmethod which can be set toTRUEin order to get more insight into your API errors.
plumber 0.3.3
-
plumb()now accepts an argumentdir, referring to a directory containingplumber.R, which may be provided instead offile.
plumber 0.3.2
CRAN release: 2017-05-22
- Introduced the
do_provision(),do_deploy_api(),do_remove_api()anddo_configure_https()functions to provision and manage your APIs on a cloud server running on DigitalOcean. -
source()the referenced R file to plumb inside of a new environment that inherits directly from the GlobalEnv. This provides more explicit control over exactly how this environment should behave. - Added
@serializer htmlwidgetto support rendering and returning a self-contained htmlwidget from a plumber endpoint. - Properly handle cookies with no value. (#88)
- Don’t convert
+character in a query string to a space.
plumber 0.3.1
CRAN release: 2016-10-04
- Add a method to consume JSON on post (you can still send a query string in the body of a POST request as well).
plumber 0.3.0
- BREAKING CHANGE: serializer factories are now registered instead of the serializer themselves. Thus,
addSerializer()now expects a function that returns a serializer, andResponse$new()now expects a serializer itself rather than a character string naming a serializer. Internally it is the serializer itself that is attached to the response rather than the name of the serializer. This allows for a serializer to customize its behavior. - Accept an additional argument on the
@serializerannotation – R code that will be passed in as an argument to the serializer factory. See example09-content-type.
plumber 0.2.4
CRAN release: 2016-04-14
- Add a filter which parses and sets req$cookies to be a list corresponding to the cookies provided with the request.
- Responses can set multiple cookies
- Bug Fix: convert non-character arguments in setCookie to character before URL- encoding.
plumber 0.2.3
- Set options(warn=1) during execution of user code so that warnings are immediately visible in the console, rather than storing them until the server is stopped.
plumber 0.2.2
- Add
sessionCookiefunction to define a processor that can be used as a globalProcessor on a router to encrypt values from req$session and store them as an encrypted cookie in on the user’s browser. - Added
setCookiemethod to response which (primitively) allows you to set a cookie to be included in the response. - Add
addGlobalProcessormethod onplumberclass to support a processor that runs a processor only a single time, before and then after all other filters and the endpoint. - Document all public params so CHECK passes
plumber 0.2.1
- Add more
roxygen2documentation for exported functions - Remove the warning in the README as the API seems to be stabilizing.