Skip to main content

Crate piying

Crate piying 

Source
Expand description

§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.3"

The default features enable actor macros and tracing. Optional remote networking is layered, and needs serde-codec or rkyv-codec:

  • remote: messaging core (request-response, remote::Behaviour, #[remote_message]). Bring your own libp2p swarm. No Kademlia, mDNS or transports are compiled in.
  • remote-registry: adds Kademlia name register/lookup across the network.
  • remote-bootstrap: adds remote::bootstrap() (mDNS, TCP, QUIC); implies remote-registry.

See the API documentation for actor and messaging examples.

§Migrating to 0.3.0

remote is now messaging-only. Replace remote with remote-bootstrap to keep the previous behaviour, or remote-registry if you build your own swarm but still use Kademlia name lookup. Without remote-registry, ActorRef::register and ActorRef::lookup are the synchronous in-process versions.

§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-bootstrap 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.21.0 (substituted from the public canix Attic cache). 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.

§License

Piying is dual-licensed under either:

Same as the original Piying project.

Re-exports§

pub use actor::Actor;
pub use reply::Reply;

Modules§

actor
Core functionality for defining and managing actors in Piying.
error
Defines error handling constructs for piying.
mailbox
A multi-producer, single-consumer queue for sending messages and signals between actors.
message
Messaging infrastructure for actor communication in Piying.
prelude
Commonly used types and functions that can be imported with a single use statement.
remote
Remote Actors in Piying
reply
Constructs for handling replies and errors in Piying’s actor communication.
request
Types for sending requests including messages and queries to actors.

Attribute Macros§

messages
Attribute macro placed on impl blocks of actors to define messages.
remote_message
Registers an actor message to be supported with remote messages.

Derive Macros§

Actor
Derive macro implementing the Actor trait with default behaviour.
RemoteActor
Derive macro implementing the RemoteActor trait with a default remote ID being the full path of the type being implemented.
Reply
Derive macro implementing the Reply trait as an infallible reply.