[Proposal] Bundle Store: Adopting OCI Registry as Storage for Apache Celix

[pnoltes]

Description

ASF Celix bundles are currently distributed and loaded as ZIP files, which requires a runtime dependency on libzip. This proposal details the concept of a Bundle Store architecture designed to decouple the distribution format from runtime execution. By adopting a Content-Addressable Storage (CAS) model (aligned with the OCI Registry as Storage (ORAS) concept) bundles can be provisioned via ZIP, TAR, or OCI layers, while moving the bundle runtime usage to a directory-based system.

Rationale

• Removal of Runtime Overhead: Transitioning to a directory-based store eliminates the need for libzip and runtime decompression.
• OCI Ecosystem Alignment: Leveraging the ORAS concept for bundle distribution and possible signing.
• Security & Reliability: Explicitly separates immutable bundle code from application state.

Storage Management: celix-bnd-storage

The management of the bundle store and the association of storage tiers is handled by a new utility: celix-bnd-storage.

Configuration (~/.config/celix/bnd-storage.json)

This human-editable file defines the global environment settings:

• Storage Roots: Base paths for the Bundle Store, Persistent Storage, and Volatile Storage.
• Policy Settings: Default garbage collection (GC) rules and retention periods.

Instance (Bundle) State (/var/run/celix/instances.d/ or ~/.local/share/celix/state/instances.d/)

To ensure concurrency safety and remove the usage of a state directory in the CWD, a directory-based Instance State is introduced. Each active framework instance maintains its own JSON entry named after its SHA-256 ID. This registry tracks:

• Instance Mapping: Linkage between the Framework Instance SHA-256 and its assigned Friendly Name.
• Process Tracking: The current Process ID (PID) and start time.

Framework Instance Identification

The framework transitions from random UUIDs to deterministic SHA-256 Framework Instance IDs.

1. Identity Derivation: If an instance ID is not explicitly provided, the Celix launcher generates a SHA-256 hash based on:

• The absolute path of the application executable
• The absolute path of the current working directory (CWD).

2. Naming Approach: Instances are assigned "friendly names" (e.g., focused_hawking) mapped to the SHA-256 ID within the State Registry entries (nice to have).
3. Launcher Integration: The launcher supports the --instance_id argument to manually specify a SHA-256 ID. And optionally support a --instance_name argument.

Architecture: The 3-Tier Filesystem Model

The framework interacts with three distinct filesystem areas:

1. Bundle Store (Immutable):

• blobs/sha256/: Contains unpacked bundle content, indexed by the SHA-256 hash. If possible, these directories should be mounted or marked as read-only to ensure integrity.
• tags/<bundle_symbolic_name>/<bundle_version>: A structure of symbolic links, linking to unpacked bundle blob entries.

2. Volatile Storage:

• Located at <volatile_root>/<instance_sha256>/. Intended for tmpfs storage.

3. Persistent Storage:

• Located at <persistent_root>/<instance_sha256>/. Reserved for long-term state that survives restarts.

Proposed API Changes

The celix_bundle.h and celix_framework.h interfaces are extended:

• Immutable Resources:

  • const char* celix_bundle_getBundleStorePath(const celix_bundle_t* bnd, const char* path): Returns the absolute path to a file within the Bundle Store for the specific bundle.

• Instance Storage:

  • char* celix_bundle_getPersistentStoragePath(const celix_bundle_t* bnd): Returns the path to the persistent directory dedicated to the bundle for the specific framework instance.
  • char* celix_bundle_getVolatileStoragePath(const celix_bundle_t* bnd): Returns the path to the volatile directory for the current run.

• Framework

  • const char* celix_framework_getInstanceId(const celix_framework_t* fw): Returns the framework instance id (SHA256).
  • const char* celix_framework_getName(const celix_framework_t* fw): Returns the framework (human friendly) name.

[PengZheng]

Bundle decompression used to be a big headache for fast launch scenario. Removing it is generally welcome.

Power-cut safety of the bundle cache during bundle decompression is another big concern. In my day job, bundle cache is always clean, otherwise it always results in a corrupted one from which the application fails to start. We must take care of it when dealing with long-term state storage. @pnoltes

We need to have a good study on this and then have discussions. @xuzhenbao