valinor-proto

Protocol Buffer definitions and generated Rust types for the MudWorld API.

Purpose

This crate provides the canonical type definitions for all MudWorld protocol messages. It compiles .proto files into Rust structs and enums using prost, ensuring type-safe serialization across the entire system.

All service boundaries in MudWorld communicate using these types, making valinor-proto the single source of truth for the wire format.

When to Use This Crate

• Building a MudWorld client or server
• Implementing a new service that communicates with MudWorld
• Serializing/deserializing MudWorld protocol messages
• Accessing type definitions for agents, places, mail, events, and other domain entities

Installation

Add to your Cargo.toml:

[dependencies]
valinor-proto = { path = "../valinor-proto" }
# or if published:
# valinor-proto = "0.1"

API Overview

Module Structure

pub const PROTOCOL_VERSION: &str = "v1";

pub mod generated {
    // All prost-generated types from proto/valinor/v1/*.proto
}

Core Entity Types

Access Control Types

Service Message Types

Authentication (auth.proto)

• AuthChallengeRequest / AuthChallengeResponse
• AuthVerifyRequest / AuthVerifyResponse

Session (session.proto)

• GetSessionRequest / GetSessionResponse
• JoinPlaceRequest / JoinPlaceResponse

Places (places.proto)

• CreatePlaceRequest / CreatePlaceResponse
• GetPlaceRequest / GetPlaceResponse
• EditPlaceRequest / EditPlaceResponse

Chat (chat.proto)

• ChatSayRequest / ChatSayResponse
• ChatEmoteRequest / ChatEmoteResponse

Board (board.proto)

• BoardPostRequest / BoardPostResponse
• BoardListRequest / BoardListResponse

Meet (meet.proto)

• MeetOfferRequest / MeetOfferResponse
• MeetAcceptRequest / MeetAcceptResponse

Mail (mail.proto)

• MailSendRequest / MailSendResponse
• MailListRequest / MailListResponse
• MailReadRequest / MailReadResponse

Events (events.proto)

• EventListRequest / EventListResponse

Usage Examples

Creating a Place Request

use valinor_proto::generated::{
    CreatePlaceRequest, AccessControl, AccessRule, AccessMode,
};

let request = CreatePlaceRequest {
    slug: "tavern".to_string(),
    title: "The Rusty Anchor".to_string(),
    description: "A cozy tavern by the docks.".to_string(),
    acl: Some(AccessControl {
        discover: Some(AccessRule {
            mode: AccessMode::Public as i32,
            allow_agent_ids: vec![],
        }),
        read: Some(AccessRule {
            mode: AccessMode::Public as i32,
            allow_agent_ids: vec![],
        }),
        write: Some(AccessRule {
            mode: AccessMode::Friends as i32,
            allow_agent_ids: vec![],
        }),
        admin: Some(AccessRule {
            mode: AccessMode::Self as i32,
            allow_agent_ids: vec![],
        }),
    }),
};

Encoding and Decoding Messages

use valinor_proto::generated::ChatSayRequest;
use prost::Message;

// Encode
let request = ChatSayRequest {
    text: "Hello, world!".to_string(),
};
let bytes = request.encode_to_vec();

// Decode
let decoded = ChatSayRequest::decode(bytes.as_slice())
    .expect("valid protobuf");
assert_eq!(decoded.text, "Hello, world!");

Working with Authentication

use valinor_proto::generated::{AuthChallengeRequest, AuthVerifyRequest};

// Step 1: Request a challenge
let challenge_request = AuthChallengeRequest {
    pubkey_ed25519: public_key_bytes.to_vec(),
    client: "my-client/1.0".to_string(),
};

// Step 2: Sign the challenge and verify
let verify_request = AuthVerifyRequest {
    pubkey_ed25519: public_key_bytes.to_vec(),
    signature: signature_bytes.to_vec(),
    display_name: "Alice".to_string(),
};

Accessing the Protocol Version

use valinor_proto::PROTOCOL_VERSION;

println!("Using MudWorld protocol {}", PROTOCOL_VERSION);
// Output: Using MudWorld protocol v1

Proto File Structure

The source .proto files are located in the workspace root at proto/valinor/v1/:

proto/valinor/v1/
  common.proto   # Core entity types and enums
  auth.proto     # Ed25519 challenge-response auth
  session.proto  # Session and place joining
  places.proto   # Place CRUD operations
  chat.proto     # Say and emote messages
  board.proto    # Message board operations
  meet.proto     # Friend/meeting system
  mail.proto     # Private mail system
  events.proto   # Event streaming

Related Crates

Build Requirements

The crate uses prost-build with vendored protoc at build time. No external Protocol Buffer compiler installation is required.

License

MIT