/src/Message.zig at 4819312d21cb99186a0a8e27d0ab7fc62075126c

// Copyright 2025 Shota FUJI
//
// Licensed under the Zero-Clause BSD License or the Apache License, Version 2.0, at your option.
// You may not use, copy, modify, or distribute this file except according to those terms. You can
// find a copy of the Zero-Clause BSD License at LICENSES/0BSD.txt, and a copy of the Apache License,
// Version 2.0 at LICENSES/Apache-2.0.txt. You may also obtain a copy of the Apache License, Version
// 2.0 at <https://www.apache.org/licenses/LICENSE-2.0>
//
// SPDX-License-Identifier: 0BSD OR Apache-2.0

//! This module contains parsing of and serializing from SOOD message used by Roon Core and
//! discovery clients. References:
//! <https://github.com/RoonLabs/node-roon-api/blob/51258392f8bfae3fe218740dda5bc049a822872e/sood.js>
//! <https://github.com/pavoni/pyroon/blob/981a62b715c0bd31664342a7cff94a8624e18f79/roonapi/soodmessage.py>
//! Since there is no official documentation and the message format is flexible (key-value fields,)
//! this module does not add semantics or "static types" over it.

const std = @import("std");

const constants = @import("constants.zig");
const property = @import("Message/property.zig");

pub const Property = property.Property;
pub const PropertyParseError = property.ParseError;

const Self = @This();

kind: Kind,

body: []const u8,

pub const Kind = enum {
    /// A message has unsupported/unknown type field. Caller may reject a message of this kind.
    /// This variant exists for forward compatibility.
    unknown,

    /// Query message. A client performing discovery sends a message of this kind.
    query,

    /// Response message. Roon Core received a Query sends a message of this kind.
    response,
};

pub const HeaderParseError = error{
    /// A message header is incomplete.
    InvalidHeaderSize,

    /// A message does not have valid SOOD message signature: `['S', 'O', 'O', 'D', 0x2]`.
    InvalidSignature,
};

/// Returns a parsed message. Created Message's fields refer to the `bytes`: freeing `bytes` then
/// accessing a Message's field would be use-after-free.
pub fn parse(bytes: []const u8) HeaderParseError!Self {
    if (bytes.len < constants.header_byte_size) {
        return HeaderParseError.InvalidHeaderSize;
    }

    if (!std.mem.startsWith(u8, bytes, constants.magic_string)) {
        return HeaderParseError.InvalidSignature;
    }

    const kind: Kind = switch (bytes[5]) {
        'Q' => .query,
        'R' => .response,
        else => .unknown,
    };

    return .{
        .kind = kind,
        .body = bytes[constants.header_byte_size..],
    };
}

test "Should not parse non-SOOD messages" {
    {
        // PNG file signature
        const message = parse("\x89PNG\r\n\x1a\n");
        try std.testing.expectError(HeaderParseError.InvalidSignature, message);
    }

    {
        // No `0x02` after `SOOD`
        const message = parse("SOODR\x02foo");
        try std.testing.expectError(HeaderParseError.InvalidSignature, message);
    }

    {
        // Too short
        const message = parse("SOOD\x02");
        try std.testing.expectError(HeaderParseError.InvalidHeaderSize, message);
    }
}

test "Should parse unknown message type" {
    {
        const message = try parse("SOOD\x02r");
        try std.testing.expectEqual(Kind.unknown, message.kind);
    }

    {
        const message = try parse("SOOD\x02\x02");
        try std.testing.expectEqual(Kind.unknown, message.kind);
    }
}

pub const Iterator = struct {
    /// Remaining bytes.
    bytes: []const u8,

    pub fn next(it: *Iterator) PropertyParseError!?Property {
        if (it.bytes.len == 0) {
            return null;
        }

        var p: Property = undefined;
        const i = try property.parseInto(it.bytes, &p);

        it.bytes = it.bytes[i..];

        return p;
    }
};

pub fn iterator(self: *const Self) Iterator {
    return .{ .bytes = self.body };
}

test iterator {
    const message = try parse("SOOD\x02R\x03foo\x00\x03bar");

    var it = message.iterator();

    const foo = try it.next();

    try std.testing.expect(std.mem.eql(u8, foo.?.key, "foo"));
    try std.testing.expect(std.mem.eql(u8, foo.?.value, "bar"));

    try std.testing.expect(try it.next() == null);
}

pub const WriteError = error{
    /// Target buffer does not have enough space for the header.
    NoEnoughSpace,

    /// Tried to write unknown type message.
    UnknownKind,

    /// Size of property key is too large.
    TooLargePropertyKey,

    /// Size of property value is too large.
    TooLargePropertyValue,
};

/// Generate SOOD message bytes. Caller is responsible for `free`-ing the returned data.
pub fn write(allocator: std.mem.Allocator, kind: Kind, props: []const Property) ![]u8 {
    var props_size: usize = 0;
    for (props) |p| {
        props_size += 1 + p.key.len + 2 + p.value.len;
    }

    const buf = try allocator.alloc(u8, constants.header_byte_size + props_size);
    errdefer allocator.free(buf);

    std.mem.copyForwards(u8, buf, constants.magic_string);

    buf[constants.magic_string.len] = switch (kind) {
        .query => 'Q',
        .response => 'R',
        else => return WriteError.UnknownKind,
    };

    var i: usize = constants.magic_string.len + 1;
    for (props) |p| {
        if (p.key.len > std.math.maxInt(u8)) {
            return WriteError.TooLargePropertyKey;
        }
        buf[i] = @truncate(p.key.len);
        i += 1;
        std.mem.copyForwards(u8, buf[i..], p.key);
        i += p.key.len;
        if (p.value.len > std.math.maxInt(u16)) {
            return WriteError.TooLargePropertyValue;
        }
        var value_size: [2]u8 = undefined;
        std.mem.writeInt(u16, &value_size, @truncate(p.value.len), .big);
        std.mem.copyForwards(u8, buf[i..], &value_size);
        i += 2;
        std.mem.copyForwards(u8, buf[i..], p.value);
        i += p.value.len;
    }

    return buf;
}

test write {
    const props = &[_]Property{
        .{ .key = "foo", .value = "foo-foo" },
        .{ .key = "bar", .value = "bar-bar" },
    };
    const bytes = try write(std.testing.allocator, .query, props);
    defer std.testing.allocator.free(bytes);

    try std.testing.expect(
        std.mem.eql(u8, bytes, "SOOD\x02Q\x03foo\x00\x07foo-foo\x03bar\x00\x07bar-bar"),
    );
}

test "Should not write unknown message type" {
    const result = write(std.testing.allocator, .unknown, &.{});

    try std.testing.expectError(WriteError.UnknownKind, result);
}

test "Should not write a key that its size exceeds MAX(u8)" {
    const key = try std.testing.allocator.alloc(u8, std.math.maxInt(u8) + 1);
    defer std.testing.allocator.free(key);
    @memset(key, '?');

    const props = &[_]Property{
        .{ .key = key, .value = "!" },
    };
    const result = write(std.testing.allocator, .query, props);

    try std.testing.expectError(WriteError.TooLargePropertyKey, result);
}

test "Should not write a value that its size exceeds MAX(u16)" {
    const value = try std.testing.allocator.alloc(u8, std.math.maxInt(u16) + 1);
    defer std.testing.allocator.free(value);
    @memset(value, '?');

    const props = &[_]Property{
        .{ .key = "?", .value = value },
    };
    const result = write(std.testing.allocator, .query, props);

    try std.testing.expectError(WriteError.TooLargePropertyValue, result);
}

test "Should write large property" {
    const key = try std.testing.allocator.alloc(u8, std.math.maxInt(u8) - 1);
    defer std.testing.allocator.free(key);
    @memset(key, 'K');

    const value = try std.testing.allocator.alloc(u8, std.math.maxInt(u16) - 1);
    defer std.testing.allocator.free(value);
    @memset(value, 'V');

    const props = &[_]Property{
        .{ .key = key, .value = value },
    };
    const bytes = try write(std.testing.allocator, .query, props);
    defer std.testing.allocator.free(bytes);

    try std.testing.expect(bytes.len > 0);

    const message = try parse(bytes);

    try std.testing.expectEqual(Kind.query, message.kind);

    var it = message.iterator();

    const prop = try it.next();

    try std.testing.expectEqual(std.math.maxInt(u8) - 1, prop.?.key.len);
    try std.testing.expectEqual(std.math.maxInt(u16) - 1, prop.?.value.len);
}