Skip to contents

ic_session_bytes() serialises a session (Icechunk's own Session::as_bytes) behind a small header: "ICR1", a u16 little-endian length, the icechunk crate version, then the payload. Any consumer built against the same icechunk version can rebuild the session (e.g. pizzarr's zarrs backend) and read or write at native speed.

Usage

ic_session_bytes(session)

ic_session_from_bytes(bytes)

ic_session_fork(session)

ic_session_merge(session, bytes)

Arguments

session

an icechunk_session.

bytes

a raw vector from ic_session_bytes().

Value

raw vector; a session; or nothing.

Details

For writes, hand out a ic_session_fork() of a writable session, take the consumer's bytes back with ic_session_merge(), then ic_commit() the base session. Commit authority stays here.

The bytes carry credentials. They hold the repository storage (bucket, prefix, endpoint, and its credentials) and the virtual chunk authorisations the repository was opened with. Static keys given to ic_storage_s3() or to ic_cred_s3()("static", ...) are in the bytes in plain text (verified for icechunk 2.3.1: S3ObjectStoreBackend and S3Storage serialise their credentials field, and so does the virtual chunk resolver). "from_env" and "anonymous" credentials carry no secret: the consumer resolves them from its own environment. Prefer those when bytes leave the process, and never log or persist bytes made with static keys.

Examples

ex <- ic_example_repo()
repo <- ic_repo_open(ex$path, authorize = ex$authorize)
s <- ic_session_writable(repo, "main")

# hand a session to another process (or package) as bytes ...
b <- ic_session_bytes(s)
b
#> <icechunk_session_bytes> 915 bytes, icechunk 2.3.1
s2 <- ic_session_from_bytes(b)
ic_set(s2, "small/c/0/0", writeBin(as.double(6:1), raw(), size = 8, endian = "little"))

# ... and merge its changes back before committing
ic_session_merge(s, ic_session_bytes(s2))
ic_status(s)
#> <icechunk_diff>
#>   updated chunks: 1 
ic_commit(s, "written elsewhere")
#> [1] "96BA01HF63H8QVX5TYD0"