midi_ci_pe.hpp

Go to the documentation of this file.

#pragma once
 
// MIDI-CI Property Exchange (PE) — multipart Get/Set messaging plus
// Subscribe/Notify management on top of the discovery layer.
//
// The PE wire format wraps every Get/Set/Subscribe Inquiry and Reply in
// SysEx envelopes whose body looks like:
//
//   request_id        : 1 byte (1..0x7F; 0 reserved)
//   header_length     : 2 bytes 7-bit LE
//   header_data       : N bytes Mcoded7-encoded JSON UTF-8
//   total_chunks      : 2 bytes 7-bit LE
//   chunk_number      : 2 bytes 7-bit LE  (1-indexed)
//   payload_length    : 2 bytes 7-bit LE
//   payload_data      : N bytes Mcoded7-encoded resource bytes
//
// Pulp implements the framing + Mcoded7 + JSON-header construction here.
// Optional zlib payload encoding (MIDI-CI v1.2 §6.3) is exposed through
// pe_compress()/pe_decompress(); those helpers operate on payload bytes only
// and do not touch the SysEx envelope or Mcoded7 framing.
//
// This file is intentionally header-only-ish: it owns no I/O. The caller
// drives SysEx in/out around it.
 
#include <cstddef>
#include <cstdint>
#include <functional>
#include <optional>
#include <string>
#include <string_view>
#include <unordered_map>
#include <vector>
 
#include <pulp/midi/midi_ci.hpp>
 
namespace pulp::midi {

enum class PeMessageType : uint8_t {
    GetInquiry      = 0x34,
    GetReply        = 0x35,
    SetInquiry      = 0x36,
    SetReply        = 0x37,
    SubscribeInquiry = 0x38,
    SubscribeReply   = 0x39,
    Notify           = 0x3F,
};

struct PeChunk {
    uint8_t request_id = 0;
    uint16_t total_chunks = 0;
    uint16_t chunk_number = 0;       
    std::string header_json;         
    std::vector<uint8_t> payload;    
};

std::vector<uint8_t> pe_build_message(PeMessageType pe_type,
                                      uint8_t ci_version,
                                      MUID source,
                                      MUID destination,
                                      uint8_t request_id,
                                      std::string_view header_json,
                                      uint16_t total_chunks,
                                      uint16_t chunk_number,
                                      const uint8_t* payload,
                                      std::size_t payload_size);
 
inline std::vector<uint8_t> pe_build_message(PeMessageType pe_type,
                                             uint8_t ci_version,
                                             MUID source,
                                             MUID destination,
                                             uint8_t request_id,
                                             std::string_view header_json,
                                             uint16_t total_chunks,
                                             uint16_t chunk_number,
                                             const std::vector<uint8_t>& payload) {
    return pe_build_message(pe_type, ci_version, source, destination,
                            request_id, header_json, total_chunks,
                            chunk_number, payload.data(), payload.size());
}

std::optional<PeChunk> pe_parse_message(const uint8_t* data, std::size_t size);

std::vector<std::vector<uint8_t>>
pe_split_into_chunks(PeMessageType pe_type,
                     uint8_t ci_version,
                     MUID source,
                     MUID destination,
                     uint8_t request_id,
                     std::string_view header_json,
                     const uint8_t* payload,
                     std::size_t payload_size,
                     std::size_t max_payload_bytes);

class PeReassembler {
public:
    std::optional<PeChunk> push(PeChunk chunk);

    void cancel(uint8_t request_id);

    std::size_t pending_transfers() const { return slots_.size(); }
 
private:
    struct Slot {
        uint16_t total = 0;
        uint16_t received = 0;
        std::string header_json;
        std::vector<std::vector<uint8_t>> chunks;  
        std::vector<bool> seen;                    
    };
    std::unordered_map<uint8_t, Slot> slots_;
};
 
// ── zlib payload encoding (MIDI-CI 1.2 §6.3) ────────────────────────────
//
// PE payloads may be zlib-wrapped (RFC 1950) prior to Mcoded7 encoding
// when the JSON header advertises `"compressed": "zlib"`. Both helpers
// are payload-only — they do not touch the SysEx envelope or the
// Mcoded7 framing.
//
// NOT RT-safe — both calls heap-allocate the output buffer and run
// `deflate` / `inflate` internally.

std::optional<std::vector<uint8_t>> pe_compress(const uint8_t* data, std::size_t size);
 
inline std::optional<std::vector<uint8_t>> pe_compress(const std::vector<uint8_t>& payload) {
    return pe_compress(payload.data(), payload.size());
}

std::optional<std::vector<uint8_t>> pe_decompress(const uint8_t* data, std::size_t size);
 
inline std::optional<std::vector<uint8_t>> pe_decompress(const std::vector<uint8_t>& blob) {
    return pe_decompress(blob.data(), blob.size());
}

std::string pe_header_make(std::string_view resource,
                           std::string_view command = {},
                           int status = 200);

bool pe_header_parse(std::string_view json,
                     std::string* resource,
                     std::string* command,
                     int* status);
 
// ── Subscription management ─────────────────────────────────────────────

struct PeSubscription {
    std::string subscription_id;   
    std::string resource;
    MUID subscriber;
};

class PeSubscriptionManager {
public:
    std::string subscribe(std::string_view resource, MUID subscriber);

    bool unsubscribe(std::string_view subscription_id);

    std::vector<PeSubscription> subscribers_of(std::string_view resource) const;

    const std::vector<PeSubscription>& all() const { return subs_; }
 
private:
    std::vector<PeSubscription> subs_;
    uint64_t next_id_ = 1;
};
 
}  // namespace pulp::midi