Skip to main content

Crate pork_proto

Crate pork_proto 

Source
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::PorkControlMessage for framework-level coordination
  • protocol::PorkIpcMessage<T> for wrapping your own protocol payloads
  • protocol::PorkControlCodec for choosing how control messages are encoded
  • feature-gated codec implementations in codecs for custom payloads
  • environment helpers so parent and child agree on the selected codec

§Feature flags

  • codec-json enables the JSON codec implementation
  • codec-postcard enables 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::PorkIpcMessage payloads through concrete protocol::PorkCodec implementations such as [codecs::json::JsonCodec] and [codecs::postcard::PostcardCodec].
protocol
Shared protocol models, codec selection, parsing, and environment helpers.