Contract 0.3.0: memory write (POST /mem) + audio drain (GET /audio) 674b8447022b

**Contract version: 0.3.0** (semver; clients assert on the MAJOR). 0.3 adds

memory write (`POST /mem`) and an audio drain (`GET /audio`); 0.2 added input

injection (`POST /key`, `POST /reset`). Every minor is purely additive, so older

clients keep working and servers advertise the highest level whose callbacks are

all present via `/status.contract`.

  "contract": "0.3.0",

### `POST /mem?addr=<a>[&bank=<b>]`  *(0.3)*

Write (poke) memory. The write-sibling of `GET /mem`; same address/bank model.

- `addr`, `bank` — as for the read form. `len` is NOT a query param: the byte

  count is the request **body** length.

- Body — `application/octet-stream`, the raw bytes to write starting at `addr`.

  Servers MAY cap the body (recommend ≥ 65536).

- Response: `{ "written": <n> }` — bytes actually written. A server MAY write

  fewer than requested (e.g. it stops at a ROM/unwritable boundary); the count

  tells the truth.

- Writes go through the emulator's CPU write path. Intended for RAM/state

  fixup (force lives, seed a level, restore a snapshot). Writing an I/O register

  MAY trigger device side effects — that is the caller's responsibility.

- Determinism: poke while `paused` so the machine can't overwrite between the

  write and a subsequent read.

### `GET /audio`  *(0.3)*

Drain the audio the emulator has synthesised since the last `/audio` call — the

audio analogue of `/screenshot`, but a *window* (everything since last drain)

rather than a snapshot.

- Response: `audio/wav`, a self-describing **PCM WAV** (RIFF, 16-bit signed,

  interleaved). The header carries the sample rate and channel count; clients

  read them from the WAV — do not hardcode (appendix lists native rates).

- The server keeps a bounded ring of mixed output samples, teed from the same

  buffer that feeds the sound device. Each call empties the ring and returns it;

  an empty ring returns a valid zero-frame WAV.

- Determinism: under `/pause` + `/step`, the drain covers exactly the audio of

  the stepped frames, so a test can `pause → step(n) → GET /audio` and get the

  sound of those `n` frames reproducibly.

- `X-Rrdc-Audio-Dropped: <n>` — samples the ring dropped (oldest-first) to

  overflow since the last drain. Non-zero means drain more often. `0` when clean.

- Audio: stereo (2 ch), native rate `25000000/512` ≈ **48828 Hz**, teed from the

  mixed `audio_render()` output.

  emulators. Implement the backend callbacks (four are enough for 0.1; add

  `inject_key`/`reset` for 0.2 and `write_mem`/`capture_audio` for 0.3 — a NULL

  callback makes its endpoint return 501 and lowers the advertised contract),

  wire three loop hooks, call `retro_control_start(port, &backend)`; the socket

  loop, HTTP parsing, PPM/JSON encoding and pause/step control come for free.

  The Commander X16 fork does this.

../SPEC.md (0.3.x). Depends only on the stdlib; Pillow is optional and only

    def _post(self, path: str, body: bytes = b"") -> bytes:

        req = urllib.request.Request(self.base + path, method="POST", data=body)

    def mem_write(self, addr: int, data: bytes, bank: int | None = None) -> int:

        """Write/poke bytes at addr (contract 0.3). Returns the number written."""

        path = f"/mem?addr={addr}"

        if bank is not None:

            path += f"&bank={bank}"

        return int(json.loads(self._post(path, bytes(data)))["written"])

    def audio(self) -> bytes:

        """Raw WAV (PCM) of audio synthesized since the last call (contract 0.3).

        Drain regularly (e.g. after each step) so the ring doesn't overflow."""

        body, _ = self._get("/audio")

        return body

"""Contract conformance tests (SPEC.md 0.3.x). Platform-agnostic: framebuffer

exercised but banking is not required. Tests gated on the server's advertised

minor (input injection 0.2; memory write + audio 0.3) skip on older servers."""

# -- contract 0.3: memory write + audio (skipped on < 0.3 servers) -----------

def test_mem_write_roundtrip(emu):

    """POST /mem pokes bytes; GET /mem reads them back (contract 0.3)."""

    if _contract_minor(emu) < 3:

        pytest.skip("contract < 0.3 (no memory write)")

    emu.pause()               # freeze so the machine can't overwrite between write+read

    try:

        addr, payload = 0x0400, bytes([0xA5, 0x5A, 0x00, 0xFF])

        assert emu.mem_write(addr, payload) == len(payload)

        assert emu.mem(addr, len(payload)) == payload

    finally:

        emu.resume()

def test_mem_write_requires_post(emu):

    if _contract_minor(emu) < 3:

        pytest.skip("contract < 0.3")

    # GET /mem is the read path (200), never a write — writing needs POST.

    code, _ = _raw(emu, "GET", "/mem?addr=0&len=1")

    assert code == 200

def test_audio_is_valid_wav(emu):

    """GET /audio returns a parseable PCM WAV (contract 0.3)."""

    if _contract_minor(emu) < 3:

        pytest.skip("contract < 0.3 (no audio)")

    import io

    import wave

    emu.pause(); emu.step(4)          # produce a little audio deterministically

    w = wave.open(io.BytesIO(emu.audio()), "rb")

    assert w.getsampwidth() == 2      # signed 16-bit

    assert w.getnchannels() in (1, 2)

    assert w.getframerate() > 0

    emu.resume()

/* single-slot marshalled request. */

typedef enum { REQ_NONE = 0, REQ_MEM, REQ_REGS, REQ_SHOT, REQ_KEY, REQ_RESET,

               REQ_WRITE, REQ_AUDIO } req_t;

static const uint8_t *g_write_data;   /* POST /mem body (HTTP-thread owned) */

static char     g_resp_extra[64];     /* extra response header line, or "" */

#define AUDIO_MAX_SAMPLES (1u << 18)   /* drain cap: 256K int16 (~2.7 s stereo @48.8k) */

static void le16(uint8_t *p, uint16_t v) { p[0] = v; p[1] = v >> 8; }

static void le32(uint8_t *p, uint32_t v) { p[0] = v; p[1] = v >> 8; p[2] = v >> 16; p[3] = v >> 24; }

/* Drain the backend's audio ring and wrap it as a canonical PCM WAV. */

static void build_wav(void)

{

    static int16_t samp[AUDIO_MAX_SAMPLES];

    int rate = 48000, channels = 1;

    uint32_t dropped = 0;

    uint32_t n = g_be->capture_audio(samp, AUDIO_MAX_SAMPLES, &rate, &channels, &dropped);

    if (channels < 1) channels = 1;

    if (rate < 1) rate = 1;

    uint32_t data_bytes = n * 2;               /* int16 samples */

    uint32_t total = 44 + data_bytes;

    uint8_t *out = (uint8_t *)malloc(total);

    if (!out) { g_resp_body = NULL; g_resp_len = 0; g_resp_status = 500; return; }

    uint32_t byte_rate = (uint32_t)rate * channels * 2;

    memcpy(out, "RIFF", 4);       le32(out + 4, 36 + data_bytes);

    memcpy(out + 8, "WAVE", 4);

    memcpy(out + 12, "fmt ", 4);  le32(out + 16, 16);

    le16(out + 20, 1);            le16(out + 22, (uint16_t)channels);

    le32(out + 24, (uint32_t)rate);

    le32(out + 28, byte_rate);    le16(out + 32, (uint16_t)(channels * 2));

    le16(out + 34, 16);

    memcpy(out + 36, "data", 4);  le32(out + 40, data_bytes);

    memcpy(out + 44, samp, data_bytes);

    g_resp_body = out; g_resp_len = total; g_resp_status = 200;

    g_resp_ctype = "audio/wav";

    snprintf(g_resp_extra, sizeof g_resp_extra,

             "X-Rrdc-Audio-Dropped: %u\r\n", (unsigned)dropped);

}

    g_resp_extra[0] = 0;

        g_resp_ctype = "application/json";

        break;

    }

    case REQ_WRITE: {

        const char *json; char *b;

        if (!g_be->write_mem) {

            json = "{\"error\":\"not implemented\"}"; g_resp_status = 501;

            size_t l = strlen(json); b = (char *)malloc(l + 1);

            if (b) memcpy(b, json, l + 1);

            g_resp_len = b ? l : 0;

        } else {

            uint32_t wrote = g_be->write_mem(g_req_addr, g_req_bank, g_req_len, g_write_data);

            b = (char *)malloc(48);

            g_resp_len = b ? (size_t)snprintf(b, 48, "{\"written\":%u}", (unsigned)wrote) : 0;

            g_resp_status = 200;

        }

        g_resp_body = (uint8_t *)b;

    case REQ_AUDIO:

        if (g_be->capture_audio) build_wav();

        else {

            const char *json = "{\"error\":\"not implemented\"}";

            size_t l = strlen(json); uint8_t *b = (uint8_t *)malloc(l + 1);

            if (b) memcpy(b, json, l + 1);

            g_resp_body = b; g_resp_len = b ? l : 0; g_resp_status = 501;

            g_resp_ctype = "application/json";

        }

        break;

/* `extra`, if non-NULL, is a complete header line ("Name: value\r\n"). */

                      const uint8_t *body, size_t len, const char *extra)

    char hdr[320];

        "Connection: close\r\nAccess-Control-Allow-Origin: *\r\n%s\r\n",

        status, reason, ctype, len, extra ? extra : "");

    send_http(fd, status, "application/json", (const uint8_t *)json, strlen(json), NULL);

    char extra[64]; memcpy(extra, g_resp_extra, sizeof extra);

    send_http(fd, st, ct, body, len, extra[0] ? extra : NULL);

    /* Advertise the highest level whose defining callbacks are all present. */

    const char *contract =

        (g_be->inject_key && g_be->write_mem && g_be->capture_audio) ? "0.3.0" :

        g_be->inject_key ? "0.2.0" : "0.1.0";

/* Read a request body (POST /mem). `req`/`n` = what handle_conn already recv'd

 * (headers + maybe some body); reads the rest per Content-Length. Returns a

 * malloc'd buffer of *out_len bytes (caller frees), capped at MEM_CAP. */

static uint8_t *read_body(int fd, char *req, size_t n, size_t *out_len)

{

    *out_len = 0;

    char *hdr_end = strstr(req, "\r\n\r\n");

    if (!hdr_end) return NULL;

    char *body_start = hdr_end + 4;

    long clen = 0;

    char *cl = strstr(req, "Content-Length:");

    if (!cl) cl = strstr(req, "content-length:");

    if (cl) clen = strtol(cl + 15, NULL, 10);

    if (clen < 0) clen = 0;

    if (clen > (long)MEM_CAP) clen = (long)MEM_CAP;

    uint8_t *body = (uint8_t *)malloc((size_t)clen ? (size_t)clen : 1);

    if (!body) return NULL;

    size_t have = (size_t)(req + n - body_start);

    if (have > (size_t)clen) have = (size_t)clen;

    memcpy(body, body_start, have);

    size_t got = have;

    while (got < (size_t)clen) {

        ssize_t r = recv(fd, body + got, (size_t)clen - got, 0);

        if (r <= 0) break;

        got += (size_t)r;

    }

    *out_len = got;

    return body;

}

    if (!strcmp(target, "/audio"))           { do_marshalled(fd, REQ_AUDIO); return; }

        if (is_post) {                        /* 0.3: write / poke */

            size_t blen = 0;

            uint8_t *body = read_body(fd, req, n, &blen);

            g_req_len = (uint32_t)blen;

            g_write_data = body;

            do_marshalled(fd, REQ_WRITE);

            free(body);

        } else {                              /* read */

            g_req_len = (uint32_t)query_long(query, "len", 0);

            do_marshalled(fd, REQ_MEM);

        }

/* Highest contract the core implements. The server advertises the highest level

 * whose backend callbacks are all present: 0.3.0 needs inject_key + write_mem +

 * capture_audio; 0.2.0 needs inject_key; else 0.1.0. Keeps a partial backend

 * honest. */

#define RETRO_CONTROL_CONTRACT "0.3.0"

    /* 0.3: write len bytes from `in` at addr (debug/state poke; bank<0 =

     * current). Intended for RAM/state — I/O-register writes may trigger device

     * side effects. Return bytes written. NULL => POST /mem returns 501. */

    uint32_t (*write_mem)(uint32_t addr, int32_t bank, uint32_t len,

                          const uint8_t *in);

    /* 0.3: drain up to `cap` interleaved signed-16-bit audio samples the

     * emulator has synthesised since the last call into `out`; set *rate and

     * *channels; set *dropped to samples lost to overflow since the last drain.

     * Return the number of int16 samples written. NULL => /audio returns 501. */

    uint32_t (*capture_audio)(int16_t *out, uint32_t cap,

                              int *rate, int *channels, uint32_t *dropped);