mudRPC, gRPC for unstable networks

mudRPC is RPC for networks that go away: a call is a message, a reply may come hours later or expire, nothing blocks. The Java binding is one file, Mud.java, over the C ABI through the foreign function API in java.lang.foreign, with no package and no JNI: copy it into your project as mudrpc/Mud.java (it declares package mudrpc) and your IDE sees every type and comment. Java 22 or later.

Integrate

From a clone to a call answered over the simulator, then your transport, your .proto and a signed fleet.

1. Build the library. A Rust toolchain is the one build dependency, until prebuilt binaries ship at 3.0:

cargo build --release -p mudrpc-c -p mudrpc-gen

That gives the library and target/release/mud. Copy bindings/java/Mud.java into your project as mudrpc/Mud.java. Point MUDRPC_LIB at the library, or put it next to your classes (the javac -d directory) or jar. From 3.0, the Maven Central artefact io.github.jacob-mellor:mudrpc gives the same: the classes with the library inside the jar, copied out for the run when none is beside it, and the sources and javadoc jars.

2. Make one call. The smallest complete program: two peers in one process, a call and a reply moved by hand between them.

import mudrpc.Mud.*;

import java.nio.charset.StandardCharsets;
import java.util.Arrays;

public class Example {
    public static void main(String[] args) {
        byte[] key = new byte[32]; new java.security.SecureRandom().nextBytes(key);   // the fleet key: 32 bytes from the OS, provisioned to every peer; never a constant and never a passphrase (32 equal bytes are refused, other constants are not)
        int epoch = 1;                                               // persisted beside the key; raise it on every boot and restore, write it first
        try (Peer gcs = new Peer("gcs", key, 1, epoch); Peer drone = new Peer("drone", key, 2, epoch)) {   // roster numbers; 0 cannot send; the shorter constructors pass Peer.CIPHER_DEFAULT
            drone.listen("nav.Flight");                                     // the drone's transport will subscribe to nav.Flight
            byte[] callId = gcs.call(0, "nav.Flight", "Arm", new byte[] { 8, 1 }, 30);   // now 0, ttl 30 s; a protobuf request, encoded by your protobuf library
            Peer[] peers = { gcs, drone };
            for (int now = 0; now < 3; now++)                        // your loop: pump each peer, every tick
                for (int i = 0; i < 2; i++) {
                    Peer p = peers[i];
                    Outgoing o;
                    while ((o = p.outgoing(now)) != null) {
                        if (!o.listen()) {                           // hand o.topic(), o.wire(), o.ttlSecs() to your transport; listen: subscribe to o.topic()
                            Incoming incoming = peers[1 - i].deliver(now, o.topic(), o.wire());
                            switch (incoming.kind()) {
                                case CALL -> {
                                    System.out.println("drone: " + incoming.method());
                                    peers[1 - i].reply(now, incoming, 0, "armed".getBytes(StandardCharsets.UTF_8));
                                }
                                case REPLY -> {
                                    System.out.println("gcs: status " + incoming.status() + " " + new String(incoming.bytes(), StandardCharsets.UTF_8));
                                    return;
                                }
                                case DROPPED -> System.out.println("dropped: " + incoming.dropped());   // log in development, count in the field
                                default -> {}
                            }
                        }
                        p.sent();                                    // only after the transport took it; if it refused, break instead
                    }
                    while (p.tick(now) != null) System.out.println("expired");
                }
        }
        System.exit(2);
    }
}

javac -d out mudrpc/Mud.java Example.java, copy libmudrpc.dylib into out (or set MUDRPC_LIB), then java --enable-native-access=ALL-UNNAMED -cp out Example: that flag is the JDK’s permission for any native call and the only one the binding needs. Expected output: drone: Arm then gcs: status 0 armed, exit 0.

3. The loop. Every tick, drain outgoing() into your transport, calling sent() once it took each item (if it refused, break: the item is there next tick); feed what it received to deliver(); call tick(). outgoing() also yields listen items, one for the peer’s own name (its reply inbox) and one per listen(), and what a peer hears is what its transport subscribes to. now is your uptime in seconds; the 12-byte byte[] id returned by call is the id() on the reply that answers it, compared with Arrays.equals, seq() and end() carry streams and status() is gRPC’s status number, whose name Mud.statusName(status) gives. Incoming.kind() is CALL, REPLY, EVENT (a publish), EXPIRED (from tick(), with the call’s id()), DROPPED, FLOOD or ROLLBACK, and all but EXPIRED and DROPPED name their sender(). save(), Peer.restore(saved, epoch), renew(epoch) and close() keep and end a peer under the host contract at the top of bindings/c/mudrpc.h, which every binding shares.

4. Over the simulator. Replace the hand-moving with the simulator, new Sim(text), one radio per peer in place of your transport. The text is a scenario in the format adapters/SKILL.md gives, "seed 1\npeers 2\nprofile reticulum\n0 partition 0 1\n30000 heal 0 1\n" cutting the two radios apart until 30 s, so a call at 0 with ttl 60 is answered after the heal and one with ttl 10 expires; events() lists its host events as SimEvent(atMs, kind, a, b, text) for your harness to perform; a bad line throws IllegalArgumentException naming it. Radio i is your ith peer, 0 to peers() − 1, whatever its sender number. Each round, for each peer i: hand its outgoing items to send(i, o.topic(), o.wire(), o.ttlSecs()) or listen(i, o.topic()) (false while the radio is down, a peer_down row, not a partition, whose wire the mesh holds: break, no sent()), deliver() each poll(i) result with kind() == 1 until null (2 is on-mesh, 3 off-mesh), tick(); then step(100). now is (int) (nowMs() / 1000); note(text) writes a host line and log() returns the world’s log; peers() and lastEventMs() come from the text.

5. Your transport. In the simulator’s place your transport takes each send item and listen topic, and what it receives goes to deliver; its rungs are below. On an IP network it can be the library’s own, new Mud.Udp("10.0.0.2:7000", "10.0.0.3:7000"), with send(item), a listen among them, and poll(), which yields only a listed peer’s wires on a topic listened to, into deliver, or given to a MudChannel, which pumps it every 10 ms. It binds and sends to private, loopback or link-local addresses alone; 0.0.0.0 is public, since it binds every interface. A library built with the cargo feature internet, and MUDRPC_INTERNET=listen-on-public-addresses in the builder’s environment, may bind and send to public ones; the feature alone fails the build, since any crate in it could set the feature, and no release is built with it. Cargo shows the build’s own warning for the workspace alone, so a socket on a public address says so on standard error and Udp.internet() is the check a product makes at start. The variable belongs on the command line of the one build that means it, never in a .cargo/config.toml, where every build would go public in silence. Reticulum’s and DTN’s adapters are their own people’s, against adapters/CONFORMANCE.md.

6. Your .proto. If the product has gRPC code, in Java or Kotlin, keep it and read “Drop-in for gRPC” below. Otherwise encode request and reply bytes with your protobuf library of choice. The wire is protobuf; only the payload is yours. A proto service Flight in package nav is the service string "nav.Flight", which the server listens on, with the rpc name as the method; (mud.ttl_secs) is the ttlSecs argument; a method with (mud.topic) is publish on that topic, arrives as EVENT and has no reply.

7. Streams. Answer one call with reply(now, call, status, payload, end, seq), or reply(now, call, status, payload, end, seq, detail) to give the status its text, for seq 0, 1, 2… below 64 (above it a MudException, code == -3), end true on the last item only; the four-argument reply passes true and 0, so a unary reply is seq 0 with end. The items arrive in any order, each a REPLY with its seq() and end(), and the call completes once every seq() up to the lowest end() it has seen has arrived, or is EXPIRED at its ttl with one missing. Send end once: an item above the lowest end() is Dropped.SEQ, a redelivered item Dropped.DUPLICATE, and anything after completion Dropped.NO_PENDING.

8. A signed fleet (SPEC.md layer 1).

target/release/mud provision fleet 3

That writes fleet/fleet.key (key <hex>, once), fleet/device-1 to fleet/device-3 (sender <n>, epoch 1, seed <hex>, owner-only, each device’s one secret) and fleet/roster (<sender> <public key hex> a line), 32-byte values in lowercase hex; run it again to add devices, numbered after the highest, and --key in place of the count for a rotation’s next key, fleet/fleet.key.next; no file is ever overwritten. A device gets the fleet key, its own device file and the roster, and boots new Peer(name, key, sender, epoch, seed, budget) from them (HexFormat.of().parseHex each value), then a roster(sender, key, null) line for every sender it believes; its epoch starts at the file’s and is raised under the host contract. new Peer(name, key, sender, epoch, seed, budget) with this sender’s 32-byte Ed25519 seed and the signature checks per second this host affords (at least 1; a wire past them is Dropped.OPEN, status() 6), a roster(sender, key, next) line for every sender using Peer.publicKey(seed), revoke(sender) to remove one. A peer believes 16 senders and the 17th line throws MudException with isFull(), so a ground station that must believe a fleet is built with hub true (the seventh argument), the same peer with 256 lines, 256 replay windows and 1024 remembered messages in a larger block. Its wire is version 4 (2 under ChaCha20-Poly1305): an unsigned peer gives it Kind.DROPPED with Dropped.VERSION and status() == 4, and a signed peer an unsigned wire the same with status() == 3, so one fleet key never serves both. A discovered key or seed: SECURITY.md, “If a key is discovered”.

cipher, the eighth argument, is Peer.CIPHER_DEFAULT from the shorter constructors, AES-256-GCM; Peer.CIPHER_CHACHA20_POLY1305 there builds any of these peers under ChaCha20-Poly1305 instead: the same sizes and calls, wire version 1, or 2 signed, so a peer of the other cipher gives its wires Dropped.VERSION with that version in status().

9. Verify. cargo test -p mudrpc-c --test abi -- --include-ignored the_java_skill_example_runs runs step 2’s program and every row of the table below.

Drop-in for gRPC

What every language’s drop-in shares, the one-line change, gRPC without HTTP/2, the dependencies and what is not carried, is From gRPC in the README.

The product keeps its .proto, the protobuf Gradle or Maven plugin in IntelliJ, Eclipse or VS Code, and the stubs and service bases grpc-java and grpc-kotlin generate. MudChannel.java, beside Mud.java, is an io.grpc.Channel and the server for the services added to it, with the grpc-java packages whose types they are, and no transport package:

dependencies {
    implementation("io.grpc:grpc-protobuf:1.85.1")
    implementation("io.grpc:grpc-stub:1.85.1")            // and for Kotlin, "io.grpc:grpc-kotlin-stub:1.5.0"
    implementation("com.google.protobuf:protobuf-java:4.36.2")
}   // no grpc-netty, grpc-okhttp or grpc-servlet: MudChannel is the transport

Building the channel is the line that changes; the stub is the generated one, as before:

// was: ManagedChannel channel = ManagedChannelBuilder.forAddress("drone", 5001).usePlaintext().build();
MudChannel channel = new MudChannel(new Mud.Peer("gcs", fleetKey, 1, epoch), new Mud.Udp("10.0.0.2:7000", "10.0.0.3:7000"));
DroneGrpc.DroneBlockingStub drone = DroneGrpc.newBlockingStub(channel).withDeadlineAfter(30, TimeUnit.SECONDS);
ArmReply reply = drone.arm(ArmRequest.newBuilder().setId(7).build());

Kotlin’s is the same channel, DroneGrpcKt.DroneCoroutineStub(channel). A server adds the generated base where ServerBuilder did, channel.addService(new DroneService()), interceptors included through ServerInterceptors.intercept, in any process, with no server or port of gRPC’s. Over Mud.Udp a channel listens on its own name when constructed and on a service when it is added, before the call returns, so a server is called the moment it is built. While the channel lives the peer is reached through channel.use(p -> p.save()), the same for a key’s stage, rotate and retire, and the channel is closed before the peer, from any thread, the transport’s send included. Another transport takes each item through the Consumer the channel was built with and hands every wire it receives to channel.deliver(topic, wire); an exception it throws goes to the channel’s fault callback, and the item is tried for a second, then let go.

cargo test -p mudrpc-c --test abi -- --include-ignored the_java_and_kotlin_drop_in fetches protoc, grpc-java’s and grpc-kotlin’s plugins and their packages from Maven Central, each pinned by its SHA-256, generates the stubs, and runs a Java client and service over two peers, over UDP and against a native server through every case above, then Kotlin’s coroutine stub and base.

Verify

The host mistakes the contract names, each with what it throws or returns, every row asserted by the_java_skill_example_runs:

Mistake Answer Kind
restore or renew with an epoch at or below the saved one MudException, code == -6 error
sender 0 sending MudException, code == -7, at the first send error
a key or seed of 32 equal bytes MudException, code == -1; another length is an IllegalArgumentException first error
save() bytes of another length to restore MudException, code == -4 error
a hub’s save() cut to a leaf’s length MudException, code == -5 error
hub true without a seed MudException, code == -1 error
save() bytes retagged to the other cipher MudException, code == -4 error
saved bytes sent from without a resume cannot happen: restore resumes none
ttl 0, or past a week (a negative int is past it) sent as 1, or a week clamp
a topic or name over 64 bytes, or a payload over the ceiling MudException, code == -3 error
an empty name or topic MudException, code == -1 error
a reply to a call this peer does not have deliver() returns dropped() == Dropped.NO_PENDING silent
16 calls pending, or 16 items queued undrained MudException, isFull(), code == -2: decide what not to queue; pending() and queued() count them error
the 33rd send in one second MudException, code == -9: the next second sends error

Test at each rung

Known edges