Home /Modules/docs/preferred-routers.md

preferred-routers.md

docs/modules/tutorials/preferred-routers.md · 163 line(s) · markdown

<img align="right" src="../../../images/sleela/sleela-medium-profile-permanent-icon-002.jpg" width="45" height="45" alt="SLeeLa">

preferred-routers: Tutorial

Natureprotocol (bin/sleelactl help preferred-routers)
Registry summaryPreferred-router selection model
Lives inpreferred-routers/
Writeup typeTutorial, because the C selector can be compiled and called from a short program, and every step below ran. The module's own Makefile only syntax-checks, so the program is one you write.
Verified2026-11-13 against master e048707fd: bin/sleelactl validate preferred-routers exit 0; a scratch C program linked with preferred_router.c returned the outputs shown.

What it is

A routing-preference policy. A small config file (preferred-routers.conf) names a country, a preferred role and a minimum score. The C function sleela_preferred_router_select returns a role, a preference tier from 1 to 5 and the VM generation for an HTTP protocol string (README.md). The tier is a SLeeLa preference, not a measurement of latency or quality. The module does not install routes. http-1.0 and http-2.0 compile preferred_router.c into their servers (http-1.0/Makefile:16, http-2.0/Makefile:24). A data catalog (preferred-routers.csv / .json, 996 rows for 249 countries) sits next to the code.

Before you start

export SLEELA_HOME=$PWD SLEELA_LIB=$PWD/lib SLEELA_SHEET=$PWD/SHEET.sheet \
       SLEELA_SHA256_MANIFEST=$PWD/security/sha256-manifest.json

Step 1 - Syntax-check the module

bin/sleelactl validate preferred-routers
  make -C preferred-routers syntax
cc -std=c11 -O2 -Wall -Wextra -Wpedantic -I. -fsyntax-only preferred_router.c
g++ -std=c++17 -O2 -Wall -Wextra -Wpedantic -I. -fsyntax-only preferred_router.cpp
  ✓ preferred-routers validated (syntax)

Exit 0. -Wall prints several warnings for preferred_router.c (misleading indentation, and snprintf truncation notes on the 16-byte country and 64-byte role fields). They are warnings only. The Makefile's all target is syntax, and clean is true. No binary is built.

Step 2 - Write a small caller

The module has no CLI, so write one. This program asks for the router for HTTP/3.0 and prints it.

mkdir -p /tmp/pr-demo && cat > /tmp/pr-demo/demo.c <<'EOF'
#include "preferred_router.h"
#include <stdio.h>
int main(int argc, char **argv) {
    sleela_preferred_router r;
    int rc = sleela_preferred_router_select(argc > 1 ? argv[1] : NULL, "HTTP/3.0", &r);
    printf("rc=%d country=%s role=%s preference=%d vm=%d/%s %s\n", rc, r.country, r.role,
           r.routing_preference, r.vm_generation, r.vm_name, r.vm_path);
    printf("candidate=%s\n", r.candidate);
    printf("packet_policy(HTTP/3.0, min 5) = %d\n", sleela_preferred_router_packet_policy("HTTP/3.0", 5));
    return 0;
}
EOF
cc -std=c11 -Ipreferred-routers /tmp/pr-demo/demo.c preferred-routers/preferred_router.c -o /tmp/pr-demo/demo

The compile prints -Wmisleading-indentation warnings from preferred_router.c and succeeds.

Step 3 - Select with defaults and with the repository config

/tmp/pr-demo/demo
/tmp/pr-demo/demo preferred-routers/preferred-routers.conf

Both print:

rc=0 country=US role=national_backbone preference=5 vm=3/Specialist /3
candidate=US — configured national_backbone anchor
packet_policy(HTTP/3.0, min 5) = 1

The first call has no config path and no SLEELA_PREFERRED_ROUTER_CONFIG, so the C code uses its built-in defaults (US, national_backbone, min_score=4). The repository file sets the same values.

Step 4 - Change the policy

printf 'country=DE\npreferred_role=regional_carrier\nmin_score=5\n' > /tmp/pr-demo/de.conf
/tmp/pr-demo/demo /tmp/pr-demo/de.conf
SLEELA_PREFERRED_ROUTER_CONFIG=/tmp/pr-demo/de.conf /tmp/pr-demo/demo
rc=0 country=DE role=national_backbone preference=5 vm=3/Specialist /3
candidate=DE — configured national_backbone anchor
packet_policy(HTTP/3.0, min 5) = 1

The config asked for regional_carrier (tier 4) with min_score=5. The selector raised the role to national_backbone (tier 5). Scores are fixed in code: national_backbone and national_ixp are 5; regional_carrier and international_dc are 4; any other role is 1. The same output appears whether you pass the path or set the environment variable.

printf 'country=FR\npreferred_role=international_dc\nmin_score=4\n' > /tmp/pr-demo/fr.conf
/tmp/pr-demo/demo /tmp/pr-demo/fr.conf
rc=0 country=FR role=international_dc preference=4 vm=3/Specialist /3
candidate=FR — configured international_dc anchor
packet_policy(HTTP/3.0, min 5) = 1

The last line is 1 even though FR's tier is 4. sleela_preferred_router_packet_policy calls select with a NULL path, so it reads the environment variable or the defaults, not the file you passed to your own select call. Set SLEELA_PREFERRED_ROUTER_CONFIG if you want the policy hook to see your file.

Step 5 - Look at the catalog

python3 - <<'EOF'
import csv, collections
rows = list(csv.DictReader(open('preferred-routers/preferred-routers.csv')))
print(len(rows), len({r['country_code'] for r in rows}))
print(collections.Counter((r['role'], r['routing_preference']) for r in rows))
print(collections.Counter(r['selection_mode'] for r in rows))
EOF
996 249
Counter({('national_backbone', '5'): 249, ('national_ixp', '5'): 249, ('regional_carrier', '4'): 249, ('international_dc', '4'): 249})
Counter({'role-anchor': 996})

This is what README.md and DATA.md say: four roles per country, every row a placeholder role-anchor and none refreshed from PeeringDB. preferred-routers.json has schema_version 1.1 and the same 996 entries. backup/MANIFEST.md lists earlier editions.

What you did

You syntax-checked the module, linked the selector into a program, read the policy from defaults, a file and an environment variable, saw the min_score escalation, and checked the catalog totals.

What the other sleelactl verbs do for this module

CommandResult
bin/sleelactl negotiate preferred-routers"protocol-metadata operation defined by the generated spec", points to "the negotiate section in preferred-routers/README.md", then no standalone negotiate CLI is built. Exit 3. The README has no such section.
bin/sleelactl grade preferred-routerssame, for grade. Exit 3.
bin/sleelactl simulate preferred-routersno simulator registered (sim= unset). Exit 3.
bin/sleelactl info preferred-routersexit 0; see: preferred-routers/README.md; docs DATA.md, README.md, REFRESH.md

Things to know

Next steps

Sources