# comfy_patches

Local patches that ride on top of vanilla ComfyUI (the `comfy_source/` git
submodule).

`overlay/` mirrors the ComfyUI tree — every file under it is copied
verbatim over the matching path inside `comfy_source/` by
`apply.sh`. Run that whenever you bump the submodule or after a fresh
clone with `--recurse-submodules`.

## Why an overlay instead of a fork

Pinning a fork would mean rebasing it every time we bump ComfyUI. An
overlay keeps the upstream submodule clean: the patches are visible in
git, easy to diff against vanilla, and trivial to drop once they're
upstreamed.

## Patch inventory

| File | Type | Notes |
|---|---|
| `comfy_api_nodes/util/_helpers.py` | BoosAPI integration | `get_auth_header` falls back to `BOOSAPI_BUILTIN_KEY`; `default_base_url()` reads `--comfy-api-base`. Required for the multi-tenant pool — the per-user containers authenticate to BoosAPI through this. |
| `app/frontend_management.py` + `server.py` + `openapi.yaml` | Feature | Adds `comfy_package_versions` to `/system_stats` so the admin UI can surface drift across `comfy*` packages. Candidate for upstreaming. |
| `comfy_extras/nodes_audio.py` | Hardening | Guards Save/Preview/Trim/Split nodes against `audio is None` (happens when source video has no audio track). Candidate for upstreaming. |
| `requirements.txt` | Bump | `comfyui-workflow-templates==0.9.77` (vanilla pins 0.9.75). |
| `tests-unit/app_test/frontend_manager_test.py` | Test | Covers the new `get_comfy_package_versions()` path. |
| `tests-unit/comfy_test/model_detection_test.py` | Test | Adjusted assertions for the audio-node guards. |
| `README.md`, `SECURITY.md` | Docs | Local edits. Not load-bearing. |

## Apply

```bash
./comfy_patches/apply.sh
```

Idempotent — safe to re-run. Aborts if `comfy_source/` is dirty (so you
don't silently clobber upstream work-in-progress).

## Upgrading vanilla ComfyUI

This is the SOP whenever you want to bump the `comfy_source/` submodule
to a newer upstream commit / tag.

```bash
cd /root/metapi

# 1. Pull the new upstream commit into the submodule.
#    Use --remote to follow the branch tracked in .gitmodules; pin to a
#    specific tag with `git -C comfy_source checkout <tag>` instead.
git submodule update --remote comfy_source

# 2. Re-apply the local overlay on top.
#    apply.sh aborts if comfy_source/ is dirty — commit or stash first.
./comfy_patches/apply.sh

# 3. Rebuild the multi-tenant image.
#    --no-run skips starting the boosapi binary; we only want the image.
./build-and-run.sh --no-run

# 4. Smoke-test the new image without touching the live pool.
docker run --rm -p 18188:8188 \
    -e BOOSAPI_BUILTIN_KEY=test \
    -e BOOSAPI_BASE=http://host.docker.internal:8787 \
    -e BOOSAPI_KEY=test \
    boosapi-comfyui:multi-tenant &
sleep 5
curl -s http://localhost:18188/system_stats | jq .comfy_package_versions
# Expect a JSON object with comfy / comfyui_frontend_package versions.
# Ctrl-C the container when done; --rm cleans it up.
```

### When upstream changes a file we patch

If `apply.sh` finds that vanilla has changed under one of the overlay
paths, it copies our overlay over anyway — vanilla's new content is
silently lost. To detect this before bumping:

```bash
# Diff our overlay against the new vanilla, file by file.
for f in $(cd comfy_patches/overlay && find . -type f); do
  diff -u "comfy_source/$f" "comfy_patches/overlay/$f" \
    | head -40
done
```

For each diff that shows upstream behaviour we want to keep (not just
formatting), edit `comfy_patches/overlay/<file>` to merge the
intent — then re-run `apply.sh`. The patch-inventory table above is
the canonical list of files to check.

### Backout

If the new upstream breaks something:

```bash
# Roll the submodule back to whatever commit was pinned in HEAD.
git submodule update comfy_source
./comfy_patches/apply.sh
./build-and-run.sh --no-run
```

The previous image is still in `docker images` (we don't auto-prune),
so you can also fall back to it via tag pin in production until the
upgrade is fixed.

### Restoring from the saved image

A known-good build of the image is exported at
`docker/boosapi-comfyui-multi-tenant-20260520.tar` (754 MiB). To
restore on this or any other host:

```bash
docker load -i docker/boosapi-comfyui-multi-tenant-20260520.tar
# → boosapi-comfyui:multi-tenant
```

Use this when a rebuild fails (network, dependency drift) and you need
the running pool back fast — load the tar, the per-user containers
will pick the image up on next launch.

## Runtime contract: ComfyUI calls our API, not the upstream's

The point of the `_helpers.py` overlay is to redirect every "call the
ComfyUI cloud" code path inside the per-user container to BoosAPI:

- `--comfy-api-base http://host.docker.internal:8787/v1` is forwarded
  by `docker/comfyui-entrypoint.sh` from the `BOOSAPI_BASE` env var.
- `BOOSAPI_BUILTIN_KEY` / `BOOSAPI_KEY` become the auth header that
  ComfyUI's API nodes send. BoosAPI verifies it, looks up the
  `token_routes` row for the requested model, picks a `route_channels`
  row, and forwards to the real upstream account.

So the per-user ComfyUI instances never talk to upstream platforms
directly — every API node call funnels through BoosAPI's routing
layer (the same path serving `/v1/chat/completions` for the rest of
the product).