Introduction to pslr

section = "private" fall-through

When you restrict to a section and the host matches no explicit rule there, the query falls through to the implicit default rule rather than failing. A plain ICANN host queried under section = "private" therefore resolves to its own last label via the default rule:

public_suffix("example.com", section = "private")
#> [1] "com"

To distinguish “no explicit rule matched” from a real match, combine the section with unknown = "na" (below).

Explicit-membership queries

is_public_suffix() reports whether a host is itself a public suffix. Under the default policy an unlisted single label is TRUE via the implicit rule; use unknown = "na" to test explicit list membership instead.

is_public_suffix("co.uk")
#> [1] TRUE
is_public_suffix("madeuptld") # TRUE via the implicit default rule
#> [1] TRUE
is_public_suffix("madeuptld", unknown = "na") # explicit membership only
#> [1] NA

Why “check due” is not “update available”

These are different kinds of statement, and conflating them is the mistake this design exists to avoid.

check_due is about your knowledge: some days have passed since anything last confirmed this snapshot, so a check is worth making. It says nothing whatsoever about upstream. The list may not have changed in months.

update_available is about upstream: a check actually ran, and the source reported a checksum that differs from the snapshot you are looking at. That is an observation, and pslr will only ever make it after a real check.

Elapsed time alone therefore never produces update_available. A year-old snapshot that nobody has checked is never_checked, not “outdated” — because nothing in the local state knows whether it is out of date. (This is why the old psl_outdated() was removed: a Boolean derived from the list date could only ever answer the age question while sounding like it answered the upstream one.)

ETag and Last-Modified versus SHA-256

Two different identifiers do two different jobs, and they are not interchangeable.

A SHA-256 checksum identifies bytes. pslr computes it over the exact source bytes of every snapshot, and it is the package’s own, verifiable answer to “are these the same list?” Two snapshots with the same SHA-256 are the same list; a stored file whose bytes no longer hash to its name is corrupt. Checksums are computed locally, so nothing upstream has to be trusted for them to mean something.

An ETag or Last-Modified value is an opaque token the server issues for one URL. pslr stores it and sends it back on the next check, which lets the server answer 304 Not Modified and skip resending a list that has not changed — a courtesy to publicsuffix.org and a saving for you. But a validator proves nothing about content: it is scoped to the server that issued it, it can change while the bytes do not, and it is never used as an integrity or authenticity check. Downloaded bytes are always hashed and fully validated on their own merits.

The four successful refresh outcomes

A successful psl_refresh() returns invisibly with exactly one outcome:

downloaded_unchanged is the honest name for the case where no validator was usable, so the list had to be fetched to find out that it was identical.

Anything that is not one of those four is a failure, and failures are classed errors rooted at pslr_refresh_error — never a success-shaped result. A failed refresh leaves the cache, the selected snapshot, and the active matcher exactly as they were.

Courtesy: no more than daily

The Public Suffix List asks clients to download it no more than once a day. An ordinary psl_refresh() therefore makes no request at all while the last successful check is inside a courtesy window of at least 24 hours; it returns skipped_recently without touching the network. If the server advertises longer freshness, the window follows it, up to a 30-day cap.

force = TRUE bypasses that local window and nothing else. It is not an unconditional download: the request it makes still carries a validator when one is available, so upstream can still answer 304.

Opt-in reminders

Reminders are off until you turn them on, and they never make a request. When enabled, a direct library(pslr) prints at most one startup message per R session, and only for the three states where local evidence supports advice: never_checked, check_due, and update_available.

psl_reminder(enable = TRUE) # weekly by default
psl_reminder(enable = TRUE, every = 30) # or a month
psl_reminder(enable = FALSE) # off; the interval is remembered
psl_reminder() # just query, writes nothing

The preference is configuration rather than cache: it lives under tools::R_user_dir("pslr", "config"), so refreshing, pruning, or deleting the snapshot cache never changes it. suppressPackageStartupMessages() silences the message as usual, and a package that merely imports the namespace never triggers it.

Note that a reminder is a prompt to check, not a claim that something changed — with the one exception of update_available, where the newer snapshot is already stored locally and the message suggests activating it with psl_use("cache") rather than downloading anything again.

Refreshing on a schedule

pslr installs no scheduler, runs no daemon, and starts no background request. If you want a daily or weekly refresh, drive it from a scheduler you already have, with a one-line script:

# refresh-psl.R
pslr::psl_refresh()

# cron: every day at 04:30
30 4 * * * Rscript /path/to/refresh-psl.R

# or a weekly GitHub Actions / systemd timer / Task Scheduler entry

Because psl_refresh() enforces the courtesy window itself, over-scheduling is harmless: extra runs return skipped_recently without making a request. Nothing is activated unless you pass activate = TRUE, so a scheduled refresh stages new bytes and leaves it to the next session to pick them up.

Snapshots, retention, and pruning

Every distinct validated download is preserved by its checksum until you explicitly remove it. psl_snapshots() lists what this installation can resolve — one row per distinct SHA-256, so bytes stored twice collapse into one row:

snapshots <- psl_snapshots()
snapshots[c("checksum", "bundled", "size", "integrity")]
#>                                                                  checksum
#> 1 sha256:00dda6fa84060cca59415b5ba30bbe9d6700deb78d177f59fc83673531e30099
#>   bundled   size integrity
#> 1    TRUE 335611        ok

psl_cache_prune() is the explicit, offline, destructive counterpart. It protects the selected cache snapshot, every snapshot any source record still names, the snapshot active in this session, and the keep most recently retrieved snapshots beyond those:

psl_cache_prune() # referenced snapshots, plus one more
psl_cache_prune(keep = 0) # referenced snapshots only

Keeping history is not an accident: stable checksums are the seam psl_diff() needs to say what changed between two snapshots. Pruning to keep = 0 gives that up in exchange for disk.

Comparing two snapshots

psl_diff(old, new) reports which rules were added, removed, or changed between two snapshots — offline, from bytes already on this machine. The usual comparison is the snapshot you installed against one you have since retrieved:

# After at least one psl_refresh(), the cache selection is a second snapshot:
changes <- psl_diff("bundled", "cache")
table(changes$change)
head(changes)

That works only once local collection has started. Installing pslr makes no request and gives you exactly one snapshot: the bundled one. The first explicit psl_refresh() is what begins the history — from then on every distinct validated download is retained by checksum until you prune it, and each retained file is a valid old or new. Any path from psl_snapshots() can be passed directly, as can a historical revision you materialized as a file by other means; psl_diff() resolves no dates and downloads nothing.

Either side also accepts a source-file path, a psl_engine(), or a psl_rules()-shaped table, which is enough to see the semantics without a cache:

write_list <- function(private) {
  path <- tempfile(fileext = ".dat")
  writeLines(
    c(
      "// ===BEGIN ICANN DOMAINS===",
      "com",
      "// ===END ICANN DOMAINS===",
      "// ===BEGIN PRIVATE DOMAINS===",
      private,
      "// ===END PRIVATE DOMAINS==="
    ),
    path
  )
  path
}

psl_diff(
  write_list(c("a.example.com", "*.b.example.com")),
  write_list(c("b.example.com", "c.example.com"))
)
#>    change          rule        old_rule      new_rule old_kind new_kind
#> 1 removed a.example.com   a.example.com          <NA>   normal     <NA>
#> 2 changed b.example.com *.b.example.com b.example.com wildcard   normal
#> 3   added c.example.com            <NA> c.example.com     <NA>   normal
#>   old_section new_section
#> 1     private        <NA>
#> 2     private     private
#> 3        <NA>     private

A row is keyed on a rule’s logical identity — its canonical labels with any leading *. or ! removed — so *.b.example.com becoming b.example.com is one changed row rather than an unrelated removal and addition. A rule moving between the ICANN and PRIVATE sections is changed for the same reason. The comparison happens after parsing and canonicalization, so comments, blank lines, whitespace, letter case, source ordering, and raw Unicode spelling never appear as changes. Two snapshots that agree return the same columns with zero rows.

psl_diff() never activates anything: both sides resolve independently, and the session-global list keeps answering from whatever psl_use() last selected. Provenance travels with the result as attributes, so a diff can be filed alongside the identities it compared:

d <- psl_diff("bundled", "bundled")
attr(d, "old_version")[c("source", "checksum")]
#>    source
#> 1 bundled
#>                                                                  checksum
#> 1 sha256:00dda6fa84060cca59415b5ba30bbe9d6700deb78d177f59fc83673531e30099