# Media image service (C++) — rollout plan

## Goals

- **CLI**: resize files on disk (batch-friendly, scripts).
- **REST**: HTTP server for resize jobs (Node or other clients).
- **IPC**: async socket server — **Unix domain socket** on Linux/macOS; **TCP loopback** on Windows (Asio does not ship portable UDS on Windows; optional **named pipe** phase later).

## Dependencies (CMake / FetchContent)

| Component | Choice | Notes |
|-----------|--------|--------|
| CLI | [CLI11](https://github.com/CLIUtils/CLI11) | Same pattern as `kbot/cpp`. |
| Async I/O | [Asio](https://think-async.com/Asio/) (standalone) | UDS + accept loop; no Boost linkage. |
| HTTP | [cpp-httplib](https://github.com/yhirose/cpp-httplib) | Header-only REST; good for a dedicated worker. |
| JSON | [nlohmann/json](https://github.com/nlohmann/json) | Request/response bodies. |
| Images (v1) | [stb](https://github.com/nothings/stb) | No system install; PNG/JPEG in-tree. |
| Images (later) | **libvips** | Optional `find_package` / vcpkg when you need parity with Sharp speed/quality. |

## Phases

### Phase 0 — Scaffold (this PR)

- CMake presets `dev` / `release`, output `dist/media-img(.exe)`.
- `npm run build:release` green on Windows MSVC.

### Phase 1 — Core + CLI

- `resize` command: input path, output path, max width/height, format (png/jpeg).
- Single-threaded; deterministic errors to stderr.

### Phase 2 — REST

- `serve --bind --port`: `GET /health`, `POST /v1/resize` (JSON with paths or raw body + query params — v1 uses file paths for simplicity).

### Phase 3 — IPC

- `ipc --listen <path|host:port>`: line-delimited or length-prefixed JSON requests (documented in `docs/ipc-protocol.md` stub).
- Linux: Unix socket. Windows: TCP `127.0.0.1:<port>` (or named pipe in a follow-up).

### Phase 4 — Production hardening

- Optional libvips backend behind `MEDIA_USE_VIPS`.
- Worker pool, request limits, metrics.
- CI: Linux + Windows matrix.

## npm scripts

- `npm run build:release` — configure + build Release.
- `npm run run` — `dist/media-img --help`.