# `radicle-job`

A crate for all† your automated job needs on the [Radicle

Network](https://radicle.xyz).

†: _well maybe almost all._

## Overview

`radicle-job` provides a collaborative framework for managing automated tasks

across the Radicle peer-to-peer network. Multiple nodes can pick up and execute

jobs (like CI/CD pipelines) for any given Git commit, with results synchronized

across the network using Radicle's Collaborative Objects (COBs).

### Key Features

- **Decentralized Execution**: Any node in the network can pick up and run jobs

- **Collaborative Tracking**: Multiple nodes can contribute runs for the same

  job

- **Rich Status Reporting**: Track job lifecycle from start to completion with

  success/failure reasons

- **External Log Integration**: Link to external logging services via URLs

- **Git Integration**: Jobs are tied to specific Git commits using OIDs

## Key Concepts

- **Job**: Represents an automated task for a specific Git commit that can be

  executed by multiple nodes

- **Run**: A single execution attempt of a job by a particular node, identified

  by a UUID

- **Status**: The current state of a run (`Started`, `Finished(Succeeded)`,

  `Finished(Failed)`)

- **COB (Collaborative Object)**: The underlying Radicle primitive that enables

  decentralized synchronization of job data

## Installation

Add this to your `Cargo.toml`:

```toml

[dependencies]

radicle-job = "0.1"

radicle >= "0.15" # Required for core Radicle functionality

```

This crate is designed to work seamlessly with the

[`radicle`](https://crates.io/crates/radicle) ecosystem.

## Quick Start

### Creating and Managing Jobs

```rust

use radicle_job::{Jobs, Reason};

use radicle::git::Oid;

use url::Url;

use uuid::Uuid;

// Open the jobs store for a repository

let mut jobs = Jobs::open(&repo)?;

// Create a new job for a specific commit

let commit_oid = /* your commit OID */;

let mut job = jobs.create(commit_oid, &signer)?;

// Node starts a run

let run_id = Uuid::new_v4();

let log_url = Url::parse("https://ci.example.com/logs/run-123")?;

job.run(run_id, log_url, &signer)?;

// Node reports completion

job.finish(run_id, Reason::Succeeded, &signer)?;

```

### Querying Job Status

```rust

// Get all runs that are currently in progress

let started_runs = job.started();

// Get successful runs from all nodes

let successful_runs = job.succeeded();

// Get the latest run from a specific node

if let Some((uuid, run)) = job.latest_of(&node_id) {

    println!("Latest run: {} - Status: {:?}", uuid, run.status());

    println!("Logs available at: {}", run.log());

}

// Partition runs by status

let all_nodes_status = job.partition();

for (node_id, (started, succeeded, failed)) in all_nodes_status {

    println!("Node {}: {} started, {} succeeded, {} failed", 

             node_id, started.len(), succeeded.len(), failed.len());

}

```

## Use Cases

### Continuous Integration

The primary use case is distributed CI execution:

1. A developer creates a patch

2. The job is broadcast to the network

3. Available CI nodes pick up the job and execute tests

4. Results are reported back with logs and status

5. The developer can see which nodes ran CI and their results

### Future Possibilities

- **Continuous Deployment**: Automated deployment pipelines

- **Code Analysis**: Static analysis, security scanning, performance

  benchmarking

- **Marketplace**: Nodes could offer specialized compute resources for different

  job types

## API Overview

### Core Types

- **`Jobs<R>`**: The main store for managing jobs in a repository

- **`Job`**: A read-only view of a job and its runs across all nodes

- **`JobMut`**: A mutable job handle for adding runs and updating status

- **`Run`**: Represents a single execution attempt with status and log URL

- **`Runs`**: A collection of runs with insertion-order iteration

### Key Methods

- **`Jobs::create()`**: Create a new job for a commit

- **`Jobs::get()`** / **`Jobs::get_mut()`**: Retrieve existing jobs

- **`JobMut::run()`**: Start a new run

- **`JobMut::finish()`**: Mark a run as completed

- **`Job::latest()`**: Get the most recent run

## Collaborative Nature

Jobs in `radicle-job` are inherently collaborative:

- **Multiple Executors**: Many nodes can run the same job independently

- **Decentralized Results**: Each node reports its own results without requiring

  coordination

- **Automatic Synchronization**: The Radicle protocol handles data

  synchronization across nodes

- **No Consensus Required**: This crate doesn't enforce consensus on results —

  that's left to higher-level applications

This design enables resilient, distributed job execution where no single point

of failure can prevent job completion.

## License

This project is licensed under the [MIT License](LICENSE-MIT) or [Apache License

2.0](LICENSE-APACHE) at your option.

## Related Projects

- [`radicle`](https://crates.io/crates/radicle) - Core Radicle protocol

  implementation

- [`radicle-ci-broker`](https://crates.io/crates/radicle-ci-broker) - Radicle

  library for brokering CI events