media:cpp docs | http | tests

packages/media/cpp/.gitignore

@@ -8,3 +8,4 @@ cache
 third_party/vips-dev-*/
 third_party/vips-dev-x64-all*.zip
 .env
+

packages/media/cpp/README.md

@@ -111,7 +111,7 @@ Sharp wraps libvips: **decode → process → encode**. We do the same with `vip
 
 **Windows:** `pm-image resize --ui` opens a **native Win32** dialog to choose input/output paths, max dimensions, fit mode, quality, and enlargement / autorotate / strip options. Other CLI flags seed the dialog; **`--src` / `--dst` are not allowed** with `--ui`. If you cancel, the command exits without processing.
 
-**REST** `POST /v1/resize` and **IPC** use the same JSON keys as the table, plus the fields in the **“Batch paths & cache”** section below.
+**REST** `POST /v1/resize` accepts **`application/json`** (same keys as the table, plus **“Batch paths & cache”** below) **or** **`multipart/form-data`** (upload a file; response is the **image bytes** — see **`serve`**). **IPC** uses the same JSON keys as the table, plus the batch/cache fields.
 
 ---
 
@@ -190,7 +190,7 @@ curl -s -X POST http://127.0.0.1:8080/v1/resize \
 
 All **resize** options (`max_width`, `fit`, …) participate in the same JSON body.
 
-**REST / IPC** always require `"output"` in JSON (no automatic path).
+**REST / IPC** JSON always require `"output"` in JSON (no automatic path). Multipart upload does not use `input`/`output` paths.
 
 ### Output cache
 
@@ -296,20 +296,34 @@ pm-image resize img.jpg rotated.jpg --max-width 1024 --rotate 90 --flip
 ### `serve` — HTTP REST
 
 ```bash
-# Default: http://127.0.0.1:8080 — GET /health, POST /v1/resize with JSON body
+# Default: http://127.0.0.1:8080 — GET /health, POST /v1/resize
 pm-image serve --host 127.0.0.1 -p 8080
 ```
 
-Example resize request (paths must be readable/writable by the server process):
+| Mode | `Content-Type` | Request | Response |
+|------|----------------|---------|----------|
+| **Upload** | `multipart/form-data` | Image part **`file`**, **`image`**, or **`upload`**; optional fields: `max_width`, `max_height`, `format`, `fit`, `quality`, … | **Binary image** (`Content-Type` matches format; default **JPEG** if `format` omitted). `Content-Disposition: inline; filename="resized…"`. |
+| **Paths** | `application/json` | **`input`** and **`output`** (server-visible paths), plus resize / batch / cache fields | **JSON** — `{"ok":true}` or batch `count` / `outputs` |
+
+**Upload (multipart):** the response body is the **processed image**, not JSON. The on-disk **output cache is not used** for uploads (each request uses temporary files).
 
 ```bash
 curl -s http://127.0.0.1:8080/health
+curl -s -o thumb.jpg -X POST http://127.0.0.1:8080/v1/resize \
+  -F "file=@/path/in.png" \
+  -F "max_width=400" \
+  -F "quality=85"
+```
+
+**Paths (JSON):** same resize options as the CLI, with `input` and `output` paths (must be readable/writable by the server process).
+
+```bash
 curl -s -X POST http://127.0.0.1:8080/v1/resize \
   -H 'Content-Type: application/json' \
   -d '{"input":"/path/in.png","output":"/path/out.webp","max_width":400,"quality":80}'
 ```
 
-Optional: `"cache":false`, `"expand_glob":false`, `"cache_dir":"..."` — see **Batch paths & cache** above.
+Optional JSON: `"cache":false`, `"expand_glob":false`, `"cache_dir":"..."` — see **Batch paths & cache** above.
 
 ### `ipc` — one JSON line per connection (TCP; Unix socket on Linux/macOS)
 
@@ -321,24 +335,26 @@ pm-image ipc --host 127.0.0.1 -p 9333 --cache-dir ./cache/images
 
 Same JSON fields as REST (`input`, `output`, globs, `expand_glob`, `cache`, `cache_dir`, resize options).
 
-### `kbot` — forward to another binary (optional)
-
-Requires **`KBOT_EXE`** pointing at the kbot executable; remaining args are passed through.
-
-```bash
-export KBOT_EXE=/path/to/kbot    # Windows: set KBOT_EXE=C:\path\to\kbot.exe
-pm-image kbot ai --prompt "hello"
-```
-
 ## Tests
 
+From `packages/media/cpp`, after **`cmake --build --preset release`** (or `npm run build:release`):
+
 ```bash
-npm run test:media
+npm run test:media                  # full suite
+npm run test:media:rest             # REST only (JSON + multipart)
+npm run test:media:multipart        # multipart upload → image body only
+npm run test:media:templates        # `${SRC_*}` REST + IPC + CLI
+npm run test:media:glob             # recursive glob + templates (PNG under glob-in/)
+npm run test:media:glob:raw         # same for tests/assets/raw/**/*.arw (skips if none)
+npm run test:media:ipc              # IPC only
+npm run test:media:url              # HTTP(S) URL inputs — needs network
 ```
 
-Requires a built `dist/pm-image` **linked against libvips** and fixture PNGs (`npm run generate:assets` if missing).
+Requires a built **`dist/pm-image`** linked against **libvips** and fixture PNGs (`npm run generate:assets` if missing).
 
-The suite covers **REST**, **IPC (TCP)**, optional **Unix socket** on non-Windows, **destination templates** (`npm run test:media:templates`), and **recursive glob + `${SRC_DIR}` / `${SRC_NAME}`** (`npm run test:media:glob` — outputs under `tests/assets/glob-in/**/out/`, gitignored, for manual inspection).
+Each run overwrites **`tests/test-report-last.md`** with Markdown from **`orchestrator/reports.js`**: **host** (CPU, RAM, load), **Node process** (CPU/memory deltas, RSS), timing, plus **image rows** (fixture and response **byte sizes**, PNG **pixel dimensions** when known, and multipart/JSON **output file** sizes).
+
+The suite covers **REST** (JSON paths and **multipart upload**), **IPC (TCP)**, optional **Unix socket** on non-Windows, **destination templates**, and **recursive glob + `${SRC_DIR}` / `${SRC_NAME}`** (`test:media:glob` — outputs under `tests/assets/glob-in/**/out/`, gitignored, for manual inspection). **`test:media:glob:raw`** runs the same glob flow against user-supplied **`.arw`** files under `tests/assets/raw/` (skipped when the folder is missing or has no ARW files).
 
 **HTTP URL smoke tests** (downloads from **picsum.photos**, needs network):