AORP Core

AORP Core is the routing decision library for the AORP protocol. It is a minimal, opaque Rust crate: it chooses the next hop without exposing internal scores or taking dependencies on transport, crypto, or packet formats.

Note on authorship and accuracy

This repository content was generated with AI assistance. It may contain errors or inaccuracies. If you find any issue, please open an issue describing the problem. Thank you!

Structure

• src/core: core logic (decision engine, neighbor set, metrics, entropy, policies).
• src/interfaces: public API and opaque types exposed to consumers.
• src/utils: internal helpers.
• Cargo.toml: crate configuration, including cdylib for future bindings.

Next steps

1. Completar scoring/selección en core (manteniendo opacidad).
2. Ampliar tests unitarios e integración bajo tests/ (incluye propiedades estadísticas).
3. Proveer bindings (PyO3, NAPI-RS, cgo) (Planned) una vez estabilice la API.
4. Documentar guía de integración y referencia de API en docs/.

How to try it locally

1. Prereqs: Rust stable toolchain (rustup) and cargo.
2. Build check: cargo check
3. Run tests: cargo test
4. Quick smoke example (inside the repo):

cat > /tmp/aorp_smoke.rs <<'EOF'
use aorp::{DecisionEngine, NeighborSet, MetricView, PolicyConstraints, DecisionConfig, EntropySource};

fn main() {
    let mut engine = DecisionEngine::new(DecisionConfig::new(None));
    let neighbors = NeighborSet::from_peers(["n1", "n2", "n3"]);
    let metrics = MetricView::builder()
        .add_latency_bucket(aorp::interfaces::types::NeighborId("n1".into()), aorp::interfaces::types::LatencyBucket::Low)
        .add_bandwidth_rank(aorp::interfaces::types::NeighborId("n1".into()), aorp::interfaces::types::BandwidthRank::High)
        .build();
    let policies = PolicyConstraints::builder()
        .require_diversity(aorp::interfaces::types::DiversityLevel::Medium)
        .latency_weight(2)
        .bandwidth_weight(1)
        .build();
    let hop = engine.decide_next_hop(neighbors, metrics, EntropySource::secure_random(), policies);
    println!("Next hop: {:?}", hop);
}
EOF
cargo run --quiet --bin aorp_smoke 2>/dev/null || rustc -L target/debug -L target/debug/deps /tmp/aorp_smoke.rs && /tmp/aorp_smoke

You can also move the snippet to examples/ and run cargo run --example <name>.

Integration in Taior or other projects

As a Rust dependency

1. In your project Cargo.toml:

   [dependencies]
   aorp = { git = "https://github.com/taiorproject/aorp-core", branch = "main" }

2. Basic usage in code:

   use aorp::{DecisionEngine, NeighborSet, MetricView, PolicyConstraints, DecisionConfig, EntropySource};
   let mut engine = DecisionEngine::new(DecisionConfig::new(Some(5)));
   let neighbors = NeighborSet::from_peers(["n1", "n2"]);
   let metrics = MetricView::builder()
       .add_latency_bucket(aorp::interfaces::types::NeighborId("n1".into()), aorp::interfaces::types::LatencyBucket::Low)
       .build();
   let policies = PolicyConstraints::builder().require_diversity(aorp::interfaces::types::DiversityLevel::Medium).build();
   let hop = engine.decide_next_hop(neighbors, metrics, EntropySource::secure_random(), policies);

Language bindings (Planned)

• El crate compila como cdylib y permite FFI, pero los bindings Python/Node/Go aún no están implementados; lo anterior es roadmap.
• Mantener la interfaz opaca: exponer inputs (neighbors, metrics, policies) y NextHop, nunca puntuaciones.

Considerations for Taior

• Taior builds NeighborSet from its discovery layer and MetricView from its latency/bandwidth measurements.
• Use EntropySource::from_seed in tests/e2e for reproducible routes; secure_random in production.
• Respect Taior-specific PolicyConstraints (e.g., avoid loops, hop limits, diversity).
• Use examples/route_flow.rs as guidance for multi-hop orchestration and dynamic metric adjustments.
• For debugging, instrument only external layers (e.g., logging before/after decide_next_hop), never inside the engine to avoid leaking heuristics.

Visual overview and mathematical model

Decision flow (opaque)

flowchart TD
    A[NeighborSet] --> B[Normalize metrics*]
    C[PolicyConstraints] --> D[Apply weights & filters]
    B --> D
    D --> E[Order by score]
    E --> F{Diversity N}
    F --> G[Top-N pool]
    G --> H[Random pick with EntropySource]
    H --> I[NextHop]

Loading

Normalize metrics*: hoy las métricas ya llegan categorizadas (buckets/ranks); no se aplica normalización adicional en el motor.

Features

• standard-entropy, basic-scoring, research, minimal existen en Cargo.toml pero aún no habilitan código condicional. Se mantendrán como placeholders hasta definir variantes reales.

Scoring and selection formulas

1. Per-neighbor score (kept opaque to the consumer):

$$S(v) = w_\ell \cdot L(v) + w_b \cdot B(v)$$

• (w_\ell =) latency_weight, (w_b =) bandwidth_weight.
• (L(v) \in {1,2,3}) maps latency buckets (High→1, Medium→2, Low→3).
• (B(v) \in {1,2,3}) maps bandwidth ranks (Low→1, Medium→2, High→3).

1. Diversity selection:

• Sort neighbors by (S(v)) descending.
• Take a pool of size (N) per diversity:
  • Low / None → (N=1)
  • Medium → (N=2)
  • High → (N=3)
• Pick uniformly at random within the pool using EntropySource.

1. Early rejection policies:

• max_hops == 0 → no choice.
• avoid_loops with only 1 neighbor → no choice.
• No neighbors → no choice.