Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions .dockerignore
Original file line number Diff line number Diff line change
@@ -1,5 +1,11 @@
/woom
/target
/dist
/static/dist
/data
/.git
/test-results
/playwright-report
.idea
.vscode
node_modules
1 change: 1 addition & 0 deletions .gitattributes
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
* text=auto eol=lf
30 changes: 18 additions & 12 deletions .github/workflows/build.yml
Original file line number Diff line number Diff line change
@@ -1,28 +1,34 @@
name: Build

on: [push, pull_request]
on:
push:
branches-ignore:
- main
pull_request: {}
workflow_call: {}

permissions:
contents: read

jobs:
deploy:
build:
strategy:
matrix:
os: [macos-latest, ubuntu-latest, windows-latest]
name: Deploy proxy
name: Build (${{ matrix.os }})
runs-on: ${{ matrix.os }}
steps:
- name: Checkout
uses: actions/checkout@v4
- uses: actions/setup-node@v4
uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: latest
node-version: 26
cache: npm
- name: Install npm dependencies
run: npm ci
- name: Build WebApp
run: npm run build
- name: Install golang
uses: actions/setup-go@v5
with:
go-version: '1.21'
- name: Install Rust
uses: dtolnay/rust-toolchain@stable
- name: Build Woom
run: go build -tags release -trimpath

run: cargo build --release --locked
17 changes: 13 additions & 4 deletions .github/workflows/flyio.yml
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,26 @@ on:
branches:
- main

permissions:
contents: read

jobs:
build:
uses: ./.github/workflows/build.yml

test:
uses: ./.github/workflows/test.yml

deploy:
name: Deploy proxy
name: Deploy to Fly
needs: [build, test]
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v4
uses: actions/checkout@v7
- name: Set flyctl
uses: superfly/flyctl-actions/setup-flyctl@master
uses: superfly/flyctl-actions/setup-flyctl@98172f70657cb3e15db199af139be99bd3e61200
- name: Deploy to fly.io
run: flyctl deploy --remote-only
env:
FLY_API_TOKEN: ${{ secrets.FLY_API_TOKEN }}

95 changes: 95 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,95 @@
name: Test

on:
push:
branches-ignore:
- main
pull_request: {}
workflow_call: {}

permissions:
contents: read

jobs:
rust:
name: Rust quality
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 26
cache: npm
- name: Build embedded WebApp and audit production dependencies
run: npm ci && npm run build && npm audit --omit=dev
- name: Install Rust
uses: dtolnay/rust-toolchain@stable
with:
components: rustfmt, clippy
- name: Check format, lints and tests
run: npm run test:rust

e2e:
name: Playwright e2e
runs-on: ubuntu-latest
services:
live777:
image: ghcr.io/binbat/liveion:0.10.2
ports:
- 7777:7777
steps:
- name: Checkout
uses: actions/checkout@v7
- uses: actions/setup-node@v7
with:
node-version: 26
cache: npm
- name: Install npm dependencies
run: npm ci
- name: Install Playwright Chromium
run: npx playwright install --with-deps chromium
- name: Install Rust
uses: dtolnay/rust-toolchain@stable
- name: Run e2e tests
run: npm run test:e2e
- name: Upload Playwright report
if: ${{ !cancelled() }}
uses: actions/upload-artifact@v7
with:
name: playwright-report
path: playwright-report/
retention-days: 7

docker:
name: Docker smoke
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v7
- name: Build image
run: docker build -t woom:ci .
- name: Start container
run: |
docker run -d --name woom-ci \
-p 4000:4000 \
-v woom-ci-data:/data \
-e SECRET=ci-9f6c2a84d17b43e0a5c98f21e6d04b7a \
woom:ci
for attempt in $(seq 1 30); do
if curl -fsS http://localhost:4000/ >/dev/null; then
exit 0
fi
sleep 1
done
docker logs woom-ci
exit 1
- name: Check SPA and missing asset responses
run: |
curl -fsS -H 'Accept: text/html' http://localhost:4000/meeting/example >/dev/null
test "$(curl -sS -o /dev/null -w '%{http_code}' -H 'Accept: application/javascript' http://localhost:4000/assets/missing.js)" = 404
- name: Clean up
if: ${{ !cancelled() }}
run: |
docker rm -f woom-ci
docker volume rm woom-ci-data
6 changes: 6 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
@@ -1,8 +1,14 @@
woom
/target
/data/
.idea
.vscode
node_modules
.DS_Store
dist
dist-ssr
*.local
/test-results/
/playwright-report/
/blob-report/
/playwright/.cache/
115 changes: 115 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,115 @@
# AGENTS.md

Guidance for AI agents working on this repository.

## Project overview

WOOM is a self-hosted meeting service built on the
[Live777](https://github.com/binbat/live777) WebRTC engine (WHIP/WHEP).

- `src/` — Rust backend (axum). Serves the REST API (`/user/`, `/room/*`),
reverse-proxies `/whip/*`, `/whep/*` and their `/session/*` resources to
Live777, pushes room state over SSE (`/room/{id}/events`), and serves the
WebApp. Media and room APIs require current active-participant
authorization. SSE uses short-lived tickets from
`POST /room/{id}/events/ticket`; `snapshot` and `message` events carry a
per-room monotonically increasing `revision`.
- `src/store.rs` — Atomic domain commands and a single-process durable JSON
store. Rooms, meeting instances, participants, chat and archived records
are persisted with clone-on-write and atomic file replacement. Presence is
ephemeral with a 45s TTL; participant offline reclamation uses a separate
24h TTL. `DATA_FILE=:memory:` is available for tests. Do not run multiple
processes against one JSON file.
- `src/config.rs` — Environment configuration. `SECRET` is required and must
contain at least 32 bytes. Other variables: `PORT` 4000, `LIVE777_URL`,
`LIVE777_TOKEN`, `DATA_FILE` (default `./data/woom.json`), and optional
`LOG_READ_TOKEN` for admin-only diagnostic export. Never log secrets, JWTs,
SSE ticket query strings or room passwords.
- `src/events.rs` — Per-room broadcast channels. Subscribe before taking the
initial snapshot, deduplicate by revision, and recover from lag with a full
snapshot. All state-changing API operations publish in commit order.
- Browser failures go to `POST /log` and are written as NDJSON on the
`client_log` tracing target. Intake is intentionally anonymous but bounded
and redacts sensitive fields. `GET /log` requires `LOG_READ_TOKEN` and exports
the most recent 5000 in-memory entries as NDJSON with meeting/session filters
for AI-assisted diagnosis. The buffer is cleared on restart.
- `webapp/` — Vue 3 + TypeScript + Vite + UnoCSS frontend (`<script setup>`
SFCs). State uses module-level `ref`/`shallowRef` (`webapp/store/atoms.ts`),
persisted settings (`webapp/store/setting.ts`), and localStorage for
user/token (`webapp/lib/storage.ts`). Join passwords remain in memory only.
Welcome/Meeting views are switched by `meetingId` in `webapp/app.vue`.
- WHIP/WHEP clients are framework-agnostic classes exposed through
composables. Asynchronous start/stop/restart operations use generations so
stale sessions cannot update current state. Both publishing and subscribing
send the user bearer token; `/session/*` remains on the WOOM proxy.
- PWA: `webapp/public/sw.js` is a build-time template. Vite generates a
content-versioned precache containing the app shell. Navigations are
network-first; API/SSE/media signaling bypass the cache. Missing static
assets return 404 rather than the SPA HTML fallback.
- `static/` — WebApp build output embedded into the Rust binary via rust-embed
(`src/spa.rs`). `static/dist` is produced by `npm run build` and must exist
before compiling.
- `tests/` — Playwright E2E tests, see below.

## Build and run

External dependency: Live777/Liveion on port 7777.

```bash
docker compose up -d
npm ci
export SECRET="$(openssl rand -hex 32)"
npm run build # required before the first backend compile
cargo run # backend + production WebApp on :4000
npm run dev # optional Vite development server on :5173

make # WebApp -> static/dist, then cargo build --release --locked
./target/release/woom
```

Keep `SECRET` stable across restarts. Docker uses `/data/woom.json` and expects
a persistent `/data` volume. See README for Live777 networking and upgrades.

## Testing

- Rust format, Clippy and tests: `npm run test:rust`
- E2E (Playwright, Chromium only):

```bash
docker compose up -d
npx playwright install chromium
npm run test:e2e
E2E_REUSE_SERVER=true npx playwright test # explicit opt-in to an existing server
```

E2E conventions:

- Tests cover core flows and regression paths and must stay green across
refactors; update specs when behavior intentionally changes.
- Locate elements by `data-testid` only (never text/CSS classes). Add
`data-testid` to new interactive elements.
- Browsers use fake media devices. Assert playback with
`expectVideoPlaying()` in `tests/helper.ts`, which checks dimensions and
advancing playback/decoded frames rather than element presence.
- Remote stream state and WebRTC recovery are asynchronous; use generous
timeouts without replacing assertions with fixed sleeps.
- `tests/global-setup.ts` fails fast if Live777 is unreachable.
- Playwright uses an explicit test-only `SECRET` and `DATA_FILE=:memory:`.
It does not reuse an existing server unless `E2E_REUSE_SERVER=true`.

## Code style

- Biome 2.6.4 handles formatting, general TS/JS checks and import organization
(`biome.json`, same major tool version as Live777). ESLint 10 retains Vue
essential and TypeScript semantic rules; `vue-tsc --noEmit` checks WebApp,
Playwright and config types. Style: no semicolons, single quotes, 2-space
indent, trailing commas only when multiline. Use `npm run format` for safe
fixes and `npm run lint` for all checks; lint is part of `npm run build`.
- Rust must pass `cargo fmt --check` and
`cargo clippy --all-targets -- -D warnings`.
- Commits: Conventional Commits with scope, for example `feat(webapp): ...`,
`fix(server): ...`, `test(e2e): ...`.
- CI: `.github/workflows/build.yml` (three-OS build),
`.github/workflows/test.yml` (Rust quality, E2E, Docker smoke), and
`.github/workflows/flyio.yml` (deploy only after reusable Build and Test
workflows succeed).
Loading
Loading