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 PHP binding is one file, Mud.php, over the C ABI through PHP’s FFI extension (php -m lists FFI; the default ffi.enable=preload lets the CLI load it, while php-fpm and Apache need ffi.enable=1 or Mud.php in opcache.preload), with no composer package.

Integrate

From a clone to a call answered by hand, 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

That gives target/release/libmudrpc.dylib (.so on Linux). Copy bindings/php/Mud.php beside your script and put the library next to it, or point MUDRPC_LIB at it.

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

<?php
require __DIR__ . '/Mud.php';

use Mud\Peer;

$key = random_bytes(32);                                 // 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)
$epoch = 1;                                              // persisted beside the key; raise it on every boot and restore, write it first
$gcs = new Peer('gcs', $key, sender: 1, epoch: $epoch, cipher: Mud\CIPHER_DEFAULT);     // roster numbers; 0 cannot send
$drone = new Peer('drone', $key, sender: 2, epoch: $epoch, cipher: Mud\CIPHER_DEFAULT);
$drone->listen('nav.Flight');                            // the drone's transport will subscribe to nav.Flight

$callId = $gcs->call(0, 'nav.Flight', 'Arm', "\x08\x01", ttl: 30);   // now 0; a protobuf request, which the stubs encode for you

$peers = [$gcs, $drone];
for ($now = 0; $now < 3; $now++) {                       // your loop: pump each peer, every tick
    foreach ($peers as $i => $p) {
        while (($o = $p->outgoing($now)) !== null) {
            if ($o->kind === 'send') {                   // hand $o->topic, $o->wire, $o->ttl to your transport; 'listen': subscribe to $o->topic
                $in = $peers[1 - $i]->deliver($now, $o->topic, $o->wire);
                if ($in->kind === 'call') {
                    echo "drone: $in->method\n";
                    $peers[1 - $i]->reply($now, $in, status: 0, payload: 'armed');
                } elseif ($in->kind === 'reply') {
                    echo "gcs: status $in->status $in->bytes\n";
                    exit(0);
                } elseif ($in->kind === 'dropped') {
                    echo "dropped: $in->dropped\n";        // log in development, count in the field
                }
            }
            $p->sent();                                  // only after the transport took it; if it refused, break instead
        }
        while ($p->tick($now) !== null) {
            echo "expired\n";
        }
    }
}
exit(2);

MUDRPC_LIB=/path/to/libmudrpc.dylib php example.php prints drone: Arm then gcs: status 0 armed and exits 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 an int, your uptime in seconds; the 12-byte string call() returns is the id on the reply that answers it, seq and end carry streams, status is gRPC’s status number and Mud\statusName($status) its name. 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 UDP. new Mud\Udp('10.0.0.5:4000', '10.0.0.7:4000') binds the first address and sends every wire to each of the others; it is a Mud\Radio, send($item) for each outgoing item and poll() for the next [$topic, $wire], so the loop above is the same with it in place of the hand-moving. Private addresses only: a public bind or peer is Mud\Error -1 in every release build, and Mud\Udp::internet() says whether this library may do otherwise. Your own transport is a class with those two methods.

5. Your .proto. The composer package google/protobuf and protoc --php_out give the messages; serializeToString() is the payload of a call or reply and mergeFromString() reads one. For the services, the drop-in below runs the client grpc_php_plugin generates; a PHP server answers each call with reply() as step 2 does, seq 0, 1, 2… and end on the last item of a stream, or detail: Mud\STREAM_END with no item when the stream has none.

6. A signed fleet and the cipher. new Peer($name, $key, $sender, $epoch, seed: $seed) signs every wire with the sender’s 32-byte Ed25519 seed, and a receiver believes only the senders on its roster: roster($sender, Peer::publicKey($seed)), 16 lines for a leaf, 256 with hub: true. stage($next), rotate() and retire() turn the fleet key over in three steps; opened() says which slot opened the last wire. cipher: is Mud\CIPHER_AES_256_GCM (the default) or Mud\CIPHER_CHACHA20_POLY1305; a fleet runs one.

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.

A gRPC PHP product keeps its .proto, the client grpc_php_plugin generates and the composer package grpc/grpc, and changes the options that build the stub. MudGrpc.php beside Mud.php is a Grpc\CallInvoker over one peer; the grpc extension is not needed, and where it is not loaded the file defines the Grpc\STATUS_* numbers and the credentials class BaseStub asks about.

// before
$drone = new Test\DroneClient('drone.example.com:50051', ['credentials' => Grpc\ChannelCredentials::createInsecure()]);
// after
$mud = new Mud\Channel(new Mud\Peer('gcs', $key, 1, $epoch), new Mud\Udp('10.0.0.5:4000', '10.0.0.7:4000'));
$drone = new Test\DroneClient('drone', ['credentials' => null, 'grpc_call_invoker' => $mud]);

$drone->Arm($request)->wait() gives [$reply, $status] and $drone->Telemetry($request)->responses() the items, then getStatus(), as with gRPC’s own channel. What differs:

cargo test -p mudrpc-c --test abi -- --include-ignored the_php_drop_in installs grpc/grpc and google/protobuf into target/grpc-php from Packagist, pinned by bindings/c/tests/grpc-php/composer.lock, generates the client with grpc_php_plugin, and runs it over a peer in-process against a native PHP server, then over UDP to one in its own process, through every case above.

Verify

The host mistakes the contract names, each with what it throws or returns:

Mistake Answer Kind
restore or renew with an epoch at or below the saved one Mud\Error, getCode() === -6 error
sender 0 sending Mud\Error, -7, at the first send error
a key or seed of 32 equal bytes Mud\Error, -1; another length is an InvalidArgumentException first error
save() bytes of another length to restore Mud\Error, -4 error
a hub’s save() cut to a leaf’s length Mud\Error, -5 error
hub: true without a seed Mud\Error, -1 error
ttl 0, or past a week sent as 1, or a week clamp
a topic or name over 64 bytes, or a payload over the ceiling Mud\Error, -3 error
an empty name or topic Mud\Error, -1 error
a reply to a call this peer does not have deliver returns dropped === 'no_pending' silent
16 calls pending, or 16 items queued undrained Mud\Error, -2: decide what not to queue; pending() and queued() count them error
the 33rd send in one second Mud\Error, -9: the next second sends error
a peer after close() Mud\Error, -4; pending(), queued(), pressure() and counts() read 0 error

Test at each rung

Known edges