Skip to contents

Create or reopen a local artifact store

Source: R/artifact-store.R
graft_store.Rd

Create or reopen a local artifact store, save opaque bytes, and resolve an exact revision. Saving grants no approval, access, or execution authority.

Usage

graft_store(
  path,
  create = FALSE,
  max_bytes = 64 * 1024^2,
  max_revision_bytes = 1024^2,
  lock_timeout = 10
)

Arguments

path

Directory for a Graft artifact store, distinct from a native graph store. Creation requires a missing or empty directory. Filesystem paths follow platform limits, independently of artifact identity byte limits.

create

Whether to create a new store. Defaults to FALSE, which reopens an existing store.

max_bytes

Maximum payload bytes per artifact to save or read in this handle. Dependency traversal also applies this limit to aggregate payloads.

max_revision_bytes

Maximum encoded metadata bytes per revision to save or read through this handle, a positive whole number. Defaults to 1 MiB (1024^2), independently of payload and dependency-count bounds. Increase it for large dependency lists, including when reopening the store.

lock_timeout

Seconds to wait while another process records a decision in the same stream. Defaults to 10. When the wait runs out, the call fails with a graft_store_busy_error and records nothing.

Value

graft_store() returns a LocalArtifactStore.

Details

Identity, media type, and reference strings are normalized to plain UTF-8 character values without R attributes.

Local stores hold trusted files. Several R processes can write to one store: content and revisions are saved under their SHA-256 digests, so concurrent saves of the same bytes agree, and decisions in a stream are serialized by a file lock, as PostgreSQL scopes are by an advisory lock. The lock is an operating-system advisory lock (via the filelock package) on a file under locks/ in the store, so it only works where the file system honours such locks; some network file systems do not. SHA-256 digests identify content and metadata. Repeating an identical save returns the same reference, while corrections retain earlier revisions. There is no mutable latest pointer.

Payloads are published before immutable revision metadata, using staged files in the destination directory. A failed save can leave unreferenced bytes; retries reuse verified content. Orphans are retained rather than deleted automatically; a replacement planned with nothing to forget (graft_plan_replacement()) copies everything but them. Every write also holds the store's lock shared; see graft_with_store_lock(). Successful reads verify metadata, payload size, and digest. Interrupted writes cannot produce a successful incomplete reference. The interface does not promise power-loss durability, authorization, erasure, or backup recovery. Applications control access and policy. Local handles have no open connections, so callers do not need to close them. For transaction-scoped database persistence, use graft_store_postgres() with the same artifact APIs.

Examples

path <- tempfile("artifacts-")
store <- graft_store(path, create = TRUE)
ref <- graft_save(store, "A retained report", "report:daily")
reopened <- graft_store(path)
graft_read(reopened, ref)@data
#> [1] "A retained report"
unlink(path, recursive = TRUE)