github.com/containerpak/storage defines the versioned storage driver contract used by cpak. A driver prepares persistent native directories for immutable OCI layers. cpak records those directories in an atomic runtime index and passes them directly to rootless OverlayFS when an application starts.
Storage engines use this module as their common boundary. cpak ships FVS and DaBaDee implementations, and external drivers can implement the protocol in any language.
Protocol v1 uses one newline-terminated JSON request and response per Unix socket connection. Frames are limited to 1 MiB. The server rejects unknown JSON fields, unsupported versions, duplicate layer identifiers, invalid identifiers, and peers with a different user ID.
Supported methods:
| Method | Purpose |
|---|---|
probe |
Return driver identity, version, protocol, and capabilities. |
prepare |
Prepare persistent native checkouts and return OverlayFS lower directories. |
verify |
Check derived layer data and optionally repair it from the source store. |
remove |
Remove derived data for selected layers. |
gc |
Report or remove derived data not referenced by live layers. |
shutdown |
Stop the on-demand driver process. |
Requests contain immutable layer identifiers and operation flags. Source paths and driver roots are process configuration, not protocol input. Returned directories must resolve below the root assigned to the driver.
See docs/protocol-v1.md for the wire format and lifecycle.
Implement driver.Handler, expose it through driver.Server, then run the shared conformance suite:
func TestDriver(t *testing.T) {
conformance.Run(t, conformance.Harness{
New: newTestDriver,
Root: testDriverRoot,
Seed: seedTestLayer,
})
}pkg/index provides the atomic runtime index used after preparation. Application launch reads this index without starting a driver.
cpak starts an external driver only for preparation, verification, removal, or garbage collection. The process receives its socket, source root, driver root, and selected driver name as arguments. It runs without network access and with filesystem access restricted to those roots when the host supports the required kernel controls. cpak fails closed when an external driver cannot be confined. A driver shipped beside the official cpak binary is trusted as part of that installation.
Set CPAK_STORAGE_DRIVER to select a configured driver. Set CPAK_STORAGE_DRIVER_BINARY only while developing or deploying an external implementation.
The protocol is versioned independently from cpak and each storage engine. A new protocol version must use additive migration tooling or a new major module path. A driver must keep prepared data private to its assigned root and treat it as rebuildable derived state.
cpak storage is licensed under LGPL-2.1-only.
