rs-pfcp

A high-performance Rust implementation of the PFCP (Packet Forwarding Control Protocol) for 5G networks, providing comprehensive compliance with 3GPP TS 29.244 Release 18 specification.

🚀 What is PFCP?

PFCP is the critical communication protocol between Control Plane and User Plane functions in 5G networks:

• SMF (Session Management Function) ↔ UPF (User Plane Function)
• Manages packet forwarding rules, traffic steering, and usage reporting
• Essential for 5G service orchestration, QoS enforcement, and network slicing

✨ Key Features

• 🏆 3GPP TS 29.244 Release 18 Compliance - 354 Information Elements implemented — 100% complete specification coverage
• 🔥 High Performance - Sub-microsecond binary protocol implementation
• 🧪 Battle Tested - 3,400+ comprehensive tests with full round-trip serialization validation
• 🛠️ Developer Friendly - Ergonomic builder APIs, typed IE decoding via Ie::parse::<T>(), and direct marshaling
• 📊 Production Ready - Message comparison, YAML/JSON display, network interface support, and robust examples

Ergonomic Builder API

Build and send PFCP messages in just 2-3 lines:

// Session responses with convenience methods
let response = SessionEstablishmentResponseBuilder::accepted(seid, seq)
    .fseid(upf_seid, upf_ip)
    .marshal()?;

// Or with cause values
let response = SessionModificationResponseBuilder::new(seid, seq)
    .cause_accepted()
    .marshal();

// Requests with type-safe builders
let request = AssociationSetupRequestBuilder::new(seq)
    .node_id(Ipv4Addr::new(10, 0, 0, 1))
    .recovery_time_stamp(SystemTime::now())
    .marshal();

// IntoIe tuple conversions for common IEs
use rs_pfcp::ie::IntoIe;

let fseid_ie = (session_seid, ip_address).into_ie();  // F-SEID from tuple
let fteid_ie = (teid, ip_address).into_ie();           // F-TEID from tuple
let ue_ip_ie = (ipv4, ipv6).into_ie();                 // UE IP dual-stack

// Iterator-based IE access
for pdr in msg.ies(IeType::CreatePdr) {
    process_pdr(pdr);
}

let first_fseid = msg.ies(IeType::Fseid).next();
let pdr_count = msg.ies(IeType::CreatePdr).count();

// Typed IE decoding with Ie::parse<T>()
let pdr_id: PdrId = msg.ies(IeType::PdrId).next()?.parse()?;
let cause: Cause = msg.ies(IeType::Cause).next()?.parse()?;

Protocol Coverage

• ✅ 25/25 Message Types (100% coverage) - All core session and association management
• ✅ 354 Information Elements implemented (354 enum variants) - 100% 3GPP TS 29.244 Release 18 coverage
• ✅ Advanced Features - Network slicing (S-NSSAI), multi-access support, F-TEID with CHOOSE flags, QoS enforcement, usage reporting, Ethernet PDU sessions
• ✅ 5G Core Integration - Session establishment, modification, deletion, and comprehensive usage reporting with quota management

🏃‍♂️ Quick Start

Installation

Add to your Cargo.toml:

[dependencies]
rs-pfcp = "0.4.0"

Basic Usage

use rs_pfcp::message::session_establishment_request::SessionEstablishmentRequestBuilder;
use rs_pfcp::message::session_establishment_response::SessionEstablishmentResponseBuilder;
use std::net::Ipv4Addr;

// Create a session establishment request with ergonomic builders
let request_bytes = SessionEstablishmentRequestBuilder::new(session_id, sequence_number)
    .node_id(Ipv4Addr::new(10, 0, 0, 1))           // Direct IP address
    .fseid(0x123456789ABCDEF0, my_ip_addr)         // SEID + IP
    .create_pdrs(vec![pdr.to_ie()])
    .create_fars(vec![far.to_ie()])
    .marshal()?;                                    // Direct marshaling

// Send over network
socket.send(&request_bytes)?;

// Parse received messages and respond
let parsed_msg = rs_pfcp::message::parse(&received_bytes)?;
match parsed_msg.msg_type() {
    MsgType::SessionEstablishmentRequest => {
        // Handle session establishment
        println!("Received session establishment for SEID: {:016x}",
                 parsed_msg.seid().unwrap_or(0));

        // Create response with convenience methods
        let response_bytes = SessionEstablishmentResponseBuilder::accepted(seid, sequence)
            .fseid(upf_seid, upf_ip)
            .marshal()?;

        socket.send(&response_bytes)?;
    }
    _ => {} // Handle other message types
}

Message Comparison & Validation

use rs_pfcp::comparison::MessageComparator;

// Test mode - ignore transient fields (sequence, timestamps)
let result = MessageComparator::new(&msg1, &msg2)
    .test_mode()
    .compare()?;

if result.is_match {
    println!("✓ Messages match functionally");
} else {
    println!("Differences found:");
    for mismatch in &result.ie_mismatches {
        println!("  - {:?}: {:?}", mismatch.ie_type, mismatch.reason);
    }
}

// Semantic comparison with timestamp tolerance
let result = MessageComparator::new(&msg1, &msg2)
    .semantic_mode()                    // Compare F-TEID, UE IP by meaning
    .timestamp_tolerance(5)              // 5 second tolerance
    .ignore_sequence()
    .compare()?;

// Generate detailed diff
let result = MessageComparator::new(&msg1, &msg2)
    .generate_diff(true)
    .compare()?;

if let Some(diff) = result.diff {
    println!("{}", diff);  // YAML-formatted differences
}

Features:

• Multiple comparison modes - Strict, semantic, test, and audit presets
• Semantic comparison - F-TEID, UE IP Address compared by function, not bytes
• Timestamp tolerance - Configurable window for timestamp comparison
• Flexible IE filtering - Ignore specific IEs, focus on subsets, or handle timestamps
• Detailed reporting - Match statistics, mismatch details, YAML diffs

Network Examples

The library includes comprehensive examples for real-world scenarios:

# Run PFCP heartbeat server
cargo run --example heartbeat-server -- --interface lo --port 8805

# Run session client connecting to UPF
cargo run --example session-client -- --address 127.0.0.1 --sessions 5

# Analyze captured PFCP traffic
cargo run --example pcap-reader -- --pcap traffic.pcap --format yaml

# Demo message comparison and validation
cargo run --example message-comparison          # All demos
cargo run --example message-comparison semantic # Specific demo

# Run performance benchmarks
cargo bench

🏗️ Architecture

Core Components

rs-pfcp/
├── src/ie/              # Information Elements (354 types, 100% Rel-18)
│   ├── f_teid.rs        # F-TEID with 3GPP compliant CHOOSE flags
│   ├── pdn_type.rs      # PDN connection types (IPv4/IPv6/Non-IP)
│   ├── snssai.rs        # 5G Network Slicing identifiers
│   ├── ethernet_*.rs    # Ethernet PDU session support (10 IEs)
│   └── ...
├── src/message/         # PFCP Messages (25 types)
│   ├── session_*.rs     # Session lifecycle management
│   ├── association_*.rs # Node association handling
│   └── heartbeat.rs     # Keep-alive mechanism
├── src/comparison/      # Message comparison framework
│   ├── builder.rs       # Fluent comparison API
│   ├── semantic.rs      # Semantic comparison (F-TEID, UE IP, timestamps)
│   ├── options.rs       # Configuration options
│   └── result.rs        # Result types and statistics
└── examples/            # Production-ready examples
    ├── session-server/  # UPF simulator
    ├── session-client/  # SMF simulator
    └── pcap-reader/     # Traffic analysis tool

Key Design Principles

• Type Safety - Rust's type system prevents protocol errors at compile time
• Zero Copy - Efficient binary serialization without unnecessary allocations
• Builder Patterns - Intuitive construction of complex PFCP messages
• Error Handling - Comprehensive error types with proper cause codes
• Testing - Every marshal/unmarshal operation verified with round-trip tests

📖 Documentation

Quick Links

Document	Purpose
Documentation Hub	Complete documentation index
API Guide	Comprehensive API reference and usage patterns
Comparison Guide	Message comparison, testing, and validation
IE Support	Complete Information Element implementation status
Messages Reference	Message types, usage patterns, and code examples
Examples Guide	Running and understanding example applications

Guides & Tutorials

• Comparison Guide - Testing and validating PFCP messages
• Deployment Guide - Production deployment strategies
• Session Report Demo - Quota management walkthrough
• Git Hooks Setup - Development workflow automation

Reference Documentation

• 3GPP Compliance - Detailed compliance verification
• IE Compliance - Information Element compliance details
• API Documentation - Full API reference on docs.rs

🔒 API Stability

rs-pfcp is currently pre-1.0 (version 0.3.x), meaning the API may change between minor versions. We follow Semantic Versioning and document all breaking changes in the CHANGELOG.

Current Status:

• Version: 0.3.1
• MSRV: Rust 1.87.0
• Spec Compliance: 3GPP TS 29.244 Release 18
• Stability: Pre-1.0 (API evolving)

Upgrade Guide

When upgrading between versions:

1. Check CHANGELOG.md for breaking changes
2. Run cargo update -p rs-pfcp
3. Fix compiler errors (we prefer compile-time breaks over runtime breaks)
4. Test your integration

For detailed API stability guarantees and version roadmap, see docs/API-STABILITY.md.

Writing Future-Proof Code

✅ DO: Use builder patterns, trait methods, and public constructors ❌ DON'T: Access struct fields directly or depend on internal modules

We provide migration guides for all breaking changes and deprecate features before removing them.

🔧 Development

Build and Test

# Build the library
cargo build

# Run all tests (3,400+ tests)
cargo test

# Run specific test category
cargo test ie::f_teid          # Test F-TEID implementation
cargo test message::heartbeat  # Test heartbeat messages

# Run performance benchmarks
cargo bench

# Check code formatting and linting
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings

# Generate documentation
cargo doc --no-deps --document-private-items --all-features

Example Workflows

# Test complete session lifecycle
cargo run --example session-server -- --interface lo --port 8805 &
cargo run --example session-client -- --address 127.0.0.1 --sessions 3

# Analyze protocol compliance
cargo run --example pcap-reader -- --pcap captured.pcap --format json --pfcp-only

# Benchmark performance
cargo test --release -- --ignored bench_

Cross-Language Interoperability Testing

Go interoperability tests (using go-pfcp) live in a separate repository: github.com/xandlom/go-pfcp-interop

It verifies cross-compatibility between rs-pfcp (Rust) and Go PFCP implementations:

• Association Setup/Release between Rust and Go stacks
• Complete session lifecycle (establish, modify, report, delete)
• Binary protocol compatibility and 3GPP TS 29.244 compliance

🌟 Real-World Usage

The library covers the full 5G session lifecycle: PDR/FAR construction with grouped IE builders, usage reporting with quota triggers, Ethernet PDU sessions, and network slicing (S-NSSAI). See docs/guides/api-guide.md for complete examples and examples/session-client/ for a working SMF simulator.

🤝 Contributing

We welcome contributions! This library is actively maintained and we're happy to help with:

• 🐛 Bug Reports - Protocol compliance issues, performance problems
• 💡 Feature Requests - Additional 3GPP features, improved APIs
• 📖 Documentation - Examples, tutorials, architectural guides
• 🧪 Testing - Real-world scenarios, edge cases, performance benchmarks

📜 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by the excellent go-pfcp library
• Built according to 3GPP TS 29.244 Release 18 specification
• Developed with ❤️ for the 5G networking community

---

Ready to build next-generation 5G networks with Rust? Check out our examples to get started! 🚀