implement-service

name: implement-service description: Implement a new UPnP service in sonos-api by extracting operations from documentation URLs (like https://sonos.svrooij.io/services/av-transport), testing against real speakers, and generating complete Rust code with operations, validation, and tests. Use when implementing new Sonos service modules in sonos-api/src/services/.

Implement Sonos Service

Implement a complete UPnP service module in sonos-api/src/services/ by:

1. Extracting operations from documentation
2. Testing operations against real Sonos speakers
3. Generating Rust code with macros, validation, and tests

Workflow

Step 1: Gather Requirements

Ask user for:

• Documentation URL (e.g., https://sonos.svrooij.io/services/av-transport)
• Service name (e.g., content_directory, use snake_case)

Step 2: Fetch and Parse Documentation

Use WebFetch to extract operations from the documentation URL:

WebFetch: {url}
Prompt: "Extract all UPnP operations. For each, list: action name, input parameters (name, type, description), output parameters (name, type), and any notes about valid values."

Document each operation found with:

• Action name (PascalCase)
• Input parameters and their types
• Output parameters and their types
• Known valid values (for enums/ranges)

Step 3: Discover Speakers

Run speaker discovery:

cargo run -p sonos-discovery --example discover_json

Present discovered speakers to user. Get user selection for which speaker to test against.

Step 4: Test Operations and Discover Validation Requirements

IMPORTANT: This step determines what validation is needed for each operation.

For each operation with parameters, test against the real speaker:

# Test with valid values to get response format
cargo run -p sonos-api --example test_operation -- <ip> <service> <action> Param=ValidValue

# Test with INVALID values to discover validation requirements
cargo run -p sonos-api --example test_operation -- <ip> <service> <action> Param=INVALID

Examples:

# Valid - returns 200 with response
cargo run -p sonos-api --example test_operation -- 192.168.1.100 AVTransport Seek Unit=TRACK_NR Target=1

# Invalid - returns 500 error (needs validation)
cargo run -p sonos-api --example test_operation -- 192.168.1.100 AVTransport Seek Unit=INVALID Target=1

# Valid channel
cargo run -p sonos-api --example test_operation -- 192.168.1.100 RenderingControl GetVolume Channel=Master

# Invalid channel - returns 500 (needs enum validation)
cargo run -p sonos-api --example test_operation -- 192.168.1.100 RenderingControl GetVolume Channel=InvalidChannel

Record which parameters need validation:

• HTTP 500 on invalid value = Add validation
• Parameters with documented allowed values = Add enum validation
• Numeric parameters with bounds = Add range validation
• URI/metadata strings = Usually no validation (device validates)

Step 5: Register Service

If this is a new service, add to sonos-api/src/service.rs:

// Add to Service enum
pub enum Service {
    // ... existing ...
    NewService,
}

// Add to name() match
Service::NewService => "NewService",

// Add to info() match
Service::NewService => ServiceInfo {
    endpoint: "MediaRenderer/NewService/Control",  // Get from docs
    service_uri: "urn:schemas-upnp-org:service:NewService:1",  // Get from docs
    event_endpoint: "MediaRenderer/NewService/Event",
},

// Add to scope() match
Service::NewService => ServiceScope::PerSpeaker,  // Or PerNetwork/PerCoordinator

Step 6: Create Service Module

Create directory: sonos-api/src/services/{service_name}/

Create files:

• mod.rs - Module exports
• operations.rs - UPnP operations
• events.rs - Event parsing (if needed)

Register in sonos-api/src/services/mod.rs:

pub mod {service_name};

Step 7: Implement Operations with Validation

CRITICAL: Every operation MUST have a Validate implementation or the code will not compile.

Read references/macro-patterns.md for detailed patterns including validation.

For each operation:

1. Define the operation:

define_upnp_operation! {
    operation: ActionOperation,
    action: "Action",
    service: ServiceName,
    request: { param: Type, },
    response: (),
    payload: |req| format!("<InstanceID>{}</InstanceID><Param>{}</Param>", req.instance_id, req.param),
    parse: |_xml| Ok(()),
}

2. Implement Validate (REQUIRED):

// No validation needed (parameterless or device validates)
impl Validate for ActionOperationRequest {}

// With validation
impl Validate for ActionOperationRequest {
    fn validate_basic(&self) -> Result<(), crate::operation::ValidationError> {
        // Add validation based on Step 4 testing results
        match self.param.as_str() {
            "VALID1" | "VALID2" => Ok(()),
            other => Err(crate::operation::ValidationError::Custom {
                parameter: "param".to_string(),
                message: format!("Invalid param '{}'", other),
            })
        }
    }
}

Validation patterns based on testing:

Step 8: Add Tests

For each operation, add at minimum:

#[cfg(test)]
mod tests {
    use super::*;
    use crate::operation::UPnPOperation;

    #[test]
    fn test_{operation}_builder() {
        let op = {operation}_operation(/* params */).build().unwrap();
        assert_eq!(op.metadata().action, "{Action}");
    }

    #[test]
    fn test_{operation}_payload() {
        let request = {Operation}OperationRequest { /* fields */ };
        let payload = {Operation}Operation::build_payload(&request).unwrap();
        assert!(payload.contains("<ExpectedElement>"));
    }

    // If validation was added:
    #[test]
    fn test_{operation}_validation() {
        let valid = {Operation}OperationRequest { instance_id: 0, param: "VALID".to_string() };
        assert!(valid.validate_basic().is_ok());

        let invalid = {Operation}OperationRequest { instance_id: 0, param: "INVALID".to_string() };
        assert!(invalid.validate_basic().is_err());
    }
}

Step 9: Verify

Run tests:

cargo test -p sonos-api --lib

Test against real speaker:

cargo run -p sonos-api --example test_operation -- <ip> <Service> <Action>

References

• Macro patterns & validation: Read references/macro-patterns.md for detailed patterns
• Service structure: Read references/service-structure.md for complete module templates

Type Mapping

Common Validation Values (Discovered Through Testing)

Common Services