Initial commit: MIT-licensed compositor architecture & build plan (14 files, ~80 pages, 10 parallel research agents)
This commit is contained in:
commit
582e61e942
15 files changed
+4970
No files matched your search
+392
@@ -0,0 +1,392 @@
|
||||
# 11 — Pitfalls, GPL Contaminants, Clean-Room Requirements
|
||||
|
||||
This is the prominent pitfalls chapter for the MIT approach. It documents:
|
||||
|
||||
1. **3 GPL contaminants found** (must be replaced)
|
||||
2. **Clean-room legal requirements** (cannot read AGPL source and reimplement)
|
||||
3. **Engineering pitfalls of building from scratch**
|
||||
4. **Risk analysis**
|
||||
|
||||
## Critical finding: 3 GPL contaminants
|
||||
|
||||
The user's #1 priority is **license purity** — no GPL/AGPL contamination of
|
||||
the shipping product. The license audit (Agent T) found **3 GPL
|
||||
contaminants** that MUST be replaced:
|
||||
|
||||
### Contaminant 1: `@gfld/compositor-ffmpeg-h264` is GPL-3.0, not Apache-2.0
|
||||
|
||||
**What Greenfield claims**: `package.json` declares `"license":
|
||||
"Apache-2.0"`.
|
||||
|
||||
**What the LICENSE file actually says**: Full GPL v3 text.
|
||||
|
||||
**Why this happened**: The TypeScript wrapper (`H264Decoder.ts`,
|
||||
`H264Worker.ts`, `index.ts`) is genuinely Apache-2.0. But the
|
||||
`build_wasm.sh` script compiles FFmpeg with `--enable-gpl
|
||||
--enable-version3 --enable-nonfree`, which makes the resulting WASM
|
||||
binary GPL-3.0. The 1.8 MB compiled `libav-h264.js` contains embedded
|
||||
GPL/LGPL license strings.
|
||||
|
||||
**Impact on the user**: Using `@gfld/compositor-ffmpeg-h264` would force
|
||||
the entire Odoo fork to be GPL-3.0.
|
||||
|
||||
**Replacement**: WebCodecs `VideoDecoder` API (browser-native,
|
||||
hardware-accelerated, W3C standard). Fallback: OpenH264 BSD Wasm (NOT
|
||||
FFmpeg).
|
||||
|
||||
### Contaminant 2: `gstreamer1.0-plugins-ugly` (provides `x264enc`) is GPL-2.0+
|
||||
|
||||
**What it provides**: The `x264enc` GStreamer element, which is the
|
||||
software H.264 encoder Greenfield uses by default.
|
||||
|
||||
**Why it's GPL**: `libx264.so.164` is GPL-2.0+. The plugin that wraps it
|
||||
(`gst-plugins-ugly`) inherits the GPL. Loading this plugin into the
|
||||
Python process = GPL contamination under FSF's strict interpretation.
|
||||
|
||||
**Verified**: `ldd libgstx264.so` → links `libx264.so.164` (GPL-2.0+).
|
||||
x264 has NO dynamic-linking exception.
|
||||
|
||||
**Impact**: Using `x264enc` would force the entire Python proxy to be
|
||||
GPL-2.0+.
|
||||
|
||||
**Replacement**: Use `vaapih264enc` (Intel/AMD, LGPL plugin + MIT libva),
|
||||
`nvh264enc` (NVIDIA, BSD plugin + proprietary NVENC blob), or
|
||||
`openh264enc` (CPU fallback, BSD libopenh264).
|
||||
|
||||
### Contaminant 3: `gstreamer1.0-libav` on Debian is GPL (HIDDEN TRAP)
|
||||
|
||||
**What it provides**: The `gst-libav` plugin set, which wraps FFmpeg's
|
||||
libavcodec for various codecs.
|
||||
|
||||
**Why it's a trap**: The gst-libav plugin SOURCE CODE is LGPL-2.1+.
|
||||
**BUT** Debian's `libavcodec.so.61` is built with `--enable-gpl` and
|
||||
directly links `libx264.so.164` + `libx265.so.215`.
|
||||
|
||||
**Verified**: `ldd libgstlibav.so` → `libavcodec.so.61` → `libx264.so.164`
|
||||
+ `libx265.so.215`.
|
||||
|
||||
**Impact**: Even if the user might never use `avenc_h264`, the mere
|
||||
presence of `libgstlibav.so` triggers GStreamer's plugin auto-discovery,
|
||||
which dlopens it, which loads the GPL'd FFmpeg into the Python process's
|
||||
address space.
|
||||
|
||||
**Replacement**: Don't install `gstreamer1.0-libav`. Use only
|
||||
`gst-plugins-base` + `gst-plugins-good` + `gst-vaapi` + BSD subset of
|
||||
`gst-plugins-bad`.
|
||||
|
||||
## Clean-room legal requirements (CRITICAL)
|
||||
|
||||
### The problem
|
||||
|
||||
**You CANNOT read Greenfield's AGPL `@gfld/compositor` source and
|
||||
reimplement it as "inspired-by" code.** Even non-literal similarity is
|
||||
sufficient to find derivative-work infringement.
|
||||
|
||||
### Reasons
|
||||
|
||||
1. **AFC test risk**: Under *Computer Associates v. Altai*'s
|
||||
Abstraction-Filtration-Comparison test, even non-literal similarity
|
||||
(same class names, method names, code structure) is sufficient to
|
||||
find derivative-work infringement. A single developer who reads AGPL
|
||||
source then writes a TS replacement will almost certainly reproduce
|
||||
the SSO (structure, sequence, organization) subconsciously.
|
||||
|
||||
2. **AGPL §13 network-use clause**: This is the killer for an Odoo fork.
|
||||
AGPL-3.0 §13 requires offering the source of any modified AGPL work
|
||||
to all users interacting with it over a network. If a court finds the
|
||||
custom compositor is an AGPL derivative, the entire Odoo fork (which
|
||||
links to the compositor) must be open-sourced to all users —
|
||||
destroying the proprietary value.
|
||||
|
||||
3. **Westfield doesn't help**: Greenfield's predecessor repo at
|
||||
https://github.com/udevbe/westfield IS MIT-licensed, but it contains
|
||||
ONLY the protocol infrastructure (the same `@gfld/common` +
|
||||
`@gfld/compositor-protocol` + `@gfld/compositor-wasm` we already have).
|
||||
It NEVER had the in-browser compositor logic (Surface/Renderer/Seat/etc.).
|
||||
The compositor code was always in the Greenfield monorepo, always AGPL.
|
||||
|
||||
### Right approach: True clean-room
|
||||
|
||||
1. **Person A** (spec author, MAY read AGPL source) writes a behavioral
|
||||
spec (inputs/outputs/edge cases, NO code).
|
||||
2. **Person B** (implementer, MUST NOT open `packages/compositor/src/`)
|
||||
implements from spec + MIT references only:
|
||||
- Wayland protocol spec (https://wayland.freedesktop.org/docs/html/)
|
||||
- wlroots C source (MIT, https://gitlab.freedesktop.org/wlroots/wlroots)
|
||||
- Weston C source (MIT, https://gitlab.freedesktop.org/wayland/weston)
|
||||
- Smithay Rust source (MIT, https://github.com/Smithay/smithay)
|
||||
- WebGL2/WebCodecs/KCP MDN docs
|
||||
|
||||
### Legal-defensibility artifacts
|
||||
|
||||
Maintain these as legal-defensibility artifacts:
|
||||
|
||||
- `SPEC.md` — the behavioral spec (written by Person A)
|
||||
- `CLEAN_ROOM_LOG.md` — who read AGPL, who didn't, when, what they referenced
|
||||
|
||||
### What can Person B reference?
|
||||
|
||||
| Reference | License | OK to read for implementation? |
|
||||
|---|---|---|
|
||||
| Greenfield's `packages/compositor/src/` | AGPL-3.0 | ❌ NO (Person B forbidden) |
|
||||
| Greenfield's `libs/` (MIT) | MIT | ✅ Yes (already reused) |
|
||||
| Greenfield's `protocol/` XML | MIT | ✅ Yes |
|
||||
| Greenfield's `docs/` | MIT | ✅ Yes |
|
||||
| Wayland protocol spec | MIT | ✅ Yes |
|
||||
| wlroots C source | MIT | ✅ Yes |
|
||||
| Weston C source | MIT | ✅ Yes |
|
||||
| Smithay Rust source | MIT | ✅ Yes |
|
||||
| MDN docs (WebGL2, WebCodecs, etc.) | CC-BY-SA | ✅ Yes |
|
||||
| pywayland source | Apache-2.0 | ✅ Yes |
|
||||
| qtile source | GPL-2.0 | ❌ NO (architectural patterns OK, code not) |
|
||||
|
||||
## License audit table (full stack)
|
||||
|
||||
### Browser side
|
||||
|
||||
| Component | License | Compatible with proprietary? |
|
||||
|---|---|---|
|
||||
| @gfld/common | MIT | ✅ |
|
||||
| @gfld/client-protocol | MIT | ✅ |
|
||||
| @gfld/compositor-protocol | MIT | ✅ (verified NO @gfld/compositor import) |
|
||||
| @gfld/client-generator | MIT | ✅ |
|
||||
| @gfld/compositor-generator | MIT | ✅ |
|
||||
| @gfld/compositor-wasm (pixman+xkbcommon) | MIT | ✅ |
|
||||
| @gfld/xtsb (X11 bindings, optional) | MIT | ✅ (only if XWayland needed) |
|
||||
| ~~@gfld/compositor-ffmpeg-h264~~ | ~~GPL-3.0~~ | ❌ **REPLACE with WebCodecs** |
|
||||
| Custom browser compositor (your code) | PROPRIETARY | ✅ (clean-room) |
|
||||
| WebCodecs API | W3C standard | ✅ |
|
||||
| WebGL2 | W3C standard | ✅ |
|
||||
| OffscreenCanvas | W3C standard | ✅ |
|
||||
| OpenH264 BSD Wasm (fallback) | BSD-2-Clause | ✅ |
|
||||
|
||||
### Python backend
|
||||
|
||||
| Component | License | Compatible with proprietary? |
|
||||
|---|---|---|
|
||||
| pywayland | Apache-2.0 | ✅ |
|
||||
| python-xkbcommon (`xkbcommon` PyPI) | MIT | ✅ |
|
||||
| PyGObject (gi.repository.Gst) | LGPL-2.1+ | ✅ (dynamic linking) |
|
||||
| GLib | LGPL-2.1+ | ✅ (dynamic linking) |
|
||||
| GStreamer core | LGPL-2.0+ | ✅ (dynamic linking) |
|
||||
| gst-plugins-base | LGPL | ✅ |
|
||||
| gst-plugins-good (pngenc) | LGPL | ✅ |
|
||||
| gst-vaapi (vaapih264enc) | LGPL + MIT (libva) | ✅ |
|
||||
| gst-plugins-bad (nvh264enc, openh264enc) | BSD subset | ✅ |
|
||||
| ~~gst-plugins-ugly (x264enc)~~ | ~~GPL-2.0+~~ | ❌ **DROP** |
|
||||
| ~~gst-libav (libavcodec)~~ | ~~LGPL source, GPL binary on Debian~~ | ❌ **DROP** |
|
||||
| libwayland | MIT | ✅ |
|
||||
| libdrm | MIT | ✅ |
|
||||
| mesa (libGL, libEGL, libgbm) | MIT | ✅ |
|
||||
| aiohttp | Apache-2.0 | ✅ |
|
||||
| kcp (PyPI, RealistikDash) | MIT | ✅ |
|
||||
| PyJWT | MIT | ✅ |
|
||||
| bubblewrap (bwrap) | LGPL-2.0+ | ✅ (dynamic linking) |
|
||||
| libseccomp | LGPL-2.1 | ✅ |
|
||||
|
||||
### Odoo integration
|
||||
|
||||
| Component | License | Compatible? |
|
||||
|---|---|---|
|
||||
| Odoo 20 Community | LGPL-3.0 | ✅ (separate process, no contamination) |
|
||||
| Nginx | BSD-2-Clause | ✅ |
|
||||
| Docker | Apache-2.0 | ✅ |
|
||||
|
||||
### Vendored Greenfield C files (MIT, reused verbatim)
|
||||
|
||||
| File | License | Reuse? |
|
||||
|---|---|---|
|
||||
| westfield-buffer.c | MIT (Greenfield) | ✅ |
|
||||
| westfield-dmabuf.c | MIT (Greenfield) | ✅ |
|
||||
| westfield-egl.c | MIT (Greenfield) | ✅ |
|
||||
| westfield-xwayland.c | MIT (Greenfield) | ✅ |
|
||||
| wlr_drm.c | MIT (vendored from wlroots) | ✅ |
|
||||
| wlr_linux_dmabuf_v1.c | MIT (vendored from wlroots) | ✅ |
|
||||
| drm_format_set.c | MIT (vendored from wlroots) | ✅ |
|
||||
| addon.c | MIT (vendored from wlroots) | ✅ |
|
||||
| changes.diff | MIT (Greenfield patches to libwayland) | ✅ (optional, for fast-sync) |
|
||||
|
||||
## CI/CD license hygiene gates (recommended)
|
||||
|
||||
Add these to your CI pipeline to catch GPL contamination early:
|
||||
|
||||
### Docker image audit
|
||||
|
||||
```bash
|
||||
# Must return zero matches
|
||||
dpkg -l | grep -E "libx264|libx265|gstreamer1.0-plugins-ugly|gstreamer1.0-libav"
|
||||
```
|
||||
|
||||
### npm license check
|
||||
|
||||
```bash
|
||||
# Must pass (no GPL/AGPL)
|
||||
npx license-checker --production --failOn "GPL-3.0;AGPL-3.0;GPL-2.0;GPL-2.0+;GPL-3.0+"
|
||||
```
|
||||
|
||||
### Python license check
|
||||
|
||||
```bash
|
||||
# Must pass (no GPL/AGPL)
|
||||
pip-licenses --fail-on "GPL.*;AGPL.*" --ignore-builtin
|
||||
```
|
||||
|
||||
### Runtime GStreamer plugin check
|
||||
|
||||
```bash
|
||||
# Must return zero matches
|
||||
gst-inspect-1.0 --print-plugin-auto-install-info | grep -E "x264|x265|libav"
|
||||
```
|
||||
|
||||
## Engineering pitfalls (beyond licensing)
|
||||
|
||||
### 1. Browser compositor is the biggest effort
|
||||
|
||||
The custom browser compositor is ~13,400 LOC TypeScript for MVP, ~25
|
||||
dev-weeks (1 senior dev). This is the critical path.
|
||||
|
||||
**Mitigation**: Hire 2 senior engineers to parallelize. Use Smithay (Rust,
|
||||
MIT) as a reference for Wayland semantics. Use wlroots (C, MIT) as a
|
||||
reference for compositor patterns.
|
||||
|
||||
### 2. xdg-shell state machine is the highest-risk component
|
||||
|
||||
The configure/ack-configure round-trip, popup positioner math, and
|
||||
subsurface sync/desync cascades are subtle. Bugs here can cause apps to
|
||||
hang or crash.
|
||||
|
||||
**Mitigation**: Write extensive unit tests using Weston's test clients
|
||||
(ported to TypeScript). Test with real GTK4/Qt6 apps early and often.
|
||||
|
||||
### 3. asyncio + libwayland integration is under-documented
|
||||
|
||||
The 5-line cffi shim for `wl_event_loop_get_fd` is verified working, but
|
||||
the pattern is not widely documented. Bugs here could cause Wayland
|
||||
events to be dropped or duplicated.
|
||||
|
||||
**Mitigation**: Spend 1 day on a standalone prototype before committing.
|
||||
Reference qtile's Wayland backend (architectural patterns OK, code is
|
||||
GPL — don't copy).
|
||||
|
||||
### 4. GStreamer threading is non-trivial
|
||||
|
||||
GLib MainLoop runs in a separate thread; results must be marshalled back
|
||||
to asyncio via `asyncio.run_coroutine_threadsafe`. Bugs here can cause
|
||||
race conditions or deadlocks.
|
||||
|
||||
**Mitigation**: Reuse Greenfield's MIT C files via cffi — only the
|
||||
marshalling needs Python. Test with high-frame-rate content (e.g. glxgears).
|
||||
|
||||
### 5. XWayland is a major time sink (~8 weeks)
|
||||
|
||||
If you need X11 app support (e.g. older apps that don't speak Wayland
|
||||
natively), the XWayland bridge is ~5,000 LOC TypeScript + ~465 LOC C.
|
||||
It uses `@gfld/xtsb` (MIT, REUSED) for X11 protocol bindings.
|
||||
|
||||
**Mitigation**: Skip XWayland in MVP. Most modern GTK4/Qt6 apps are
|
||||
Wayland-native. Add XWayland only if a specific X11-only app is needed.
|
||||
|
||||
### 6. KCP Python port may have performance issues
|
||||
|
||||
The `kcp` PyPI package (RealistikDash, MIT) is a Cython wrapper over
|
||||
upstream `ikcp.c`. Performance should be adequate, but if it's not,
|
||||
porting Greenfield's TypeScript KCP (~1100 lines) to Python would be
|
||||
~1500 lines of pure Python (slower).
|
||||
|
||||
**Mitigation**: Benchmark early. If Cython wrapper is too slow, write a
|
||||
C extension via cffi.
|
||||
|
||||
### 7. WebGL2 + OffscreenCanvas + Workers is complex
|
||||
|
||||
Multi-threaded rendering with OffscreenCanvas requires careful message
|
||||
passing between workers. Debugging is harder than main-thread code.
|
||||
|
||||
**Mitigation**: Start with main-thread WebGL2 (simpler), then move to
|
||||
OffscreenCanvas in Phase 5 (polish).
|
||||
|
||||
### 8. WebCodecs hardware decode may have bugs
|
||||
|
||||
Greenfield explicitly disables hardware decode with `// FIXME hardware
|
||||
decoding frame offset is wrong`. We're enabling it (`prefer-hardware`),
|
||||
but the bug Greenfield hit may still affect us.
|
||||
|
||||
**Mitigation**: Test extensively on Intel/AMD/NVIDIA GPUs. Fall back to
|
||||
`prefer-software` if hardware decode is broken on specific hardware.
|
||||
|
||||
### 9. Bubblewrap + seccomp may break some apps
|
||||
|
||||
Some GTK apps may need additional filesystem access (e.g. ~/.config for
|
||||
settings, ~/.cache for thumbnails). The default-deny approach may break
|
||||
them.
|
||||
|
||||
**Mitigation**: Test with the apps you want to support. Add per-app
|
||||
overrides in `compositor.app` model (e.g. extra filesystem binds).
|
||||
|
||||
### 10. JWT secret rotation
|
||||
|
||||
The JWT secret is shared between Odoo and the compositor proxy via env
|
||||
var. If the secret leaks, attackers can forge JWTs and run apps on
|
||||
behalf of any user.
|
||||
|
||||
**Mitigation**: Rotate the secret periodically (e.g. monthly). Use a
|
||||
secrets manager (Vault, AWS Secrets Manager). Log all JWT validations.
|
||||
|
||||
## Risk analysis summary
|
||||
|
||||
| Risk | Likelihood | Impact | Mitigation |
|
||||
|---|---|---|---|
|
||||
| GPL contamination in shipping product | Medium (3 contaminants found) | **CRITICAL** (forces open-source) | 3 substitutions + CI/CD license gates |
|
||||
| AGPL derivative-work lawsuit | Low (clean-room approach) | **CRITICAL** (forces open-source) | True clean-room with SPEC.md + CLEAN_ROOM_LOG.md |
|
||||
| Browser compositor takes >6 months | Medium | High (delays MVP) | 2 senior engineers in parallel |
|
||||
| xdg-shell state machine bugs | High | Medium (app crashes) | Extensive testing with Weston test clients |
|
||||
| asyncio + libwayland integration bugs | Medium | High (events dropped) | 1-day prototype before committing |
|
||||
| GStreamer threading deadlocks | Medium | Medium (encoder stalls) | Reuse Greenfield's MIT C files via cffi |
|
||||
| XWayland scope creep | High | High (+8 weeks) | Skip XWayland in MVP |
|
||||
| KCP Python performance | Low | Medium (latency) | Benchmark early, fall back to cffi C extension |
|
||||
| WebGL2 + Workers complexity | Medium | Medium (debugging pain) | Start with main-thread, move to Workers in Phase 5 |
|
||||
| WebCodecs hardware decode bugs | Medium | Medium (CPU usage) | Test on Intel/AMD/NVIDIA, fall back to software |
|
||||
| Bubblewrap breaks apps | Medium | Low (per-app overrides) | Test with target apps, add per-app overrides |
|
||||
| JWT secret leak | Low | **CRITICAL** (auth bypass) | Rotate periodically, use secrets manager |
|
||||
|
||||
## Design wins to copy from Greenfield
|
||||
|
||||
These Greenfield design choices are worth copying in the MIT approach
|
||||
(but implemented clean-room):
|
||||
|
||||
1. **Generator-driven protocol stubs** — single XML source for both
|
||||
sides. REUSED from Greenfield's MIT libs.
|
||||
2. **Dual-buffer commit semantics** — Surface state vs pendingState,
|
||||
atomic merge. Clean-room from spec.
|
||||
3. **UserShellApi decoupling** — shell sees only `{events, actions}`,
|
||||
never Wayland resources. Clean-room from spec.
|
||||
4. **Asynchronous browser compositor** — per-client channels, never
|
||||
blocks on a slow client. Clean-room from spec.
|
||||
5. **KCP-over-WebSocket** for UDP-like latency over TCP. Use `kcp` PyPI
|
||||
package (MIT).
|
||||
6. **WebCodecs primary + fallback** — capability probe at session
|
||||
startup. Clean-room, but enable hardware decode (Greenfield doesn't).
|
||||
7. **Zero-copy dmabuf → encoder** via `linux-dmabuf-unstable-v1`.
|
||||
REUSED vendored Greenfield C files (MIT).
|
||||
8. **Per-surface encoder feedback channel** — Greenfield produces it
|
||||
but doesn't use it. **Our MIT approach consumes it for adaptive
|
||||
bitrate** (NEW).
|
||||
9. **`ReconnectingWebSocket`** with exponential backoff. Vendored from
|
||||
pladaria (MIT).
|
||||
10. **Honest docs** — Greenfield's `docs/pages/design/` openly admits
|
||||
what's wrong. Use as reference for trade-off analysis.
|
||||
|
||||
## Top-5 recommendations
|
||||
|
||||
1. **Replace the 3 GPL contaminants IMMEDIATELY**: WebCodecs (not FFmpeg
|
||||
Wasm), vaapih264enc/nvh264enc/openh264enc (not x264enc), don't install
|
||||
gst-libav.
|
||||
2. **Adopt true clean-room discipline** for the browser compositor. One
|
||||
spec author (may read AGPL), one implementer (must NOT). Maintain
|
||||
`SPEC.md` + `CLEAN_ROOM_LOG.md` as legal-defensibility artifacts.
|
||||
3. **Skip XWayland in MVP** — add 8 weeks only if legacy X11 apps are
|
||||
required.
|
||||
4. **Use the kcp PyPI package** — don't port Greenfield's TS KCP to
|
||||
Python (would be slower).
|
||||
5. **Add CI/CD license hygiene gates** — Docker image audit, npm
|
||||
license-checker, pip-licenses, gst-inspect check. Catch GPL
|
||||
contamination early.
|
||||
Reference in new issue
Block a user