piying_macros 0.2.0

Fault-tolerant Async Actors Built on Tokio - macros
Documentation

Piying

CI Nix crates.io

Fault-tolerant async actors built on Tokio.

Piying is a fork of Kameo by tqwewe.

Why fork?

  • Larger production scope — Piying targets real-time networked games and other latency-sensitive distributed systems, driving changes to codec flexibility, networking, and error handling that go beyond upstream's focus.
  • AI-generated code welcome — the upstream project does not accept AI-generated contributions. Piying has no such restriction.

Key differences from upstream

  • Pluggable codec system (rkyv, serde, or custom) — decoupled from the core actor framework
  • PiyingRkyvCodec for high-performance binary serialization via rkyv
  • Various networking and swarm improvements for production P2P use

Installation

Add Piying to your Cargo dependencies:

[dependencies]
piying = "0.2"

The default features enable actor macros and tracing. Optional remote networking uses the remote feature with serde-codec or rkyv-codec. See the API documentation for actor and messaging examples.

Migrating to 0.2.0

ActorPool worker errors now preserve SendError<M, R::Error> rather than only the handler error. Callers matching a pool's handler failure must handle that nested send-error type.

Piying 0.2.0 requires libp2p 0.57.0 for consumers that compose Piying's network behaviours or exchange libp2p types with Piying. Custom request-response codecs implement libp2p's native async methods without #[async_trait]. The minimum Rust version remains 1.88.0.

registry::Event::RoutingUpdated::addresses is now Box<kad::Addresses> to keep the larger upstream address collection out of every remote event. Borrowed access works through dereferencing; use *addresses when moving the collection into code that expects an owned kad::Addresses.

The remote feature requires hickory-proto 0.26.3 or later in the 0.26 series to resolve RUSTSEC-2026-0118 and RUSTSEC-2026-0119. The existing rkyv framing helpers remain supplied by libp2p-rkyv-codec 0.3; Piying implements the libp2p 0.57 codec itself. Remote protocol identifiers and the THSP version-2 rkyv framing remain unchanged.

Upstream features (inherited)

  • Lightweight async actors on Tokio
  • Fault tolerance with supervision strategies
  • Flexible messaging (bounded/unbounded channels, backpressure)
  • Local and distributed communication via libp2p
  • Panic safety and actor isolation
  • Type-safe message interfaces

Development

Run nix develop for the pinned Rust tools, Just, and Simit 0.19.0 with the coordinated-release event-SHA fix. Then:

just ci
simit init ci --check --diff

GitHub Actions checks the entire workspace with all features and without default features, including its declared minimum Rust version. The minimal-library gate separately checks Piying's library with no features and with macros only; library-only checks avoid dev-dependencies re-enabling default features. The required feature-matrix gate also runs just ci for separate serde/rkyv lint and test runs, minimal-feature tests, and the tokio_unstable build. The packaging gate checks workspace package contents and verifies the macros crate archive. Both gates run before crate publishing as well.

Publishing requires the GitHub repository secret CRATES_IO_API_TOKEN and a signed version tag trusted by keys/maintainers.gpg. The workflow publishes piying_macros, then piying, then piying_actors. The signed tag must resolve to the immutable workflow event commit; a moved tag fails validation before any release gates or publication run. The temporary nix/simit-release-event.patch carries the generator fix until it is released upstream.

License

Piying is dual-licensed under either:

Same as the original Piying project.