Review this C# method that builds a fixed-layout binary message for a partner system, including a customer name field limited to 32 bytes. What is wrong and how would you fix it?

1. What the partner actually receives

For Id = 1, Name = "José" on an x64 machine:

expected (spec):  00 00 00 01 | 00 05 | 4A 6F 73 C3 A9 00 00 ... 00
sent (original):  01 00 00 00 | 04 00 | 4A 6F 73 3F 00 00 ... 00
                  ^ ID reads as 16,777,216   ^ length 1,024   ^ '?' instead of é

One hex dump makes the whole review obvious, which is why golden-byte tests are so effective.

2. Counting the right thing

Worst cases: a CJK character is 3 bytes (so about 10 fit in 32), an emoji with a skin-tone modifier is 8 bytes.

3. Truncation strategy

for each grapheme cluster in name:
    bytes = UTF-8 byte count of the cluster
    if written + bytes > 32: stop
    encode the cluster into the field, written += bytes
pad the remaining bytes with 0x00
write nameLength = written (big-endian uint16)

Alternative: System.Text.Unicode.Utf8.FromUtf16 writes only complete scalar values when the destination is too small (returns DestinationTooSmall), which avoids invalid UTF-8 but can still split a grapheme such as an emoji with a modifier. Use grapheme truncation when the text is user-visible at the other end.

4. Why Span and BinaryPrimitives

• The fixed version writes straight into the destination buffer: no intermediate arrays from BitConverter.GetBytes or Encoding.GetBytes.
• BinaryPrimitives is explicit about byte order and compiles to a byte-swap instruction.
• Callers sending thousands of messages a second can pass a pooled buffer (ArrayPool<byte>.Shared) or a PipeWriter span.

5. Questions to ask the partner (or check in the spec)

• Is the name zero-padded or space-padded? Is nameLength the used bytes or always 32?
• Should truncated names be flagged? Silent truncation of legal names can matter for identity checks.
• Is there a version byte for future changes? If not, propose one.

6. Testing approach

• Golden bytes: the partner's sample message as a hex string; assert byte-for-byte equality.
• Property-style tests: for random Unicode strings, the output field never exceeds 32 bytes, always decodes as valid UTF-8, and is a prefix of the original by graphemes.
• Boundary tests: exactly 32 ASCII characters, 31 ASCII + é, emoji at the boundary, empty name.

7. Try it yourself

1. Run the original method for José and print the hex; compare it with the expected bytes above.
2. Change only the encoding to UTF-8 and pass a 32-character Vietnamese name; observe the exception.
3. Implement the fixed version and write the golden-byte, boundary and random-string tests.

namespace PartnerProtocol;

using System.Buffers.Binary;
using System.Globalization;
using System.Text;

public sealed record Customer(int Id, string Name);

public static class PartnerMessage
{
    public const int NameFieldBytes = 32;
    public const int Size = 4 + 2 + NameFieldBytes;

    public static byte[] Build(Customer customer)
    {
        var buffer = new byte[Size];
        Write(customer, buffer);
        return buffer;
    }

    // Spec: [int32 id BE][uint16 nameLength BE][32 bytes UTF-8 name, zero-padded]
    public static void Write(Customer customer, Span<byte> destination)
    {
        ArgumentNullException.ThrowIfNull(customer);
        ArgumentNullException.ThrowIfNull(customer.Name);
        ArgumentOutOfRangeException.ThrowIfNegative(customer.Id);
        if (destination.Length < Size)
        {
            throw new ArgumentException($"Destination must be at least {Size} bytes.", nameof(destination));
        }

        BinaryPrimitives.WriteInt32BigEndian(destination, customer.Id);

        Span<byte> nameField = destination.Slice(6, NameFieldBytes);
        nameField.Clear(); // zero padding
        int written = EncodeTruncated(customer.Name, nameField);

        BinaryPrimitives.WriteUInt16BigEndian(destination.Slice(4, 2), (ushort)written);
    }

    // Encodes whole grapheme clusters as UTF-8 until the next one would not fit.
    private static int EncodeTruncated(ReadOnlySpan<char> text, Span<byte> field)
    {
        int written = 0;
        while (!text.IsEmpty)
        {
            int length = StringInfo.GetNextTextElementLength(text);
            ReadOnlySpan<char> element = text[..length];
            int needed = Encoding.UTF8.GetByteCount(element);
            if (written + needed > field.Length)
            {
                break;
            }
            written += Encoding.UTF8.GetBytes(element, field[written..]);
            text = text[length..];
        }
        return written;
    }
}

// xUnit golden-byte test
public class PartnerMessageTests
{
    [Fact]
    public void Matches_partner_specification_example()
    {
        byte[] bytes = PartnerMessage.Build(new Customer(1, "José"));
        string expected = "00000001" + "0005" + "4A6F73C3A9" + new string('0', 27 * 2);
        Assert.Equal(expected, Convert.ToHexString(bytes));
    }
}