warp-pipe/docs/milestone-0.md

Milestone 0 - Foundation

Build system

• CMake 3.20+
• C++17
• pkg-config
• libpipewire-0.3 development files

Public API surface

• Namespace: warppipe
• Core types: Status, StatusCode, Result
• Threading: ThreadingMode (caller thread or managed thread loop)
• Primary entry: Client
• Handles: NodeId, PortId, LinkId, RuleId
• Data shapes: NodeInfo, PortInfo, VirtualSink, VirtualSource, Link, RouteRule

Error model

• StatusCode enum with explicit categories (ok, invalid argument, not found, unavailable, permission denied, timeout, internal, not implemented)
• Status carries code + message; Result pairs Status with value

Threading model

• Default: managed thread loop owned by Client
• Optional: caller thread loop for embedding in existing event loop

Performance budget and metrics

• Target: 200 create/modify/delete operations in under 1 second on a warm PipeWire connection
• Target per operation: median < 2 ms, p95 < 10 ms for create or delete
• Track metrics for: create virtual sink/source, create link, delete link

Ephemeral source identity strategy

• Match priority: application.name, application.process.binary, media.role, node.name
• Fallback: client properties and media class
• Avoid serial IDs or object IDs for persistence
• Rule matching is stable across restarts and reconnects

Tests to add (Milestone 0)

• Missing PipeWire daemon: Client::Create returns StatusCode::kUnavailable
• Missing link-factory module: CreateLink returns StatusCode::kUnavailable
• Missing metadata module: SaveConfig or policy init returns StatusCode::kUnavailable
• Invalid media class in virtual node creation: returns StatusCode::kInvalidArgument

Performance tests (Milestone 0)

• Microbenchmark harness that measures connect -> create N -> destroy N
• Baseline: N=200 with subsecond wall time on a warm PipeWire connection
• Record median and p95 latency per operation