ratch-job

Namespaces are managed via an Actor model using NamespaceManager. The system distinguishes between Raft-replicated requests (for state changes) and standard business requests (for read-only queries).

Actor Message Types

Raft Requests (NamespaceManagerRaftReq)

Used for operations that must be synchronized across the cluster via Raft:

• AddNamespace: Creates a new namespace.
• UpdateNamespace: Modifies an existing namespace.
• Remove: Deletes a namespace.

Business Requests (NamespaceManagerReq)

Used for local, non-replicated reads:

• GetNamespace: Retrieves a single namespace by id.
• QueryNamespace: Performs paginated queries with type filtering.

Data Structures

• Namespace: The in-memory object containing id, name, and type.
• NamespaceDo: The Protobuf persistence object used for serialization.
• NamespaceInfo: The API response object used for returning namespace details.

To ensure durability and fast recovery, NamespaceManager implements snapshotting logic using the T_NAMESPACE table identifier.

Snapshot Lifecycle

1. Build Snapshot: The build_snapshot() method iterates through the in-memory BTreeMap, serializes each Namespace into a NamespaceDo protobuf object, and creates a SnapshotRecordDto with tree=T_NAMESPACE. This is sent to the SnapshotWriterActor.
2. Load Snapshot: During recovery, load_snapshot_record() identifies records marked as T_NAMESPACE, uses a BytesReader to deserialize them back into NamespaceDo, and reconstructs the in-memory state.
3. Completion: load_completed() executes initialization logic once the full state is restored.

Persistence Implementation

• Serialization: Uses to_do() to convert memory objects to Protobuf.
• Deserialization: Implements From<NamespaceDo<'_>> to convert Protobuf back to memory objects, utilizing Cow::Borrowed to minimize string copying.

You can deploy ratch-job in a single-node configuration using several methods:

Download Binary

Download the appropriate package for your system from [GitHub Releases], extract it, and run the executable.

Linux/macOS:

tar -xvf ratchjob-x86_64-apple-darwin-v0.1.4.tar.gz
./ratchjob

Windows: Run ratchjob.exe after extraction.

Note: The default console is accessible at http://127.0.0.1:8825/ratchjob/.

Docker

docker pull qingpan/ratchjob:stable
docker run --name myratchjob -p 8725:8725 -p 8825:8825 -p 8925:8925 -d qingpan/ratchjob:stable

Note: The container uses /io as the data directory.

Cargo (Rust)

cargo install ratchjob
ratchjob

Source Code

git clone https://github.com/ratch-job/ratch-job.git
cd ratch-job
cargo build --release
cargo run --release

# Example: Running via binary
tar -xvf ratchjob-x86_64-apple-darwin-v0.1.4.tar.gz
./ratchjob

ratch-job can be configured using environment variables. Below are the key configuration parameters:

A PrivilegeGroup<T> is a data model used to manage access control via whitelists and blacklists. It supports both explicit lists of items and 'all-or-nothing' modes.

Key Concepts

• Whitelist: If whitelist_is_all is true, all keys are permitted. Otherwise, only keys present in the whitelist set are permitted.
• Blacklist: If blacklist_is_all is true, all keys are denied. Otherwise, keys present in the blacklist set are denied.
• Permission Logic: A key is permitted if it is in the whitelist AND NOT in the blacklist (at_whitelist(key) && !at_blacklist(key)).
• Enabled State: If enabled is false, the group's logic is bypassed (though the implementation details of how enabled interacts with the check depend on the caller, the check_permission method specifically evaluates the lists).

Common States

• empty(): Enabled, but with empty whitelists/blacklists (effectively restrictive).
• all(): Enabled, with whitelist_is_all set to true (effectively permissive).

// Example of checking permission for a specific key
let group = PrivilegeGroup::new(flags, whitelist, blacklist);
let is_allowed = group.check_permission(&some_key);