Pamoja.Ladder 0.1.17

Pamoja.Ladder

Cheapest reachable link first, buffering to a store when every link is down. One capability of pamoja, one memory-safe Rust core with bindings for TypeScript, Python, and C#.

Install

dotnet add package Pamoja.Ladder

using Pamoja.Ladder;

This pulls in Pamoja.Native, the compiled engine, and Pamoja.Core and Pamoja.Sync. dotnet add package Pamoja is the whole framework in one package.

Example

The guide project's example, spliced here as it ran in CI.

From bindings/dotnet/samples/Pamoja.Guides/LadderGuide.cs:

const string Topic = "sensors/1/temperature";

// Two links off the same node: a near mesh hop and a metered backhaul. Each is a
// separate broker, so which one carried a reading is visible from its subscriber.
using var mesh = new LoopbackBroker();
using var backhaul = new LoopbackBroker();
using var gateway = backhaul.Link();
await gateway.ConnectAsync();
await gateway.SubscribeAsync(Topic);

// Rungs are tried in the order they are added, cheapest first. The mesh hop loses
// every packet here; the backhaul carries one send, then drops the next two.
using var ladder = new Ladder(Store.Memory());
ladder.Rung(Transport.Degraded(mesh.Rung(), dropEvery: 1));
ladder.Rung(Transport.Degraded(backhaul.Rung(), up: 1, down: 2));
await ladder.ConnectAsync();

// The mesh hop refuses, so the reading goes out over the backhaul and arrives on
// the broker only that rung publishes to.
Delivery first = await ladder.SendAsync(Topic, "21.5"u8.ToArray());
TransportMessage arrived = (await gateway.ReceiveAsync())!;
Console.WriteLine(
    $"first reading: {first}, gateway got"
    + $" {System.Text.Encoding.UTF8.GetString(arrived.Payload)}");

// Now nothing will take a send, so the next reading is buffered rather than lost.
Delivery second = await ladder.SendAsync(Topic, "21.6"u8.ToArray());
int waiting = await ladder.BufferedAsync();
Console.WriteLine($"second reading: {second}, {waiting} waiting in the queue");

// A flush while the links are still down forwards nothing and leaves the backlog
// intact, because a record is removed only once a rung has accepted it.
int whileDown = await ladder.FlushAsync();
Console.WriteLine(
    $"flush while down forwarded {whileDown}, queue still {await ladder.BufferedAsync()}");

// The backhaul is reachable again, so the buffered reading goes out exactly once.
int whenUp = await ladder.FlushAsync();
TransportMessage late = (await gateway.ReceiveAsync())!;
Console.WriteLine(
    $"flush when up forwarded {whenUp}, gateway got"
    + $" {System.Text.Encoding.UTF8.GetString(late.Payload)}");

The same capability in every language

Documentation

• Pamoja.Ladder reference, every type in this namespace.
• The Transport ladder guide, with the same example in Rust, TypeScript, and Python.
• Every capability, and the install page.

License

MIT