Expand description
Shared protocol primitives for applications built on top of pork.
This crate defines the control-plane messages exchanged between a parent process and a managed child process, plus optional built-in codecs for serializing those messages on the dedicated control channel.
§What this crate gives you
protocol::PorkControlMessagefor framework-level coordinationprotocol::PorkIpcMessage<T>for wrapping your own protocol payloadsprotocol::PorkControlCodecfor choosing how control messages are encoded- feature-gated codec implementations in
codecsfor custom payloads - environment helpers so parent and child agree on the selected codec
§Feature flags
codec-jsonenables the JSON codec implementationcodec-postcardenables the Postcard codec implementation
You can enable one or both features depending on the transport format you want to expose to consumers.
§Example: wrap your own messages
use pork_proto::protocol::{PorkControlMessage, PorkIpcMessage};
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
struct AppMessage {
command: String,
}
// Wrap application data without mixing it into the control plane.
let app_message = PorkIpcMessage::Custom(AppMessage {
command: "ping".to_owned(),
});
let shutdown = PorkIpcMessage::<AppMessage>::Control(PorkControlMessage::GracefulShutdown);
let restart = PorkIpcMessage::<AppMessage>::Control(PorkControlMessage::Restart);
assert!(matches!(app_message, PorkIpcMessage::Custom(_)));
assert!(matches!(shutdown, PorkIpcMessage::Control(PorkControlMessage::GracefulShutdown)));
assert!(matches!(restart, PorkIpcMessage::Control(PorkControlMessage::Restart)));§Example: encode and decode control messages
use pork_proto::protocol::{PorkControlCodec, PorkControlMessage};
// Host and child must use the same control-message codec.
let codec = PorkControlCodec::Json;
let shutdown = codec.encode_control_message(PorkControlMessage::GracefulShutdown)?;
let restart = codec.encode_restart()?;
assert_eq!(
codec.decode_control_message(&shutdown)?,
PorkControlMessage::GracefulShutdown,
);
assert!(codec.is_restart_message(&restart));§Example: serialize your own payload with the JSON codec
use pork_proto::codecs::json::JsonCodec;
use pork_proto::protocol::{PorkCodec, PorkIpcMessage};
use serde::{Deserialize, Serialize};
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
struct AppMessage {
command: String,
}
let original = PorkIpcMessage::Custom(AppMessage {
command: "reload".to_owned(),
});
// Encode the shared envelope before sending it over the data channel.
let bytes = JsonCodec::encode(&original)?;
let decoded: PorkIpcMessage<AppMessage> = JsonCodec::decode(&bytes)?;
assert_eq!(decoded, original);§Example: host/child control-plane contract
The host and child must agree on one codec and encode all control-plane
messages (GracefulShutdown, Restart, StatusUpdate) with that codec.
use pork_proto::protocol::{PorkChildStatus, PorkControlCodec, PorkControlMessage, PorkStatusUpdate};
// Status updates travel over the dedicated control channel.
let codec = PorkControlCodec::Json;
let status_payload = codec.encode_control_message(PorkControlMessage::StatusUpdate(
PorkStatusUpdate {
status: PorkChildStatus::Running,
timestamp_ms: 123,
},
))?;
assert!(matches!(
codec.decode_control_message(&status_payload)?,
PorkControlMessage::StatusUpdate(PorkStatusUpdate {
status: PorkChildStatus::Running,
timestamp_ms: 123,
})
));§Example: agree on a codec through the environment
The parent process can write the selected codec into
protocol::PORK_CONTROL_CODEC_ENV, and the child can read it back with
protocol::control_codec_from_env().
use pork_proto::protocol::{control_codec_from_env, PORK_CONTROL_CODEC_ENV, PorkControlCodec};
// In a real process bootstrap flow, the parent would set this before spawning the child.
unsafe {
std::env::set_var(PORK_CONTROL_CODEC_ENV, "postcard");
}
// The child resolves the codec selected by the parent process.
let codec = control_codec_from_env()?;
assert_eq!(codec, PorkControlCodec::Postcard);
unsafe {
std::env::remove_var(PORK_CONTROL_CODEC_ENV);
}If the environment variable is missing, control_codec_from_env() falls back
to PorkControlCodec::Json.
Modules§
- codecs
- Feature-gated codec implementations for encoding and decoding
protocol::PorkIpcMessagepayloads through concreteprotocol::PorkCodecimplementations such as [codecs::json::JsonCodec] and [codecs::postcard::PostcardCodec]. - protocol
- Shared protocol models, codec selection, parsing, and environment helpers.