Cap’n Proto RPC serving

Overview

readcon-core provides an optional Cap’n Proto RPC interface (behind the rpc feature flag) that allows any language with a Cap’n Proto implementation to request frame parsing and writing over the network.

Schema

The schema defines a ReadConService interface with two methods:

parseFrames

Accepts raw file bytes, returns parsed frame data.

writeFrames

Accepts structured frame data, returns serialized file bytes.

The schema file is at schema/ReadCon.capnp.

**CON v3 field parity** (wire shape of a parsed ConFrame, not an on-disk bcon file):

Cap’n Proto	Maps to
ConAtom.fixedMask (u8, 0–7)	per-axis constraints (encode_fixed_bitmask)
ConAtom velocity / force / energy / charge / spin / magmom	AtomDatum optional sections
ConFrameData.specVersion	FrameHeader.spec_version (default 2)
hasForces / hasEnergies / hasCharges / hasSpins / hasMagmoms	section presence
massesPerType / natmsPerType	type table
sections	declared section names
metadataJson	free-form + reserved JSON keys (units, energy, NEB, …)
strictValidation / sectionsDeclared	parse policy flags

Round-trip helpers live in src/rpc/convert.rs (fill_frame_builder / frame_from_reader). Text .con remains the on-disk interchange authority.

Breaking note: pre-v3 wire used a single isFixed: Bool and velocity-only atoms. Clients must regenerate from the current schema (0.x RPC surface).

Building

# Requires capnproto installed (via pixi or system package)
cargo build --features rpc

# Or via pixi (capnproto is a dependency)
pixi r build-rpc

Server

// Start a TCP RPC server
#[tokio::main]
async fn main() {
    readcon_core::rpc::server::start_server("127.0.0.1:9876")
        .await
        .unwrap();
}

Client

use readcon_core::rpc::client::RpcClient;
use std::path::Path;

let client = RpcClient::new("127.0.0.1:9876").unwrap();
let frames = client.parse_file(Path::new("input.con")).unwrap();
let output = client.write_frames(&frames).unwrap();

Protocol

The RPC uses Cap’n Proto two-party protocol over TCP. The server listens on a configurable host:port and handles one connection per accepted socket using tokio for async I/O.