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)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"