
```{r}
library("vcr")
```

You can also get the default configuration variables via `vcr_config_defaults()`

```{r}
vcr_config_defaults()
```

These defaults are set when you load `vcr` - you can override any of them as described below.

## Set configuration variables

Use `vcr_configure()` to set configuration variables.

For example, set a single variable:

```{r}
vcr_configure(
  dir = "foobar/vcr_cassettes"
)
```

Or many at once:

```{r}
vcr_configure(
  dir = "foobar/vcr_cassettes",
  record = "all"
)
```

## Re-set to defaults

```{r}
vcr_configure_reset()
```

## Details on some of the config options

### dir

Directory where cassettes are stored

```{r}
vcr_configure(dir = "new/path")
```

### record

The record mode

One of: 'all', 'none', 'new_episodes', 'once'. See `?recording` for info on the options

```{r}
vcr_configure(record = "new_episodes")
```

### match_requests_on 

Customize how `vcr` matches requests

```{r}
vcr_configure(match_requests_on = c('query', 'headers'))
```

### allow_unused_http_interactions 

Allow HTTP connections when no cassette

Default is `TRUE`, and thus does not error when http interactions are unused. You 
can set to `FALSE` in which case vcr errors when a cassette is ejected and 
not all http interactions have been used.

```{r}
vcr_configure(allow_unused_http_interactions = FALSE)
```

### serialize_with

Which serializer to use. Right now only option is "yaml"

```{r}
vcr_configure(serialize_with = "yaml")
```

### persist_with

Which persister to use. Right now only option is "FileSystem"

```{r}
vcr_configure(persist_with = "FileSystem")
```

### ignoring some requests

**ignore_hosts**

Specify particular hosts to ignore. By ignore, we mean that 
real HTTP requests to the ignored host will be allowed to occur, while
all others will not.

```{r}
vcr_configure(ignore_hosts = "google.com")
```

**ignore_localhost**

Ignore all localhost requests

```{r}
vcr_configure(ignore_localhost = TRUE)
```

**ignore_request**

THIS DOESN'T WORK YET

**How to ignore requests**

For ignoring requests, you can for example, have real http requests go through (ignored by `vcr`) while other requests are handled by `vcr`. For example, let's say you want requests to `google.com` to be ignored:

```{r eval=FALSE}
vcr_configure(ignore_hosts = "google.com")
use_cassette("foo_bar", {
  crul::HttpClient$new("https://httpbin.org/get")$get()
  crul::HttpClient$new("https://google.com")$get()
})
```

The request to httpbin.org will be handled by `vcr`, a cassette created for the request/response to that url, while the google.com request will be ignored and not cached at all.

Note: ignoring requests only works for the `crul` package for now; it should work for `httr` in a later `vcr` version.

### uri_parse

Which uri parser to use

By default we use `crul::url_parse`, but you can use a different one. Remember 
to pass in the function quoted, and namespaced.

```{r}
vcr_configure(uri_parser = "urltools::url_parse")
```

### preserve_exact_body_bytes

Some HTTP servers are not well-behaved and respond with invalid data. Set 
`preserve_exact_body_bytes` to `TRUE` to base64 encode the result body in 
order to preserve the bytes exactly as-is. `vcr` does not do this by
default, since base64-encoding the string removes the human readability 
of the cassette.

```{r}
vcr_configure(preserve_exact_body_bytes = TRUE)
```

### filter_sensitive_data 

A named list of values to replace. Sometimes your package or script is 
working with sensitive tokens/keys, which you do not want to accidentally 
share with the world.

Before recording (writing to a cassette) we do the replacement and then when
reading from the cassette we do the reverse replacement to get back
to the real data.

```r
vcr_configure(
  filter_sensitive_data = list("<some_api_key>" = Sys.getenv('MY_API_KEY'))
)
```

Before recording to disk, the env var `MY_API_KEY` is retrieved from your machine, 
and we find instances of it, and replace with `<some_api_key>`. When replaying 
to create the HTTP response object we put the real value of the env var 
back in place.

To target specific request or response headers see `filter_request_headers`
and `filter_response_headers`.

### filter_request_headers

Expects a character vector or a named list. If a character vector, or any
unnamed element in a list, the request header is removed before being 
written to the cassette.

If a named list is passed, the name is the header and the value is the
value with which to replace the real value.

A request header you set to remove or replace is only removed/replaced
from the cassette, and any requests using a cassette, but will still be in
your crul or httr response objects on a real request that creates the
cassette.

Examples:

```r
vcr_configure(
  filter_request_headers = "Authorization"
)
vcr_configure(
  filter_request_headers = c("Authorization", "User-Agent")
)
vcr_configure(
  filter_request_headers = list(Authorization = Sys.getenv('MY_API_KEY'))
)
```

### filter_response_headers

Expects a character vector or a named list. If a character vector, or any
unnamed element in a list, the response header is removed before being
written to the cassette.

If a named list is passed, the name is the header and the value is the
value with which to replace the real value.

A response header you set to remove or replace is only removed/replaced
from the cassette, and any requests using a cassette, but will still be in
your crul or httr response objects on a real request that creates the
cassette.

Examples:

```r
vcr_configure(
  filter_response_headers = "server"
)
vcr_configure(
  filter_response_headers = c("server", "date")
)
vcr_configure(
  filter_response_headers = list(server = "fake-server")
)
```
