Help for package cookies

Title:

Use Browser Cookies with 'shiny'

Version:

0.2.3

Description:

Browser cookies are name-value pairs that are saved in a user's browser by a website. Cookies allow websites to persist information about the user and their use of the website. Here we provide tools for working with cookies in 'shiny' apps, in part by wrapping the 'js-cookie' JavaScript library https://github.com/js-cookie/js-cookie.

License:

MIT + file LICENSE

URL:

https://github.com/r4ds/cookies, https://r4ds.github.io/cookies/

BugReports:

https://github.com/r4ds/cookies/issues

Imports:

cli, clock, glue, htmltools, httpuv, jsonlite, purrr, rlang, shiny (≥ 1.6.0), stats, vctrs

Suggests:

covr, pkgdown, rmarkdown, roxygen2, testthat (≥ 3.0.0)

Config/testthat/edition:

Encoding:

UTF-8

RoxygenNote:

7.2.3

NeedsCompilation:

Packaged:

2023-10-02 16:44:59 UTC; jonth

Author:

Jon Harmon

[aut, cre, cph], Klaus Hartl [cph] (js-cookie JavaScript library), Fagner Brack [cph] (js-cookie JavaScript library)

Maintainer:

Jon Harmon <jonthegeek@gmail.com>

Repository:

CRAN

Date/Publication:

2023-10-02 17:20:02 UTC

cookies: Use Browser Cookies with 'shiny'

Description

Author(s)

Maintainer: Jon Harmon jonthegeek@gmail.com (ORCID) [copyright holder]

Other contributors:

Klaus Hartl (js-cookie JavaScript library) [copyright holder]
Fagner Brack (js-cookie JavaScript library) [copyright holder]

Condense attributes to a string

Description

Condense attributes to a string

Usage

.attributes_string(expiration, secure_only, domain, path, same_site, http_only)

Arguments

expiration

Days after which the cookie should expire. To remove an HttpOnly cookie, send a negative value for this attribute.

secure_only

Logical indicating whether the cookie should only be accessible via secure (⁠https:⁠) requests (except on localhost).

domain

The host to which the cookie will be sent (including subdomains). If this is NULL (default) the cookie will only be sent to the host of the page where this cookie was set (not including subdomains).

path

The path that must exist in the requested URL for the browser to send this cookie. Includes subdirectories.

same_site

One of "strict", "lax" (default), or "none", indicating when the cookie should be sent. When same_site = "none", secure_only must be TRUE.

http_only

Logical indicating whether the cookie should only be sent as part of an HTTP request. When this is FALSE (default), the cookie is accessible to JavaScript via the Document.cookie property.

Value

A string with a format like "Domain=domain-value; Secure; HttpOnly".

Generate the separate attribute strings

Description

Generate the separate attribute strings

Usage

.generate_http_attribute_strings(http_attributes)

Arguments

http_attributes

A list of attributes with the names expected by Set-Cookie.

Value

A character vector of either the names (for Secure or HttpOnly) or name=value pairs.

Prepare cookie attributes for HTTP

Description

Prepare cookie attributes for HTTP

Usage

.http_attributes(expiration, secure_only, domain, path, same_site, http_only)

Arguments

expiration

Days after which the cookie should expire. To remove an HttpOnly cookie, send a negative value for this attribute.

secure_only

Logical indicating whether the cookie should only be accessible via secure (⁠https:⁠) requests (except on localhost).

domain

path

The path that must exist in the requested URL for the browser to send this cookie. Includes subdirectories.

same_site

One of "strict", "lax" (default), or "none", indicating when the cookie should be sent. When same_site = "none", secure_only must be TRUE.

http_only

Logical indicating whether the cookie should only be sent as part of an HTTP request. When this is FALSE (default), the cookie is accessible to JavaScript via the Document.cookie property.

Value

A list of attributes ready for HTTP.

Condense cookie attributes to a set-cookie string

Description

Condense cookie attributes to a set-cookie string

Usage

.http_cookie_string(
  cookie_name,
  cookie_value,
  expiration,
  secure_only,
  domain,
  path,
  same_site,
  http_only
)

Arguments

cookie_name

The name of the cookie. Can contain any US-ASCII characters except for: the control character, space, a tab, or separator characters like ( ) < > @ , ; : \ " / [ ] ? = { }.

cookie_value

The contents of the cookie as a single character value.

expiration

Days after which the cookie should expire. To remove an HttpOnly cookie, send a negative value for this attribute.

secure_only

Logical indicating whether the cookie should only be accessible via secure (⁠https:⁠) requests (except on localhost).

domain

path

The path that must exist in the requested URL for the browser to send this cookie. Includes subdirectories.

same_site

One of "strict", "lax" (default), or "none", indicating when the cookie should be sent. When same_site = "none", secure_only must be TRUE.

http_only

Logical indicating whether the cookie should only be sent as part of an HTTP request. When this is FALSE (default), the cookie is accessible to JavaScript via the Document.cookie property.

Value

A string in the form "Set-Cookie: cookie-name=cookie-value; Expires=date", etc.

Convert expiration days to the expected date format

Description

Convert expiration days to the expected date format

Usage

.http_date(expiration)

Arguments

expiration

Days after which the cookie should expire. To remove an HttpOnly cookie, send a negative value for this attribute.

Value

A string of the date in the required format.

Is this cookie HttpOnly?

Description

HttpOnly cookies can't be manipulated via javascript.

Usage

.is_http_only(cookie_name, session = shiny::getDefaultReactiveDomain())

Arguments

cookie_name

The cookie to check.

session

Shiny session in which the cookies can be found (the default should probably always be used).

Value

A logical indicating whether cookie_name is http-only.

Prepare cookie attributes for javascript

Description

Prepare cookie attributes for javascript

Usage

.javascript_attributes(expiration, secure_only, domain, path, same_site)

Arguments

expiration

Days after which the cookie should expire. To remove an HttpOnly cookie, send a negative value for this attribute.

secure_only

Logical indicating whether the cookie should only be accessible via secure (⁠https:⁠) requests (except on localhost).

domain

path

The path that must exist in the requested URL for the browser to send this cookie. Includes subdirectories.

same_site

One of "strict", "lax" (default), or "none", indicating when the cookie should be sent. When same_site = "none", secure_only must be TRUE.

Value

A list of attributes with the names expected by js-cookie.

Find the main session

Description

This function escapes from a module (or submodule, etc) to find the root session.

Usage

.root_session(session = shiny::getDefaultReactiveDomain())

Arguments

session

A session object. Probably always use the default.

Value

The first session that isn't a "session_proxy".

Parameters used in multiple functions

Description

These are parameters that are likely to show up in multiple functions, so I gather their definitions in one easy-to-find place.

Arguments

attributes

A list with values for expiration, secure_only, domain, path, same_site, and http_only

cookie_name

The name of the cookie. Can contain any US-ASCII characters except for: the control character, space, a tab, or separator characters like ( ) < > @ , ; : \ " / [ ] ? = { }.

cookie_value

The contents of the cookie as a single character value.

domain

expiration

Days after which the cookie should expire. To remove an HttpOnly cookie, send a negative value for this attribute.

http_only

Logical indicating whether the cookie should only be sent as part of an HTTP request. When this is FALSE (default), the cookie is accessible to JavaScript via the Document.cookie property.

path

The path that must exist in the requested URL for the browser to send this cookie. Includes subdirectories.

same_site

One of "strict", "lax" (default), or "none", indicating when the cookie should be sent. When same_site = "none", secure_only must be TRUE.

secure_only

Logical indicating whether the cookie should only be accessible via secure (⁠https:⁠) requests (except on localhost).

session

Shiny session in which the cookies can be found (the default should probably always be used).

ui

A 0- or 1-argument function defining the ui of a shiny app, or a shiny::tagList().

Prep data for javascript

Description

This is an unexported function in shiny, and has been directly copy/pasted (other than the name and documentation). This function formats things in the way shiny's JS functions expect.

Usage

.shiny_toJSON(
  x,
  ...,
  dataframe = "columns",
  null = "null",
  na = "null",
  auto_unbox = TRUE,
  digits = getOption("shiny.json.digits", 16),
  use_signif = TRUE,
  force = TRUE,
  POSIXt = "ISO8601",
  UTC = TRUE,
  rownames = FALSE,
  keep_vec_names = TRUE,
  strict_atomic = TRUE
)

Arguments

x

the object to be encoded

...

Arguments passed on to jsonlite::toJSON

matrix: how to encode matrices and higher dimensional arrays: must be one of 'rowmajor' or 'columnmajor'.
Date: how to encode Date objects: must be one of 'ISO8601' or 'epoch'
factor: how to encode factor objects: must be one of 'string' or 'integer'
complex: how to encode complex numbers: must be one of 'string' or 'list'
raw: how to encode raw objects: must be one of 'base64', 'hex' or 'mongo'
pretty: adds indentation whitespace to JSON output. Can be TRUE/FALSE or a number specifying the number of spaces to indent. See prettify()

dataframe

how to encode data.frame objects: must be one of 'rows', 'columns' or 'values'

null

how to encode NULL values within a list: must be one of 'null' or 'list'

na

how to print NA values: must be one of 'null' or 'string'. Defaults are class specific

auto_unbox

automatically unbox() all atomic vectors of length 1. It is usually safer to avoid this and instead use the unbox() function to unbox individual elements. An exception is that objects of class AsIs (i.e. wrapped in I()) are not automatically unboxed. This is a way to mark single values as length-1 arrays.

digits

max number of decimal digits to print for numeric values. Use I() to specify significant digits. Use NA for max precision.

use_signif

Passed on to a print method.

force

unclass/skip objects of classes with no defined JSON mapping

POSIXt

how to encode POSIXt (datetime) objects: must be one of 'string', 'ISO8601', 'epoch' or 'mongo'

UTC

Passed on to a print method.

rownames

Passed on to a print method.

keep_vec_names

Passed on to a print method.

strict_atomic

Used to deal with atomic vectors and/or unboxing.

Value

Jsonified text.

Ensure cookie attributes are valid

Description

Ensure cookie attributes are valid

Usage

.validate_attributes(
  expiration,
  secure_only,
  domain,
  path,
  same_site,
  http_only
)

Arguments

expiration

Days after which the cookie should expire. To remove an HttpOnly cookie, send a negative value for this attribute.

secure_only

Logical indicating whether the cookie should only be accessible via secure (⁠https:⁠) requests (except on localhost).

domain

path

The path that must exist in the requested URL for the browser to send this cookie. Includes subdirectories.

same_site

One of "strict", "lax" (default), or "none", indicating when the cookie should be sent. When same_site = "none", secure_only must be TRUE.

http_only

Logical indicating whether the cookie should only be sent as part of an HTTP request. When this is FALSE (default), the cookie is accessible to JavaScript via the Document.cookie property.

Value

A list of attributes.

Ensure domain is valid

Description

Ensure domain is valid

Usage

.validate_domain(domain)

Arguments

domain

Value

NULL or domain as a character.

Ensure expiration is valid

Description

Ensure expiration is valid

Usage

.validate_expiration(expiration)

Arguments

expiration

Days after which the cookie should expire. To remove an HttpOnly cookie, send a negative value for this attribute.

Value

NULL or the expiration as a double.

Ensure http_only is valid

Description

Ensure http_only is valid

Usage

.validate_http_only(http_only)

Arguments

http_only

Logical indicating whether the cookie should only be sent as part of an HTTP request. When this is FALSE (default), the cookie is accessible to JavaScript via the Document.cookie property.

Value

NULL or TRUE.

Ensure the argument is a single logical value

Description

Ensure the argument is a single logical value

Usage

.validate_logical_scalar(arg_value, arg_name)

Arguments

arg_value

The value of the argument.

arg_name

The name of the argument for error messages.

Value

NULL or TRUE.

Ensure path is valid

Description

Ensure path is valid

Usage

.validate_path(path)

Arguments

path

The path that must exist in the requested URL for the browser to send this cookie. Includes subdirectories.

Value

NULL or path as a character.

Ensure same_site is valid

Description

Ensure same_site is valid

Usage

.validate_same_site(same_site, secure_only)

Arguments

same_site

One of "strict", "lax" (default), or "none", indicating when the cookie should be sent. When same_site = "none", secure_only must be TRUE.

secure_only

Logical indicating whether the cookie should only be accessible via secure (⁠https:⁠) requests (except on localhost).

Value

One of NULL, "Strict", "Lax", or "None".

Ensure the argument is a single logical value

Description

Ensure the argument is a single logical value

Usage

.validate_scalar(arg_value, arg_name, arg_type = "logical")

Arguments

arg_value

The value of the argument.

arg_name

The name of the argument for error messages.

arg_type

The expected class for error messages.

Value

The value (if it is length-1).

Ensure secure_only is valid

Description

Ensure secure_only is valid

Usage

.validate_secure_only(secure_only)

Arguments

secure_only

Logical indicating whether the cookie should only be accessible via secure (⁠https:⁠) requests (except on localhost).

Value

NULL or TRUE.

Add cookies to an existing shiny ui

Description

Wrap a shiny ui in this function in order to add cookie-handling functionality. The ui can be defined in any format compatible with shiny, using functions such as shiny::fluidPage(), shiny::bootstrapPage(), shiny::htmlTemplate(), or a raw HTML string.

Usage

add_cookie_handlers(ui)

Arguments

ui

A 0- or 1-argument function defining the ui of a shiny app, or a shiny::tagList().

Value

An object with the same signature as the input ui, but with the dependencies needed to handle cookies. If ui is a shiny::tagList(), a shiny::tagList() will be returned; if ui is a function, a function will be returned.

Examples

str(add_cookie_handlers("example"))

Attach the js-cookie javascript library for shiny

Description

Add the js-cookie Javascript library as an HTML dependency, and make cookies available in the shiny input object.

Usage

cookie_dependency()

Details

Call this function within your shiny ui to attach the necessary JavaScript code.

Value

An htmltools::htmlDependency(), which shiny uses to add the js-cookie Javascript library exactly once.

Examples

cookie_dependency()

Extract an individual cookie from a shiny request

Description

The shiny request object includes any cookies that are available to the app. This function extracts the value of a named cookie from that request.

Usage

extract_cookie(request, cookie_name, missing = NULL)

Arguments

request

A shiny request object.

cookie_name

The name of the cookie. Can contain any US-ASCII characters except for: the control character, space, a tab, or separator characters like ( ) < > @ , ; : \ " / [ ] ? = { }.

missing

The value to return if the requested cookie is not stored in the request. Defaults to NULL.

Value

The contents of that cookie.

Examples

req <- list(HTTP_COOKIE = "cookie1=expected_value; cookie2=1; cookie3=2")
extract_cookie(req, "cookie1")
extract_cookie(req, "cookie2")
extract_cookie(list(), "cookie1")
extract_cookie(NULL, "cookie1")

Extract all cookies from a shiny request

Description

The shiny request object includes any cookies that are available to the app. This function extracts those cookies as a named list.

Usage

extract_cookies(request)

Arguments

request

A shiny request object.

Value

All cookies in the request, as a list.

Examples

req <- list(HTTP_COOKIE = "cookie1=expected_value; cookie2=1; cookie3=2")
extract_cookies(req)
extract_cookies(list())
extract_cookies(NULL)

Read a cookie

Description

Read a cookie from the input object.

Usage

get_cookie(
  cookie_name,
  missing = NULL,
  session = shiny::getDefaultReactiveDomain()
)

Arguments

cookie_name

The name of the cookie. Can contain any US-ASCII characters except for: the control character, space, a tab, or separator characters like ( ) < > @ , ; : \ " / [ ] ? = { }.

missing

The value to return if the requested cookie does not exist. Defaults to NULL.

session

Shiny session in which the cookies can be found (the default should probably always be used).

Value

A character with the value of the cookie.

Examples

server <- function(input, output, session) {
  get_cookie("my_cookie")
}

Remove a cookie

Description

Instruct the user's browser to remove a cookie via JavaScript.

Usage

remove_cookie(cookie_name, session = shiny::getDefaultReactiveDomain())

Arguments

cookie_name

The name of the cookie. Can contain any US-ASCII characters except for: the control character, space, a tab, or separator characters like ( ) < > @ , ; : \ " / [ ] ? = { }.

session

Shiny session in which the cookies can be found (the default should probably always be used).

Value

A call to session$sendCustomMessage() which removes the targeted cookie.

Examples

server <- function(input, output, server) {
  shiny::observeEvent(
    input$button_that_removes_cookie,
    remove_cookie("my_cookie")
  )
}

Create or update a cookie

Description

Instruct the user's browser to create a cookie via JavaScript.

Usage

set_cookie(
  cookie_name,
  cookie_value,
  expiration = 90,
  secure_only = NULL,
  domain = NULL,
  path = NULL,
  same_site = NULL,
  session = shiny::getDefaultReactiveDomain()
)

Arguments

cookie_name

The name of the cookie. Can contain any US-ASCII characters except for: the control character, space, a tab, or separator characters like ( ) < > @ , ; : \ " / [ ] ? = { }.

cookie_value

The contents of the cookie as a single character value.

expiration

Days after which the cookie should expire. To remove an HttpOnly cookie, send a negative value for this attribute.

secure_only

Logical indicating whether the cookie should only be accessible via secure (⁠https:⁠) requests (except on localhost).

domain

path

The path that must exist in the requested URL for the browser to send this cookie. Includes subdirectories.

same_site

One of "strict", "lax" (default), or "none", indicating when the cookie should be sent. When same_site = "none", secure_only must be TRUE.

session

Shiny session in which the cookies can be found (the default should probably always be used).

Value

A call to session$sendCustomMessage() which sets the targeted cookie.

Examples

server <- function(input, output, server) {
  shiny::observeEvent(
    input$button_that_sets_cookie,
    set_cookie(
      "my_cookie",
      "the value of this cookie"
    )
  )
}

Shiny tag to add cookies on page load

Description

Generate a shiny::tagList() which uses JavaScript to set a cookie in the user's browser when the shiny app loads.

Usage

set_cookie_on_load(
  cookie_name,
  cookie_value,
  expiration = 90,
  secure_only = NULL,
  domain = NULL,
  path = NULL,
  same_site = NULL
)

Arguments

cookie_name

The name of the cookie. Can contain any US-ASCII characters except for: the control character, space, a tab, or separator characters like ( ) < > @ , ; : \ " / [ ] ? = { }.

cookie_value

The contents of the cookie as a single character value.

expiration

Days after which the cookie should expire. To remove an HttpOnly cookie, send a negative value for this attribute.

secure_only

Logical indicating whether the cookie should only be accessible via secure (⁠https:⁠) requests (except on localhost).

domain

path

The path that must exist in the requested URL for the browser to send this cookie. Includes subdirectories.

same_site

One of "strict", "lax" (default), or "none", indicating when the cookie should be sent. When same_site = "none", secure_only must be TRUE.

Value

A shiny::tagList() that provides the HTML and javascript to set the cookie.

Examples

set_cookie_on_load("my_cookie", "contents of my cookie")
set_cookie_on_load("my_cookie", "contents of my cookie", expiration = 10)

Set cookie via HTTP header

Description

Send a shiny::httpResponse() that sets a cookie in the user's browser. Note that this does not return a full shiny ui.

Usage

set_cookie_response(
  cookie_name,
  cookie_value,
  expiration = 90,
  secure_only = NULL,
  domain = NULL,
  path = NULL,
  same_site = NULL,
  http_only = FALSE,
  redirect = NULL,
  ...
)

Arguments

cookie_name

The name of the cookie. Can contain any US-ASCII characters except for: the control character, space, a tab, or separator characters like ( ) < > @ , ; : \ " / [ ] ? = { }.

cookie_value

The contents of the cookie as a single character value.

expiration

Days after which the cookie should expire. To remove an HttpOnly cookie, send a negative value for this attribute.

secure_only

Logical indicating whether the cookie should only be accessible via secure (⁠https:⁠) requests (except on localhost).

domain

path

The path that must exist in the requested URL for the browser to send this cookie. Includes subdirectories.

same_site

One of "strict", "lax" (default), or "none", indicating when the cookie should be sent. When same_site = "none", secure_only must be TRUE.

http_only

Logical indicating whether the cookie should only be sent as part of an HTTP request. When this is FALSE (default), the cookie is accessible to JavaScript via the Document.cookie property.

redirect

A relative or absolute URL where the user should be sent next. A typical case would be the same URL minus the query parameter that triggered the Set-cookie response.

...

Additional parameters passed on to shiny::httpResponse().

Value

A shiny::httpResponse() that sets the cookie.

Examples

set_cookie_response("my_cookie", "contents of my cookie")
set_cookie_response("my_cookie", "contents of my cookie", expiration = 10)
set_cookie_response(
  "my_cookie", "contents of my cookie",
  content = "Your cookie is set."
)
set_cookie_response(
  "my_cookie", "contents of my cookie",
  redirect = "/"
)

cookies: Use Browser Cookies with 'shiny'

Description

Author(s)

See Also

Condense attributes to a string

Description

Usage

Arguments

Value

Generate the separate attribute strings

Description

Usage

Arguments

Value

Prepare cookie attributes for HTTP

Description

Usage

Arguments

Value

Condense cookie attributes to a set-cookie string

Description

Usage

Arguments

Value

Convert expiration days to the expected date format

Description

Usage

Arguments

Value

Is this cookie HttpOnly?

Description

Usage

Arguments

Value

Prepare cookie attributes for javascript

Description

Usage

Arguments

Value

Find the main session

Description

Usage

Arguments

Value

Parameters used in multiple functions

Description

Arguments

Prep data for javascript

Description

Usage

Arguments

Value

Ensure cookie attributes are valid

Description

Usage

Arguments

Value

Ensure domain is valid

Description

Usage

Arguments

Value

Ensure expiration is valid

Description

Usage

Arguments

Value

Ensure http_only is valid

Description

Usage

Arguments

Value

Ensure the argument is a single logical value

Description

Usage

Arguments

Value

Ensure path is valid

Description

Usage