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 Swift binding is one file, Mud.swift, over the C ABI, which Swift imports from bindings/c/mudrpc.h through bindings/c/module.modulemap as the module CMudRPC; MudGrpc.swift beside it is the drop-in for grpc-swift. Swift 6.1 or later, on macOS 15 or later and on Linux; iOS’s library is built in the gate, its simulator run waiting on Xcode.

Integrate

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). In your Swift package, copy mudrpc.h and module.modulemap into Sources/CMudRPC/ and declare it .systemLibrary(name: "CMudRPC", path: "Sources/CMudRPC"); copy Mud.swift into the target that uses it, which depends on "CMudRPC". Link with swift build -Xlinker -L<dir> -Xlinker -rpath -Xlinker <dir>, <dir> the library’s folder, or the same as linkerSettings in Xcode.

For iOS, rustup target add aarch64-apple-ios aarch64-apple-ios-sim and cargo rustc --release -p mudrpc-c --target aarch64-apple-ios --crate-type staticlib (-sim for the simulator) give libmudrpc.a for the device and the simulator, which the app target links beside CMudRPC; the gate builds both.

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

import Foundation

let key = (0..<32).map { _ in UInt8.random(in: .min ... .max) }   // the fleet key: 32 bytes from the system's secure generator, provisioned to every peer; never a constant and never a passphrase
let epoch: UInt32 = 1                                   // persisted beside the key; raise it on every boot and restore, write it first
let gcs = try Peer(name: "gcs", key: key, sender: 1, epoch: epoch)       // roster numbers; 0 cannot send
let drone = try Peer(name: "drone", key: key, sender: 2, epoch: epoch)
try drone.listen("nav.Flight")                          // the drone's transport will subscribe to nav.Flight

_ = try gcs.call(now: 0, service: "nav.Flight", method: "Arm", request: [8, 1], ttlSecs: 30)   // a protobuf request, which the generated code encodes for you

let peers = [gcs, drone]
for now in UInt32(0)..<3 {                              // your loop: pump each peer, every tick
  for (i, p) in peers.enumerated() {
    while let o = try p.outgoing(now: now) {
      if !o.listen {                                    // hand o.topic, o.wire, o.ttlSecs to your transport; a listen: subscribe to o.topic
        let incoming = try peers[1 - i].deliver(now: now, topic: o.topic, wire: o.wire)
        switch incoming.kind {
        case .call:
          print("drone:", incoming.method)
          try peers[1 - i].reply(now: now, to: incoming, payload: Array("armed".utf8))
        case .reply:
          print("gcs: status", incoming.status, String(decoding: incoming.bytes, as: UTF8.self))
          exit(0)
        case .dropped: print("dropped:", incoming.dropped)   // log in development, count in the field
        default: break
        }
      }
      try p.sent()                                      // only after the transport took it; if it refused, break instead
    }
    while try p.tick(now: now) != nil { print("expired") }
  }
}
exit(2)

It prints drone: Arm then gcs: status 0 armed and exits 0.

3. The loop. Every tick, drain outgoing(now:) 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(now:topic:wire:); call tick(now:). 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 whole seconds, from a clock that only moves forward; the 12-byte id call returns is the id on the reply that answers it, seq and end carry streams and status is gRPC’s status number, statusName(_:) 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(_: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; every error is a MudError whose code is that header’s. A peer is one thread’s: the drop-in’s transport owns it and lends it out through use.

4. A signed fleet and the cipher. target/release/mud provision fleet 3 writes the fleet key, one device file per sender and the roster, as the C skill describes; a device builds Peer(name:key:sender:epoch:seed:budget:) from them and adds roster(sender:key:) for every sender it believes, with Peer.publicKey(seed:) and revoke(sender:). hub: true believes 256 senders in place of 16. cipher: is Peer.cipherDefault, AES-256-GCM, unless Peer.cipherChaCha20Poly1305 is passed; a fleet runs one.

5. UDP. Udp(bind: "10.0.0.2:7000", peers: ["10.0.0.3:7000"]) sends each wire to every listed peer and hears only them, on the topics its peer listens to; a public address, 0.0.0.0 included, is MudError -1 unless the library was built with the cargo feature internet and MUDRPC_INTERNET=listen-on-public-addresses, which no release is (Udp.internet says which), and a bind the system refuses is -2. send(_:) takes an outgoing item and throws -2 when no peer took a wire; poll() gives the next (topic, wire) or nil.

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, protoc-gen-swift and protoc-gen-grpc-swift-2 (or the GRPCProtobufGenerator build plugin, which runs them for Xcode and SwiftPM), what they generate, and the service it implements. MudTransport, in MudGrpc.swift, is grpc-swift 2’s ClientTransport and ServerTransport over one peer, with GRPCCore from grpc-swift-2 and GRPCProtobuf from grpc-swift-protobuf; no HTTP/2, no server stack and no port:

// was: .http2NIOPosix(target: .ipv4(address: "10.0.0.3", port: 5001), transportSecurity: .plaintext)
let mud = MudTransport(peer: try Peer(name: "gcs", key: fleetKey, sender: 1, epoch: epoch), udp: try Udp(bind: "10.0.0.2:7000", peers: ["10.0.0.3:7000"]))
try await withGRPCClient(transport: mud.client) { grpc in
  let drone = Nav_Drone.Client(wrapping: grpc)
  let reply = try await drone.arm(.with { $0.id = 7 }, options: { var o = CallOptions.defaults; o.timeout = .seconds(30); return o }())
}

A server is GRPCServer(transport: mud.server, services: [DroneService()]) and try await server.serve(), in any process; one transport can be a client and one server at once, a second server failedPrecondition. beginGracefulShutdown() takes no new calls and serve() returns once the running and waiting ones have finished; cancelling the task running serve(), grpc-swift’s shutdown past a deadline, cancels the running and the waiting, their callers cancelled. While it lives the peer is reached through mud.use { try $0.save() }, the same for a key’s stage, rotate and retire, and the transport is closed before the peer. Another radio is a closure, MudTransport(peer:) { outgoing in ... }, taking each outgoing item on the pump’s thread with no lock held, so it may wait on a thread that calls into the transport, and it hands every wire it receives to mud.deliver(topic:wire:); an error it throws goes to fault:, called the same way, and the item is tried for a second, then let go. The transport pumps on a thread of its own, asleep when it has no socket and nothing timed waits; deadlines are grpc-swift’s, on ContinuousClock, so a wall clock stepped by NTP moves none. close() lets the client’s connect() return; a transport closed under it, by a peer or socket gone, answers every call unavailable until it is closed.

cargo test -p mudrpc-c --test abi -- --include-ignored the_swift_drop_in builds bindings/c/tests/grpc-swift/ in target/grpc-swift, its packages pinned to their commits by Package.resolved, generates with protoc and both plugins, and runs a grpc-swift client and service over two peers, over UDP and against a native server through every case above, and step 2’s program.

Verify