diff --git a/.config/nextest.toml b/.config/nextest.toml index 1037b2310..128a76cf9 100644 --- a/.config/nextest.toml +++ b/.config/nextest.toml @@ -1,7 +1,6 @@ # cargo-nextest (https://nexte.st) runs every test in its own process, in parallel across test -# binaries. The Windows leg of the Workspace gate uses it (.github/workflows/workspace.yml); every -# other leg, and local runs, keep `cargo test`. Nextest does not run doctests, so the Windows leg -# also runs `cargo test --doc`. +# binaries. Every leg of the Workspace gate uses it (.github/workflows/workspace.yml); local runs may +# keep `cargo test`. Nextest does not run doctests, so the gate also runs `cargo test --doc`. # # cargo nextest run --workspace --profile ci # cargo test --workspace --doc @@ -22,10 +21,9 @@ video-fixtures = { max-threads = 1 } # craft-print: `PRINT_TICKET_PROVIDER` serializes the Windows PrintTicket provider, and the tests # share the one test print queue the gate installs. print = { max-threads = 1 } - -[[profile.default.overrides]] -filter = 'package(craft-ui) & (binary(visual_regression) | test(/^combo::tests::|selected_tab_erases_a_baseline_centered_on_its_bottom_edge/))' -test-group = 'gpu' +# craft-video integration tests on Linux and macOS: the binaries generate and read the same fixture +# directories (see the `ci` overrides below). +video-integration = { max-threads = 1 } [[profile.default.overrides]] filter = 'package(craft-video) & binary(h264_decode)' @@ -42,3 +40,17 @@ test-group = 'print' fail-fast = false slow-timeout = { period = "60s" } failure-output = "immediate-final" + +# Linux and macOS (the resource audit in craft-libs#2058): every GPU consumer shares the one `gpu` +# slot, and the craft-video integration binaries share their fixture directories. Conservative on +# purpose: the in-process mutexes these tests rely on do not reach across nextest's processes. +# Windows keeps the default groups above, which its leg has passed with since it moved to nextest. +[[profile.ci.overrides]] +platform = 'cfg(unix)' +filter = 'package(craft-ui) | package(craft-keymap) | package(craft-update)' +test-group = 'gpu' + +[[profile.ci.overrides]] +platform = 'cfg(unix)' +filter = 'package(craft-video) & kind(test)' +test-group = 'video-integration' diff --git a/.gitattributes b/.gitattributes index 0c35cf7c5..00c1fc249 100644 --- a/.gitattributes +++ b/.gitattributes @@ -17,3 +17,16 @@ crates/fonts-build/tests/fixture/craft-fonts/fonts/**/OFL.txt -text # DXF drawing goldens assert exact writer bytes, including LF on every platform. crates/dxf/tests/data/drawing_*.dxf -text + +# The generated components index is compared byte for byte with the generator's LF output (craft-ui test +# components_index): a Windows checkout must not convert its line endings. +docs/components-index.md text eol=lf + +# The built-in size files are compared byte for byte with the writer's LF output (craft-theme sizes_tests), and the +# token dumps with the dump writer's (craft-theme dumps test): a Windows checkout must not convert their line endings. +crates/theme/sizes/*.json text eol=lf +crates/theme/tests/dumps/** text eol=lf + +# The facade's [features] table is compared with the table the craft features test writes, with LF (craft test +# integration::features): a Windows checkout must not convert its line endings. +crates/craft/Cargo.toml text eol=lf diff --git a/.github/workflows/actions.lock b/.github/workflows/actions.lock index 02cdf71c8..c7f0a2e6b 100644 --- a/.github/workflows/actions.lock +++ b/.github/workflows/actions.lock @@ -18,7 +18,6 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/cms.yml': - 'actions/checkout@v4.4.0' - 'dtolnay/rust-toolchain@stable' @@ -27,7 +26,6 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/dialogs.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' @@ -36,10 +34,10 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - '.github/workflows/docpath.yml': + '.github/workflows/docs.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - - 'step-security/harden-runner@v2.22.4' + - 'step-security/rust-cache@v2.9.2' '.github/workflows/ecproj-format.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' @@ -52,22 +50,15 @@ workflows: - 'actions/checkout@v7.0.1' - 'dtolnay/rust-toolchain@stable' - 'step-security/harden-runner@v2.22.4' - - 'swatinem/rust-cache@v2.9.3' '.github/workflows/house-rules.yml': [] - '.github/workflows/i18n.yml': - - 'actions/checkout@v7.0.1' - - 'step-security/dtolnay-rust-toolchain@v1.0.0' - - 'step-security/harden-runner@v2.22.4' '.github/workflows/jpeg.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/keymap.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/lockfile.yml': - 'actions/checkout@v7.0.1' - 'step-security/harden-runner@v2.22.4' @@ -75,11 +66,10 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/menu.yml': - 'actions/checkout@v7.0.1' - 'dtolnay/rust-toolchain@stable' - - 'swatinem/rust-cache@v2.9.3' + '.github/workflows/nightly.yml': [] '.github/workflows/pcraft-format.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' @@ -89,23 +79,15 @@ workflows: - 'actions/setup-python@v7.1.0' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' - 'step-security/taiki-e-install-action@v2.87.32' - '.github/workflows/print.yml': - - 'actions/checkout@v7.0.1' - - 'step-security/dtolnay-rust-toolchain@v1.0.0' - - 'step-security/harden-runner@v2.22.4' '.github/workflows/proof.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/sonarcloud.yml': [] - '.github/workflows/ui.yml': + '.github/workflows/theme.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/update.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' @@ -118,7 +100,6 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' '.github/workflows/web-api.yml': - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' @@ -128,7 +109,6 @@ workflows: - 'actions/checkout@v7.0.1' - 'step-security/dtolnay-rust-toolchain@v1.0.0' - 'step-security/harden-runner@v2.22.4' - - 'step-security/rust-cache@v2.9.2' - 'step-security/taiki-e-install-action@v2.87.32' '.github/workflows/window.yml': - 'actions/checkout@v7.0.1' diff --git a/.github/workflows/ai-core.yml b/.github/workflows/ai-core.yml index 96e2c8474..6f5b34e89 100644 --- a/.github/workflows/ai-core.yml +++ b/.github/workflows/ai-core.yml @@ -12,20 +12,17 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: ai-core-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: ai-core-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: ai-core: + name: AI model WASM timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -35,15 +32,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-ai-core --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-ai-core --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-ai-core --locked # The model promises to compile for the web. - run: cargo check -p craft-ai-core --target wasm32-unknown-unknown --locked diff --git a/.github/workflows/atomic.yml b/.github/workflows/atomic.yml index dedfcf161..b7e1ece7c 100644 --- a/.github/workflows/atomic.yml +++ b/.github/workflows/atomic.yml @@ -12,20 +12,17 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: atomic-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: atomic-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests run in the Workspace gate on every OS; this runs what it does not. jobs: atomic: + name: Atomic inherited Linux ACLs timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -35,20 +32,9 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy - name: Install ACL tools - if: runner.os == 'Linux' run: sudo apt-get update && sudo apt-get install -y acl - - run: cargo fmt --check - - run: cargo clippy -p craft-atomic -p craft-settings --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-atomic -p craft-settings --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-atomic -p craft-settings --locked -- --nocapture - name: Check inherited Linux ACLs - if: runner.os == 'Linux' run: cargo test -p craft-atomic --locked -- --ignored --nocapture wasm: diff --git a/.github/workflows/audio.yml b/.github/workflows/audio.yml index 62c380e2d..6063c4e4d 100644 --- a/.github/workflows/audio.yml +++ b/.github/workflows/audio.yml @@ -11,17 +11,22 @@ on: permissions: contents: read +# A fraction of the fuzz-style cases, as in the Workspace gate; nightly.yml runs them in full. +env: + CRAFT_HOSTILE_DIVISOR: "8" + PROPTEST_CASES: "64" + concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-audio-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-audio-${{ github.ref }} + cancel-in-progress: true jobs: lint: timeout-minutes: 15 - name: Audio lint, feature sets, docs, WASM + # fmt, clippy with all features and the minimum Rust version run in the Workspace gate. + name: Audio feature sets, docs, WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -34,13 +39,8 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-audio-lint - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-audio --check # Each feature on its own, so code that needs another feature fails here. - name: Clippy, each feature alone run: | @@ -49,7 +49,6 @@ jobs: cargo clippy -p craft-audio --all-targets --locked --no-default-features ${f:+--features "$f"} -- -D warnings echo "::endgroup::" done - - run: cargo clippy -p craft-audio --all-targets --locked --all-features -- -D warnings # missing_docs is a warning in the crate; -D warnings makes it (and broken links) fail here. - run: cargo doc -p craft-audio --all-features --no-deps --locked env: @@ -63,25 +62,6 @@ jobs: RUSTDOCFLAGS: "-D warnings" - run: cargo check -p craft-audio --all-features --locked --target wasm32-unknown-unknown - run: cargo check -p craft-audio --no-default-features --features lossless-encode --locked --target wasm32-unknown-unknown - msrv: - timeout-minutes: 10 - name: Audio on the minimum Rust version - runs-on: ubuntu-latest - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - with: - persist-credentials: false - # The workspace's rust-version. - - run: rustup toolchain install 1.95.0 --profile minimal - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-audio-msrv - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo +1.95.0 check -p craft-audio -p craft-media --all-features --locked features: timeout-minutes: 10 name: Audio tests without symphonia and lossless-encode only @@ -97,10 +77,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-audio-features - save-if: ${{ github.ref == 'refs/heads/main' }} - run: cargo test -p craft-audio --no-default-features --features lossless-encode --locked - run: cargo test -p craft-audio --no-default-features --features pcm-encode --locked --lib - run: cargo test -p craft-audio --no-default-features --features flac-encode --locked --lib @@ -122,10 +98,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-audio-test - save-if: ${{ github.ref == 'refs/heads/main' }} - uses: actions/cache@v6.1.0 with: path: ${{ runner.temp }}/media-fixtures/opus/vectors diff --git a/.github/workflows/cms.yml b/.github/workflows/cms.yml index 2bb99686a..c18aecb27 100644 --- a/.github/workflows/cms.yml +++ b/.github/workflows/cms.yml @@ -11,6 +11,13 @@ on: permissions: contents: read +concurrency: + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: cms-${{ github.ref }} + cancel-in-progress: true + +# clippy and the debug tests run in the Workspace gate; this runs the release build of the tests. jobs: cms: timeout-minutes: 20 @@ -18,9 +25,6 @@ jobs: steps: - uses: actions/checkout@v4.4.0 - uses: dtolnay/rust-toolchain@stable - with: - components: clippy - - run: cargo clippy -p craft-cms --all-targets --all-features --locked -- -D warnings # Release: the FOGRA39 fit and ink-limit tests take about 35 s in debug and 4 s here. Tests that need # installed system profiles print "skipped:" when none are present. - run: cargo test -p craft-cms --all-features --release --locked -- --nocapture diff --git a/.github/workflows/crw.yml b/.github/workflows/crw.yml index 59c7395f2..1d2b4f389 100644 --- a/.github/workflows/crw.yml +++ b/.github/workflows/crw.yml @@ -12,46 +12,13 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-crw-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-crw-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: - native: - timeout-minutes: 20 - name: CRW lint and tests (${{ matrix.os }}) - strategy: - fail-fast: false - matrix: - os: ${{ github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - with: - persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: rustfmt, clippy - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-crw-${{ matrix.os }} - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-crw --check - - run: cargo clippy -p craft-crw --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-crw --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-crw --locked - wasm: timeout-minutes: 10 name: CRW WASM @@ -68,10 +35,6 @@ jobs: with: toolchain: stable targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-crw-wasm - save-if: ${{ github.ref == 'refs/heads/main' }} - run: cargo check -p craft-crw --locked --target wasm32-unknown-unknown samples: @@ -89,10 +52,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-crw-samples - save-if: ${{ github.ref == 'refs/heads/main' }} - name: Cache the CC0 sample files uses: actions/cache@v6.1.0 with: diff --git a/.github/workflows/dialogs.yml b/.github/workflows/dialogs.yml index c71de9f0a..f9ab8fe56 100644 --- a/.github/workflows/dialogs.yml +++ b/.github/workflows/dialogs.yml @@ -12,10 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: dialogs-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: dialogs-${{ github.ref }} + cancel-in-progress: true jobs: dialogs: @@ -37,10 +37,5 @@ jobs: components: clippy # The macOS code is linted on Linux: it compiles for the target without the SDK. targets: aarch64-apple-darwin - - run: cargo clippy -p craft-dialogs --all-targets --locked -- -D warnings + # Native clippy and the tests run in the Workspace gate. - run: cargo clippy -p craft-dialogs --target aarch64-apple-darwin --locked -- -D warnings - - name: Docs (links and missing docs) - run: cargo doc -p craft-dialogs --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-dialogs --locked diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index 406a47ea6..00b8336db 100644 --- a/.github/workflows/doc.yml +++ b/.github/workflows/doc.yml @@ -12,20 +12,17 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: doc-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: doc-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: doc: + name: Craft documents WASM timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -37,16 +34,5 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-doc --all-targets --locked -- -D warnings - - run: cargo clippy -p craft-doc --all-targets --all-features --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-doc --all-features --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-doc --locked -- --nocapture - - run: cargo test -p craft-doc --all-features --locked -- --nocapture - run: cargo check -p craft-doc --all-features --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/docpath.yml b/.github/workflows/docpath.yml deleted file mode 100644 index f19b9a6b4..000000000 --- a/.github/workflows/docpath.yml +++ /dev/null @@ -1,46 +0,0 @@ -name: Document paths - -on: - workflow_dispatch: - push: - branches: [main, next] - paths: ['crates/docpath/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/docpath.yml'] - pull_request: - paths: ['crates/docpath/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/docpath.yml'] - -permissions: - contents: read - -concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: docpath-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} - -jobs: - docpath: - timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: rustfmt, clippy - - run: cargo fmt --check - - run: cargo clippy -p craft-docpath --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-docpath --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-docpath --locked -- --nocapture diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index 5bd990d93..a37675342 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -20,14 +20,27 @@ jobs: name: Workspace docs runs-on: ubuntu-latest steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 with: # The token isn't needed after checkout; cargo runs build scripts and proc macros from # dependencies, so don't leave it in .git/config for that third-party code to read. persist-credentials: false - - uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable - - uses: Swatinem/rust-cache@d1527c8f67ef9af357290475d4af4b0fab8f12e0 # v2.9.3 + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 + with: + toolchain: stable + components: clippy + - uses: step-security/rust-cache@v2.9.2 + # A lib build selects no dev-dependency, so craft-ui's `testing` stays off as in an app's + # build: warnings that show only without it fail here. + - name: Facade as an app builds it + run: cargo clippy -p craft --lib --locked --features ui,layers,color,draw,imaging -- -D warnings - name: Docs (links and missing docs) run: cargo doc --workspace --no-deps --locked --keep-going env: RUSTDOCFLAGS: -D warnings + # The crates whose features add public items document with every feature too; the + # per-crate workflows document the media, audio and video crates. + - name: Docs with all features + run: cargo doc -p craft-ui -p craft-ui-contract -p craft-ui-widgets -p craft-ui-panels -p craft-ui-canvas -p craft-ui-patterns -p craft-ui-shell -p craft-doc -p craft-pdf --all-features --no-deps --locked --keep-going + env: + RUSTDOCFLAGS: -D warnings diff --git a/.github/workflows/ecproj-format.yml b/.github/workflows/ecproj-format.yml index 6ad11109c..bec96fed5 100644 --- a/.github/workflows/ecproj-format.yml +++ b/.github/workflows/ecproj-format.yml @@ -12,20 +12,17 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: ecproj-format-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: ecproj-format-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: ecproj-format: + name: EffectCraft project format WASM timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -37,14 +34,5 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-ecproj-format --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-ecproj-format --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-ecproj-format --locked -- --nocapture - run: cargo check -p craft-ecproj-format --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/font-store.yml b/.github/workflows/font-store.yml index ba1095b03..fd599d207 100644 --- a/.github/workflows/font-store.yml +++ b/.github/workflows/font-store.yml @@ -12,20 +12,17 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: font-store-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: font-store-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests run in the Workspace gate on every OS; this checks what it does not. jobs: font-store: + name: Font store WASM timeout-minutes: 20 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -35,18 +32,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-font-store --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-font-store --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-font-store --locked - - run: cargo clippy -p craft-font-catalog --all-targets --locked -- -D warnings - - run: cargo test -p craft-font-catalog --locked - name: Check the web build - if: runner.os == 'Linux' run: cargo check -p craft-font-store --target wasm32-unknown-unknown --locked diff --git a/.github/workflows/formats.yml b/.github/workflows/formats.yml index a78bbac5d..f96bf9a4a 100644 --- a/.github/workflows/formats.yml +++ b/.github/workflows/formats.yml @@ -42,11 +42,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-formats-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-formats-${{ github.ref }} + cancel-in-progress: true jobs: check: @@ -68,7 +67,9 @@ jobs: - { crate: craft-tiff, features: "" } - { crate: craft-heif, features: "testdata" } - { crate: craft-cms, features: "" } - name: ${{ matrix.crate }} lint, tests, WASM + # fmt, clippy with default and with all features, and the tests run in the Workspace gate on + # every OS; this lints each feature alone and checks the web build. + name: ${{ matrix.crate }} feature sets, WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -80,32 +81,19 @@ jobs: persist-credentials: false - uses: dtolnay/rust-toolchain@stable with: - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: Swatinem/rust-cache@v2.9.3 - with: - key: ${{ matrix.crate }} - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p "$CRATE" --check - env: - CRATE: ${{ matrix.crate }} - - name: Clippy, default features and each feature alone + - name: Clippy, each feature alone + if: matrix.features != '' env: CRATE: ${{ matrix.crate }} FEATURES: ${{ matrix.features }} run: | - cargo clippy -p "$CRATE" --all-targets --locked -- -D warnings for f in $FEATURES; do echo "::group::feature: $f" cargo clippy -p "$CRATE" --all-targets --locked --no-default-features --features "$f" -- -D warnings echo "::endgroup::" done - - run: cargo clippy -p "$CRATE" --all-targets --locked --all-features -- -D warnings - env: - CRATE: ${{ matrix.crate }} - - run: cargo test -p "$CRATE" --all-features --locked - env: - CRATE: ${{ matrix.crate }} - run: cargo check -p "$CRATE" --all-features --locked --target wasm32-unknown-unknown env: CRATE: ${{ matrix.crate }} diff --git a/.github/workflows/i18n.yml b/.github/workflows/i18n.yml deleted file mode 100644 index 61c7ccff3..000000000 --- a/.github/workflows/i18n.yml +++ /dev/null @@ -1,46 +0,0 @@ -name: Translations - -on: - workflow_dispatch: - push: - branches: [main, next] - paths: ['crates/i18n/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/i18n.yml'] - pull_request: - paths: ['crates/i18n/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/i18n.yml'] - -permissions: - contents: read - -concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: i18n-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} - -jobs: - i18n: - timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: rustfmt, clippy - - run: cargo fmt --check - - run: cargo clippy -p craft-i18n --all-targets --features collate --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-i18n --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-i18n --features collate --locked -- --nocapture diff --git a/.github/workflows/jpeg.yml b/.github/workflows/jpeg.yml index 6beccab19..ebb27bafd 100644 --- a/.github/workflows/jpeg.yml +++ b/.github/workflows/jpeg.yml @@ -12,16 +12,17 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-jpeg-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-jpeg-${{ github.ref }} + cancel-in-progress: true jobs: check: - timeout-minutes: 10 - name: JPEG lint, tests, WASM + # Uncached: the wasm check builds its dependencies on every run (about 10 minutes with setup). + timeout-minutes: 20 + # fmt, clippy and the tests run in the Workspace gate on every OS. + name: JPEG WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -34,17 +35,5 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-jpeg - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-jpeg --check - - run: cargo clippy -p craft-jpeg --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - run: cargo doc -p craft-jpeg --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-jpeg --locked - run: cargo check -p craft-jpeg --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/keymap.yml b/.github/workflows/keymap.yml index 2cd3fffed..bfce47378 100644 --- a/.github/workflows/keymap.yml +++ b/.github/workflows/keymap.yml @@ -12,16 +12,17 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: keymap-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: keymap-${{ github.ref }} + cancel-in-progress: true jobs: linux: timeout-minutes: 15 - name: Keymap (Linux) + # fmt, and clippy and the tests with default and with all features, run in the Workspace gate + # on every OS; this runs the feature subsets. + name: Keymap feature sets runs-on: ubuntu-latest env: CRAFT_FONTS_DIR: ${{ github.workspace }}/.test-inputs/craft-fonts @@ -43,59 +44,14 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-keymap-linux - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-keymap --check + components: clippy - run: cargo clippy -p craft-keymap --all-targets --no-default-features --locked -- -D warnings - run: cargo clippy -p craft-keymap --all-targets --features egui --locked -- -D warnings - - name: Docs (links and missing docs) - run: cargo doc -p craft-keymap --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - # Doctests run once, in the `ui` step. + # Doctests run once, in the `egui` step. - name: Test core run: cargo test -p craft-keymap --no-default-features --lib --tests --locked - name: Test egui dispatch run: cargo test -p craft-keymap --features egui --locked - native: - # Pushes to next run Linux only. - if: github.ref != 'refs/heads/next' || github.event_name == 'workflow_dispatch' - timeout-minutes: 15 - name: Keymap (${{ matrix.os }}) - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["macos-latest","windows-latest"]') || fromJSON('["windows-latest"]') }} - runs-on: ${{ matrix.os }} - env: - CRAFT_FONTS_DIR: ${{ github.workspace }}/.test-inputs/craft-fonts - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - with: - persist-credentials: false - - name: Checkout test fonts - uses: actions/checkout@v7.0.1 - with: - repository: storytold/craft-fonts - ref: b076417b5880bd4154bd22f00695b1d28c6bea83 - path: .test-inputs/craft-fonts - persist-credentials: false - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-keymap-${{ matrix.os }} - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo test -p craft-keymap --features egui --locked wasm: timeout-minutes: 10 name: Keymap WASM @@ -112,8 +68,4 @@ jobs: with: toolchain: stable targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-keymap-wasm - save-if: ${{ github.ref == 'refs/heads/main' }} - run: cargo check -p craft-keymap --features egui --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/media.yml b/.github/workflows/media.yml index 415ab92f9..090ad84da 100644 --- a/.github/workflows/media.yml +++ b/.github/workflows/media.yml @@ -11,17 +11,22 @@ on: permissions: contents: read +# A fraction of the fuzz-style cases, as in the Workspace gate; nightly.yml runs them in full. +env: + CRAFT_HOSTILE_DIVISOR: "8" + PROPTEST_CASES: "64" + concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-media-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-media-${{ github.ref }} + cancel-in-progress: true jobs: lint: timeout-minutes: 10 - name: Media lint, feature sets, WASM + # fmt, and clippy with default and with all features, run in the Workspace gate on every OS. + name: Media feature sets, WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -34,20 +39,12 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-media-lint - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-media --check - run: cargo clippy -p craft-media --all-targets --locked --no-default-features -- -D warnings - run: cargo clippy -p craft-media --all-targets --locked --no-default-features --features bitstream -- -D warnings - - run: cargo clippy -p craft-media --all-targets --locked -- -D warnings - run: cargo clippy -p craft-media --all-targets --locked --no-default-features --features matroska -- -D warnings - run: cargo clippy -p craft-media --all-targets --locked --no-default-features --features ogg -- -D warnings - - run: cargo clippy -p craft-media --all-targets --locked --all-features -- -D warnings - - run: cargo clippy -p craft-media-testkit --all-targets --locked -- -D warnings - run: cargo clippy -p craft-media --all-targets --locked --no-default-features --features serde -- -D warnings - name: Docs (links and missing docs) run: cargo doc -p craft-media -p craft-media-testkit --all-features --no-deps --locked @@ -69,10 +66,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-media-test - save-if: ${{ github.ref == 'refs/heads/main' }} - name: Build tests while installing ffmpeg run: | # The man-db index rebuild after dpkg is slow on hosted runners. diff --git a/.github/workflows/menu.yml b/.github/workflows/menu.yml index d0eac01a1..80b6678cd 100644 --- a/.github/workflows/menu.yml +++ b/.github/workflows/menu.yml @@ -18,7 +18,8 @@ concurrency: jobs: linux: timeout-minutes: 15 - name: Menu (Linux) + # fmt, native clippy and the tests run in the Workspace gate on every OS. + name: Menu macOS and WASM lint runs-on: ubuntu-latest steps: - uses: actions/checkout@v7.0.1 @@ -26,14 +27,8 @@ jobs: persist-credentials: false - uses: dtolnay/rust-toolchain@stable with: - components: rustfmt, clippy + components: clippy targets: aarch64-apple-darwin, wasm32-unknown-unknown - - uses: Swatinem/rust-cache@v2.9.3 - with: - key: craft-menu-linux - - run: cargo fmt -p craft-menu --check - - run: cargo clippy -p craft-menu --all-targets --locked -- -D warnings # The macOS backend type-checks from Linux; it needs no linker or SDK. - run: cargo clippy -p craft-menu --lib --locked --target aarch64-apple-darwin -- -D warnings - run: cargo clippy -p craft-menu --lib --locked --target wasm32-unknown-unknown -- -D warnings - - run: cargo test -p craft-menu --locked diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml new file mode 100644 index 000000000..ed9d36127 --- /dev/null +++ b/.github/workflows/nightly.yml @@ -0,0 +1,34 @@ +name: Nightly full tests + +# The tests the Workspace gate shortens, in full, once a day: every hostile-input hammer and sweep +# without CRAFT_HOSTILE_DIVISOR, and every proptest at its own case count (no PROPTEST_CASES). The +# rest of the workspace's tests run with them, on Linux, with the gate's setup. +on: + schedule: + - cron: "37 2 * * *" + workflow_dispatch: + +permissions: + contents: read + +concurrency: + group: nightly-${{ github.ref }} + cancel-in-progress: false + +jobs: + full: + name: Full tests + uses: storytold/craft-common-actions/.github/workflows/gate.yml@main + with: + os: '["ubuntu-latest"]' + timeout-minutes: 120 + tools: cargo-nextest@0.9.150 + packages: mesa-vulkan-drivers libvulkan1 + craft-fonts-ref: b076417b5880bd4154bd22f00695b1d28c6bea83 + linux-env: WGPU_BACKEND=vulkan + env: CRAFT_PRINT_REQUIRE_QUEUE=0 + setup-command: bash scripts/ci-test-inputs.sh + cache-paths: .test-inputs/photocraft/corpus + cache-key: photocraft-corpus + cache-key-files: scripts/ci-test-inputs.sh + command: cargo nextest run --workspace --all-features --locked --profile ci diff --git a/.github/workflows/pcraft-format.yml b/.github/workflows/pcraft-format.yml index 130e679b4..cefa5360c 100644 --- a/.github/workflows/pcraft-format.yml +++ b/.github/workflows/pcraft-format.yml @@ -12,20 +12,18 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: pcraft-format-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: pcraft-format-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests run in the Workspace gate on every OS, and its msrv job checks the +# workspace on 1.95; this checks the web build on 1.95. jobs: pcraft-format: + name: PhotoCraft format WASM timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -37,14 +35,5 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: "1.95" - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-pcraft-format --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-pcraft-format --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-pcraft-format --locked -- --nocapture - run: cargo check -p craft-pcraft-format --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/pdf.yml b/.github/workflows/pdf.yml index bcd81efa4..7785d9212 100644 --- a/.github/workflows/pdf.yml +++ b/.github/workflows/pdf.yml @@ -11,22 +11,23 @@ on: permissions: contents: read +# A fraction of the proptest cases, as in the Workspace gate; nightly.yml runs them in full. +env: + PROPTEST_CASES: "64" + concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-pdf-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-pdf-${{ github.ref }} + cancel-in-progress: true jobs: native: - name: PDF (${{ matrix.os }}) - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + # fmt, clippy and the tests run in the Workspace gate on every OS, with the licensed fonts and + # the plate tests; this runs the tests behind craft_pdf_unicode_fixtures and the read-only + # contract, which is its own workspace. + name: PDF Unicode fixtures and read-only contract + runs-on: ubuntu-latest env: RUSTFLAGS: --cfg craft_pdf_unicode_fixtures steps: @@ -38,11 +39,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-pdf - save-if: ${{ github.ref == 'refs/heads/main' }} - uses: actions/setup-python@v7.1.0 with: python-version: "3.12" @@ -52,14 +48,7 @@ jobs: python scripts/test-fetch-pdf-test-fonts.py python scripts/fetch-pdf-test-fonts.py "$RUNNER_TEMP/craft-pdf-test-fonts" echo "CRAFT_PDF_TEST_FONT_DIR=$RUNNER_TEMP/craft-pdf-test-fonts" >> "$GITHUB_ENV" - - run: cargo fmt --check - - run: cargo clippy -p craft-pdf --all-targets --all-features --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-pdf --all-features --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-pdf --all-features --locked + - run: cargo test -p craft-pdf --all-features --locked --lib -- integration::unicode_writing integration::upstream_compatibility - run: cargo test --manifest-path crates/pdf/read-only-contract/Cargo.toml --locked backends: name: PDF vendored contracts @@ -73,10 +62,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-pdf-backends - save-if: ${{ github.ref == 'refs/heads/main' }} - run: bash scripts/test-pdf-backends.sh wasm: name: PDF WASM runtime @@ -94,10 +79,6 @@ jobs: with: toolchain: stable targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-pdf-wasm - save-if: ${{ github.ref == 'refs/heads/main' }} - uses: actions/setup-python@v7.1.0 with: python-version: "3.12" @@ -122,31 +103,3 @@ jobs: fallback: cargo-install - run: cargo test -p craft-pdf --all-features --locked --target wasm32-unknown-unknown - run: cargo test --manifest-path crates/pdf/read-only-contract/Cargo.toml --locked --target wasm32-unknown-unknown - plate-test: - name: Plate tests and craft-prepress - runs-on: ubuntu-latest - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: clippy - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-plate-test - save-if: ${{ github.ref == 'refs/heads/main' }} - - uses: actions/setup-python@v7.1.0 - with: - python-version: "3.12" - - name: Provision licensed PDF test fonts - shell: bash - run: | - python scripts/test-fetch-pdf-test-fonts.py - python scripts/fetch-pdf-test-fonts.py "$RUNNER_TEMP/craft-pdf-test-fonts" - echo "CRAFT_PDF_TEST_FONT_DIR=$RUNNER_TEMP/craft-pdf-test-fonts" >> "$GITHUB_ENV" - - run: cargo clippy -p craft-plate-test -p craft-prepress --all-targets --all-features --locked -- -D warnings - - run: cargo test -p craft-plate-test -p craft-prepress --all-features --locked diff --git a/.github/workflows/print.yml b/.github/workflows/print.yml deleted file mode 100644 index c1994deb8..000000000 --- a/.github/workflows/print.yml +++ /dev/null @@ -1,51 +0,0 @@ -name: Print spooler -on: - workflow_dispatch: - push: - branches: [main, next] - paths: ['crates/print/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/print.yml'] - pull_request: - paths: ['crates/print/**', 'Cargo.toml', 'Cargo.lock', '.github/workflows/print.yml'] -permissions: - contents: read -concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: print-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} -jobs: - print: - timeout-minutes: 30 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: rustfmt, clippy - - run: cargo fmt --check - - run: cargo clippy -p craft-print --all-targets -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-print --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - name: Prepare the Windows test driver - if: runner.os == 'Windows' - shell: powershell - run: | - Start-Service Spooler - Add-PrinterDriver -Name 'Generic / Text Only' - - run: cargo test -p craft-print --locked -- --nocapture - timeout-minutes: 10 - env: - CRAFT_PRINT_REQUIRE_QUEUE: ${{ runner.os == 'Windows' && '1' || '0' }} diff --git a/.github/workflows/proof.yml b/.github/workflows/proof.yml index 84ccb38d4..0f5b869a4 100644 --- a/.github/workflows/proof.yml +++ b/.github/workflows/proof.yml @@ -12,16 +12,16 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: craft-proof-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: craft-proof-${{ github.ref }} + cancel-in-progress: true jobs: check: timeout-minutes: 20 - name: Proofing lint, tests with and without Language data, WASM + # fmt, and clippy and the tests without Language data, run in the Workspace gate on every OS. + name: Proofing with Language data, WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -43,18 +43,10 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-proof - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-proof --check - - name: Without Language data (a fork, docs.rs, offline) - run: | - cargo clippy -p craft-proof --all-targets --locked -- -D warnings - cargo test -p craft-proof --locked - cargo check -p craft-proof --locked --target wasm32-unknown-unknown + - name: The web build without Language data (a fork, docs.rs, offline) + run: cargo check -p craft-proof --locked --target wasm32-unknown-unknown - name: A release without Language data fails run: | if CRAFT_I18N_REQUIRED=1 cargo check -p craft-proof --locked 2>build.log; then diff --git a/.github/workflows/theme.yml b/.github/workflows/theme.yml index b61e9efcf..213a74b14 100644 --- a/.github/workflows/theme.yml +++ b/.github/workflows/theme.yml @@ -17,13 +17,14 @@ jobs: name: Theme lint, tests, WASM runs-on: ubuntu-latest steps: - - uses: actions/checkout@v7 + - uses: actions/checkout@v7.0.1 with: # The token isn't needed after checkout; cargo runs build scripts and proc macros from # dependencies, so don't leave it in .git/config for that third-party code to read. persist-credentials: false - - uses: dtolnay/rust-toolchain@b725eda525362e7cf34af9a7243cac1e3f01a7ec # stable + - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: + toolchain: stable components: rustfmt, clippy targets: wasm32-unknown-unknown - run: cargo fmt -p craft-theme --check diff --git a/.github/workflows/ui.yml b/.github/workflows/ui.yml deleted file mode 100644 index 805a344da..000000000 --- a/.github/workflows/ui.yml +++ /dev/null @@ -1,84 +0,0 @@ -name: Shared UI - -on: - push: - branches: [main, next] - paths: ["crates/craft/**", "crates/ui/**", "crates/ui-contract/**", "crates/ui-widgets/**", "crates/ui-panels/**", "crates/ui-canvas/**", "crates/ui-patterns/**", "crates/ui-shell/**", "crates/ui-macros/**", "crates/i18n/**", "Cargo.toml", "Cargo.lock", ".github/workflows/ui.yml"] - pull_request: - paths: ["crates/craft/**", "crates/ui/**", "crates/ui-contract/**", "crates/ui-widgets/**", "crates/ui-panels/**", "crates/ui-canvas/**", "crates/ui-patterns/**", "crates/ui-shell/**", "crates/ui-macros/**", "crates/i18n/**", "Cargo.toml", "Cargo.lock", ".github/workflows/ui.yml"] - workflow_dispatch: - -permissions: - contents: read - -concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-ui-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} - -jobs: - native: - timeout-minutes: 30 - name: UI (${{ matrix.os }}) - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - name: Install software Vulkan renderer - if: runner.os == 'Linux' - run: | - sudo apt-get update - sudo apt-get install -y mesa-vulkan-drivers libvulkan1 - echo 'WGPU_BACKEND=vulkan' >> "$GITHUB_ENV" - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - components: rustfmt, clippy - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-ui - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt --check - - run: cargo clippy -p craft-ui -p craft-ui-contract -p craft-ui-widgets -p craft-ui-panels -p craft-ui-canvas -p craft-ui-patterns -p craft-ui-shell --all-targets --locked -- -D warnings - - run: cargo clippy -p craft-ui -p craft-ui-contract -p craft-ui-widgets -p craft-ui-panels -p craft-ui-canvas -p craft-ui-patterns -p craft-ui-shell --all-targets --all-features --locked -- -D warnings - # A lib build selects no dev-dependency, so craft-ui's `testing` stays off as in an app's build: warnings that - # show only without it fail here. - - name: Facade as an app builds it - if: runner.os == 'Linux' - run: cargo clippy -p craft --lib --locked --features ui,layers,color,draw,imaging -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-ui -p craft-ui-contract -p craft-ui-widgets -p craft-ui-panels -p craft-ui-canvas -p craft-ui-patterns -p craft-ui-shell --all-features --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-ui -p craft-ui-contract -p craft-ui-widgets -p craft-ui-panels -p craft-ui-canvas -p craft-ui-patterns -p craft-ui-shell --locked - - run: cargo test -p craft-ui -p craft-ui-contract -p craft-ui-widgets -p craft-ui-panels -p craft-ui-canvas -p craft-ui-patterns -p craft-ui-shell --all-features --locked - wasm: - timeout-minutes: 15 - name: UI WASM - runs-on: ubuntu-latest - steps: - - name: Harden runner - uses: step-security/harden-runner@v2.22.4 - with: - egress-policy: audit - - uses: actions/checkout@v7.0.1 - - uses: step-security/dtolnay-rust-toolchain@v1.0.0 - with: - toolchain: stable - targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-ui-wasm - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo check -p craft-ui --all-features --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/update.yml b/.github/workflows/update.yml index 6ff69c10e..0ea3b8c1b 100644 --- a/.github/workflows/update.yml +++ b/.github/workflows/update.yml @@ -12,20 +12,18 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: update-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: update-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests with default and with all features run in the Workspace gate on every +# OS; this runs the ui feature alone. jobs: update: + name: Update with ui alone timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -39,15 +37,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy - - run: cargo fmt --check - # Default (no egui) and the ui feature both build and lint cleanly. - - run: cargo clippy -p craft-update --all-targets --locked -- -D warnings + components: clippy - run: cargo clippy -p craft-update --all-targets --locked --features ui -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-update --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-update --locked -- --nocapture - run: cargo test -p craft-update --locked --features ui -- --nocapture diff --git a/.github/workflows/vectorcraft-format.yml b/.github/workflows/vectorcraft-format.yml index b2eb4596b..0ca15636d 100644 --- a/.github/workflows/vectorcraft-format.yml +++ b/.github/workflows/vectorcraft-format.yml @@ -12,20 +12,18 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: vectorcraft-format-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: vectorcraft-format-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests run in the Workspace gate on every OS, and its msrv job checks the +# workspace on 1.95; this checks the web build on 1.95. jobs: vectorcraft-format: + name: VectorCraft format WASM timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -37,14 +35,5 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: "1.95" - components: rustfmt, clippy targets: wasm32-unknown-unknown - - run: cargo fmt --check - - run: cargo clippy -p craft-vectorcraft-format --all-targets --locked -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-vectorcraft-format --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-vectorcraft-format --locked -- --nocapture - run: cargo check -p craft-vectorcraft-format --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/video.yml b/.github/workflows/video.yml index a09f9bfe5..03b59cc42 100644 --- a/.github/workflows/video.yml +++ b/.github/workflows/video.yml @@ -11,6 +11,11 @@ on: permissions: contents: read +# A fraction of the fuzz-style cases, as in the Workspace gate; nightly.yml runs them in full. +env: + CRAFT_HOSTILE_DIVISOR: "8" + PROPTEST_CASES: "64" + concurrency: group: shared-video-${{ github.ref }} cancel-in-progress: true @@ -18,7 +23,8 @@ concurrency: jobs: lint: timeout-minutes: 20 - name: Video lint, feature sets, docs, WASM + # fmt and clippy with all features run in the Workspace gate on every OS. + name: Video feature sets, docs, WASM runs-on: ubuntu-latest steps: - name: Harden runner @@ -31,12 +37,8 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: "1.95" - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-video-lint - - run: cargo fmt -p craft-video --check # Each feature on its own, so code that needs another feature fails here. - name: Clippy, each feature alone run: | @@ -45,19 +47,15 @@ jobs: cargo clippy -p craft-video --all-targets --locked --no-default-features ${f:+--features "$f"} -- -D warnings echo "::endgroup::" done - - run: cargo clippy -p craft-video --all-targets --locked --all-features -- -D warnings - run: cargo doc -p craft-video --all-features --no-deps --locked env: RUSTDOCFLAGS: "-D warnings" - run: cargo check -p craft-video --all-features --locked --target wasm32-unknown-unknown test: timeout-minutes: 30 - strategy: - fail-fast: false - matrix: - os: ${{ github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} - name: Video tests (${{ matrix.os }}) + # The Workspace gate runs these tests on every OS without ffmpeg; this runs them with it. + runs-on: ubuntu-latest + name: Video tests with ffmpeg steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -69,11 +67,7 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: "1.95" - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-video-${{ matrix.os }} - - name: Install ffmpeg (Linux) - if: runner.os == 'Linux' + - name: Install ffmpeg run: | sudo rm -f /var/lib/man-db/auto-update sudo apt-get update -qq && sudo apt-get install -y -qq --no-install-recommends ffmpeg diff --git a/.github/workflows/web-api.yml b/.github/workflows/web-api.yml index 5b09d5155..0ad01e28f 100644 --- a/.github/workflows/web-api.yml +++ b/.github/workflows/web-api.yml @@ -12,10 +12,10 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: web-api-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: web-api-${{ github.ref }} + cancel-in-progress: true jobs: web-api: @@ -35,7 +35,7 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - name: Read the wasm-bindgen version from Cargo.lock id: wasm-bindgen @@ -50,12 +50,6 @@ jobs: with: tool: wasm-bindgen@${{ steps.wasm-bindgen.outputs.version }} fallback: cargo-install - - run: cargo fmt --check - - run: cargo clippy -p craft-web-api --all-targets --locked -- -D warnings + # fmt, native clippy and the native tests run in the Workspace gate. - run: cargo clippy -p craft-web-api --all-targets --locked --target wasm32-unknown-unknown -- -D warnings - - name: Docs (links and missing docs) - run: cargo doc -p craft-web-api --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-web-api --locked - run: cargo test -p craft-web-api --locked --target wasm32-unknown-unknown diff --git a/.github/workflows/web-host.yml b/.github/workflows/web-host.yml index 7463cc1f8..055303bc2 100644 --- a/.github/workflows/web-host.yml +++ b/.github/workflows/web-host.yml @@ -12,16 +12,16 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets its own group: it is never cancelled or replaced while queued, so it - # always gets to save the cache. - group: shared-web-host-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: shared-web-host-${{ github.ref }} + cancel-in-progress: true jobs: check: timeout-minutes: 20 - name: Web host lint, tests, WASM tests + # fmt, native clippy and the native tests run in the Workspace gate. + name: Web host WASM lint and tests runs-on: ubuntu-latest env: CARGO_TARGET_WASM32_UNKNOWN_UNKNOWN_RUNNER: wasm-bindgen-test-runner @@ -36,20 +36,9 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy + components: clippy targets: wasm32-unknown-unknown - - uses: step-security/rust-cache@v2.9.2 - with: - key: craft-web-host - save-if: ${{ github.ref == 'refs/heads/main' }} - - run: cargo fmt -p craft-web-host --check - - run: cargo clippy -p craft-web-host --all-targets --locked -- -D warnings - run: cargo clippy -p craft-web-host --all-targets --locked --target wasm32-unknown-unknown -- -D warnings - - name: Docs (links and missing docs) - run: cargo doc -p craft-web-host --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-web-host --locked - name: Read the wasm-bindgen version from Cargo.lock id: wasm-bindgen shell: bash diff --git a/.github/workflows/window.yml b/.github/workflows/window.yml index 73372ce56..a534393fd 100644 --- a/.github/workflows/window.yml +++ b/.github/workflows/window.yml @@ -12,20 +12,18 @@ permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (main, manual) gets a group of its own, so it is neither cancelled nor replaced while queued. - group: window-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # One group per pull request and per branch: a newer push cancels the run it supersedes, on main + # too, since the newest run checks everything before it. + group: window-${{ github.ref }} + cancel-in-progress: true +# fmt, clippy and the tests with default and with all features run in the Workspace gate on every +# OS; this runs the ui feature alone. jobs: window: + name: Window with ui alone timeout-minutes: 15 - strategy: - fail-fast: false - matrix: - # macOS runners are kept for releases: macOS runs only when started by hand. - os: ${{ github.event_name == 'workflow_dispatch' && fromJSON('["ubuntu-latest","windows-latest","macos-latest"]') || github.ref == 'refs/heads/next' && fromJSON('["ubuntu-latest"]') || fromJSON('["ubuntu-latest","windows-latest"]') }} - runs-on: ${{ matrix.os }} + runs-on: ubuntu-latest steps: - name: Harden runner uses: step-security/harden-runner@v2.22.4 @@ -39,15 +37,6 @@ jobs: - uses: step-security/dtolnay-rust-toolchain@v1.0.0 with: toolchain: stable - components: rustfmt, clippy - - run: cargo fmt --check - # Default (no egui) and the ui feature both build and lint cleanly. - - run: cargo clippy -p craft-window --all-targets --locked -- -D warnings + components: clippy - run: cargo clippy -p craft-window --all-targets --locked --features ui -- -D warnings - - name: Docs (links and missing docs) - if: runner.os == 'Linux' - run: cargo doc -p craft-window --no-deps --locked - env: - RUSTDOCFLAGS: -D warnings - - run: cargo test -p craft-window --locked -- --nocapture - run: cargo test -p craft-window --locked --features ui -- --nocapture diff --git a/.github/workflows/workspace.yml b/.github/workflows/workspace.yml index 3e7f07d8a..309506b2e 100644 --- a/.github/workflows/workspace.yml +++ b/.github/workflows/workspace.yml @@ -6,65 +6,81 @@ on: tags: ["v*"] pull_request: workflow_dispatch: + # A full run on main every 6 hours that is never cancelled, so the caches are saved while pushes + # to main cancel each other. + schedule: + - cron: "17 */6 * * *" permissions: contents: read concurrency: - # Pull requests share one group per branch, so a newer push cancels the older run. Every other - # run (push to main, a release tag, a manual run) gets a group of its own: it is neither - # cancelled nor replaced while queued, so a main run always finishes and saves the dependency - # cache, and a release run is never cancelled. - group: workspace-${{ github.event_name == 'pull_request' && github.ref || github.run_id }} - cancel-in-progress: ${{ github.event_name == 'pull_request' }} + # A pull request, and main, each have one group, so a newer push cancels the run it supersedes; + # the newest push's run still tests everything before it. Every other run (a release tag, a + # manual run, the scheduled run) gets a group of its own and is neither cancelled nor replaced + # while queued: a release run always finishes, and the scheduled run saves the caches. + group: workspace-${{ (github.event_name == 'pull_request' || github.event_name == 'push' && github.ref == 'refs/heads/main') && github.ref || github.run_id }} + cancel-in-progress: ${{ github.event_name == 'pull_request' || github.event_name == 'push' && github.ref == 'refs/heads/main' }} jobs: native: name: Workspace uses: storytold/craft-common-actions/.github/workflows/gate.yml@main with: + # Pushes to next run Linux only. os: ${{ github.ref == 'refs/heads/next' && '["ubuntu-latest"]' || '["ubuntu-latest","windows-latest","macos-latest"]' }} + # On a pull request, macOS and Windows run only when it can change platform behaviour: a + # crate with platform cfg code or one that depends on it, the build setup, or a file outside + # the crates (craft-common-actions' select-platforms). The full-ci label runs them anyway + # from the next push or manual run; pushes to main always run every leg. + select-os: '["windows-latest","macos-latest"]' timeout-minutes: 120 - # The Windows leg runs its tests with nextest (.config/nextest.toml). + # Every leg runs its tests with nextest, and its doctests with cargo test (.config/nextest.toml). tools: cargo-nextest@0.9.150 packages: mesa-vulkan-drivers libvulkan1 craft-fonts-ref: b076417b5880bd4154bd22f00695b1d28c6bea83 linux-env: WGPU_BACKEND=vulkan - windows-env: CRAFT_PRINT_REQUIRE_QUEUE=1 - env: CRAFT_PRINT_REQUIRE_QUEUE=0 - setup-command: | - set -euo pipefail - corpus_fetcher=.test-inputs/photocraft - mkdir -p "$corpus_fetcher" - git -C "$corpus_fetcher" init - git -C "$corpus_fetcher" remote add origin https://github.com/storytold/PhotoCraft.git - git -C "$corpus_fetcher" fetch --quiet --depth=1 origin 74330157cb601573ae4523a95bb9132822fc3918 - git -C "$corpus_fetcher" checkout --quiet --detach FETCH_HEAD - (cd "$corpus_fetcher" && cargo xtask corpus --psd --psd-tools --atn --exr --heif --pngsuite) - mkdir -p corpus - cp -a "$corpus_fetcher/corpus/." corpus/ - python scripts/test-fetch-pdf-test-fonts.py - python scripts/fetch-pdf-test-fonts.py "$RUNNER_TEMP/craft-pdf-test-fonts" - printf 'CRAFT_PSD_CORPUS=%s\n' "$GITHUB_WORKSPACE/$corpus_fetcher/corpus" >> "$GITHUB_ENV" - printf 'CRAFT_PDF_TEST_FONT_DIR=%s\n' "$RUNNER_TEMP/craft-pdf-test-fonts" >> "$GITHUB_ENV" + # No debuginfo on Windows: writing PDBs for every test binary is a large part of its link + # time. A panic still names its file and line; only backtrace frames lose theirs, and the + # Linux and macOS legs keep line tables. + windows-env: | + CRAFT_PRINT_REQUIRE_QUEUE=1 + CARGO_PROFILE_DEV_DEBUG=0 + # The fuzz-style tests run a fraction of their cases here: every hostile-input hammer and + # sweep 1/8 (craft-testkit's CRAFT_HOSTILE_DIVISOR), every proptest without its own case + # count 64 cases instead of 256. nightly.yml runs them all in full. + env: | + CRAFT_PRINT_REQUIRE_QUEUE=0 + CRAFT_HOSTILE_DIVISOR=8 + PROPTEST_CASES=64 + setup-command: bash scripts/ci-test-inputs.sh + # The PhotoCraft corpora, keyed on the script that pins them: a hit skips the PhotoCraft + # checkout and its xtask build (1:51 on Windows). + cache-paths: .test-inputs/photocraft/corpus + cache-key: photocraft-corpus + cache-key-files: scripts/ci-test-inputs.sh + # A `lint ()` leg beside each `gate ()` leg, so clippy is off the tests' critical path. + lint-command: | + if [ "$RUNNER_OS" = Linux ]; then + python3 scripts/test-workspace-concurrency.py + python3 scripts/test-workspace-tests.py + fi + cargo fmt --check + cargo clippy --workspace --all-targets --locked -- -D warnings + cargo clippy --workspace --all-targets --all-features --locked -- -D warnings command: | - python3 scripts/test-workspace-concurrency.py - cargo fmt --check - cargo clippy --workspace --all-targets --locked --keep-going -- -D warnings - cargo clippy --workspace --all-targets --all-features --locked --keep-going -- -D warnings - cargo test --workspace --locked - cargo test --workspace --all-features --locked - windows-command: | - powershell.exe -NoProfile -Command '$ErrorActionPreference = "Stop"; Start-Service Spooler; Add-PrinterDriver -Name "Generic / Text Only"' - cargo fmt --check - cargo clippy --workspace --all-targets --locked --keep-going -- -D warnings - cargo clippy --workspace --all-targets --all-features --locked --keep-going -- -D warnings - # The same tests as `cargo test`, run in parallel across test binaries instead of one - # binary at a time; nextest skips doctests, so `cargo test --doc` runs them. - cargo nextest run --workspace --locked --profile ci - cargo test --workspace --doc --locked + # The tests run once, with every feature, in parallel across test binaries; nextest skips + # doctests, so `cargo test --doc` runs them. The default-feature compile is the lint leg's + # first clippy run; the last command runs the crates whose tests check behaviour with a + # feature off, which an all-features build cannot reach. cargo nextest run --workspace --all-features --locked --profile ci cargo test --workspace --doc --all-features --locked + cargo nextest run -p craft-image-codecs -p craft-text --locked --profile ci + windows-command: | + powershell.exe -NoProfile -Command '$ErrorActionPreference = "Stop"; Start-Service Spooler; Add-PrinterDriver -Name "Generic / Text Only"' + cargo nextest run --workspace --all-features --locked --profile ci + cargo test --workspace --doc --all-features --locked + cargo nextest run -p craft-image-codecs -p craft-text --locked --profile ci msrv: name: Rust 1.95 diff --git a/ATTRIBUTION.md b/ATTRIBUTION.md index c42bc8168..de712b4ee 100644 --- a/ATTRIBUTION.md +++ b/ATTRIBUTION.md @@ -122,9 +122,47 @@ The XML reader in `crates/plist/src/xml.rs` and its base64 compatibility helper `crates/palette` extracts the GPL text parser from AniCraft `crates/doc/src/swatch.rs` at `d875a7feb250e6ab06aa28a37fb78a0699e88330` (MIT OR Apache-2.0), introduced by Tanish Manku in `a64130a9da9bdde545463b852d95d6a6774b1dfd` (AniCraft #270). The import preserves Tanish as primary author. Neutral RGB/name adaptation separates application display-name sanitization and the `Untitled` policy; validation tests and integration are subsequent Dylan M. Taylor changes. +The legacy ZIP Zstandard method-20 mapping and bounded-read regression in `crates/zip/src/lenient` are ported from RRFZ's Craft Anything commit `29badae7c9280fdf4c24795927bf3a91f51694c6` (MIT OR Apache-2.0). RRFZ remains the primary Git author. Firmware scanner detection remains app-owned and is not part of this port. +## TAR/CPIO compatibility updates + +The old GNU sparse-extension traversal, GNU CRC-symlink compatibility and PAX-size precedence fixes and their regression tests in `crates/tar` are ported from RRFZ's Craft Anything PRs #1973 (`8ea2ec66a1bc80f0420f3695baac877a0cb9b9a5`), #1984 (`b226a475f7dce9710e3af7a069386fe7a9720df7`) and #2007 (`d29465c20b0d570ea4973be512a0cb4e212bb60f`). Source is MIT OR Apache-2.0; RRFZ remains the primary Git author of each port. The PAX update adapts to the shared parser's existing `PaxOverrides` structure without changing the source policy. + +## Aligned stored ZIP entries + +The USDZ alignment requirement and compatibility fixture for `Writer::add_stored_aligned` come from TextureCraft `crates/formats/src/mesh_export/usd.rs`, introduced by bflatastic in `bdbb52c9` and maintained through `9eb20086` (MIT OR Apache-2.0). The shared API and alignment validation are subsequent Dylan M. Taylor work. Scene/material mapping remains in TextureCraft. + The raw gradient wire ordering in `craft-lottie::Gradient::flat_values` follows AniCraft's Lottie exporter by Tanish Manku (`63b39355`, `b9258b7b`), MIT OR Apache-2.0. Sanitization, animation fitting and numeric output policy remain caller-owned. + ## Screen Video key frames `crates/video/src/screen_video.rs` extracts AniCraft `crates/xfl/src/video.rs` codec-3 decoding and its synthetic partial-block fixture, introduced by Tanish Manku in `1f3e603b7ff53a3da364e41ec4da8d43dc83aab0` with pixel-loop cleanup `2b7571363b4b647266df758f95b6e397021cfd4d` (MIT OR Apache-2.0). Import commits preserve Tanish as primary author. Caller-owned bounds and neutral RGBA output separate codec work from the consuming app's FLV first-frame/report policy. Boundary tests and integration are subsequent Dylan M. Taylor changes. + +## Source Map v3 parser and lookup + +`crates/sourcemap` extracts the bounded parser, source inventory and generated-position lookup from Craft Anything `crates/formats/src/sourcemap.rs` at `e5c9c94106747ed44b9a3fb0decce867c2285f93` (MIT OR Apache-2.0). Core-history ports preserve Brandon Thomas, BFlat, Afloat, RRFZ, Nicolas Bohn and Alex Joaquim Pereira as primary authors, with exact source revisions in each commit. Six regression files preserve their source authors; nine core unit tests retain the original tests. App annotation scanning, data URLs, base64 and file I/O are intentionally not imported. Workspace wiring is a subsequent change; existing limits and errors are unchanged. +## JSONC span-preserving editing + +`crates/jsonc` is extracted from Craft Anything `crates/formats/src/jsonc.rs` at `e5c9c94106747ed44b9a3fb0decce867c2285f93` (MIT OR Apache-2.0). The original implementation and hardening by BFlat, newline preservation by NetterSilver, and subsequent RRFZ/Afloat correctness fixes retain separate primary-author port commits with immutable source revisions. Shared API wiring and optional input-byte admission are subsequent changes. Compatibility parsing and all existing formatting/editing tests are retained; application file I/O and policy are not imported. + +## Java class inspection + +`crates/java-class` extracts Craft Anything `java_class.rs` and `java_ops.rs` at `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0), preserving separate primary-author source-history ports by Brandon Thomas, BFlat, Afloat and RRFZ. The checked byte-reader, modified UTF-8 unit decoder, descriptor display helper and synthetic class fixtures come from the same source snapshot. Seven regression files retain their source authors. Neutral error wiring and shared crate integration are subsequent changes. No JAR archive, application I/O or bytecode execution is imported. + +## WebAssembly inspection + +`crates/wasm` extracts Craft Anything `crates/formats/src/wasm.rs` at `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2`, with its checked byte-reader subset and original synthetic WASM/testkit fixtures (MIT OR Apache-2.0). Eight core-history ports preserve Brandon Thomas, Afloat and RRFZ as primary authors; component, repeated-custom-section and referenced-string regression imports retain source authors and commit references. Fixtures come from `crates/testkit/src/formats.rs` and deterministic mutation helpers from `crates/testkit/src/lib.rs`; no third-party binaries. Shared error naming and workspace wiring are subsequent changes. Existing inspection limits and report behavior are unchanged; this crate validates/inspects/renders, never executes modules. + +## Packet capture and protocol inspection + +`crates/pcap` extracts Craft Anything `crates/formats/src/pcap.rs`, its checked byte reader primitives and synthetic packet fixtures/regressions at `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0). Brandon Thomas introduced the implementation, byte reader and fixtures in `f64ae3bf3c8863a982af1304e06de20653803968`. Subsequent fixes by phatloi0010, GGWA, BFlat, Afloat, NetterSilver, Max Mittelstädt and RRFZ retain separate primary-author source-history commits with immutable source revisions. Shared error/API wiring and chrono-based timestamp formatting with exhaustive day-boundary parity tests are subsequent Dylan M. Taylor changes. No packet reassembly, decryption, live capture or app analysis policy is imported. +## HTTP Archive reader + +`crates/har` preserves Craft Anything `crates/formats/src/har.rs` from `5979f9b13f16dcf1df3c7ae7f8e7735f452866f2` (MIT OR Apache-2.0). Brandon Thomas introduced the typed reader in `f64ae3bf3c8863a982af1304e06de20653803968`; BFlat added UTF-8 BOM compatibility in `cb0bb9d8fa4536ba44ef2c86f5ed759b879cc2d3`. Both source snapshots retain primary author attribution. Shared wiring, explicit byte admission and its tests are subsequent Dylan M. Taylor changes. Redaction and analysis remain app-owned. + +## XFDF field reader + +`crates/xfdf` extracts PDFCraft field reading from #5937 refresh `cb564fd827f572818e9ddb0ea5989a432b1f39fd` (MIT OR Apache-2.0). App-side annotation and form policy remains local; source history is retained in the original repository. + +Retained XFDF source contributors (move-aware blame): Brandon Thomas, Marco Arnulfo, pkibiego and storybored379; module split by aiongg. Subsequent budget/integration work by Dylan M. Taylor. diff --git a/Cargo.lock b/Cargo.lock index dcdeaed12..191e94921 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1188,6 +1188,18 @@ dependencies = [ "winx", ] +[[package]] +name = "cap-std" +version = "4.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "c1ec78e242cfa2cfe276807ac2ecc00315a6c97786977414bcd1c3963b6c91b8" +dependencies = [ + "cap-primitives", + "io-extras", + "io-lifetimes 3.0.1", + "rustix 1.1.5", +] + [[package]] name = "cast" version = "0.3.0" @@ -1729,6 +1741,9 @@ dependencies = [ "craft-browse", "craft-captions", "craft-cfb", + "craft-cloud", + "craft-cloud-local", + "craft-cloud-ui", "craft-cms", "craft-codepage", "craft-color", @@ -1778,6 +1793,7 @@ dependencies = [ "craft-gif", "craft-gridcraft-format", "craft-gzip", + "craft-har", "craft-hdr", "craft-heif", "craft-host", @@ -1790,8 +1806,10 @@ dependencies = [ "craft-imaging", "craft-indd", "craft-ipc", + "craft-java-class", "craft-jmap", "craft-jpeg", + "craft-jsonc", "craft-jsonrpc", "craft-jxl", "craft-keymap", @@ -1823,6 +1841,7 @@ dependencies = [ "craft-ora", "craft-pages", "craft-palette", + "craft-pcap", "craft-pcraft-bundle", "craft-pcraft-format", "craft-pdf 0.1.0", @@ -1858,6 +1877,7 @@ dependencies = [ "craft-sketch", "craft-smime", "craft-sniff", + "craft-sourcemap", "craft-ssip", "craft-stencilcraft-document", "craft-stencilcraft-format", @@ -1881,12 +1901,14 @@ dependencies = [ "craft-vectorcraft-format", "craft-vectordrawable", "craft-video", + "craft-wasm", "craft-web-api", "craft-web-host", "craft-webp", "craft-window", "craft-wordmodel", "craft-xcf", + "craft-xfdf", "craft-xfl", "craft-xls", "craft-xlsx", @@ -2081,6 +2103,36 @@ dependencies = [ "craft-media-testkit", ] +[[package]] +name = "craft-cloud" +version = "0.1.0" +dependencies = [ + "serde", + "thiserror 2.0.21", +] + +[[package]] +name = "craft-cloud-local" +version = "0.1.0" +dependencies = [ + "cap-std", + "craft-cloud", + "craft-ui", + "egui", + "tempfile", +] + +[[package]] +name = "craft-cloud-ui" +version = "0.1.0" +dependencies = [ + "craft-cloud", + "egui", + "egui_kittest", + "image", + "serde_json", +] + [[package]] name = "craft-cms" version = "0.1.0" @@ -2199,6 +2251,7 @@ dependencies = [ name = "craft-design-lint" version = "0.1.0" dependencies = [ + "dunce", "proc-macro2", "quote", "serde", @@ -2665,6 +2718,14 @@ dependencies = [ "flate2", ] +[[package]] +name = "craft-har" +version = "0.1.0" +dependencies = [ + "serde_json", + "thiserror 2.0.21", +] + [[package]] name = "craft-hdr" version = "0.1.0" @@ -2830,6 +2891,14 @@ dependencies = [ "widestring", ] +[[package]] +name = "craft-java-class" +version = "0.1.0" +dependencies = [ + "serde", + "thiserror 2.0.21", +] + [[package]] name = "craft-jmap" version = "0.1.0" @@ -2849,6 +2918,13 @@ dependencies = [ "zune-jpeg", ] +[[package]] +name = "craft-jsonc" +version = "0.1.0" +dependencies = [ + "serde_json", +] + [[package]] name = "craft-jsonrpc" version = "0.1.0" @@ -3207,6 +3283,16 @@ dependencies = [ name = "craft-palette" version = "0.1.0" +[[package]] +name = "craft-pcap" +version = "0.1.0" +dependencies = [ + "chrono", + "serde", + "serde_json", + "thiserror 2.0.21", +] + [[package]] name = "craft-pcraft-bundle" version = "0.1.0" @@ -3528,6 +3614,7 @@ name = "craft-raster-codecs" version = "0.1.0" dependencies = [ "base64 0.23.1", + "craft-dds", "craft-image-codecs", "image", "thiserror 2.0.21", @@ -3699,6 +3786,15 @@ dependencies = [ name = "craft-sniff" version = "0.1.0" +[[package]] +name = "craft-sourcemap" +version = "0.1.0" +dependencies = [ + "serde", + "serde_json", + "thiserror 2.0.21", +] + [[package]] name = "craft-ssip" version = "0.1.0" @@ -3909,6 +4005,7 @@ name = "craft-ui" version = "0.1.0" dependencies = [ "craft-behavior", + "craft-cloud-ui", "craft-i18n", "craft-ui", "craft-ui-canvas", @@ -4206,6 +4303,16 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "craft-wasm" +version = "0.1.0" +dependencies = [ + "serde", + "thiserror 2.0.21", + "wasmparser 0.261.0", + "wasmprinter", +] + [[package]] name = "craft-web-api" version = "0.1.0" @@ -4294,6 +4401,14 @@ dependencies = [ "thiserror 2.0.21", ] +[[package]] +name = "craft-xfdf" +version = "0.1.0" +dependencies = [ + "craft-xml", + "thiserror 2.0.21", +] + [[package]] name = "craft-xfl" version = "0.1.0" @@ -6392,7 +6507,7 @@ dependencies = [ [[package]] name = "harfbuzz-subset-sys" version = "0.1.0+harfbuzz-15.0.0" -source = "git+https://github.com/storytold/harfbuzz.git?rev=2659dd807f9a48f75604ee7c76cb709f7b70b950#2659dd807f9a48f75604ee7c76cb709f7b70b950" +source = "git+https://github.com/storytold/harfbuzz.git?rev=f32ed1e548eaa8852bff47e49a90629a013a2faa#f32ed1e548eaa8852bff47e49a90629a013a2faa" dependencies = [ "cc", ] @@ -13254,7 +13369,7 @@ dependencies = [ "wasmi_collections", "wasmi_core", "wasmi_ir", - "wasmparser", + "wasmparser 0.228.0", ] [[package]] @@ -13294,6 +13409,28 @@ dependencies = [ "indexmap", ] +[[package]] +name = "wasmparser" +version = "0.261.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "4f20f20e44f7e8aeb6744823ea9d869ede51e51be4fdaedede2852282e54d2d8" +dependencies = [ + "bitflags 2.13.2", + "indexmap", + "semver", +] + +[[package]] +name = "wasmprinter" +version = "0.261.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "86a21c9e3325655ba02de3e645bc8357a8b3651a2e3ada25b6dbc37560deb9b7" +dependencies = [ + "anyhow", + "termcolor", + "wasmparser 0.261.0", +] + [[package]] name = "wayland-backend" version = "0.3.17" diff --git a/Cargo.toml b/Cargo.toml index a7b8713ab..bc711ff49 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -11,6 +11,12 @@ rust-version = "1.95" repository = "https://github.com/storytold/craft-libs" [workspace.dependencies] +craft-java-class = { path = "crates/java-class" } +craft-sourcemap = { path = "crates/sourcemap" } +craft-pcap = { path = "crates/pcap" } +craft-har = { path = "crates/har" } +craft-xfdf = { path = "crates/xfdf" } +craft-jsonc = { path = "crates/jsonc" } craft-palette = { path = "crates/palette" } craft-score = { path = "crates/score" } craft-shx = { path = "crates/shx" } @@ -25,6 +31,7 @@ acadrust = "=0.6.6" log = "0.4" # internal: add each crate here as `craft- = { path = "crates/" }` craft-plist = { path = "crates/plist" } +craft-wasm = { path = "crates/wasm" } craft-platform = { path = "crates/platform" } craft-aep = { path = "crates/aep" } craft-affinity = { path = "crates/affinity" } @@ -58,6 +65,9 @@ craft-captions = { path = "crates/captions" } craft-cfb = { path = "crates/cfb" } craft-codepage = { path = "crates/codepage" } craft-cms = { path = "crates/cms" } +craft-cloud = { path = "crates/cloud" } +craft-cloud-local = { path = "crates/cloud-local" } +craft-cloud-ui = { path = "crates/cloud-ui" } craft-color = { path = "crates/color" } craft-color-ui = { path = "crates/color-ui" } craft-frame = { path = "crates/frame" } @@ -113,7 +123,7 @@ craft-fig = { path = "crates/fig" } craft-fonts-build = { path = "crates/fonts-build" } craft-font-subset = { path = "crates/font-subset" } # The HarfBuzz subsetter from storytold's HarfBuzz fork (branch rust-subset-15.0.0: HarfBuzz 15.0.0 plus rust/harfbuzz-subset-sys). -harfbuzz-subset-sys = { git = "https://github.com/storytold/harfbuzz.git", rev = "2659dd807f9a48f75604ee7c76cb709f7b70b950" } +harfbuzz-subset-sys = { git = "https://github.com/storytold/harfbuzz.git", rev = "f32ed1e548eaa8852bff47e49a90629a013a2faa" } craft-host = { path = "crates/host" } craft-i18n = { path = "crates/i18n" } craft-ipc = { path = "crates/ipc" } diff --git a/README.md b/README.md index d42d43b07..659b21db0 100644 --- a/README.md +++ b/README.md @@ -288,7 +288,7 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit - [`craft-math`](crates/math/README.md): equations as one tree (the Office Math object model) with its syntaxes, read and written: OMML, presentation MathML, LaTeX math and the UnicodeMath linear format. - [`craft-media`](crates/media/README.md): bit-level I/O (`bitstream`), clean-room MP4/MOV (`isobmff`), Matroska/WebM (`matroska`) and MXF (`mxf`) demuxers and muxers, Ogg (`ogg`), AVI (`avi`) and - MPEG-TS/PS (`mpegts`) demuxers, from FilmCraft, and an ISO BMFF box reader. Containers only; codecs are in `craft-audio`, and + MPEG-TS/PS (`mpegts`) demuxers, from FilmCraft, a Sierra VMD (`vmd`) demuxer, and an ISO BMFF box reader. Containers only; codecs are in `craft-audio`, and video codecs will go in a separate crate. - [`craft-lottie`](crates/lottie/README.md): Lottie (Bodymovin) JSON: the document model of lottie-spec 1.0 (animation, assets, layers by type, shape items, masks, effects, text, markers) diff --git a/crates/atomic/tests/permissions.rs b/crates/atomic/tests/permissions.rs index bd8e63a5b..95702cfe7 100644 --- a/crates/atomic/tests/permissions.rs +++ b/crates/atomic/tests/permissions.rs @@ -6,11 +6,16 @@ use craft_atomic::{NewFilePermissions, WriteOptions, atomic_write, write_new}; use std::fs::{self, File, Permissions}; use std::io::{self, Write}; use std::os::unix::fs::PermissionsExt; -use std::path::{Path, PathBuf}; +use std::path::Path; +#[cfg(target_os = "linux")] +use std::path::PathBuf; use std::process::Command; +#[cfg(target_os = "linux")] use std::sync::atomic::{AtomicU64, Ordering}; +#[cfg(target_os = "linux")] struct TempDir(PathBuf); +#[cfg(target_os = "linux")] impl TempDir { fn new() -> io::Result { static N: AtomicU64 = AtomicU64::new(0); @@ -19,6 +24,7 @@ impl TempDir { Ok(Self(path)) } } +#[cfg(target_os = "linux")] impl Drop for TempDir { fn drop(&mut self) { let _ = fs::remove_dir_all(&self.0); @@ -29,6 +35,7 @@ fn mode(path: &Path) -> io::Result { Ok(fs::metadata(path)?.permissions().mode() & 0o777) } +#[cfg(target_os = "linux")] /// Set umask only in a separate shell process; changing it in a parallel test process races. fn child(dir: &Path, mask: &str, expected: &str, check_acl: bool) -> io::Result<()> { let output = Command::new("sh") diff --git a/crates/audio/Cargo.toml b/crates/audio/Cargo.toml index 734cb7f45..78c589e49 100644 --- a/crates/audio/Cargo.toml +++ b/crates/audio/Cargo.toml @@ -37,15 +37,23 @@ flac-encode = ["craft-media/bitstream"] # The pure-Rust Vorbis encoder (`vorbis::encoder`) and Ogg Vorbis files through `encode` and # `encode_ogg_vorbis`. vorbis-encode = ["craft-media/ogg"] +# The pure-Rust Vorbis decoder (`vorbis::decoder`), packets and whole Ogg Vorbis files. +vorbis-decode = ["craft-media/ogg"] # Codec modules on their own, for packet-level use. aac-decode = ["craft-media/bitstream"] # The AAC encoder (`aac::Encoder`), and AAC in M4A through `encode` and `FileEncoder`. aac-encode = ["craft-media/bitstream", "craft-media/isobmff"] opus-decode = [] +# ADPCM (`adpcm`): IMA WAV, Microsoft, Yamaha and Flash (SWF) decoders and encoders. +adpcm = ["craft-media/bitstream"] # QOA (Quite OK Audio) files: decoder and encoder in the `qoa` module, each on its own. qoa = ["qoa-decode", "qoa-encode"] qoa-decode = [] qoa-encode = [] +# ITU-T G.722 wideband sub-band ADPCM speech codec (64 kbit/s). +g722 = [] +# ITU-T G.726 ADPCM speech codec (16/24/32/40 kbit/s). +g726 = [] opus-encode = [] # GSM 06.10 full-rate speech: decoder and encoder in the `gsm` module, each on its own. gsm = ["gsm-decode", "gsm-encode"] @@ -63,8 +71,13 @@ ac3-encode = ["craft-media/bitstream"] eac3-encode = ["craft-media/bitstream"] # MPEG-1/2 Layer III (MP3) encoder (`mp3`). mp3-encode = ["craft-media/bitstream"] +# MPEG-1/2 Layer II (MP2) encoder (`mpa::encoder`). It shares the polyphase analysis filter of the +# MP3 encoder and the tables of the MP1/MP2 decoder. +mpa-encode = ["mpa-decode", "mp3-encode"] # Bluetooth Low Complexity Subband Coding (SBC) audio codec (`sbc`). sbc = [] +# Sierra VMD sound decoder (`vmd::Decoder`): 8-bit PCM and 16-bit DPCM. +vmd-decode = [] # Multi-resolution waveform overviews (`peaks`). peaks = [] # Encode AAC channels in parallel (with `aac-encode`). @@ -84,6 +97,8 @@ symphonia = { version = "0.6.1", optional = true, default-features = false, feat [dev-dependencies] craft-media-testkit = { workspace = true } +# The VMD demuxer, for the VMD sound decoder's tests. +craft-media = { workspace = true, features = ["vmd"] } proptest = { workspace = true } serde_json = { workspace = true } diff --git a/crates/audio/README.md b/crates/audio/README.md index 10080ebbe..bd80b5406 100644 --- a/crates/audio/README.md +++ b/crates/audio/README.md @@ -39,12 +39,16 @@ No default features. The shared types (`AudioBuffer`, `AudioInfo`, `ChannelLayou | `alac-encode` | `alac::Encoder`; `encode`, `FileEncoder` for ALAC in M4A | craft-media `isobmff` | | `opus-decode`, `opus-encode` | `opus::Decoder`/`StreamDecoder`, `opus::Encoder` | none | | `vorbis-encode` | `vorbis::encoder::Encoder` (pure Rust); `encode_ogg_vorbis`, `encode_ogg` and `encode` for Ogg Vorbis files (whole buffer; not `FileEncoder`) | craft-media `ogg` | +| `vorbis-decode` | `vorbis::decoder::Decoder` (packets), `vorbis::decoder::decode_ogg` (whole Ogg Vorbis files); native Vorbis I: floors 0 and 1, residues 0 to 2, channel coupling, both block sizes. `decode` still reads Vorbis files through symphonia | craft-media `ogg` | | `ac3-decode` | `ac3::Decoder`, `ac3::ProgrammeDecoder` | craft-media `bitstream` | | `ac3-encode`, `eac3-encode` | `ac3::encoder::Encoder`; `encode`, `FileEncoder` for AC-3 and E-AC-3 streams | craft-media `bitstream` | | `mpa-decode` | `mpa::Decoder` | craft-media `bitstream` | | `mp3-decode` | `mp3::Decoder`, `mp3::InfoTag` | `mpa-decode` | | `mp3-encode` | `mp3::Encoder`; `encode`, `FileEncoder` for MP3 | craft-media `bitstream` | +| `mpa-encode` | `mpa::encoder::Encoder` (Layer II / MP2 frames) | `mpa-decode`, `mp3-encode` | +| `adpcm` | `adpcm::{ima, ms, yamaha, swf}`: decoders and encoders for IMA WAV, Microsoft, Yamaha and Flash ADPCM | craft-media `bitstream` | | `gsm-decode`, `gsm-encode` (`gsm`) | `gsm::Decoder`, `gsm::Encoder`, `gsm::decode`, `gsm::encode`: GSM 06.10 full-rate speech, bit-exact, raw `.gsm` and WAV (GSM 6.10) packings | none | +| `vmd-decode` | `vmd::Decoder`: Sierra VMD sound (8-bit PCM and 16-bit DPCM), frame by frame from `craft_media::vmd` | none | | `peaks` | `peaks::Peaks` | none | | `rayon` | parallel AAC encoding (with `aac-encode`) | `rayon` | | `serde` | `Serialize`/`Deserialize` on the shared types | `serde` | @@ -566,6 +570,7 @@ Each codec module's rustdoc lists the coding tools it implements. | Opus (`opus`) | RFC 6716, 8251, 7845 | decoder: SILK, hybrid, CELT, all frame sizes, PLC and FEC, multistream (`Decoder`) and single stream (`StreamDecoder`), 8–48 kHz output; encoder (`Encoder`): SILK, hybrid, CELT, 48 kHz, 20 ms frames, mono or stereo | all 36 RFC 8251 conformance cases; encoder output through ffmpeg's two Opus decoders | | AC-3/E-AC-3 (`ac3`) | decoder: ATSC A/52:2012; encoder/programme API: ETSI TS 102 366 V1.4.1 | single-syncframe and complete-programme decoding; packet encoding through discrete 7.1 (see below) | decoder comparisons and encoder output through ffmpeg, CRC/channel/timing/bit-budget regressions; synthetic quality limitations below | | MP1/MP2 (`mpa`) | ISO/IEC 11172-3, 13818-3 | Layer I and II, MPEG-1/2/2.5, 8–48 kHz; also the Layer II rate/mode pairs the spec disallows (ffmpeg's default mono 384 kbit/s); no free format | ffmpeg-encoded streams, 73–84 dB SNR | +| MP2 encoder (`mpa::encoder`) | ISO/IEC 11172-3 (§2.4, Annex B and C), 13818-3 | Layer II, constant bit rate, mono or stereo (no joint stereo), 32/44.1/48 kHz at the spec's rate/mode pairs and 16/22.05/24 kHz at 8–160 kbit/s; no CRC | our decoder and ffmpeg decode the frames; SNR of 20–37 dB on tone mixes, and the 481-sample filter delay matches | | MP3 decoder (`mp3`) | ISO/IEC 11172-3, 13818-3 | Layer III, MPEG-1/2/2.5, 8–48 kHz, every bit rate, CBR and VBR; mono, stereo, dual channel, joint stereo (mid/side and intensity); long, short and mixed blocks; bit reservoir; CRC read, not checked; Xing / Info / VBRI and LAME tags; no free format (read through symphonia) | ffmpeg's float decoder: 127–131 dB SNR on LAME streams of every sampling frequency (CBR, VBR, CRC, no reservoir, transients with short blocks) and on this crate's encoder's; intensity stereo and mixed blocks through LAME frames edited to use them (112–131 dB) | | MP3 encoder (`mp3`) | ISO/IEC 11172-3, 13818-3 | Layer III, constant bit rate: 32–320 kbit/s at 32/44.1/48 kHz, 8–160 kbit/s at 16/22.05/24 kHz; mono, stereo, joint stereo (mid/side); bit reservoir; long blocks only; no Xing/Info tag, VBR, CRC or free format | ffmpeg decodes every Huffman code as intended; full encodes at every sampling frequency checked with ffprobe and by SNR of ffmpeg's decode | | ALAC (`alac`) | Apple's reference implementation | decode and encode, 1–8 channels, 16/20/24/32 bits (decode: any depth 1–32), fast mode, magic cookie in MP4/Matroska and CAF form | Apple's reference: same packets from the encoder, same samples from both decoders on 766 configurations; ffmpeg: bit-exact both ways | diff --git a/crates/audio/src/adpcm/ima.rs b/crates/audio/src/adpcm/ima.rs new file mode 100644 index 000000000..dcf6958f7 --- /dev/null +++ b/crates/audio/src/adpcm/ima.rs @@ -0,0 +1,247 @@ +//! IMA ADPCM in WAV blocks (format tag 0x0011). +//! +//! A block is, per channel, a 4-byte header (the first sample as `i16` and the step index as `u8`, +//! then a zero byte), then groups of 4 bytes per channel in channel order, each holding eight +//! 4-bit codes, low nibble first. A block of `block_align` bytes holds +//! `(block_align - 4 * channels) * 2 / channels + 1` samples per channel. A code is a sign bit and +//! three magnitude bits: the decoder adds `step/8` plus `step`, `step/2` and `step/4` for each set +//! magnitude bit from the top, then moves the step index by `[-1, -1, -1, -1, 2, 4, 6, 8]`. + +use super::{Error, Result, clip16, step_at}; + +const INDEX_ADJUST: [i32; 8] = [-1, -1, -1, -1, 2, 4, 6, 8]; + +/// The state of one channel's decoder. +#[derive(Clone, Copy)] +struct State { + predictor: i32, + index: i32, +} + +impl State { + /// The sample after code `nibble`. + fn step(&mut self, nibble: u8) -> i16 { + let step = step_at(self.index); + let mut diff = step >> 3; + if nibble & 1 != 0 { + diff += step >> 2; + } + if nibble & 2 != 0 { + diff += step >> 1; + } + if nibble & 4 != 0 { + diff += step; + } + if nibble & 8 != 0 { + diff = -diff; + } + self.predictor = clip16(self.predictor + diff); + self.index = (self.index + INDEX_ADJUST.get(usize::from(nibble & 7)).copied().unwrap_or(0)).clamp(0, 88); + self.predictor as i16 + } + + /// The code that brings the predictor closest to `sample`, applied to the state. + fn encode(&mut self, sample: i16) -> u8 { + let step = step_at(self.index); + let mut diff = i32::from(sample) - self.predictor; + let mut code = 0u8; + if diff < 0 { + code = 8; + diff = -diff; + } + let mut s = step; + for bit in [4u8, 2, 1] { + if diff >= s { + code |= bit; + diff -= s; + } + s >>= 1; + } + self.step(code); + code + } +} + +/// Samples per channel in a block of `block_align` bytes; `None` when the layout is impossible +/// (a block must hold the headers and whole groups of eight samples, and there are 1 to 8 +/// channels). +pub fn samples_per_block(block_align: usize, channels: usize) -> Option { + if !(1..=8).contains(&channels) { + return None; + } + let header = 4 * channels; + let body = block_align.checked_sub(header)?; + if body == 0 || !body.is_multiple_of(4 * channels) { + return None; + } + let per = (body / channels).checked_mul(2)?.checked_add(1)?; + // Callers size interleaved buffers from this value; the full count must fit too. + per.checked_mul(channels)?; + Some(per) +} + +/// Decode one block, appending its samples interleaved by channel to `out`. +pub fn decode_block(block: &[u8], channels: usize, out: &mut Vec) -> Result<()> { + let per = samples_per_block(block.len(), channels).ok_or(Error::Malformed("block size does not fit the channel count"))?; + let mut states = Vec::with_capacity(channels); + for ch in 0..channels { + let h = block.get(4 * ch..4 * ch + 4).ok_or(Error::Malformed("truncated block header"))?; + let index = i32::from(h[2]); + if index > 88 { + return Err(Error::Malformed("step index above 88")); + } + states.push(State { predictor: i32::from(i16::from_le_bytes([h[0], h[1]])), index }); + } + let start = out.len(); + out.resize(start + per * channels, 0); + let samples = out.get_mut(start..).ok_or(Error::Malformed("output"))?; + for (ch, s) in states.iter().enumerate() { + if let Some(o) = samples.get_mut(ch) { + *o = s.predictor as i16; + } + } + let body = block.get(4 * channels..).ok_or(Error::Malformed("truncated block"))?; + for (g, group) in body.chunks_exact(4 * channels).enumerate() { + for (ch, bytes) in group.as_chunks::<4>().0.iter().enumerate() { + let Some(state) = states.get_mut(ch) else { continue }; + for (k, b) in bytes.iter().enumerate() { + for (half, nibble) in [b & 0xF, b >> 4].into_iter().enumerate() { + let t = 1 + g * 8 + k * 2 + half; + if let Some(o) = samples.get_mut(t * channels + ch) { + *o = state.step(nibble); + } + } + } + } + } + Ok(()) +} + +/// Decode a stream of blocks of `block_align` bytes. A final partial block is decoded as far as it +/// holds whole groups. +pub fn decode(data: &[u8], channels: usize, block_align: usize) -> Result> { + samples_per_block(block_align, channels).ok_or(Error::Malformed("block size does not fit the channel count"))?; + let mut out = Vec::new(); + for block in data.chunks(block_align) { + if block.len() == block_align { + decode_block(block, channels, &mut out)?; + } else { + let (header, group) = (4 * channels, 4 * channels); + let whole = block.len().saturating_sub(header) / group * group; + if whole > 0 { + decode_block(block.get(..header + whole).unwrap_or(block), channels, &mut out)?; + } + } + } + Ok(out) +} + +/// The starting step index for a channel whose first samples are `x`: the index whose first +/// codes follow `x` most closely. +fn start_index(first: i16, x: &[i16]) -> i32 { + let mut best = (i64::MAX, 0); + for index in 0..=88 { + let mut st = State { predictor: i32::from(first), index }; + let mut err = 0i64; + for &s in x.iter().take(16) { + let code = st.encode(s); + let _ = code; + err += (i64::from(s) - i64::from(st.predictor)).pow(2); + } + if err < best.0 { + best = (err, index); + } + } + best.1 +} + +/// Encode one block from exactly `samples_per_block * channels` interleaved samples. +pub fn encode_block(samples: &[i16], channels: usize, block_align: usize) -> Result> { + let per = samples_per_block(block_align, channels).ok_or(Error::InvalidInput("block size does not fit the channel count"))?; + if samples.len() != per * channels { + return Err(Error::InvalidInput("a block needs exactly samples_per_block samples per channel")); + } + let mut block = vec![0u8; block_align]; + let mut states = Vec::with_capacity(channels); + for ch in 0..channels { + let col: Vec = samples.iter().skip(ch).step_by(channels).copied().collect(); + let first = col.first().copied().unwrap_or(0); + let st = State { predictor: i32::from(first), index: start_index(first, col.get(1..).unwrap_or(&[])) }; + if let Some(h) = block.get_mut(4 * ch..4 * ch + 4) { + h[..2].copy_from_slice(&first.to_le_bytes()); + h[2] = st.index as u8; + } + states.push(st); + } + let groups = (block_align - 4 * channels) / (4 * channels); + for g in 0..groups { + for ch in 0..channels { + let Some(state) = states.get_mut(ch) else { continue }; + for k in 0..4 { + let mut byte = 0u8; + for half in 0..2 { + let t = 1 + g * 8 + k * 2 + half; + let nibble = state.encode(samples.get(t * channels + ch).copied().unwrap_or(0)); + byte |= nibble << (4 * half); + } + if let Some(b) = block.get_mut(4 * channels + g * 4 * channels + ch * 4 + k) { + *b = byte; + } + } + } + } + Ok(block) +} + +/// Encode interleaved samples as blocks of `block_align` bytes. The last block is padded with +/// copies of the last sample, so a decoder returns up to one block more than was given. +pub fn encode(samples: &[i16], channels: usize, block_align: usize) -> Result> { + let per = samples_per_block(block_align, channels).ok_or(Error::InvalidInput("block size does not fit the channel count"))?; + if !samples.len().is_multiple_of(channels) { + return Err(Error::InvalidInput("the sample count is not a multiple of the channel count")); + } + let mut out = Vec::new(); + for chunk in samples.chunks(per * channels) { + if chunk.len() == per * channels { + out.extend(encode_block(chunk, channels, block_align)?); + } else { + let mut padded = chunk.to_vec(); + let last: Vec = chunk.get(chunk.len().saturating_sub(channels)..).unwrap_or(&[]).to_vec(); + while padded.len() < per * channels { + padded.extend(last.iter().copied().chain(std::iter::repeat(0)).take(channels)); + } + out.extend(encode_block(&padded, channels, block_align)?); + } + } + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn layout() { + assert_eq!(samples_per_block(256, 1), Some(505)); + assert_eq!(samples_per_block(512, 2), Some(505)); + assert_eq!(samples_per_block(4, 1), None); + assert_eq!(samples_per_block(100, 0), None); + assert_eq!(samples_per_block(258, 2), None); + } + + #[test] + fn unrepresentable_interleaved_layout_is_rejected() { + let align = usize::MAX - 7; + assert_eq!(samples_per_block(align, 2), None); + assert!(encode(&[], 2, align).is_err()); + assert!(encode_block(&[], 2, align).is_err()); + } + + #[test] + fn silence_stays_silent() { + let block = encode_block(&vec![0; 505], 1, 256).unwrap(); + let mut out = Vec::new(); + decode_block(&block, 1, &mut out).unwrap(); + assert!(out.iter().all(|&s| s == 0)); + } +} diff --git a/crates/audio/src/adpcm/mod.rs b/crates/audio/src/adpcm/mod.rs new file mode 100644 index 000000000..da552d3cd --- /dev/null +++ b/crates/audio/src/adpcm/mod.rs @@ -0,0 +1,56 @@ +//! ADPCM: a decoder and an encoder for four families, each on whole blocks or streams of `i16` +//! samples interleaved by channel (feature `adpcm`). +//! +//! - [`ima`]: IMA / DVI ADPCM in WAV blocks (format tag 0x0011): 4 bits per sample, a 4-byte header +//! per channel and groups of eight samples per channel. +//! - [`ms`]: Microsoft ADPCM in WAV blocks (format tag 0x0002): 4 bits per sample, adaptive +//! two-tap prediction with the seven standard coefficient pairs. +//! - [`yamaha`]: Yamaha ADPCM (the YM2608 / AICA family): a raw stream of 4-bit codes. +//! - [`swf`]: the ADPCM of Flash (SWF) audio: 2 to 5 bits per sample, in blocks of 4096 samples. +//! +//! Written from the public descriptions of the algorithms: the IMA Digital Audio Focus and +//! Technical Working Groups' *Recommended Practices for Enhancing Digital Audio Compatibility* +//! (IMA ADPCM), Microsoft's *Multimedia Standards Update* (the WAVE format tags and the block +//! layout of Microsoft ADPCM), the SWF file format specification (the ADPCM section) and the +//! Yamaha ADPCM-B description. ffmpeg is only run as a black-box oracle in the tests. +//! +//! Decoders return errors, never panic, on damaged blocks. Encoders are greedy: they choose each +//! code to bring the decoder's output closest to the sample. + +pub mod ima; +pub mod ms; +pub mod swf; +pub mod yamaha; + +/// What went wrong decoding or encoding ADPCM. +#[non_exhaustive] +#[derive(Debug, thiserror::Error, PartialEq, Eq)] +pub enum Error { + /// The data is damaged, truncated or does not fit the stated block layout. + #[error("malformed ADPCM: {0}")] + Malformed(&'static str), + /// The settings or samples given to an encoder cannot be written. + #[error("ADPCM cannot encode: {0}")] + InvalidInput(&'static str), +} + +/// Result with this module's [`Error`]. +pub type Result = std::result::Result; + +/// IMA ADPCM step sizes (the 89-entry table of the IMA recommended practices). +pub(crate) const STEP_TABLE: [i32; 89] = [ + 7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 21, 23, 25, 28, 31, 34, 37, 41, 45, 50, 55, 60, 66, 73, 80, 88, 97, 107, 118, 130, 143, 157, 173, 190, + 209, 230, 253, 279, 307, 337, 371, 408, 449, 494, 544, 598, 658, 724, 796, 876, 963, 1060, 1166, 1282, 1411, 1552, 1707, 1878, 2066, 2272, 2499, + 2749, 3024, 3327, 3660, 4026, 4428, 4871, 5358, 5894, 6484, 7132, 7845, 8630, 9493, 10442, 11487, 12635, 13899, 15289, 16818, 18500, 20350, + 22385, 24623, 27086, 29794, 32767, +]; + +/// Clamp to the 16-bit sample range. +pub(crate) fn clip16(v: i32) -> i32 { + v.clamp(i32::from(i16::MIN), i32::from(i16::MAX)) +} + +/// The step size at `index` (clamped to the table). +pub(crate) fn step_at(index: i32) -> i32 { + STEP_TABLE.get(index.clamp(0, 88) as usize).copied().unwrap_or(7) +} diff --git a/crates/audio/src/adpcm/ms.rs b/crates/audio/src/adpcm/ms.rs new file mode 100644 index 000000000..057f93549 --- /dev/null +++ b/crates/audio/src/adpcm/ms.rs @@ -0,0 +1,244 @@ +//! Microsoft ADPCM in WAV blocks (format tag 0x0002). +//! +//! A block starts, for all channels in turn, with one predictor index (a byte, 0 to 6), then one +//! initial step (`delta`, `i16`), then each channel's second-last sample (`sample1`, `i16`) and +//! last sample (`sample2`, `i16`) before the block; the block's first two samples per channel are +//! `sample2` then `sample1`. The rest is 4-bit two's-complement codes, the first channel in the +//! high nibble. A block of `block_align` bytes holds `(block_align - 7 * channels) * 2 / channels +//! + 2` samples per channel. Each sample is predicted as `(sample1 * c1 + sample2 * c2) / 256` (rounding toward zero) +//! from the block's coefficient pair, plus `code * delta`; then `delta` becomes +//! `max(16, delta * a / 256)`, where `a` is the table entry for the code (`ADAPT`). + +use super::{Error, Result, clip16}; + +/// The seven coefficient pairs `(c1, c2)` every Microsoft ADPCM stream uses. +pub const COEFFICIENTS: [(i32, i32); 7] = [(256, 0), (512, -256), (0, 0), (192, 64), (240, 0), (460, -208), (392, -232)]; +/// How the step moves with the code's unsigned value (the index is the 4-bit pattern). +/// The largest step. The reference keeps it in 16 bits and no real stream gets near this bound; it +/// keeps every product in range however long a damaged block runs. +const MAX_DELTA: i32 = 1 << 24; +const ADAPT: [i32; 16] = [230, 230, 230, 230, 307, 409, 512, 614, 768, 614, 512, 409, 307, 230, 230, 230]; + +#[derive(Clone, Copy)] +struct State { + c1: i32, + c2: i32, + delta: i32, + s1: i32, + s2: i32, +} + +impl State { + fn step(&mut self, nibble: u8) -> i16 { + let signed = i32::from(nibble) - if nibble & 8 != 0 { 16 } else { 0 }; + let predicted = (self.s1 * self.c1 + self.s2 * self.c2) / 256; + let sample = clip16(predicted + signed * self.delta); + self.s2 = self.s1; + self.s1 = sample; + let adapt = i64::from(ADAPT.get(usize::from(nibble)).copied().unwrap_or(256)); + let new_delta = (adapt * i64::from(self.delta)) >> 8; + self.delta = (new_delta.min(i64::from(MAX_DELTA)) as i32).max(16); + sample as i16 + } + + /// The code that brings the output closest to `sample`, applied to the state. + fn encode(&mut self, sample: i16) -> u8 { + let predicted = (self.s1 * self.c1 + self.s2 * self.c2) / 256; + let err = i32::from(sample) - predicted; + // round to the nearest multiple of delta + let q = if err >= 0 { (err + self.delta / 2) / self.delta } else { -((-err + self.delta / 2) / self.delta) }; + let code = (q.clamp(-8, 7) & 0xF) as u8; + self.step(code); + code + } +} + +/// Samples per channel in a block of `block_align` bytes; `None` for an impossible layout (1 or 2 +/// channels, and room for the header and at least one code byte). +pub fn samples_per_block(block_align: usize, channels: usize) -> Option { + if !(1..=2).contains(&channels) { + return None; + } + let body = block_align.checked_sub(7 * channels).filter(|&b| b > 0)?; + // codes pair up across channels + let per = (body.checked_mul(2)? / channels).checked_add(2)?; + // Include the header samples and all channels before callers size their buffers. + per.checked_mul(channels)?; + Some(per) +} + +/// Decode one block, appending its samples interleaved by channel to `out`. +pub fn decode_block(block: &[u8], channels: usize, out: &mut Vec) -> Result<()> { + let per = samples_per_block(block.len(), channels).ok_or(Error::Malformed("block size does not fit the channel count"))?; + let header = block.get(..7 * channels).ok_or(Error::Malformed("truncated block header"))?; + let mut states = Vec::with_capacity(channels); + let word = |i: usize| i32::from(i16::from_le_bytes([header.get(i).copied().unwrap_or(0), header.get(i + 1).copied().unwrap_or(0)])); + for ch in 0..channels { + let pred = usize::from(header.get(ch).copied().unwrap_or(0)); + let &(c1, c2) = COEFFICIENTS.get(pred).ok_or(Error::Malformed("predictor index above 6"))?; + states.push(State { c1, c2, delta: word(channels + 2 * ch), s1: word(3 * channels + 2 * ch), s2: word(5 * channels + 2 * ch) }); + } + let start = out.len(); + out.resize(start + per * channels, 0); + let samples = out.get_mut(start..).ok_or(Error::Malformed("output"))?; + for (ch, s) in states.iter().enumerate() { + if let Some(a) = samples.get_mut(ch) { + *a = s.s2 as i16; + } + if let Some(b) = samples.get_mut(channels + ch) { + *b = s.s1 as i16; + } + } + let codes = block.get(7 * channels..).ok_or(Error::Malformed("truncated block"))?; + let mut t = 2 * channels; + for byte in codes { + for nibble in [byte >> 4, byte & 0xF] { + let ch = t % channels; + if let (Some(o), Some(state)) = (samples.get_mut(t), states.get_mut(ch)) { + *o = state.step(nibble); + } + t += 1; + } + } + Ok(()) +} + +/// Decode a stream of blocks of `block_align` bytes. A final partial block is decoded in full if +/// it holds a header and a code byte. +pub fn decode(data: &[u8], channels: usize, block_align: usize) -> Result> { + samples_per_block(block_align, channels).ok_or(Error::Malformed("block size does not fit the channel count"))?; + let mut out = Vec::new(); + for block in data.chunks(block_align) { + if block.len() == block_align || samples_per_block(block.len(), channels).is_some() { + decode_block(block, channels, &mut out)?; + } + } + Ok(out) +} + +/// The squared error of encoding `col` (one channel) from state `st`. +fn trial(mut st: State, col: &[i16]) -> i64 { + let mut err = 0i64; + for &s in col { + st.encode(s); + err += (i64::from(s) - i64::from(st.s1)).pow(2); + } + err +} + +/// Encode one block from exactly `samples_per_block * channels` interleaved samples. Each channel +/// gets the coefficient pair and initial step that code it with the least error. +pub fn encode_block(samples: &[i16], channels: usize, block_align: usize) -> Result> { + let per = samples_per_block(block_align, channels).ok_or(Error::InvalidInput("block size does not fit the channel count"))?; + if samples.len() != per * channels { + return Err(Error::InvalidInput("a block needs exactly samples_per_block samples per channel")); + } + let mut block = vec![0u8; block_align]; + let mut states = Vec::with_capacity(channels); + for ch in 0..channels { + let col: Vec = samples.iter().skip(ch).step_by(channels).copied().collect(); + let (x0, x1) = (col.first().copied().unwrap_or(0), col.get(1).copied().unwrap_or(0)); + let rest = col.get(2..).unwrap_or(&[]); + let mut best: Option<(i64, usize, i32)> = None; + for (p, &(c1, c2)) in COEFFICIENTS.iter().enumerate() { + for delta in [16, 64, 256, 1024] { + let st = State { c1, c2, delta, s1: i32::from(x1), s2: i32::from(x0) }; + let e = trial(st, rest); + if best.is_none_or(|(b, _, _)| e < b) { + best = Some((e, p, delta)); + } + } + } + let (_, p, delta) = best.unwrap_or((0, 0, 16)); + let &(c1, c2) = COEFFICIENTS.get(p).unwrap_or(&(256, 0)); + states.push(State { c1, c2, delta, s1: i32::from(x1), s2: i32::from(x0) }); + let (d, a, b) = (delta as i16, x1, x0); + let put = |block: &mut Vec, at: usize, v: i16| { + if let Some(w) = block.get_mut(at..at + 2) { + w.copy_from_slice(&v.to_le_bytes()); + } + }; + if let Some(h) = block.get_mut(ch) { + *h = p as u8; + } + put(&mut block, channels + 2 * ch, d); + put(&mut block, 3 * channels + 2 * ch, a); + put(&mut block, 5 * channels + 2 * ch, b); + } + let mut t = 2 * channels; + for byte in block.iter_mut().skip(7 * channels) { + let mut b = 0u8; + for half in 0..2 { + let ch = t % channels; + let nibble = match states.get_mut(ch) { + Some(st) => st.encode(samples.get(t).copied().unwrap_or(0)), + None => 0, + }; + b |= nibble << (4 * (1 - half)); + t += 1; + } + *byte = b; + } + Ok(block) +} + +/// Encode interleaved samples as blocks of `block_align` bytes. The last block is padded with +/// copies of the last frame, so a decoder returns up to one block more than was given. +pub fn encode(samples: &[i16], channels: usize, block_align: usize) -> Result> { + let per = samples_per_block(block_align, channels).ok_or(Error::InvalidInput("block size does not fit the channel count"))?; + if !samples.len().is_multiple_of(channels) { + return Err(Error::InvalidInput("the sample count is not a multiple of the channel count")); + } + let mut out = Vec::new(); + for chunk in samples.chunks(per * channels) { + let mut padded = chunk.to_vec(); + let last: Vec = chunk.get(chunk.len().saturating_sub(channels)..).unwrap_or(&[]).to_vec(); + while padded.len() < per * channels { + padded.extend(last.iter().copied().chain(std::iter::repeat(0)).take(channels)); + } + out.extend(encode_block(&padded, channels, block_align)?); + } + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn layout() { + assert_eq!(samples_per_block(256, 1), Some(500)); + assert_eq!(samples_per_block(512, 2), Some(500)); + assert_eq!(samples_per_block(7, 1), None); + assert_eq!(samples_per_block(100, 3), None); + } + + #[test] + fn unrepresentable_layouts_are_rejected() { + for (align, channels) in [(usize::MAX / 2 + 7, 1), (usize::MAX / 2 + 14, 2)] { + assert_eq!(samples_per_block(align, channels), None); + assert!(encode(&[], channels, align).is_err()); + assert!(encode_block(&[], channels, align).is_err()); + } + } + + #[test] + fn a_long_run_of_large_codes_cannot_overflow() { + // a step that starts at its largest 16-bit value and grows with every large code + let mut block = vec![0x77u8; 7 + 2000]; + block[..7].copy_from_slice(&[0, 255, 127, 0, 0, 0, 0]); + for b in block.iter_mut().skip(7) { + *b = 0x88; + } + let mut out = Vec::new(); + decode_block(&block, 1, &mut out).unwrap(); + assert_eq!(out.len(), 2000 * 2 + 2); + } + + #[test] + fn bad_predictor_index_is_an_error() { + let mut block = vec![0u8; 64]; + block[0] = 7; + assert!(decode_block(&block, 1, &mut Vec::new()).is_err()); + } +} diff --git a/crates/audio/src/adpcm/swf.rs b/crates/audio/src/adpcm/swf.rs new file mode 100644 index 000000000..2fc780b1d --- /dev/null +++ b/crates/audio/src/adpcm/swf.rs @@ -0,0 +1,168 @@ +//! The ADPCM of Flash (SWF) audio, 2 to 5 bits per sample. +//! +//! The stream starts with two bits, the code size minus 2. It continues in blocks of 4096 samples +//! per channel: each block starts, for every channel, with the first sample (16 bits, signed) and +//! the step index (6 bits, 0 to 88), then 4095 codes per channel, interleaved by sample. All fields +//! are packed most significant bit first. A code is a sign bit and `bits - 1` magnitude bits; the +//! decoder adds `step >> (bits - 1)` plus `step >> k` for each magnitude bit set `k` places below +//! the top one, negated when the sign is set, and moves the step index by the adjustment table of +//! the code size (negative for small magnitudes, positive for large ones). The last block may +//! be shorter. + +use super::{Error, Result, clip16, step_at}; +use craft_media::bitstream::{BitReader, BitWriter}; + +/// Samples per channel in a full block. +pub const BLOCK_SAMPLES: usize = 4096; + +/// The index adjustment for each magnitude, per code size. +fn adjust(bits: u32) -> &'static [i32] { + match bits { + 2 => &[-1, 2], + 3 => &[-1, -1, 2, 4], + 4 => &[-1, -1, -1, -1, 2, 4, 6, 8], + _ => &[-1, -1, -1, -1, -1, -1, -1, -1, 1, 2, 4, 6, 8, 10, 13, 16], + } +} + +#[derive(Clone, Copy)] +struct State { + predictor: i32, + index: i32, +} + +impl State { + fn apply(&mut self, code: u32, bits: u32) -> i16 { + let step = step_at(self.index); + let mag = code & ((1 << (bits - 1)) - 1); + let mut diff = step >> (bits - 1); + for k in 0..bits - 1 { + if mag & (1 << (bits - 2 - k)) != 0 { + diff += step >> k; + } + } + if code & (1 << (bits - 1)) != 0 { + diff = -diff; + } + self.predictor = clip16(self.predictor + diff); + self.index = (self.index + adjust(bits).get(mag as usize).copied().unwrap_or(0)).clamp(0, 88); + self.predictor as i16 + } + + fn encode(&mut self, sample: i16, bits: u32) -> u32 { + let step = step_at(self.index); + let mut diff = i32::from(sample) - self.predictor; + let mut code = 0u32; + if diff < 0 { + code = 1 << (bits - 1); + diff = -diff; + } + let mut s = step; + for k in 0..bits - 1 { + if diff >= s { + code |= 1 << (bits - 2 - k); + diff -= s; + } + s >>= 1; + } + self.apply(code, bits); + code + } +} + +/// Decode a stream. `channels` is 1 or 2; the code size comes from the stream's first two bits. +/// The result holds every sample up to the end of the data (a last block cut short decodes as +/// far as it goes). +pub fn decode(data: &[u8], channels: usize) -> Result> { + if !(1..=2).contains(&channels) { + return Err(Error::Malformed("Flash ADPCM has one or two channels")); + } + let mut r = BitReader::new(data); + let bits = r.read_bits(2).map_err(|_| Error::Malformed("empty stream"))? + 2; + let mut out = Vec::new(); + let header_bits = channels * 22; + while r.bits_left() >= header_bits { + let mut states = Vec::with_capacity(channels); + for _ in 0..channels { + let sample = r.read_bits(16).map_err(|_| Error::Malformed("truncated block"))? as u16 as i16; + let index = r.read_bits(6).map_err(|_| Error::Malformed("truncated block"))? as i32; + if index > 88 { + return Err(Error::Malformed("step index above 88")); + } + out.push(sample); + states.push(State { predictor: i32::from(sample), index }); + } + 'block: for _ in 1..BLOCK_SAMPLES { + if r.bits_left() < channels * (bits as usize) { + break 'block; + } + for st in states.iter_mut() { + match r.read_bits(bits) { + Ok(code) => out.push(st.apply(code, bits)), + Err(_) => break 'block, + } + } + } + } + Ok(out) +} + +/// Encode interleaved samples with `bits` (2 to 5) bits per sample. Blocks hold 4096 samples per +/// channel; the stream ends at a byte boundary. +pub fn encode(samples: &[i16], channels: usize, bits: u32) -> Result> { + if !(1..=2).contains(&channels) { + return Err(Error::InvalidInput("Flash ADPCM has one or two channels")); + } + if !(2..=5).contains(&bits) { + return Err(Error::InvalidInput("Flash ADPCM codes have 2 to 5 bits")); + } + if !samples.len().is_multiple_of(channels) { + return Err(Error::InvalidInput("the sample count is not a multiple of the channel count")); + } + let mut w = BitWriter::new(); + w.write_bits(bits - 2, 2); + for block in samples.chunks(BLOCK_SAMPLES * channels) { + let mut states = Vec::with_capacity(channels); + for ch in 0..channels { + let col: Vec = block.iter().skip(ch).step_by(channels).copied().collect(); + let first = col.first().copied().unwrap_or(0); + // the index whose first codes follow the signal most closely + let mut best = (i64::MAX, 0); + for index in 0..=63 { + let mut st = State { predictor: i32::from(first), index }; + let mut err = 0i64; + for &s in col.iter().skip(1).take(16) { + st.encode(s, bits); + err += (i64::from(s) - i64::from(st.predictor)).pow(2); + } + if err < best.0 { + best = (err, index); + } + } + w.write_bits(u32::from(first as u16), 16); + w.write_bits(best.1 as u32, 6); + states.push(State { predictor: i32::from(first), index: best.1 }); + } + for frame in block.chunks(channels).skip(1) { + for (st, &s) in states.iter_mut().zip(frame) { + w.write_bits(st.encode(s, bits), bits); + } + } + } + w.align_zero(); + Ok(w.finish()) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn settings_are_checked() { + assert!(encode(&[0], 3, 4).is_err()); + assert!(encode(&[0], 1, 1).is_err()); + assert!(encode(&[0], 1, 6).is_err()); + assert!(decode(&[], 1).is_err()); + assert!(decode(&[0], 0).is_err()); + } +} diff --git a/crates/audio/src/adpcm/yamaha.rs b/crates/audio/src/adpcm/yamaha.rs new file mode 100644 index 000000000..22ea0e77f --- /dev/null +++ b/crates/audio/src/adpcm/yamaha.rs @@ -0,0 +1,113 @@ +//! Yamaha ADPCM (the ADPCM-B of the YM2608 and the AICA): a raw stream of 4-bit codes, no header. +//! +//! Each channel starts at predictor 0 and step 127. A code is a sign bit and three magnitude bits; +//! the sample moves by `step * [1, 3, 5, 7, 9, 11, 13, 15][magnitude] / 8` (negative when the sign +//! is set) and the step is multiplied by `[230, 230, 230, 230, 307, 409, 512, 614][magnitude] / 256`, +//! kept within 127 and 24576. One channel: the low nibble of a byte is the first sample. Two +//! channels: the low nibble is the left channel and the high nibble the right one of the same +//! frame. + +use super::{Error, Result, clip16}; + +const SCALE: [i32; 8] = [230, 230, 230, 230, 307, 409, 512, 614]; + +#[derive(Clone, Copy)] +struct State { + predictor: i32, + step: i32, +} + +impl State { + fn new() -> State { + State { predictor: 0, step: 127 } + } + + fn apply(&mut self, nibble: u8) -> i16 { + let m = usize::from(nibble & 7); + let diff = self.step * (2 * m as i32 + 1) / 8; + self.predictor = clip16(self.predictor + if nibble & 8 != 0 { -diff } else { diff }); + self.step = ((self.step * SCALE.get(m).copied().unwrap_or(256)) >> 8).clamp(127, 24_576); + self.predictor as i16 + } + + fn encode(&mut self, sample: i16) -> u8 { + let err = i32::from(sample) - self.predictor; + let m = (err.abs() * 8 / self.step / 2).clamp(0, 7); + // the magnitude whose reconstruction (2m + 1) * step / 8 is nearest + let mut best = (i32::MAX, 0u8); + for cand in [m - 1, m, m + 1] { + let c = cand.clamp(0, 7); + let recon = self.step * (2 * c + 1) / 8; + let e = (err.abs() - recon).abs(); + if e < best.0 { + best = (e, c as u8); + } + } + let nibble = best.1 | if err < 0 { 8 } else { 0 }; + self.apply(nibble); + nibble + } +} + +/// Decode a stream of `channels` (1 or 2) interleaved channels. +pub fn decode(data: &[u8], channels: usize) -> Result> { + if !(1..=2).contains(&channels) { + return Err(Error::Malformed("Yamaha ADPCM has one or two channels")); + } + let mut states = vec![State::new(); channels]; + let mut out = Vec::with_capacity(data.len() * 2); + let mut t = 0usize; + for byte in data { + for nibble in [byte & 0xF, byte >> 4] { + if let Some(st) = states.get_mut(t % channels) { + out.push(st.apply(nibble)); + } + t += 1; + } + } + Ok(out) +} + +/// Encode interleaved samples. With two channels the frame count must be whole bytes, which it +/// always is; with one channel an odd count is padded with a copy of the last sample. +pub fn encode(samples: &[i16], channels: usize) -> Result> { + if !(1..=2).contains(&channels) { + return Err(Error::InvalidInput("Yamaha ADPCM has one or two channels")); + } + if !samples.len().is_multiple_of(channels) { + return Err(Error::InvalidInput("the sample count is not a multiple of the channel count")); + } + let mut states = vec![State::new(); channels]; + let mut out = Vec::with_capacity(samples.len().div_ceil(2)); + let mut t = 0usize; + let mut padded = samples.to_vec(); + if padded.len() % 2 == 1 { + padded.push(padded.last().copied().unwrap_or(0)); + } + for pair in padded.chunks(2) { + let mut byte = 0u8; + for (half, &s) in pair.iter().enumerate() { + let code = match states.get_mut(t % channels) { + Some(st) => st.encode(s), + None => 0, + }; + byte |= code << (4 * half); + t += 1; + } + out.push(byte); + } + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn channel_count_is_checked() { + assert!(decode(&[0], 0).is_err()); + assert!(decode(&[0], 3).is_err()); + assert!(encode(&[0], 3).is_err()); + assert!(encode(&[0, 0, 0], 2).is_err()); + } +} diff --git a/crates/audio/src/g722.rs b/crates/audio/src/g722.rs new file mode 100644 index 000000000..030b87d14 --- /dev/null +++ b/crates/audio/src/g722.rs @@ -0,0 +1,693 @@ +//! ITU-T Recommendation G.722 wideband audio coding (64 kbit/s). +//! +//! Pure safe Rust clean-room implementation of the G.722 sub-band adaptive differential +//! pulse code modulation (SB-ADPCM) speech and audio codec. +//! +//! Input audio is 16 kHz 16-bit linear PCM. An analysis Quadrature Mirror Filter (QMF) splits +//! the 16 kHz audio into a lower sub-band (0–4 kHz) and a higher sub-band (4–8 kHz), each +//! sampled at 8 kHz. The lower sub-band is encoded at 48 kbit/s (6 bits/sample) and the higher +//! sub-band at 16 kbit/s (2 bits/sample), multiplexed into an 8-bit octet per 8 kHz cycle +//! (64 kbit/s total stream rate). +//! +//! On decoding, inverse adaptive quantizers reconstruct each sub-band signal, and a synthesis +//! QMF interpolates and combines them back to 16 kHz 16-bit linear PCM. + +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] + +/// Maximum allowed channels for multi-channel processing. +pub const MAX_CHANNELS: usize = 8; + +/// Maximum input byte buffer bound to prevent memory exhaustion on hostile inputs (64 MiB). +pub const MAX_INPUT_BYTES: usize = 64 * 1024 * 1024; + +/// Maximum input sample count bound (128 million samples). +pub const MAX_SAMPLES: usize = 128 * 1024 * 1024; + +/// Error conditions encountered during G.722 encoding or decoding. +#[derive(Debug, thiserror::Error, PartialEq, Eq)] +pub enum Error { + /// The channel count is invalid. + #[error("invalid channel count: {0} (must be 1..={MAX_CHANNELS})")] + InvalidChannels(usize), + + /// The input size exceeds safety bounds. + #[error("input exceeds maximum size bound")] + InputTooLarge, + + /// Encoding requires an even number of samples per channel (16 kHz sample pairs). + #[error("odd number of samples: {0} (G.722 encodes pairs of 16 kHz samples)")] + OddSampleCount(usize), + + /// System allocation failed when reserving buffer memory. + #[error("allocation failed")] + AllocationFailed, +} + +// --------------------------------------------------------------------------- +// Specification Tables from ITU-T Recommendation G.722 +// --------------------------------------------------------------------------- + +/// 24-tap QMF filter coefficients scaled by 2^13 (Table 11/G.722). +const H: [i16; 24] = [3, -11, -11, 53, 12, -156, 32, 362, -210, -805, 951, 3876, 3876, 951, -805, -210, 362, 32, -156, 12, 53, -11, -11, 3]; + +/// Lower sub-band 60-level inverse quantizer reconstruction table QQ6 (Table 14/G.722). +const QQ6: [i16; 31] = [ + 0, 17, 54, 91, 130, 170, 211, 254, 300, 347, 396, 447, 501, 558, 618, 682, 750, 822, 899, 982, 1072, 1170, 1279, 1399, 1535, 1689, 1873, 2088, + 2376, 2738, 3101, +]; + +/// Lower sub-band quantizer decision levels Q6 (Table 14/G.722). +const Q6: [i16; 30] = [ + 0, 35, 72, 110, 150, 190, 233, 276, 323, 370, 422, 473, 530, 587, 650, 714, 786, 858, 940, 1023, 1121, 1219, 1339, 1458, 1612, 1765, 1980, 2195, + 2557, 2919, +]; + +/// Lower sub-band 15-level inverse quantizer reconstruction table QQ4 (Table 14/G.722). +const QQ4: [i16; 8] = [0, 150, 323, 530, 786, 1121, 1612, 2557]; + +/// Lower sub-band logarithmic scale factor multipliers WL (Table 14/G.722). +const WL: [i16; 8] = [-60, -30, 58, 172, 334, 538, 1198, 3042]; + +/// Higher sub-band 4-level inverse quantizer reconstruction table QQ2 (Table 14/G.722). +const QQ2: [i16; 3] = [0, 202, 926]; + +/// Higher sub-band logarithmic scale factor multipliers WH (Table 14/G.722). +const WH: [i16; 3] = [0, -214, 798]; + +/// 32-entry inverse logarithmic scale table ILB (Table 15/G.722). +const ILB: [i32; 32] = [ + 2048, 2093, 2139, 2186, 2233, 2282, 2332, 2383, 2435, 2489, 2543, 2599, 2656, 2714, 2774, 2834, 2896, 2960, 3025, 3091, 3158, 3228, 3298, 3371, + 3444, 3520, 3597, 3676, 3756, 3838, 3922, 4008, +]; + +/// Table 17/G.722: 4-bit codeword (RIL = IL >> 2) to (SIL, IL4). +const IL4_MAP: [(i16, usize); 16] = + [(0, 0), (-1, 7), (-1, 6), (-1, 5), (-1, 4), (-1, 3), (-1, 2), (-1, 1), (0, 7), (0, 6), (0, 5), (0, 4), (0, 3), (0, 2), (0, 1), (0, 0)]; + +/// Table 21/G.722: 2-bit codeword IH to (SIH, IH2). +const IH2_MAP: [(i16, usize); 4] = [(-1, 2), (-1, 1), (0, 2), (0, 1)]; + +#[inline] +fn mult(a: i16, b: i16) -> i16 { + (((a as i32) * (b as i32)) >> 15) as i16 +} + +#[inline] +fn scalel(nbpl: i32) -> i32 { + let wd1 = ((nbpl >> 6) & 31) as usize; + let wd2 = nbpl >> 11; + let shift = 8 - wd2; + let wd3 = if shift >= 0 { ILB[wd1] >> shift } else { ILB[wd1] << (-shift) }; + wd3 << 2 +} + +#[inline] +fn scaleh(nbph: i32) -> i32 { + let wd1 = ((nbph >> 6) & 31) as usize; + let wd2 = nbph >> 11; + let shift = 10 - wd2; + let wd3 = if shift >= 0 { ILB[wd1] >> shift } else { ILB[wd1] << (-shift) }; + wd3 << 2 +} + +// --------------------------------------------------------------------------- +// Sub-band ADPCM State (Pole/Zero Predictors & Adaptations) +// --------------------------------------------------------------------------- + +#[derive(Debug, Clone)] +struct BandState { + s: i16, + sp: i16, + sz: i16, + d: [i16; 7], + r: [i16; 3], + p: [i16; 3], + a: [i16; 3], + b: [i16; 7], + nb: i32, + det: i32, +} + +impl BandState { + fn new(is_lower: bool) -> Self { + Self { s: 0, sp: 0, sz: 0, d: [0; 7], r: [0; 3], p: [0; 3], a: [0; 3], b: [0; 7], nb: 0, det: if is_lower { 32 } else { 8 } } + } + + fn reset(&mut self, is_lower: bool) { + self.s = 0; + self.sp = 0; + self.sz = 0; + self.d = [0; 7]; + self.r = [0; 3]; + self.p = [0; 3]; + self.a = [0; 3]; + self.b = [0; 7]; + self.nb = 0; + self.det = if is_lower { 32 } else { 8 }; + } + + fn update_predictor(&mut self, d: i16, p_sig: i16, r_sig: i16) { + // UPZERO: update 6th order zero predictor coefficients + let wd1: i16 = if d != 0 { 128 } else { 0 }; + let sg0: i16 = if d < 0 { -1 } else { 0 }; + for i in 1..=6 { + let sgi = if self.d[i] < 0 { -1 } else { 0 }; + let wd2 = if sg0 == sgi { wd1 } else { wd1.saturating_neg() }; + let wd3 = mult(self.b[i], 32640); + self.b[i] = wd2.saturating_add(wd3); + } + + // UPPOL2: update 2nd pole coefficient + let sg0 = if p_sig < 0 { -1 } else { 0 }; + let sg1 = if self.p[1] < 0 { -1 } else { 0 }; + let sg2 = if self.p[2] < 0 { -1 } else { 0 }; + let wd1 = self.a[1].saturating_add(self.a[1]).saturating_add(self.a[1].saturating_add(self.a[1])); + let wd2 = if sg0 == sg1 { wd1.saturating_neg() } else { wd1 } >> 7; + let wd3: i16 = if sg0 == sg2 { 128 } else { -128 }; + let wd4 = wd2.saturating_add(wd3); + let wd5 = mult(self.a[2], 32512); + let apl2 = wd4.saturating_add(wd5).clamp(-12288, 12288); + + // UPPOL1: update 1st pole coefficient + let wd1: i16 = if sg0 == sg1 { 192 } else { -192 }; + let wd2 = mult(self.a[1], 32640); + let apl1 = wd1.saturating_add(wd2); + let wd3 = 15360 - apl2; + let apl1 = apl1.clamp(-wd3, wd3); + + self.a[1] = apl1; + self.a[2] = apl2; + + // Shift history delay lines + for i in (2..=6).rev() { + self.d[i] = self.d[i - 1]; + } + self.d[1] = d; + + self.p[2] = self.p[1]; + self.p[1] = p_sig; + + self.r[2] = self.r[1]; + self.r[1] = r_sig; + + // FILTEZ: compute zero section output + let mut sz: i16 = 0; + for i in (1..=6).rev() { + let part = mult(self.b[i], self.d[i].saturating_add(self.d[i])); + sz = sz.saturating_add(part); + } + self.sz = sz; + + // FILTEP: compute pole section output + let sp1 = mult(self.a[1], self.r[1].saturating_add(self.r[1])); + let sp2 = mult(self.a[2], self.r[2].saturating_add(self.r[2])); + self.sp = sp1.saturating_add(sp2); + + // PREDIC: compute full predictor output value + self.s = self.sp.saturating_add(self.sz); + } +} + +// --------------------------------------------------------------------------- +// Quadrature Mirror Filters (QMF) +// --------------------------------------------------------------------------- + +/// Analysis QMF (transmit filter bank): splits pairs of 16 kHz samples into lower and higher sub-bands. +#[derive(Debug, Clone, Default)] +pub struct QmfTx { + x: [i16; 24], +} + +impl QmfTx { + /// Create a new analysis QMF filter. + pub fn new() -> Self { + Self { x: [0; 24] } + } + + /// Reset filter history. + pub fn reset(&mut self) { + self.x = [0; 24]; + } + + /// Process a pair of 16 kHz input samples `(s0, s1)` into `(xl, xh)`. + pub fn filter(&mut self, s0: i16, s1: i16) -> (i16, i16) { + for i in (2..24).rev() { + self.x[i] = self.x[i - 2]; + } + self.x[0] = s1 >> 1; + self.x[1] = s0 >> 1; + + let mut xa: i32 = 0; + let mut xb: i32 = 0; + for i in 0..12 { + xa = xa.saturating_add((self.x[2 * i] as i32) * (H[2 * i] as i32)); + xb = xb.saturating_add((self.x[2 * i + 1] as i32) * (H[2 * i + 1] as i32)); + } + + let xl = ((xa.saturating_add(xb)) >> 13).clamp(-16384, 16383) as i16; + let xh = ((xa.saturating_sub(xb)) >> 13).clamp(-16384, 16383) as i16; + (xl, xh) + } +} + +/// Synthesis QMF (receive filter bank): synthesizes lower and higher sub-band signals into 16 kHz output. +#[derive(Debug, Clone, Default)] +pub struct QmfRx { + xd: [i16; 12], + xs: [i16; 12], +} + +impl QmfRx { + /// Create a new synthesis QMF filter. + pub fn new() -> Self { + Self { xd: [0; 12], xs: [0; 12] } + } + + /// Reset filter history. + pub fn reset(&mut self) { + self.xd = [0; 12]; + self.xs = [0; 12]; + } + + /// Reconstruct a pair of 16 kHz output samples from sub-band samples `(rl, rh)`. + pub fn filter(&mut self, rl: i16, rh: i16) -> (i16, i16) { + let xd_curr = rl.saturating_sub(rh); + let xs_curr = rl.saturating_add(rh); + + for i in (1..12).rev() { + self.xd[i] = self.xd[i - 1]; + self.xs[i] = self.xs[i - 1]; + } + self.xd[0] = xd_curr; + self.xs[0] = xs_curr; + + let mut wd_c: i32 = 0; + let mut wd_d: i32 = 0; + for i in 0..12 { + wd_c = wd_c.saturating_add((self.xd[i] as i32) * (H[2 * i] as i32)); + wd_d = wd_d.saturating_add((self.xs[i] as i32) * (H[2 * i + 1] as i32)); + } + + let xout1 = (wd_c >> 12).clamp(-16384, 16383); + let xout2 = (wd_d >> 12).clamp(-16384, 16383); + + let s0 = (xout1 << 1).clamp(-32768, 32767) as i16; + let s1 = (xout2 << 1).clamp(-32768, 32767) as i16; + (s0, s1) + } +} + +// --------------------------------------------------------------------------- +// G.722 Decoder & Encoder +// --------------------------------------------------------------------------- + +/// ITU-T G.722 64 kbit/s single-channel decoder. +#[derive(Debug, Clone)] +pub struct Decoder { + band_l: BandState, + band_h: BandState, + qmf: QmfRx, +} + +impl Default for Decoder { + fn default() -> Self { + Self::new() + } +} + +impl Decoder { + /// Create a new G.722 decoder initialized to standard reset state. + pub fn new() -> Self { + Self { band_l: BandState::new(true), band_h: BandState::new(false), qmf: QmfRx::new() } + } + + /// Reset decoder internal state. + pub fn reset(&mut self) { + self.band_l.reset(true); + self.band_h.reset(false); + self.qmf.reset(); + } + + /// Decode a single 8-bit octet into two 16 kHz 16-bit PCM samples. + pub fn decode_octet(&mut self, octet: u8) -> (i16, i16) { + let ih = ((octet >> 6) & 3) as usize; + let il = (octet & 0x3F) as usize; + + // INVQBL: 6-bit lower sub-band inverse quantization + let (sil6, il6) = table18_lookup(il); + let wd1 = (QQ6[il6] as i32) << 3; + let wd2 = if sil6 == 0 { wd1 } else { -wd1 }; + let dl = mult(self.band_l.det as i16, wd2 as i16); + let yl = self.band_l.s.saturating_add(dl); + let rl = yl.clamp(-16384, 16383); + + // INVQAL: lower sub-band predictor update (4-bit feedback path) + let ril = il >> 2; + let (sil4, il4) = IL4_MAP[ril & 0x0F]; + let wd1 = (QQ4[il4] as i32) << 3; + let wd2 = if sil4 == 0 { wd1 } else { -wd1 }; + let dlt = mult(self.band_l.det as i16, wd2 as i16); + let plt = dlt.saturating_add(self.band_l.sz); + let rlt = self.band_l.s.saturating_add(dlt); + + // Lower sub-band scale factor adaptation (LOGSCL) + let wd_scale = mult(self.band_l.nb as i16, 32512); + let nbpl = (wd_scale as i32 + WL[il4] as i32).clamp(0, 18432); + self.band_l.nb = nbpl; + self.band_l.det = scalel(nbpl); + self.band_l.update_predictor(dlt, plt, rlt); + + // INVQAH: higher sub-band inverse quantization + let (sih_dec, ih2) = IH2_MAP[ih & 0x03]; + let wd1 = (QQ2[ih2] as i32) << 3; + let wd2 = if sih_dec == 0 { wd1 } else { -wd1 }; + let dh = mult(self.band_h.det as i16, wd2 as i16); + let yh = self.band_h.s.saturating_add(dh); + let rh = yh.clamp(-16384, 16383); + + // Higher sub-band scale factor adaptation (LOGSCH) + let wd_scale = mult(self.band_h.nb as i16, 32512); + let nbph = (wd_scale as i32 + WH[ih2] as i32).clamp(0, 22528); + self.band_h.nb = nbph; + self.band_h.det = scaleh(nbph); + let ph = dh.saturating_add(self.band_h.sz); + self.band_h.update_predictor(dh, ph, yh); + + // Synthesis QMF + self.qmf.filter(rl, rh) + } + + /// Decode G.722 octets into 16 kHz 16-bit linear PCM samples, appending to `dst`. + pub fn decode(&mut self, src: &[u8], dst: &mut Vec) -> Result<(), Error> { + if src.len() > MAX_INPUT_BYTES { + return Err(Error::InputTooLarge); + } + let needed_samples = src.len().saturating_mul(2); + if needed_samples > MAX_SAMPLES { + return Err(Error::InputTooLarge); + } + dst.try_reserve(needed_samples).map_err(|_| Error::AllocationFailed)?; + for &octet in src { + let (s0, s1) = self.decode_octet(octet); + dst.push(s0); + dst.push(s1); + } + Ok(()) + } +} + +/// ITU-T G.722 64 kbit/s single-channel encoder. +#[derive(Debug, Clone)] +pub struct Encoder { + qmf: QmfTx, + band_l: BandState, + band_h: BandState, +} + +impl Default for Encoder { + fn default() -> Self { + Self::new() + } +} + +impl Encoder { + /// Create a new G.722 encoder initialized to standard reset state. + pub fn new() -> Self { + Self { qmf: QmfTx::new(), band_l: BandState::new(true), band_h: BandState::new(false) } + } + + /// Reset encoder internal state. + pub fn reset(&mut self) { + self.qmf.reset(); + self.band_l.reset(true); + self.band_h.reset(false); + } + + /// Encode a pair of 16 kHz 16-bit PCM samples into one 8-bit G.722 octet. + pub fn encode_sample_pair(&mut self, s0: i16, s1: i16) -> u8 { + // Analysis QMF + let (xl, xh) = self.qmf.filter(s0, s1); + + // Lower sub-band quantizer (QUANTL) + let el = xl.saturating_sub(self.band_l.s); + let sil = if el < 0 { -1 } else { 0 }; + let wd = if sil == 0 { el } else { 32767 - (el & 32767) }; + let mut mil: usize = 30; + for (k, &thresh_q) in Q6.iter().enumerate().skip(1) { + let thresh = (((thresh_q as i32) << 3) * self.band_l.det) >> 15; + if (wd as i32) < thresh { + mil = k; + break; + } + } + + // Table 16 conversion to IL + let il: u8 = if sil == 0 { + (62 - mil) as u8 + } else if mil == 1 { + 63 + } else if mil == 2 { + 62 + } else { + (34 - mil) as u8 + }; + + // Lower sub-band feedback and predictor update (INVQAL) + let ril = (il >> 2) as usize; + let (sil4, il4) = IL4_MAP[ril & 0x0F]; + let wd1 = (QQ4[il4] as i32) << 3; + let wd2 = if sil4 == 0 { wd1 } else { -wd1 }; + let dlt = mult(self.band_l.det as i16, wd2 as i16); + let plt = dlt.saturating_add(self.band_l.sz); + let rlt = self.band_l.s.saturating_add(dlt); + + // Lower sub-band scale factor adaptation (LOGSCL) + let wd_scale = mult(self.band_l.nb as i16, 32512); + let nbpl = (wd_scale as i32 + WL[il4] as i32).clamp(0, 18432); + self.band_l.nb = nbpl; + self.band_l.det = scalel(nbpl); + self.band_l.update_predictor(dlt, plt, rlt); + + // Higher sub-band quantizer (QUANTH) + let eh = xh.saturating_sub(self.band_h.s); + let sih = if eh < 0 { -1 } else { 0 }; + let wd = if sih == 0 { eh } else { 32767 - (eh & 32767) }; + let thresh = ((564 << 3) * self.band_h.det) >> 15; + let mih = if (wd as i32) < thresh { 1 } else { 2 }; + + // Table 20 conversion to IH + let ih: u8 = if sih == -1 { + if mih == 2 { 0 } else { 1 } + } else if mih == 1 { + 3 + } else { + 2 + }; + + // Higher sub-band feedback and predictor update (INVQAH) + let (sih_dec, ih2) = IH2_MAP[ih as usize]; + let wd1 = (QQ2[ih2] as i32) << 3; + let wd2 = if sih_dec == 0 { wd1 } else { -wd1 }; + let dh = mult(self.band_h.det as i16, wd2 as i16); + let yh = self.band_h.s.saturating_add(dh); + + // Higher sub-band scale factor adaptation (LOGSCH) + let wd_scale = mult(self.band_h.nb as i16, 32512); + let nbph = (wd_scale as i32 + WH[ih2] as i32).clamp(0, 22528); + self.band_h.nb = nbph; + self.band_h.det = scaleh(nbph); + let ph = dh.saturating_add(self.band_h.sz); + self.band_h.update_predictor(dh, ph, yh); + + // Multiplexer (MUX) + (ih << 6) | (il & 0x3F) + } + + /// Encode 16 kHz 16-bit linear PCM samples into G.722 octets, appending to `dst`. + pub fn encode(&mut self, src: &[i16], dst: &mut Vec) -> Result<(), Error> { + if !src.len().is_multiple_of(2) { + return Err(Error::OddSampleCount(src.len())); + } + if src.len() > MAX_SAMPLES { + return Err(Error::InputTooLarge); + } + let needed_octets = src.len() / 2; + dst.try_reserve(needed_octets).map_err(|_| Error::AllocationFailed)?; + for &[s0, s1] in src.as_chunks::<2>().0 { + let octet = self.encode_sample_pair(s0, s1); + dst.push(octet); + } + Ok(()) + } +} + +// --------------------------------------------------------------------------- +// Helpers +// --------------------------------------------------------------------------- + +#[inline] +fn table18_lookup(il: usize) -> (i16, usize) { + let il = il & 0x3F; + if (4..=31).contains(&il) { + (-1, 34 - il) + } else if il == 62 { + (-1, 2) + } else if il == 63 { + (-1, 1) + } else if (32..=61).contains(&il) { + (0, 62 - il) + } else { + // Transmission error fallbacks (0..=3) + (-1, 1) + } +} + +// --------------------------------------------------------------------------- +// Public Top-Level Functions +// --------------------------------------------------------------------------- + +/// Decode a mono 64 kbit/s G.722 stream into 16 kHz 16-bit linear PCM samples. +pub fn decode(bytes: &[u8]) -> Result, Error> { + let mut decoder = Decoder::new(); + let mut out = Vec::new(); + decoder.decode(bytes, &mut out)?; + Ok(out) +} + +/// Encode mono 16 kHz 16-bit linear PCM samples into a 64 kbit/s G.722 stream. +pub fn encode(samples: &[i16]) -> Result, Error> { + let mut encoder = Encoder::new(); + let mut out = Vec::new(); + encoder.encode(samples, &mut out)?; + Ok(out) +} + +/// Decode an interleaved multi-channel G.722 stream into interleaved 16 kHz 16-bit PCM samples. +pub fn decode_interleaved(bytes: &[u8], channels: usize) -> Result, Error> { + if channels == 0 || channels > MAX_CHANNELS { + return Err(Error::InvalidChannels(channels)); + } + if channels == 1 { + return decode(bytes); + } + if bytes.len() > MAX_INPUT_BYTES { + return Err(Error::InputTooLarge); + } + let frames = bytes.len() / channels; + let mut decoders: Vec = Vec::with_capacity(channels); + for _ in 0..channels { + decoders.push(Decoder::new()); + } + let total_samples = frames.saturating_mul(channels).saturating_mul(2); + let mut out = Vec::new(); + out.try_reserve(total_samples).map_err(|_| Error::AllocationFailed)?; + + // Each frame has `channels` bytes. Decode each byte with its channel's decoder, + // producing sample 0 for each channel, then sample 1 for each channel. + for chunk in bytes.chunks_exact(channels) { + let mut pairs = [(0i16, 0i16); MAX_CHANNELS]; + for (ch, &b) in chunk.iter().enumerate() { + pairs[ch] = decoders[ch].decode_octet(b); + } + for pair in pairs.iter().take(channels) { + out.push(pair.0); + } + for pair in pairs.iter().take(channels) { + out.push(pair.1); + } + } + Ok(out) +} + +/// Encode interleaved 16 kHz 16-bit PCM samples into an interleaved multi-channel G.722 stream. +pub fn encode_interleaved(samples: &[i16], channels: usize) -> Result, Error> { + if channels == 0 || channels > MAX_CHANNELS { + return Err(Error::InvalidChannels(channels)); + } + if channels == 1 { + return encode(samples); + } + if samples.len() > MAX_SAMPLES { + return Err(Error::InputTooLarge); + } + let frame_len = channels.saturating_mul(2); + if !samples.len().is_multiple_of(frame_len) { + return Err(Error::OddSampleCount(samples.len())); + } + let frames = samples.len() / frame_len; + let mut encoders: Vec = Vec::with_capacity(channels); + for _ in 0..channels { + encoders.push(Encoder::new()); + } + let total_bytes = frames.saturating_mul(channels); + let mut out = Vec::new(); + out.try_reserve(total_bytes).map_err(|_| Error::AllocationFailed)?; + + for chunk in samples.chunks_exact(frame_len) { + for ch in 0..channels { + let s0 = chunk[ch]; + let s1 = chunk[ch + channels]; + out.push(encoders[ch].encode_sample_pair(s0, s1)); + } + } + Ok(out) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn reject_invalid_channels() { + assert_eq!(decode_interleaved(&[0; 4], 0), Err(Error::InvalidChannels(0))); + assert_eq!(decode_interleaved(&[0; 4], 9), Err(Error::InvalidChannels(9))); + assert_eq!(encode_interleaved(&[0; 4], 0), Err(Error::InvalidChannels(0))); + assert_eq!(encode_interleaved(&[0; 4], 9), Err(Error::InvalidChannels(9))); + } + + #[test] + fn reject_odd_sample_count() { + assert_eq!(encode(&[0; 3]), Err(Error::OddSampleCount(3))); + assert_eq!(encode_interleaved(&[0; 5], 2), Err(Error::OddSampleCount(5))); + } + + #[test] + fn roundtrip_silence() { + let input = vec![0i16; 320]; + let encoded = encode(&input).expect("encode silence"); + assert_eq!(encoded.len(), 160); + let decoded = decode(&encoded).expect("decode silence"); + assert_eq!(decoded.len(), 320); + for &s in &decoded[40..] { + assert!(s.abs() <= 6, "silence sample too large: {s}"); + } + } + + #[test] + fn multichannel_stereo_roundtrip() { + let mut stereo_pcm = Vec::new(); + for i in 0..400 { + stereo_pcm.push((i * 10) as i16); + stereo_pcm.push((-i * 10) as i16); + } + let enc = encode_interleaved(&stereo_pcm, 2).expect("encode stereo"); + assert_eq!(enc.len(), 400); + let dec = decode_interleaved(&enc, 2).expect("decode stereo"); + assert_eq!(dec.len(), 800); + } + + #[test] + fn hostile_input_does_not_panic() { + let garbage = [0xFF, 0x00, 0x55, 0xAA, 0x12, 0x34, 0x7F, 0x80]; + let dec = decode(&garbage).expect("decode garbage"); + assert_eq!(dec.len(), 16); + } + + #[test] + fn uppol2_overflow_does_not_panic() { + let mut state = BandState::new(true); + state.a[1] = -8192; + state.p = [0, 0, 0]; + state.update_predictor(0, 0, 0); + } +} diff --git a/crates/audio/src/g726.rs b/crates/audio/src/g726.rs new file mode 100644 index 000000000..6ac02359d --- /dev/null +++ b/crates/audio/src/g726.rs @@ -0,0 +1,996 @@ +//! ITU-T Recommendation G.726 ADPCM speech codec (16, 24, 32, 40 kbit/s). +//! +//! Clean-room implementation based on ITU-T Recommendation G.726 (12/1990) +//! "40, 32, 24, 16 kbit/s Adaptive Differential Pulse Code Modulation (ADPCM)". +//! +//! Provides encoding from 8 kHz 16-bit linear PCM to G.726 bitstreams, and decoding +//! from G.726 bitstreams to 8 kHz 16-bit linear PCM. +//! +//! Supports both standard big-endian bit packing (network order / RFC 3551) and +//! little-endian bit packing (RIFF WAV / AVID format tag 0x0045 / 0x0014). + +const MAX_CHANNELS: usize = 8; +const MAX_INPUT_BYTES: usize = 64 * 1024 * 1024; +const MAX_SAMPLES: usize = 64 * 1024 * 1024; + +/// Bit rate for G.726 ADPCM. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum BitRate { + /// 16 kbit/s (2 bits per sample). + Rate16k, + /// 24 kbit/s (3 bits per sample). + Rate24k, + /// 32 kbit/s (4 bits per sample). + Rate32k, + /// 40 kbit/s (5 bits per sample). + Rate40k, +} + +impl BitRate { + /// Number of bits per code (sample). + #[inline] + #[must_use] + pub const fn code_size(self) -> usize { + match self { + Self::Rate16k => 2, + Self::Rate24k => 3, + Self::Rate32k => 4, + Self::Rate40k => 5, + } + } + + /// Bit rate in bits per second. + #[inline] + #[must_use] + pub const fn bit_rate_bps(self) -> u32 { + match self { + Self::Rate16k => 16_000, + Self::Rate24k => 24_000, + Self::Rate32k => 32_000, + Self::Rate40k => 40_000, + } + } +} + +/// Bit packing order within bytes. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)] +pub enum BitPacking { + /// Big-endian packing: MSB to LSB (standard RFC 3551 / network order). + #[default] + BigEndian, + /// Little-endian packing: LSB to MSB (WAV / RIFF order). + LittleEndian, +} + +/// Errors returned by G.726 operations. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum Error { + /// Channel count must be between 1 and 8. + #[error("unsupported channel count: {0} (must be 1..=8)")] + InvalidChannels(usize), + /// Input exceeds safe maximum memory bound. + #[error("input exceeds safe maximum processing limit")] + InputTooLarge, + /// Output buffer allocation failed. + #[error("memory allocation failed")] + AllocationFailed, +} + +// --------------------------------------------------------------------------- +// G.726 Tables +// --------------------------------------------------------------------------- + +// Table 11..14 (I -> DQS, DQLN) +static OUT_16: [(u8, u16); 4] = [(0, 116), (0, 365), (1, 365), (1, 116)]; + +static OUT_24: [(u8, u16); 8] = [(0, 2048), (0, 135), (0, 273), (0, 373), (1, 373), (1, 273), (1, 135), (1, 2048)]; + +static OUT_32: [(u8, u16); 16] = [ + (0, 2048), + (0, 4), + (0, 135), + (0, 213), + (0, 273), + (0, 323), + (0, 373), + (0, 425), + (1, 425), + (1, 373), + (1, 323), + (1, 273), + (1, 213), + (1, 135), + (1, 4), + (1, 2048), +]; + +static OUT_40: [(u8, u16); 32] = [ + (0, 2048), + (0, 4030), + (0, 28), + (0, 104), + (0, 169), + (0, 224), + (0, 274), + (0, 318), + (0, 358), + (0, 395), + (0, 429), + (0, 459), + (0, 488), + (0, 514), + (0, 539), + (0, 566), + (1, 566), + (1, 539), + (1, 514), + (1, 488), + (1, 459), + (1, 429), + (1, 395), + (1, 358), + (1, 318), + (1, 274), + (1, 224), + (1, 169), + (1, 104), + (1, 28), + (1, 4030), + (1, 2048), +]; + +// FUNCTW: scale factor multipliers WI +static WI_16: [u16; 2] = [4074, 439]; +static WI_24: [u16; 4] = [4092, 30, 137, 582]; +static WI_32: [u16; 8] = [4084, 18, 41, 64, 112, 198, 355, 1122]; +static WI_40: [u16; 16] = [14, 14, 24, 39, 40, 41, 58, 100, 141, 179, 219, 280, 358, 440, 529, 696]; + +#[inline] +fn get_wi(rate: BitRate, code: u8) -> u16 { + match rate { + BitRate::Rate16k => { + let im = if (code >> 1) == 0 { (code & 1) as usize } else { ((3 - code) & 1) as usize }; + WI_16[im] + } + BitRate::Rate24k => { + let im = if (code >> 2) == 0 { (code & 3) as usize } else { ((7 - code) & 3) as usize }; + WI_24[im] + } + BitRate::Rate32k => { + let im = if (code >> 3) == 0 { (code & 7) as usize } else { ((15 - code) & 7) as usize }; + WI_32[im] + } + BitRate::Rate40k => { + let im = if (code >> 4) == 0 { (code & 15) as usize } else { ((31 - code) & 15) as usize }; + WI_40[im] + } + } +} + +#[inline] +fn get_fi(rate: BitRate, code: u8) -> u8 { + match rate { + BitRate::Rate16k => { + let im = if (code >> 1) == 0 { code & 1 } else { (3 - code) & 1 }; + if im == 1 { 7 } else { 0 } + } + BitRate::Rate24k => { + let im = if (code >> 2) == 0 { code & 3 } else { (7 - code) & 3 }; + match im { + 0 => 0, + 1 => 1, + 2 => 2, + _ => 7, + } + } + BitRate::Rate32k => { + let im = if (code >> 3) == 0 { code & 7 } else { (15 - code) & 7 }; + if im <= 2 { + 0 + } else if im <= 5 { + 1 + } else if im == 6 { + 3 + } else { + 7 + } + } + BitRate::Rate40k => { + let im = if (code >> 4) == 0 { code & 15 } else { (31 - code) & 15 }; + if im <= 4 { + 0 + } else if im <= 9 { + 1 + } else { + match im { + 10 => 2, + 11 => 3, + 12 => 4, + 13 => 5, + _ => 6, + } + } + } + } +} + +// Quantizer decision intervals (lo, hi, positive_code, negative_code) +static THRESH_16: [(i32, i32, u8, u8); 1] = [(261, 2047, 1, 2)]; + +static THRESH_24: [(i32, i32, u8, u8); 3] = [(331, 2047, 3, 4), (218, 330, 2, 5), (8, 217, 1, 6)]; + +static THRESH_32: [(i32, i32, u8, u8); 8] = [ + (400, 2047, 7, 8), + (349, 399, 6, 9), + (300, 348, 5, 10), + (246, 299, 4, 11), + (178, 245, 3, 12), + (80, 177, 2, 13), + (0, 79, 1, 14), + (3972, 4095, 1, 14), +]; + +static THRESH_40: [(i32, i32, u8, u8); 16] = [ + (553, 2047, 15, 16), + (528, 552, 14, 17), + (502, 527, 13, 18), + (475, 501, 12, 19), + (445, 474, 11, 20), + (413, 444, 10, 21), + (378, 412, 9, 22), + (339, 377, 8, 23), + (298, 338, 7, 24), + (250, 297, 6, 25), + (198, 249, 5, 26), + (139, 197, 4, 27), + (68, 138, 3, 28), + (0, 67, 2, 29), + (4080, 4095, 2, 29), + (3974, 4079, 1, 30), +]; + +#[inline] +fn quantize_16(dln: i32, ds: u8) -> u8 { + for &(lo, hi, pos, neg) in &THRESH_16 { + if (lo..=hi).contains(&dln) { + return if ds == 0 { pos } else { neg }; + } + } + if ds == 0 { 0 } else { 3 } +} + +#[inline] +fn quantize_24(dln: i32, ds: u8) -> u8 { + for &(lo, hi, pos, neg) in &THRESH_24 { + if (lo..=hi).contains(&dln) { + return if ds == 0 { pos } else { neg }; + } + } + 7 +} + +#[inline] +fn quantize_32(dln: i32, ds: u8) -> u8 { + for &(lo, hi, pos, neg) in &THRESH_32 { + if (lo..=hi).contains(&dln) { + return if ds == 0 { pos } else { neg }; + } + } + 15 +} + +#[inline] +fn quantize_40(dln: i32, ds: u8) -> u8 { + for &(lo, hi, pos, neg) in &THRESH_40 { + if (lo..=hi).contains(&dln) { + return if ds == 0 { pos } else { neg }; + } + } + 31 +} + +// --------------------------------------------------------------------------- +// G.726 Core State +// --------------------------------------------------------------------------- + +#[derive(Debug, Clone)] +struct Core { + rate: BitRate, + is_40k: bool, + a: [u16; 2], + b: [u16; 6], + dms: i16, + dml: i16, + ap: i16, + yu: i16, + yl: i32, + sr: [u16; 2], + dq: [u16; 6], + pk: [u8; 2], + td: i16, +} + +impl Core { + fn new(rate: BitRate) -> Self { + let is_40k = matches!(rate, BitRate::Rate40k); + let mut core = + Self { rate, is_40k, a: [0; 2], b: [0; 6], dms: 0, dml: 0, ap: 0, yu: 544, yl: 34816, sr: [32, 32], dq: [32; 6], pk: [0; 2], td: 0 }; + core.reset(); + core + } + + fn reset(&mut self) { + self.a = [0; 2]; + self.b = [0; 6]; + self.dms = 0; + self.dml = 0; + self.ap = 0; + self.yu = 544; + self.yl = 34816; + self.sr = [32, 32]; + self.dq = [32; 6]; + self.pk = [0; 2]; + self.td = 0; + } + + #[inline] + fn fmult(an: u16, srn: u16) -> u16 { + let an_s = (an >> 15) & 1; + let an_mag = if an_s == 0 { (an >> 2) & 0x1FFF } else { (16384_u32.wrapping_sub((an >> 2) as u32) & 0x1FFF) as u16 }; + let an_exp = if an_mag > 0 { (16 - an_mag.leading_zeros()).min(13) as u16 } else { 0 }; + let an_mant = if an_mag == 0 { 1 << 5 } else { (((an_mag as u32) << 6) >> an_exp) as u16 & 0x3F }; + + let srn_s = (srn >> 10) & 1; + let srn_exp = (srn >> 6) & 15; + let srn_mant = srn & 63; + + let wan_s = srn_s ^ an_s; + let wan_exp = srn_exp + an_exp; + let wan_mant = (((srn_mant as u32 * an_mant as u32) + 48) >> 4) as u16; + + let wan_mag = + if wan_exp <= 26 { ((wan_mant as u32) << 7) >> (26 - wan_exp) } else { (((wan_mant as u32) << 7) << (wan_exp - 26)) & 0x7FFF } as u16; + + if wan_s == 0 { wan_mag } else { (65536_u32.wrapping_sub(wan_mag as u32) & 0xFFFF) as u16 } + } + + #[inline] + fn quantize(&self, dln: i32, ds: u8) -> u8 { + match self.rate { + BitRate::Rate16k => quantize_16(dln, ds), + BitRate::Rate24k => quantize_24(dln, ds), + BitRate::Rate32k => quantize_32(dln, ds), + BitRate::Rate40k => quantize_40(dln, ds), + } + } + + #[inline] + fn table_lookup(&self, code: u8) -> (u8, u16) { + match self.rate { + BitRate::Rate16k => OUT_16[(code & 3) as usize], + BitRate::Rate24k => OUT_24[(code & 7) as usize], + BitRate::Rate32k => OUT_32[(code & 15) as usize], + BitRate::Rate40k => OUT_40[(code & 31) as usize], + } + } + + #[inline] + fn compute_accum(&self) -> (i16, i16) { + let wa0 = Self::fmult(self.a[0], self.sr[0]); + let wa1 = Self::fmult(self.a[1], self.sr[1]); + let mut sezi: u32 = 0; + for i in 0..6 { + sezi = (sezi + Self::fmult(self.b[i], self.dq[i]) as u32) & 0xFFFF; + } + let sei = (sezi + wa1 as u32 + wa0 as u32) & 0xFFFF; + let sez = (sezi as i16) >> 1; + let se = (sei as i16) >> 1; + (sez, se) + } + + #[inline] + fn compute_mix(&self) -> i32 { + let al = if self.ap >= 256 { 64 } else { self.ap >> 2 } as i32; + let dif = (self.yu as i32 + 16384 - (self.yl >> 6)) & 16383; + let difs = (dif >> 13) & 1; + let difm = if difs == 0 { dif } else { (16384 - dif) & 8191 }; + let prodm = (difm * al) >> 6; + let prod = if difs == 0 { prodm } else { (16384 - prodm) & 8191 }; + ((self.yl >> 6) + prod) & 8191 + } + + #[inline] + fn quantize_sample(&self, sample: i16, se: i16, y: i32) -> u8 { + let sl = (sample >> 2) as i32; + let sl_ext = if sl >= 0 { sl } else { 65536 + sl }; + let se_ext = if se >= 0 { se as i32 } else { 65536 + se as i32 }; + let d = ((sl_ext + 65536 - se_ext) & 0xFFFF) as u16; + + let ds = ((d >> 15) & 1) as u8; + let dqm = if ds == 0 { d } else { (65536_u32.wrapping_sub(d as u32) & 0x7FFF) as u16 }; + let exp = if dqm > 1 { (15 - dqm.leading_zeros()).min(14) } else { 0 }; + let mant = (((dqm as u32) << 7) >> exp) & 127; + let dl = ((exp << 7) + mant) as u16; + let dln = (dl as i32 + 4096 - (y >> 2)) & 4095; + self.quantize(dln, ds) + } + + #[inline] + fn step(&mut self, sample: i16, is_encoder: bool, code_in: u8) -> (u8, i16) { + let (sez, se) = self.compute_accum(); + let y = self.compute_mix(); + + let code = if is_encoder { self.quantize_sample(sample, se, y) } else { code_in }; + + // 4. RECONST & ADDA & ANTILOG + let (dqs, dqln) = self.table_lookup(code); + let dql = (dqln as i32 + (y >> 2)) & 4095; + let dex = (dql >> 7) & 15; + let dmn = dql & 127; + let dqt = 128 + dmn; + let dqmag = if (dql >> 11) == 0 { ((dqt << 7) >> (14 - dex)) as u16 } else { 0 }; + let dq = if self.is_40k { ((dqs as u16) << 15) | (dqmag & 0x7FFF) } else { ((dqs as u16) << 14) | (dqmag & 0x3FFF) }; + + // 5. ADDB & ADDC + let dqi = if dqs == 0 { + dq as u32 + } else if self.is_40k { + 65536_u32.wrapping_sub((dq & 0x7FFF) as u32) & 0xFFFF + } else { + 65536_u32.wrapping_sub((dq & 0x3FFF) as u32) & 0xFFFF + }; + let sei_ext = if se >= 0 { se as u32 } else { (65536 + se as i32) as u32 }; + let sr = ((dqi + sei_ext) & 0xFFFF) as u16; + + let sezi_ext = if sez >= 0 { sez as u32 } else { (65536 + sez as i32) as u32 }; + let dqsez = ((dqi + sezi_ext) & 0xFFFF) as u16; + let pk0 = ((dqsez >> 15) & 1) as u8; + let sigpk = if dqsez == 0 { 1 } else { 0 }; + + // 6. FLOATA & FLOATB + let dq_mag = if self.is_40k { dq & 0x7FFF } else { dq & 0x3FFF }; + let (dq_exp, dq_mant) = if dq_mag == 0 { + (0, 32) + } else { + let max_exp = if self.is_40k { 15 } else { 14 }; + let exp = (16 - dq_mag.leading_zeros()).min(max_exp); + let mant = (((dq_mag as u32) << 6) >> exp) as u16; + (exp as u16, mant) + }; + let dq0 = ((dqs as u16) << 10) | (dq_exp << 6) | (dq_mant & 63); + + let sr_s = ((sr >> 15) & 1) as u8; + let sr_mag = if sr_s == 0 { sr } else { (65536_u32.wrapping_sub(sr as u32) & 0x7FFF) as u16 }; + let (sr_exp, sr_mant) = if sr_mag == 0 { + (0, 32) + } else { + let exp = (16 - sr_mag.leading_zeros()).min(15); + let mant = (((sr_mag as u32) << 6) >> exp) as u16; + (exp as u16, mant) + }; + let sr0 = ((sr_s as u16) << 10) | (sr_exp << 6) | (sr_mant & 63); + + self.update_adaptation_and_predictors(code, y, pk0, sigpk, dqs, dq_mag); + + self.sr = [sr0, self.sr[0]]; + self.dq = [dq0, self.dq[0], self.dq[1], self.dq[2], self.dq[3], self.dq[4]]; + self.pk = [pk0, self.pk[0]]; + + let sr_signed = if sr < 32768 { sr as i32 } else { sr as i32 - 65536 }; + let out_pcm = (sr_signed << 2).clamp(-32768, 32767) as i16; + (code, out_pcm) + } + + #[inline] + fn adapt_scale(&mut self, code: u8, y: i32) { + let wi = get_wi(self.rate, code); + let dif = (((wi as i32) << 5) + 131072 - y) & 131071; + let difs = (dif >> 16) & 1; + let difsx = if difs == 0 { dif >> 5 } else { (dif >> 5) + 4096 }; + let yut = (y + difsx) & 8191; + let yup = yut.clamp(544, 5120); + + let dif = (yup + ((1048576 - self.yl) >> 6)) & 16383; + let difs = (dif >> 13) & 1; + let difsx = if difs == 0 { dif } else { dif + 507904 }; + self.yu = yup as i16; + self.yl = (self.yl + difsx) & 524287; + } + + #[inline] + fn adapt_speed(&mut self, code: u8, y: i32, dq_mag: u16) -> (i16, i16, u8) { + let fi = get_fi(self.rate, code); + let dif = (((fi as i32) << 9) + 8192 - self.dms as i32) & 8191; + let difs = (dif >> 12) & 1; + let difsx = if difs == 0 { dif >> 5 } else { (dif >> 5) + 3840 }; + let dmsp = ((difsx + self.dms as i32) & 4095) as i16; + + let dif = (((fi as i32) << 11) + 32768 - self.dml as i32) & 32767; + let difs = (dif >> 14) & 1; + let difsx = if difs == 0 { dif >> 7 } else { (dif >> 7) + 16128 }; + let dmlp = ((difsx + self.dml as i32) & 16383) as i16; + + let dif = (((dmsp as i32) << 2) + 32768 - dmlp as i32) & 32767; + let difs = (dif >> 14) & 1; + let difm = if difs == 0 { dif } else { (32768 - dif) & 16383 }; + let dthr = (dmlp as i32) >> 3; + + let tdp = if (32768..53760).contains(&self.a[1]) { 1 } else { 0 }; + let ax = if y >= 1536 && tdp == 0 && difm < dthr { 0 } else { 1 }; + + let dif = ((ax << 9) + 2048 - self.ap as i32) & 2047; + let difs = (dif >> 10) & 1; + let difsx = if difs == 0 { dif >> 4 } else { (dif >> 4) + 1920 }; + let app = ((difsx + self.ap as i32) & 1023) as i16; + + let ylint = (self.yl >> 15) as u32; + let ylfrac = ((self.yl >> 10) & 31) as u32; + let thr1 = (32 + ylfrac) << ylint; + let thr2 = if self.is_40k && ylint > 9 { + 31 << 10 + } else if !self.is_40k && ylint > 8 { + 31 << 9 + } else { + thr1 + }; + let dqthr = (thr2 + (thr2 >> 1)) >> 1; + let tr = if (dq_mag as u32) > dqthr && self.td == 1 { 1 } else { 0 }; + let apr = if tr == 1 { 256 } else { app }; + + self.dms = dmsp; + self.dml = dmlp; + self.ap = apr; + self.td = if tr == 1 { 0 } else { tdp }; + + (apr, tdp, tr) + } + + #[inline] + fn update_predictors(&mut self, pk0: u8, sigpk: u8, dqs: u8, dq_mag: u16, tr: u8) { + let pks = pk0 ^ self.pk[0]; + let uga1 = if sigpk == 1 { + 0 + } else if pks == 0 { + 192 + } else { + 65344 + }; + let a1s = (self.a[0] >> 15) & 1; + let ula1 = if a1s == 0 { + (65536_u32.wrapping_sub((self.a[0] >> 8) as u32) & 0xFFFF) as u16 + } else { + (65536_u32.wrapping_sub(((self.a[0] >> 8) + 65280) as u32) & 0xFFFF) as u16 + }; + let ua1 = (uga1 as u32 + ula1 as u32) & 0xFFFF; + let a1t = ((self.a[0] as u32 + ua1) & 0xFFFF) as u16; + + let pks1 = pk0 ^ self.pk[0]; + let pks2 = pk0 ^ self.pk[1]; + let uga2a = if pks2 == 0 { 16384_u32 } else { 114688_u32 }; + let a1_u = self.a[0]; + let fa1 = if a1s == 0 { + if a1_u <= 8191 { (a1_u as u32) << 2 } else { 8191 << 2 } + } else if a1_u >= 57345 { + ((a1_u as u32) << 2) & 131071 + } else { + 24577 << 2 + }; + let fa = if pks1 == 1 { fa1 } else { (131072_u32.wrapping_sub(fa1)) & 131071 }; + let uga2b = (uga2a + fa) & 131071; + let uga2s = (uga2b >> 16) & 1; + let uga2 = if sigpk == 1 { + 0 + } else if uga2s == 0 { + uga2b >> 7 + } else { + (uga2b >> 7) + 64512 + } as u16; + let a2s = (self.a[1] >> 15) & 1; + let ula2 = if a2s == 0 { + (65536_u32.wrapping_sub((self.a[1] >> 7) as u32) & 0xFFFF) as u16 + } else { + (65536_u32.wrapping_sub(((self.a[1] >> 7) + 65024) as u32) & 0xFFFF) as u16 + }; + let ua2 = (uga2 as u32 + ula2 as u32) & 0xFFFF; + let a2t = ((self.a[1] as u32 + ua2) & 0xFFFF) as u16; + + let a2p = if (32768..=53248).contains(&a2t) { + 53248 + } else if (12288..=32767).contains(&a2t) { + 12288 + } else { + a2t + }; + + let ome = 15360_u32; + let a1ul = ((ome + 65536 - a2p as u32) & 0xFFFF) as u16; + let a1ll = ((a2p as u32 + 65536 - ome) & 0xFFFF) as u16; + let a1p = if a1t >= 32768 && a1t <= a1ll { + a1ll + } else if a1t >= a1ul && a1t <= 32767 { + a1ul + } else { + a1t + }; + + let a1r = if tr == 1 { 0 } else { a1p }; + let a2r = if tr == 1 { 0 } else { a2p }; + + let mut new_b = [0u16; 6]; + for (i, slot) in new_b.iter_mut().enumerate() { + let un = (dqs ^ ((self.dq[i] >> 10) as u8)) & 1; + let ugbn = if dq_mag == 0 { + 0 + } else if un == 0 { + 128 + } else { + 65408 + }; + let bns = (self.b[i] >> 15) & 1; + let ulbn = if self.is_40k { + if bns == 0 { + (65536_u32.wrapping_sub((self.b[i] >> 9) as u32) & 0xFFFF) as u16 + } else { + (65536_u32.wrapping_sub(((self.b[i] >> 9) + 65408) as u32) & 0xFFFF) as u16 + } + } else if bns == 0 { + (65536_u32.wrapping_sub((self.b[i] >> 8) as u32) & 0xFFFF) as u16 + } else { + (65536_u32.wrapping_sub(((self.b[i] >> 8) + 65280) as u32) & 0xFFFF) as u16 + }; + let ubn = (ugbn as u32 + ulbn as u32) & 0xFFFF; + let bnp = ((self.b[i] as u32 + ubn) & 0xFFFF) as u16; + *slot = if tr == 1 { 0 } else { bnp }; + } + + self.a[0] = a1r; + self.a[1] = a2r; + self.b = new_b; + } + + #[inline] + fn update_adaptation_and_predictors(&mut self, code: u8, y: i32, pk0: u8, sigpk: u8, dqs: u8, dq_mag: u16) { + self.adapt_scale(code, y); + let (_, _, tr) = self.adapt_speed(code, y, dq_mag); + self.update_predictors(pk0, sigpk, dqs, dq_mag, tr); + } +} + +// --------------------------------------------------------------------------- +// Decoder & Encoder structs +// --------------------------------------------------------------------------- + +/// G.726 ADPCM decoder. +#[derive(Debug, Clone)] +pub struct Decoder { + core: Core, + packing: BitPacking, + bit_buf: u32, + num_bits: usize, +} + +impl Decoder { + /// Create a new G.726 decoder at the specified bit rate and bit packing. + #[must_use] + pub fn new(rate: BitRate, packing: BitPacking) -> Self { + Self { core: Core::new(rate), packing, bit_buf: 0, num_bits: 0 } + } + + /// Reset decoder internal predictor state. + pub fn reset(&mut self) { + self.core.reset(); + self.bit_buf = 0; + self.num_bits = 0; + } + + /// Decode a single quantized ADPCM code into an 8 kHz 16-bit linear PCM sample. + /// Bits above the configured code width are ignored, as in packed-stream decoding. + #[inline] + pub fn decode_sample(&mut self, code: u8) -> i16 { + // Adaptation must see the same bounded codeword as the reconstruction table; + // otherwise unused high bits can underflow its unsigned inverse-code arithmetic. + let code = code & ((1u8 << self.core.rate.code_size()) - 1); + self.core.step(0, false, code).1 + } + + /// Decode G.726 bitstream bytes into 8 kHz 16-bit linear PCM samples, appending to `dst`. + pub fn decode(&mut self, src: &[u8], dst: &mut Vec) -> Result<(), Error> { + if src.len() > MAX_INPUT_BYTES { + return Err(Error::InputTooLarge); + } + let cs = self.core.rate.code_size(); + let est_samples = (src.len() * 8) / cs; + dst.try_reserve(est_samples).map_err(|_| Error::AllocationFailed)?; + + match self.packing { + BitPacking::BigEndian => { + for &b in src { + self.bit_buf = ((self.bit_buf & ((1 << self.num_bits) - 1)) << 8) | (b as u32); + self.num_bits += 8; + while self.num_bits >= cs { + let code = ((self.bit_buf >> (self.num_bits - cs)) & ((1 << cs) - 1)) as u8; + self.num_bits -= cs; + let s = self.decode_sample(code); + dst.push(s); + } + self.bit_buf &= (1 << self.num_bits) - 1; + } + } + BitPacking::LittleEndian => { + for &b in src { + self.bit_buf |= (b as u32) << self.num_bits; + self.num_bits += 8; + while self.num_bits >= cs { + let code = (self.bit_buf & ((1 << cs) - 1)) as u8; + self.bit_buf >>= cs; + self.num_bits -= cs; + let s = self.decode_sample(code); + dst.push(s); + } + } + } + } + Ok(()) + } +} + +/// G.726 ADPCM encoder. +#[derive(Debug, Clone)] +pub struct Encoder { + core: Core, + packing: BitPacking, + bit_buf: u32, + num_bits: usize, +} + +impl Encoder { + /// Create a new G.726 encoder at the specified bit rate and bit packing. + #[must_use] + pub fn new(rate: BitRate, packing: BitPacking) -> Self { + Self { core: Core::new(rate), packing, bit_buf: 0, num_bits: 0 } + } + + /// Reset encoder internal predictor state. + pub fn reset(&mut self) { + self.core.reset(); + self.bit_buf = 0; + self.num_bits = 0; + } + + /// Encode a single 8 kHz 16-bit linear PCM sample into an ADPCM code word. + #[inline] + pub fn encode_sample(&mut self, sample: i16) -> u8 { + self.core.step(sample, true, 0).0 + } + + /// Encode 8 kHz 16-bit linear PCM samples into G.726 bitstream bytes, appending to `dst`. + pub fn encode(&mut self, src: &[i16], dst: &mut Vec) -> Result<(), Error> { + if src.len() > MAX_SAMPLES { + return Err(Error::InputTooLarge); + } + let cs = self.core.rate.code_size(); + let est_bytes = (src.len() * cs).div_ceil(8); + dst.try_reserve(est_bytes).map_err(|_| Error::AllocationFailed)?; + + match self.packing { + BitPacking::BigEndian => { + for &s in src { + let code = self.encode_sample(s); + self.bit_buf = ((self.bit_buf & ((1 << self.num_bits) - 1)) << cs) | ((code as u32) & ((1 << cs) - 1)); + self.num_bits += cs; + while self.num_bits >= 8 { + dst.push(((self.bit_buf >> (self.num_bits - 8)) & 0xFF) as u8); + self.num_bits -= 8; + } + self.bit_buf &= (1 << self.num_bits) - 1; + } + } + BitPacking::LittleEndian => { + for &s in src { + let code = self.encode_sample(s); + self.bit_buf |= (code as u32) << self.num_bits; + self.num_bits += cs; + while self.num_bits >= 8 { + dst.push((self.bit_buf & 0xFF) as u8); + self.bit_buf >>= 8; + self.num_bits -= 8; + } + } + } + } + Ok(()) + } + + /// Flush any remaining buffered bits into `dst`, padding with zeroes. + pub fn flush(&mut self, dst: &mut Vec) -> Result<(), Error> { + if self.num_bits > 0 { + dst.try_reserve(1).map_err(|_| Error::AllocationFailed)?; + match self.packing { + BitPacking::BigEndian => { + let b = ((self.bit_buf << (8 - self.num_bits)) & 0xFF) as u8; + dst.push(b); + } + BitPacking::LittleEndian => { + let b = (self.bit_buf & 0xFF) as u8; + dst.push(b); + } + } + self.bit_buf = 0; + self.num_bits = 0; + } + Ok(()) + } +} + +// --------------------------------------------------------------------------- +// Public Top-Level Functions +// --------------------------------------------------------------------------- + +/// Decode a mono G.726 bitstream into 8 kHz 16-bit linear PCM samples. +pub fn decode(bytes: &[u8], rate: BitRate, packing: BitPacking) -> Result, Error> { + let mut decoder = Decoder::new(rate, packing); + let mut out = Vec::new(); + decoder.decode(bytes, &mut out)?; + Ok(out) +} + +/// Encode mono 8 kHz 16-bit linear PCM samples into a G.726 bitstream. +pub fn encode(samples: &[i16], rate: BitRate, packing: BitPacking) -> Result, Error> { + let mut encoder = Encoder::new(rate, packing); + let mut out = Vec::new(); + encoder.encode(samples, &mut out)?; + encoder.flush(&mut out)?; + Ok(out) +} + +/// Decode an interleaved multi-channel G.726 stream into interleaved 8 kHz 16-bit PCM samples. +pub fn decode_interleaved(bytes: &[u8], channels: usize, rate: BitRate, packing: BitPacking) -> Result, Error> { + if channels == 0 || channels > MAX_CHANNELS { + return Err(Error::InvalidChannels(channels)); + } + if channels == 1 { + return decode(bytes, rate, packing); + } + if bytes.len() > MAX_INPUT_BYTES { + return Err(Error::InputTooLarge); + } + + let mut decoders: Vec = Vec::with_capacity(channels); + for _ in 0..channels { + decoders.push(Decoder::new(rate, packing)); + } + + let cs = rate.code_size(); + let est_samples = (bytes.len() * 8) / cs; + let mut out = Vec::new(); + out.try_reserve(est_samples).map_err(|_| Error::AllocationFailed)?; + + let mut ch_outs: Vec> = Vec::with_capacity(channels); + for _ in 0..channels { + ch_outs.push(Vec::new()); + } + + for (i, &b) in bytes.iter().enumerate() { + let ch = i % channels; + decoders[ch].decode(&[b], &mut ch_outs[ch])?; + } + + let min_len = ch_outs.iter().map(Vec::len).min().unwrap_or(0); + for i in 0..min_len { + for ch_out in ch_outs.iter().take(channels) { + out.push(ch_out[i]); + } + } + + Ok(out) +} + +/// Encode interleaved 8 kHz 16-bit PCM samples into an interleaved multi-channel G.726 stream. +pub fn encode_interleaved(samples: &[i16], channels: usize, rate: BitRate, packing: BitPacking) -> Result, Error> { + if channels == 0 || channels > MAX_CHANNELS { + return Err(Error::InvalidChannels(channels)); + } + if channels == 1 { + return encode(samples, rate, packing); + } + if samples.len() > MAX_SAMPLES { + return Err(Error::InputTooLarge); + } + + let mut encoders: Vec = Vec::with_capacity(channels); + for _ in 0..channels { + encoders.push(Encoder::new(rate, packing)); + } + + let cs = rate.code_size(); + let est_bytes = (samples.len() * cs).div_ceil(8); + let mut out = Vec::new(); + out.try_reserve(est_bytes).map_err(|_| Error::AllocationFailed)?; + + let mut ch_samples: Vec> = Vec::with_capacity(channels); + for _ in 0..channels { + ch_samples.push(Vec::new()); + } + + for (i, &s) in samples.iter().enumerate() { + let ch = i % channels; + ch_samples[ch].push(s); + } + + let mut ch_bytes: Vec> = Vec::with_capacity(channels); + for ch in 0..channels { + let mut b = Vec::new(); + encoders[ch].encode(&ch_samples[ch], &mut b)?; + encoders[ch].flush(&mut b)?; + ch_bytes.push(b); + } + + let min_bytes = ch_bytes.iter().map(Vec::len).min().unwrap_or(0); + for i in 0..min_bytes { + for ch_b in ch_bytes.iter().take(channels) { + out.push(ch_b[i]); + } + } + + Ok(out) +} + +// --------------------------------------------------------------------------- +// Unit tests +// --------------------------------------------------------------------------- + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn sample_api_ignores_unused_codeword_bits() { + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + let mask = (1u8 << rate.code_size()) - 1; + let mut actual = Decoder::new(rate, BitPacking::BigEndian); + let mut expected = Decoder::new(rate, BitPacking::BigEndian); + for code in 0..=u8::MAX { + assert_eq!(actual.decode_sample(code), expected.decode_sample(code & mask)); + } + // High bits must not leave a different predictor state for later valid codes. + for code in 0..=mask { + assert_eq!(actual.decode_sample(code), expected.decode_sample(code)); + } + } + } + + #[test] + fn reject_invalid_channels() { + assert!(decode_interleaved(&[], 0, BitRate::Rate32k, BitPacking::BigEndian).is_err()); + assert!(decode_interleaved(&[], 9, BitRate::Rate32k, BitPacking::BigEndian).is_err()); + assert!(encode_interleaved(&[], 0, BitRate::Rate32k, BitPacking::BigEndian).is_err()); + assert!(encode_interleaved(&[], 9, BitRate::Rate32k, BitPacking::BigEndian).is_err()); + } + + #[test] + fn roundtrip_silence_all_rates() { + let pcm = vec![0i16; 64]; + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + for packing in [BitPacking::BigEndian, BitPacking::LittleEndian] { + let encoded = encode(&pcm, rate, packing).expect("encode silence"); + let decoded = decode(&encoded, rate, packing).expect("decode silence"); + assert_eq!(decoded.len(), pcm.len()); + for &s in &decoded { + assert!(s.abs() <= 16, "silence sample too large: {s}"); + } + } + } + } + + #[test] + fn hostile_input_does_not_panic() { + let mut decoder = Decoder::new(BitRate::Rate32k, BitPacking::BigEndian); + let mut out = Vec::new(); + let hostile = vec![0xFF; 1024]; + let _ = decoder.decode(&hostile, &mut out); + + let mut decoder = Decoder::new(BitRate::Rate16k, BitPacking::LittleEndian); + let mut out = Vec::new(); + let _ = decoder.decode(&[0x00, 0xAA, 0x55, 0x12, 0x34], &mut out); + } +} diff --git a/crates/audio/src/lib.rs b/crates/audio/src/lib.rs index e5e859d3c..3ccdcdf3f 100644 --- a/crates/audio/src/lib.rs +++ b/crates/audio/src/lib.rs @@ -13,6 +13,7 @@ //! demuxers and [`TrackDecoder`]; everything else (FLAC, Vorbis, CAF, ADPCM, A-law, µ-law) through //! `symphonia`, which is to be replaced by native decoders. Feature `decode-native` is the //! same without symphonia. +//! - [`vorbis::decoder`] (feature `vorbis-decode`): the pure-Rust Vorbis I decoder, packets and Ogg files. //! - [`encode_ogg_vorbis`] and [`vorbis::encoder`] (feature `vorbis-encode`): Ogg Vorbis files //! and Vorbis packets from a pure-Rust encoder, 1 to 8 channels, quality -1 to 10, with tags. //! - [`TrackDecoder`] (any decoder feature): one track's packets from any demuxer to planar @@ -28,10 +29,12 @@ //! - [`peaks`] (feature `peaks`): min/max/RMS pyramid for waveform drawing. //! - Codec modules for packet-level use, each with its own features: [`aac`] (`aac-decode`, //! `aac-encode`), [`alac`] (`alac-decode`, `alac-encode`), [`opus`] (`opus-decode`, and -//! [`opus::encoder`] with `opus-encode`), [`ac3`] (`ac3-decode`), [`mpa`] (`mpa-decode`), [`mp3`] +//! [`opus::encoder`] with `opus-encode`), [`ac3`] (`ac3-decode`), [`mpa`] (`mpa-decode`; `mpa-encode`: the Layer II encoder), [`mp3`] //! (`mp3-decode`, `mp3-encode`), [`flac`] (`flac-decode`: the frame and file decoder; -//! `flac-encode`: the packet encoder), [`qoa`] (`qoa-decode`, `qoa-encode`: whole QOA files), -//! [`gsm`] (`gsm-decode`, `gsm-encode`: GSM 06.10 full-rate speech). +//! `flac-encode`: the packet encoder), [`qoa`] (`qoa-decode`, `qoa-encode`: whole QOA files), [`adpcm`] +//! (`adpcm`: IMA WAV, Microsoft, Yamaha and Flash ADPCM), +//! [`gsm`] (`gsm-decode`, `gsm-encode`: GSM 06.10 full-rate speech), [`vmd`] (`vmd-decode`: +//! Sierra VMD sound). //! //! The shared types below build with no features. @@ -39,9 +42,15 @@ pub mod aac; #[cfg(any(feature = "ac3-decode", feature = "ac3-encode", feature = "eac3-encode"))] pub mod ac3; +#[cfg(feature = "adpcm")] +pub mod adpcm; #[cfg(any(feature = "alac-decode", feature = "alac-encode"))] pub mod alac; mod buffer; +#[cfg(feature = "g722")] +pub mod g722; +#[cfg(feature = "g726")] +pub mod g726; #[cfg(any(feature = "gsm-decode", feature = "gsm-encode"))] pub mod gsm; mod layout; @@ -63,7 +72,9 @@ mod read; pub mod sbc; #[cfg(any(feature = "aac-decode", feature = "alac-decode", feature = "opus-decode", feature = "ac3-decode", feature = "mpa-decode"))] mod track; -#[cfg(feature = "vorbis-encode")] +#[cfg(feature = "vmd-decode")] +pub mod vmd; +#[cfg(any(feature = "vorbis-decode", feature = "vorbis-encode"))] pub mod vorbis; #[cfg(any(feature = "decode-native", feature = "pcm-encode"))] mod wav; @@ -267,6 +278,16 @@ impl From for AudioError { } } +#[cfg(feature = "vmd-decode")] +impl From for AudioError { + fn from(e: vmd::Error) -> Self { + match e { + vmd::Error::Unsupported(_) => AudioError::Unsupported(e.to_string()), + _ => AudioError::Malformed(e.to_string()), + } + } +} + #[cfg(feature = "opus-encode")] impl From for AudioError { fn from(e: opus::encoder::Error) -> Self { diff --git a/crates/audio/src/mp3/mod.rs b/crates/audio/src/mp3/mod.rs index d28607110..e273e903c 100644 --- a/crates/audio/src/mp3/mod.rs +++ b/crates/audio/src/mp3/mod.rs @@ -39,13 +39,13 @@ mod decoder; #[cfg(feature = "mp3-encode")] mod encoder; #[cfg(feature = "mp3-encode")] -mod filterbank; +pub(crate) mod filterbank; #[cfg(feature = "mp3-encode")] mod huffman; mod huffman_tables; #[cfg(feature = "mp3-encode")] mod quantize; -mod tables; +pub(crate) mod tables; #[cfg(feature = "mp3-decode")] pub use decoder::{Decoder, InfoTag}; diff --git a/crates/audio/src/mpa/encoder.rs b/crates/audio/src/mpa/encoder.rs new file mode 100644 index 000000000..000f86fe7 --- /dev/null +++ b/crates/audio/src/mpa/encoder.rs @@ -0,0 +1,493 @@ +//! The Layer II encoder; the module docs are in `mpa/mod.rs`. + +// Index loops follow the specification's pseudo-code (FilmCraft allows this lint workspace-wide). +#![allow(clippy::needless_range_loop)] + +use craft_media::bitstream::BitWriter; + +use super::tables::{self, AllocTable, SUBBANDS}; +use crate::mp3::filterbank::Polyphase; +use crate::mp3::tables::ath_db; + +/// Settings an [`Encoder`] refuses. +#[non_exhaustive] +#[derive(Debug, thiserror::Error, PartialEq, Eq)] +pub enum EncodeError { + /// A sample rate outside [`SAMPLE_RATES`]. + #[error("MP2: unsupported sample rate {0} Hz (32, 44.1, 48 kHz, or 16, 22.05, 24 kHz)")] + SampleRate(u32), + /// A bit rate that is not one of [`bitrates`] for the sample rate and channel count. + #[error("MP2: unsupported bit rate {kbps} kbit/s at {rate} Hz with {channels} channel(s)")] + Bitrate { + /// The bit rate asked for, kbit/s. + kbps: u32, + /// The sample rate, Hz. + rate: u32, + /// The channel count. + channels: usize, + }, + /// More than two channels, or none. + #[error("MP2: unsupported channel count {0} (1 or 2)")] + Channels(usize), +} + +/// Result with this module's [`EncodeError`]. +pub type EncodeResult = std::result::Result; + +/// Encoder settings. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Config { + /// One of [`SAMPLE_RATES`]. + pub sample_rate: u32, + /// 1 or 2. Two channels are coded as stereo (`mode` 00), each with its own allocation. + pub channels: usize, + /// One of [`bitrates`] for the sample rate and channel count, kbit/s. + pub bitrate_kbps: u32, +} + +impl Config { + /// `channels` at `sample_rate`, constant `bitrate_kbps`. + pub fn cbr(sample_rate: u32, channels: usize, bitrate_kbps: u32) -> Config { + Config { sample_rate, channels, bitrate_kbps } + } +} + +/// The sample rates the encoder accepts. +pub const SAMPLE_RATES: [u32; 6] = [32_000, 44_100, 48_000, 16_000, 22_050, 24_000]; + +/// Samples by which a standard decoder's output lags the input: the polyphase analysis and +/// synthesis filters. +pub const DELAY: u32 = 481; + +/// Samples per channel in a frame. +pub const FRAME_SAMPLES: usize = 1152; + +/// Bit rates ISO/IEC 11172-3 Table 3-B.2 allows for a single channel at 32 / 44.1 / 48 kHz. +const MPEG1_MONO: [u32; 10] = [32, 48, 56, 64, 80, 96, 112, 128, 160, 192]; +/// Bit rates it allows for two channels. +const MPEG1_STEREO: [u32; 10] = [64, 96, 112, 128, 160, 192, 224, 256, 320, 384]; + +/// Whether `rate` is one of the MPEG-2 lower sampling frequencies; `None` if it is unsupported. +fn is_lsf(rate: u32) -> Option { + match rate { + 32_000 | 44_100 | 48_000 => Some(false), + 16_000 | 22_050 | 24_000 => Some(true), + _ => None, + } +} + +/// The bit rates (kbit/s) a Layer II stream can use at `sample_rate` with `channels` channels: +/// at 32 / 44.1 / 48 kHz the combinations ISO/IEC 11172-3 allows (32-192 for one channel, 64-384 +/// for two), at the lower sampling frequencies 8-160 for either. Empty for an unsupported rate. +pub fn bitrates(sample_rate: u32, channels: usize) -> &'static [u32] { + match is_lsf(sample_rate) { + Some(false) if channels == 1 => &MPEG1_MONO, + Some(false) => &MPEG1_STEREO, + Some(true) => &tables::BITRATES_LSF_L23[1..], + None => &[], + } +} + +/// The highest bit rate at `sample_rate` and `channels` not above `kbps` (the lowest one when +/// `kbps` is below all of them); `None` for an unsupported rate. +pub fn nearest_bitrate(sample_rate: u32, channels: usize, kbps: u32) -> Option { + let rates = bitrates(sample_rate, channels); + rates.iter().rev().find(|&&r| r <= kbps).or(rates.first()).copied() +} + +/// SNR-free noise model: the power of the error of rounding a value in ±1 to one of `steps` +/// levels spaced `2 / steps` apart, is `(2 / steps)² / 12`. +fn quantization_noise(steps: u16) -> f32 { + let d = 2.0 / f32::from(steps); + d * d / 12.0 +} + +/// Index of the scalefactor for a peak of `peak` (Table 3-B.1): the smallest scalefactor that is +/// at least `peak`, i.e. the largest index. +fn scalefactor_index(peak: f32) -> u32 { + if peak.is_nan() || peak <= 0.0 { + return 62; + } + let mut i = (3.0 * (1.0 - f64::from(peak).log2())).floor().clamp(0.0, 62.0) as u32; + while i > 0 && tables::scalefactor(i) < peak { + i -= 1; + } + while i < 62 && tables::scalefactor(i + 1) >= peak { + i += 1; + } + i +} + +/// Which scalefactors of a subband's three parts are sent (`scfsi`, §2.4.1.6) and what they are. +fn share(sf: [u32; 3]) -> (u32, [u32; 3]) { + let near = |a: u32, b: u32| a.abs_diff(b) <= 1; + let [a, b, c] = sf; + if near(a, b) && near(b, c) && near(a, c) { + let m = a.min(b).min(c); + (2, [m, m, m]) + } else if near(a, b) { + let m = a.min(b); + (1, [m, m, c]) + } else if near(b, c) { + let m = b.min(c); + (3, [a, m, m]) + } else { + (0, sf) + } +} + +/// Scalefactors sent for an `scfsi` class. +fn scalefactors_sent(scfsi: u32) -> u64 { + match scfsi { + 0 => 3, + 2 => 1, + _ => 2, + } +} + +/// Bits of the 12 granules of samples in a subband with `steps` quantization steps. +fn sample_bits(steps: u16) -> u64 { + 12 * match tables::grouping(steps) { + Some(bits) => u64::from(bits), + None => 3 * u64::from((u32::from(steps) + 1).trailing_zeros()), + } +} + +/// What the encoder decided for one channel of a frame. +#[derive(Clone)] +struct ChannelPlan { + /// The allocation value (index into the table's row) per subband. + alloc: [usize; SUBBANDS], + /// `scfsi` per subband. + scfsi: [u32; SUBBANDS], + /// The scalefactor index of each part of each subband, after sharing. + sf: [[u32; 3]; SUBBANDS], + /// Mean square of each subband's samples. + energy: [f32; SUBBANDS], +} + +/// A Layer II encoder. Feed planar `f32` samples (full scale ±1) to [`Encoder::encode`]; it +/// returns whole frames as they are completed. [`Encoder::flush`] pads the end with silence and +/// returns the rest. +/// +/// ``` +/// use craft_audio::mpa::encoder::{Config, DELAY, Encoder}; +/// +/// let left: Vec = (0..48_000).map(|i| (i as f32 * 0.05).sin() * 0.5).collect(); +/// let right = left.clone(); +/// let mut enc = Encoder::new(Config::cbr(48_000, 2, 192))?; +/// let mut mp2 = enc.encode(&[&left, &right]); // whole frames as they complete +/// mp2.extend(enc.flush()); // pads with silence to the last input sample +/// assert_eq!(mp2.len() % 576, 0); // 192 kbit/s at 48 kHz: 576 bytes per frame +/// assert_eq!(DELAY, 481); // a decoder's output lags the input by this many samples +/// # Ok::<(), craft_audio::mpa::encoder::EncodeError>(()) +/// ``` +pub struct Encoder { + cfg: Config, + lsf: bool, + sr_index: u32, + br_index: u32, + table: AllocTable, + sblimit: usize, + /// The masking offset floor per subband (power), from the threshold in quiet. + ath: [f32; SUBBANDS], + poly: Vec, + /// Buffered input per channel, and how much of it is consumed. + input: Vec>, + consumed: usize, + /// Remainder accumulator for the padding slot (44.1 / 22.05 kHz). + pad_acc: u64, + samples_in: u64, + frames: u64, +} + +impl Encoder { + /// An encoder for `cfg`, or the setting it cannot carry. + pub fn new(cfg: Config) -> EncodeResult { + let lsf = is_lsf(cfg.sample_rate).ok_or(EncodeError::SampleRate(cfg.sample_rate))?; + if !(1..=2).contains(&cfg.channels) { + return Err(EncodeError::Channels(cfg.channels)); + } + let bad = EncodeError::Bitrate { kbps: cfg.bitrate_kbps, rate: cfg.sample_rate, channels: cfg.channels }; + if !bitrates(cfg.sample_rate, cfg.channels).contains(&cfg.bitrate_kbps) { + return Err(bad); + } + let (rates, bitrate_table): (&[u32; 3], &[u32; 15]) = + if lsf { (&[22_050, 24_000, 16_000], &tables::BITRATES_LSF_L23) } else { (&tables::SAMPLE_RATES, &tables::BITRATES_MPEG1_L2) }; + let sr_index = rates.iter().position(|&r| r == cfg.sample_rate).ok_or(EncodeError::SampleRate(cfg.sample_rate))?; + let br_index = bitrate_table.iter().position(|&b| b == cfg.bitrate_kbps).ok_or(bad)?; + let per_channel = cfg.bitrate_kbps / cfg.channels as u32; + let table = AllocTable::select(lsf, cfg.sample_rate, per_channel); + let sblimit = table.sblimit().min(SUBBANDS); + let mut ath = [0f32; SUBBANDS]; + for (sb, a) in ath.iter_mut().enumerate() { + let centre = (sb as f64 + 0.5) * f64::from(cfg.sample_rate) / 64.0; + // a full-scale sine has a mean square of 1/2 and plays back at about 96 dB SPL + *a = (0.5 * 10f64.powf((ath_db(centre) - 96.0) / 10.0)) as f32; + } + Ok(Encoder { + cfg, + lsf, + sr_index: sr_index as u32, + br_index: br_index as u32, + table, + sblimit, + ath, + poly: vec![Polyphase::new(); cfg.channels], + input: vec![Vec::new(); cfg.channels], + consumed: 0, + pad_acc: 0, + samples_in: 0, + frames: 0, + }) + } + + /// The settings. + pub fn config(&self) -> &Config { + &self.cfg + } + + /// Samples per channel in a frame: 1152. + pub fn frame_samples(&self) -> usize { + FRAME_SAMPLES + } + + /// Samples by which a standard decoder's output lags the input. + pub fn delay(&self) -> u32 { + DELAY + } + + /// Frames written so far. + pub fn frames(&self) -> u64 { + self.frames + } + + /// Encode planar samples (one slice per channel; a missing channel is silence, extra ones + /// are ignored, every channel takes the first channel's length). Returns the completed frames. + pub fn encode(&mut self, planar: &[&[f32]]) -> Vec { + let n = planar.first().map_or(0, |p| p.len()); + for (c, buf) in self.input.iter_mut().enumerate() { + let src = planar.get(c).copied().unwrap_or(&[]); + buf.extend((0..n).map(|i| src.get(i).copied().filter(|v| v.is_finite()).unwrap_or(0.0).clamp(-4.0, 4.0))); + } + self.samples_in = self.samples_in.saturating_add(n as u64); + let mut out = Vec::new(); + self.drain(&mut out); + out + } + + /// Encode the buffered rest padded with silence, plus enough silence that a decoder outputs + /// every input sample, and return the remaining frames. + pub fn flush(&mut self) -> Vec { + let fs = FRAME_SAMPLES as u64; + let needed = if self.samples_in == 0 { self.frames } else { self.samples_in.saturating_add(u64::from(DELAY)).div_ceil(fs) }; + let have = self.input.first().map_or(0, |b| b.len().saturating_sub(self.consumed)); + let want = (needed.saturating_sub(self.frames) as usize).saturating_mul(FRAME_SAMPLES); + if want > have { + for buf in &mut self.input { + buf.resize(self.consumed + want, 0.0); + } + } + let mut out = Vec::new(); + self.drain(&mut out); + self.input.iter_mut().for_each(Vec::clear); + self.consumed = 0; + out + } + + /// Encode every whole frame of buffered input. + fn drain(&mut self, out: &mut Vec) { + while self.input.first().is_some_and(|b| b.len() - self.consumed >= FRAME_SAMPLES) { + let mut sub = vec![[[0f32; SUBBANDS]; 36]; self.cfg.channels]; + for (ch, slots) in sub.iter_mut().enumerate() { + let (Some(buf), Some(poly)) = (self.input.get(ch), self.poly.get_mut(ch)) else { continue }; + let frame = buf.get(self.consumed..self.consumed + FRAME_SAMPLES).unwrap_or(&[]); + for (slot, chunk) in slots.iter_mut().zip(frame.as_chunks::<32>().0) { + poly.filter(chunk, slot); + } + } + self.consumed += FRAME_SAMPLES; + self.write_frame(&sub, out); + self.frames += 1; + } + // keep the buffer small + if self.consumed >= 1 << 16 { + for buf in &mut self.input { + buf.drain(..self.consumed); + } + self.consumed = 0; + } + } + + /// The scalefactors and energies of a channel's 36 time slots. + fn analyse(&self, slots: &[[f32; SUBBANDS]; 36]) -> ChannelPlan { + let mut plan = ChannelPlan { alloc: [0; SUBBANDS], scfsi: [0; SUBBANDS], sf: [[62; 3]; SUBBANDS], energy: [0.0; SUBBANDS] }; + for sb in 0..self.sblimit { + let mut sf = [62u32; 3]; + for (part, s) in sf.iter_mut().enumerate() { + let peak = slots[12 * part..12 * part + 12].iter().map(|slot| slot[sb].abs()).fold(0f32, f32::max); + *s = scalefactor_index(peak); + } + (plan.scfsi[sb], plan.sf[sb]) = share(sf); + plan.energy[sb] = slots.iter().map(|slot| slot[sb] * slot[sb]).sum::() / 36.0; + } + plan + } + + /// Choose the allocation of every subband of every channel with the bits the frame has. + fn allocate(&self, plans: &mut [ChannelPlan], mut bits_left: i64) { + let nch = plans.len(); + // power the quantization noise of each subband may have before it is audible: a spread + // of the band energies, never below the threshold in quiet + let mut mask = vec![[0f32; SUBBANDS]; nch]; + for (m, plan) in mask.iter_mut().zip(plans.iter()) { + for sb in 0..self.sblimit { + let mut level = self.ath[sb]; + for j in 0..self.sblimit { + let atten_db = 14.0 + 20.0 * sb.abs_diff(j) as f32; + level = level.max(plan.energy[j] * 10f32.powf(-atten_db / 10.0)); + } + m[sb] = level; + } + } + // the fixed cost: every subband's allocation field + for sb in 0..self.sblimit { + bits_left -= (nch * self.table.row(sb).len().trailing_zeros() as usize) as i64; + } + // the noise a subband has with allocation `a`: dropped, or the mean over its parts + let noise = |plan: &ChannelPlan, sb: usize, a: usize| -> f32 { + let row = self.table.row(sb); + let steps = row.get(a).copied().unwrap_or(0); + if steps == 0 { + return plan.energy[sb]; + } + let mean_sf2 = plan.sf[sb].iter().map(|&i| tables::scalefactor(i).powi(2)).sum::() / 3.0; + (quantization_noise(steps) * mean_sf2).min(plan.energy[sb]) + }; + let cost = |plan: &ChannelPlan, sb: usize, a: usize| -> i64 { + let row = self.table.row(sb); + let step = |a: usize| row.get(a).copied().unwrap_or(0); + let (from, to) = (step(a), step(a + 1)); + let mut bits = sample_bits(to) as i64 - if from == 0 { 0 } else { sample_bits(from) as i64 }; + if from == 0 { + bits += 2 + 6 * scalefactors_sent(plan.scfsi[sb]) as i64; + } + bits + }; + let mut blocked = vec![[false; SUBBANDS]; nch]; + loop { + // the subband whose noise is furthest above its mask + let mut best: Option<(usize, usize, f32)> = None; + for (ch, plan) in plans.iter().enumerate() { + for sb in 0..self.sblimit { + let a = plan.alloc[sb]; + if a + 1 >= self.table.row(sb).len() || blocked[ch][sb] || plan.energy[sb] <= 0.0 { + continue; + } + let ratio = noise(plan, sb, a) / mask[ch][sb].max(1e-20); + if ratio > 1e-3 && best.is_none_or(|(_, _, r)| ratio > r) { + best = Some((ch, sb, ratio)); + } + } + } + let Some((ch, sb, _)) = best else { break }; + let plan = &mut plans[ch]; + let c = cost(plan, sb, plan.alloc[sb]); + if c <= bits_left { + bits_left -= c; + plan.alloc[sb] += 1; + } else { + blocked[ch][sb] = true; + } + } + } + + fn write_frame(&mut self, sub: &[[[f32; SUBBANDS]; 36]], out: &mut Vec) { + let nch = self.cfg.channels; + // frame length: 144 bytes per kbit/s over the sampling rate, plus a slot when the + // remainder has added up to one + let rate = u64::from(self.cfg.sample_rate); + let exact = 144 * u64::from(self.cfg.bitrate_kbps) * 1000; + self.pad_acc += exact % rate; + let pad = self.pad_acc >= rate; + if pad { + self.pad_acc -= rate; + } + let frame_bytes = (exact / rate) as usize + usize::from(pad); + + let mut plans: Vec = sub.iter().map(|s| self.analyse(s)).collect(); + self.allocate(&mut plans, frame_bytes as i64 * 8 - 32); + + let mut w = BitWriter::new(); + w.write_bits(0xFFF, 12); + w.write_bits(u32::from(!self.lsf), 1); + w.write_bits(0b10, 2); // Layer II + w.write_bits(1, 1); // no CRC + w.write_bits(self.br_index, 4); + w.write_bits(self.sr_index, 2); + w.write_bits(u32::from(pad), 1); + w.write_bits(0, 1); // private + w.write_bits(if nch == 1 { 3 } else { 0 }, 2); // mono or stereo + w.write_bits(0, 2); // mode extension + w.write_bits(0, 1); // copyright + w.write_bits(1, 1); // original + w.write_bits(0, 2); // emphasis + for sb in 0..self.sblimit { + let nbal = self.table.row(sb).len().trailing_zeros(); + for plan in &plans { + w.write_bits(plan.alloc[sb] as u32, nbal); + } + } + for sb in 0..self.sblimit { + for plan in &plans { + if plan.alloc[sb] != 0 { + w.write_bits(plan.scfsi[sb], 2); + } + } + } + for sb in 0..self.sblimit { + for plan in &plans { + if plan.alloc[sb] == 0 { + continue; + } + let [a, b, c] = plan.sf[sb]; + match plan.scfsi[sb] { + 0 => [a, b, c].iter().for_each(|&s| w.write_bits(s, 6)), + 1 => [a, c].iter().for_each(|&s| w.write_bits(s, 6)), + 2 => w.write_bits(a, 6), + _ => [a, b].iter().for_each(|&s| w.write_bits(s, 6)), + } + } + } + for gr in 0..12 { + let part = gr / 4; + for sb in 0..self.sblimit { + for (ch, plan) in plans.iter().enumerate() { + let a = plan.alloc[sb]; + let steps = self.table.row(sb).get(a).copied().unwrap_or(0); + if steps == 0 { + continue; + } + let scale = tables::scalefactor(plan.sf[sb][part]); + let n = u32::from(steps); + let code = |k: usize| -> u32 { + let x = (sub[ch][3 * gr + k][sb] / scale).clamp(-1.0, 1.0); + // the reconstruction points are (2v + 1 - n) / n + ((x * n as f32 + n as f32 - 1.0) / 2.0).round().clamp(0.0, (n - 1) as f32) as u32 + }; + let v = [code(0), code(1), code(2)]; + match tables::grouping(steps) { + Some(bits) => w.write_bits(v[0] + n * v[1] + n * n * v[2], bits), + None => { + let nb = (n + 1).trailing_zeros(); + v.iter().for_each(|&x| w.write_bits(x, nb)); + } + } + } + } + } + let mut bytes = w.finish(); + bytes.resize(frame_bytes, 0); + out.extend_from_slice(&bytes); + } +} diff --git a/crates/audio/src/mpa/mod.rs b/crates/audio/src/mpa/mod.rs index 70adcfd13..09560c9d4 100644 --- a/crates/audio/src/mpa/mod.rs +++ b/crates/audio/src/mpa/mod.rs @@ -13,12 +13,30 @@ //! format (bit rate index 0, whose frame length is only known from the next sync word) and the //! CRC (read, not checked, like most decoders). //! +//! # Encoder (feature `mpa-encode`) +//! +//! [`encoder::Encoder`] writes Layer II streams, written from ISO/IEC 11172-3 (§2.4.1.6 bit stream +//! syntax, Annex B tables, Annex C encoding process) and ISO/IEC 13818-3. +//! +//! - Constant bit rate: 32-192 kbit/s mono and 64-384 kbit/s stereo at 32 / 44.1 / 48 kHz (the +//! rate and mode pairs of Table 3-B.2), 8-160 kbit/s at 16 / 22.05 / 24 kHz. Mono, or stereo with +//! each channel allocated on its own (no joint stereo, no dual channel). +//! - The polyphase analysis filterbank of Annex C.1.3 (shared with the Layer III encoder), a +//! scalefactor per 12 samples with the `scfsi` sharing of §2.4.1.6, and a bit allocation chosen by +//! spending the frame's bits where the quantization noise is furthest above a simple masking +//! estimate (the band energies spread over the neighbouring subbands, never below the threshold +//! in quiet). It is not one of the psychoacoustic models of Annex D. +//! - Output: frames only, no CRC, no ID3 tag. Frames written one after another are a playable +//! `.mp2` file. A decoder's output lags the input by [`encoder::DELAY`] samples. +//! //! From FilmCraft's `filmcraft-mpa` (storytold/filmcraft@8fda2f2). Public items keep their names, so //! FilmCraft can re-export this module. // Index loops follow the specification's pseudo-code (FilmCraft allows this lint workspace-wide). #![allow(clippy::needless_range_loop)] +#[cfg(feature = "mpa-encode")] +pub mod encoder; pub(crate) mod tables; use craft_media::bitstream::BitReader; diff --git a/crates/audio/src/vmd.rs b/crates/audio/src/vmd.rs new file mode 100644 index 000000000..9e45b1a5c --- /dev/null +++ b/crates/audio/src/vmd.rs @@ -0,0 +1,192 @@ +//! Sierra VMD sound decoder (feature `vmd-decode`): the 8-bit PCM and 16-bit DPCM sound of VMD +//! (Video and Music Data) files, as in Sierra's and Coktel Vision's 1990s games. +//! +//! Clean-room, from the public format description at +//! ("Description of the Sierra Video and Music Data (VMD) Format", Mike Melanson and Vladimir +//! Gneushev). The description gives the coding but not the size of a block; the sizes here are +//! what ffmpeg was seen to expect of files made by this crate's tests: +//! +//! | Sound | Bytes in a block of `n` samples a channel | +//! |---|---| +//! | 8-bit | `n` for each channel, interleaved | +//! | 16-bit | 2 for each channel's first sample, then one code for each further sample, interleaved | +//! +//! The header's frame length is `n`, except in old-style stereo (audio flag 0x8000), where it +//! counts both channels. Old-style 16-bit stereo blocks begin with their first samples like the +//! others, which is what ffmpeg reads; the description says they carry the last block's samples +//! over instead. No such file was at hand to settle it. +//! +//! A [`Decoder`] is made from the 816-byte file header. [`Decoder::decode`] takes a sound +//! frame's flags (from its record in the file's table of contents; `craft_media::vmd` reads it) +//! and its data, and returns interleaved `i16` samples: one block of sound or silence, or, for a +//! frame with a silence mask (the first sound frame of a file), several. 8-bit samples are widened to 16 bits. Blocks do not depend +//! on each other, so decoding can start at any frame. +//! +//! Not decoded: IMA ADPCM sound (audio flag 0x10) and the external codecs of later Coktel Vision +//! files ([`Error::Unsupported`]). +//! +//! Input is treated as hostile: a block is at most 65 535 samples a channel and is decoded only +//! if all of it is there; a frame with a silence mask yields at most 32 blocks (the width of +//! the mask), any other frame as many whole blocks as its data holds. No `unsafe`, no panics. + +#![warn(missing_docs)] + +/// Bytes of the VMD file header a [`Decoder`] is made from. +pub const HEADER_LEN: usize = 816; + +/// Errors from decoding VMD sound. +#[non_exhaustive] +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum Error { + /// The header or a frame is not valid. + #[error("invalid VMD sound: {0}")] + Invalid(&'static str), + /// Valid, but not something this decoder handles. + #[error("unsupported VMD sound: {0}")] + Unsupported(&'static str), +} + +/// The steps of the 16-bit coding: a code's low seven bits pick one, its top bit the sign. +const STEPS: [u16; 128] = [ + 0, 8, 16, 32, 48, 64, 80, 96, 112, 128, 144, 160, 176, 192, 208, 224, 240, 256, 272, 288, 304, 320, 336, 352, 368, 384, 400, 416, 432, 448, 464, + 480, 496, 512, 520, 528, 536, 544, 552, 560, 568, 576, 584, 592, 600, 608, 616, 624, 632, 640, 648, 656, 664, 672, 680, 688, 696, 704, 712, 720, + 728, 736, 744, 752, 760, 768, 776, 784, 792, 800, 808, 816, 824, 832, 840, 848, 856, 864, 872, 880, 888, 896, 904, 912, 920, 928, 936, 944, 952, + 960, 968, 976, 984, 992, 1000, 1008, 1016, 1024, 1088, 1152, 1216, 1280, 1344, 1408, 1472, 1536, 1600, 1664, 1728, 1792, 1856, 1920, 1984, 2048, + 2304, 2560, 2816, 3072, 3328, 3584, 3840, 4096, 5120, 6144, 7168, 8192, 12288, 16384, +]; + +/// A VMD sound decoder. +#[derive(Clone, Debug)] +pub struct Decoder { + sample_rate: u32, + channels: usize, + sixteen_bit: bool, + /// Samples of one block, all channels counted. + block_total: usize, +} + +impl Decoder { + /// A decoder for the file whose header is `header` (its first 816 bytes; more are ignored). + pub fn new(header: &[u8]) -> Result { + let h = header.get(..HEADER_LEN).ok_or(Error::Invalid("the header is shorter than 816 bytes"))?; + let u16_at = |at: usize| u16::from_le_bytes([h[at], h[at + 1]]); + if usize::from(u16_at(0)) != HEADER_LEN - 2 { + return Err(Error::Invalid("not a VMD header")); + } + if u16_at(16) & 0x1000 == 0 || u16_at(804) == 0 { + return Err(Error::Invalid("the file has no sound")); + } + let flags = u16_at(810); + if flags & 0x10 != 0 { + return Err(Error::Unsupported("IMA ADPCM sound")); + } + let length = u16_at(806) as i16; + let frame_length = usize::from(length.unsigned_abs()); + // old-style stereo counts both channels, new-style one + let (channels, block_total) = match flags { + f if f & 0x8000 != 0 => (2, frame_length & !1), + f if f & 0x200 != 0 => (2, frame_length * 2), + _ => (1, frame_length), + }; + Ok(Decoder { sample_rate: u32::from(u16_at(804)), channels, sixteen_bit: length < 0, block_total }) + } + + /// Samples a second. + pub fn sample_rate(&self) -> u32 { + self.sample_rate + } + + /// 1 or 2. + pub fn channels(&self) -> usize { + self.channels + } + + /// Bits a sample in the file: 8 (PCM) or 16 (DPCM). The decoder returns `i16` for both. + pub fn bits(&self) -> u8 { + if self.sixteen_bit { 16 } else { 8 } + } + + /// Samples of one block for each channel. + pub fn block_samples(&self) -> usize { + self.block_total / self.channels + } + + /// Bytes of one block of sound in a frame. + pub fn block_bytes(&self) -> usize { + if self.sixteen_bit { (self.block_total + self.channels).min(self.block_total * 2) } else { self.block_total } + } + + /// Decode one sound frame: `flags` is the frame's flag byte from its record, `data` the + /// frame data. Returns interleaved samples, [`Decoder::block_samples`] for each channel and + /// block. + /// + /// - flags 1: one block of sound (every whole block, if the frame holds more); + /// - flags 2: a 32-bit mask, then blocks of sound: the sound a player loads ahead at the + /// start of a file. From bit 0 up, a set bit is a block of silence and a clear bit the next + /// block of data, while there is one. ffmpeg plays the silent blocks first instead; + /// the order here is the description's; + /// - flags 3: one block of silence. + /// + /// An empty frame gives no samples. With flags 1, a first block cut short is an error. A part + /// of a block after the last whole one is left out, with flags 1 and 2. + /// + /// The sound of a file is its sound frames decoded in file order and played end to end from + /// the first picture on: see `craft_media::vmd` for how that lines up with the pictures. + pub fn decode(&self, flags: u8, data: &[u8]) -> Result, Error> { + let mut out = Vec::new(); + match flags { + 3 => out.resize(self.block_total, 0), + 1 | 2 if data.is_empty() => {} + 1 => { + // one block; a frame that holds more whole blocks plays them all, as in ffmpeg + self.block(data, &mut out)?; + let size = self.block_bytes(); + if size > 0 { + for more in data[size..].chunks_exact(size) { + self.block(more, &mut out)?; + } + } + } + 2 => { + let (mask, mut data) = data.split_first_chunk::<4>().ok_or(Error::Invalid("the silence mask is cut short"))?; + let mask = u32::from_le_bytes(*mask); + // bit by bit: a set bit is a silent block, a clear one takes the next block of data + // while there is one. The header's buffer count is not needed: game files hold + // one block fewer than it says. + for i in 0..32 { + if mask >> i & 1 == 1 { + out.resize(out.len() + self.block_total, 0); + } else if !data.is_empty() && data.len() >= self.block_bytes() { + self.block(data, &mut out)?; + data = &data[self.block_bytes()..]; + } + } + } + _ => return Err(Error::Unsupported("unknown sound frame flags")), + } + Ok(out) + } + + /// Decode the block at the start of `data` onto `out`. + fn block(&self, data: &[u8], out: &mut Vec) -> Result<(), Error> { + let data = data.get(..self.block_bytes()).ok_or(Error::Invalid("a block of sound is cut short"))?; + if !self.sixteen_bit { + out.extend(data.iter().map(|&b| (i16::from(b) - 0x80) << 8)); + return Ok(()); + } + // each channel's first sample as it is, then a signed step for each further sample + let mut last = [0i32; 2]; + let Some((first, codes)) = data.split_at_checked(self.channels * 2) else { return Ok(()) }; + for (ch, s) in first.as_chunks::<2>().0.iter().enumerate() { + last[ch] = i32::from(i16::from_le_bytes(*s)); + out.push(last[ch] as i16); + } + for (i, &code) in codes.iter().enumerate() { + let ch = i % self.channels; + let step = i32::from(STEPS[usize::from(code & 0x7F)]); + last[ch] = (if code & 0x80 != 0 { last[ch] - step } else { last[ch] + step }).clamp(-32768, 32767); + out.push(last[ch] as i16); + } + Ok(()) + } +} diff --git a/crates/audio/src/vorbis/decoder/bits.rs b/crates/audio/src/vorbis/decoder/bits.rs new file mode 100644 index 000000000..6735d3d3d --- /dev/null +++ b/crates/audio/src/vorbis/decoder/bits.rs @@ -0,0 +1,96 @@ +//! The Vorbis bit reader (Vorbis I §2): bits are taken least significant first from each byte. + +/// Reading past the end of the packet ("end-of-packet", §2.1.8). +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub(super) struct Eop; + +pub(super) struct BitReader<'a> { + data: &'a [u8], + /// The position of the next bit. + pos: usize, +} + +impl<'a> BitReader<'a> { + pub(super) fn new(data: &'a [u8]) -> Self { + Self { data, pos: 0 } + } + + /// The bits not yet read. + pub(super) fn remaining(&self) -> usize { + (self.data.len() * 8).saturating_sub(self.pos) + } + + /// Read `n` (at most 32) bits as an unsigned integer. A read that does not fit takes nothing. + pub(super) fn read(&mut self, n: u32) -> Result { + if n == 0 { + return Ok(0); + } + if (n as usize) > self.remaining() { + self.pos = self.data.len() * 8; + return Err(Eop); + } + let mut value = 0u64; + let mut got = 0u32; + while got < n { + let byte = u64::from(self.data[self.pos / 8]); + let shift = (self.pos % 8) as u32; + let take = (8 - shift).min(n - got); + value |= ((byte >> shift) & ((1 << take) - 1)) << got; + got += take; + self.pos += take as usize; + } + Ok(value as u32) + } + + pub(super) fn bit(&mut self) -> Result { + Ok(self.read(1)? == 1) + } +} + +/// `ilog(x)` (§9.2.1): the position of the highest set bit, 0 for values below 1. +pub(super) fn ilog(x: i64) -> u32 { + if x <= 0 { 0 } else { 64 - (x as u64).leading_zeros() } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn reads_least_significant_bit_first() { + // Fields come out of each byte from its least significant bit. + let mut r = BitReader::new(&[0xFC, 0x08]); + assert_eq!(r.read(4), Ok(0xC)); + assert_eq!(r.read(4), Ok(0xF)); + assert_eq!(r.read(1), Ok(0)); + assert_eq!(r.read(3), Ok(4)); + assert_eq!(r.read(4), Ok(0)); + assert_eq!(r.read(1), Err(Eop)); + } + + #[test] + fn wide_reads_span_bytes_and_zero_bits_are_free() { + let mut r = BitReader::new(&[0x01, 0x02, 0x03, 0x04, 0x05]); + assert_eq!(r.read(0), Ok(0)); + assert_eq!(r.read(32), Ok(0x0403_0201)); + assert_eq!(r.read(8), Ok(5)); + assert_eq!(r.read(0), Ok(0)); + assert_eq!(r.read(1), Err(Eop)); + assert_eq!(r.remaining(), 0); + } + + #[test] + fn a_failed_read_consumes_the_rest() { + let mut r = BitReader::new(&[0xFF]); + assert_eq!(r.read(3), Ok(7)); + assert_eq!(r.read(6), Err(Eop)); + assert_eq!(r.read(1), Err(Eop)); + } + + #[test] + fn ilog_matches_the_specification_examples() { + for (x, want) in [(0, 0), (1, 1), (2, 2), (3, 2), (4, 3), (7, 3), (-5, 0), (255, 8), (256, 9)] { + assert_eq!(ilog(x), want, "ilog({x})"); + } + } +} diff --git a/crates/audio/src/vorbis/decoder/codebook.rs b/crates/audio/src/vorbis/decoder/codebook.rs new file mode 100644 index 000000000..9d083c9e4 --- /dev/null +++ b/crates/audio/src/vorbis/decoder/codebook.rs @@ -0,0 +1,409 @@ +//! Codebooks (Vorbis I §3): a Huffman code over entry numbers and an optional table of vectors. + +use super::Error; +use super::bits::{BitReader, Eop, ilog}; + +const NONE: u32 = u32::MAX; +const LEAF: u32 = 1 << 31; +/// Entries a codebook may declare. +const MAX_ENTRIES: u32 = 1 << 20; +/// Nodes of one codeword tree. +const MAX_NODES: usize = 1 << 22; + +#[derive(Clone, Copy)] +struct Node { + child: [u32; 2], + full: bool, +} + +pub(super) struct Codebook { + pub(super) dimensions: usize, + pub(super) entries: usize, + tree: Vec, + /// The only used entry of a single-entry book. + single: Option, + /// `entries * dimensions` values when the book has a lookup table. + vectors: Vec, +} + +/// `float32_unpack` (§9.2.2). +fn float32_unpack(x: u32) -> f64 { + let mantissa = f64::from(x & 0x001F_FFFF); + let exponent = ((x & 0x7FE0_0000) >> 21) as i32; + let m = if x & 0x8000_0000 != 0 { -mantissa } else { mantissa }; + m * 2f64.powi(exponent - 788) +} + +/// `lookup1_values` (§9.2.3): the greatest `v` with `v^dimensions <= entries`. +fn lookup1_values(entries: u32, dimensions: u32) -> u32 { + let mut v = 1u32; + loop { + let next = u128::from(v) + 1; + let mut p = 1u128; + for _ in 0..dimensions { + p *= next; + if p > u128::from(entries) { + return v; + } + } + v += 1; + } +} + +fn insert(tree: &mut Vec, at: usize, depth: u32, len: u32, entry: u32) -> bool { + for b in 0..2 { + let child = tree[at].child[b]; + if depth + 1 == len { + if child == NONE { + tree[at].child[b] = LEAF | entry; + refresh(tree, at); + return true; + } + continue; + } + if child == NONE { + if tree.len() >= MAX_NODES { + return false; + } + tree.push(Node { child: [NONE; 2], full: false }); + let new = tree.len() - 1; + tree[at].child[b] = new as u32; + if insert(tree, new, depth + 1, len, entry) { + refresh(tree, at); + return true; + } + return false; + } + if child & LEAF != 0 || tree[child as usize].full { + continue; + } + if insert(tree, child as usize, depth + 1, len, entry) { + refresh(tree, at); + return true; + } + } + false +} + +fn refresh(tree: &mut [Node], at: usize) { + let done = |c: u32, t: &[Node]| c != NONE && (c & LEAF != 0 || t[c as usize].full); + let full = done(tree[at].child[0], tree) && done(tree[at].child[1], tree); + tree[at].full = full; +} + +impl Codebook { + /// Read one codebook from a setup header. `budget` is the bytes the setup's codebooks may + /// still take in all. + pub(super) fn read(r: &mut BitReader<'_>, budget: &mut usize) -> Result { + let bad = |m: &'static str| Error::Setup(m); + let eop = |_: Eop| Error::Setup("setup header ends inside a codebook"); + if r.read(24).map_err(eop)? != 0x0056_4342 { + return Err(bad("codebook sync pattern missing")); + } + let dimensions = r.read(16).map_err(eop)?; + let entries = r.read(24).map_err(eop)?; + if dimensions == 0 || entries == 0 || entries > MAX_ENTRIES { + return Err(bad("codebook with no dimensions, no entries or too many")); + } + let mut lengths: Vec = Vec::with_capacity(entries as usize); + if r.bit().map_err(eop)? { + // Ordered: the number of codewords of each length. + let mut current = 0u32; + let mut len = r.read(5).map_err(eop)? + 1; + while current < entries { + let number = r.read(ilog(i64::from(entries - current))).map_err(eop)?; + if number > entries - current || len > 32 { + return Err(bad("ordered codebook lengths overrun the entries")); + } + lengths.extend(std::iter::repeat_n(len as u8, number as usize)); + current += number; + len += 1; + } + } else { + let sparse = r.bit().map_err(eop)?; + for _ in 0..entries { + if sparse && !r.bit().map_err(eop)? { + lengths.push(0); + } else { + lengths.push((r.read(5).map_err(eop)? + 1) as u8); + } + } + } + + // The codeword tree. + let used = lengths.iter().filter(|&&l| l != 0).count(); + let mut tree = vec![Node { child: [NONE; 2], full: false }]; + let mut single = None; + if used == 1 { + let entry = lengths.iter().position(|&l| l != 0).unwrap_or(0); + if lengths[entry] != 1 { + return Err(bad("a codebook with one used entry must give it length 1")); + } + single = Some(entry as u32); + } else if used > 1 { + for (entry, &len) in lengths.iter().enumerate() { + if len != 0 && !insert(&mut tree, 0, 0, u32::from(len), entry as u32) { + return Err(bad("overspecified codebook")); + } + } + if !tree[0].full { + return Err(bad("underspecified codebook")); + } + } + let tree_bytes = tree.len() * std::mem::size_of::(); + if tree_bytes > *budget { + return Err(Error::Limit("the codebooks are too large")); + } + *budget -= tree_bytes; + + // The lookup table. + let lookup_type = r.read(4).map_err(eop)?; + let mut vectors = Vec::new(); + if lookup_type > 2 { + return Err(bad("reserved codebook lookup type")); + } + if lookup_type != 0 { + let minimum = float32_unpack(r.read(32).map_err(eop)?); + let delta = float32_unpack(r.read(32).map_err(eop)?); + let value_bits = r.read(4).map_err(eop)? + 1; + let sequence = r.bit().map_err(eop)?; + // Check before multiplying or reading multiplicands: the product can overflow + // usize on 32-bit targets, and a type-2 table otherwise allocates before admission. + let total = (entries as usize) + .checked_mul(dimensions as usize) + .filter(|&n| n <= *budget / std::mem::size_of::()) + .ok_or(Error::Limit("the codebooks' vector tables are too large"))?; + let values = if lookup_type == 1 { lookup1_values(entries, dimensions) as usize } else { total }; + if !minimum.is_finite() || !delta.is_finite() || values > r.remaining() / value_bits as usize { + return Err(bad("codebook lookup table is damaged or truncated")); + } + let multiplicands: Vec = (0..values).map(|_| r.read(value_bits).unwrap_or(0)).collect(); + *budget -= total * std::mem::size_of::(); + vectors = vec![0f32; total]; + for e in 0..entries as usize { + let out = &mut vectors[e * dimensions as usize..(e + 1) * dimensions as usize]; + let mut last = 0f64; + let mut divisor = 1usize; + for (i, slot) in out.iter_mut().enumerate() { + let m = if lookup_type == 1 { + let at = (e / divisor) % values; + divisor = divisor.saturating_mul(values); + multiplicands[at] + } else { + multiplicands[e * dimensions as usize + i] + }; + let v = f64::from(m) * delta + minimum + last; + if sequence { + last = v; + } + *slot = v as f32; + } + } + } + Ok(Self { dimensions: dimensions as usize, entries: entries as usize, tree, single, vectors }) + } + + /// Whether the book has a lookup table. + pub(super) fn has_vectors(&self) -> bool { + !self.vectors.is_empty() + } + + /// Read a codeword; the entry number (scalar context). + pub(super) fn scalar(&self, r: &mut BitReader<'_>) -> Result { + if let Some(e) = self.single { + r.read(1)?; + return Ok(e); + } + let mut at = 0usize; + loop { + let c = self.tree[at].child[usize::from(r.bit()?)]; + if c == NONE { + return Err(Eop); + } + if c & LEAF != 0 { + return Ok(c & !LEAF); + } + at = c as usize; + } + } + + /// Read a codeword and return its vector (VQ context); `None` for a book without a table. + pub(super) fn vector(&self, r: &mut BitReader<'_>) -> Result, Eop> { + let e = self.scalar(r)? as usize; + Ok(self.vectors.get(e * self.dimensions..(e + 1) * self.dimensions)) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + /// Pack fields least significant bit first. + struct W(Vec, usize); + impl W { + fn put(&mut self, v: u64, n: u32) { + for i in 0..n { + if self.1.is_multiple_of(8) { + self.0.push(0); + } + let last = self.0.len() - 1; + self.0[last] |= (((v >> i) & 1) as u8) << (self.1 % 8); + self.1 += 1; + } + } + } + + fn book_bytes(lengths: &[u32], lookup: Option<(u32, u32, &[u32])>) -> Vec { + let mut w = W(Vec::new(), 0); + w.put(0x56_4342, 24); + w.put(1, 16); + w.put(lengths.len() as u64, 24); + w.put(0, 1); // not ordered + w.put(0, 1); // not sparse + for &l in lengths { + w.put(u64::from(l - 1), 5); + } + match lookup { + None => w.put(0, 4), + Some((ty, bits, mult)) => { + w.put(u64::from(ty), 4); + w.put(0, 32); // minimum: 0.0 + w.put(0, 32); + w.put(u64::from(bits - 1), 4); + w.put(0, 1); + for &m in mult { + w.put(u64::from(m), bits); + } + } + } + w.0 + } + + #[test] + fn the_specification_example_assigns_its_codewords() { + // §3.2.1: lengths 2 4 4 4 4 2 3 3 -> 00, 0100, 0101, 0110, 0111, 10, 110, 111. + let bytes = book_bytes(&[2, 4, 4, 4, 4, 2, 3, 3], None); + let mut budget = 1 << 26; + let book = Codebook::read(&mut BitReader::new(&bytes), &mut budget).expect("book"); + let code = |bits: &[u8]| { + let mut w = W(Vec::new(), 0); + for &b in bits { + w.put(u64::from(b), 1); + } + let mut r = BitReader::new(&w.0); + book.scalar(&mut r).expect("entry") + }; + assert_eq!(code(&[0, 0]), 0); + assert_eq!(code(&[0, 1, 0, 0]), 1); + assert_eq!(code(&[0, 1, 1, 1]), 4); + assert_eq!(code(&[1, 0]), 5); + assert_eq!(code(&[1, 1, 0]), 6); + assert_eq!(code(&[1, 1, 1]), 7); + } + + #[test] + fn over_and_underspecified_books_are_errors() { + let mut budget = 1 << 26; + let over = book_bytes(&[1, 1, 1], None); + assert!(Codebook::read(&mut BitReader::new(&over), &mut budget).is_err()); + let under = book_bytes(&[2, 2, 2], None); + assert!(Codebook::read(&mut BitReader::new(&under), &mut budget).is_err()); + } + + #[test] + fn a_single_entry_book_sinks_one_bit_of_either_value() { + let mut budget = 1 << 26; + let bytes = book_bytes(&[1], None); + let book = Codebook::read(&mut BitReader::new(&bytes), &mut budget).expect("book"); + for byte in [0u8, 1] { + let data = [byte]; + let mut r = BitReader::new(&data); + assert_eq!(book.scalar(&mut r), Ok(0)); + assert_eq!(r.remaining(), 7); + } + let bad = book_bytes(&[2], None); + assert!(Codebook::read(&mut BitReader::new(&bad), &mut budget).is_err()); + } + + #[test] + fn lookup_type_one_builds_a_lattice() { + // 4 entries, 2 dimensions, 2 values per dimension: minimum 0 and delta 1 in the packed + // float format are written below by hand (mantissa 1, exponent 788 -> 1.0). + let mut w = W(Vec::new(), 0); + w.put(0x56_4342, 24); + w.put(2, 16); + w.put(4, 24); + w.put(0, 1); + w.put(0, 1); + for _ in 0..4 { + w.put(1, 5); // length 2 each + } + w.put(1, 4); // lookup type 1 + w.put(0, 32); // minimum 0 + w.put((788u64 << 21) | 1, 32); // delta 1.0 + w.put(0, 4); // 1 bit per value + w.put(0, 1); + w.put(0b10, 2); // multiplicands 0, 1 + let mut budget = 1 << 26; + let book = Codebook::read(&mut BitReader::new(&w.0), &mut budget).expect("book"); + assert_eq!(lookup1_values(4, 2), 2); + // Entry e is (m[e % 2], m[(e / 2) % 2]). + assert_eq!(book.vectors, vec![0.0, 0.0, 1.0, 0.0, 0.0, 1.0, 1.0, 1.0]); + } + + #[test] + fn vector_budget_is_checked_before_reading_lookup_values() { + // A valid single-entry tree, but two values exceed the remaining budget. + // No multiplicands follow: admission must reject it before reading them. + for lookup in [1, 2] { + let mut w = W(Vec::new(), 0); + w.put(0x56_4342, 24); + w.put(2, 16); + w.put(1, 24); + w.put(0, 1); + w.put(0, 1); + w.put(0, 5); + w.put(lookup, 4); + w.put(0, 32); + w.put(0, 32); + w.put(15, 4); + w.put(0, 1); + let mut budget = std::mem::size_of::() + 4; + assert!(matches!(Codebook::read(&mut BitReader::new(&w.0), &mut budget), Err(Error::Limit(_)))); + } + } + + #[test] + fn vector_size_that_overflows_32_bits_is_refused() { + for lookup in [1, 2] { + let mut w = W(Vec::new(), 0); + w.put(0x56_4342, 24); + w.put(65535, 16); + w.put(65538, 24); // product is above u32::MAX + w.put(0, 1); // unordered + w.put(1, 1); // sparse: only one entry is used + w.put(1, 1); + w.put(0, 5); // length 1 + for _ in 1..65538 { + w.put(0, 1); + } + w.put(lookup, 4); + w.put(0, 32); + w.put(0, 32); + w.put(0, 4); + w.put(0, 1); + w.put(0, 1); // lookup type 1's single multiplicand + let mut budget = 256 << 20; + assert!(matches!(Codebook::read(&mut BitReader::new(&w.0), &mut budget), Err(Error::Limit(_)))); + } + } + + #[test] + fn helper_functions() { + assert_eq!(float32_unpack((788u32 << 21) | 5), 5.0); + assert_eq!(float32_unpack(0x8000_0000 | (789u32 << 21) | 3), -6.0); + for (entries, dims, want) in [(8, 3, 2), (9, 2, 3), (1, 5, 1), (10, 1, 10), (1000, 3, 10), (4_000_000, 2, 2000)] { + assert_eq!(lookup1_values(entries, dims), want, "{entries} entries, {dims} dims"); + } + } +} diff --git a/crates/audio/src/vorbis/decoder/floor.rs b/crates/audio/src/vorbis/decoder/floor.rs new file mode 100644 index 000000000..bc6ce4e36 --- /dev/null +++ b/crates/audio/src/vorbis/decoder/floor.rs @@ -0,0 +1,385 @@ +//! Floors (Vorbis I §6 and §7): the spectral envelope each channel's residue is multiplied by. + +use super::Error; +use super::bits::{BitReader, Eop, ilog}; +use super::codebook::Codebook; +use super::tables::INVERSE_DB; + +/// Why a floor could not be decoded from a packet. +pub(super) enum Fail { + /// The packet ended (a nominal event: the channel is silent). + Eop, + /// The packet names a codebook that does not exist: it cannot be decoded (§6.2.2). + Invalid, +} + +impl From for Fail { + fn from(_: Eop) -> Self { + Fail::Eop + } +} + +/// What a decoded floor gives to synthesis. +pub(super) enum FloorData { + One { y: Vec, step2: Vec }, + Zero { amplitude: u32, coefficients: Vec }, +} + +pub(super) struct Floor0 { + order: usize, + rate: u32, + bark_map_size: u32, + amplitude_bits: u32, + amplitude_offset: u32, + books: Vec, +} + +pub(super) struct Floor1 { + partition_class: Vec, + class_dimensions: Vec, + class_subclasses: Vec, + class_masterbook: Vec, + subclass_books: Vec>, + multiplier: i32, + range: i32, + xlist: Vec, + /// `(low, high)` neighbour positions of each X from index 2 on. + neighbours: Vec<(usize, usize)>, + /// Indices of `xlist` in ascending X order. + sorted: Vec, +} + +pub(super) enum Floor { + Zero(Floor0), + One(Floor1), +} + +fn eop(_: Eop) -> Error { + Error::Setup("setup header ends inside a floor") +} + +impl Floor { + pub(super) fn read(floor_type: u32, r: &mut BitReader<'_>, books: &[Codebook]) -> Result { + match floor_type { + 0 => { + let order = r.read(8).map_err(eop)? as usize; + let rate = r.read(16).map_err(eop)?; + let bark_map_size = r.read(16).map_err(eop)?; + let amplitude_bits = r.read(6).map_err(eop)?; + let amplitude_offset = r.read(8).map_err(eop)?; + let count = r.read(4).map_err(eop)? as usize + 1; + let mut list = Vec::with_capacity(count); + for _ in 0..count { + let b = r.read(8).map_err(eop)? as usize; + match books.get(b) { + Some(book) if book.has_vectors() => list.push(b), + _ => return Err(Error::Setup("floor 0 names a missing codebook or one without vectors")), + } + } + if order == 0 || rate == 0 || bark_map_size == 0 || amplitude_bits > 32 { + return Err(Error::Setup("floor 0 with a zero order, rate or map size, or more than 32 amplitude bits")); + } + Ok(Self::Zero(Floor0 { order, rate, bark_map_size, amplitude_bits, amplitude_offset, books: list })) + } + 1 => { + let partitions = r.read(5).map_err(eop)? as usize; + let mut partition_class = Vec::with_capacity(partitions); + for _ in 0..partitions { + partition_class.push(r.read(4).map_err(eop)? as usize); + } + let classes = partition_class.iter().max().map_or(0, |m| m + 1); + let (mut class_dimensions, mut class_subclasses, mut class_masterbook, mut subclass_books) = (vec![], vec![], vec![], vec![]); + for _ in 0..classes { + class_dimensions.push(r.read(3).map_err(eop)? as usize + 1); + let subs = r.read(2).map_err(eop)?; + class_subclasses.push(subs); + let master = if subs != 0 { r.read(8).map_err(eop)? as usize } else { 0 }; + if subs != 0 && master >= books.len() { + return Err(Error::Setup("floor 1 master book out of range")); + } + class_masterbook.push(master); + let mut list = Vec::new(); + for _ in 0..(1u32 << subs) { + let b = r.read(8).map_err(eop)? as i32 - 1; + if b >= books.len() as i32 { + return Err(Error::Setup("floor 1 subclass book out of range")); + } + list.push(b); + } + subclass_books.push(list); + } + let multiplier = r.read(2).map_err(eop)? as i32 + 1; + let rangebits = r.read(4).map_err(eop)?; + let mut xlist = vec![0, 1i32 << rangebits]; + for &c in &partition_class { + for _ in 0..class_dimensions[c] { + xlist.push(r.read(rangebits).map_err(eop)? as i32); + } + } + if xlist.len() > 65 { + return Err(Error::Setup("floor 1 has more than 65 points")); + } + let mut seen = xlist.clone(); + seen.sort_unstable(); + if seen.windows(2).any(|w| w[0] == w[1]) { + return Err(Error::Setup("floor 1 repeats an X position")); + } + // Low and high neighbours (§9.2.4, §9.2.5) of each point, among those before it. + let mut neighbours = Vec::new(); + for i in 2..xlist.len() { + let (mut lo, mut hi) = (0usize, 1usize); + for j in 0..i { + if xlist[j] < xlist[i] && xlist[j] > xlist[lo] { + lo = j; + } + if xlist[j] > xlist[i] && xlist[j] < xlist[hi] { + hi = j; + } + } + neighbours.push((lo, hi)); + } + let mut sorted: Vec = (0..xlist.len()).collect(); + sorted.sort_by_key(|&i| xlist[i]); + let range = [256, 128, 86, 64][multiplier as usize - 1]; + Ok(Self::One(Floor1 { + partition_class, + class_dimensions, + class_subclasses, + class_masterbook, + subclass_books, + multiplier, + range, + xlist, + neighbours, + sorted, + })) + } + _ => Err(Error::Setup("unknown floor type")), + } + } + + /// Decode one channel's floor from a packet: `None` when the channel is unused this block. + pub(super) fn decode(&self, r: &mut BitReader<'_>, books: &[Codebook]) -> Result, Fail> { + match self { + Self::One(f) => Ok(f.decode(r, books)?), + Self::Zero(f) => f.decode(r, books), + } + } + + /// The floor curve over `n` bins (`n` is half the block size). + pub(super) fn curve(&self, data: &FloorData, n: usize) -> Vec { + match (self, data) { + (Self::One(f), FloorData::One { y, step2 }) => f.curve(y, step2, n), + (Self::Zero(f), FloorData::Zero { amplitude, coefficients }) => f.curve(*amplitude, coefficients, n), + _ => vec![0.0; n], + } + } +} + +/// `render_point` (§9.2.6). +fn render_point(x0: i32, y0: i32, x1: i32, y1: i32, x: i32) -> i32 { + let dy = i64::from(y1 - y0); + let adx = i64::from(x1 - x0); + let err = dy.abs() * i64::from(x - x0); + let off = (err / adx) as i32; + if dy < 0 { y0 - off } else { y0 + off } +} + +/// `render_line` (§9.2.7), writing the bins that fall inside `v`. +fn render_line(x0: i32, y0: i32, x1: i32, y1: i32, v: &mut [i32]) { + let dy = y1 - y0; + let adx = x1 - x0; + let base = dy / adx; + let ady = dy.abs() - base.abs() * adx; + let sy = if dy < 0 { base - 1 } else { base + 1 }; + let (mut y, mut err) = (y0, 0); + if let Some(slot) = usize::try_from(x0).ok().and_then(|x| v.get_mut(x)) { + *slot = y; + } + for x in x0 + 1..x1 { + err += ady; + if err >= adx { + err -= adx; + y += sy; + } else { + y += base; + } + match usize::try_from(x).ok().and_then(|x| v.get_mut(x)) { + Some(slot) => *slot = y, + None => break, + } + } +} + +impl Floor1 { + fn decode(&self, r: &mut BitReader<'_>, books: &[Codebook]) -> Result, Eop> { + if !r.bit()? { + return Ok(None); + } + let bits = ilog(i64::from(self.range) - 1); + let mut y = vec![0i32; self.xlist.len()]; + y[0] = r.read(bits)? as i32; + y[1] = r.read(bits)? as i32; + let mut offset = 2usize; + for &class in &self.partition_class { + let cdim = self.class_dimensions[class]; + let cbits = self.class_subclasses[class]; + let csub = (1u32 << cbits) - 1; + let mut cval = 0u32; + if cbits > 0 { + cval = books[self.class_masterbook[class]].scalar(r)?; + } + for j in 0..cdim { + let book = self.subclass_books[class][(cval & csub) as usize]; + cval >>= cbits; + y[offset + j] = if book >= 0 { books[book as usize].scalar(r)? as i32 } else { 0 }; + } + offset += cdim; + } + + // Step 1: amplitude synthesis (§7.2.4). + let mut step2 = vec![false; self.xlist.len()]; + step2[0] = true; + step2[1] = true; + let mut fin = y.clone(); + for i in 2..self.xlist.len() { + let (lo, hi) = self.neighbours[i - 2]; + let predicted = render_point(self.xlist[lo], fin[lo], self.xlist[hi], fin[hi], self.xlist[i]); + let val = y[i]; + let highroom = self.range - predicted; + let lowroom = predicted; + let room = if highroom < lowroom { highroom * 2 } else { lowroom * 2 }; + if val != 0 { + step2[lo] = true; + step2[hi] = true; + step2[i] = true; + fin[i] = if val >= room { + if highroom > lowroom { val - lowroom + predicted } else { predicted - val + highroom - 1 } + } else if val % 2 == 1 { + predicted - (val + 1) / 2 + } else { + predicted + val / 2 + }; + } else { + fin[i] = predicted; + } + // Valid setups never leave the range; a damaged one must not carry out-of-range values on. + fin[i] = fin[i].clamp(0, self.range - 1); + } + Ok(Some(FloorData::One { y: fin, step2 })) + } + + fn curve(&self, fin: &[i32], step2: &[bool], n: usize) -> Vec { + let mut floor = vec![0i32; n]; + let (mut hx, mut hy) = (0i32, 0i32); + let (mut lx, mut ly) = (0i32, fin[self.sorted[0]] * self.multiplier); + for &i in &self.sorted[1..] { + if step2[i] { + hy = fin[i] * self.multiplier; + hx = self.xlist[i]; + render_line(lx, ly, hx, hy, &mut floor); + lx = hx; + ly = hy; + } + } + if (hx as usize) < n { + render_line(hx, hy, n as i32, hy, &mut floor); + } + floor.iter().map(|&v| INVERSE_DB[v.clamp(0, 255) as usize]).collect() + } +} + +impl Floor0 { + fn decode(&self, r: &mut BitReader<'_>, books: &[Codebook]) -> Result, Fail> { + let amplitude = r.read(self.amplitude_bits)?; + if amplitude == 0 { + return Ok(None); + } + let book = r.read(ilog(self.books.len() as i64))? as usize; + let Some(&book) = self.books.get(book) else { return Err(Fail::Invalid) }; + let book = &books[book]; + let mut coefficients: Vec = Vec::with_capacity(self.order + book.dimensions); + let mut last = 0f32; + while coefficients.len() < self.order { + let Some(v) = book.vector(r)? else { return Err(Fail::Invalid) }; + coefficients.extend(v.iter().map(|&x| x + last)); + last = coefficients[coefficients.len() - 1]; + } + Ok(Some(FloorData::Zero { amplitude, coefficients })) + } + + fn curve(&self, amplitude: u32, coefficients: &[f32], n: usize) -> Vec { + let bark = |x: f64| 13.1 * (0.00074 * x).atan() + 2.24 * (0.000_000_018_5 * x * x).atan() + 0.0001 * x; + let scale = f64::from(self.bark_map_size) / bark(0.5 * f64::from(self.rate)); + let map: Vec = (0..n) + .map(|i| { + let foobar = (bark(f64::from(self.rate) * i as f64 / (2.0 * n as f64)) * scale).floor() as i64; + foobar.min(i64::from(self.bark_map_size) - 1) + }) + .collect(); + let cos_c: Vec = coefficients.iter().take(self.order).map(|&c| f64::from(c).cos()).collect(); + let amp = f64::from(amplitude); + let offset = f64::from(self.amplitude_offset); + let top = (2f64).powi(self.amplitude_bits as i32) - 1.0; + let mut out = vec![0f32; n]; + let mut i = 0usize; + while i < n { + let omega = std::f64::consts::PI * map[i] as f64 / f64::from(self.bark_map_size); + let cw = omega.cos(); + let (p, q); + if self.order % 2 == 1 { + let mut pp = 1.0 - cw * cw; + for j in 0..(self.order - 1) / 2 { + let d = cos_c[2 * j + 1] - cw; + pp *= 4.0 * d * d; + } + let mut qq = 0.25; + for j in 0..=(self.order - 1) / 2 { + let d = cos_c[2 * j] - cw; + qq *= 4.0 * d * d; + } + p = pp; + q = qq; + } else { + let mut pp = (1.0 - cw) / 2.0; + let mut qq = (1.0 + cw) / 2.0; + for j in 0..self.order / 2 { + let d1 = cos_c[2 * j + 1] - cw; + pp *= 4.0 * d1 * d1; + let d0 = cos_c[2 * j] - cw; + qq *= 4.0 * d0 * d0; + } + p = pp; + q = qq; + } + let linear = (0.115_129_25 * (amp * offset / (top * (p + q).sqrt()) - offset)).exp() as f32; + let key = map[i]; + while i < n && map[i] == key { + out[i] = linear; + i += 1; + } + } + out + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn render_line_matches_a_bresenham_walk() { + let mut v = vec![0i32; 16]; + render_line(0, 0, 8, 4, &mut v); + assert_eq!(&v[..8], &[0, 0, 1, 1, 2, 2, 3, 3]); + let mut v = vec![0i32; 16]; + render_line(2, 10, 6, 2, &mut v); + assert_eq!(&v[2..6], &[10, 8, 6, 4]); + // Lines running past the vector stop at its end. + let mut v = vec![0i32; 4]; + render_line(0, 0, 100, 100, &mut v); + assert_eq!(v, vec![0, 1, 2, 3]); + assert_eq!(render_point(0, 0, 10, 10, 5), 5); + assert_eq!(render_point(0, 10, 10, 0, 5), 5); + } +} diff --git a/crates/audio/src/vorbis/decoder/mdct.rs b/crates/audio/src/vorbis/decoder/mdct.rs new file mode 100644 index 000000000..b4eb6c8ec --- /dev/null +++ b/crates/audio/src/vorbis/decoder/mdct.rs @@ -0,0 +1,164 @@ +//! The inverse MDCT of a block (Vorbis I §4.3.7) and the window slopes. +//! +//! `y[j] = sum_k X[k] cos(2*pi/n * (j + 1/2 + n/4) * (k + 1/2))` for `n/2` coefficients and `n` +//! samples, computed as a DCT-IV of the coefficients through an `n/8`-point complex FFT, then +//! unfolded. + +use std::f64::consts::PI; + +#[derive(Clone, Copy, Default)] +struct Cpx { + re: f64, + im: f64, +} + +impl Cpx { + fn mul(self, o: Cpx) -> Cpx { + Cpx { re: self.re * o.re - self.im * o.im, im: self.re * o.im + self.im * o.re } + } +} + +fn cis(t: f64) -> Cpx { + Cpx { re: t.cos(), im: t.sin() } +} + +pub(super) struct Imdct { + n: usize, + twiddle: Vec, + post: Vec, + fft_tw: Vec, + rev: Vec, +} + +impl Imdct { + /// For blocks of `n` samples, a power of two of at least 16. + pub(super) fn new(n: usize) -> Self { + let m = n / 2; + let h = m / 2; + let twiddle = (0..h).map(|j| cis(-PI * (4.0 * j as f64 + 1.0) / (4.0 * m as f64))).collect(); + let post = (0..h).map(|k| cis(-PI * k as f64 / m as f64)).collect(); + let fft_tw = (0..h / 2).map(|j| cis(-2.0 * PI * j as f64 / h as f64)).collect(); + let bits = h.trailing_zeros(); + let rev = (0..h).map(|i| if bits == 0 { 0 } else { i.reverse_bits() >> (usize::BITS - bits) }).collect(); + Self { n, twiddle, post, fft_tw, rev } + } + + /// `x`: `n/2` coefficients; `out`: `n` samples. + pub(super) fn inverse(&self, x: &[f32], out: &mut [f32]) { + let m = self.n / 2; + let q = self.n / 4; + let h = m / 2; + let mut z: Vec = (0..h).map(|j| Cpx { re: f64::from(x[2 * j]), im: f64::from(x[m - 1 - 2 * j]) }.mul(self.twiddle[j])).collect(); + self.fft(&mut z); + let mut v = vec![0f64; m]; + for (k, c) in z.iter().enumerate() { + let d = c.mul(self.post[k]); + v[2 * k] = d.re; + v[m - 1 - 2 * k] = -d.im; + } + // Unfold the DCT-IV output to the block. + for i in 0..q { + out[3 * q - 1 - i] = (-v[i]) as f32; + out[3 * q + i] = (-v[i]) as f32; + } + for i in q..2 * q { + out[i - q] = v[i] as f32; + out[3 * q - 1 - i] = (-v[i]) as f32; + } + } + + fn fft(&self, a: &mut [Cpx]) { + let h = a.len(); + for (i, &j) in self.rev.iter().enumerate() { + if i < j { + a.swap(i, j); + } + } + let mut len = 2; + while len <= h { + let step = h / len; + for start in (0..h).step_by(len) { + for k in 0..len / 2 { + let w = self.fft_tw[k * step]; + let u = a[start + k]; + let t = a[start + k + len / 2].mul(w); + a[start + k] = Cpx { re: u.re + t.re, im: u.im + t.im }; + a[start + k + len / 2] = Cpx { re: u.re - t.re, im: u.im - t.im }; + } + } + len *= 2; + } + } +} + +/// The rising half of the Vorbis window over `len` samples (§4.3.1): +/// `sin(pi/2 * sin^2((i + 0.5) / len * pi/2))`. +pub(super) fn slope(len: usize) -> Vec { + (0..len) + .map(|i| { + let s = (PI / 2.0 * (i as f64 + 0.5) / len as f64).sin(); + (PI / 2.0 * s * s).sin() as f32 + }) + .collect() +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn matches_the_direct_formula() { + for n in [16usize, 64, 256, 2048] { + let x: Vec = (0..n / 2).map(|i| ((i * 7919 % 211) as f32 - 105.0) / 50.0).collect(); + let mut fast = vec![0f32; n]; + Imdct::new(n).inverse(&x, &mut fast); + for j in [0usize, 1, 2, n / 4, n / 2, n - 1] { + let direct: f64 = + (0..n / 2).map(|k| f64::from(x[k]) * (2.0 * PI / n as f64 * (j as f64 + 0.5 + n as f64 / 4.0) * (k as f64 + 0.5)).cos()).sum(); + assert!((direct - f64::from(fast[j])).abs() < 1e-3 * (1.0 + direct.abs()), "n={n} j={j}: {direct} vs {}", fast[j]); + } + } + } + + #[test] + fn windowed_overlap_add_reconstructs_the_signal() { + // Forward MDCT by the definition with the 2/M scale an encoder uses, then this inverse. + let n = 64usize; + let m = n / 2; + let signal: Vec = (0..n * 6).map(|i| ((i * 37 % 101) as f64 - 50.0) / 50.0).collect(); + let w: Vec = slope(m).into_iter().chain(slope(m).into_iter().rev()).collect(); + let imdct = Imdct::new(n); + let mut out = vec![0f64; signal.len()]; + let mut start = 0; + while start + n <= signal.len() { + let coeffs: Vec = (0..m) + .map(|k| { + let s: f64 = (0..n) + .map(|j| { + signal[start + j] * f64::from(w[j]) * (2.0 * PI / n as f64 * (j as f64 + 0.5 + n as f64 / 4.0) * (k as f64 + 0.5)).cos() + }) + .sum(); + (s * 2.0 / m as f64) as f32 + }) + .collect(); + let mut y = vec![0f32; n]; + imdct.inverse(&coeffs, &mut y); + for j in 0..n { + out[start + j] += f64::from(y[j]) * f64::from(w[j]); + } + start += m; + } + for i in m..signal.len() - m { + assert!((out[i] - signal[i]).abs() < 1e-4, "sample {i}: {} vs {}", out[i], signal[i]); + } + } + + #[test] + fn the_slope_is_power_complementary() { + let s = slope(1024); + for i in 0..1024 { + let sum = s[i] * s[i] + s[1023 - i] * s[1023 - i]; + assert!((sum - 1.0).abs() < 1e-5, "{i}: {sum}"); + } + } +} diff --git a/crates/audio/src/vorbis/decoder/mod.rs b/crates/audio/src/vorbis/decoder/mod.rs new file mode 100644 index 000000000..7485e34b8 --- /dev/null +++ b/crates/audio/src/vorbis/decoder/mod.rs @@ -0,0 +1,552 @@ +//! A clean-room Vorbis I decoder (feature `vorbis-decode`), written from the Vorbis I +//! specification (Xiph.Org, 2020). +//! +//! [`Decoder`] works on packets: build it from the three header packets (identification, comment +//! and setup), then give it audio packets in order. Each call returns the PCM the packet +//! completes, planar `f32` in the nominal range -1.0 to 1.0 (not clipped), channels in the order of +//! the stream. The first packet only primes the overlap and returns nothing. [`decode_ogg`] reads a +//! whole Ogg Vorbis file. +//! +//! Codebooks, floors 0 and 1, residues 0, 1 and 2, channel coupling and both block sizes with their +//! hybrid windows are implemented. Damaged input is an error, never a panic: setup sizes are +//! bounded before anything is allocated, and the codeword trees are checked for completeness. + +mod bits; +mod codebook; +mod floor; +mod mdct; +mod residue; +mod tables; + +use bits::{BitReader, Eop, ilog}; +use codebook::Codebook; +use floor::{Fail, Floor, FloorData}; +use mdct::{Imdct, slope}; +use residue::Residue; + +/// Errors of the Vorbis decoder. +#[non_exhaustive] +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum Error { + /// The identification or comment header is not valid Vorbis. + #[error("invalid Vorbis header: {0}")] + Header(&'static str), + /// The setup header is damaged or uses something Vorbis I does not allow. + #[error("invalid Vorbis setup: {0}")] + Setup(&'static str), + /// The setup or decoded PCM asks for more memory than the decoder allows. + #[error("Vorbis decode above the limits: {0}")] + Limit(&'static str), + /// The packet is not an audio packet (a header, or a packet with its first bit set). + #[error("not an audio packet")] + NotAudio, + /// The packet is damaged: it ends before its mode and window flags are read, or names a mode + /// that does not exist. + #[error("damaged audio packet: {0}")] + Packet(&'static str), + /// An Ogg file with no Vorbis stream, or one that cannot be read. + #[error("Ogg Vorbis file: {0}")] + Ogg(String), +} + +/// `Result` of this module. +pub type Result = std::result::Result; + +/// The identification header (§4.2.2). +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub struct Identification { + /// The channel count, at least 1. + pub channels: u8, + /// Samples per second per channel. + pub sample_rate: u32, + /// The maximum bit rate in bits per second, 0 or negative when not set. + pub bitrate_maximum: i32, + /// The nominal bit rate in bits per second, 0 or negative when not set. + pub bitrate_nominal: i32, + /// The minimum bit rate in bits per second, 0 or negative when not set. + pub bitrate_minimum: i32, + /// The short block size in samples. + pub blocksize_0: u32, + /// The long block size in samples. + pub blocksize_1: u32, +} + +/// The comment header (§5): a vendor string and `NAME=value` comments. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct Comments { + /// The vendor string of the encoder. + pub vendor: String, + /// The user comments, each `NAME=value`. + pub comments: Vec, +} + +impl Comments { + /// The first comment named `name` (case-insensitive), its value. + #[must_use] + pub fn get(&self, name: &str) -> Option<&str> { + self.comments.iter().find_map(|c| { + let (k, v) = c.split_once('=')?; + k.eq_ignore_ascii_case(name).then_some(v) + }) + } +} + +fn header_start(packet: &[u8], kind: u8) -> Result> { + if packet.len() < 7 || packet[0] != kind || &packet[1..7] != b"vorbis" { + return Err(Error::Header("wrong packet type or missing \"vorbis\" tag")); + } + let mut r = BitReader::new(packet); + let _ = r.read(8); + for _ in 0..6 { + let _ = r.read(8); + } + Ok(r) +} + +fn read_identification(packet: &[u8]) -> Result { + let mut r = header_start(packet, 1)?; + let eop = |_: Eop| Error::Header("identification header is truncated"); + if r.read(32).map_err(eop)? != 0 { + return Err(Error::Header("unsupported Vorbis version")); + } + let channels = r.read(8).map_err(eop)? as u8; + let sample_rate = r.read(32).map_err(eop)?; + let bitrate_maximum = r.read(32).map_err(eop)? as i32; + let bitrate_nominal = r.read(32).map_err(eop)? as i32; + let bitrate_minimum = r.read(32).map_err(eop)? as i32; + let e0 = r.read(4).map_err(eop)?; + let e1 = r.read(4).map_err(eop)?; + if !r.bit().map_err(eop)? { + return Err(Error::Header("identification header framing bit is not set")); + } + if channels == 0 || sample_rate == 0 { + return Err(Error::Header("no channels or a zero sample rate")); + } + if !(6..=13).contains(&e0) || !(6..=13).contains(&e1) || e0 > e1 { + return Err(Error::Header("block sizes must be powers of two from 64 to 8192, the short one not above the long one")); + } + Ok(Identification { channels, sample_rate, bitrate_maximum, bitrate_nominal, bitrate_minimum, blocksize_0: 1 << e0, blocksize_1: 1 << e1 }) +} + +/// Comments are best effort: damage here is not fatal (§4.2.1). +fn read_comments(packet: &[u8]) -> Result { + header_start(packet, 3)?; + let mut at = 7usize; + let mut take = |n: usize| -> Option<&[u8]> { + let s = packet.get(at..at.checked_add(n)?)?; + at += n; + Some(s) + }; + let word = |b: &[u8]| u32::from_le_bytes([b[0], b[1], b[2], b[3]]) as usize; + let mut out = Comments::default(); + let Some(n) = take(4).map(word) else { return Ok(out) }; + let Some(vendor) = take(n) else { return Ok(out) }; + out.vendor = String::from_utf8_lossy(vendor).into_owned(); + let Some(count) = take(4).map(word) else { return Ok(out) }; + for _ in 0..count { + let Some(n) = take(4).map(word) else { break }; + let Some(c) = take(n) else { break }; + out.comments.push(String::from_utf8_lossy(c).into_owned()); + } + Ok(out) +} + +struct Mapping { + coupling: Vec<(usize, usize)>, + mux: Vec, + /// `(floor, residue)` of each submap. + submaps: Vec<(usize, usize)>, +} + +struct Mode { + long: bool, + mapping: usize, +} + +struct Setup { + books: Vec, + floors: Vec, + residues: Vec, + mappings: Vec, + modes: Vec, +} + +/// Bytes the codebooks of a setup may take in all (codeword trees and vector tables). +const CODEBOOK_BUDGET: usize = 256 << 20; + +fn read_setup(packet: &[u8], channels: usize) -> Result { + let mut r = header_start(packet, 5)?; + let eop = |_: Eop| Error::Setup("setup header is truncated"); + let count = r.read(8).map_err(eop)? as usize + 1; + let mut budget = CODEBOOK_BUDGET; + let mut books = Vec::with_capacity(count); + for _ in 0..count { + books.push(Codebook::read(&mut r, &mut budget)?); + } + // Time domain transforms: placeholders. + for _ in 0..r.read(6).map_err(eop)? + 1 { + if r.read(16).map_err(eop)? != 0 { + return Err(Error::Setup("a time domain transform is not zero")); + } + } + let count = r.read(6).map_err(eop)? as usize + 1; + let mut floors = Vec::with_capacity(count); + for _ in 0..count { + let kind = r.read(16).map_err(eop)?; + floors.push(Floor::read(kind, &mut r, &books)?); + } + let count = r.read(6).map_err(eop)? as usize + 1; + let mut residues = Vec::with_capacity(count); + for _ in 0..count { + let kind = r.read(16).map_err(eop)?; + if kind > 2 { + return Err(Error::Setup("unknown residue type")); + } + residues.push(Residue::read(kind, &mut r, &books)?); + } + let count = r.read(6).map_err(eop)? as usize + 1; + let mut mappings = Vec::with_capacity(count); + for _ in 0..count { + if r.read(16).map_err(eop)? != 0 { + return Err(Error::Setup("unknown mapping type")); + } + let submaps = if r.bit().map_err(eop)? { r.read(4).map_err(eop)? as usize + 1 } else { 1 }; + let mut coupling = Vec::new(); + if r.bit().map_err(eop)? { + let steps = r.read(8).map_err(eop)? as usize + 1; + let bits = ilog(channels as i64 - 1); + for _ in 0..steps { + let magnitude = r.read(bits).map_err(eop)? as usize; + let angle = r.read(bits).map_err(eop)? as usize; + if magnitude == angle || magnitude >= channels || angle >= channels { + return Err(Error::Setup("channel coupling names an invalid channel pair")); + } + coupling.push((magnitude, angle)); + } + } + if r.read(2).map_err(eop)? != 0 { + return Err(Error::Setup("reserved mapping bits are set")); + } + let mut mux = vec![0usize; channels]; + if submaps > 1 { + for m in &mut mux { + *m = r.read(4).map_err(eop)? as usize; + if *m >= submaps { + return Err(Error::Setup("channel multiplexed to a submap that does not exist")); + } + } + } + let mut list = Vec::with_capacity(submaps); + for _ in 0..submaps { + r.read(8).map_err(eop)?; + let floor = r.read(8).map_err(eop)? as usize; + let residue = r.read(8).map_err(eop)? as usize; + if floor >= floors.len() || residue >= residues.len() { + return Err(Error::Setup("submap names a floor or residue that does not exist")); + } + list.push((floor, residue)); + } + mappings.push(Mapping { coupling, mux, submaps: list }); + } + let count = r.read(6).map_err(eop)? as usize + 1; + let mut modes = Vec::with_capacity(count); + for _ in 0..count { + let long = r.bit().map_err(eop)?; + let window = r.read(16).map_err(eop)?; + let transform = r.read(16).map_err(eop)?; + let mapping = r.read(8).map_err(eop)? as usize; + if window != 0 || transform != 0 || mapping >= mappings.len() { + return Err(Error::Setup("a mode has a nonzero window or transform type or an unknown mapping")); + } + modes.push(Mode { long, mapping }); + } + if !r.bit().map_err(eop)? { + return Err(Error::Setup("setup header framing bit is not set")); + } + Ok(Setup { books, floors, residues, mappings, modes }) +} + +/// The previous block, windowed, kept for overlap-add. +struct Previous { + n: usize, + data: Vec>, +} + +/// A Vorbis I packet decoder. +pub struct Decoder { + id: Identification, + comments: Comments, + setup: Setup, + imdct: [Imdct; 2], + slopes: [Vec; 2], + previous: Option, +} + +impl Decoder { + /// A decoder from the three header packets, in order. A damaged comment header is tolerated + /// (its comments are then empty); the other two must be valid. + pub fn new(identification: &[u8], comment: &[u8], setup: &[u8]) -> Result { + let id = read_identification(identification)?; + let comments = read_comments(comment)?; + let setup = read_setup(setup, usize::from(id.channels))?; + let (b0, b1) = (id.blocksize_0 as usize, id.blocksize_1 as usize); + Ok(Self { id, comments, setup, imdct: [Imdct::new(b0), Imdct::new(b1)], slopes: [slope(b0 / 2), slope(b1 / 2)], previous: None }) + } + + /// The identification header. + #[must_use] + pub fn identification(&self) -> &Identification { + &self.id + } + + /// The comment header. + #[must_use] + pub fn comments(&self) -> &Comments { + &self.comments + } + + /// Forget the previous block, as after a seek: the next packet only primes the overlap again. + pub fn reset(&mut self) { + self.previous = None; + } + + /// The window of a block (§4.3.1). + fn window(&self, n: usize, long: bool, prev_long: bool, next_long: bool) -> Vec { + let half = n / 2; + let b0 = self.id.blocksize_0 as usize; + let mut w = vec![0f32; n]; + // Left half. + if long && !prev_long { + let (start, end) = (n / 4 - b0 / 4, n / 4 + b0 / 4); + w[start..end].copy_from_slice(&self.slopes[0]); + w[end..half].fill(1.0); + } else { + w[..half].copy_from_slice(&self.slopes[usize::from(long)]); + } + // Right half. + if long && !next_long { + let start = 3 * n / 4 - b0 / 4; + w[half..start].fill(1.0); + for (i, s) in self.slopes[0].iter().rev().enumerate() { + w[start + i] = *s; + } + } else { + for (i, s) in self.slopes[usize::from(long)].iter().rev().enumerate() { + w[half + i] = *s; + } + } + w + } + + /// Decode one audio packet. The result holds one `Vec` per channel, all of the same length: + /// the samples this packet completes (none for the first packet after a start or reset). + pub fn decode_packet(&mut self, packet: &[u8]) -> Result>> { + let channels = usize::from(self.id.channels); + let mut r = BitReader::new(packet); + match r.bit() { + Ok(false) => {} + Ok(true) => return Err(Error::NotAudio), + Err(_) => return Err(Error::Packet("empty packet")), + } + let mode_bits = ilog(self.setup.modes.len() as i64 - 1); + let mode_number = r.read(mode_bits).map_err(|_| Error::Packet("packet ends inside the mode number"))? as usize; + let Some(mode) = self.setup.modes.get(mode_number) else { return Err(Error::Packet("mode number out of range")) }; + let long = mode.long; + let n = if long { self.id.blocksize_1 } else { self.id.blocksize_0 } as usize; + let (mut prev_long, mut next_long) = (true, true); + if long { + prev_long = r.bit().map_err(|_| Error::Packet("packet ends inside the window flags"))?; + next_long = r.bit().map_err(|_| Error::Packet("packet ends inside the window flags"))?; + } + let window = self.window(n, long, prev_long, next_long); + let half = n / 2; + let mapping = &self.setup.mappings[mode.mapping]; + + let spectrum = self.spectrum(&mut r, mapping, half, channels)?; + // Inverse transform and window. + let which = usize::from(long); + let mut blocks: Vec> = Vec::with_capacity(channels); + for s in &spectrum { + let mut y = vec![0f32; n]; + self.imdct[which].inverse(s, &mut y); + for (v, w) in y.iter_mut().zip(&window) { + *v *= *w; + } + blocks.push(y); + } + + // Overlap-add with the previous block (§4.3.8). + let out = match &self.previous { + None => vec![Vec::new(); channels], + Some(prev) => { + let count = prev.n / 4 + n / 4; + blocks + .iter() + .zip(&prev.data) + .map(|(cur, old)| { + (0..count) + .map(|k| { + let a = old.get(prev.n / 2 + k).copied().unwrap_or(0.0); + let b = (n / 4 + k).checked_sub(prev.n / 4).and_then(|i| cur.get(i)).copied().unwrap_or(0.0); + a + b + }) + .collect() + }) + .collect() + } + }; + self.previous = Some(Previous { n, data: blocks }); + Ok(out) + } + + /// Floors, residues, coupling and the dot product: the spectrum of each channel (§4.3.2 to 4.3.6). + fn spectrum(&self, r: &mut BitReader<'_>, mapping: &Mapping, half: usize, channels: usize) -> Result>> { + let zero = || vec![vec![0f32; half]; channels]; + let setup = &self.setup; + // Floors, in channel order. + let mut floors: Vec> = Vec::with_capacity(channels); + for ch in 0..channels { + let (floor, _) = mapping.submaps[mapping.mux[ch]]; + match setup.floors[floor].decode(r, &setup.books) { + Ok(f) => floors.push(f), + Err(Fail::Eop) => return Ok(zero()), + Err(Fail::Invalid) => return Err(Error::Packet("a floor names a codebook that does not exist")), + } + } + let mut no_residue: Vec = floors.iter().map(Option::is_none).collect(); + for &(m, a) in &mapping.coupling { + if !no_residue[m] || !no_residue[a] { + no_residue[m] = false; + no_residue[a] = false; + } + } + // Residues, in submap order. + let mut residue = zero(); + for (i, &(_, res)) in mapping.submaps.iter().enumerate() { + let members: Vec = (0..channels).filter(|&c| mapping.mux[c] == i).collect(); + if members.is_empty() { + continue; + } + let skip: Vec = members.iter().map(|&c| no_residue[c]).collect(); + let mut vectors = vec![vec![0f32; half]; members.len()]; + setup.residues[res].decode(r, &setup.books, half, &skip, &mut vectors); + for (v, &c) in vectors.into_iter().zip(&members) { + residue[c] = v; + } + } + // Inverse channel coupling (§4.3.5), last step first. + for &(m, a) in mapping.coupling.iter().rev() { + let mut mag = std::mem::take(&mut residue[m]); + let mut ang = std::mem::take(&mut residue[a]); + for (mv, av) in mag.iter_mut().zip(ang.iter_mut()) { + let (big, small) = (*mv, *av); + let (new_m, new_a); + if big > 0.0 { + if small > 0.0 { + new_m = big; + new_a = big - small; + } else { + new_a = big; + new_m = big + small; + } + } else if small > 0.0 { + new_m = big; + new_a = big + small; + } else { + new_a = big; + new_m = big - small; + } + *mv = new_m; + *av = new_a; + } + residue[m] = mag; + residue[a] = ang; + } + // The floor times the residue. + for ch in 0..channels { + match &floors[ch] { + Some(data) => { + let (floor, _) = mapping.submaps[mapping.mux[ch]]; + let curve = setup.floors[floor].curve(data, half); + for (v, c) in residue[ch].iter_mut().zip(curve) { + *v *= c; + } + } + None => residue[ch].fill(0.0), + } + } + Ok(residue) + } +} + +/// A decoded Ogg Vorbis file. +#[derive(Debug, Clone, PartialEq)] +pub struct Decoded { + /// Samples per second per channel. + pub sample_rate: u32, + /// One `Vec` of samples per channel. + pub channels: Vec>, + /// The stream's comment header. + pub comments: Comments, + /// Audio packets that could not be decoded and were skipped. + pub damaged_packets: usize, +} + +/// Decode the first Vorbis stream of an Ogg file. The result is trimmed to the stream's final +/// granule position, so an encoder's padding at the end is dropped. Damaged packets are skipped +/// and counted, not fatal. Collected PCM is limited to 256 MiB; use the packet +/// decoder for longer streams without retaining the entire output. +pub fn decode_ogg(data: &[u8]) -> Result { + let ogg = craft_media::ogg::open(data).map_err(|e| Error::Ogg(e.to_string()))?; + let index = ogg.stream_of(craft_media::ogg::Codec::Vorbis).ok_or_else(|| Error::Ogg("no Vorbis stream".into()))?; + let stream = &ogg.streams[index]; + let [id, comment, setup, ..] = stream.headers.as_slice() else { return Err(Error::Ogg("the stream has fewer than three header packets".into())) }; + let mut decoder = Decoder::new(id, comment, setup)?; + let channel_count = usize::from(decoder.id.channels); + let mut channels = vec![Vec::new(); channel_count]; + let mut damaged = 0; + for i in 0..stream.packets.len() { + let packet = ogg.read_packet(data, index, i).map_err(|e| Error::Ogg(e.to_string()))?; + match decoder.decode_packet(&packet) { + Ok(pcm) => { + append_pcm(&mut channels, pcm, 256 << 20)?; + } + Err(_) => damaged += 1, + } + } + if let Some(total) = stream.last_granule.and_then(|g| usize::try_from(g).ok()) { + for c in &mut channels { + c.truncate(total); + } + } + Ok(Decoded { sample_rate: decoder.id.sample_rate, channels, comments: decoder.comments.clone(), damaged_packets: damaged }) +} + +// Admit every channel together before extending any of them. Limit retained PCM, +// not the compressed input, setup tables or the decoder's bounded packet scratch. +fn append_pcm(channels: &mut [Vec], pcm: Vec>, budget: usize) -> Result<()> { + let samples = channels.iter().chain(&pcm).try_fold(0usize, |n, c| n.checked_add(c.len())); + if samples.is_none_or(|n| n > budget / std::mem::size_of::()) { + return Err(Error::Limit("decoded PCM exceeds the whole-file budget")); + } + for (all, new) in channels.iter_mut().zip(pcm) { + all.try_reserve_exact(new.len()).map_err(|_| Error::Limit("cannot allocate decoded PCM"))?; + all.extend(new); + } + Ok(()) +} + +#[cfg(test)] +mod budget_tests { + use super::*; + + #[test] + fn pcm_budget_counts_all_channels_before_extending() { + let mut channels = vec![vec![1.0], vec![2.0]]; + append_pcm(&mut channels, vec![vec![3.0], vec![4.0]], 16).expect("exact budget"); + let before = channels.clone(); + assert!(matches!(append_pcm(&mut channels, vec![vec![5.0], vec![6.0]], 23), Err(Error::Limit(_)))); + assert_eq!(channels, before); + append_pcm(&mut channels, vec![Vec::new(), Vec::new()], 16).expect("empty packet"); + } +} diff --git a/crates/audio/src/vorbis/decoder/residue.rs b/crates/audio/src/vorbis/decoder/residue.rs new file mode 100644 index 000000000..99918d379 --- /dev/null +++ b/crates/audio/src/vorbis/decoder/residue.rs @@ -0,0 +1,196 @@ +//! Residues (Vorbis I §8): the fine detail of the spectrum, coded as vectors in passes. + +use super::Error; +use super::bits::{BitReader, Eop}; +use super::codebook::Codebook; + +pub(super) struct Residue { + kind: u32, + begin: usize, + end: usize, + partition_size: usize, + classifications: usize, + classbook: usize, + /// `books[class][pass]`. + books: Vec<[Option; 8]>, +} + +fn eop(_: Eop) -> Error { + Error::Setup("setup header ends inside a residue") +} + +impl Residue { + pub(super) fn read(kind: u32, r: &mut BitReader<'_>, books: &[Codebook]) -> Result { + let begin = r.read(24).map_err(eop)? as usize; + let end = r.read(24).map_err(eop)? as usize; + let partition_size = r.read(24).map_err(eop)? as usize + 1; + let classifications = r.read(6).map_err(eop)? as usize + 1; + let classbook = r.read(8).map_err(eop)? as usize; + let Some(cb) = books.get(classbook) else { return Err(Error::Setup("residue class book out of range")) }; + // classifications ^ dimensions must not exceed the book's entries. + let mut reach = 1u128; + for _ in 0..cb.dimensions { + reach = reach.saturating_mul(classifications as u128); + if reach > cb.entries as u128 { + return Err(Error::Setup("residue class book has too few entries for its classifications")); + } + } + let mut cascade = Vec::with_capacity(classifications); + for _ in 0..classifications { + let low = r.read(3).map_err(eop)?; + let high = if r.bit().map_err(eop)? { r.read(5).map_err(eop)? } else { 0 }; + cascade.push(high * 8 + low); + } + let mut list = Vec::with_capacity(classifications); + for &c in &cascade { + let mut row = [None; 8]; + for (j, slot) in row.iter_mut().enumerate() { + if c & (1 << j) != 0 { + let b = r.read(8).map_err(eop)? as usize; + match books.get(b) { + Some(book) if book.has_vectors() => *slot = Some(b), + _ => return Err(Error::Setup("residue names a missing codebook or one without vectors")), + } + } + } + list.push(row); + } + Ok(Self { kind, begin, end, partition_size, classifications, classbook, books: list }) + } + + /// Decode a bundle of vectors, each `n` long (half the block size), into `out`; a vector marked + /// in `skip` is left zero. End of packet ends decoding where it is (a nominal event). + pub(super) fn decode(&self, r: &mut BitReader<'_>, books: &[Codebook], n: usize, skip: &[bool], out: &mut [Vec]) { + let ch = out.len(); + if skip.iter().all(|&s| s) { + return; + } + if self.kind == 2 { + let mut flat = vec![vec![0f32; n * ch]]; + let _ = self.decode_vectors(r, books, n * ch, &[false], &mut flat); + for i in 0..n { + for (j, v) in out.iter_mut().enumerate() { + v[i] = flat[0][i * ch + j]; + } + } + } else { + let _ = self.decode_vectors(r, books, n, skip, out); + } + } + + fn decode_vectors(&self, r: &mut BitReader<'_>, books: &[Codebook], actual: usize, skip: &[bool], out: &mut [Vec]) -> Result<(), Eop> { + let ch = out.len(); + let begin = self.begin.min(actual); + let end = self.end.min(actual); + if end <= begin { + return Ok(()); + } + let classbook = &books[self.classbook]; + let cpw = classbook.dimensions; + let partitions = (end - begin) / self.partition_size; + // Classbook dimensions may greatly exceed the actual partition count. + // Retain only digits that this block can use, not padding per channel. + let mut classes = vec![vec![0usize; partitions]; ch]; + for pass in 0..8 { + let mut count = 0usize; + while count < partitions { + if pass == 0 { + for j in 0..ch { + if skip[j] { + continue; + } + let mut temp = classbook.scalar(r)? as usize; + for i in (0..cpw).rev() { + if i + count < partitions { + classes[j][i + count] = temp % self.classifications; + } + temp /= self.classifications; + } + } + } + let mut i = 0; + while i < cpw && count < partitions { + for j in 0..ch { + if skip[j] { + continue; + } + let Some(book) = self.books[classes[j][count]][pass] else { continue }; + let book = &books[book]; + let offset = begin + count * self.partition_size; + self.partition(r, book, &mut out[j][offset..offset + self.partition_size])?; + } + count += 1; + i += 1; + } + } + } + Ok(()) + } + + /// One partition into `v` (the slice of the vector it covers). + fn partition(&self, r: &mut BitReader<'_>, book: &Codebook, v: &mut [f32]) -> Result<(), Eop> { + let n = v.len(); + let dims = book.dimensions; + let step = n / dims; + if self.kind == 0 { + for i in 0..step { + let Some(entry) = book.vector(r)? else { return Ok(()) }; + for (j, &e) in entry.iter().enumerate() { + v[i + j * step] += e; + } + } + } else { + let mut i = 0; + for _ in 0..step { + let Some(entry) = book.vector(r)? else { return Ok(()) }; + for &e in entry { + v[i] += e; + i += 1; + } + } + } + Ok(()) + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn huge_class_dimensions_keep_only_actual_partitions() { + let mut data = Vec::::new(); + let mut bits = 0usize; + let mut put = |value: u32, n: usize| { + for i in 0..n { + if bits.is_multiple_of(8) { + data.push(0); + } + let last = data.len() - 1; + data[last] |= (((value >> i) & 1) as u8) << (bits % 8); + bits += 1; + } + }; + put(0x56_4342, 24); + put(65535, 16); + put(1, 24); + put(0, 1); // unordered, not sparse, one length-1 entry + put(0, 1); + put(0, 5); + put(0, 4); // scalar-only classbook + let book = Codebook::read(&mut BitReader::new(&data), &mut (1 << 20)).expect("classbook"); + let books = [book]; + for kind in [0, 1] { + let residue = Residue { kind, begin: 0, end: 32, partition_size: 1, classifications: 1, classbook: 0, books: vec![[None; 8]] }; + let mut out = vec![vec![0.0; 32]; 255]; + let packet = [0u8; 32]; + let mut r = BitReader::new(&packet); + residue.decode(&mut r, &books, 32, &[false; 255], &mut out); + assert_eq!(r.remaining(), 1); // one classword per channel, not 32 + assert!(out.iter().flatten().all(|&x| x == 0.0)); + let mut r = BitReader::new(&packet); + residue.decode(&mut r, &books, 32, &[true; 255], &mut out); + assert_eq!(r.remaining(), 256); // skipped channels consume nothing + } + } +} diff --git a/crates/audio/src/vorbis/decoder/tables.rs b/crates/audio/src/vorbis/decoder/tables.rs new file mode 100644 index 000000000..49e5b97b9 --- /dev/null +++ b/crates/audio/src/vorbis/decoder/tables.rs @@ -0,0 +1,263 @@ +//! `floor1_inverse_dB_table` (Vorbis I §10.1): the 256 linear amplitudes of the floor 1 integer values. + +// The values are printed to the digits the specification gives them. +#![allow(clippy::excessive_precision)] + +pub(super) const INVERSE_DB: [f32; 256] = [ + 1.0649863e-07, + 1.1341951e-07, + 1.2079015e-07, + 1.2863978e-07, + 1.3699951e-07, + 1.4590251e-07, + 1.5538408e-07, + 1.6548181e-07, + 1.7623575e-07, + 1.8768855e-07, + 1.9988561e-07, + 2.1287530e-07, + 2.2670913e-07, + 2.4144197e-07, + 2.5713223e-07, + 2.7384213e-07, + 2.9163793e-07, + 3.1059021e-07, + 3.3077411e-07, + 3.5226968e-07, + 3.7516214e-07, + 3.9954229e-07, + 4.2550680e-07, + 4.5315863e-07, + 4.8260743e-07, + 5.1396998e-07, + 5.4737065e-07, + 5.8294187e-07, + 6.2082472e-07, + 6.6116941e-07, + 7.0413592e-07, + 7.4989464e-07, + 7.9862701e-07, + 8.5052630e-07, + 9.0579828e-07, + 9.6466216e-07, + 1.0273513e-06, + 1.0941144e-06, + 1.1652161e-06, + 1.2409384e-06, + 1.3215816e-06, + 1.4074654e-06, + 1.4989305e-06, + 1.5963394e-06, + 1.7000785e-06, + 1.8105592e-06, + 1.9282195e-06, + 2.0535261e-06, + 2.1869758e-06, + 2.3290978e-06, + 2.4804557e-06, + 2.6416497e-06, + 2.8133190e-06, + 2.9961443e-06, + 3.1908506e-06, + 3.3982101e-06, + 3.6190449e-06, + 3.8542308e-06, + 4.1047004e-06, + 4.3714470e-06, + 4.6555282e-06, + 4.9580707e-06, + 5.2802740e-06, + 5.6234160e-06, + 5.9888572e-06, + 6.3780469e-06, + 6.7925283e-06, + 7.2339451e-06, + 7.7040476e-06, + 8.2047000e-06, + 8.7378876e-06, + 9.3057248e-06, + 9.9104632e-06, + 1.0554501e-05, + 1.1240392e-05, + 1.1970856e-05, + 1.2748789e-05, + 1.3577278e-05, + 1.4459606e-05, + 1.5399272e-05, + 1.6400004e-05, + 1.7465768e-05, + 1.8600792e-05, + 1.9809576e-05, + 2.1096914e-05, + 2.2467911e-05, + 2.3928002e-05, + 2.5482978e-05, + 2.7139006e-05, + 2.8902651e-05, + 3.0780908e-05, + 3.2781225e-05, + 3.4911534e-05, + 3.7180282e-05, + 3.9596466e-05, + 4.2169667e-05, + 4.4910090e-05, + 4.7828601e-05, + 5.0936773e-05, + 5.4246931e-05, + 5.7772202e-05, + 6.1526565e-05, + 6.5524908e-05, + 6.9783085e-05, + 7.4317983e-05, + 7.9147585e-05, + 8.4291040e-05, + 8.9768747e-05, + 9.5602426e-05, + 0.00010181521, + 0.00010843174, + 0.00011547824, + 0.00012298267, + 0.00013097477, + 0.00013948625, + 0.00014855085, + 0.00015820453, + 0.00016848555, + 0.00017943469, + 0.00019109536, + 0.00020351382, + 0.00021673929, + 0.00023082423, + 0.00024582449, + 0.00026179955, + 0.00027881276, + 0.00029693158, + 0.00031622787, + 0.00033677814, + 0.00035866388, + 0.00038197188, + 0.00040679456, + 0.00043323036, + 0.00046138411, + 0.00049136745, + 0.00052329927, + 0.00055730621, + 0.00059352311, + 0.00063209358, + 0.00067317058, + 0.00071691700, + 0.00076350630, + 0.00081312324, + 0.00086596457, + 0.00092223983, + 0.00098217216, + 0.0010459992, + 0.0011139742, + 0.0011863665, + 0.0012634633, + 0.0013455702, + 0.0014330129, + 0.0015261382, + 0.0016253153, + 0.0017309374, + 0.0018434235, + 0.0019632195, + 0.0020908006, + 0.0022266726, + 0.0023713743, + 0.0025254795, + 0.0026895994, + 0.0028643847, + 0.0030505286, + 0.0032487691, + 0.0034598925, + 0.0036847358, + 0.0039241906, + 0.0041792066, + 0.0044507950, + 0.0047400328, + 0.0050480668, + 0.0053761186, + 0.0057254891, + 0.0060975636, + 0.0064938176, + 0.0069158225, + 0.0073652516, + 0.0078438871, + 0.0083536271, + 0.0088964928, + 0.009474637, + 0.010090352, + 0.010746080, + 0.011444421, + 0.012188144, + 0.012980198, + 0.013823725, + 0.014722068, + 0.015678791, + 0.016697687, + 0.017782797, + 0.018938423, + 0.020169149, + 0.021479854, + 0.022875735, + 0.024362330, + 0.025945531, + 0.027631618, + 0.029427276, + 0.031339626, + 0.033376252, + 0.035545228, + 0.037855157, + 0.040315199, + 0.042935108, + 0.045725273, + 0.048696758, + 0.051861348, + 0.055231591, + 0.058820850, + 0.062643361, + 0.066714279, + 0.071049749, + 0.075666962, + 0.080584227, + 0.085821044, + 0.091398179, + 0.097337747, + 0.10366330, + 0.11039993, + 0.11757434, + 0.12521498, + 0.13335215, + 0.14201813, + 0.15124727, + 0.16107617, + 0.17154380, + 0.18269168, + 0.19456402, + 0.20720788, + 0.22067342, + 0.23501402, + 0.25028656, + 0.26655159, + 0.28387361, + 0.30232132, + 0.32196786, + 0.34289114, + 0.36517414, + 0.38890521, + 0.41417847, + 0.44109412, + 0.46975890, + 0.50028648, + 0.53279791, + 0.56742212, + 0.60429640, + 0.64356699, + 0.68538959, + 0.72993007, + 0.77736504, + 0.82788260, + 0.88168307, + 0.9389798, + 1.0, +]; diff --git a/crates/audio/src/vorbis/mod.rs b/crates/audio/src/vorbis/mod.rs index 29c423f1d..15b81bb26 100644 --- a/crates/audio/src/vorbis/mod.rs +++ b/crates/audio/src/vorbis/mod.rs @@ -1,4 +1,7 @@ -//! Vorbis I (feature `vorbis-encode`): the pure-Rust [`encoder`]. Decoding Vorbis goes through -//! [`crate::decode`]. +//! Vorbis I: the pure-Rust [`decoder`] (feature `vorbis-decode`) and [`encoder`] (feature +//! `vorbis-encode`). `craft_audio::decode` still reads Vorbis files through symphonia. +#[cfg(feature = "vorbis-decode")] +pub mod decoder; +#[cfg(feature = "vorbis-encode")] pub mod encoder; diff --git a/crates/audio/tests/adpcm_oracle.rs b/crates/audio/tests/adpcm_oracle.rs new file mode 100644 index 000000000..c89fe6444 --- /dev/null +++ b/crates/audio/tests/adpcm_oracle.rs @@ -0,0 +1,516 @@ +//! ADPCM (feature `adpcm`): every family decodes what ffmpeg's encoder writes to ffmpeg's own +//! samples, and ffmpeg decodes what our encoder writes to our own decoder's samples (oracle; +//! skipped when ffmpeg is absent, a failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`); plus the +//! round trip through our own encoder and decoder, and damaged input. + +use craft_audio::adpcm::{ima, ms, swf, yamaha}; +use std::path::Path; +use std::process::Command; + +const RATE: u32 = 22_050; + +/// Interleaved test audio: tones, a sweep, noise bursts, silence and a full-scale square. +fn signal(channels: usize, frames: usize) -> Vec { + let mut seed = 0x2545_F491u32; + let mut out = Vec::with_capacity(frames * channels); + for i in 0..frames { + for c in 0..channels { + seed ^= seed << 13; + seed ^= seed >> 17; + seed ^= seed << 5; + let t = i as f64; + let v = match (i / 1500) % 5 { + 0 => (t * (0.03 + 0.011 * c as f64)).sin() * 9000.0, + 1 => (t * 0.002 * (1.0 + t / 3000.0)).sin() * 14000.0, + 2 => f64::from(seed % 12000) - 6000.0, + 3 => 0.0, + _ => { + if (i / 40) % 2 == 0 { + 20000.0 + } else { + -20000.0 + } + } + }; + out.push(v as i16); + } + } + out +} + +fn snr(a: &[i16], b: &[i16]) -> f64 { + let (mut s, mut n) = (0f64, 0f64); + for (x, y) in a.iter().zip(b) { + s += f64::from(*x).powi(2); + n += (f64::from(*x) - f64::from(*y)).powi(2); + } + 10.0 * (s / n.max(1.0)).log10() +} + +fn max_diff(a: &[i16], b: &[i16]) -> i32 { + a.iter().zip(b).map(|(x, y)| (i32::from(*x) - i32::from(*y)).abs()).max().unwrap_or(0) +} + +#[test] +fn encode_then_decode_is_close_to_the_input() { + for channels in [1usize, 2] { + let x = signal(channels, 20_000); + // (name, decoded, minimum SNR dB, a few dB under what each reaches): the signal has noise bursts + // and full-scale square waves, which codes this small follow loosely + let cases: Vec<(&str, Vec, f64)> = vec![ + ("ima", ima::decode(&ima::encode(&x, channels, 512).unwrap(), channels, 512).unwrap(), 5.0), + ("ms", ms::decode(&ms::encode(&x, channels, 512).unwrap(), channels, 512).unwrap(), 18.0), + ("yamaha", yamaha::decode(&yamaha::encode(&x, channels).unwrap(), channels).unwrap(), 5.0), + ("swf2", swf::decode(&swf::encode(&x, channels, 2).unwrap(), channels).unwrap(), 1.0), + ("swf3", swf::decode(&swf::encode(&x, channels, 3).unwrap(), channels).unwrap(), 3.0), + ("swf4", swf::decode(&swf::encode(&x, channels, 4).unwrap(), channels).unwrap(), 5.0), + ("swf5", swf::decode(&swf::encode(&x, channels, 5).unwrap(), channels).unwrap(), 7.0), + ]; + for (name, y, min) in cases { + assert!(y.len() >= x.len(), "{name}: {} samples for {}", y.len(), x.len()); + let s = snr(&x, &y[..x.len()]); + println!("{name} {channels}ch: SNR {s:.1} dB"); + assert!(s >= min, "{name} {channels}ch: SNR {s:.1} dB under {min}"); + } + } +} + +#[test] +fn damaged_input_is_an_error_or_decodes_never_panics() { + let x = signal(2, 4000); + let streams: Vec<(&str, Vec)> = vec![ + ("ima", ima::encode(&x, 2, 256).unwrap()), + ("ms", ms::encode(&x, 2, 256).unwrap()), + ("yamaha", yamaha::encode(&x, 2).unwrap()), + ("swf", swf::encode(&x, 2, 4).unwrap()), + ]; + let mut seed = 99u32; + for (name, s) in &streams { + for cut in (0..s.len()).step_by(7) { + let part = &s[..cut]; + let _ = match *name { + "ima" => ima::decode(part, 2, 256).map(drop), + "ms" => ms::decode(part, 2, 256).map(drop), + "yamaha" => yamaha::decode(part, 2).map(drop), + _ => swf::decode(part, 2).map(drop), + }; + } + for _ in 0..300 { + let mut d = s.clone(); + seed ^= seed << 13; + seed ^= seed >> 17; + seed ^= seed << 5; + let at = seed as usize % d.len(); + d[at] ^= (seed >> 8) as u8 | 1; + let _ = match *name { + "ima" => ima::decode(&d, 2, 256).map(drop), + "ms" => ms::decode(&d, 2, 256).map(drop), + "yamaha" => yamaha::decode(&d, 2).map(drop), + _ => swf::decode(&d, 2).map(drop), + }; + } + } + // the impossible layouts + assert!(ima::decode(&[0; 10], 2, 10).is_err()); + assert!(ima::decode(&[0; 8], 9, 8).is_err()); + assert!(ms::decode(&[0; 8], 3, 8).is_err()); + assert!(ima::encode(&[0; 3], 2, 256).is_err()); + assert!(ima::encode_block(&[0; 3], 1, 256).is_err()); + assert!(ms::encode_block(&[0; 3], 1, 256).is_err()); + // a block whose step index or predictor is out of range + let mut bad = ima::encode_block(&vec![0; 505], 1, 256).unwrap(); + bad[2] = 200; + assert!(ima::decode_block(&bad, 1, &mut Vec::new()).is_err()); + let mut bad = swf::encode(&[0; 10], 1, 4).unwrap(); + bad[2] = 0xFF; + let _ = swf::decode(&bad, 1); +} + +#[test] +fn huge_layouts_and_big_jumps_are_handled() { + // block sizes whose sample counts do not fit in a usize + assert_eq!(ima::samples_per_block(usize::MAX - 3, 1), None); + assert_eq!(ms::samples_per_block(usize::MAX, 1), None); + assert!(ima::encode(&[], 1, usize::MAX - 3).is_err()); + assert!(ms::encode(&[], 1, usize::MAX).is_err()); + // a Flash stream's header holds the step index in six bits: a jump from silence to full scale + // still decodes to what the encoder's own state says + for bits in [2u32, 3, 4, 5] { + let x = [0i16, 32767, -32768, 0, 0]; + let y = swf::decode(&swf::encode(&x, 1, bits).unwrap(), 1).unwrap(); + // the stream has no length: up to seven padding bits can read as one more code + assert!((x.len()..=x.len() + 3).contains(&y.len()), "{bits} bits: {} samples", y.len()); + assert!(y[1] > 0 && y[2] < y[1], "{bits} bits: {y:?}"); + } + // padding bits at the end of a stream are not a code: no incomplete stereo frame + for bits in [2u32, 3, 4, 5] { + let y = swf::decode(&swf::encode(&[0, 0, 5, -5, 9, 9], 2, bits).unwrap(), 2).unwrap(); + assert_eq!(y.len() % 2, 0, "{bits} bits: {y:?}"); + assert!((6..=8).contains(&y.len()), "{bits} bits: {} samples", y.len()); + } +} + +#[test] +fn partial_final_blocks_are_handled() { + let x = signal(1, 1000); + // IMA: 256-byte blocks hold 505 samples; 1000 samples is two blocks, the second padded + let enc = ima::encode(&x, 1, 256).unwrap(); + assert_eq!(enc.len(), 2 * 256); + assert_eq!(ima::decode(&enc, 1, 256).unwrap().len(), 1010); + // a stream cut inside the last block decodes as far as it goes + let cut = ima::decode(&enc[..256 + 4 + 40], 1, 256).unwrap(); + assert_eq!(cut.len(), 505 + 1 + 80); + let enc = ms::encode(&x, 1, 256).unwrap(); + assert_eq!(ms::decode(&enc, 1, 256).unwrap().len(), 1000); + assert!(ima::encode(&[], 1, 256).unwrap().is_empty()); + assert!(ms::encode(&[], 1, 256).unwrap().is_empty()); + assert!(yamaha::encode(&[], 1).unwrap().is_empty()); + assert_eq!(yamaha::decode(&yamaha::encode(&[5, 6, 7], 1).unwrap(), 1).unwrap().len(), 4); +} + +// ---- the other rounding some ffmpeg versions use for IMA and Flash ADPCM +// +// The IMA recommended practices build the step difference from `step >> 3` and the shifted steps +// of the magnitude bits that are set; some decoders (including older ffmpeg releases) compute +// `((2 * magnitude + 1) * step) >> (bits - 1)` instead, which rounds differently by a few units +// and so drifts apart through the predictor. A stream decodes to ours or to this one. + +fn alt_diff(mag: i32, step: i32, bits: u32) -> i32 { + ((2 * mag + 1) * step) >> (bits - 1) +} + +const INDEX_4: [i32; 8] = [-1, -1, -1, -1, 2, 4, 6, 8]; +const INDEX_5: [i32; 16] = [-1, -1, -1, -1, -1, -1, -1, -1, 1, 2, 4, 6, 8, 10, 13, 16]; +const STEPS: [i32; 89] = [ + 7, 8, 9, 10, 11, 12, 13, 14, 16, 17, 19, 21, 23, 25, 28, 31, 34, 37, 41, 45, 50, 55, 60, 66, 73, 80, 88, 97, 107, 118, 130, 143, 157, 173, 190, + 209, 230, 253, 279, 307, 337, 371, 408, 449, 494, 544, 598, 658, 724, 796, 876, 963, 1060, 1166, 1282, 1411, 1552, 1707, 1878, 2066, 2272, 2499, + 2749, 3024, 3327, 3660, 4026, 4428, 4871, 5358, 5894, 6484, 7132, 7845, 8630, 9493, 10442, 11487, 12635, 13899, 15289, 16818, 18500, 20350, + 22385, 24623, 27086, 29794, 32767, +]; + +fn index_table(bits: u32) -> &'static [i32] { + match bits { + 2 => &[-1, 2], + 3 => &[-1, -1, 2, 4], + 4 => &INDEX_4, + _ => &INDEX_5, + } +} + +/// `ima::decode` with the other rounding. +fn alt_ima_decode(data: &[u8], channels: usize, block_align: usize) -> Vec { + let per = ima::samples_per_block(block_align, channels).expect("layout"); + let mut out = Vec::new(); + for block in data.chunks_exact(block_align) { + let mut pred = vec![0i32; channels]; + let mut idx = vec![0i32; channels]; + let base = out.len(); + out.resize(base + per * channels, 0); + for ch in 0..channels { + pred[ch] = i32::from(i16::from_le_bytes([block[4 * ch], block[4 * ch + 1]])); + idx[ch] = i32::from(block[4 * ch + 2]); + out[base + ch] = pred[ch] as i16; + } + for (g, group) in block[4 * channels..].chunks_exact(4 * channels).enumerate() { + for (ch, bytes) in group.as_chunks::<4>().0.iter().enumerate() { + for (k, b) in bytes.iter().enumerate() { + for (half, nib) in [b & 0xF, b >> 4].into_iter().enumerate() { + let step = STEPS[idx[ch] as usize]; + let d = alt_diff(i32::from(nib & 7), step, 4); + pred[ch] = (pred[ch] + if nib & 8 != 0 { -d } else { d }).clamp(-32768, 32767); + idx[ch] = (idx[ch] + INDEX_4[usize::from(nib & 7)]).clamp(0, 88); + out[base + (1 + g * 8 + k * 2 + half) * channels + ch] = pred[ch] as i16; + } + } + } + } + } + out +} + +/// `swf::decode` with the other rounding (one stream). +fn alt_swf_decode(data: &[u8], channels: usize) -> Vec { + let mut bitpos = 0usize; + let mut get = |n: usize| -> Option { + let mut v = 0u32; + for _ in 0..n { + let byte = *data.get(bitpos / 8)?; + v = (v << 1) | u32::from((byte >> (7 - bitpos % 8)) & 1); + bitpos += 1; + } + Some(v) + }; + let bits = get(2).expect("header") + 2; + let mut out = Vec::new(); + loop { + let mut pred = Vec::new(); + let mut idx = Vec::new(); + for _ in 0..channels { + let (Some(p), Some(i)) = (get(16), get(6)) else { return out }; + out.push(p as u16 as i16); + pred.push(i32::from(p as u16 as i16)); + idx.push(i as i32); + } + for _ in 1..4096 { + for ch in 0..channels { + let Some(code) = get(bits as usize) else { return out }; + let mag = (code & ((1 << (bits - 1)) - 1)) as i32; + let d = alt_diff(mag, STEPS[idx[ch] as usize], bits); + pred[ch] = (pred[ch] + if code >> (bits - 1) != 0 { -d } else { d }).clamp(-32768, 32767); + idx[ch] = (idx[ch] + index_table(bits)[mag as usize]).clamp(0, 88); + out.push(pred[ch] as i16); + } + } + } +} + +/// Assert `theirs` is `ours` or `alt` over their common length (and say which). +fn same_as_either(what: &str, ours: &[i16], alt: &[i16], theirs: &[i16]) { + let n = ours.len().min(theirs.len()); + let (a, b) = (max_diff(&ours[..n], &theirs[..n]), max_diff(&alt[..n.min(alt.len())], &theirs[..n.min(alt.len())])); + println!("{what}: largest difference from ours {a}, from the other rounding {b}"); + assert!(a == 0 || b == 0, "{what}: ffmpeg's decode is neither ours ({a}) nor the other rounding ({b})"); +} + +/// A name, the WAV file around our stream, our decode of it and the other rounding's. +type Stream = (&'static str, Vec, Vec, Vec); + +// ---- ffmpeg as the reference + +fn ffmpeg(ff: &Path, args: &[&str]) { + let out = Command::new(ff).args(["-v", "error", "-nostdin", "-y"]).args(args).output().expect("run ffmpeg"); + assert!(out.status.success(), "ffmpeg {args:?}: {}", String::from_utf8_lossy(&out.stderr)); +} + +fn s(p: &Path) -> String { + p.to_str().expect("path").to_string() +} + +fn write_pcm(path: &Path, x: &[i16]) { + std::fs::write(path, x.iter().flat_map(|v| v.to_le_bytes()).collect::>()).expect("write"); +} + +fn read_pcm(path: &Path) -> Vec { + std::fs::read(path).expect("read").as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect() +} + +/// The `fmt ` chunk's fields and the `data` chunk of a WAV file. +fn wav_parts(bytes: &[u8]) -> (u16, usize, usize, Vec) { + let mut at = 12; + let (mut tag, mut channels, mut align) = (0, 0, 0); + while at + 8 <= bytes.len() { + let id = &bytes[at..at + 4]; + let len = u32::from_le_bytes([bytes[at + 4], bytes[at + 5], bytes[at + 6], bytes[at + 7]]) as usize; + let body = &bytes[at + 8..(at + 8 + len).min(bytes.len())]; + if id == b"fmt " { + tag = u16::from_le_bytes([body[0], body[1]]); + channels = usize::from(u16::from_le_bytes([body[2], body[3]])); + align = usize::from(u16::from_le_bytes([body[12], body[13]])); + } else if id == b"data" { + return (tag, channels, align, body.to_vec()); + } + at += 8 + len + (len & 1); + } + panic!("no data chunk"); +} + +/// A WAV file around `data`. +fn wav(tag: u16, channels: usize, align: usize, bits: u16, extra: &[u8], data: &[u8]) -> Vec { + let mut fmt = Vec::new(); + fmt.extend(tag.to_le_bytes()); + fmt.extend((channels as u16).to_le_bytes()); + fmt.extend(RATE.to_le_bytes()); + fmt.extend((RATE * align as u32 / 500).to_le_bytes()); + fmt.extend((align as u16).to_le_bytes()); + fmt.extend(bits.to_le_bytes()); + if !extra.is_empty() || tag == 0x11 || tag == 2 { + fmt.extend((extra.len() as u16).to_le_bytes()); + fmt.extend(extra); + } + let mut out = b"RIFF".to_vec(); + out.extend((4 + 8 + fmt.len() as u32 + 8 + data.len() as u32).to_le_bytes()); + out.extend(b"WAVEfmt "); + out.extend((fmt.len() as u32).to_le_bytes()); + out.extend(fmt); + out.extend(b"data"); + out.extend((data.len() as u32).to_le_bytes()); + out.extend(data); + out +} + +#[test] +fn we_decode_what_ffmpeg_encodes_to_the_samples_ffmpeg_decodes() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("adpcm"); + for channels in [1usize, 2] { + let x = signal(channels, 30_000); + let pcm = dir.join(format!("in{channels}.pcm")); + write_pcm(&pcm, &x); + let input = ["-f", "s16le", "-ar", "22050", "-ac", if channels == 1 { "1" } else { "2" }, "-i"]; + for (name, codec, align) in [("ima", "adpcm_ima_wav", 512usize), ("ms", "adpcm_ms", 512), ("yamaha", "adpcm_yamaha", 0)] { + let file = dir.join(format!("{name}{channels}.wav")); + let mut args: Vec = input.iter().map(|a| a.to_string()).collect(); + args.extend([s(&pcm), "-c:a".into(), codec.into()]); + if align > 0 { + args.extend(["-block_size".into(), align.to_string()]); + } + args.push(s(&file)); + ffmpeg(&ff, &args.iter().map(String::as_str).collect::>()); + let back = dir.join(format!("{name}{channels}.out.pcm")); + ffmpeg(&ff, &["-i", &s(&file), "-f", "s16le", "-acodec", "pcm_s16le", &s(&back)]); + let theirs = read_pcm(&back); + let (tag, ch, block, data) = wav_parts(&std::fs::read(&file).expect("read")); + assert_eq!(ch, channels); + let ours = match name { + "ima" => { + assert_eq!(tag, 0x11); + ima::decode(&data, ch, block).expect("decode") + } + "ms" => { + assert_eq!(tag, 2); + ms::decode(&data, ch, block).expect("decode") + } + _ => yamaha::decode(&data, ch).expect("decode"), + }; + let n = ours.len().min(theirs.len()); + assert!(n >= 29_000 * channels, "{name} {channels}ch: {} ours, {} theirs", ours.len(), theirs.len()); + if name == "ima" { + same_as_either(&format!("{name} {channels}ch"), &ours, &alt_ima_decode(&data, ch, block), &theirs); + } else { + let d = max_diff(&ours[..n], &theirs[..n]); + println!("{name} {channels}ch: {n} samples, largest difference from ffmpeg's decode {d}"); + assert_eq!(d, 0, "{name} {channels}ch"); + } + // our encoder is as good as ffmpeg's on the same audio, to within 3 dB + let mine = match name { + "ima" => ima::decode(&ima::encode(&x, ch, block).expect("encode"), ch, block).expect("decode"), + "ms" => ms::decode(&ms::encode(&x, ch, block).expect("encode"), ch, block).expect("decode"), + _ => yamaha::decode(&yamaha::encode(&x, ch).expect("encode"), ch).expect("decode"), + }; + let m = x.len().min(mine.len()).min(theirs.len()); + let (a, b) = (snr(&x[..m], &mine[..m]), snr(&x[..m], &theirs[..m])); + println!("{name} {channels}ch: SNR {a:.1} dB ours, {b:.1} dB ffmpeg's"); + assert!(a + 3.0 >= b, "{name} {channels}ch: our encoder {a:.1} dB against ffmpeg's {b:.1} dB"); + } + } +} + +#[test] +fn ffmpeg_decodes_what_we_encode_to_the_samples_we_decode() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("adpcm"); + for channels in [1usize, 2] { + let x = signal(channels, 12_000); + let coefs: Vec = ms::COEFFICIENTS.iter().flat_map(|&(a, b)| [a as i16, b as i16].into_iter().flat_map(i16::to_le_bytes)).collect(); + let streams: Vec = { + let e = ima::encode(&x, channels, 512).unwrap(); + let per = ima::samples_per_block(512, channels).unwrap() as u16; + let d = ima::decode(&e, channels, 512).unwrap(); + let d_alt = alt_ima_decode(&e, channels, 512); + let ima_wav = wav(0x11, channels, 512, 4, &per.to_le_bytes(), &e); + let e = ms::encode(&x, channels, 512).unwrap(); + let per = ms::samples_per_block(512, channels).unwrap() as u16; + let d2 = ms::decode(&e, channels, 512).unwrap(); + let mut extra = per.to_le_bytes().to_vec(); + extra.extend(7u16.to_le_bytes()); + extra.extend(&coefs); + let ms_wav = wav(2, channels, 512, 4, &extra, &e); + let e = yamaha::encode(&x, channels).unwrap(); + let d3 = yamaha::decode(&e, channels).unwrap(); + let y_wav = wav(0x20, channels, 512 * channels, 4, &[], &e); + vec![("ima", ima_wav, d, d_alt), ("ms", ms_wav, d2.clone(), d2), ("yamaha", y_wav, d3.clone(), d3)] + }; + for (name, bytes, ours, alt) in streams { + let file = dir.join(format!("our_{name}{channels}.wav")); + std::fs::write(&file, bytes).expect("write"); + let back = dir.join(format!("our_{name}{channels}.pcm")); + ffmpeg(&ff, &["-i", &s(&file), "-f", "s16le", "-acodec", "pcm_s16le", &s(&back)]); + let theirs = read_pcm(&back); + let n = ours.len().min(theirs.len()); + assert!(n + 2048 >= ours.len(), "{name} {channels}ch: ffmpeg decoded {} of {}", theirs.len(), ours.len()); + same_as_either(&format!("{name} {channels}ch, our stream"), &ours, &alt, &theirs); + } + } +} + +/// The audio tags of an FLV file: each tag's body without its flags byte. +fn flv_audio(bytes: &[u8]) -> Vec> { + let mut at = 13; + let mut out = Vec::new(); + while at + 11 <= bytes.len() { + let kind = bytes[at]; + let len = (usize::from(bytes[at + 1]) << 16) | (usize::from(bytes[at + 2]) << 8) | usize::from(bytes[at + 3]); + let body = &bytes[at + 11..(at + 11 + len).min(bytes.len())]; + if kind == 8 && body.len() > 1 { + assert_eq!(body[0] >> 4, 1, "SWF ADPCM tag"); + out.push(body[1..].to_vec()); + } + at += 11 + len + 4; + } + out +} + +/// An FLV file of 44.1 kHz audio tags with these ADPCM bodies. +fn flv(stereo: bool, tags: &[Vec]) -> Vec { + let mut out = b"FLV\x01\x04\0\0\0\x09\0\0\0\0".to_vec(); + let flags = (1u8 << 4) | (3 << 2) | (1 << 1) | u8::from(stereo); + for (i, t) in tags.iter().enumerate() { + let len = t.len() + 1; + let ts = (i * 4096 * 1000 / 44_100) as u32; + out.extend([ + 8, + (len >> 16) as u8, + (len >> 8) as u8, + len as u8, + (ts >> 16) as u8, + (ts >> 8) as u8, + ts as u8, + (ts >> 24) as u8, + 0, + 0, + 0, + flags, + ]); + out.extend(t); + out.extend((len as u32 + 11).to_be_bytes()); + } + out +} + +#[test] +fn flash_adpcm_matches_ffmpeg_in_both_directions() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("adpcm"); + for channels in [1usize, 2] { + let x = signal(channels, 4096 * 3); + let pcm = dir.join(format!("swf_in{channels}.pcm")); + write_pcm(&pcm, &x); + // ffmpeg encodes (it needs 44.1 kHz for FLV) + let file = dir.join(format!("swf{channels}.flv")); + ffmpeg(&ff, &["-f", "s16le", "-ar", "44100", "-ac", &channels.to_string(), "-i", &s(&pcm), "-c:a", "adpcm_swf", "-f", "flv", &s(&file)]); + let tags = flv_audio(&std::fs::read(&file).expect("read")); + assert!(tags.len() >= 3, "{} tags", tags.len()); + let back = dir.join(format!("swf{channels}.out.pcm")); + ffmpeg(&ff, &["-i", &s(&file), "-f", "s16le", "-acodec", "pcm_s16le", &s(&back)]); + let theirs = read_pcm(&back); + let ours: Vec = tags.iter().flat_map(|t| swf::decode(t, channels).expect("decode")).collect(); + assert_eq!(ours.len(), 4096 * 3 * channels); + assert_eq!(theirs.len(), 4096 * 3 * channels); + let alt: Vec = tags.iter().flat_map(|t| alt_swf_decode(t, channels)).collect(); + same_as_either(&format!("swf {channels}ch"), &ours, &alt, &theirs); + // ffmpeg decodes ours, one 4096-sample stream per tag + for bits in [2u32, 3, 4, 5] { + let tags: Vec> = x.chunks(4096 * channels).map(|c| swf::encode(c, channels, bits).expect("encode")).collect(); + let ours: Vec = tags.iter().flat_map(|t| swf::decode(t, channels).expect("decode")).collect(); + let file = dir.join(format!("our_swf{channels}_{bits}.flv")); + std::fs::write(&file, flv(channels == 2, &tags)).expect("write"); + let back = dir.join(format!("our_swf{channels}_{bits}.pcm")); + ffmpeg(&ff, &["-i", &s(&file), "-f", "s16le", "-acodec", "pcm_s16le", &s(&back)]); + let theirs = read_pcm(&back); + assert_eq!(ours.len(), 4096 * 3 * channels); + assert_eq!(theirs.len(), 4096 * 3 * channels); + let alt: Vec = tags.iter().flat_map(|t| alt_swf_decode(t, channels)).collect(); + same_as_either(&format!("swf {channels}ch {bits} bits, our stream"), &ours, &alt, &theirs); + } + } +} diff --git a/crates/audio/tests/g722_oracle.rs b/crates/audio/tests/g722_oracle.rs new file mode 100644 index 000000000..3da059011 --- /dev/null +++ b/crates/audio/tests/g722_oracle.rs @@ -0,0 +1,201 @@ +//! ITU-T G.722 SB-ADPCM tests and FFmpeg oracle comparisons. +//! +//! Skipped when FFmpeg is not found, unless `CRAFT_MEDIA_REQUIRE_ORACLES=1` is set. + +use craft_audio::g722::{Decoder, Encoder, Error, decode, decode_interleaved, encode, encode_interleaved}; +use std::process::Command; + +fn generate_signal(samples: usize, freq: f64) -> Vec { + (0..samples) + .map(|i| { + let t = i as f64 / 16000.0; + let val = (2.0 * std::f64::consts::PI * freq * t).sin() * 10000.0; + val as i16 + }) + .collect() +} + +#[test] +fn test_silence_roundtrip() { + let pcm = vec![0i16; 640]; + let encoded = encode(&pcm).expect("encode"); + assert_eq!(encoded.len(), 320); + let decoded = decode(&encoded).expect("decode"); + assert_eq!(decoded.len(), 640); + for &s in &decoded[40..] { + assert!(s.abs() <= 6, "silence sample out of bounds: {s}"); + } +} + +#[test] +fn test_sine_wave_roundtrip_fidelity() { + let pcm = generate_signal(1600, 1000.0); + let encoded = encode(&pcm).expect("encode"); + let decoded = decode(&encoded).expect("decode"); + assert_eq!(decoded.len(), pcm.len()); + + // Compute normalized cross-correlation accounting for filter group delay (approx 22 samples) + let delay = 22; + let mut num = 0.0; + let mut den_orig = 0.0; + let mut den_dec = 0.0; + for i in 0..(pcm.len() - delay) { + let o = pcm[i] as f64; + let d = decoded[i + delay] as f64; + num += o * d; + den_orig += o * o; + den_dec += d * d; + } + let corr = num / (den_orig.sqrt() * den_dec.sqrt()); + assert!(corr > 0.98, "reconstructed sine wave correlation too low: {corr}"); +} + +#[test] +fn test_stereo_multichannel_roundtrip() { + let left = generate_signal(800, 440.0); + let right = generate_signal(800, 880.0); + let mut interleaved = Vec::with_capacity(1600); + for i in 0..800 { + interleaved.push(left[i]); + interleaved.push(right[i]); + } + let encoded = encode_interleaved(&interleaved, 2).expect("encode stereo"); + assert_eq!(encoded.len(), 800); + let decoded = decode_interleaved(&encoded, 2).expect("decode stereo"); + assert_eq!(decoded.len(), 1600); +} + +#[test] +fn test_hostile_inputs_do_not_crash() { + let garbage = [0xFF, 0x00, 0xAA, 0x55, 0x12, 0x34, 0x89, 0xFE]; + let decoded = decode(&garbage).expect("decode garbage"); + assert_eq!(decoded.len(), 16); + + assert_eq!(encode(&[1, 2, 3]), Err(Error::OddSampleCount(3))); + assert_eq!(decode_interleaved(&[0; 8], 0), Err(Error::InvalidChannels(0))); + assert_eq!(decode_interleaved(&[0; 8], 9), Err(Error::InvalidChannels(9))); +} + +#[test] +fn test_encoder_and_decoder_reset() { + let mut enc = Encoder::new(); + let mut dec = Decoder::new(); + let pcm = generate_signal(200, 1000.0); + + let mut out1 = Vec::new(); + enc.encode(&pcm, &mut out1).expect("enc 1"); + let mut dec1 = Vec::new(); + dec.decode(&out1, &mut dec1).expect("dec 1"); + + enc.reset(); + dec.reset(); + + let mut out2 = Vec::new(); + enc.encode(&pcm, &mut out2).expect("enc 2"); + let mut dec2 = Vec::new(); + dec.decode(&out2, &mut dec2).expect("dec 2"); + + assert_eq!(out1, out2); + assert_eq!(dec1, dec2); +} + +#[test] +fn test_ffmpeg_g722_oracle_encoder_and_decoder() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("g722_oracle"); + + // 1. Generate test 1000 Hz tone at 16 kHz mono (800 samples = 0.05s) + let pcm = generate_signal(800, 1000.0); + let pcm_path = dir.join("input.s16le"); + let mut pcm_bytes = Vec::with_capacity(pcm.len() * 2); + for &s in &pcm { + pcm_bytes.extend_from_slice(&s.to_le_bytes()); + } + std::fs::write(&pcm_path, &pcm_bytes).expect("write pcm"); + + // 2. FFmpeg encodes the PCM to G.722 + let ff_g722_path = dir.join("ffmpeg.g722"); + let out = Command::new(&ff) + .args(["-y", "-f", "s16le", "-ar", "16000", "-ac", "1", "-i"]) + .arg(&pcm_path) + .args(["-f", "g722"]) + .arg(&ff_g722_path) + .output() + .expect("ffmpeg encode"); + assert!(out.status.success(), "ffmpeg encode failed: {}", String::from_utf8_lossy(&out.stderr)); + let ff_g722_bytes = std::fs::read(&ff_g722_path).expect("read ff g722"); + + // 3. FFmpeg decodes its own G.722 back to PCM + let ff_pcm_back_path = dir.join("ff_back.s16le"); + let out = Command::new(&ff) + .args(["-y", "-f", "g722", "-i"]) + .arg(&ff_g722_path) + .args(["-f", "s16le", "-ar", "16000", "-ac", "1"]) + .arg(&ff_pcm_back_path) + .output() + .expect("ffmpeg decode"); + assert!(out.status.success(), "ffmpeg decode failed: {}", String::from_utf8_lossy(&out.stderr)); + let ff_back_bytes = std::fs::read(&ff_pcm_back_path).expect("read ff back pcm"); + let ff_back_samples: Vec = ff_back_bytes.as_chunks::<2>().0.iter().map(|c| i16::from_le_bytes(*c)).collect(); + + // 4. Our decoder decodes FFmpeg's G.722 stream + let our_decoded_from_ff = decode(&ff_g722_bytes).expect("our decode of ff stream"); + assert_eq!(our_decoded_from_ff.len(), ff_back_samples.len()); + + // Verify sample-by-sample match against FFmpeg decoder: within ±1 LSB tolerance + let mut max_diff: i32 = 0; + for (i, (&ours, &theirs)) in our_decoded_from_ff.iter().zip(&ff_back_samples).enumerate() { + let diff = (ours as i32 - theirs as i32).abs(); + if diff > max_diff { + max_diff = diff; + } + assert!(diff <= 1, "sample {i} mismatch between our decoder and FFmpeg decoder: ours {ours}, theirs {theirs}"); + } + assert!(max_diff <= 1, "max diff {max_diff} exceeded tolerance"); + + // 5. Our encoder encodes the PCM to G.722 + let our_encoded_bytes = encode(&pcm).expect("our encode"); + let our_g722_path = dir.join("ours.g722"); + std::fs::write(&our_g722_path, &our_encoded_bytes).expect("write our g722"); + + // 6. FFmpeg decodes our encoded G.722 stream + let our_decoded_by_ff_path = dir.join("our_by_ff.s16le"); + let out = Command::new(&ff) + .args(["-y", "-f", "g722", "-i"]) + .arg(&our_g722_path) + .args(["-f", "s16le", "-ar", "16000", "-ac", "1"]) + .arg(&our_decoded_by_ff_path) + .output() + .expect("ffmpeg decode of our stream"); + assert!(out.status.success(), "ffmpeg decode of our stream failed: {}", String::from_utf8_lossy(&out.stderr)); + let our_by_ff_bytes = std::fs::read(&our_decoded_by_ff_path).expect("read our by ff pcm"); + let our_by_ff_samples: Vec = our_by_ff_bytes.as_chunks::<2>().0.iter().map(|c| i16::from_le_bytes(*c)).collect(); + + // Verify that our decoder and FFmpeg decoder produce identical samples on our stream + let our_decoded_from_ours = decode(&our_encoded_bytes).expect("our decode of our stream"); + assert_eq!(our_decoded_from_ours.len(), our_by_ff_samples.len()); + let mut max_diff_ours: i32 = 0; + for (i, (&ours, &theirs)) in our_decoded_from_ours.iter().zip(&our_by_ff_samples).enumerate() { + let diff = (ours as i32 - theirs as i32).abs(); + if diff > max_diff_ours { + max_diff_ours = diff; + } + assert!(diff <= 1, "sample {i} on our stream mismatch between our decoder and FFmpeg decoder: ours {ours}, theirs {theirs}"); + } + assert!(max_diff_ours <= 1, "max diff {max_diff_ours} exceeded tolerance"); + + // Also check high fidelity correlation of our stream decoded by FFmpeg to original signal + let delay = 22; + let mut num = 0.0; + let mut den_orig = 0.0; + let mut den_dec = 0.0; + for i in 0..(pcm.len() - delay) { + let o = pcm[i] as f64; + let d = our_by_ff_samples[i + delay] as f64; + num += o * d; + den_orig += o * o; + den_dec += d * d; + } + let corr = num / (den_orig.sqrt() * den_dec.sqrt()); + assert!(corr > 0.98, "correlation of our encoded stream decoded by FFmpeg is too low: {corr}"); +} diff --git a/crates/audio/tests/g726_oracle.rs b/crates/audio/tests/g726_oracle.rs new file mode 100644 index 000000000..ec875e2c4 --- /dev/null +++ b/crates/audio/tests/g726_oracle.rs @@ -0,0 +1,218 @@ +#![cfg(feature = "g726")] + +use craft_audio::g726::{BitPacking, BitRate, Decoder, Encoder, decode, decode_interleaved, encode, encode_interleaved}; +use std::process::Command; + +fn pearson_correlation(x: &[i16], y: &[i16]) -> f64 { + let n = x.len().min(y.len()); + if n == 0 { + return 0.0; + } + let x = &x[..n]; + let y = &y[..n]; + let mean_x = x.iter().map(|&v| v as f64).sum::() / (n as f64); + let mean_y = y.iter().map(|&v| v as f64).sum::() / (n as f64); + let mut num = 0.0; + let mut denom_x = 0.0; + let mut denom_y = 0.0; + for (&a, &b) in x.iter().zip(y) { + let da = (a as f64) - mean_x; + let db = (b as f64) - mean_y; + num += da * db; + denom_x += da * da; + denom_y += db * db; + } + let denom = (denom_x * denom_y).sqrt(); + if denom > 0.0 { num / denom } else { 0.0 } +} + +fn find_ffmpeg() -> Option { + for cmd in ["ffmpeg", "/opt/homebrew/bin/ffmpeg", "/usr/bin/ffmpeg"] { + if Command::new(cmd).arg("-version").output().is_ok() { + return Some(cmd.to_string()); + } + } + None +} + +#[test] +fn test_silence_roundtrip() { + let pcm = vec![0i16; 80]; + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + for packing in [BitPacking::BigEndian, BitPacking::LittleEndian] { + let enc = encode(&pcm, rate, packing).expect("encode"); + let dec = decode(&enc, rate, packing).expect("decode"); + assert_eq!(dec.len(), pcm.len()); + for &s in &dec { + assert!(s.abs() <= 16, "silence sample too large: {s}"); + } + } + } +} + +#[test] +fn test_sine_wave_roundtrip_fidelity() { + let sample_rate = 8000.0; + let freq = 300.0; + let num_samples = 160; + let mut pcm = Vec::with_capacity(num_samples); + for i in 0..num_samples { + let t = i as f64 / sample_rate; + let s = (4000.0 * (2.0 * std::f64::consts::PI * freq * t).sin()) as i16; + pcm.push(s); + } + + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + for packing in [BitPacking::BigEndian, BitPacking::LittleEndian] { + let enc = encode(&pcm, rate, packing).expect("encode sine"); + let dec = decode(&enc, rate, packing).expect("decode sine"); + let corr = pearson_correlation(&pcm, &dec); + assert!(corr > 0.90, "correlation {corr} too low for rate {rate:?} packing {packing:?}"); + } + } +} + +#[test] +fn test_encoder_and_decoder_reset() { + let mut enc = Encoder::new(BitRate::Rate32k, BitPacking::BigEndian); + let mut dec = Decoder::new(BitRate::Rate32k, BitPacking::BigEndian); + + let pcm = vec![1000i16, 2000, 3000, 2000, 1000, 0, -1000, -2000]; + let mut out1 = Vec::new(); + enc.encode(&pcm, &mut out1).expect("enc 1"); + enc.flush(&mut out1).expect("flush 1"); + + let mut dec_pcm1 = Vec::new(); + dec.decode(&out1, &mut dec_pcm1).expect("dec 1"); + + enc.reset(); + dec.reset(); + + let mut out2 = Vec::new(); + enc.encode(&pcm, &mut out2).expect("enc 2"); + enc.flush(&mut out2).expect("flush 2"); + + let mut dec_pcm2 = Vec::new(); + dec.decode(&out2, &mut dec_pcm2).expect("dec 2"); + + assert_eq!(out1, out2); + assert_eq!(dec_pcm1, dec_pcm2); +} + +#[test] +fn test_stereo_multichannel_roundtrip() { + let mut stereo_pcm = Vec::new(); + for i in 0..160 { + let left = (3000.0 * (i as f64 * 0.05).sin()) as i16; + let right = (2000.0 * (i as f64 * 0.03).cos()) as i16; + stereo_pcm.push(left); + stereo_pcm.push(right); + } + + let enc = encode_interleaved(&stereo_pcm, 2, BitRate::Rate32k, BitPacking::BigEndian).expect("encode stereo"); + let dec = decode_interleaved(&enc, 2, BitRate::Rate32k, BitPacking::BigEndian).expect("decode stereo"); + + assert_eq!(dec.len(), stereo_pcm.len()); + let corr = pearson_correlation(&stereo_pcm, &dec); + assert!(corr > 0.90, "stereo correlation {corr} too low"); +} + +#[test] +fn test_hostile_inputs_do_not_crash() { + let mut dec = Decoder::new(BitRate::Rate32k, BitPacking::BigEndian); + let mut out = Vec::new(); + let hostile = vec![0xEE; 1000]; + let _ = dec.decode(&hostile, &mut out); + + let mut enc = Encoder::new(BitRate::Rate40k, BitPacking::LittleEndian); + let mut out_enc = Vec::new(); + let hostile_pcm = vec![i16::MIN, i16::MAX, -1, 1, 0]; + let _ = enc.encode(&hostile_pcm, &mut out_enc); + let _ = enc.flush(&mut out_enc); +} + +#[test] +fn test_ffmpeg_g726_oracle_encoder_and_decoder() { + let ff = match find_ffmpeg() { + Some(f) => f, + None => return, + }; + + let sample_rate = 8000; + let num_samples = 240; + let mut pcm = Vec::with_capacity(num_samples); + for i in 0..num_samples { + let t = i as f64 / sample_rate as f64; + let s = (5000.0 * (2.0 * std::f64::consts::PI * 350.0 * t).sin()) as i16; + pcm.push(s); + } + + let dir = std::env::temp_dir().join("craft_g726_oracle"); + let _ = std::fs::create_dir_all(&dir); + let in_pcm_path = dir.join("input.s16le"); + let mut in_bytes = Vec::with_capacity(pcm.len() * 2); + for &s in &pcm { + in_bytes.extend_from_slice(&s.to_le_bytes()); + } + std::fs::write(&in_pcm_path, &in_bytes).expect("write input pcm"); + + for rate in [BitRate::Rate16k, BitRate::Rate24k, BitRate::Rate32k, BitRate::Rate40k] { + for (packing, ff_codec, ff_fmt) in [(BitPacking::BigEndian, "g726", "g726"), (BitPacking::LittleEndian, "g726le", "g726le")] { + let cs = rate.code_size(); + let ff_g726_path = dir.join(format!("ff_{}_{}.g726", cs, ff_codec)); + + // 1. FFmpeg encodes PCM to G.726 + let out = Command::new(&ff) + .args(["-y", "-f", "s16le", "-ar", "8000", "-ac", "1", "-i"]) + .arg(&in_pcm_path) + .args(["-c:a", ff_codec, "-code_size", &cs.to_string(), "-f", ff_fmt]) + .arg(&ff_g726_path) + .output() + .expect("ffmpeg encode"); + assert!(out.status.success(), "ffmpeg encode failed: {}", String::from_utf8_lossy(&out.stderr)); + let ff_g726_bytes = std::fs::read(&ff_g726_path).expect("read ff g726"); + + // 2. FFmpeg decodes its own G.726 stream + let ff_pcm_back_path = dir.join(format!("ff_back_{}_{}.s16le", cs, ff_codec)); + let out = Command::new(&ff) + .args(["-y", "-f", ff_fmt, "-code_size", &cs.to_string(), "-i"]) + .arg(&ff_g726_path) + .args(["-f", "s16le", "-ar", "8000", "-ac", "1"]) + .arg(&ff_pcm_back_path) + .output() + .expect("ffmpeg decode"); + assert!(out.status.success(), "ffmpeg decode failed: {}", String::from_utf8_lossy(&out.stderr)); + let ff_back_bytes = std::fs::read(&ff_pcm_back_path).expect("read ff back pcm"); + let ff_back_samples: Vec = ff_back_bytes.as_chunks::<2>().0.iter().map(|c| i16::from_le_bytes(*c)).collect(); + + // 3. Our decoder decodes FFmpeg's stream + let our_decoded = decode(&ff_g726_bytes, rate, packing).expect("our decode"); + let corr = pearson_correlation(&our_decoded, &ff_back_samples); + assert!(corr > 0.998, "correlation {corr} too low between our decoder and FFmpeg decoder for rate {rate:?} packing {packing:?}"); + + // 4. Our encoder encodes PCM to G.726 + let our_g726_bytes = encode(&pcm, rate, packing).expect("our encode"); + let our_g726_path = dir.join(format!("our_{}_{}.g726", cs, ff_codec)); + std::fs::write(&our_g726_path, &our_g726_bytes).expect("write our g726"); + + // 5. FFmpeg decodes our encoded stream + let our_decoded_by_ff_path = dir.join(format!("our_by_ff_{}_{}.s16le", cs, ff_codec)); + let out = Command::new(&ff) + .args(["-y", "-f", ff_fmt, "-code_size", &cs.to_string(), "-i"]) + .arg(&our_g726_path) + .args(["-f", "s16le", "-ar", "8000", "-ac", "1"]) + .arg(&our_decoded_by_ff_path) + .output() + .expect("ffmpeg decode of our stream"); + assert!(out.status.success(), "ffmpeg decode of our stream failed: {}", String::from_utf8_lossy(&out.stderr)); + let our_by_ff_bytes = std::fs::read(&our_decoded_by_ff_path).expect("read our by ff pcm"); + let our_by_ff_samples: Vec = our_by_ff_bytes.as_chunks::<2>().0.iter().map(|c| i16::from_le_bytes(*c)).collect(); + + let corr_input = pearson_correlation(&pcm, &our_by_ff_samples); + assert!( + corr_input > 0.90, + "correlation {corr_input} too low for input vs FFmpeg-decoded our stream for rate {rate:?} packing {packing:?}" + ); + } + } +} diff --git a/crates/audio/tests/main.rs b/crates/audio/tests/main.rs index dcba6e1d7..a1bd3d933 100644 --- a/crates/audio/tests/main.rs +++ b/crates/audio/tests/main.rs @@ -1,5 +1,8 @@ //! Integration tests, built into the library's own test executable. +#[cfg(feature = "adpcm")] +#[path = "adpcm_oracle.rs"] +mod adpcm_oracle; #[cfg(all(feature = "decode", feature = "lossless-encode", feature = "peaks"))] #[path = "audio/main.rs"] mod audio; @@ -9,12 +12,33 @@ mod codecs; #[cfg(all(feature = "flac-decode", feature = "flac-encode"))] #[path = "flac_decode.rs"] mod flac_decode; +#[cfg(feature = "g722")] +#[path = "g722_oracle.rs"] +mod g722_oracle; +#[cfg(feature = "g726")] +#[path = "g726_oracle.rs"] +mod g726_oracle; #[cfg(feature = "gsm")] #[path = "gsm_oracle.rs"] mod gsm_oracle; +#[cfg(feature = "mpa-encode")] +#[path = "mp2_encoder_oracle.rs"] +mod mp2_encoder_oracle; #[cfg(feature = "qoa")] #[path = "qoa_oracle.rs"] mod qoa_oracle; #[cfg(feature = "sbc")] #[path = "sbc_oracle.rs"] mod sbc_oracle; +#[cfg(feature = "vmd-decode")] +#[path = "vmd.rs"] +mod vmd; +#[cfg(all(feature = "vorbis-decode", feature = "vorbis-encode"))] +#[path = "vorbis_decode_hostile.rs"] +mod vorbis_decode_hostile; +#[cfg(all(feature = "vorbis-decode", feature = "vorbis-encode", feature = "decode"))] +#[path = "vorbis_decode_oracle.rs"] +mod vorbis_decode_oracle; +#[cfg(feature = "vorbis-decode")] +#[path = "vorbis_decode_synthetic.rs"] +mod vorbis_decode_synthetic; diff --git a/crates/audio/tests/mp2_encoder_oracle.rs b/crates/audio/tests/mp2_encoder_oracle.rs new file mode 100644 index 000000000..ca4d15bd3 --- /dev/null +++ b/crates/audio/tests/mp2_encoder_oracle.rs @@ -0,0 +1,228 @@ +//! The Layer II encoder (feature `mpa-encode`): every frame has the header and size its settings +//! give and decodes with our decoder; ffmpeg as an external decoder (skipped without ffmpeg, a +//! failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`) decodes the stream without a complaint, to the +//! right length, and its output, aligned by [`DELAY`], matches the input within a signal-to-noise +//! ratio per bit rate. The bounds sit well under what the encoder reaches today; white noise loses +//! the subbands above the table's last one (a sixth of it at 48 kHz), so its bound is low. + +use std::path::Path; +use std::process::{Command, Stdio}; + +use craft_audio::mpa::encoder::{Config, DELAY, EncodeError, Encoder, bitrates, nearest_bitrate}; +use craft_audio::mpa::{Decoder, Mode, Version, parse_header}; + +fn chords(rate: u32, n: usize, detune: f32) -> Vec { + let f = [220.0, 277.18, 329.63, 440.0, 1318.5, 3520.0]; + let a = [0.2, 0.15, 0.12, 0.1, 0.05, 0.02]; + (0..n) + .map(|i| { + let t = i as f32 / rate as f32; + f.iter().zip(a).map(|(f, a)| a * (2.0 * std::f32::consts::PI * f * (1.0 + detune) * t).sin()).sum::() + }) + .collect() +} + +fn noise(n: usize, amp: f32, seed: u64) -> Vec { + let mut s = seed.wrapping_mul(0x9E37_79B9_7F4A_7C15) | 1; + (0..n) + .map(|_| { + s ^= s << 13; + s ^= s >> 7; + s ^= s << 17; + ((s >> 40) as f32 / (1u64 << 24) as f32 * 2.0 - 1.0) * amp + }) + .collect() +} + +fn encode(cfg: Config, input: &[Vec], chunk: usize) -> Vec { + let mut enc = Encoder::new(cfg).expect("encoder"); + let mut out = Vec::new(); + let n = input[0].len(); + let mut pos = 0; + while pos < n { + let end = (pos + chunk).min(n); + let planes: Vec<&[f32]> = input.iter().map(|c| &c[pos..end]).collect(); + out.extend(enc.encode(&planes)); + pos = end; + } + out.extend(enc.flush()); + out +} + +/// Split a stream into frames by its headers; every header must be one the settings give. +fn frames<'a>(bytes: &'a [u8], cfg: &Config) -> Vec<&'a [u8]> { + let mut out = Vec::new(); + let mut pos = 0; + while pos < bytes.len() { + let h = parse_header(&bytes[pos..]).unwrap_or_else(|e| panic!("frame {} at byte {pos}: {e}", out.len())); + assert_eq!(h.layer, 2); + assert_eq!(h.version, if cfg.sample_rate >= 32_000 { Version::Mpeg1 } else { Version::Mpeg2 }); + assert_eq!((h.sample_rate, h.bitrate_kbps), (cfg.sample_rate, cfg.bitrate_kbps)); + assert_eq!(h.mode, if cfg.channels == 1 { Mode::Mono } else { Mode::Stereo }); + assert!(!h.crc); + out.push(&bytes[pos..pos + h.frame_bytes]); + pos += h.frame_bytes; + } + assert_eq!(pos, bytes.len(), "the stream ends on a frame boundary"); + out +} + +fn snr(input: &[f32], dec: &[f32]) -> f64 { + let (mut s, mut n) = (0f64, 0f64); + for (a, b) in input.iter().zip(dec) { + s += f64::from(*a) * f64::from(*a); + n += f64::from(a - b) * f64::from(a - b); + } + 10.0 * (s / n.max(1e-30)).log10() +} + +struct Case { + name: &'static str, + rate: u32, + channels: usize, + kbps: u32, + signal: fn(u32, usize, usize) -> Vec, + min_snr: f64, +} + +fn sig_chords(rate: u32, n: usize, c: usize) -> Vec { + chords(rate, n, 0.003 * c as f32) +} +fn sig_noise(_rate: u32, n: usize, c: usize) -> Vec { + noise(n, 0.25, 11 + c as u64) +} + +const CASES: &[Case] = &[ + Case { name: "chords", rate: 48_000, channels: 2, kbps: 192, signal: sig_chords, min_snr: 30.0 }, + Case { name: "chords", rate: 44_100, channels: 2, kbps: 128, signal: sig_chords, min_snr: 25.0 }, + Case { name: "chords", rate: 44_100, channels: 1, kbps: 64, signal: sig_chords, min_snr: 25.0 }, + Case { name: "chords", rate: 32_000, channels: 2, kbps: 96, signal: sig_chords, min_snr: 20.0 }, + Case { name: "chords", rate: 22_050, channels: 2, kbps: 64, signal: sig_chords, min_snr: 20.0 }, + Case { name: "chords", rate: 24_000, channels: 1, kbps: 32, signal: sig_chords, min_snr: 18.0 }, + Case { name: "noise", rate: 48_000, channels: 2, kbps: 384, signal: sig_noise, min_snr: 4.0 }, + Case { name: "noise", rate: 44_100, channels: 2, kbps: 256, signal: sig_noise, min_snr: 4.0 }, +]; + +fn inputs(c: &Case, n: usize) -> Vec> { + (0..c.channels).map(|ch| (c.signal)(c.rate, n, ch)).collect() +} + +#[test] +fn frames_have_the_size_and_header_their_settings_give_and_decode_with_our_decoder() { + for c in CASES { + let n = c.rate as usize * 2 + 777; + let cfg = Config::cbr(c.rate, c.channels, c.kbps); + let bytes = encode(cfg, &inputs(c, n), 1000); + let frames = frames(&bytes, &cfg); + // every input sample and the filter delay fit in the frames, and no more than one frame more + let covered = frames.len() * 1152; + assert!(covered >= n + DELAY as usize && covered < n + DELAY as usize + 1152, "{}: {} frames for {n} samples", c.name, frames.len()); + // 144 kbit/s-slots per frame, the padding slots adding up to the exact rate + let nominal = f64::from(c.kbps) * 125.0 * covered as f64 / f64::from(c.rate); + assert!((bytes.len() as f64 - nominal).abs() < 1.0 + f64::from(c.rate) / 1000.0, "{}: {} bytes against {nominal}", c.name, bytes.len()); + let mut dec = Decoder::new(); + let mut out = vec![Vec::new(); c.channels]; + for f in frames { + let frame = dec.decode(f).unwrap_or_else(|e| panic!("{}: {e}", c.name)); + for (o, ch) in out.iter_mut().zip(frame.channels) { + o.extend(ch); + } + } + let d = DELAY as usize; + for (ch, input) in inputs(c, n).iter().enumerate() { + let s = snr(input, &out[ch][d..d + n]); + println!("{:<7} {:>5} Hz {}ch {:>3} kbps: SNR {s:.2} dB (our decoder)", c.name, c.rate, c.channels, c.kbps); + assert!(s >= c.min_snr, "{} {} Hz {}ch {} kbps: SNR {s:.2} dB under {}", c.name, c.rate, c.channels, c.kbps, c.min_snr); + } + } +} + +#[test] +fn the_stream_does_not_depend_on_how_the_input_is_chunked() { + let c = &CASES[1]; + let n = 44_100 + 333; + let cfg = Config::cbr(c.rate, c.channels, c.kbps); + let input = inputs(c, n); + let whole = encode(cfg, &input, n); + for chunk in [1, 7, 1152, 5000] { + assert_eq!(encode(cfg, &input, chunk), whole, "chunk {chunk}"); + } +} + +#[test] +fn silence_and_nothing_encode_to_valid_frames() { + let cfg = Config::cbr(48_000, 2, 128); + let silent = vec![vec![0f32; 5000]; 2]; + let bytes = encode(cfg, &silent, 5000); + let fs = frames(&bytes, &cfg); + let mut dec = Decoder::new(); + for f in fs { + let frame = dec.decode(f).expect("decode"); + assert!(frame.channels.iter().flatten().all(|v| v.abs() < 1e-6)); + } + assert!(Encoder::new(cfg).expect("encoder").flush().is_empty(), "no input, no frames"); +} + +#[test] +fn hostile_samples_are_tamed() { + let cfg = Config::cbr(44_100, 2, 192); + let mut x = vec![0f32; 4000]; + for (i, v) in x.iter_mut().enumerate() { + *v = [f32::NAN, f32::INFINITY, -f32::INFINITY, 1e30, -1e30, 3.0, 0.5][i % 7]; + } + let bytes = encode(cfg, &[x.clone(), x], 4000); + let mut dec = Decoder::new(); + for f in frames(&bytes, &cfg) { + dec.decode(f).expect("decode"); + } +} + +#[test] +fn settings_that_cannot_be_carried_are_refused() { + assert_eq!(Encoder::new(Config::cbr(44_000, 2, 128)).err(), Some(EncodeError::SampleRate(44_000))); + assert_eq!(Encoder::new(Config::cbr(44_100, 3, 128)).err(), Some(EncodeError::Channels(3))); + assert_eq!(Encoder::new(Config::cbr(44_100, 0, 128)).err(), Some(EncodeError::Channels(0))); + // ISO/IEC 11172-3 allows neither 32 kbit/s for two channels nor 224 for one + assert!(matches!(Encoder::new(Config::cbr(44_100, 2, 32)), Err(EncodeError::Bitrate { .. }))); + assert!(matches!(Encoder::new(Config::cbr(44_100, 1, 224)), Err(EncodeError::Bitrate { .. }))); + assert!(matches!(Encoder::new(Config::cbr(44_100, 2, 130)), Err(EncodeError::Bitrate { .. }))); + assert_eq!(bitrates(44_100, 1).len(), 10); + assert_eq!(bitrates(22_050, 2).first(), Some(&8)); + assert!(bitrates(8_000, 2).is_empty()); + assert_eq!(nearest_bitrate(44_100, 2, 100), Some(96)); + assert_eq!(nearest_bitrate(44_100, 2, 1), Some(64)); + assert_eq!(nearest_bitrate(8_000, 2, 100), None); +} + +fn ffmpeg_decode(ff: &Path, path: &Path, channels: usize) -> (Vec>, String) { + let out = Command::new(ff) + .args(["-v", "error", "-nostdin", "-i"]) + .arg(path) + .args(["-f", "f32le", "-acodec", "pcm_f32le", "-"]) + .stdin(Stdio::null()) + .output() + .expect("run ffmpeg"); + let samples: Vec = out.stdout.as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes(*b)).collect(); + let planar = (0..channels).map(|c| samples.iter().skip(c).step_by(channels).copied().collect()).collect(); + (planar, String::from_utf8_lossy(&out.stderr).into_owned()) +} + +#[test] +fn ffmpeg_decodes_our_streams_to_the_input() { + let Some(ff) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("mp2enc"); + for c in CASES { + let n = c.rate as usize * 2 + 777; + let input = inputs(c, n); + let bytes = encode(Config::cbr(c.rate, c.channels, c.kbps), &input, 1000); + let path = dir.join(format!("{}_{}_{}ch_{}k.mp2", c.name, c.rate, c.channels, c.kbps)); + std::fs::write(&path, &bytes).expect("write"); + let (dec, err) = ffmpeg_decode(&ff, &path, c.channels); + assert!(err.trim().is_empty(), "{}: ffmpeg reported: {err}", path.display()); + let d = DELAY as usize; + assert!(dec[0].len() >= n + d, "{}: decoded {} samples, need {}", c.name, dec[0].len(), n + d); + let s = (0..c.channels).map(|ch| snr(&input[ch], &dec[ch][d..d + n])).sum::() / c.channels as f64; + println!("{:<7} {:>5} Hz {}ch {:>3} kbps: SNR {s:.2} dB (ffmpeg)", c.name, c.rate, c.channels, c.kbps); + assert!(s >= c.min_snr, "{} {} Hz {}ch {} kbps: SNR {s:.2} dB under {}", c.name, c.rate, c.channels, c.kbps, c.min_snr); + } +} diff --git a/crates/audio/tests/vmd.rs b/crates/audio/tests/vmd.rs new file mode 100644 index 000000000..145aafa79 --- /dev/null +++ b/crates/audio/tests/vmd.rs @@ -0,0 +1,280 @@ +//! VMD sound decoder tests. ffmpeg reads VMD but cannot write it, so the files come from the +//! test kit's VMD writer. The decoder must return the samples that were packed, and the same +//! samples as ffmpeg (skipped without ffmpeg). + +use std::process::Command; + +use craft_audio::AudioError; +use craft_audio::vmd::{Decoder, Error}; +use craft_media::vmd::{FrameKind, open}; +use craft_media_testkit::hostile::Rng; +use craft_media_testkit::vmd::{Audio, Frame, Spec, build, dpcm_pack}; + +/// (frame length field, audio flags, channels, 16-bit): every layout the decoder handles. +const FORMATS: [(i16, u16, usize, bool); 6] = + [(50, 0, 1, false), (50, 0x200, 2, false), (50, 0x8000, 2, false), (-50, 0, 1, true), (-50, 0x200, 2, true), (-50, 0x8000, 2, true)]; + +fn spec(frame_length: i16, flags: u16) -> Spec { + let mut spec = Spec::new(4, 4); + spec.audio = Some(Audio { sample_rate: 22050, frame_length, buffers: 5, flags }); + spec +} + +fn decoder(frame_length: i16, flags: u16) -> Decoder { + Decoder::new(&build(&spec(frame_length, flags), &[])).unwrap() +} + +/// One block of random sound: its bytes in the file and the samples it decodes to. +fn block(rng: &mut Rng, d: &Decoder) -> (Vec, Vec) { + let n = d.block_samples() * d.channels(); + if d.bits() == 8 { + let bytes: Vec = (0..n).map(|_| rng.next_u64() as u8).collect(); + let samples = bytes.iter().map(|&b| (i16::from(b) - 0x80) << 8).collect(); + return (bytes, samples); + } + // a random walk, so that the steps are of every size + let mut last = [0i32; 2]; + let samples: Vec = (0..n) + .map(|i| { + let bits = 1 + rng.below(15); + let step = rng.below(1 << bits) as i32 - (1 << (bits - 1)); + let s = &mut last[i % d.channels()]; + *s = (*s + step).clamp(-32768, 32767); + *s as i16 + }) + .collect(); + dpcm_pack(&samples, d.channels()) +} + +/// A file of sound frames (with a small picture each, as ffmpeg expects video) and the samples +/// expected of it. The first frame is a mask frame: one silent block, then four of sound. +fn movie(seed: u64, frame_length: i16, flags: u16) -> (Vec, Vec) { + let spec = spec(frame_length, flags); + let d = decoder(frame_length, flags); + let mut rng = Rng(seed | 1); + let mut picture = vec![2u8]; + picture.extend([9; 16]); + let silence = vec![0i16; d.block_samples() * d.channels()]; + let mut want = Vec::new(); + let mut blocks = Vec::new(); + for n in 0..12 { + let sound = match n { + 0 => { + let mut data = 1u32.to_le_bytes().to_vec(); + want.extend_from_slice(&silence); + for _ in 0..4 { + let (bytes, samples) = block(&mut rng, &d); + data.extend_from_slice(&bytes); + want.extend_from_slice(&samples); + } + Frame::audio(2, data) + } + _ if rng.below(4) == 0 => { + want.extend_from_slice(&silence); + Frame::audio(3, vec![]) + } + _ => { + let (bytes, samples) = block(&mut rng, &d); + want.extend_from_slice(&samples); + Frame::audio(1, bytes) + } + }; + blocks.push(vec![sound, Frame::video([0, 0, 3, 3], false, picture.clone())]); + } + (build(&spec, &blocks), want) +} + +fn decode_all(bytes: &[u8]) -> Vec { + let file = open(bytes).unwrap(); + let d = Decoder::new(file.header_bytes()).unwrap(); + let mut out = Vec::new(); + for (i, frame) in file.frames.iter().enumerate() { + if let FrameKind::Audio { flags } = frame.kind { + out.extend(d.decode(flags, &file.read_frame(bytes, i).unwrap()).unwrap()); + } + } + out +} + +#[test] +fn decodes_the_samples_that_were_packed() { + for (i, (frame_length, flags, channels, sixteen)) in FORMATS.into_iter().enumerate() { + let d = decoder(frame_length, flags); + assert_eq!((d.channels(), d.bits(), d.sample_rate()), (channels, if sixteen { 16 } else { 8 }, 22050), "format {i}"); + // old-style stereo counts both channels in the frame length + assert_eq!(d.block_samples(), if flags & 0x8000 != 0 { 25 } else { 50 }, "format {i}"); + let (bytes, want) = movie(i as u64 + 1, frame_length, flags); + assert_eq!(want.len(), 16 * d.block_samples() * channels); + assert!(decode_all(&bytes) == want, "format {i}"); + } +} + +#[test] +fn matches_ffmpeg() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg_or_skip("vmd sound oracle") else { return }; + let dir = craft_media_testkit::private_dir("vmd-sound"); + for (i, (frame_length, flags, ..)) in FORMATS.into_iter().enumerate() { + let (bytes, _) = movie(i as u64 + 1, frame_length, flags); + let path = dir.join(format!("sound{i}.vmd")); + std::fs::write(&path, &bytes).unwrap(); + let out = Command::new(&ffmpeg).args(["-v", "error", "-i"]).arg(&path).args(["-vn", "-f", "s16le", "-"]).output().unwrap(); + assert!(out.status.success() && out.stderr.is_empty(), "format {i}: ffmpeg: {}", String::from_utf8_lossy(&out.stderr)); + let theirs: Vec = out.stdout.as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect(); + assert!(theirs == decode_all(&bytes), "format {i} differs from ffmpeg"); + } + std::fs::remove_dir_all(&dir).unwrap(); +} + +#[test] +fn sixteen_bit_steps() { + // values ffmpeg gave for this block: the first sample, then signed steps from the table + let mut data = 1000i16.to_le_bytes().to_vec(); + data.extend([1, 1, 1, 0x81, 0x81, 2, 3, 0x7F, 0xFF, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]); + let d = decoder(-20, 0); + assert_eq!(d.block_bytes(), 21); + assert_eq!( + d.decode(1, &data).unwrap(), + [1000, 1008, 1016, 1024, 1016, 1008, 1024, 1056, 17440, 1056, 1056, 1056, 1056, 1056, 1056, 1056, 1056, 1056, 1056, 1064] + ); + // stereo: the channels take turns + let mut data = [1000i16.to_le_bytes(), (-1000i16).to_le_bytes()].concat(); + data.extend([1, 0x82].repeat(3)); + let d = decoder(-4, 0x200); + assert_eq!(d.decode(1, &data).unwrap(), [1000, -1000, 1008, -1016, 1016, -1032, 1024, -1048]); + // a flags 1 frame of several blocks: each block starts from its own first samples + let (first, first_samples) = dpcm_pack(&[100, -100, 300, -50, 200, 0, 1000, 500], 2); + let (second, second_samples) = dpcm_pack(&[-7000, 7000, -6000, 6500, -6100, 6400, -3000, 3000], 2); + assert_eq!(d.decode(1, &[first, second, vec![1, 2, 3]].concat()).unwrap(), [first_samples, second_samples].concat()); + // steps past 16 bits stop at the ends + let mut data = 30000i16.to_le_bytes().to_vec(); + data.extend([0x7F, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF]); + assert_eq!(decoder(-7, 0).decode(1, &data).unwrap(), [30000, 32767, 16383, -1, -16385, -32768, -32768]); +} + +#[test] +fn eight_bit_and_silence() { + let d = decoder(4, 0); + assert_eq!(d.decode(1, &[0x80, 0x00, 0xFF, 0x70]).unwrap(), [0, -32768, 0x7F00, -0x1000]); + assert_eq!(d.decode(3, &[]).unwrap(), [0; 4]); + assert_eq!(d.decode(1, &[]).unwrap(), [0i16; 0]); + assert_eq!(decoder(4, 0x200).decode(3, &[]).unwrap(), [0; 8]); + // a flags 1 frame of more than one block plays every whole block + assert_eq!( + d.decode(1, &[0x80, 0x81, 0x82, 0x83, 0x90, 0x91, 0x92, 0x93, 0xA0]).unwrap(), + [0, 0x100, 0x200, 0x300, 0x1000, 0x1100, 0x1200, 0x1300] + ); + assert_eq!(decoder(-4, 0x8000).decode(3, &[]).unwrap(), [0; 4]); +} + +#[test] +fn silence_mask_runs_bit_by_bit() { + let d = decoder(2, 0); + let frame = |mask: u32, data: &[u8]| d.decode(2, &[&mask.to_le_bytes()[..], data].concat()); + let (a, b) = ([0x90, 0x91], [0xA0, 0xA1]); + let (sa, sb) = ([0x1000, 0x1100], [0x2000, 0x2100]); + assert_eq!(frame(0, &[a, b].concat()).unwrap(), [sa, sb].concat()); + // silent, sound, silent, sound + assert_eq!(frame(0b0101, &[a, b].concat()).unwrap(), [[0, 0], sa, [0, 0], sb].concat()); + // game files set a bit for every block when all are silent + assert_eq!(frame(0b0111, &[]).unwrap(), [0; 6]); + // a trailing part of a block is left out + assert_eq!(frame(0, &[0x90, 0x91, 0xA0]).unwrap(), sa); + assert_eq!(d.decode(2, &[0, 0, 0]), Err(Error::Invalid("the silence mask is cut short"))); +} + +#[test] +fn bad_input_is_an_error() { + let d = decoder(-20, 0); + assert_eq!(d.decode(1, &[0; 20]), Err(Error::Invalid("a block of sound is cut short"))); + assert_eq!(d.decode(4, &[0; 21]), Err(Error::Unsupported("unknown sound frame flags"))); + assert_eq!(d.decode(4, &[]), Err(Error::Unsupported("unknown sound frame flags"))); + // in the file API's error: unsupported stays unsupported, the rest is malformed input + assert!(matches!(AudioError::from(Error::Unsupported("x")), AudioError::Unsupported(_))); + assert!(matches!(AudioError::from(Error::Invalid("x")), AudioError::Malformed(_))); + + let good = build(&spec(20, 0), &[]); + let with = |patch: &dyn Fn(&mut Vec)| { + let mut h = good.clone(); + patch(&mut h); + Decoder::new(&h).err() + }; + assert_eq!(with(&|_| {}), None); + assert_eq!(with(&|h| h.truncate(815)), Some(Error::Invalid("the header is shorter than 816 bytes"))); + assert_eq!(with(&|h| h[0] = 0), Some(Error::Invalid("not a VMD header"))); + assert_eq!(with(&|h| h[17] = 0), Some(Error::Invalid("the file has no sound"))); + assert_eq!(with(&|h| h[804..806].fill(0)), Some(Error::Invalid("the file has no sound"))); + assert_eq!(with(&|h| h[810] = 0x10), Some(Error::Unsupported("IMA ADPCM sound"))); + // a frame length of nothing decodes to nothing + let mut empty = good.clone(); + empty[806..808].fill(0); + let d = Decoder::new(&empty).unwrap(); + assert_eq!(d.decode(1, &[1, 2, 3]).unwrap(), [0i16; 0]); + assert_eq!(d.decode(2, &[0, 0, 0, 0, 1, 2]).unwrap(), [0i16; 0]); +} + +#[test] +fn hostile_input_never_panics() { + for (i, (frame_length, flags, ..)) in FORMATS.into_iter().enumerate() { + let (bytes, _) = movie(i as u64 + 1, frame_length, flags); + craft_media_testkit::hostile::hammer(&format!("vmd sound format {i}"), &bytes, 10_000, |d| { + let Ok(file) = open(d) else { return }; + let Ok(decoder) = Decoder::new(file.header_bytes()) else { return }; + for (i, frame) in file.frames.iter().enumerate() { + let FrameKind::Audio { flags } = frame.kind else { continue }; + if let Ok(data) = file.read_frame(d, i) { + let _ = decoder.decode(flags, &data); + } + } + }); + } +} + +/// Real files, for whoever has some: the sound of every `.vmd` in the directory +/// `CRAFT_MEDIA_VMD_SAMPLES` names must decode to the samples ffmpeg gets. Game files are not +/// redistributable, so none are in the repository and the test is skipped without the variable. +#[test] +fn real_files_match_ffmpeg() { + let Some(dir) = std::env::var_os("CRAFT_MEDIA_VMD_SAMPLES").filter(|d| !d.is_empty()) else { + craft_media_testkit::skip_test("vmd samples", "CRAFT_MEDIA_VMD_SAMPLES is not set"); + return; + }; + let Some(ffmpeg) = craft_media_testkit::ffmpeg_or_skip("vmd sound samples") else { return }; + let mut paths: Vec<_> = std::fs::read_dir(&dir) + .unwrap() + .filter_map(|e| Some(e.ok()?.path())) + .filter(|p| p.extension().is_some_and(|e| e.eq_ignore_ascii_case("vmd"))) + .collect(); + paths.sort(); + assert!(!paths.is_empty(), "no .vmd files in CRAFT_MEDIA_VMD_SAMPLES"); + let (mut files, mut samples) = (0, 0); + for path in &paths { + let name = path.display(); + let source = std::fs::File::open(path).unwrap(); + let file = open(&source).unwrap(); + if file.audio_params().is_none() { + continue; + } + let d = Decoder::new(file.header_bytes()).unwrap(); + let mut ours = Vec::new(); + for (i, frame) in file.frames.iter().enumerate() { + let FrameKind::Audio { flags } = frame.kind else { continue }; + let mut data = file.read_frame(&source, i).unwrap(); + if flags == 2 && data.len() >= 4 { + // ffmpeg plays a mask frame's silent blocks before its sound; put ours in that + // order to compare + let silent = u32::from_le_bytes([data[0], data[1], data[2], data[3]]).count_ones() as usize; + ours.resize(ours.len() + silent * d.block_samples() * d.channels(), 0); + data[..4].fill(0); + } + ours.extend(d.decode(flags, &data).unwrap_or_else(|e| panic!("{name}: frame {i}: {e}"))); + } + let out = Command::new(&ffmpeg).args(["-v", "quiet", "-i"]).arg(path).args(["-vn", "-f", "s16le", "-"]).output().unwrap(); + let theirs: Vec = out.stdout.as_chunks::<2>().0.iter().map(|b| i16::from_le_bytes(*b)).collect(); + if let Some(at) = (0..ours.len().max(theirs.len())).find(|&i| ours.get(i) != theirs.get(i)) { + panic!("{name}: sample {at} differs from ffmpeg ({} samples here, {} there)", ours.len(), theirs.len()); + } + files += 1; + samples += ours.len(); + } + println!("{files} files, {samples} samples match ffmpeg"); +} diff --git a/crates/audio/tests/vorbis_decode_hostile.rs b/crates/audio/tests/vorbis_decode_hostile.rs new file mode 100644 index 000000000..fba004e10 --- /dev/null +++ b/crates/audio/tests/vorbis_decode_hostile.rs @@ -0,0 +1,230 @@ +//! Hostile input to the Vorbis decoder: damaged headers and packets, truncations, and headers that +//! ask for absurd sizes. Every case is an error or a result, never a panic or a large allocation. + +use craft_audio::vorbis::decoder::{Decoder, Error, decode_ogg}; +use craft_audio::{AudioBuffer, OggVorbisOptions, encode_ogg_vorbis}; + +fn xorshift(seed: &mut u32) -> u32 { + *seed ^= *seed << 13; + *seed ^= *seed >> 17; + *seed ^= *seed << 5; + *seed +} + +struct Parts { + ogg: Vec, + headers: Vec>, + packets: Vec>, +} + +fn parts(channels: usize) -> Parts { + let signal: Vec> = (0..channels) + .map(|c| (0..20_000).map(|i| ((i as f32 * (0.03 + 0.01 * c as f32)).sin() * 0.4) + ((i * 7 % 13) as f32 - 6.0) / 60.0).collect()) + .collect(); + let ogg = + encode_ogg_vorbis(&AudioBuffer { sample_rate: 44_100, channels: signal }, &OggVorbisOptions::default().with_quality(4.0)).expect("encode"); + let file = craft_media::ogg::open(ogg.as_slice()).expect("open"); + let s = &file.streams[0]; + let packets = (0..s.packets.len()).map(|i| file.read_packet(ogg.as_slice(), 0, i).expect("packet")).collect(); + Parts { headers: s.headers.clone(), packets, ogg } +} + +fn decoder(p: &Parts) -> Decoder { + Decoder::new(&p.headers[0], &p.headers[1], &p.headers[2]).expect("valid headers") +} + +#[test] +fn every_truncated_header_is_an_error() { + let p = parts(2); + for which in [0usize, 2] { + for n in 0..p.headers[which].len() { + let mut h = p.headers.clone(); + h[which].truncate(n); + assert!(Decoder::new(&h[0], &h[1], &h[2]).is_err(), "header {which} cut to {n} bytes"); + } + } + // A damaged comment header is not fatal. + let mut h = p.headers.clone(); + h[1].truncate(12); + let d = Decoder::new(&h[0], &h[1], &h[2]).expect("comments are best effort"); + assert!(d.comments().comments.is_empty()); + assert!(Decoder::new(&p.headers[0], &[], &p.headers[2]).is_err(), "the comment header still needs its tag"); +} + +#[test] +fn damaged_headers_never_panic() { + let p = parts(2); + let mut seed = 99u32; + for which in [0usize, 2] { + let len = p.headers[which].len(); + for _ in 0..800 { + let mut h = p.headers.clone(); + for _ in 0..1 + xorshift(&mut seed) % 3 { + let at = xorshift(&mut seed) as usize % len; + h[which][at] = xorshift(&mut seed) as u8; + } + if let Ok(mut d) = Decoder::new(&h[0], &h[1], &h[2]) { + // A setup that survives must also survive audio packets. + for pk in p.packets.iter().take(6) { + let _ = d.decode_packet(pk); + } + } + } + } +} + +#[test] +fn damaged_packets_never_panic() { + let p = parts(2); + let mut seed = 7u32; + let mut d = decoder(&p); + for pk in &p.packets { + for _ in 0..6 { + let mut bad = pk.clone(); + match xorshift(&mut seed) % 3 { + 0 => bad.truncate(xorshift(&mut seed) as usize % (bad.len() + 1)), + 1 => { + let at = xorshift(&mut seed) as usize % bad.len(); + bad[at] = xorshift(&mut seed) as u8; + } + _ => bad = (0..xorshift(&mut seed) % 300).map(|_| xorshift(&mut seed) as u8).collect(), + } + let _ = d.decode_packet(&bad); + } + } + // The decoder still decodes good packets after all that. + d.reset(); + assert!(d.decode_packet(&p.packets[3]).is_ok()); +} + +#[test] +fn header_packets_and_empty_packets_are_not_audio() { + let p = parts(1); + let mut d = decoder(&p); + assert_eq!(d.decode_packet(&p.headers[0]), Err(Error::NotAudio)); + assert_eq!(d.decode_packet(&p.headers[2]), Err(Error::NotAudio)); + assert!(matches!(d.decode_packet(&[]), Err(Error::Packet(_)))); +} + +#[test] +fn damaged_files_never_panic() { + let p = parts(2); + let mut seed = 31u32; + for _ in 0..120 { + let mut bad = p.ogg.clone(); + for _ in 0..1 + xorshift(&mut seed) % 4 { + let at = xorshift(&mut seed) as usize % bad.len(); + bad[at] = xorshift(&mut seed) as u8; + } + let _ = decode_ogg(&bad); + bad.truncate(xorshift(&mut seed) as usize % bad.len()); + let _ = decode_ogg(&bad); + } + assert!(matches!(decode_ogg(b"not an ogg file"), Err(Error::Ogg(_)))); + assert!(matches!(decode_ogg(&[]), Err(Error::Ogg(_)))); +} + +/// A bit writer for hand-built setups. +#[derive(Default)] +struct W(Vec, usize); +impl W { + fn put(&mut self, v: u64, n: u32) { + for i in 0..n { + if self.1.is_multiple_of(8) { + self.0.push(0); + } + let last = self.0.len() - 1; + self.0[last] |= (((v >> i) & 1) as u8) << (self.1 % 8); + self.1 += 1; + } + } +} + +fn setup_with_first_book(book: impl FnOnce(&mut W)) -> Vec { + let mut w = W::default(); + w.put(5, 8); + for c in b"vorbis" { + w.put(u64::from(*c), 8); + } + w.put(0, 8); // one book + book(&mut w); + w.0 +} + +#[test] +fn absurd_codebook_sizes_are_refused_before_allocating() { + let p = parts(1); + let try_setup = |setup: Vec| Decoder::new(&p.headers[0], &p.headers[1], &setup); + // 2^24 - 1 entries. + assert!( + try_setup(setup_with_first_book(|w| { + w.put(0x56_4342, 24); + w.put(1, 16); + w.put(0xFF_FFFF, 24); + w.put(1, 1); // ordered + w.put(0, 5); + })) + .is_err() + ); + // An ordered book whose lengths overrun its entries. + assert!( + try_setup(setup_with_first_book(|w| { + w.put(0x56_4342, 24); + w.put(1, 16); + w.put(8, 24); + w.put(1, 1); + w.put(0, 5); + w.put(0xFF, 4); // asks for more codewords of length 1 than there are entries + })) + .is_err() + ); + // A lookup table of 65535 dimensions over a million entries: 69 billion values. + assert!( + try_setup(setup_with_first_book(|w| { + w.put(0x56_4342, 24); + w.put(0xFFFF, 16); + w.put(1 << 20, 24); + w.put(1, 1); // ordered + w.put(19, 5); // length 20 + w.put(1 << 20, 21); // all the entries + w.put(2, 4); // lookup type 2 + w.put(0, 32); + w.put(0, 32); + w.put(0, 4); + w.put(0, 1); + })) + .is_err() + ); + // A million-entry book with a legitimate tree but a lookup table that is not in the packet. + assert!( + try_setup(setup_with_first_book(|w| { + w.put(0x56_4342, 24); + w.put(4, 16); + w.put(1 << 20, 24); + w.put(1, 1); + w.put(19, 5); + w.put(1 << 20, 21); + w.put(1, 4); // lookup type 1 + w.put(0, 32); + w.put(0, 32); + w.put(15, 4); + w.put(0, 1); + })) + .is_err() + ); +} + +#[test] +fn identification_header_limits() { + let p = parts(1); + let mut h = p.headers[0].clone(); + let setup = &p.headers[2]; + h[11] = 0; // no channels + assert!(matches!(Decoder::new(&h, &p.headers[1], setup), Err(Error::Header(_)))); + let mut h = p.headers[0].clone(); + h[28] = 0x95; // a short block size of 2^5 is below the 64 Vorbis allows + assert!(matches!(Decoder::new(&h, &p.headers[1], setup), Err(Error::Header(_)))); + let mut h = p.headers[0].clone(); + h[7] = 1; // version 1 + assert!(matches!(Decoder::new(&h, &p.headers[1], setup), Err(Error::Header(_)))); +} diff --git a/crates/audio/tests/vorbis_decode_oracle.rs b/crates/audio/tests/vorbis_decode_oracle.rs new file mode 100644 index 000000000..a23d2a954 --- /dev/null +++ b/crates/audio/tests/vorbis_decode_oracle.rs @@ -0,0 +1,216 @@ +//! The Vorbis decoder against ffmpeg's as the reference (oracle; skipped when ffmpeg is absent, a +//! failure with `CRAFT_MEDIA_REQUIRE_ORACLES=1`). Streams come from two encoders, this crate's and +//! ffmpeg's own, so the setups differ: different floors, residues, block sizes, channel counts and +//! coupling. Both decoders must return the same samples. + +use craft_audio::AudioBuffer; +use craft_audio::vorbis::decoder::{Decoder, decode_ogg}; +use craft_audio::{OggVorbisOptions, encode_ogg_vorbis}; +use std::path::Path; +use std::process::Command; + +fn xorshift(seed: &mut u32) -> u32 { + *seed ^= *seed << 13; + *seed ^= *seed >> 17; + *seed ^= *seed << 5; + *seed +} + +/// A signal with tones, noise bursts, clicks and silence, different in every channel. +fn signal(rate: u32, channels: usize, frames: usize) -> Vec> { + let mut seed = 0x1234_5678u32; + (0..channels) + .map(|c| { + (0..frames) + .map(|i| { + let t = i as f64 / f64::from(rate); + let tone = + (t * (220.0 + 110.0 * c as f64) * std::f64::consts::TAU).sin() * 0.3 + (t * 3100.0 * std::f64::consts::TAU).sin() * 0.05; + let noise = (f64::from(xorshift(&mut seed) % 2000) - 1000.0) / 6000.0; + let s = match (i / (rate as usize / 4)) % 6 { + 0 | 1 => tone, + 2 => noise, + 3 => 0.0, + 4 => tone + if i % 3000 < 8 { 0.6 } else { 0.0 }, + _ => tone * (t * 4.0).sin(), + }; + s as f32 + }) + .collect() + }) + .collect() +} + +fn ffmpeg_decode(ffmpeg: &Path, ogg: &Path, channels: usize) -> Vec> { + let out = Command::new(ffmpeg) + .args(["-v", "error", "-nostdin", "-i"]) + .arg(ogg) + .args(["-f", "f32le", "-acodec", "pcm_f32le", "-"]) + .output() + .expect("run ffmpeg"); + assert!(out.status.success(), "ffmpeg failed on {}: {}", ogg.display(), String::from_utf8_lossy(&out.stderr)); + let all: Vec = out.stdout.as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes(*b)).collect(); + (0..channels).map(|c| all.iter().skip(c).step_by(channels).copied().collect()).collect() +} + +/// Each of our channels matches a different one of theirs (ffmpeg reorders the channels of surround +/// streams), to within float rounding. +fn assert_same(name: &str, ours: &[Vec], theirs: &[Vec]) { + assert_prefix(name, ours, theirs, true); +} + +/// As [`assert_same`], but with `exact` unset ffmpeg may return more samples than we do (it does +/// not always trim a stream to its last granule position); the common part must agree. +fn assert_prefix(name: &str, ours: &[Vec], theirs: &[Vec], exact: bool) { + assert_eq!(ours.len(), theirs.len(), "{name}: channel count"); + assert!(ours.iter().chain(theirs).flatten().all(|v| v.is_finite()), "{name}: non-finite oracle input or output"); + let mut used = vec![false; theirs.len()]; + for (c, o) in ours.iter().enumerate() { + let mut best: Option<(usize, f32)> = None; + for (k, t) in theirs.iter().enumerate() { + if used[k] { + continue; + } + if exact { + assert_eq!(o.len(), t.len(), "{name}: channel {c} length {} vs ffmpeg {}", o.len(), t.len()); + } else { + assert!(o.len() <= t.len(), "{name}: channel {c} length {} vs ffmpeg {}", o.len(), t.len()); + } + let worst = o.iter().zip(t).map(|(a, b)| (a - b).abs()).fold(0f32, f32::max); + if best.is_none_or(|(_, w)| worst < w) { + best = Some((k, worst)); + } + } + let (k, worst) = best.expect("a free channel"); + used[k] = true; + assert!(worst < 2e-4, "{name}: channel {c} differs from ffmpeg's channel {k} by up to {worst}"); + } +} + +#[test] +fn ffmpeg_decodes_our_encoders_streams_to_the_same_samples() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("vorbis_decode"); + for (rate, channels, quality) in + [(44_100u32, 2usize, 6.0f32), (44_100, 1, 3.0), (48_000, 2, -1.0), (22_050, 1, 10.0), (44_100, 6, 5.0), (32_000, 8, 4.0)] + { + let buf = AudioBuffer { sample_rate: rate, channels: signal(rate, channels, rate as usize * 2 + 777) }; + let ogg = encode_ogg_vorbis(&buf, &OggVorbisOptions::default().with_quality(quality)).expect("encode"); + let file = dir.join(format!("ours_{rate}_{channels}_{quality}.ogg")); + std::fs::write(&file, &ogg).expect("write fixture"); + let decoded = decode_ogg(&ogg).expect("decode"); + assert_eq!(decoded.damaged_packets, 0); + assert_eq!(decoded.sample_rate, rate); + assert_same(&format!("our stream {rate} Hz {channels} ch q{quality}"), &decoded.channels, &ffmpeg_decode(&ffmpeg, &file, channels)); + } +} + +/// ffmpeg's own Vorbis encoder (stereo only) writes setups ours does not: coupled channels, residue +/// type 2, floor classes with subclasses and master books, two block sizes. The reference is +/// Symphonia, an independent decoder. ffmpeg's decoder agrees on the first channel but not on the +/// second of these streams, where it differs from both Symphonia and this decoder; the stream does +/// not show which reading it means (the channel comes back poorly, about 3 dB SNR, in all three), +/// so ffmpeg is compared on the first channel only. The setups ffmpeg's decoder does read the same +/// way as we do are covered, on both channels, in `vorbis_decode_synthetic.rs`. +#[test] +fn we_decode_ffmpegs_encoder_streams_like_symphonia() { + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("vorbis_decode"); + for (rate, bitrate) in [(44_100u32, "128k"), (48_000, "96k"), (22_050, "48k"), (32_000, "64k")] { + let channels = 2usize; + let pcm: Vec = { + let s = signal(rate, channels, rate as usize * 2 + 301); + (0..s[0].len()).flat_map(|i| s.iter().map(move |c| c[i])).collect() + }; + let raw = dir.join(format!("src_{rate}_{channels}.f32")); + std::fs::write(&raw, pcm.iter().flat_map(|v| v.to_le_bytes()).collect::>()).expect("write source"); + let file = dir.join(format!("ffmpeg_{rate}_{channels}_{bitrate}.ogg")); + let out = Command::new(&ffmpeg) + .args(["-v", "error", "-nostdin", "-y", "-f", "f32le", "-ar"]) + .arg(rate.to_string()) + .arg("-ac") + .arg(channels.to_string()) + .arg("-i") + .arg(&raw) + .args(["-c:a", "vorbis", "-strict", "-2", "-b:a", bitrate]) + .arg(&file) + .output() + .expect("run ffmpeg"); + assert!(out.status.success(), "ffmpeg could not encode {}: {}", file.display(), String::from_utf8_lossy(&out.stderr)); + let ogg = std::fs::read(&file).expect("read"); + let ours = decode_ogg(&ogg).expect("decode"); + assert_eq!(ours.damaged_packets, 0, "{}", file.display()); + let (_, symphonia) = craft_audio::decode(&ogg, Some("ogg")).expect("symphonia"); + let name = format!("ffmpeg-encoded {rate} Hz {bitrate}"); + assert_prefix(&name, &ours.channels, &symphonia.channels, false); + // The first channel also agrees with ffmpeg's decoder. + let theirs = ffmpeg_decode(&ffmpeg, &file, channels); + assert_prefix(&format!("{name} (channel 0 against ffmpeg)"), &ours.channels[..1], &theirs[..1], true); + } +} + +#[test] +fn packets_decode_one_at_a_time_to_the_file_result() { + let buf = AudioBuffer { sample_rate: 44_100, channels: signal(44_100, 2, 30_000) }; + let ogg = encode_ogg_vorbis(&buf, &OggVorbisOptions::default().with_quality(5.0)).expect("encode"); + let file = craft_media::ogg::open(ogg.as_slice()).expect("open"); + let s = &file.streams[file.stream_of(craft_media::ogg::Codec::Vorbis).expect("vorbis")]; + let mut dec = Decoder::new(&s.headers[0], &s.headers[1], &s.headers[2]).expect("decoder"); + assert_eq!((dec.identification().channels, dec.identification().sample_rate), (2, 44_100)); + let mut got: Vec> = vec![Vec::new(); 2]; + for i in 0..s.packets.len() { + let p = file.read_packet(ogg.as_slice(), 0, i).expect("packet"); + for (a, b) in got.iter_mut().zip(dec.decode_packet(&p).expect("packet decodes")) { + a.extend(b); + } + } + let whole = decode_ogg(&ogg).expect("file"); + for (a, b) in got.iter().zip(&whole.channels) { + assert!(a.len() >= b.len() && a[..b.len()] == b[..]); + } + // After a reset the next packet only primes the overlap again. + dec.reset(); + let p = file.read_packet(ogg.as_slice(), 0, 5).expect("packet"); + assert!(dec.decode_packet(&p).expect("decodes").iter().all(Vec::is_empty)); +} + +#[test] +fn the_round_trip_through_our_encoder_is_faithful() { + let src = signal(44_100, 2, 44_100); + let buf = AudioBuffer { sample_rate: 44_100, channels: src.clone() }; + let ogg = encode_ogg_vorbis(&buf, &OggVorbisOptions::default().with_quality(8.0)).expect("encode"); + let out = decode_ogg(&ogg).expect("decode"); + assert_eq!(out.channels[0].len(), src[0].len()); + let (mut sig, mut err) = (0f64, 0f64); + for (a, b) in src[0].iter().zip(&out.channels[0]) { + sig += f64::from(*a) * f64::from(*a); + err += f64::from(a - b) * f64::from(a - b); + } + assert!(10.0 * (sig / err).log10() > 15.0, "SNR {:.1} dB", 10.0 * (sig / err).log10()); +} + +/// A stream from libvorbis itself (the repository's `tone.ogg` fixture, made with ffmpeg's libvorbis +/// wrapper): mono, 8 kHz, the lowest quality. +#[test] +fn a_libvorbis_stream_decodes_like_ffmpeg() { + let path = Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures/tone.ogg"); + let ogg = std::fs::read(&path).expect("fixture"); + let ours = decode_ogg(&ogg).expect("decode"); + assert_eq!((ours.sample_rate, ours.channels.len(), ours.damaged_packets), (8000, 1, 0)); + assert!(ours.comments.vendor.contains("Lavf") || ours.comments.vendor.contains("libVorbis"), "vendor {:?}", ours.comments.vendor); + assert!(ours.channels[0].iter().any(|s| s.abs() > 0.1), "the fixture is a tone"); + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + assert_prefix("libvorbis tone.ogg", &ours.channels, &ffmpeg_decode(&ffmpeg, &path, 1), false); +} + +#[test] +#[should_panic(expected = "non-finite oracle input or output")] +fn oracle_comparison_rejects_nan_output() { + assert_same("NaN output", &[vec![f32::NAN]], &[vec![0.0]]); +} + +#[test] +#[should_panic(expected = "non-finite oracle input or output")] +fn oracle_comparison_rejects_nan_reference() { + assert_same("NaN reference", &[vec![0.0]], &[vec![f32::NAN]]); +} diff --git a/crates/audio/tests/vorbis_decode_synthetic.rs b/crates/audio/tests/vorbis_decode_synthetic.rs new file mode 100644 index 000000000..46c48eced --- /dev/null +++ b/crates/audio/tests/vorbis_decode_synthetic.rs @@ -0,0 +1,384 @@ +//! Differential tests on streams built by hand: a setup header written here, with floor 0 and +//! floor 1 side by side, residues 0, 1 and 2, several submaps and channel coupling, followed by +//! random audio packets. Every packet of random bits is decodable, so the two decoders (ours and +//! ffmpeg's, the oracle; skipped when ffmpeg is absent, a failure with +//! `CRAFT_MEDIA_REQUIRE_ORACLES=1`) must return the same samples, and no encoder's habits narrow +//! what is exercised. Floor 0, residue 0 and multi-submap mappings are the parts no encoder here +//! writes. + +use craft_audio::vorbis::decoder::{Decoder, decode_ogg}; +use craft_media::ogg::{PageWriter, vorbis_comment}; +use std::process::Command; + +fn xorshift(seed: &mut u32) -> u32 { + *seed ^= *seed << 13; + *seed ^= *seed >> 17; + *seed ^= *seed << 5; + *seed +} + +/// A least-significant-bit-first bit writer. +#[derive(Default)] +struct W { + bytes: Vec, + bits: usize, +} + +impl W { + fn put(&mut self, v: u64, n: u32) { + for i in 0..n { + if self.bits.is_multiple_of(8) { + self.bytes.push(0); + } + let last = self.bytes.len() - 1; + self.bytes[last] |= (((v >> i) & 1) as u8) << (self.bits % 8); + self.bits += 1; + } + } + fn flag(&mut self, b: bool) { + self.put(u64::from(b), 1); + } +} + +fn float_bits(v: f64) -> u64 { + // The Vorbis float32 packing: sign, 10-bit exponent biased by 788, 21-bit mantissa. + if v == 0.0 { + return 0; + } + let (sign, a) = if v < 0.0 { (1u64 << 31, -v) } else { (0, v) }; + let mut exp = 0i32; + let mut m = a; + while m >= (1 << 21) as f64 { + m /= 2.0; + exp += 1; + } + while m < (1 << 20) as f64 { + m *= 2.0; + exp -= 1; + } + sign | (((exp + 788) as u64) << 21) | (m.round() as u64 & 0x1F_FFFF) +} + +/// A complete codebook: `entries` codewords all of length `len` (`entries == 2^len`), optionally +/// with a lookup table: `(type, minimum, delta, value_bits, multiplicands)`. +fn book(w: &mut W, dims: u32, entries: u32, len: u32, lookup: Option<(u32, f64, f64, u32, Vec)>) { + w.put(0x56_4342, 24); + w.put(u64::from(dims), 16); + w.put(u64::from(entries), 24); + w.flag(false); // not ordered + w.flag(false); // not sparse + for _ in 0..entries { + w.put(u64::from(len - 1), 5); + } + match lookup { + None => w.put(0, 4), + Some((ty, min, delta, bits, mult)) => { + w.put(u64::from(ty), 4); + w.put(float_bits(min), 32); + w.put(float_bits(delta), 32); + w.put(u64::from(bits - 1), 4); + w.flag(ty == 1); // sequence_p: cumulative for the floor 0 book + for m in mult { + w.put(u64::from(m), bits); + } + } + } +} + +struct Layout { + channels: u8, + /// The residue type of each of the two residues. + residue_types: [u32; 2], + /// The submap of each channel (0 or 1): submap 0 uses floor 0 and residue 0, submap 1 uses + /// floor 1 and residue 1. + mux: Vec, + coupling: Vec<(u8, u8)>, +} + +fn identification(channels: u8) -> Vec { + let mut w = W::default(); + w.put(1, 8); + for c in b"vorbis" { + w.put(u64::from(*c), 8); + } + w.put(0, 32); + w.put(u64::from(channels), 8); + w.put(16_000, 32); + w.put(0, 32); + w.put(0, 32); + w.put(0, 32); + w.put(8, 4); // short blocks: 256 + w.put(10, 4); // long blocks: 1024 + w.flag(true); + w.bytes +} + +fn setup(l: &Layout) -> Vec { + let mut w = W::default(); + w.put(5, 8); + for c in b"vorbis" { + w.put(u64::from(*c), 8); + } + // Books: 0 floor 0 vectors, 1 class book, 2 and 3 residue vectors, 4 floor 1 values. + w.put(4, 8); // five books + book(&mut w, 4, 16, 4, Some((1, 0.7, 0.2, 1, vec![0, 1]))); // lookup1_values(16, 4) = 2 + book(&mut w, 1, 4, 2, None); + book(&mut w, 2, 16, 4, Some((1, -0.4, 0.25, 2, vec![0, 1, 2, 3]))); // lookup1_values(16, 2) = 4 + book(&mut w, 4, 16, 4, Some((1, -0.3, 0.6, 1, vec![0, 1]))); + book(&mut w, 1, 128, 7, None); + // One time domain placeholder. + w.put(0, 6); + w.put(0, 16); + // Floors: 0 and 1. + w.put(1, 6); // two floors + w.put(0, 16); + w.put(8, 8); // order + w.put(16_000, 16); // rate + w.put(64, 16); // bark map size + w.put(8, 6); // amplitude bits + w.put(2, 8); // amplitude offset + w.put(0, 4); // one book + w.put(0, 8); + w.put(1, 16); + w.put(1, 5); // one partition + w.put(0, 4); // class 0 + w.put(2, 3); // dimension 3 + w.put(0, 2); // no subclasses + w.put(4 + 1, 8); // subclass book: book 4 (stored plus one) + w.put(1, 2); // multiplier 2 + w.put(8, 4); // rangebits + for x in [10, 40, 130] { + w.put(x, 8); + } + // Residues. + w.put(1, 6); // two residues + for ty in l.residue_types { + w.put(u64::from(ty), 16); + w.put(0, 24); // begin + w.put(if ty == 2 { 96 } else { 48 }, 24); // end + w.put(7, 24); // partition size 8 + w.put(3, 6); // four classifications + w.put(1, 8); // class book + for _ in 0..4 { + w.put(0b011, 3); // passes 0 and 1 + w.flag(false); + } + for class in 0..4 { + w.put(2 + (class % 2), 8); // pass 0 uses book 2 or 3 + w.put(3 - (class % 2), 8); // pass 1 uses book 3 or 2 + } + } + // One mapping, two submaps. + w.put(0, 6); + w.put(0, 16); + w.flag(true); + w.put(1, 4); // two submaps + w.flag(!l.coupling.is_empty()); + if !l.coupling.is_empty() { + w.put(l.coupling.len() as u64 - 1, 8); + let bits = if l.channels <= 1 { 0 } else { 8 - (l.channels - 1).leading_zeros() }; + for &(m, a) in &l.coupling { + w.put(u64::from(m), bits); + w.put(u64::from(a), bits); + } + } + w.put(0, 2); + for &m in &l.mux { + w.put(u64::from(m), 4); + } + for sub in 0..2u64 { + w.put(0, 8); + w.put(sub, 8); // floor + w.put(sub, 8); // residue + } + // Two modes over the one mapping. + w.put(1, 6); + for long in [false, true] { + w.flag(long); + w.put(0, 16); + w.put(0, 16); + w.put(0, 8); + } + w.flag(true); + w.bytes +} + +fn stream(l: &Layout, packets: usize, seed: &mut u32) -> Vec { + let mut pages = PageWriter::new(7); + let mut out = pages.header(&identification(l.channels)); + out.extend(pages.header(&vorbis_comment("synthetic", &[("TITLE", "hand built")]))); + out.extend(pages.header(&setup(l))); + // The window flags of a long block say whether its neighbours are long, so choose the block + // sizes first. + let longs: Vec = (0..packets).map(|_| !xorshift(seed).is_multiple_of(3)).collect(); + let mut granule = 0i64; + for i in 0..packets { + let long = longs[i]; + // Packet type 0, the mode bit, and for a long block the two neighbour flags. + let prev = i == 0 || longs[i - 1]; + let next = i + 1 >= packets || longs[i + 1]; + let mut w = W::default(); + w.flag(false); + w.flag(long); + if long { + w.flag(prev); + w.flag(next); + } + // Floor 0 needs a codebook number that exists, which random bits would not give, so the + // channels that use it (the first ones) are written properly: an amplitude, book 0 and two + // codewords of its vectors (a full tree of 4-bit codes: the code is the entry number). + for _ in 0..l.mux.iter().take_while(|&&m| m == 0).count() { + w.put(1 + u64::from(xorshift(seed)) % 24, 8); + w.put(0, 1); + for _ in 0..2 { + let entry = xorshift(seed) % 16; + for bit in (0..4).rev() { + w.put(u64::from(entry >> bit) & 1, 1); + } + } + } + // The rest is random bits, enough that no residue runs out of packet. + let mut p = w.bytes; + let fixed = p.len(); + p.extend((0..200 + xorshift(seed) as usize % 200).map(|_| xorshift(seed) as u8)); + let _ = fixed; + // The bits after the fixed fields start mid-byte: the last fixed byte keeps its own bits and + // takes random ones above them. + let used = w.bits % 8; + if used != 0 { + let last = fixed - 1; + p[last] |= (xorshift(seed) as u8) << used; + } + if i > 0 { + let size = |long: bool| if long { 1024 } else { 256 }; + granule += (size(longs[i - 1]) / 4 + size(long) / 4) as i64; + } + out.extend(pages.packet(&p, granule)); + } + out.extend(pages.finish(None)); + out +} + +/// `tolerance`: the largest difference from ffmpeg, as a fraction of the peak output. A floor 0 +/// curve is an exponential of a quotient that random coefficients can make very large, so where +/// two floors meet in one stream (ffmpeg computes in single precision, we in double) the results +/// agree only to about a thousandth of the peak. +fn run(name: &str, l: &Layout, seed: u32, tolerance: f32) { + let mut s = seed; + let ogg = stream(l, 40, &mut s); + // Packet by packet our decoder must accept every one. + let file = craft_media::ogg::open(ogg.as_slice()).expect("open"); + let st = &file.streams[0]; + let mut dec = Decoder::new(&st.headers[0], &st.headers[1], &st.headers[2]).expect("setup decodes"); + let mut total = vec![Vec::new(); usize::from(l.channels)]; + for i in 0..st.packets.len() { + let p = file.read_packet(ogg.as_slice(), 0, i).expect("packet"); + let pcm = dec.decode_packet(&p).unwrap_or_else(|e| panic!("{name}: packet {i}: {e}")); + for (t, c) in total.iter_mut().zip(pcm) { + t.extend(c); + } + } + let expected = usize::try_from(st.last_granule.expect("generated final granule")).expect("nonnegative granule"); + for channel in &total { + assert_eq!(channel.len(), expected, "{name}: decoded sample count"); + assert!(channel.iter().all(|v| v.is_finite()), "{name}: non-finite output"); + } + let whole = decode_ogg(&ogg).expect("whole file"); + assert_eq!(whole.channels, total, "{name}: packet and file decoding differ"); + let Some(ffmpeg) = craft_media_testkit::ffmpeg() else { return }; + let dir = craft_media_testkit::fixture_subdir("vorbis_synthetic"); + let path = dir.join(format!("{name}.ogg")); + std::fs::write(&path, &ogg).expect("write fixture"); + let out = Command::new(&ffmpeg) + .args(["-v", "error", "-nostdin", "-i"]) + .arg(&path) + .args(["-f", "f32le", "-acodec", "pcm_f32le", "-"]) + .output() + .expect("run ffmpeg"); + assert!(out.status.success(), "{name}: ffmpeg failed: {}", String::from_utf8_lossy(&out.stderr)); + let all: Vec = out.stdout.as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes(*b)).collect(); + let ch = usize::from(l.channels); + let theirs: Vec> = (0..ch).map(|c| all.iter().skip(c).step_by(ch).copied().collect()).collect(); + assert!(theirs.iter().flatten().all(|v| v.is_finite()), "{name}: non-finite ffmpeg output"); + for channel in &theirs { + assert!(channel.len() >= expected, "{name}: ffmpeg returned fewer than the expected samples"); + } + // ffmpeg puts the channels of surround streams in its own order, so each of ours is matched + // with the channel of theirs it agrees with best, and every one of theirs is used once. + let mut used = vec![false; ch]; + #[allow(clippy::needless_range_loop)] + for c in 0..ch { + let mut best: Option<(usize, f32, f32)> = None; + for (k, t) in theirs.iter().enumerate().filter(|(k, _)| !used[*k]) { + let n = total[c].len().min(t.len()); + assert!(n > 1000, "{name}: only {n} samples to compare"); + let scale = total[c][..n].iter().fold(1e-3f32, |m, v| m.max(v.abs())); + let worst = (0..n).map(|i| (total[c][i] - t[i]).abs()).fold(0f32, f32::max); + if best.is_none_or(|(_, w, sc)| worst / scale < w / sc) { + best = Some((k, worst, scale)); + } + } + let (k, worst, scale) = best.expect("a free channel"); + used[k] = true; + assert!(worst <= tolerance * scale + 1e-5, "{name}: channel {c} differs from ffmpeg's channel {k} by {worst} (peak {scale})"); + } +} + +#[test] +fn mono_floor_zero_and_residue_zero() { + run("mono_f0_r0", &Layout { channels: 1, residue_types: [0, 0], mux: vec![0], coupling: vec![] }, 11, 1e-4); +} + +#[test] +fn mono_floor_one_and_residue_one() { + run("mono_f1_r1", &Layout { channels: 1, residue_types: [1, 1], mux: vec![1], coupling: vec![] }, 12, 1e-4); +} + +#[test] +fn two_submaps_floor_zero_and_one() { + run("stereo_mixed", &Layout { channels: 2, residue_types: [0, 1], mux: vec![0, 1], coupling: vec![] }, 13, 3e-3); +} + +#[test] +fn coupled_stereo_residue_two() { + run("stereo_coupled_r2", &Layout { channels: 2, residue_types: [2, 2], mux: vec![1, 1], coupling: vec![(0, 1)] }, 14, 1e-4); +} + +#[test] +fn six_channels_with_coupling_and_submaps() { + let l = Layout { channels: 6, residue_types: [1, 2], mux: vec![0, 0, 0, 1, 1, 1], coupling: vec![(0, 3), (1, 2), (4, 5)] }; + run("six", &l, 15, 3e-3); +} + +#[test] +fn mono_floor_one_and_residue_zero() { + run("mono_f1_r0", &Layout { channels: 1, residue_types: [0, 0], mux: vec![1], coupling: vec![] }, 16, 1e-4); +} + +#[test] +fn mono_floor_zero_and_residue_one() { + run("mono_f0_r1", &Layout { channels: 1, residue_types: [1, 1], mux: vec![0], coupling: vec![] }, 17, 1e-4); +} + +/// A packet that names a floor 0 codebook that does not exist cannot be decoded (§6.2.2); the +/// decoder says so and the stream goes on with the next packet. +#[test] +fn a_floor_zero_codebook_that_does_not_exist_is_a_packet_error() { + let l = Layout { channels: 1, residue_types: [1, 1], mux: vec![0], coupling: vec![] }; + let mut seed = 5u32; + let ogg = stream(&l, 6, &mut seed); + let file = craft_media::ogg::open(ogg.as_slice()).expect("open"); + let st = &file.streams[0]; + let mut dec = Decoder::new(&st.headers[0], &st.headers[1], &st.headers[2]).expect("decoder"); + let good = file.read_packet(ogg.as_slice(), 0, 0).expect("packet"); + assert!(dec.decode_packet(&good).is_ok()); + // A short block: type 0, mode 0, then the 8 amplitude bits, then book number 1 (only 0 exists). + let mut w = W::default(); + w.flag(false); + w.flag(false); + w.put(9, 8); + w.put(1, 1); + w.put(0, 64); + assert!(matches!(dec.decode_packet(&w.bytes), Err(craft_audio::vorbis::decoder::Error::Packet(_)))); + assert!(dec.decode_packet(&good).is_ok(), "the decoder carries on"); +} diff --git a/crates/browse/src/links/tests.rs b/crates/browse/src/links/tests.rs index d667d0ec6..fa5cb12cb 100644 --- a/crates/browse/src/links/tests.rs +++ b/crates/browse/src/links/tests.rs @@ -49,18 +49,21 @@ fn monitor(files: &Arc, jobs: &Arc) -> LinkMonitor { LinkMonitor::new(files.clone(), jobs.clone(), Wake::none()) } +/// Absolute on every platform: a link path that is not is refused as invalid. +const FILE: &str = if cfg!(windows) { r"C:\p\a.png" } else { "/p/a.png" }; + // A file changes once: one LinkChange Ok -> Modified, and nothing on the following passes. #[trial] fn the_monitor_reports_a_change_once() { - let files = Disk::new(FakeLinkFiles::new().with("/p/a.png", b"abc", 1)); - let a = link(1, "/p/a.png", files.identity_of("/p/a.png")); + let files = Disk::new(FakeLinkFiles::new().with(FILE, b"abc", 1)); + let a = link(1, FILE, files.identity_of(FILE)); let jobs = Arc::new(ManualJobs::new()); let mut m = monitor(&files, &jobs); m.set(&[a], None); jobs.run_all(); assert_eq!(m.take_changes(), vec![LinkChange { key: 1, before: None, status: LinkStatus::Ok }]); - files.change(FakeLinkFiles::new().with("/p/a.png", b"abcd", 2)); + files.change(FakeLinkFiles::new().with(FILE, b"abcd", 2)); m.window_focused(); jobs.run_all(); assert_eq!(m.take_changes(), vec![LinkChange { key: 1, before: Some(LinkStatus::Ok), status: LinkStatus::Modified }]); @@ -77,10 +80,10 @@ fn the_monitor_reports_a_change_once() { // A check that finished before the link was updated is stale when it is taken in: it reports nothing, and the newer check decides. #[trial] fn a_check_older_than_known_now_is_dropped() { - let files = Disk::new(FakeLinkFiles::new().with("/p/a.png", b"abc", 1)); - let old = link(1, "/p/a.png", files.identity_of("/p/a.png")); - files.change(FakeLinkFiles::new().with("/p/a.png", b"abcd", 2)); - let updated = link(1, "/p/a.png", files.identity_of("/p/a.png")); + let files = Disk::new(FakeLinkFiles::new().with(FILE, b"abc", 1)); + let old = link(1, FILE, files.identity_of(FILE)); + files.change(FakeLinkFiles::new().with(FILE, b"abcd", 2)); + let updated = link(1, FILE, files.identity_of(FILE)); let jobs = Arc::new(ManualJobs::new()); let mut m = monitor(&files, &jobs); m.set(&[old], None); diff --git a/crates/browse/tests/it/relink.rs b/crates/browse/tests/it/relink.rs index 4de218139..275dc78d0 100644 --- a/crates/browse/tests/it/relink.rs +++ b/crates/browse/tests/it/relink.rs @@ -101,11 +101,15 @@ fn linked_keys(result: &DialogResult>) -> (Vec, Vec (outcome.linked.iter().map(|(key, _)| *key).collect(), outcome.offline.clone()) } +/// A folder path is absolute only with a drive on Windows. +const DRIVE: &str = if cfg!(windows) { "D:" } else { "" }; + #[trial] fn relink_others_offers_the_rows_the_remap_fits() { - let files = files(&[("/T7/shoot/a.mov", SAME), ("/T7/shoot/b.mov", SAME), ("/T7/shoot/c.mov", OTHER)]); + let files = + files(&[(&format!("{DRIVE}/T7/shoot/a.mov"), SAME), (&format!("{DRIVE}/T7/shoot/b.mov"), SAME), (&format!("{DRIVE}/T7/shoot/c.mov"), OTHER)]); let rows = vec![row(1, "Clip A", "C:\\shoot\\a.mov"), row(2, "Clip B", "C:\\shoot\\b.mov"), row(3, "Clip C", "C:\\shoot\\c.mov")]; - let mut rig = rig(rows, &files, "/T7/shoot", true, true); + let mut rig = rig(rows, &files, &format!("{DRIVE}/T7/shoot"), true, true); rig.search(); rig.click("Link"); rig.jobs.run_all(); diff --git a/crates/cloud-local/Cargo.toml b/crates/cloud-local/Cargo.toml new file mode 100644 index 000000000..39d6dfa6e --- /dev/null +++ b/crates/cloud-local/Cargo.toml @@ -0,0 +1,25 @@ +[package] +name = "craft-cloud-local" +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true +rust-version.workspace = true +description = "A reference CloudBackend over a local folder, proving the contract needs no specific provider" + +[lints] +workspace = true + +[dependencies] +# Resolution-time confinement: every path this crate resolves goes through a `Dir` capability +# opened on the configured root, never through an absolute OS path this crate builds itself. +# `craft-font-store` already depends on the lower-level `cap-primitives` for the same family of +# guarantee; this crate uses the ergonomic `cap-std` built on top of it instead of hand-rolling +# the equivalent `Dir`-style API again. +cap-std = "4" +craft-cloud = { workspace = true } +craft-ui = { workspace = true, features = ["cloud"] } + +[dev-dependencies] +tempfile = "3" +egui = { workspace = true } diff --git a/crates/cloud-local/README.md b/crates/cloud-local/README.md new file mode 100644 index 000000000..a5006c2ca --- /dev/null +++ b/crates/cloud-local/README.md @@ -0,0 +1,39 @@ +# craft-cloud-local + +A reference `CloudBackend` over one folder on disk, proving that `craft-cloud`'s contract needs +no specific provider behind it. + +## No-escape policy + +Every path this crate is handed, a `Job::List`/`Read`/`Write` path or a `Job::Create` name, is +confined to the configured root before anything touches a filesystem, in two layers. + +A path's segments are accepted only when each one parses as a single `Component::Normal`: no +`..`, no `.`, no empty segment, and no absolute form. A `Create` name goes through a stricter +check of its own, since it is one chosen name and not a path: it additionally refuses a +backslash, a colon, or a Windows reserved device name (`CON`, `COM1`, `CONIN$`, and so on), on +every platform this crate builds for, not only on Windows, because a chosen name reaches this +backend from whatever platform the UI runs on. An existing name that already has one of those +characters, discovered through `list`, stays reachable: `:` and `\` are not path separators on +any platform's filesystem, so refusing to read a real file back because of a byte in its name +(macOS stores a `/` typed in Finder as `:` on disk) would be a usability bug with no matching +security benefit. + +The second layer is the one that actually keeps resolution inside the root: every already +segment-checked relative path is handed to a [`cap-std`](https://docs.rs/cap-std) `Dir` +capability opened on the root, never joined onto the root as an absolute OS path this crate +builds itself. `cap-std` resolves one path component at a time against real, already-open +directory handles, so a symlink or (on Windows) a directory junction anywhere under the root, +dangling or already pointing outside, cannot walk resolution above the root. There is no separate +"does this still look like it is inside the root" check with a window for the directory tree to +change underneath it between the check and the actual read or write; the one resolution is the +open. + +## Hard links + +A hard link is not a symlink, and this backend does not refuse one: from inside the sandbox the +inode it names is an ordinary file. What it protects instead is the shared inode's content: a +write never truncates its target in place. It writes a new sibling file and renames that sibling +over the target, so the target's directory entry is replaced rather than its bytes being +overwritten. A rename only ever changes one name; it does not reach through to any other name, +inside the root or out, that happens to point at the same inode. diff --git a/crates/cloud-local/src/lib.rs b/crates/cloud-local/src/lib.rs new file mode 100644 index 000000000..715a87084 --- /dev/null +++ b/crates/cloud-local/src/lib.rs @@ -0,0 +1,510 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] + +//! A reference [`CloudBackend`] that treats one folder on disk as the cloud. +//! +//! [`craft_ui::cloud::CloudBackend`] names a contract and nothing about who +//! answers it. This crate is the proof: a working implementation that reaches +//! no service, a vendor, or a personal repo anybody else has to trust. An app +//! wires [`LocalBackend`] the same way it would wire a provider's own client, +//! by calling [`craft_ui::cloud::CloudFiles::connect`]. Swapping one for the +//! other is the whole point; nothing above the [`CloudBackend`] seam can tell +//! the difference. +//! +//! What this is not: a sync engine, a sharing service, or a place to keep a +//! credential. A folder has no concept of another account, so +//! [`Job::SharedWithMe`] answers empty and [`Job::Conversation`] answers with +//! a [`Fault`], and [`Account::capabilities`] claims neither. Reporting a +//! capability this backend cannot honour would be the broken window the +//! contract's own docs warn about. +//! +//! Every job answers on its own [`std::thread`]. [`CloudBackend::submit`] +//! must return before the file is opened, let alone read, or a twenty +//! megabyte document would freeze the window that called it. +//! +//! # The no-escape policy +//! +//! `Entry::id` and `Entry::path` are the same slash-separated path relative to +//! `root`, always starting with `/` below the root itself (the root's own +//! path is the empty string, matching [`Job::List`]'s contract), and a +//! [`Job::Create`] name is one plain file name, not a path at all. Neither is +//! an OS path string handed to `std::fs`. Confinement happens in two layers: +//! +//! 1. `confine_segment` (every path segment) and `confine_name` (a +//! `Create` name, stricter) reject `..`, `.`, an empty segment, an +//! absolute form, and anything that is not exactly one +//! [`std::path::Component::Normal`]. `confine_name` additionally refuses a +//! backslash, a colon, and a Windows reserved device name +//! (`CON`, `COM1`, `CONIN$`, ...) on every platform this crate builds for, +//! because a chosen name reaches this backend from whatever platform the +//! UI runs on. Browsing an *existing* name is more lenient: a literal `:` +//! or `\` already on disk (macOS stores a `/` typed in Finder as `:`) is +//! not itself a path separator on any platform's filesystem, so +//! `confine_segment` lets `list`, `read` and `write` keep such a name +//! reachable instead of discovering it and then refusing to open it. +//! 2. `open_root` opens `root` as a [`cap_std::fs::Dir`] capability once per +//! job. Every `list`, `read`, `write` and `create` routes its +//! already-segment-checked relative path through that one `Dir`, never +//! through an absolute OS path built by this crate. `cap_std` resolves one +//! component at a time against real, already-open directory handles, so a +//! symlink or a Windows junction anywhere under `root`, dangling or not, +//! cannot walk resolution above `root`: there is no separate "is this +//! still inside the root" check with a window for the directory tree to +//! change underneath it, because the one resolution *is* the open. +//! +//! A hard link is not a symlink and `cap_std` does not refuse one; the inode +//! it names is an ordinary file from inside the sandbox. [`write`] protects +//! it a different way: it always writes a sibling temporary file and renames +//! it over the target, rather than truncating the target in place. A rename +//! replaces one name's directory entry; it never reaches through to another +//! name that happens to point at the same inode outside `root`. + +use std::ffi::OsStr; +use std::fs; +use std::io::{Read as _, Write as _}; +use std::path::{Component, Path, PathBuf}; +use std::sync::atomic::{AtomicU64, Ordering}; + +use cap_std::fs::{Dir, OpenOptions}; +use craft_cloud::{Capability, Entry, EntryKind}; +use craft_ui::cloud::{Account, CloudBackend, Event, Fault, Job, Post}; + +/// Where "the cloud" lives for this backend: one directory on disk. +pub struct LocalBackend { + root: PathBuf, + /// Shown in the account badge. Nothing else reads it. + display: String, +} + +impl LocalBackend { + /// Treat `root` as the cloud. The directory is not created here; a + /// listing of a root that does not exist yet answers with a [`Fault`] + /// the same way a real provider's missing folder would. [`Job::Create`] + /// is the one exception, and always has been: it brings a fresh root + /// into existence itself, the same way a first Save As does not require + /// the destination folder to already be there. + pub fn new(root: PathBuf) -> LocalBackend { + LocalBackend { root, display: "Local disk".to_owned() } + } + + /// Name shown in the account badge, in place of the default "Local disk". + pub fn named(mut self, display: impl Into) -> LocalBackend { + self.display = display.into(); + self + } +} + +impl CloudBackend for LocalBackend { + fn submit(&self, job: Job, post: Post) { + let root = self.root.clone(); + match job { + // Nothing is saved between runs and nothing was ever signed into, + // so there is nothing to forget. The trait states no answer for + // this job; CloudFiles::sign_out clears its own state regardless + // of whether anything ever arrives. + Job::SignOut => {} + Job::Account | Job::SignIn => { + let display = self.display.clone(); + std::thread::spawn(move || post.send(Event::Account(Ok(account(display))))); + } + // There is no browser round trip: a local folder is already + // "linked" the moment it exists. Reporting that immediately, + // rather than inventing a URL nobody needs to visit, is what the + // contract calls honest. + Job::LinkStart | Job::LinkPoll(_) => { + std::thread::spawn(move || post.send(Event::Linked(Ok(true)))); + } + Job::List(path) => { + std::thread::spawn(move || post.send(Event::Listed { entries: list(&root, &path), path })); + } + Job::SharedWithMe => { + std::thread::spawn(move || post.send(Event::Shared(Ok(Vec::new())))); + } + Job::Read { entry, into } => { + std::thread::spawn(move || match read(&root, &entry) { + Ok((entry, bytes)) => post.send(Event::Read { entry, into, bytes: Ok(bytes) }), + Err(fault) => post.send(Event::Read { entry, into, bytes: Err(fault) }), + }); + } + Job::Write { uid, entry, bytes } => { + std::thread::spawn(move || post.send(Event::Saved { uid, entry: write(&root, &entry, &bytes) })); + } + Job::Create { uid, folder, name, bytes } => { + std::thread::spawn(move || post.send(Event::Saved { uid, entry: create(&root, &folder, &name, &bytes) })); + } + // No sharing, no accounts beyond this one, and so nowhere for a + // conversation to live. A reference backend that invented one + // would be lying about what a folder on disk can do. + Job::Conversation(_) => { + std::thread::spawn(move || { + post.send(Event::Conversation(Err(Fault::Refused("this reference backend has no shared workspace to converse in".to_owned())))) + }); + } + } + } +} + +fn account(display: String) -> Account { + Account { display, capabilities: vec![Capability::Files, Capability::Etags], provider_linked: true } +} + +/// Turns a [`Job`]'s slash-separated path into a path relative to `root`, +/// refusing anything that is not a run of ordinary names. The result is +/// never joined onto `root` as an OS path; every caller hands it to a +/// [`cap_std::fs::Dir`] opened on `root` instead, which is the layer that +/// actually keeps resolution from leaving `root`. +/// +/// `.` and repeated or leading slashes are just an empty segment and are +/// skipped, the same way a browser's address bar collapses them. Every other +/// segment goes through [`confine_segment`]. +fn relative(path: &str) -> Result { + let mut rel = PathBuf::new(); + for segment in path.split('/') { + if segment.is_empty() || segment == "." { + continue; + } + rel.push(confine_segment(segment)?); + } + Ok(rel) +} + +/// Confines one path segment to a single ordinary file or folder name. +/// +/// Accepted only when `segment` parses as exactly one [`Component::Normal`] +/// equal to `segment` itself: no empty name, no `.` or `..`, no absolute +/// form, and nothing left over for a second component to hide in. +/// +/// This is deliberately lenient about an ordinary character such as `:` or +/// `\` that is not, on its own, a path separator on any platform's +/// filesystem: `list` discovers real names from disk, and a name containing +/// one of those (macOS stores a `/` typed in Finder as `:` on disk) must stay +/// reachable by a later `read` or `write`, not become visible-but-unopenable. +/// [`confine_name`] is the stricter check for a name being chosen new, where +/// refusing those characters costs nothing and closes a real escape. +fn confine_segment(segment: &str) -> Result<&str, Fault> { + let mut components = Path::new(segment).components(); + match (components.next(), components.next()) { + (Some(Component::Normal(name)), None) if name == OsStr::new(segment) => Ok(segment), + _ => Err(Fault::Refused(format!("{segment} is not a plain file name"))), + } +} + +/// Windows device names that name a device rather than a file, with or +/// without a trailing extension (`CON`, `con.txt`, ...). Checked on every +/// platform: a name chosen here can end up read on a Windows client too. +const WINDOWS_RESERVED_NAMES: &[&str] = &[ + "CON", "PRN", "AUX", "NUL", "CONIN$", "CONOUT$", "COM1", "COM2", "COM3", "COM4", "COM5", "COM6", "COM7", "COM8", "COM9", "LPT1", "LPT2", "LPT3", + "LPT4", "LPT5", "LPT6", "LPT7", "LPT8", "LPT9", +]; + +fn is_windows_reserved_name(name: &str) -> bool { + let stem = name.split('.').next().unwrap_or(name); + WINDOWS_RESERVED_NAMES.iter().any(|reserved| stem.eq_ignore_ascii_case(reserved)) +} + +/// Confines a [`Job::Create`] `name` to a single ordinary file name that is +/// safe to choose on any platform, not only the one this crate is built for. +/// +/// Stricter than [`confine_segment`]: a backslash or colon is refused +/// outright first, because a Unix build's [`Component`] parser does not +/// treat either as a separator and would wave a Windows drive letter or UNC +/// prefix (`C:`, `\\server\share`) straight through as one ordinary name. A +/// Windows reserved device name is refused the same way. None of this costs +/// anything here, unlike applying it to a name `list` merely discovered. +fn confine_name(name: &str) -> Result<&str, Fault> { + if name.contains('\\') || name.contains(':') { + return Err(Fault::Refused(format!("{name} is not a plain file name"))); + } + if is_windows_reserved_name(name) { + return Err(Fault::Refused(format!("{name} is a reserved device name on Windows"))); + } + confine_segment(name) +} + +/// Opens `root` as the one ambient-authority capability this crate holds. +/// Every other path in this crate is resolved relative to the [`Dir`] this +/// returns, never as an absolute OS path built by string concatenation. +fn open_root(root: &Path) -> Result { + Dir::open_ambient_dir(root, cap_std::ambient_authority()).map_err(|error| io_fault(&error)) +} + +/// The path a listed child gets, given the folder it was found in. +fn child_path(folder: &str, name: &str) -> String { + format!("{}/{name}", folder.trim_end_matches('/')) +} + +/// An opaque version token for a file's current bytes. +/// +/// Not a timestamp for a person to read (that would go through `chrono`, per +/// this workspace's rule); just enough to tell "the file I read" from "the +/// file as it is now" apart, which is all a conditional write needs. +fn etag_of(meta: &cap_std::fs::Metadata) -> String { + let stamp = + meta.modified().ok().and_then(|time| time.duration_since(cap_std::time::SystemClock::UNIX_EPOCH).ok()).map(|d| d.as_nanos()).unwrap_or(0); + format!("{}-{stamp}", meta.len()) +} + +fn io_fault(error: &std::io::Error) -> Fault { + use std::io::ErrorKind; + match error.kind() { + ErrorKind::NotFound => Fault::Refused("no such file or folder".to_owned()), + ErrorKind::PermissionDenied => Fault::Refused("permission denied".to_owned()), + _ => Fault::Unreachable(error.to_string()), + } +} + +fn list(root: &Path, path: &str) -> Result, Fault> { + let rel = relative(path)?; + let dir = open_root(root)?; + let read = if rel.as_os_str().is_empty() { dir.entries() } else { dir.read_dir(&rel) }; + let read = read.map_err(|error| io_fault(&error))?; + let mut entries = Vec::new(); + for item in read { + let item = item.map_err(|error| io_fault(&error))?; + let meta = item.metadata().map_err(|error| io_fault(&error))?; + let name = item.file_name().to_string_lossy().into_owned(); + let id = child_path(path, &name); + entries.push(Entry { + room: format!("local:{id}"), + name, + kind: if meta.is_dir() { EntryKind::Folder } else { EntryKind::File }, + size: if meta.is_dir() { None } else { Some(meta.len()) }, + modified: None, + mime: None, + etag: if meta.is_dir() { None } else { Some(etag_of(&meta)) }, + writable: true, + shared_by: None, + path: id.clone(), + id, + }); + } + entries.sort_by(|a, b| (a.kind != EntryKind::Folder, &a.name).cmp(&(b.kind != EntryKind::Folder, &b.name))); + Ok(entries) +} + +/// Reads a file's bytes together with the entry for the version just read. +/// +/// The entry is built from a fresh metadata call here, not handed back +/// unchanged from what the caller already believed. A reload after a conflict +/// hands in the stale entry it is trying to get past; echoing that back would +/// carry the old etag into the reloaded document, so the very next save would +/// conflict again on a copy that is actually current. +/// +/// Refuses outright if `entry.id` names a symlink, the same policy `write` +/// uses: this backend never reports the bytes of whatever a link happens to +/// point at, inside `root` or out. +fn read(root: &Path, entry: &Entry) -> Result<(Entry, Vec), Fault> { + let rel = relative(&entry.id)?; + let dir = open_root(root)?; + // Stats without following only the last component; every component + // before it is still resolved, and sandboxed, normally, so a link + // earlier in `rel` is refused by `open_root`'s `Dir` itself when `open` + // below walks it, never silently followed here either way. + match dir.symlink_metadata(&rel) { + Ok(meta) if meta.is_symlink() => return Err(Fault::Refused("that path is a link, not a plain file".to_owned())), + Ok(_) => {} + Err(error) if error.kind() == std::io::ErrorKind::NotFound => {} + Err(error) => return Err(io_fault(&error)), + } + let mut file = dir.open(&rel).map_err(|error| io_fault(&error))?; + let mut bytes = Vec::new(); + file.read_to_end(&mut bytes).map_err(|error| io_fault(&error))?; + let meta = file.metadata().map_err(|error| io_fault(&error))?; + let fresh = Entry { size: Some(meta.len()), etag: Some(etag_of(&meta)), ..entry.clone() }; + Ok((fresh, bytes)) +} + +/// Saves back over `entry`, refusing the write when the file moved on since +/// `entry.etag` was read. A file that no longer exists has nothing to +/// conflict with, the same way a provider treats a deleted document. +/// +/// Never truncates `entry.id`'s current bytes in place. [`write_replacing`] +/// writes a sibling temporary file and renames it over the target instead, +/// so a hard link sharing the target's inode keeps its own, unmodified copy: +/// the rename replaces `entry.id`'s directory entry, and never reaches +/// through to any other name pointing at the same inode. +fn write(root: &Path, entry: &Entry, bytes: &[u8]) -> Result { + let rel = relative(&entry.id)?; + let dir = open_root(root)?; + match dir.symlink_metadata(&rel) { + Ok(meta) if meta.is_symlink() => return Err(Fault::Refused("that path is a link, not a plain file".to_owned())), + Ok(meta) => { + if Some(etag_of(&meta)) != entry.etag { + return Err(Fault::Conflict); + } + } + Err(error) if error.kind() == std::io::ErrorKind::NotFound => {} + Err(error) => return Err(io_fault(&error)), + } + if let Some(parent) = rel.parent() { + dir.create_dir_all(parent).map_err(|error| io_fault(&error))?; + } + write_replacing(&dir, &rel, bytes)?; + let meta = dir.metadata(&rel).map_err(|error| io_fault(&error))?; + Ok(Entry { size: Some(meta.len()), etag: Some(etag_of(&meta)), ..entry.clone() }) +} + +/// The next in a run of sibling temporary names, unique within this process. +/// Not meant to resist a second process picking the same name; the create +/// this writes with is exclusive (`create_new`), so a collision there is +/// just retried under a new counter value rather than silently overwritten. +static TEMP_SEQUENCE: AtomicU64 = AtomicU64::new(0); + +/// Writes `bytes` to a new sibling of `rel` inside `dir`, then renames that +/// sibling over `rel`. See the module docs for why: a direct write would +/// truncate whatever `rel` currently names in place, and if that happens to +/// be a hard link to a file outside `root`, the outside copy would be +/// corrupted along with it. A rename only ever replaces `rel`'s own +/// directory entry. +fn write_replacing(dir: &Dir, rel: &Path, bytes: &[u8]) -> Result<(), Fault> { + let name = rel.file_name().ok_or_else(|| Fault::Refused("that path names no file".to_owned()))?; + let mut temp_name = OsStr::new(".").to_os_string(); + temp_name.push(name); + temp_name.push(format!(".tmp-{}-{}", std::process::id(), TEMP_SEQUENCE.fetch_add(1, Ordering::Relaxed))); + let temp_rel = match rel.parent() { + Some(parent) if !parent.as_os_str().is_empty() => parent.join(&temp_name), + _ => PathBuf::from(&temp_name), + }; + let mut options = OpenOptions::new(); + options.write(true).create_new(true); + let written = (|| -> Result<(), Fault> { + let mut handle = dir.open_with(&temp_rel, &options).map_err(|error| io_fault(&error))?; + handle.write_all(bytes).map_err(|error| io_fault(&error))?; + handle.sync_all().map_err(|error| io_fault(&error)) + })(); + if let Err(fault) = written { + let _ = dir.remove_file(&temp_rel); + return Err(fault); + } + if let Err(error) = dir.rename(&temp_rel, dir, rel) { + let _ = dir.remove_file(&temp_rel); + return Err(io_fault(&error)); + } + Ok(()) +} + +fn create(root: &Path, folder: &str, name: &str, bytes: &[u8]) -> Result { + // `name` is never a path: it is one `Job::Create` field that names the + // new file, so it goes through `confine_name` directly rather than + // through `relative`, which only ever splits and confines a slash path. + let name = confine_name(name)?; + // `root` is the operator-configured boundary, never attacker input, so + // creating it directly with `std::fs` is safe; this is also the one + // place that has always brought a fresh root into existence (see + // `LocalBackend::new`'s docs), and `Dir::open_ambient_dir` below needs it + // to already exist. + fs::create_dir_all(root).map_err(|error| io_fault(&error))?; + let dir = open_root(root)?; + let rel_folder = relative(folder)?; + dir.create_dir_all(&rel_folder).map_err(|error| io_fault(&error))?; + let rel = rel_folder.join(name); + // Exclusive creation, not an `exists` check ahead of a separate write: two + // creates of the same name racing both see "not there yet" otherwise, and + // the second write silently replaces the first with neither ever refused. + // `create_new` asks the filesystem to open and create in one step, so the + // loser gets an error instead of a chance to overwrite the winner. It also + // refuses outright when `name` already exists as a symlink, dangling or + // not: `O_EXCL` never follows one to decide whether it is "in the way". + let mut create_options = OpenOptions::new(); + create_options.write(true).create_new(true); + let mut handle = match dir.open_with(&rel, &create_options) { + Ok(handle) => handle, + Err(error) if error.kind() == std::io::ErrorKind::AlreadyExists => { + return Err(Fault::Refused(format!("{name} already exists"))); + } + Err(error) => return Err(io_fault(&error)), + }; + handle.write_all(bytes).map_err(|error| io_fault(&error))?; + drop(handle); + let meta = dir.metadata(&rel).map_err(|error| io_fault(&error))?; + let id = child_path(folder, name); + Ok(Entry { + room: format!("local:{id}"), + name: name.to_owned(), + kind: EntryKind::File, + size: Some(meta.len()), + modified: None, + mime: None, + etag: Some(etag_of(&meta)), + writable: true, + shared_by: None, + path: id.clone(), + id, + }) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_parent_segment_cannot_walk_out_of_root() { + assert!(relative("../secrets").is_err()); + assert!(relative("Archive/../../../etc/passwd").is_err()); + } + + #[test] + fn repeated_and_trailing_slashes_collapse_like_a_browser_address_bar() { + assert_eq!(relative("//Archive//2026/").unwrap(), Path::new("Archive").join("2026")); + assert_eq!(relative("").unwrap(), PathBuf::new()); + } + + #[test] + fn confine_segment_accepts_only_a_single_ordinary_name() { + for ordinary in ["Minutes.txt", "Archive", "2026", "a name with spaces.docx"] { + assert!(confine_segment(ordinary).is_ok(), "{ordinary} is an ordinary name"); + } + } + + #[test] + fn confine_segment_refuses_empty_dot_and_dot_dot() { + for bad in ["", ".", ".."] { + assert!(confine_segment(bad).is_err(), "{bad:?} is not a single ordinary name"); + } + } + + #[test] + fn confine_segment_refuses_a_slash_hidden_inside_a_create_name() { + assert!(confine_segment("folder/evil").is_err()); + assert!(confine_segment("../outside.txt").is_err()); + assert!(confine_segment("/outside.txt").is_err()); + } + + /// The fix for the non-blocking finding that `list` made a real macOS + /// name (a literal `/`, stored on disk as `:`) visible but unreadable: an + /// existing name with an ordinary `:` byte is not refused by the lenient + /// per-segment check, only by `confine_name` for a chosen one. A literal + /// `\` is not tested the same way here: on a Windows build it really is + /// a second path component (`std::path::Component` already splits on + /// it), so there is no existing-name case for `confine_segment` to stay + /// lenient about cross-platform the way there is for `:`. + #[test] + fn confine_segment_tolerates_a_colon_already_on_disk() { + assert!(confine_segment("weird:name.txt").is_ok()); + assert!(relative("weird:name.txt").is_ok()); + } + + #[test] + fn confine_name_refuses_backslash_and_colon_on_every_platform() { + for bad in ["..\\outside.txt", "C:\\x", "C:evil", "\\\\server\\share\\x"] { + assert!(confine_name(bad).is_err(), "{bad:?} must be refused on every platform, not only on Windows"); + } + } + + #[test] + fn confine_name_refuses_windows_reserved_device_names() { + for bad in ["CON", "con", "con.txt", "NUL", "COM1", "lpt9.log", "CONIN$"] { + assert!(confine_name(bad).is_err(), "{bad:?} names a Windows device, not a file"); + } + for ordinary in ["console.txt", "NULLABLE.md", "COM10"] { + assert!(confine_name(ordinary).is_ok(), "{ordinary} only resembles a reserved name"); + } + } + + #[test] + fn a_folder_announces_no_capability_this_backend_cannot_honour() { + let reported = account("Local disk".to_owned()).capabilities; + for absent in [Capability::SharedWithMe, Capability::Sharing, Capability::Conversation, Capability::Contacts] { + assert!(!reported.contains(&absent), "a folder has no {absent:?}"); + } + } +} diff --git a/crates/cloud-local/tests/backend.rs b/crates/cloud-local/tests/backend.rs new file mode 100644 index 000000000..d2a9fd4e5 --- /dev/null +++ b/crates/cloud-local/tests/backend.rs @@ -0,0 +1,244 @@ +//! Drives [`craft_cloud_local::LocalBackend`] the way an app does: through +//! `craft_ui::cloud`'s own public functions, never by calling the backend +//! directly. That is the seam this crate exists to prove, so the tests stay +//! on the application's side of it. + +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use craft_cloud::{Entry, EntryKind}; +use craft_cloud_local::LocalBackend; +use craft_ui::cloud::{self, Account, CloudApp, CloudFiles, Destination, DocumentKind, Job}; + +const NOTE: DocumentKind = DocumentKind { extensions: &["txt"], mimes: &["text/plain"], noun: "note", default_extension: "txt" }; + +/// A document the harness was told to open: its name and its bytes. +type OpenedDocs = Arc)>>>; + +/// The least a [`CloudApp`] can be. What it was told to open is recorded, so a +/// round trip can be checked by content and not only by the entry metadata +/// `craft_ui` itself remembers. +struct Harness { + cloud: CloudFiles, + share: craft_ui::share::ShareDialog, + presence: craft_ui::presence::PresenceBar, + opened: OpenedDocs, + said: Arc>>, +} + +impl Harness { + fn new() -> Harness { + Harness { + cloud: CloudFiles::new(), + share: craft_ui::share::ShareDialog::new(), + presence: craft_ui::presence::PresenceBar::new(), + opened: Arc::new(Mutex::new(Vec::new())), + said: Arc::new(Mutex::new(Vec::new())), + } + } +} + +impl CloudApp for Harness { + fn cloud(&self) -> &CloudFiles { + &self.cloud + } + + fn cloud_mut(&mut self) -> &mut CloudFiles { + &mut self.cloud + } + + fn kind(&self) -> DocumentKind { + NOTE + } + + fn active(&self) -> Option { + None + } + + fn title(&self, _uid: u64) -> String { + String::new() + } + + fn open_bytes(&mut self, name: &str, bytes: Vec) -> Result, String> { + self.opened.lock().unwrap().push((name.to_owned(), bytes)); + Ok(Some(1)) + } + + fn encode(&mut self, _uid: u64, _into: Destination<'_>) -> Result, String> { + Ok(Vec::new()) + } + + fn close(&mut self, _uid: u64) {} + + fn sharing(&mut self) -> &mut craft_ui::share::ShareDialog { + &mut self.share + } + + fn presence(&mut self) -> &mut craft_ui::presence::PresenceBar { + &mut self.presence + } + + fn paint_icon(&self, _painter: &egui::Painter, _rect: egui::Rect, _kind: EntryKind, _colour: egui::Color32) {} + + fn open_url(&self, _url: &str) {} + + fn say(&mut self, text: String) { + self.said.lock().unwrap().push(text); + } + + fn app_name(&self) -> &str { + "Harness" + } +} + +fn wired(root: std::path::PathBuf) -> (Harness, egui::Context) { + let mut app = Harness::new(); + app.cloud.connect(LocalBackend::new(root)); + (app, egui::Context::default()) +} + +/// Drains whatever the backend's worker threads have sent so far, until +/// `done` says the state the test is waiting for arrived or five seconds pass. +/// Five seconds is far more than a thread doing local file IO ever needs; it +/// only guards against a real bug leaving the test to hang forever. +fn settle(app: &mut Harness, ctx: &egui::Context, mut done: impl FnMut(&Harness) -> bool) { + let start = Instant::now(); + loop { + ctx.begin_pass(Default::default()); + cloud::pump(app, ctx); + ctx.end_pass().textures_delta.clear(); + if done(app) { + return; + } + assert!(start.elapsed() < Duration::from_secs(5), "timed out waiting for the backend's worker thread"); + std::thread::sleep(Duration::from_millis(5)); + } +} + +#[test] +fn account_and_sign_in_report_the_same_fixed_identity_with_no_browser_round_trip() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::start(&mut app); + settle(&mut app, &ctx, |app| app.cloud().account.is_some()); + + assert_eq!( + app.cloud().account, + Some(Account { + display: "Local disk".to_owned(), + capabilities: vec![craft_cloud::Capability::Files, craft_cloud::Capability::Etags], + provider_linked: true + }) + ); + // There was never an account to link, so nothing was ever offered. + assert!(app.cloud().link.is_none()); +} + +#[test] +fn creating_a_document_writes_real_bytes_a_read_gets_back() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::submit(&app, Job::Create { uid: 1, folder: String::new(), name: "Minutes.txt".to_owned(), bytes: b"first draft".to_vec() }); + settle(&mut app, &ctx, |app| app.cloud().origins.contains_key(&1)); + + let entry = app.cloud().origins.get(&1).unwrap().entry.clone(); + assert_eq!(entry.name, "Minutes.txt"); + assert_eq!(entry.id, "/Minutes.txt"); + assert_eq!(fs_read(dir.path(), "Minutes.txt"), b"first draft"); + + cloud::submit(&app, Job::Read { entry, into: None }); + settle(&mut app, &ctx, |app| !app.opened.lock().unwrap().is_empty()); + + let opened = app.opened.lock().unwrap().clone(); + assert_eq!(opened, vec![("Minutes.txt".to_owned(), b"first draft".to_vec())], "the read got back exactly what the create wrote"); +} + +#[test] +fn a_write_under_a_stale_version_is_refused_and_never_overwrites_the_newer_file() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::submit(&app, Job::Create { uid: 1, folder: String::new(), name: "Minutes.txt".to_owned(), bytes: b"v1".to_vec() }); + settle(&mut app, &ctx, |app| app.cloud().origins.contains_key(&1)); + let stale = app.cloud().origins.get(&1).unwrap().entry.clone(); + + // Somebody else saves first, changing the file's etag without going + // through this window at all. + std::fs::write(dir.path().join("Minutes.txt"), b"somebody else's edit").unwrap(); + + cloud::submit(&app, Job::Write { uid: 1, entry: stale, bytes: b"this window's edit".to_vec() }); + settle(&mut app, &ctx, |app| app.cloud().conflict.is_some()); + + assert_eq!(app.cloud().conflict.as_ref().unwrap().uid, 1); + assert_eq!(fs_read(dir.path(), "Minutes.txt"), b"somebody else's edit", "the refused write never touched the file"); +} + +#[test] +fn listing_the_root_reflects_a_file_nobody_went_through_this_backend_to_write() { + let dir = tempfile::tempdir().unwrap(); + std::fs::write(dir.path().join("Agenda.txt"), b"1. roll call").unwrap(); + std::fs::create_dir(dir.path().join("Archive")).unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::browse(&mut app, ""); + settle(&mut app, &ctx, |app| app.cloud().mine.loaded); + + let names: Vec<_> = app.cloud().mine.entries.iter().map(|entry| entry.name.clone()).collect(); + assert_eq!(names, vec!["Archive".to_owned(), "Agenda.txt".to_owned()], "folders first, then files, each alphabetised"); + let folder = app.cloud().mine.entries.iter().find(|entry| entry.name == "Archive").unwrap(); + assert_eq!(folder.kind, EntryKind::Folder); + assert!(folder.size.is_none()); +} + +#[test] +fn nobody_has_shared_anything_with_a_folder() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::load_shared(&mut app); + settle(&mut app, &ctx, |app| app.cloud().shared.loaded); + + assert_eq!(app.cloud().shared.entries, Vec::new()); + assert!(app.cloud().shared.error.is_none(), "an empty share list is not a failure"); +} + +#[test] +fn a_conversation_is_a_fault_this_backend_is_honest_about() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + cloud::submit(&app, Job::Conversation("/Minutes.txt".to_owned())); + settle(&mut app, &ctx, |app| app.cloud().status.is_some()); + + assert_eq!(app.cloud().status, Some("this reference backend has no shared workspace to converse in".to_owned())); +} + +#[test] +fn a_read_of_a_document_that_is_not_there_is_put_to_the_user_not_silently_dropped() { + let dir = tempfile::tempdir().unwrap(); + let (mut app, ctx) = wired(dir.path().to_path_buf()); + + let ghost = Entry { + id: "/ghost.txt".to_owned(), + room: "local:/ghost.txt".to_owned(), + name: "ghost.txt".to_owned(), + path: "/ghost.txt".to_owned(), + kind: EntryKind::File, + size: None, + modified: None, + mime: None, + etag: None, + writable: true, + shared_by: None, + }; + cloud::submit(&app, Job::Read { entry: ghost, into: None }); + settle(&mut app, &ctx, |app| !app.said.lock().unwrap().is_empty()); + + assert!(app.said.lock().unwrap()[0].contains("ghost.txt"), "the message names the document, not just that something failed"); +} + +fn fs_read(root: &std::path::Path, name: &str) -> Vec { + std::fs::read(root.join(name)).unwrap() +} diff --git a/crates/cloud-local/tests/confinement_regressions.rs b/crates/cloud-local/tests/confinement_regressions.rs new file mode 100644 index 000000000..6356e5150 --- /dev/null +++ b/crates/cloud-local/tests/confinement_regressions.rs @@ -0,0 +1,431 @@ +//! Confinement regressions for `crates/cloud-local`. The first round (FredApps' re-review) found +//! that `resolve` only split on `/` and rejected a segment equal to `..`, with no constraint on a +//! Windows backslash, a drive letter or UNC prefix, or a filesystem link, and that `create` +//! joined `name` onto the resolved folder with no validation of `name` at all. The second round +//! (benandez's re-review) reproduced three escapes the first fix still left open: a dangling +//! symlink, a check-then-use race on a swapped link, and a hard link sharing a file's inode. +//! Driven through `craft_ui::cloud`'s public functions the way an application does, with a +//! sentinel file and directory kept as a sibling of the configured root: every test here must +//! leave both untouched and unread. + +use std::path::PathBuf; +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use craft_cloud::{Entry, EntryKind}; +use craft_cloud_local::LocalBackend; +use craft_ui::cloud::{self, CloudApp, CloudFiles, Destination, DocumentKind, Job}; + +const NOTE: DocumentKind = DocumentKind { extensions: &["txt"], mimes: &["text/plain"], noun: "note", default_extension: "txt" }; + +/// A document the harness was told to open: its name and its bytes. +type OpenedDocs = Arc)>>>; + +struct Harness { + cloud: CloudFiles, + share: craft_ui::share::ShareDialog, + presence: craft_ui::presence::PresenceBar, + opened: OpenedDocs, + said: Arc>>, +} + +impl Harness { + fn new() -> Harness { + Harness { + cloud: CloudFiles::new(), + share: craft_ui::share::ShareDialog::new(), + presence: craft_ui::presence::PresenceBar::new(), + opened: Arc::new(Mutex::new(Vec::new())), + said: Arc::new(Mutex::new(Vec::new())), + } + } +} + +impl CloudApp for Harness { + fn cloud(&self) -> &CloudFiles { + &self.cloud + } + fn cloud_mut(&mut self) -> &mut CloudFiles { + &mut self.cloud + } + fn kind(&self) -> DocumentKind { + NOTE + } + fn active(&self) -> Option { + None + } + fn title(&self, _uid: u64) -> String { + String::new() + } + fn open_bytes(&mut self, name: &str, bytes: Vec) -> Result, String> { + self.opened.lock().unwrap().push((name.to_owned(), bytes)); + Ok(Some(1)) + } + fn encode(&mut self, _uid: u64, _into: Destination<'_>) -> Result, String> { + Ok(Vec::new()) + } + fn close(&mut self, _uid: u64) {} + fn sharing(&mut self) -> &mut craft_ui::share::ShareDialog { + &mut self.share + } + fn presence(&mut self) -> &mut craft_ui::presence::PresenceBar { + &mut self.presence + } + fn paint_icon(&self, _painter: &egui::Painter, _rect: egui::Rect, _kind: EntryKind, _colour: egui::Color32) {} + fn open_url(&self, _url: &str) {} + fn say(&mut self, text: String) { + self.said.lock().unwrap().push(text); + } + fn app_name(&self) -> &str { + "Harness" + } +} + +fn wired(root: PathBuf) -> (Harness, egui::Context) { + let mut app = Harness::new(); + app.cloud.connect(LocalBackend::new(root)); + (app, egui::Context::default()) +} + +/// Drains whatever the backend's worker threads have sent so far, until `done` says the state +/// the test is waiting for arrived or five seconds pass. Five seconds is far more than a thread +/// doing local file IO ever needs; it only guards against a real bug leaving the test to hang. +fn settle(app: &mut Harness, ctx: &egui::Context, mut done: impl FnMut(&Harness) -> bool) { + let start = Instant::now(); + loop { + ctx.begin_pass(Default::default()); + cloud::pump(app, ctx); + ctx.end_pass().textures_delta.clear(); + if done(app) { + return; + } + assert!(start.elapsed() < Duration::from_secs(5), "timed out waiting for the backend's worker thread"); + std::thread::sleep(Duration::from_millis(5)); + } +} + +/// Clears both event sinks, then waits for the next job to land in either one. Clearing first +/// matters for a test that submits several jobs in a loop: without it, a stale `said` from two +/// iterations ago would satisfy `settle` immediately, before the new job had actually answered. +fn said(app: &mut Harness, ctx: &egui::Context) -> Vec { + app.opened.lock().unwrap().clear(); + app.said.lock().unwrap().clear(); + settle(app, ctx, |app| !app.said.lock().unwrap().is_empty() || !app.opened.lock().unwrap().is_empty()); + app.said.lock().unwrap().clone() +} + +/// A tempdir holding the cloud root, plus a sentinel file and a sentinel directory that sit +/// beside it rather than inside it. Every test below must leave both exactly as they start. +struct Sentinels { + // Kept only so the tempdir outlives every test that borrows the paths below; nothing reads + // it back once the paths it was built from are in hand. + _arena: tempfile::TempDir, + root: PathBuf, + sentinel_file: PathBuf, + sentinel_dir: PathBuf, +} + +const SENTINEL_FILE_BYTES: &[u8] = b"a sibling file this backend must never read or write"; +const SENTINEL_DIR_FILE_BYTES: &[u8] = b"a sibling directory this backend must never list"; + +fn sentinels() -> Sentinels { + let arena = tempfile::tempdir().unwrap(); + let root = arena.path().join("root"); + std::fs::create_dir(&root).unwrap(); + let sentinel_file = arena.path().join("sentinel.txt"); + std::fs::write(&sentinel_file, SENTINEL_FILE_BYTES).unwrap(); + let sentinel_dir = arena.path().join("sentinel-dir"); + std::fs::create_dir(&sentinel_dir).unwrap(); + std::fs::write(sentinel_dir.join("secret.txt"), SENTINEL_DIR_FILE_BYTES).unwrap(); + Sentinels { _arena: arena, root, sentinel_file, sentinel_dir } +} + +fn assert_sentinels_untouched(sentinels: &Sentinels) { + assert_eq!(std::fs::read(&sentinels.sentinel_file).unwrap(), SENTINEL_FILE_BYTES, "the sentinel file outside the root was changed"); + assert_eq!( + std::fs::read(sentinels.sentinel_dir.join("secret.txt")).unwrap(), + SENTINEL_DIR_FILE_BYTES, + "the sentinel directory's file outside the root was changed" + ); +} + +/// Every one of these is a [`Job::Create`] `name` that must be refused before any byte reaches +/// disk: the review's own examples (a parent segment, an absolute path, and the three +/// Windows-shaped forms), none of which a Unix build's native parser alone would catch, and a +/// name that already is nothing but a Windows separator or drive prefix on top of that. +fn malicious_create_names() -> Vec<&'static str> { + vec!["../sentinel.txt", "/sentinel.txt", "..\\sentinel.txt", "C:\\x", "C:evil", "\\\\server\\share\\x"] +} + +#[test] +fn create_refuses_every_escaping_name_and_the_sentinels_stay_untouched() { + for name in malicious_create_names() { + let sentinels = sentinels(); + let (mut app, ctx) = wired(sentinels.root.clone()); + + cloud::submit(&app, Job::Create { uid: 1, folder: String::new(), name: name.to_owned(), bytes: b"pwned".to_vec() }); + let messages = said(&mut app, &ctx); + + assert!(cloud::origin(&app).is_none(), "{name:?} must not be reported as created"); + assert!(!messages.is_empty(), "{name:?} must be refused, not silently dropped"); + assert_sentinels_untouched(&sentinels); + } +} + +// ------------------------------------------------------------------- link-based escapes +// +// `escape(&sentinels)` places one link named `escape` inside the cloud root, pointing out to +// `sentinels.sentinel_dir`: a symlink on Unix, a directory junction on Windows, which needs no +// elevated privilege, unlike a Windows symlink. The Linux gate runs the symlink half of every +// test below; CI's windows-latest lanes run the junction half. Either way `root/escape/...` +// reaches into the sentinel directory through the link. + +/// Nothing to clean up on Unix: `tempfile`'s own recursive removal of the arena directory +/// removes a plain symlink entry without following it. This exists only so `escape` returns the +/// same shape of RAII handle on every platform, rather than a bare `()` some lint would flag. +#[cfg(unix)] +struct Linked; + +#[cfg(unix)] +fn escape(sentinels: &Sentinels) -> Linked { + std::os::unix::fs::symlink(&sentinels.sentinel_dir, sentinels.root.join("escape")).unwrap(); + Linked +} + +/// A directory junction, removed on drop before the tempdir it sits beside is cleaned up. +#[cfg(windows)] +struct Junction(PathBuf); + +#[cfg(windows)] +impl Drop for Junction { + fn drop(&mut self) { + let _ = std::fs::remove_dir(&self.0); + } +} + +#[cfg(windows)] +fn escape(sentinels: &Sentinels) -> Junction { + use std::os::windows::process::CommandExt as _; + let link = sentinels.root.join("escape"); + let target = &sentinels.sentinel_dir; + assert!(link.is_absolute() && target.is_absolute()); + let output = std::process::Command::new("cmd") + .args(["/C", "mklink", "/J"]) + .arg(&link) + .arg(target) + .creation_flags(0x0800_0000) // CREATE_NO_WINDOW + .output() + .unwrap(); + assert!(output.status.success(), "{}", String::from_utf8_lossy(&output.stderr)); + Junction(link) +} + +/// An [`Entry`] stub naming `id`, for a [`Job::Read`] or [`Job::Write`] this file submits +/// directly rather than through an entry the backend itself handed back. +fn leaked_entry(id: &str, name: &str) -> Entry { + Entry { + id: id.to_owned(), + room: format!("local:{id}"), + name: name.to_owned(), + path: id.to_owned(), + kind: EntryKind::File, + size: None, + modified: None, + mime: None, + etag: None, + writable: true, + shared_by: None, + } +} + +#[cfg(any(unix, windows))] +#[test] +fn listing_a_linked_folder_cannot_see_outside_the_root() { + let sentinels = sentinels(); + let (mut app, ctx) = wired(sentinels.root.clone()); + let _escape = escape(&sentinels); + + cloud::browse(&mut app, "escape"); + settle(&mut app, &ctx, |app| app.cloud().mine.loaded); + + assert!(app.cloud().mine.error.is_some(), "listing through a symlink or junction out of the root must be refused"); + assert!(app.cloud().mine.entries.is_empty()); + assert_sentinels_untouched(&sentinels); +} + +#[cfg(any(unix, windows))] +#[test] +fn reading_through_a_linked_folder_cannot_return_bytes_from_outside_the_root() { + let sentinels = sentinels(); + let (mut app, ctx) = wired(sentinels.root.clone()); + let _escape = escape(&sentinels); + + cloud::submit(&app, Job::Read { entry: leaked_entry("/escape/secret.txt", "secret.txt"), into: None }); + said(&mut app, &ctx); + + assert!(app.opened.lock().unwrap().is_empty(), "a read through a symlink or junction out of the root must not deliver bytes"); + assert_sentinels_untouched(&sentinels); +} + +/// benandez's finding 4: the original version of this test targeted the pre-existing +/// `secret.txt`, with `etag: None`. `write` refused that for an unrelated reason, a version +/// mismatch, before confinement ever ran, so the test passed whether or not confinement worked. +/// Targeting a name that does not exist yet under the link reaches the code that actually +/// matters, and the oracle (the file must never be created) is one confinement failing would +/// actually flip. +#[cfg(any(unix, windows))] +#[test] +fn writing_through_a_linked_folder_cannot_create_a_file_outside_the_root() { + let sentinels = sentinels(); + let (mut app, ctx) = wired(sentinels.root.clone()); + let _escape = escape(&sentinels); + + cloud::submit(&app, Job::Write { uid: 1, entry: leaked_entry("/escape/not-yet-created.txt", "not-yet-created.txt"), bytes: b"pwned".to_vec() }); + said(&mut app, &ctx); + + assert!(!sentinels.sentinel_dir.join("not-yet-created.txt").exists(), "a write through a link must not create a file outside the root"); + assert_sentinels_untouched(&sentinels); +} + +/// benandez's finding 5: nothing previously exercised a link in the `folder` a `Create` targets. +#[cfg(any(unix, windows))] +#[test] +fn creating_through_a_linked_folder_cannot_create_a_file_outside_the_root() { + let sentinels = sentinels(); + let (mut app, ctx) = wired(sentinels.root.clone()); + let _escape = escape(&sentinels); + + cloud::submit(&app, Job::Create { uid: 1, folder: "escape".to_owned(), name: "new.txt".to_owned(), bytes: b"pwned".to_vec() }); + let messages = said(&mut app, &ctx); + + assert!(cloud::origin(&app).is_none(), "a create into a linked folder must not be reported as created"); + assert!(!messages.is_empty(), "a create into a linked folder must be refused, not silently dropped"); + assert!(!sentinels.sentinel_dir.join("new.txt").exists(), "a create through a link must not create a file outside the root"); + assert_sentinels_untouched(&sentinels); +} + +// ------------------------------------------------------------------- Unix-only reproductions +// +// Directory junctions cannot be dangling (`mklink /J` requires the target to exist) and the +// race and hard-link reproductions below are exactly benandez's own repros, run on Linux only, +// as stated in that review. The structural fix (resolving through a `cap_std::fs::Dir`, and +// writing through a temporary file and rename) is the same code on every platform; these three +// just do not have a Windows-shaped equivalent worth a separate repro. + +/// benandez's finding 1, reproduced exactly: `root/doc.txt` is a symlink to a file that does not +/// exist yet, outside the root. The old code's `confine_to_root` canonicalised the dangling link +/// to `NotFound`, walked up to `root`, accepted it, found no file to conflict with, and `write` +/// created the target for real, outside the root. +#[cfg(unix)] +#[test] +fn writing_through_a_dangling_symlink_cannot_create_a_file_outside_the_root() { + let sentinels = sentinels(); + let outside_target = sentinels._arena.path().join("outside-planted.txt"); + std::os::unix::fs::symlink(&outside_target, sentinels.root.join("doc.txt")).unwrap(); + let (mut app, ctx) = wired(sentinels.root.clone()); + + cloud::submit(&app, Job::Write { uid: 1, entry: leaked_entry("/doc.txt", "doc.txt"), bytes: b"pwned".to_vec() }); + said(&mut app, &ctx); + + assert!(!outside_target.exists(), "a write through a dangling symlink must not create its target outside the root"); + assert_sentinels_untouched(&sentinels); +} + +/// benandez's finding 3, reproduced exactly: `root/hl` is a hard link sharing an inode with a +/// file outside the root. Reading it through the backend is legitimate (it is, from inside the +/// sandbox, an ordinary file), which is also how this test gets a real, matching etag to write +/// with, the same way a real caller would after opening the document. The old code's `write` +/// truncated the shared inode in place; `write_replacing` must instead replace `hl`'s own +/// directory entry, leaving the sentinel file's inode, and its other name, untouched. +#[cfg(unix)] +#[test] +fn writing_through_a_hard_link_replaces_the_entry_without_touching_the_shared_file() { + let sentinels = sentinels(); + std::fs::hard_link(&sentinels.sentinel_file, sentinels.root.join("hl")).unwrap(); + let (mut app, ctx) = wired(sentinels.root.clone()); + + cloud::submit(&app, Job::Read { entry: leaked_entry("/hl", "hl"), into: None }); + settle(&mut app, &ctx, |app| !app.opened.lock().unwrap().is_empty()); + let real_entry = app.cloud().origins.get(&1).expect("the read registered an origin for uid 1").entry.clone(); + + // A successful write answers through `cloud.status`, not through `said` or `opened`, so it + // needs its own wait condition rather than the `said` helper used everywhere else in this + // file for a refusal. The read above already set `status` once (`Opened hl from the + // cloud.`), so that has to be cleared first or this would observe the read's own status and + // never actually wait for the write to finish. + app.cloud_mut().status = None; + cloud::submit(&app, Job::Write { uid: 1, entry: real_entry, bytes: b"replaced via rename, not truncated in place".to_vec() }); + settle(&mut app, &ctx, |app| app.cloud().status.is_some() || app.cloud().conflict.is_some() || !app.said.lock().unwrap().is_empty()); + assert!(app.cloud().conflict.is_none(), "the write through the hard-linked name should succeed, not conflict"); + assert!( + app.said.lock().unwrap().is_empty(), + "the write through the hard-linked name should succeed, not be refused: {:?}", + app.said.lock().unwrap() + ); + + assert_eq!( + std::fs::read(sentinels.root.join("hl")).unwrap(), + b"replaced via rename, not truncated in place", + "the write through the hard-linked name should still succeed" + ); + assert_sentinels_untouched(&sentinels); +} + +/// benandez's finding 2, reproduced at a smaller scale: a background thread swaps `root/d` +/// between a symlink into an inside folder and a symlink to the sentinel directory, as fast as +/// it can, with no coordination with the reads below. The old code's `confine_to_root` checked +/// one path string and then `fs::read` resolved that path again, a second, later lookup a swap +/// could land in between; out of 3000 such reads benandez's own run returned the outside file's +/// bytes 347 times. `cap_std::fs::Dir::open` resolves and opens `d` as one operation with no +/// such second lookup, so this must come back empty every time, not merely most of the time. +#[cfg(unix)] +#[test] +fn reading_through_a_link_being_swapped_never_observes_the_outside_target() { + use std::sync::atomic::{AtomicBool, Ordering}; + + let sentinels = sentinels(); + let inside = sentinels.root.join("inside"); + std::fs::create_dir(&inside).unwrap(); + std::fs::write(inside.join("secret.txt"), b"inside bytes, always safe to read").unwrap(); + let link = sentinels.root.join("d"); + std::os::unix::fs::symlink(&inside, &link).unwrap(); + + let stop = Arc::new(AtomicBool::new(false)); + let swapper = { + let stop = stop.clone(); + let link = link.clone(); + let outside = sentinels.sentinel_dir.clone(); + std::thread::spawn(move || { + let temp = link.with_extension("swap"); + let mut toward_outside = false; + while !stop.load(Ordering::Relaxed) { + let target = if toward_outside { &outside } else { &inside }; + // A stale `temp` from a rename that did not happen (should not occur, but a + // leftover `temp` would otherwise wedge every later iteration's `symlink` call, + // silently stopping the swap rather than failing the test loudly) is cleared + // first so this loop cannot get stuck. + let _ = std::fs::remove_file(&temp); + if std::os::unix::fs::symlink(target, &temp).is_ok() { + let _ = std::fs::rename(&temp, &link); + } + toward_outside = !toward_outside; + } + }) + }; + + let (mut app, ctx) = wired(sentinels.root.clone()); + let mut leaked = false; + for _ in 0..200 { + cloud::submit(&app, Job::Read { entry: leaked_entry("/d/secret.txt", "secret.txt"), into: None }); + said(&mut app, &ctx); + if let Some((_, bytes)) = app.opened.lock().unwrap().first() { + leaked |= bytes.as_slice() == SENTINEL_DIR_FILE_BYTES; + } + } + + stop.store(true, Ordering::Relaxed); + swapper.join().unwrap(); + + assert!(!leaked, "a read observed the outside target's bytes while the link was being swapped underneath it"); + assert_sentinels_untouched(&sentinels); +} diff --git a/crates/cloud-local/tests/save_path_regressions.rs b/crates/cloud-local/tests/save_path_regressions.rs new file mode 100644 index 000000000..76cec678a --- /dev/null +++ b/crates/cloud-local/tests/save_path_regressions.rs @@ -0,0 +1,160 @@ +//! Two save-path defects that need a real backend to show: a reload after a conflict carrying a +//! stale etag into the next save, and two creates of the same name racing past an exists check. +//! Driven through craft_ui::cloud's public functions the way an application does. + +use std::sync::{Arc, Mutex}; +use std::time::{Duration, Instant}; + +use craft_cloud::{Entry, EntryKind}; +use craft_cloud_local::LocalBackend; +use craft_ui::cloud::{self, CloudApp, CloudFiles, Destination, DocumentKind}; + +const NOTE: DocumentKind = DocumentKind { extensions: &["txt"], mimes: &["text/plain"], noun: "note", default_extension: "txt" }; + +struct Window { + cloud: CloudFiles, + share: craft_ui::share::ShareDialog, + presence: craft_ui::presence::PresenceBar, + body: Vec, + said: Arc>>, +} + +impl Window { + fn new(root: std::path::PathBuf, body: &[u8]) -> Window { + let mut w = Window { + cloud: CloudFiles::new(), + share: craft_ui::share::ShareDialog::new(), + presence: craft_ui::presence::PresenceBar::new(), + body: body.to_vec(), + said: Arc::default(), + }; + w.cloud.connect(LocalBackend::new(root)); + w + } +} + +impl CloudApp for Window { + fn cloud(&self) -> &CloudFiles { + &self.cloud + } + fn cloud_mut(&mut self) -> &mut CloudFiles { + &mut self.cloud + } + fn kind(&self) -> DocumentKind { + NOTE + } + fn active(&self) -> Option { + Some(1) + } + fn title(&self, _uid: u64) -> String { + String::new() + } + fn open_bytes(&mut self, _name: &str, bytes: Vec) -> Result, String> { + self.body = bytes; + Ok(Some(1)) + } + fn encode(&mut self, _uid: u64, _into: Destination<'_>) -> Result, String> { + Ok(self.body.clone()) + } + fn close(&mut self, _uid: u64) {} + fn sharing(&mut self) -> &mut craft_ui::share::ShareDialog { + &mut self.share + } + fn presence(&mut self) -> &mut craft_ui::presence::PresenceBar { + &mut self.presence + } + fn paint_icon(&self, _p: &egui::Painter, _r: egui::Rect, _k: EntryKind, _c: egui::Color32) {} + fn open_url(&self, _url: &str) {} + fn say(&mut self, text: String) { + self.said.lock().unwrap().push(text); + } + fn app_name(&self) -> &str { + "Review" + } +} + +fn settle(app: &mut Window, ctx: &egui::Context, mut done: impl FnMut(&Window) -> bool) { + let start = Instant::now(); + loop { + ctx.begin_pass(Default::default()); + cloud::pump(app, ctx); + ctx.end_pass().textures_delta.clear(); + if done(app) { + return; + } + assert!(start.elapsed() < Duration::from_secs(5), "timed out"); + std::thread::sleep(Duration::from_millis(2)); + } +} + +fn listed(app: &mut Window, ctx: &egui::Context, name: &str) -> Entry { + cloud::browse(app, ""); + settle(app, ctx, |a| a.cloud.mine.loaded); + app.cloud.mine.entries.iter().find(|e| e.name == name).cloned().expect("listed") +} + +/// Open v1, another writer stores v2, Save conflicts, the user picks "Reload from the cloud" +/// (`reload_active`, what the modal calls). The window now shows v2's bytes, so the next Save +/// must go through rather than conflict again on the etag the reloaded copy was read at. +#[test] +fn reload_after_a_conflict_carries_the_freshly_read_etag_so_the_next_save_succeeds() { + let root = tempfile::tempdir().unwrap(); + std::fs::write(root.path().join("note.txt"), b"v1").unwrap(); + let ctx = egui::Context::default(); + let mut app = Window::new(root.path().to_owned(), b""); + let v1 = listed(&mut app, &ctx, "note.txt"); + cloud::open_entry(&mut app, v1.clone(), None); + settle(&mut app, &ctx, |a| a.cloud.busy.is_none() && a.body == b"v1"); + + std::thread::sleep(Duration::from_millis(20)); + std::fs::write(root.path().join("note.txt"), b"v2 by someone else").unwrap(); + + app.body = b"my edit".to_vec(); + cloud::save(&mut app).unwrap(); + settle(&mut app, &ctx, |a| a.cloud.busy.is_none()); + assert!(app.cloud.conflict.is_some(), "the first save is refused (correct)"); + + cloud::reload_active(&mut app).unwrap(); + settle(&mut app, &ctx, |a| a.cloud.busy.is_none()); + assert_eq!(app.body, b"v2 by someone else", "reload shows the stored bytes"); + let origin_etag = cloud::report(&app)["origin"]["etag"].clone(); + + cloud::save(&mut app).unwrap(); + settle(&mut app, &ctx, |a| a.cloud.busy.is_none()); + let on_disk = std::fs::read(root.path().join("note.txt")).unwrap(); + assert!( + app.cloud.conflict.is_none(), + "after reloading v2 the save conflicted again: origin etag after reload = {origin_etag} \ + (listing etag was {:?}); file on disk = {:?}", + v1.etag, + String::from_utf8_lossy(&on_disk) + ); +} + +/// Two windows Save As the same new name at once. At most one create may succeed; the other +/// must be refused ("already exists") rather than both reporting success while one silently +/// replaces the other on disk. +#[test] +fn concurrent_create_of_one_name_refuses_the_loser() { + let rounds = 300; + let (mut both_ok, mut example) = (0, String::new()); + for round in 0..rounds { + let root = tempfile::tempdir().unwrap(); + let ctx = egui::Context::default(); + let mut a = Window::new(root.path().to_owned(), format!("window A round {round}").as_bytes()); + let mut b = Window::new(root.path().to_owned(), format!("window B round {round}").as_bytes()); + cloud::save_as(&mut a, "", "Report.txt").unwrap(); + cloud::save_as(&mut b, "", "Report.txt").unwrap(); + settle(&mut a, &ctx, |w| w.cloud.busy.is_none()); + settle(&mut b, &ctx, |w| w.cloud.busy.is_none()); + let (a_ok, b_ok) = (cloud::origin(&a).is_some(), cloud::origin(&b).is_some()); + if a_ok && b_ok { + both_ok += 1; + if example.is_empty() { + let disk = std::fs::read_to_string(root.path().join("Report.txt")).unwrap(); + example = format!("round {round}: A status {:?}, B status {:?}, file holds {disk:?}", a.cloud.status, b.cloud.status); + } + } + } + assert_eq!(both_ok, 0, "{both_ok}/{rounds} rounds: both windows were told the new file was created; e.g. {example}"); +} diff --git a/crates/cloud-ui/Cargo.toml b/crates/cloud-ui/Cargo.toml new file mode 100644 index 000000000..45cc4306f --- /dev/null +++ b/crates/cloud-ui/Cargo.toml @@ -0,0 +1,34 @@ +[package] +name = "craft-cloud-ui" +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true +rust-version.workspace = true +description = "Share dialog, cloud Open and Save pages, account menu and presence bar for Craft apps, on egui" + +[lints] +workspace = true + +[dependencies] +egui = { workspace = true } +# The vendor-neutral vocabulary the share dialog speaks. No IO and no +# vendor, so this stays buildable for the web. +craft-cloud = { workspace = true, optional = true } +# The control channel's report of the cloud state. One serialiser here +# rather than one per application. No IO and no vendor. +serde_json = { workspace = true, optional = true } + +[features] +default = [] +# The share dialog and the backend contract it states its work through. +share = ["dep:craft-cloud"] +# Open and Save against cloud storage. Needs the share dialog, which a +# document's overflow menu and the Share split button both open. +cloud = ["share", "dep:serde_json"] + +[dev-dependencies] +image = { version = "0.25", default-features = false, features = ["png"] } + +[target.'cfg(not(target_arch = "wasm32"))'.dev-dependencies] +egui_kittest = { version = "0.37", features = ["wgpu"] } diff --git a/crates/cloud-ui/README.md b/crates/cloud-ui/README.md new file mode 100644 index 000000000..9bde8feb5 --- /dev/null +++ b/crates/cloud-ui/README.md @@ -0,0 +1,67 @@ +# craft-cloud-ui + +The share dialog, the cloud Open and Save pages, the account menu and the presence bar that every +Craft app shares. This is storytold main's cloud and share UI as main wrote it in craft-ui: raw egui, +outside the craft UI library's component contract, to be ported onto the framework's components. The +`craft-ui` facade re-exports `account`, `cloud`, `share` and `presence` from here behind the same +`share` and `cloud` features. + +## Sharing + +`share::ShareDialog` is a whole dialog. It holds a recipient picker with autocomplete and +removable chips. It offers a view-or-edit choice, a note and a notify-by-email box. Under those it +lists who already has access, with a withdrawal beside each entry. Every Craft app gets the same +dialog. An application's own part comes to three lines. + +```rust +// Once, at startup. The host supplies the half that reaches the service. +app.share.connect(my_backend); + +// Every frame, open or shut. This is also where answers are collected. +app.share.show(ctx); + +// From the app's Share control, drawn only while `available()` is true. +if app.share.available() && share_button.clicked() { + app.share.open(entry.id.clone(), entry.name.clone()); +} +``` + +The dialog opens no socket, names no provider and holds no credential. It states each piece of +work as a `share::Request` and hands it to a `share::ShareBackend`. That backend answers through a +`share::Replier` whenever it is ready. Nothing in this crate implements that trait. A host writes +the half that opens a socket, and this crate never learns what it reaches. The interface half +therefore builds for the web, and every flow is testable with no server running. + +Autocomplete waits `share::DEBOUNCE` after the last keystroke before it asks anything. An answer +to a query the user has already typed past is dropped before it reaches the list. A list that +flickers back to stale matches is worse than one that arrives late. + +Partial success is rendered as partial success. A share aimed at five people with one wrong +address reaches four. The dialog names the fifth with the reason the service gave. It keeps that +one recipient in the picker. A correction then takes one edit. `outcome()` hands back both halves. + +Capability is reported and never assumed. `available()` stays false until the service says the +provider supports sharing and an account is linked. `open` does nothing while it is false. An +application draws no Share control in that state. A hidden feature beats a button that fails on +use. Contacts and mail are reported separately. A server with no address book accepts typed +addresses only. A server that cannot send mail disables the notify box and says why. +`ShareLabels` holds every string the dialog shows. The defaults are English. A localized +application replaces them without touching this crate. + +A contact's `avatar` is a URL. The dialog asks for the bytes through the same backend, as the row +that needs the picture is painted and only while that row is on screen. A search answering with +ten people costs no pictures until somebody looks at them. Each URL is asked about once. A refusal +is remembered, with initials painted in its place. The host decides whether a picture may be +fetched at all. A backend that refuses `share::Request::Avatar` gets initials painted instead, and +a host that would rather not have an application reach a provider's avatar URL directly can say +so by refusing it. A host that relays pictures answers it. Nothing else changes. + +### The account + +`account::AccountMenu` is the badge every suite puts in the top right. It shows who is signed in, +where they are signed in, and whether storage is linked. It holds no credential. It asks the +service who the caller is, through the application. It reports what the user asked for through +`take_action`. The application owns what signing in means. + +Without linked storage, Open and Save have nowhere to go. The menu says so at rest. A failure at +the moment of saving arrives too late to be useful. diff --git a/crates/cloud-ui/src/account.rs b/crates/cloud-ui/src/account.rs new file mode 100644 index 000000000..9c8921064 --- /dev/null +++ b/crates/cloud-ui/src/account.rs @@ -0,0 +1,449 @@ +//! Who is signed in, which account is in use, and how to stop being signed in. +//! +//! Every office suite puts this in the same place, for the same reason. A +//! document is about to be saved somewhere and shared with somebody. The +//! account decides both the destination and the identity. An application that +//! never shows it leaves the user guessing which of their identities is in +//! play. +//! +//! A person commonly holds more than one. A work account and a personal one +//! are two different places to save, with two different sets of colleagues to +//! share with, and confusing them is the expensive mistake this control exists +//! to prevent. So the control holds a list and marks which one is in use. +//! +//! This holds no credential. It asks the service who the caller is and shows +//! the answer. A sign-out makes the service forget the session. + +use std::sync::mpsc::{Receiver, Sender, channel}; + +use egui::{Align, Context, Layout, RichText, Ui}; + +/// One account the user is signed in to. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct Account { + /// How the service names this account. Never shown. + pub id: String, + /// What to show. A display name, never an identity. + pub display: String, + pub email: Option, + /// Where they are signed in, such as the service's host. Shown because + /// somebody with accounts on two deployments needs to tell them apart. + pub service: String, + /// Whether storage is linked. Without it Open and Save have nowhere to go, + /// and saying so here is kinder than a failure at the moment of saving. + pub linked: bool, +} + +impl Account { + pub fn new(id: impl Into, display: impl Into) -> Account { + Account { id: id.into(), display: display.into(), ..Account::default() } + } + + /// The letter on the badge. The first character of the display name, which + /// is what every suite uses and what people recognise at that size. + pub fn initial(&self) -> String { + self.display.chars().next().map(|c| c.to_uppercase().to_string()).unwrap_or_else(|| "?".to_owned()) + } +} + +/// What the menu asks the application to do. +/// +/// Each one names the account it is about. A control that said only "sign out" +/// would be ambiguous the moment somebody held two. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum AccountAction { + /// Begin a sign-in with nobody signed in yet. + SignIn, + /// Add another account alongside the ones already here. + AddAccount, + /// Work as this account from now on. + Use(String), + /// End this account's session, at the service and here. + SignOut(String), + /// Connect storage for an account that has none. + Link(String), + /// Open the service's own page for this account. + Manage(String), +} + +/// Strings, so an application can translate them. +#[derive(Clone, Debug)] +pub struct AccountLabels { + pub signed_out: String, + pub sign_in: String, + pub sign_out: String, + pub add_account: String, + pub other_accounts: String, + pub link: String, + pub linked: String, + pub not_linked: String, + pub manage: String, + pub working: String, + /// The badge's accessible name. `{name}` is replaced. + /// + /// A button announcing only a person's name says nothing about what + /// pressing it does, and collides with every other place that name is + /// written. + pub badge: String, + /// Shown when accounts are signed in and none is in use. + pub choose: String, + /// Why that happened, since a person who did not sign out needs telling. + pub choose_why: String, +} + +impl Default for AccountLabels { + fn default() -> AccountLabels { + AccountLabels { + signed_out: "Not signed in".into(), + sign_in: "Sign in".into(), + sign_out: "Sign out".into(), + add_account: "Add an account".into(), + other_accounts: "Other accounts".into(), + link: "Connect storage".into(), + linked: "Storage connected".into(), + not_linked: "No storage connected".into(), + manage: "Account settings".into(), + working: "Working\u{2026}".into(), + badge: "Account, {name}".into(), + choose: "Choose an account".into(), + choose_why: "The account you were using is no longer signed in.".into(), + } + } +} + +/// The account badge and its menu. +pub struct AccountMenu { + accounts: Vec, + /// Which account the application is working as. Held by id rather than by + /// index, since the list is replaced wholesale whenever the service answers. + active: Option, + labels: AccountLabels, + /// Set while a sign-in or sign-out is in flight, so the control says so + /// rather than looking unresponsive. + busy: bool, + /// Whether the host can hold more than one account at once. + /// + /// Off until a host says otherwise. An application that keeps one + /// session would otherwise draw an Add an account that signs the user + /// in again as the account they are already using, which reads as a + /// button that does nothing. + more_allowed: bool, + actions: (Sender, Receiver), +} + +impl Default for AccountMenu { + fn default() -> AccountMenu { + AccountMenu::new() + } +} + +impl AccountMenu { + pub fn new() -> AccountMenu { + AccountMenu { accounts: Vec::new(), active: None, labels: AccountLabels::default(), busy: false, more_allowed: false, actions: channel() } + } + + pub fn with_labels(mut self, labels: AccountLabels) -> AccountMenu { + self.labels = labels; + self + } + + /// Say that this host can hold more than one account at once. + /// + /// Until a host says so, the menu offers no way to add one. Signing in + /// again as the account already in use is not an action worth drawing. + pub fn allowing_more(mut self) -> AccountMenu { + self.more_allowed = true; + self + } + + /// Replace the whole set of accounts. + /// + /// Wholesale rather than one at a time. A session that missed a sign-out + /// elsewhere would otherwise keep offering an account that is gone. + /// + /// The account in use is kept when it is still in the list. + /// + /// When it has gone, nothing takes its place. A work session that expires + /// would otherwise hand the next save, share and open to a personal + /// account without saying so, and sending a document to the wrong tenant + /// is not a mistake a person can take back. The control asks instead. + /// + /// The first account is chosen only when none was in use at all, which is + /// the first sign-in. + pub fn set(&mut self, accounts: Vec) { + let chose_before = self.active.is_some(); + let kept = self.active.take().filter(|id| accounts.iter().any(|a| a.id == *id)); + self.active = match kept { + Some(id) => Some(id), + None if chose_before => None, + None => accounts.first().map(|a| a.id.clone()), + }; + self.accounts = accounts; + self.busy = false; + } + + /// Work as this account. Ignored for an account that is not here. + pub fn set_active(&mut self, id: &str) { + if self.accounts.iter().any(|a| a.id == id) { + self.active = Some(id.to_owned()); + } + } + + pub fn active(&self) -> Option<&Account> { + let id = self.active.as_deref()?; + self.accounts.iter().find(|a| a.id == id) + } + + pub fn accounts(&self) -> &[Account] { + &self.accounts + } + + pub fn is_signed_in(&self) -> bool { + !self.accounts.is_empty() + } + + /// Mark something as in flight. Cleared by the next [`AccountMenu::set`]. + pub fn working(&mut self) { + self.busy = true; + } + + /// What the user asked for since the last call, if anything. + /// + /// Drained rather than handed a callback, so the application acts on its + /// own thread and this stays free of any notion of what signing in means. + pub fn take_action(&mut self) -> Option { + self.actions.1.try_recv().ok() + } + + /// Draw the badge. Put it where the window's own controls are. + pub fn show(&mut self, ui: &mut Ui) { + let tx = self.actions.0.clone(); + let labels = self.labels.clone(); + let busy = self.busy; + + let Some(account) = self.active().cloned() else { + // Nobody signed in, or signed in with the account that was in use + // now gone. The two read differently. One offers a sign-in. The + // other has accounts to offer and must say so, since saving has + // nowhere to go until somebody picks one. + if self.accounts.is_empty() { + let label = if busy { labels.working.as_str() } else { labels.sign_in.as_str() }; + if ui.add_enabled(!busy, egui::Button::new(label).small()).clicked() { + let _ = tx.send(AccountAction::SignIn); + } + return; + } + let waiting = self.accounts.clone(); + let hit = ui.add_enabled(!busy, egui::Button::new(labels.choose.as_str()).small()); + egui::Popup::menu(&hit).show(|ui| { + ui.set_min_width(240.0); + ui.label(RichText::new(labels.choose_why.as_str()).small().color(ui.visuals().warn_fg_color)); + ui.separator(); + for one in &waiting { + let label = format!("{}\n{}", one.display, one.service); + let row = ui.add(egui::Button::new(label).wrap_mode(egui::TextWrapMode::Extend)); + let name = one.display.clone(); + row.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, name.as_str())); + if row.clicked() { + let _ = tx.send(AccountAction::Use(one.id.clone())); + ui.close(); + } + } + ui.add_space(4.0); + if ui.button(labels.sign_in.as_str()).clicked() { + let _ = tx.send(AccountAction::SignIn); + ui.close(); + } + }); + return; + }; + + let others: Vec = self.accounts.iter().filter(|a| a.id != account.id).cloned().collect(); + let more_allowed = self.more_allowed; + let badge = egui::Button::new(RichText::new(account.initial()).strong()).min_size(egui::vec2(26.0, 26.0)).corner_radius(13.0); + let hit = ui.add(badge); + let spoken = labels.badge.replace("{name}", &account.display); + hit.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, spoken.as_str())); + let hit = hit.on_hover_text(account.display.as_str()); + + egui::Popup::menu(&hit).show(|ui| { + ui.set_min_width(260.0); + // The deployment first, because somebody with an account on two of + // them needs to know which one this is before reading anything + // else. + ui.horizontal(|ui| { + ui.label(RichText::new(account.service.as_str()).small().color(ui.visuals().weak_text_color())); + ui.with_layout(Layout::right_to_left(Align::Center), |ui| { + if ui.small_button(labels.sign_out.as_str()).clicked() { + let _ = tx.send(AccountAction::SignOut(account.id.clone())); + ui.close(); + } + }); + }); + ui.separator(); + + ui.horizontal(|ui| { + ui.label(RichText::new(account.initial()).size(26.0).strong()); + ui.vertical(|ui| { + ui.label(RichText::new(account.display.as_str()).strong().size(15.0)); + if let Some(email) = &account.email { + ui.label(RichText::new(email.as_str()).small().color(ui.visuals().weak_text_color())); + } + }); + }); + + ui.add_space(6.0); + + // Storage, which is the thing that actually stops working when it + // is missing. Said here rather than discovered at the moment of + // saving. + if account.linked { + ui.label(RichText::new(labels.linked.as_str()).small().color(ui.visuals().weak_text_color())); + } else { + ui.label(RichText::new(labels.not_linked.as_str()).small().color(ui.visuals().warn_fg_color)); + if ui.button(labels.link.as_str()).clicked() { + let _ = tx.send(AccountAction::Link(account.id.clone())); + ui.close(); + } + } + + if !others.is_empty() { + ui.add_space(6.0); + ui.separator(); + ui.label(RichText::new(labels.other_accounts.as_str()).small().color(ui.visuals().weak_text_color())); + for other in &others { + // Both lines in one control. A name above a subtitle, where + // only the name answers a press, makes half the row look + // broken to anybody who aims at the wrong half. The + // deployment is on the second line because two accounts + // both reading "Will Dunn" tell nobody which is the work + // one. + let label = format!("{}\n{}", other.display, other.service); + let row = ui.add(egui::Button::new(label).wrap_mode(egui::TextWrapMode::Extend)); + let name = other.display.clone(); + row.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, name.as_str())); + if row.clicked() { + let _ = tx.send(AccountAction::Use(other.id.clone())); + ui.close(); + } + } + } + + if more_allowed { + ui.add_space(6.0); + if ui.button(labels.add_account.as_str()).clicked() { + let _ = tx.send(AccountAction::AddAccount); + ui.close(); + } + } + + ui.add_space(4.0); + if ui.link(labels.manage.as_str()).clicked() { + let _ = tx.send(AccountAction::Manage(account.id.clone())); + ui.close(); + } + }); + } + + /// Draw the badge in a context that has no `Ui` to hand. + pub fn show_in_ctx(&mut self, ctx: &Context) { + egui::Area::new(egui::Id::unique("craft-ui/account")).anchor(egui::Align2::RIGHT_TOP, egui::vec2(-8.0, 8.0)).show(ctx, |ui| { + self.show(ui); + }); + } +} + +#[cfg(test)] +mod tests { + use super::*; + + fn account(id: &str, display: &str) -> Account { + Account { id: id.into(), display: display.into(), service: "one.example.com".into(), ..Account::default() } + } + + #[test] + fn nobody_signed_in_has_no_active_account() { + let menu = AccountMenu::new(); + assert!(!menu.is_signed_in()); + assert_eq!(menu.active(), None); + } + + #[test] + fn the_first_account_becomes_the_active_one() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work"), account("b", "Personal")]); + assert_eq!(menu.active().map(|a| a.id.as_str()), Some("a")); + } + + #[test] + fn replacing_the_list_keeps_the_account_in_use() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work"), account("b", "Personal")]); + menu.set_active("b"); + menu.set(vec![account("a", "Work"), account("b", "Personal"), account("c", "Lab")]); + assert_eq!(menu.active().map(|a| a.id.as_str()), Some("b"), "an unrelated refresh must not switch accounts"); + } + + #[test] + fn an_account_that_signed_out_elsewhere_leaves_nobody_in_use() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work"), account("b", "Personal")]); + menu.set_active("b"); + menu.set(vec![account("a", "Work")]); + // Not account a. A work session that expires must not hand the next + // save to a personal account without anybody saying so. + assert_eq!(menu.active(), None, "the one that is gone cannot be replaced in silence"); + assert!(menu.is_signed_in(), "there is still an account here to choose"); + } + + #[test] + fn choosing_again_after_one_disappeared_works() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work"), account("b", "Personal")]); + menu.set_active("b"); + menu.set(vec![account("a", "Work")]); + menu.set_active("a"); + assert_eq!(menu.active().map(|a| a.id.as_str()), Some("a")); + } + + #[test] + fn a_refresh_that_keeps_the_account_keeps_it_in_use() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work"), account("b", "Personal")]); + menu.set_active("b"); + menu.set(vec![account("b", "Personal"), account("c", "Lab")]); + assert_eq!(menu.active().map(|a| a.id.as_str()), Some("b")); + } + + #[test] + fn the_last_account_leaving_signs_everybody_out() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work")]); + menu.set(Vec::new()); + assert!(!menu.is_signed_in()); + assert_eq!(menu.active(), None); + } + + #[test] + fn switching_to_an_account_that_is_not_here_changes_nothing() { + let mut menu = AccountMenu::new(); + menu.set(vec![account("a", "Work")]); + menu.set_active("nobody"); + assert_eq!(menu.active().map(|a| a.id.as_str()), Some("a")); + } + + #[test] + fn the_badge_says_what_it_is_as_well_as_who() { + let labels = AccountLabels::default(); + let spoken = labels.badge.replace("{name}", "Ada Lovelace"); + assert_eq!(spoken, "Account, Ada Lovelace"); + assert_ne!(spoken, "Ada Lovelace", "a bare name collides with every other place it is written"); + } + + #[test] + fn an_initial_survives_a_name_that_starts_oddly() { + assert_eq!(account("1", "ann").initial(), "A"); + assert_eq!(account("1", "").initial(), "?"); + assert_eq!(account("1", "\u{e9}lodie").initial(), "\u{c9}"); + } +} diff --git a/crates/cloud-ui/src/buttons.rs b/crates/cloud-ui/src/buttons.rs new file mode 100644 index 000000000..3a10bb5d2 --- /dev/null +++ b/crates/cloud-ui/src/buttons.rs @@ -0,0 +1,18 @@ +//! The painted chevron the overflow menu and the split button draw. + +use egui::Ui; + +/// A downward triangle at the right-hand end of a control. +/// +/// Painted rather than typed. The chevron character is absent from the default +/// font set, where it renders as a missing-glyph box. A caller leaves room for +/// it by padding the label, then paints it over the response. +pub fn chevron(ui: &Ui, rect: egui::Rect, colour: egui::Color32) { + let middle = rect.right_center() - egui::vec2(9.0, 0.0); + let half = 3.5; + ui.painter().add(egui::Shape::convex_polygon( + vec![middle + egui::vec2(-half, -half * 0.6), middle + egui::vec2(half, -half * 0.6), middle + egui::vec2(0.0, half * 0.9)], + colour, + egui::Stroke::NONE, + )); +} diff --git a/crates/cloud-ui/src/cloud/app.rs b/crates/cloud-ui/src/cloud/app.rs new file mode 100644 index 000000000..cfb697935 --- /dev/null +++ b/crates/cloud-ui/src/cloud/app.rs @@ -0,0 +1,258 @@ +//! What this module needs from the application around it. +//! +//! Two operations here belong to the application alone. One turns bytes into an +//! open document. The other turns an open document into bytes. Both need the +//! application's own mutable state. That state is what holds the +//! [`CloudFiles`](crate::cloud::CloudFiles) this module keeps its own state in. +//! The pages are therefore free functions over this trait. An application +//! reaches its cloud state back through [`CloudApp::cloud_mut`]. +//! +//! Every method here is something only the application can answer. The ones +//! with a body are the ones a plain application can leave alone. + +use egui::{Color32, FontFamily, Painter, Rect, Ui}; + +use craft_cloud::EntryKind; + +/// What one of the application's documents is, as a file list needs to know. +/// +/// Four pieces of static data, usually one `const` in the application. These +/// four are the whole of what an application has to say about its own +/// documents. They are data because every one of them as a trait method would +/// have been a pure function of nothing. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct DocumentKind { + /// Extensions this application opens, lower case and without a dot. The + /// same set its desktop file picker offers. + pub extensions: &'static [&'static str], + /// Content types it opens, matched against the start of what the provider + /// said. The match is a prefix. A provider commonly appends a profile to a + /// type it is otherwise right about. + pub mimes: &'static [&'static str], + /// What one is called in a sentence a user reads. "workbook", "document", + /// "drawing". + pub noun: &'static str, + /// The extension a typed name without a known one gets. + pub default_extension: &'static str, +} + +/// The colours and faces these pages draw in. +/// +/// The Open and Save pages sit inside the application's own Backstage view and +/// have to match the surface around them. `ui.visuals()` alone cannot say what +/// that surface is. An application with a palette of its own passes it in. One +/// without takes [`CloudStyle::from_visuals`] and writes nothing. +#[derive(Clone, Debug)] +pub struct CloudStyle { + /// Behind a bordered column. + pub surface: Color32, + pub border: Color32, + pub text: Color32, + /// Second lines, hints and the status line. + pub dim: Color32, + /// Behind a file row the pointer is over. + pub hover: Color32, + /// Behind the panel that offers to link an account. Tinted and never + /// alarming. No account yet is a state with an obvious next step. + pub soft: Color32, + pub family: FontFamily, + pub bold: FontFamily, +} + +impl CloudStyle { + /// Colours from egui's own visuals, for an application with no palette. + pub fn from_visuals(visuals: &egui::Visuals) -> CloudStyle { + CloudStyle { + surface: visuals.faint_bg_color, + border: visuals.widgets.noninteractive.bg_stroke.color, + text: visuals.text_color(), + dim: visuals.weak_text_color(), + hover: visuals.widgets.hovered.bg_fill, + soft: visuals.faint_bg_color, + family: FontFamily::Proportional, + bold: FontFamily::Proportional, + } + } +} + +/// One of the application's own Save a Copy formats, for the second half of +/// the Share menu. +/// +/// The application's own. What a spreadsheet exports and what a page layout +/// application exports have nothing in common. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct CopyFormat { + /// Handed back untouched when this one is chosen. + pub id: String, + pub label: String, +} + +impl CopyFormat { + pub fn new(id: impl Into, label: impl Into) -> CopyFormat { + CopyFormat { id: id.into(), label: label.into() } + } +} + +/// An application that opens and saves documents in cloud storage. +/// Where a save is going. +/// +/// Carried as a pair because neither half is reliable alone. A provider hands +/// back `application/octet-stream` for a perfectly good document, and a file +/// exported by a web application often has a correct content type and no +/// extension at all. The same reasoning as [`DocumentKind`], which reads both +/// when deciding whether a document opens. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct Destination<'a> { + /// The file name the bytes are going to. + pub name: &'a str, + /// What the provider says is already there, where it says anything. Absent + /// for a document that does not exist yet. + pub mime: Option<&'a str>, +} + +impl<'a> Destination<'a> { + pub fn new(name: &'a str) -> Destination<'a> { + Destination { name, mime: None } + } + + /// The extension the name carries, lower cased, when it carries one. + /// + /// Empty for a bare name. A caller that gets nothing here has the content + /// type left to read. + pub fn extension(&self) -> String { + self.name.rsplit_once('.').map(|(_, ext)| ext.to_ascii_lowercase()).filter(|ext| !ext.is_empty()).unwrap_or_default() + } +} + +pub trait CloudApp { + // ---- the state these pages keep ------------------------------------- + + fn cloud(&self) -> &crate::cloud::CloudFiles; + fn cloud_mut(&mut self) -> &mut crate::cloud::CloudFiles; + + // ---- its documents --------------------------------------------------- + + fn kind(&self) -> DocumentKind; + + /// The document in this window, when there is one. + fn active(&self) -> Option; + + /// What to call one, for the Save As name field. + fn title(&self, uid: u64) -> String; + + /// Turn bytes into an open document, answering with the one it opened as. + /// + /// `Ok(None)` when the application took the bytes somewhere else, such as + /// a prompt for a password. Nothing is said about them yet. `Err` is put + /// to the user. + fn open_bytes(&mut self, name: &str, bytes: Vec) -> Result, String>; + + /// Turn one open document into the bytes to save, for `into`. + /// + /// [`Destination`] is where the bytes are going. A document opened from + /// the cloud as `figures.csv` has to go back as a CSV. Encoding it in the + /// application's own format under that name hands the user a file no other + /// application can read, and nothing tells them it happened. + /// + /// The name is the first answer. A provider that issued no extension at + /// all still says what the thing is, so the content type is the second. + /// Both appear often: a file exported by a web application commonly has a + /// correct content type and a bare name. + /// + /// An application that cannot write what the destination asks for should + /// refuse and say which formats it can write. A refusal a person can act + /// on beats a file that silently is not what it claims. + /// + /// Takes `&mut self` so the application can record which version of the + /// document these bytes were. A save that lands clears the dirty flag for + /// exactly that version. An edit made while the bytes were on the wire + /// stays unsaved. [`CloudApp::mark_saved`] and [`CloudApp::drop_pending`] + /// say which happened. + fn encode(&mut self, uid: u64, into: Destination<'_>) -> Result, String>; + + /// Close a document a reload replaced. Called only once the replacement is + /// open. A read that failed leaves the user's work where it was. + fn close(&mut self, uid: u64); + + /// The bytes [`CloudApp::encode`] made reached the service. + fn mark_saved(&mut self, _uid: u64) {} + + /// They did not. Forget the version it recorded. + fn drop_pending(&mut self, _uid: u64) {} + + /// Finish whatever the user is still typing. False stops the save. + fn ready_to_save(&mut self) -> bool { + true + } + + // ---- the window around them ------------------------------------------ + + /// The share dialog this window holds. Opened from a document's overflow + /// menu and from the Share button. Refreshed when who is signed in + /// changes. + fn sharing(&mut self) -> &mut crate::share::ShareDialog; + + /// Who else is in the document. Drawn beside the account badge. + fn presence(&mut self) -> &mut crate::presence::PresenceBar; + + /// Paint the icon for one row of a file list. Every application already + /// owns an icon set. None of them agree on how it is reached. + fn paint_icon(&self, painter: &Painter, rect: Rect, kind: EntryKind, colour: Color32); + + /// Open a URL in the user's browser. A browser is the application's + /// business. This crate opens nothing. + fn open_url(&self, url: &str); + + /// Open the provider's conversation for this document. + /// + /// Desktop hosts may hand this to the operating system so a registered + /// chat application can claim it. Browser hosts may navigate the current + /// tab, which remains reliable after an asynchronous provider lookup. + fn open_conversation(&self, url: &str) { + self.open_url(url); + } + + /// Say something that needs the user's attention, in the application's own + /// message box. + fn say(&mut self, text: String); + + /// Say something that does not, in passing. + fn toast(&mut self, _text: String) {} + + /// Take the user to the application's own Save As page, with the name + /// [`CloudFiles::save_name`](crate::cloud::CloudFiles::save_name) now + /// holding. Called when a refused save is answered with Save as a copy. + /// Hosts call [`cancel_save_as`](crate::cloud::cancel_save_as) when leaving + /// that page without submitting, or before opening an ordinary Save As, + /// so the abandoned copy's document and suggested name cannot carry over. + fn go_to_save_as(&mut self) {} + + // ---- its words ------------------------------------------------------- + + /// What the application is called, for the one sentence that names it. + fn app_name(&self) -> &str; + + /// Translate one English string. The default leaves it alone. An + /// application with no translation table writes nothing. + fn tr(&self, text: &str) -> String { + text.to_owned() + } + + /// The host part of the service address, for the account menu's first + /// line. Somebody with an account on two deployments needs to know which + /// one a document is about to land in. + fn service(&self) -> String { + String::new() + } + + /// A line under the Save page's name field, about the format this + /// application saves in. + fn save_note(&self) -> Option { + None + } + + /// The colours and faces to draw in. + fn style(&self, ui: &Ui) -> CloudStyle { + CloudStyle::from_visuals(ui.visuals()) + } +} diff --git a/crates/cloud-ui/src/cloud/backend.rs b/crates/cloud-ui/src/cloud/backend.rs new file mode 100644 index 000000000..f92328cef --- /dev/null +++ b/crates/cloud-ui/src/cloud/backend.rs @@ -0,0 +1,213 @@ +//! Where Open and Save do their waiting. It is never on the frame. +//! +//! Every call a cloud provider needs is blocking. A blocking read of a twenty +//! megabyte document inside `update()` freezes the window for seconds. So this +//! module states a [`Job`] and reads an [`Event`]. Something behind +//! [`CloudBackend`] does the waiting. +//! +//! Nothing here opens a socket. That keeps the pages buildable for the web and +//! testable with no service running. A host supplies the half that does. This +//! crate never learns what it reaches. + +use std::sync::Arc; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::mpsc::Sender; + +use craft_cloud::{Capability, Conversation, Entry}; + +/// Work for a host's worker. Each one answers with one or more [`Event`]. +pub enum Job { + /// Who is signed in, and what the provider behind the service can do. + Account, + /// Begin signing in to the service through the browser or device flow. + SignIn, + /// Begin linking a cloud account. The answer carries a URL to open. + LinkStart, + /// Whether the user has finished in the browser yet. + LinkPoll(String), + /// One folder's contents. An empty path is the user's root. + List(String), + /// Everything other people have shared with this user. + SharedWithMe, + /// A document's bytes. `into` names the open document a reload replaces. + Read { entry: Entry, into: Option }, + /// Save back over `entry`, refusing to overwrite a newer version. + Write { uid: u64, entry: Entry, bytes: Vec }, + /// Save under a new name in `folder`. + Create { uid: u64, folder: String, name: String, bytes: Vec }, + /// End the session and forget the saved token. + SignOut, + /// Where to go to work together on a document. + Conversation(String), +} + +/// What a worker reports back. +pub enum Event { + /// Where to go to work together, or why there is nowhere. + Conversation(Result), + Account(Result), + /// A link or a sign-in needs the user's browser. `handle` is polled until + /// they are done, when the service gave one. + Browser { + url: String, + handle: Option, + }, + /// `Ok(true)` means the account is linked now. + Linked(Result), + Listed { + path: String, + entries: Result, Fault>, + }, + Shared(Result, Fault>), + Read { + entry: Entry, + into: Option, + bytes: Result, Fault>, + }, + Saved { + uid: u64, + entry: Result, + }, +} + +/// Where a worker's answers go. +/// +/// Handed to [`CloudBackend::submit`] with the job it belongs to. A worker is +/// free to keep it and send later, or to send several times. That is how a +/// sign-in reports the URL it wants a browser pointed at and then reports that +/// the user finished there. A send after the window closed is not a failure. +pub struct Post { + tx: Sender, + /// The window's account generation as of the moment the job this answers + /// was issued, beside a handle to what it is now. A sign-out or a new + /// sign-in bumps the live value; a reply that arrives after is for a + /// session that is gone, and must not land on the one that replaced it. + generation: Arc, + issued: u64, +} + +impl Post { + pub(crate) fn new(tx: Sender, generation: Arc) -> Post { + let issued = generation.load(Ordering::Relaxed); + Post { tx, generation, issued } + } + + /// Another handle to the same place, for a worker that answers more than + /// once or hands the job on. Carries the same generation: every answer to + /// one job was issued at the same moment, however many of them there are. + pub fn dup(&self) -> Post { + Post { tx: self.tx.clone(), generation: self.generation.clone(), issued: self.issued } + } + + /// Delivers the event, unless the window has signed out or signed in + /// again since the job this answers was issued. Silently dropping it + /// there, rather than delivering it, is what keeps a late reply from + /// restoring the previous session's account, files or busy state on top + /// of whatever replaced it. + pub fn send(&self, event: Event) { + if self.generation.load(Ordering::Relaxed) != self.issued { + return; + } + let _ = self.tx.send(event); + } +} + +impl std::fmt::Debug for Post { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("Post").finish() + } +} + +/// Somewhere a [`Job`] can run without blocking a frame. +/// +/// `submit` must return immediately. Answers arrive through `post` whenever +/// they are ready, or never. The pages survive either. +pub trait CloudBackend { + fn submit(&self, job: Job, post: Post); +} + +/// What the service said about the signed-in user. +/// +/// Capabilities are reported by the service and never assumed here. A provider +/// without incoming shares hides that side of the Open page. An empty list +/// where a feature should be reads to a user as a broken window. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct Account { + pub display: String, + pub capabilities: Vec, + /// Until this is true, Open and Save have nowhere to go. + pub provider_linked: bool, +} + +impl Account { + pub fn can(&self, capability: Capability) -> bool { + self.capabilities.contains(&capability) + } +} + +/// A call that did not succeed, in the shapes the pages act on differently. +/// +/// One case is worth telling apart from every other refusal. A conditional +/// write the server refused means somebody else's work is in the stored copy. +/// That one must never be retried and must never be forced. That is why +/// [`Fault::Conflict`] has a shape of its own. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Fault { + /// No cloud account is linked yet. This is a state with an obvious next + /// step. It is never drawn as an error. + NotLinked, + /// Somebody else saved while this user was editing. The save was refused + /// and their work is intact. + Conflict, + /// The session expired. The user signs in again. + Unauthenticated, + Unreachable(String), + Refused(String), +} + +impl Fault { + /// One sentence for a person to read. `noun` is what the application calls + /// one of its documents, from [`crate::cloud::DocumentKind::noun`]. + pub fn text(&self, noun: &str) -> String { + match self { + Fault::NotLinked => "No cloud account is linked yet.".to_owned(), + Fault::Conflict => format!("Somebody else saved this {noun} while you were editing it."), + Fault::Unauthenticated => "Your cloud session has expired. Sign in again.".to_owned(), + Fault::Unreachable(detail) => format!("The cloud service could not be reached. {detail}"), + Fault::Refused(detail) => detail.clone(), + } + } + + /// A short machine-readable name, for a control channel. + pub fn code(&self) -> &'static str { + match self { + Fault::NotLinked => "not_linked", + Fault::Conflict => "conflict", + Fault::Unauthenticated => "unauthenticated", + Fault::Unreachable(_) => "unreachable", + Fault::Refused(_) => "refused", + } + } +} + +/// The contract's own error, in the shapes the pages act on. +/// +/// For a host that reaches a provider through [`craft_cloud`] directly. A host +/// that reaches a service through its own client crate maps that crate's error +/// instead, since only it knows which code that service answers a refused +/// conditional write with. +/// +/// [`craft_cloud::Error::Conflict`] is the one case worth telling apart. It +/// means somebody else's work is in the stored copy. The save must never be +/// retried and never be forced. +impl From for Fault { + fn from(error: craft_cloud::Error) -> Fault { + use craft_cloud::Error; + match error { + Error::Unreachable(detail) => Fault::Unreachable(detail), + Error::Unauthenticated => Fault::Unauthenticated, + Error::Conflict(_) => Fault::Conflict, + other => Fault::Refused(other.to_string()), + } + } +} diff --git a/crates/cloud-ui/src/cloud/conflict_tests.rs b/crates/cloud-ui/src/cloud/conflict_tests.rs new file mode 100644 index 000000000..1e22e815f --- /dev/null +++ b/crates/cloud-ui/src/cloud/conflict_tests.rs @@ -0,0 +1,315 @@ +//! Two risks a tabbed host runs that a single-document test cannot see: a document other than +//! the one a conflict or a job is about can be active when the answer lands, and a session that +//! ended can still have a job outstanding. +//! +//! `Tabs` is a host with two open documents (a tabbed window) and `Held` is a backend that keeps +//! every job so the test decides when, and with what, the service answers. + +use std::sync::{Arc, Mutex}; + +use craft_cloud::{Capability, Entry, EntryKind}; +use egui_kittest::Harness; +use egui_kittest::kittest::Queryable; + +use super::*; + +const NOTES: DocumentKind = DocumentKind { extensions: &["note"], mimes: &["text/plain"], noun: "note", default_extension: "note" }; + +#[derive(Default)] +struct Log { + read: Vec, + encoded: Vec, + closed: Vec, + said: Vec, +} + +struct Tabs { + cloud: CloudFiles, + share: crate::share::ShareDialog, + presence: crate::presence::PresenceBar, + active: u64, + next_uid: u64, + log: Arc>, +} + +impl CloudApp for Tabs { + fn cloud(&self) -> &CloudFiles { + &self.cloud + } + fn cloud_mut(&mut self) -> &mut CloudFiles { + &mut self.cloud + } + fn kind(&self) -> DocumentKind { + NOTES + } + fn active(&self) -> Option { + Some(self.active) + } + fn title(&self, uid: u64) -> String { + format!("doc {uid}") + } + fn open_bytes(&mut self, name: &str, _bytes: Vec) -> Result, String> { + self.log.lock().unwrap().read.push(name.to_owned()); + self.next_uid += 1; + Ok(Some(self.next_uid)) + } + fn encode(&mut self, uid: u64, _into: Destination<'_>) -> Result, String> { + self.log.lock().unwrap().encoded.push(uid); + Ok(format!("bytes of {uid}").into_bytes()) + } + fn close(&mut self, uid: u64) { + self.log.lock().unwrap().closed.push(uid); + } + fn sharing(&mut self) -> &mut crate::share::ShareDialog { + &mut self.share + } + fn presence(&mut self) -> &mut crate::presence::PresenceBar { + &mut self.presence + } + fn paint_icon(&self, _p: &egui::Painter, _r: egui::Rect, _k: EntryKind, _c: egui::Color32) {} + fn open_url(&self, _url: &str) {} + fn say(&mut self, text: String) { + self.log.lock().unwrap().said.push(text); + } + fn app_name(&self) -> &str { + "Notes" + } +} + +#[derive(Clone, Default)] +struct Held(Arc>>); + +impl CloudBackend for Held { + fn submit(&self, job: Job, post: Post) { + self.0.lock().unwrap().push((job, post)); + } +} + +impl Held { + fn take(&self, pick: impl Fn(&Job) -> bool) -> Option<(Job, Post)> { + let mut held = self.0.lock().unwrap(); + let i = held.iter().position(|(j, _)| pick(j))?; + Some(held.remove(i)) + } +} + +fn entry(path: &str, etag: &str) -> Entry { + Entry { + id: path.to_owned(), + room: format!("room:{path}"), + name: path.trim_start_matches('/').to_owned(), + path: path.to_owned(), + kind: EntryKind::File, + size: Some(10), + modified: None, + mime: None, + etag: Some(etag.to_owned()), + writable: true, + shared_by: None, + } +} + +fn account(name: &str) -> Account { + Account { display: name.to_owned(), capabilities: vec![Capability::Files, Capability::Etags], provider_linked: true } +} + +fn drain(app: &mut Tabs, ctx: &egui::Context) { + ctx.begin_pass(Default::default()); + pump(app, ctx); + ctx.end_pass().textures_delta.clear(); +} + +/// Two cloud documents open: uid 1 = A.note, uid 2 = B.note (B has unsaved edits). +fn two_tabs() -> (Tabs, Held, Arc>) { + let held = Held::default(); + let log = Arc::new(Mutex::new(Log::default())); + let mut app = Tabs { + cloud: CloudFiles::new(), + share: crate::share::ShareDialog::new(), + presence: crate::presence::PresenceBar::new(), + active: 1, + next_uid: 10, + log: log.clone(), + }; + app.cloud.connect(held.clone()); + app.cloud.origins.insert(1, Origin { entry: entry("/A.note", "a1") }); + app.cloud.origins.insert(2, Origin { entry: entry("/B.note", "b1") }); + (app, held, log) +} + +/// Save A, the user moves to tab B while the write is on the wire, the service refuses A's write +/// (Conflict). Returns the app with the conflict modal pending, active tab = B. +fn conflict_on_a_while_b_is_active() -> (Tabs, Held, Arc>) { + let (mut app, held, log) = two_tabs(); + save(&mut app).unwrap(); + app.active = 2; + let (job, post) = held.take(|j| matches!(j, Job::Write { .. })).unwrap(); + let Job::Write { uid, .. } = job else { panic!("expected Job::Write") }; + post.send(Event::Saved { uid, entry: Err(Fault::Conflict) }); + let ctx = egui::Context::default(); + drain(&mut app, &ctx); + assert_eq!(app.cloud.conflict.as_ref().map(|c| (c.uid, c.entry.name.clone())), Some((1, "A.note".to_owned()))); + (app, held, log) +} + +fn click_in_conflict_modal(app: Tabs, label: &str) -> Tabs { + let mut harness = Harness::new_ui_state(|ui, app: &mut Tabs| conflict_modal(app, &ui.ctx().clone()), app); + harness.run(); + harness.get_by_label(label).click(); + harness.run(); + harness.into_state() +} + +/// The modal says A.note was not saved; clicking "Reload from the cloud" must reload A and +/// replace uid 1, the conflicted document, never whichever tab happens to be active. +#[test] +fn conflict_reload_acts_on_the_conflicted_document_even_when_another_tab_is_active() { + let (app, held, log) = conflict_on_a_while_b_is_active(); + let mut app = click_in_conflict_modal(app, "Reload from the cloud"); + let (job, post) = held.take(|j| matches!(j, Job::Read { .. })).expect("Reload submitted a read"); + let Job::Read { entry: read, into } = job else { panic!("expected Job::Read") }; + let read_name = read.name.clone(); + post.send(Event::Read { entry: read, into, bytes: Ok(b"stored".to_vec()) }); + drain(&mut app, &egui::Context::default()); + let log = log.lock().unwrap(); + assert!( + read_name == "A.note" && into == Some(1) && !log.closed.contains(&2), + "conflict was on uid 1 (A.note); Reload read {read_name:?} into {into:?}, then closed {:?}", + log.closed + ); +} + +/// "Save as a copy" from the conflict modal must encode the conflicted document, A, not +/// whichever tab happens to be active when the Save As page's own button is finally clicked. +#[test] +fn conflict_save_as_copy_encodes_the_conflicted_document_even_when_another_tab_is_active() { + let (app, held, log) = conflict_on_a_while_b_is_active(); + let mut app = click_in_conflict_modal(app, "Save as a copy…"); + let name = app.cloud.save_name.clone(); + save_as(&mut app, "", &name).unwrap(); // what the Save As page does with that name + let (job, _) = held.take(|j| matches!(j, Job::Create { .. })).unwrap(); + let Job::Create { uid, name, bytes, .. } = job else { panic!("expected Job::Create") }; + assert_eq!( + (uid, String::from_utf8_lossy(&bytes).into_owned()), + (1, "bytes of 1".to_owned()), + "copy of the conflicted A.note is created as {name:?} from uid {uid} (encoded uids {:?})", + log.lock().unwrap().encoded + ); +} + +/// A read the backend never answers (the trait allows "or never") must not leave every transfer +/// refused forever. Signing out and back in recovers Save. +#[test] +fn sign_out_recovers_save_after_a_backend_job_never_replies() { + let (mut app, held, _log) = two_tabs(); + open_entry(&mut app, entry("/C.note", "c1"), None); + held.take(|j| matches!(j, Job::Read { .. })).unwrap(); // dropped by the worker + sign_out(&mut app); + sign_in(&mut app); + let (_, post) = held.take(|j| matches!(j, Job::SignIn)).unwrap(); + post.send(Event::Account(Ok(account("Ada")))); + drain(&mut app, &egui::Context::default()); + app.cloud.origins.insert(1, Origin { entry: entry("/A.note", "a1") }); + let saved = save(&mut app); + assert!(saved.is_ok(), "after sign-out and sign-in, Save is still refused: {saved:?}; busy={:?}", app.cloud.busy.as_ref().map(Busy::text)); +} + +/// An account and a listing answer a job issued before sign-out. Landing after it, they must +/// not put the previous session's account and file names on screen with nobody signed in. +#[test] +fn a_late_reply_from_before_sign_out_is_dropped() { + let (mut app, held, _log) = two_tabs(); + start(&mut app); + let (_, account_post) = held.take(|j| matches!(j, Job::Account)).unwrap(); + let (_, list_post) = held.take(|j| matches!(j, Job::List(_))).unwrap(); + sign_out(&mut app); + account_post.send(Event::Account(Ok(account("Previous Person")))); + list_post.send(Event::Listed { path: String::new(), entries: Ok(vec![entry("/Payroll 2026.note", "p1")]) }); + drain(&mut app, &egui::Context::default()); + let r = report(&app); + assert!( + r["account"].is_null() && r["entries"].as_array().is_some_and(Vec::is_empty), + "signed out, yet account={} entries={}", + r["account"], + r["entries"] + ); +} + +/// Save as a copy, then the first click on the Save As page is refused (no name typed yet). The +/// second click, with a name, must still copy the conflicted document A, not the active tab B. +#[test] +fn conflict_copy_survives_a_refused_first_attempt() { + let (app, held, log) = conflict_on_a_while_b_is_active(); + let mut app = click_in_conflict_modal(app, "Save as a copy…"); + let refused = save_as(&mut app, "", ""); + assert!(refused.is_err(), "an empty name is refused: {refused:?}"); + let name = app.cloud.save_name.clone(); + save_as(&mut app, "", &name).unwrap(); + let (job, _) = held.take(|j| matches!(j, Job::Create { .. })).unwrap(); + let Job::Create { uid, bytes, .. } = job else { panic!("expected Job::Create") }; + assert_eq!( + (uid, String::from_utf8_lossy(&bytes).into_owned()), + (1, "bytes of 1".to_owned()), + "after one refused attempt the copy of A.note encodes uid {uid} (encoded uids {:?})", + log.lock().unwrap().encoded + ); +} + +/// Save as a copy, but the user leaves the Save As page without saving. Later, on tab B, an +/// ordinary Save As must save B, not the conflicted A from the abandoned copy. +#[test] +fn cancelled_conflict_copy_does_not_hijack_a_later_save_as() { + let (app, held, log) = conflict_on_a_while_b_is_active(); + let app = click_in_conflict_modal(app, "Save as a copy…"); + let mut app = app; + cancel_save_as(&mut app); // the host leaves the Save As page without submitting + assert!(app.cloud.save_name.is_empty()); + assert_eq!(app.active, 2); + save_as(&mut app, "", "B renamed").unwrap(); + let (job, _) = held.take(|j| matches!(j, Job::Create { .. })).unwrap(); + let Job::Create { uid, name, bytes, .. } = job else { panic!("expected Job::Create") }; + assert_eq!( + (uid, String::from_utf8_lossy(&bytes).into_owned()), + (2, "bytes of 2".to_owned()), + "an ordinary Save As of tab B as {name:?} encoded uid {uid} (encoded uids {:?})", + log.lock().unwrap().encoded + ); +} + +/// A successfully saved conflict copy must not redirect a later ordinary Save As. +#[test] +fn successful_conflict_copy_releases_its_document_target() { + let (app, held, _log) = conflict_on_a_while_b_is_active(); + let mut app = click_in_conflict_modal(app, "Save as a copy…"); + let name = app.cloud.save_name.clone(); + save_as(&mut app, "", &name).unwrap(); + let (job, post) = held.take(|job| matches!(job, Job::Create { .. })).unwrap(); + let Job::Create { uid, .. } = job else { panic!("expected Job::Create") }; + assert_eq!(uid, 1); + assert_eq!(app.cloud.save_as_target, Some(1)); + post.send(Event::Saved { uid, entry: Ok(entry("/A-copy.note", "a2")) }); + drain(&mut app, &egui::Context::default()); + assert_eq!(app.cloud.save_as_target, None); + save_as(&mut app, "", "B renamed").unwrap(); + let (job, _) = held.take(|job| matches!(job, Job::Create { .. })).unwrap(); + let Job::Create { uid, bytes, .. } = job else { panic!("expected Job::Create") }; + assert_eq!((uid, bytes), (2, b"bytes of 2".to_vec())); +} + +/// A refused create keeps the same document pinned while the user changes its name. +#[test] +fn conflict_copy_survives_a_backend_refusal() { + let (app, held, _log) = conflict_on_a_while_b_is_active(); + let mut app = click_in_conflict_modal(app, "Save as a copy…"); + let name = app.cloud.save_name.clone(); + save_as(&mut app, "", &name).unwrap(); + let (job, post) = held.take(|job| matches!(job, Job::Create { .. })).unwrap(); + let Job::Create { uid, .. } = job else { panic!("expected Job::Create") }; + assert_eq!(uid, 1); + post.send(Event::Saved { uid, entry: Err(Fault::Refused("exists".to_owned())) }); + drain(&mut app, &egui::Context::default()); + save_as(&mut app, "", "A another copy").unwrap(); + let (job, _) = held.take(|job| matches!(job, Job::Create { .. })).unwrap(); + let Job::Create { uid, bytes, .. } = job else { panic!("expected Job::Create") }; + assert_eq!((uid, bytes), (1, b"bytes of 1".to_vec())); +} diff --git a/crates/cloud-ui/src/cloud/mod.rs b/crates/cloud-ui/src/cloud/mod.rs new file mode 100644 index 000000000..b1013a8ad --- /dev/null +++ b/crates/cloud-ui/src/cloud/mod.rs @@ -0,0 +1,901 @@ +//! Open and Save against cloud storage, the same pages in every Craft app. +//! +//! What this offers is what a person asks for when they say "open the one in +//! my cloud": a Backstage page with their own files on one side and what other +//! people shared with them on the other, folders to walk into, an account badge +//! that says whose storage this is, a Save As page that picks a folder and +//! names a file, and a save that refuses to overwrite somebody else's work. +//! +//! Three things shape the implementation. +//! +//! Nothing here opens a socket. Every call goes through [`CloudBackend`]. A +//! host writes that half. This module never learns what it reaches. That keeps +//! it buildable for the web and testable with no service running. +//! +//! Nothing here blocks. A job goes to a worker, the answer arrives on a +//! channel, and [`pump`] drains it on a later frame. A blocking read of a +//! twenty megabyte document inside a frame would freeze the window for seconds. +//! +//! Nothing here is assumed about the provider. Every side of the Open page is +//! drawn only where the service reported the capability behind it. An empty +//! list under a heading reads to a user as a broken window. A feature the +//! provider does not have is therefore absent, heading and all. +//! +//! The application supplies [`CloudApp`]. That is what it alone can answer. +//! What its documents are, how bytes become one and back, and the words it +//! shows them in. + +use std::collections::HashMap; +use std::sync::Arc; +use std::sync::atomic::{AtomicU64, Ordering}; +use std::sync::mpsc::{Receiver, Sender, channel}; +use std::time::Duration; + +use craft_cloud::{Capability, Entry, EntryKind}; +use egui::{Align2, Rect, RichText, Sense, Stroke, Ui, pos2, vec2}; +use serde_json::{Value as Json, json}; + +mod app; +mod backend; +#[cfg(test)] +mod conflict_tests; +mod pages; +#[cfg(test)] +mod tests; +mod title; + +pub use app::{CloudApp, CloudStyle, CopyFormat, Destination, DocumentKind}; +pub use backend::{Account, CloudBackend, Event, Fault, Job, Post}; +pub use pages::{conflict_modal, open_page, progress, save_page}; +pub use title::{destination_name, prefers_cloud, share_button, shares, who}; + +/// How long to wait between asking whether the user has finished linking an +/// account in their browser. +const LINK_POLL: f64 = 1.5; + +/// What a command says when no cloud service is configured. Not a failure of +/// the service: there is no service to fail. +pub const UNAVAILABLE: &str = "no cloud service is configured"; + +// ---------------------------------------------------------------- state + +/// One folder, as it is being browsed. +#[derive(Clone, Debug, Default)] +pub struct Folder { + pub path: String, + pub entries: Vec, + pub loading: bool, + pub error: Option, + /// Answered at least once. An empty folder then reads as empty. Without + /// this it would read as still loading. + pub loaded: bool, +} + +impl Folder { + fn begin(&mut self, path: &str) { + self.path = path.to_owned(); + self.entries.clear(); + self.loading = true; + self.loaded = false; + self.error = None; + } + + fn fill(&mut self, answer: Result, Fault>) { + self.loading = false; + self.loaded = true; + match answer { + Ok(entries) => { + self.entries = entries; + self.error = None; + } + Err(fault) => { + self.entries.clear(); + self.error = Some(fault); + } + } + } +} + +/// Where the document in this window came from, and the version it came at. +/// +/// `entry.id` is the opaque handle a save passes back. `entry.etag` is the +/// version the conditional write is made against. `entry.room` is neither of +/// those. It is the collaboration identity, and it survives a rename. +#[derive(Clone, Debug)] +pub struct Origin { + pub entry: Entry, +} + +/// What the pages are waiting for. Drawn as progress while they wait. +#[derive(Clone, Debug)] +pub enum Busy { + Opening { name: String }, + Saving { name: String, bytes: usize }, +} + +impl Busy { + pub fn text(&self) -> String { + match self { + Busy::Opening { name } => format!("Opening {name}…"), + Busy::Saving { name, bytes } => format!("Saving {name} ({})…", size_text(Some(*bytes as u64))), + } + } +} + +/// A save that was refused because the stored copy had moved on. +#[derive(Clone, Debug)] +pub struct Conflict { + /// The document that could not be saved. + pub uid: u64, + pub entry: Entry, +} + +/// Linking a cloud account, which takes a browser round trip. +#[derive(Clone, Debug)] +pub enum Link { + /// Offered and not started. Never drawn as an error. + Offered, + Starting, + /// The browser is open. `handle` is polled until the user is done. + Waiting { + url: String, + handle: Option, + next_poll: f64, + }, + Failed(Fault), +} + +/// Which side of the Open page a selection came from. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub enum Source { + #[default] + Mine, + Shared, +} + +/// Who a document was shared with, when nobody is signed in. +/// +/// Somebody who followed a keyed link has no account at the service and none +/// at the provider behind it. So there is nothing to sign out of, no second +/// account to switch to and no storage to connect. An account menu offered to +/// them would be a menu whose every item fails. +/// +/// This is what a title bar says instead. It names the address the link was +/// sent to, because that is the only identity a recipient has here, and it +/// offers nothing. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Guest { + /// The address the link was sent to. + pub recipient: String, + /// Whether the share opens the document for reading only. + pub read_only: bool, +} + +/// Everything these pages keep about cloud storage. +/// +/// One per window. The application declares a field of this type, hands it +/// back through [`CloudApp::cloud_mut`], and connects a backend once one +/// exists. +pub struct CloudFiles { + backend: Option>, + events: (Sender, Receiver), + /// The badge and its menu. Signing in is the only way into any of this. + /// The badge is the only control that offers it. It lives here. An + /// application declares no field for it. + accounts: crate::account::AccountMenu, + /// Frame time, in seconds, as of the last [`pump`]. Kept because a link + /// poll is scheduled from an answer that arrives with no frame in hand. + clock: f64, + pub account: Option, + pub account_fault: Option, + /// The account is asked for once per run. A frame never asks again. + asked_account: bool, + /// The folder being browsed. Shared by the Open and Save As pages, which + /// are never on screen together. + pub mine: Folder, + pub shared: Folder, + pub source: Source, + pub busy: Option, + pub link: Option, + pub conflict: Option, + /// Save As: the file name being typed. + pub save_name: String, + /// Documents that came from the cloud, by document uid. + pub origins: HashMap, + /// The last thing that happened, for the line under the page title. + pub status: Option, + /// Whether the transfer in flight was started by the share dialog, which + /// is waiting to be told how it went. + pub sharing_save: bool, + /// Set when this window belongs to somebody who followed a shared link + /// rather than to somebody signed in. + guest: Option, + /// Set when the account menu starts sign-in. Browser builds open a login + /// popup from this gesture instead of inferring it from `status`, which can + /// stay set after a failed sign-in. + sign_in_from_menu: bool, + /// Bumped on sign-out and on a new sign-in. Stamped onto every [`Post`] + /// handed out by [`submit`] so a reply to a job issued before the bump is + /// dropped rather than applied to the session that replaced it. + account_generation: Arc, + /// The document Save As must act on, when it is not the active one. + /// + /// Set only by the conflict modal's "Save as a copy", so the copy it asks + /// for is made from the conflicted document even if the user has since + /// switched to another tab. Cleared after a successful save or by + /// [`cancel_save_as`] when the interaction is abandoned. + save_as_target: Option, +} + +impl Default for CloudFiles { + fn default() -> CloudFiles { + CloudFiles::new() + } +} + +impl CloudFiles { + pub fn new() -> CloudFiles { + CloudFiles { + backend: None, + events: channel(), + accounts: crate::account::AccountMenu::new(), + clock: 0.0, + account: None, + account_fault: None, + asked_account: false, + mine: Folder::default(), + shared: Folder::default(), + source: Source::default(), + busy: None, + link: None, + conflict: None, + save_name: String::new(), + origins: HashMap::new(), + status: None, + sharing_save: false, + guest: None, + sign_in_from_menu: false, + account_generation: Arc::new(AtomicU64::new(0)), + save_as_target: None, + } + } + + /// Whether the account menu just asked to sign in. Consumed by browser hosts + /// that need a user-gesture signal to open a login popup. + pub fn take_sign_in_from_menu(&mut self) -> bool { + std::mem::take(&mut self.sign_in_from_menu) + } + + /// Attach the thing that does the waiting. + /// + /// Until this is called nothing cloud-shaped is offered anywhere. That is + /// what a build with no service configured wants. + pub fn connect(&mut self, backend: impl CloudBackend + 'static) { + self.backend = Some(Box::new(backend)); + } + + /// Whether a service is wired at all. + pub fn available(&self) -> bool { + self.backend.is_some() + } + + /// Say that this window belongs to somebody who followed a shared link. + /// + /// Called once, before anything is drawn, by whatever landed them here. + /// It changes what the title bar says and nothing else: a recipient has no + /// file list and no account, so none of the pages here were ever offered + /// to them. + /// + /// An address of only spaces leaves no guest. A badge with nothing on it + /// reads as a fault, and saying nothing is better than that. + pub fn as_guest(&mut self, recipient: impl Into, read_only: bool) { + let recipient = recipient.into().trim().to_owned(); + self.guest = if recipient.is_empty() { None } else { Some(Guest { recipient, read_only }) }; + } + + /// Who this window's document was shared with, when nobody is signed in. + pub fn guest(&self) -> Option<&Guest> { + self.guest.as_ref() + } + + /// The account badge's own strings, for a localized application that + /// would rather translate them itself than through + /// [`CloudApp::tr`]. + pub fn account_menu_mut(&mut self) -> &mut crate::account::AccountMenu { + &mut self.accounts + } + + /// Whether the provider offers somewhere to talk about a document. + pub fn can_converse(&self) -> bool { + self.can(Capability::Conversation) + } + + fn can(&self, capability: Capability) -> bool { + self.account.as_ref().is_some_and(|a| a.can(capability)) + } +} + +// ---------------------------------------------------------------- asking + +/// Whether the host wired a cloud service. When it did not, nothing +/// cloud-shaped is offered anywhere in the interface. +pub fn available(app: &A) -> bool { + app.cloud().available() +} + +/// Whether the provider offers somewhere to talk about a document. +pub fn can_converse(app: &A) -> bool { + app.cloud().can_converse() +} + +/// Hands a job to the host's worker. +pub fn submit(app: &A, job: Job) { + let cloud = app.cloud(); + if let Some(backend) = &cloud.backend { + backend.submit(job, Post::new(cloud.events.0.clone(), cloud.account_generation.clone())); + } +} + +/// Asks who is signed in, once per run, and lists the root folder. +pub fn start(app: &mut A) { + if !available(app) { + return; + } + if !app.cloud().asked_account { + app.cloud_mut().asked_account = true; + submit(app, Job::Account); + } + if !app.cloud().mine.loaded && !app.cloud().mine.loading { + browse(app, ""); + } +} + +/// Begins signing in to the service. +/// +/// [`Job::SignIn`] is its own job so [`Job::Account`] can stay read-only on +/// cold start. The badge says it is working, because the worker then blocks +/// until the user finishes in the browser and a button that looks idle for a +/// minute reads as broken. +pub fn sign_in(app: &mut A) { + if !available(app) { + return; + } + let working = app.tr("Finish signing in, in your browser"); + let cloud = app.cloud_mut(); + cloud.accounts.working(); + cloud.account_fault = None; + // Cleared first. A sign-in that failed leaves this set, and a second press + // would then be swallowed by the guard that stops a frame asking twice. A + // button that does nothing the second time reads as a broken button. + cloud.asked_account = true; + cloud.link = None; + cloud.status = Some(working); + // A new session. A job the previous one left outstanding may never + // answer, and if it does, that answer is not about this account: see + // `Post::send`. Busy goes with it, or a stuck read from before this + // sign-in would leave Save refused for a session that never asked for it. + cloud.account_generation.fetch_add(1, Ordering::Relaxed); + cloud.busy = None; + submit(app, Job::SignIn); +} + +/// Ends the session, here and at the service. +/// +/// The saved token goes too. Forgetting the account on screen while leaving the +/// token on disk would sign the user back in on the next run. +pub fn sign_out(app: &mut A) { + let signed_out = app.tr("Signed out"); + let cloud = app.cloud_mut(); + cloud.account = None; + cloud.account_fault = None; + cloud.asked_account = false; + cloud.link = None; + cloud.mine = Folder::default(); + cloud.shared = Folder::default(); + cloud.origins.clear(); + cloud.status = Some(signed_out); + // The session this window had ends here. A job it started may never + // answer, and a reply that does arrive late must not land on whatever + // comes next: see `Post::send`. Busy goes with it, so an open or a save + // that never heard back does not refuse every one after it forever. + cloud.account_generation.fetch_add(1, Ordering::Relaxed); + cloud.busy = None; + cloud.save_as_target = None; + submit(app, Job::SignOut); +} + +/// Lists one folder. An empty path is the user's root. +pub fn browse(app: &mut A, path: &str) { + if !available(app) { + return; + } + app.cloud_mut().mine.begin(path); + submit(app, Job::List(path.to_owned())); +} + +/// Lists what other people have shared with this user. +pub fn load_shared(app: &mut A) { + if !available(app) { + return; + } + app.cloud_mut().shared.begin(""); + submit(app, Job::SharedWithMe); +} + +/// Begins linking a cloud account. +pub fn link(app: &mut A) { + if !available(app) { + return; + } + app.cloud_mut().link = Some(Link::Starting); + submit(app, Job::LinkStart); +} + +/// Asks where to work together on the open document, then opens it. +/// +/// Only offered where the provider reports it. A document that has never been +/// in the cloud has no handle to key a room on, so there is nothing to ask +/// about either. +pub fn work_together(app: &mut A) { + if !available(app) { + return; + } + let Some(id) = origin(app).map(|o| o.entry.id.clone()) else { + let noun = app.kind().noun; + app.cloud_mut().status = Some(app.tr(&format!("Save this {noun} to the cloud first"))); + return; + }; + converse(app, id); +} + +/// Asks the provider where to work together on one document. +fn converse(app: &mut A, id: String) { + let opening = app.tr("Opening a conversation"); + app.cloud_mut().status = Some(opening); + submit(app, Job::Conversation(id)); +} + +/// The parent of a path. `None` at the root. +pub fn parent_of(path: &str) -> Option { + let trimmed = path.trim_end_matches('/'); + if trimmed.is_empty() { + return None; + } + match trimmed.rfind('/') { + Some(0) | None => Some(String::new()), + Some(cut) => Some(trimmed[..cut].to_owned()), + } +} + +/// Whether this application can open an entry, judged by its extension and by +/// what the provider says it is. +/// +/// Both signals are read because neither is reliable alone. A WebDAV server +/// hands back `application/octet-stream` for a perfectly good spreadsheet. A +/// file exported by a web application often has a correct content type and no +/// extension at all. +pub fn opens(entry: &Entry, kind: DocumentKind) -> bool { + if entry.kind == EntryKind::Folder { + return false; + } + let extension = entry.name.rsplit_once('.').map(|(_, e)| e.to_ascii_lowercase()); + let by_name = extension.is_some_and(|e| kind.extensions.contains(&e.as_str())); + by_name || entry.mime.as_deref().is_some_and(|mime| mime_opens(mime, kind)) +} + +fn mime_opens(mime: &str, kind: DocumentKind) -> bool { + let mime = mime.split(';').next().unwrap_or("").trim().to_ascii_lowercase(); + kind.mimes.iter().any(|known| mime.starts_with(known)) +} + +/// A typed name as a document file name. Any folder separators are dropped and +/// a missing or unknown extension becomes the application's own. +pub fn document_name(typed: &str, kind: DocumentKind) -> String { + let base = typed.rsplit(['/', '\\']).next().unwrap_or("").trim(); + if base.is_empty() { + return String::new(); + } + let known = base.rsplit_once('.').is_some_and(|(stem, ext)| !stem.is_empty() && kind.extensions.contains(&ext.to_ascii_lowercase().as_str())); + if known { base.to_owned() } else { format!("{base}.{}", kind.default_extension) } +} + +/// One sentence with a value in it, translated whole. +/// +/// The template reaches [`CloudApp::tr`] with its `{}` intact. A translator +/// sees the whole sentence and can put the value where their own language +/// wants it. A sentence assembled from translated fragments cannot be made to +/// read correctly in a language that orders them differently. +fn fill(app: &A, template: &str, value: &str) -> String { + app.tr(template).replacen("{}", value, 1) +} + +/// A file name without its extension. +fn stem_of(name: &str) -> String { + match name.rsplit_once('.') { + Some((stem, _)) if !stem.is_empty() => stem.to_owned(), + _ => name.to_owned(), + } +} + +// ---------------------------------------------------------------- opening + +/// Reads a document and opens it. `into` names an open document the bytes +/// replace, which is how a reload after a conflict works. +pub fn open_entry(app: &mut A, entry: Entry, into: Option) { + if !available(app) || app.cloud().busy.is_some() { + return; + } + let cloud = app.cloud_mut(); + cloud.status = None; + cloud.busy = Some(Busy::Opening { name: entry.name.clone() }); + submit(app, Job::Read { entry, into }); +} + +/// Reads the active document's stored copy again. Local edits are discarded. +pub fn reload_active(app: &mut A) -> Result { + let noun = app.kind().noun; + let Some(uid) = app.active() else { return Err(format!("no {noun} open")) }; + let Some(origin) = app.cloud().origins.get(&uid).cloned() else { return Err(format!("this {noun} did not come from the cloud")) }; + app.cloud_mut().conflict = None; + let name = origin.entry.name.clone(); + open_entry(app, origin.entry, Some(uid)); + Ok(json!({"reloading": name})) +} + +// ---------------------------------------------------------------- saving + +/// The cloud document the active one came from, when it came from one. +pub fn origin(app: &A) -> Option<&Origin> { + let uid = app.active()?; + app.cloud().origins.get(&uid) +} + +/// Whether Save has somewhere to go without asking. A Backstage view uses this +/// to choose between Save and the Save As page. +pub fn has_target(app: &A) -> bool { + origin(app).is_some_and(|o| o.entry.writable) +} + +/// Save: writes back over the entry this document came from. +/// +/// The etag the document was read at goes out as the condition. A server whose +/// copy has moved on refuses the write. That arrives as [`Fault::Conflict`] and +/// is put to the user. It is never retried. +pub fn save(app: &mut A) -> Result { + let noun = app.kind().noun; + let uid = app.active().ok_or(format!("no {noun} open"))?; + let origin = app.cloud().origins.get(&uid).cloned().ok_or(format!("this {noun} did not come from the cloud"))?; + if !origin.entry.writable { + return Err("this document was shared with you for reading only. Save As keeps a copy of your own.".to_owned()); + } + if app.cloud().busy.is_some() { + return Err("a cloud transfer is already running".to_owned()); + } + let bytes = app.encode(uid, Destination { name: &origin.entry.name, mime: origin.entry.mime.as_deref() })?; + let size = bytes.len(); + let cloud = app.cloud_mut(); + cloud.status = None; + cloud.busy = Some(Busy::Saving { name: origin.entry.name.clone(), bytes: size }); + let answer = json!({"saving": origin.entry.name, "bytes": size, "ifMatch": origin.entry.etag}); + submit(app, Job::Write { uid, entry: origin.entry, bytes }); + Ok(answer) +} + +/// Ends an unsubmitted Save As interaction. +/// +/// Hosts call this when leaving the Save As page without saving, and before +/// opening an unrelated Save As. It does not cancel a transfer already sent +/// to the backend. +pub fn cancel_save_as(app: &mut A) { + let cloud = app.cloud_mut(); + cloud.save_as_target = None; + cloud.save_name.clear(); +} + +/// Save As: writes a new document into `folder` under `name`. +/// +/// Acts on `CloudFiles::save_as_target` when the conflict modal's "Save as +/// a copy" set one, so the copy is made from the document that conflicted +/// even if another tab is active by the time this runs. Otherwise, the +/// active document, same as every other ordinary Save As. +pub fn save_as(app: &mut A, folder: &str, name: &str) -> Result { + let kind = app.kind(); + let uid = app.cloud().save_as_target.or_else(|| app.active()).ok_or(format!("no {} open", kind.noun))?; + let name = document_name(name, kind); + if name.is_empty() { + return Err("type a file name".to_owned()); + } + if app.cloud().busy.is_some() { + return Err("a cloud transfer is already running".to_owned()); + } + // A document that does not exist yet has no content type to read. The + // name a person just typed is the whole of what was asked for. + let bytes = app.encode(uid, Destination::new(&name))?; + let size = bytes.len(); + let cloud = app.cloud_mut(); + cloud.status = None; + cloud.busy = Some(Busy::Saving { name: name.clone(), bytes: size }); + let answer = json!({"saving": name, "folder": folder, "bytes": size}); + submit(app, Job::Create { uid, folder: folder.to_owned(), name, bytes }); + Ok(answer) +} + +// ---------------------------------------------------------------- reading the answers + +/// Drains the host's answers and keeps a link or a transfer moving. Called +/// once a frame, before anything is drawn. +pub fn pump(app: &mut A, ctx: &egui::Context) { + if !available(app) { + return; + } + app.cloud_mut().clock = ctx.input(|i| i.time); + // Taken in one pass, then applied. An answer that arrives because of a job + // this frame sent belongs to the next frame. A worker on its own thread + // would have delivered it that way anyway. + let mut arrived = Vec::new(); + while let Ok(event) = app.cloud().events.1.try_recv() { + arrived.push(event); + } + for event in arrived { + apply(app, event); + } + poll_link(app); + // A worker answering is not a local event. Without this the progress line + // would sit frozen until the user moved the mouse. + if app.cloud().busy.is_some() || matches!(app.cloud().link, Some(Link::Starting | Link::Waiting { .. })) { + ctx.request_repaint_after(Duration::from_millis(120)); + } +} + +fn apply(app: &mut A, event: Event) { + let noun = app.kind().noun; + match event { + Event::Account(Ok(account)) => { + let linked = account.provider_linked; + // Who is signed in has changed, so what the provider can do may + // have changed with it. The dialog keeps its first answer, and on a + // cold start that answer is "nobody is signed in". + app.sharing().refresh(); + let cloud = app.cloud_mut(); + cloud.account = Some(account); + cloud.account_fault = None; + if linked { + cloud.link = None; + } else if cloud.link.is_none() { + cloud.link = Some(Link::Offered); + } + } + // No account linked yet is a state with an obvious next step. It is an + // offer to link, and never an error message. + Event::Account(Err(Fault::NotLinked)) => { + let cloud = app.cloud_mut(); + cloud.account_fault = None; + if cloud.link.is_none() { + cloud.link = Some(Link::Offered); + } + } + Event::Account(Err(fault)) => app.cloud_mut().account_fault = Some(fault), + Event::Conversation(Ok(conversation)) => { + let said = fill(app, "Opened in {}", &conversation.name); + app.cloud_mut().status = Some(said); + app.open_conversation(&conversation.url); + } + Event::Conversation(Err(fault)) => { + let text = fault.text(noun); + app.cloud_mut().status = Some(text); + } + Event::Browser { url, handle } => { + app.open_url(&url); + let next_poll = app.cloud().clock + LINK_POLL; + app.cloud_mut().link = Some(Link::Waiting { url, handle, next_poll }); + } + Event::Linked(Ok(true)) => { + // Storage just arrived, so ask what it can do. + app.sharing().refresh(); + let linked = app.tr("Cloud account linked."); + let cloud = app.cloud_mut(); + cloud.link = None; + cloud.status = Some(linked); + cloud.asked_account = false; + submit(app, Job::Account); + browse(app, ""); + app.cloud_mut().shared.loaded = false; + } + // The ordinary answer while the user is still in the browser. + Event::Linked(Ok(false)) | Event::Linked(Err(Fault::NotLinked)) => {} + Event::Linked(Err(fault)) => app.cloud_mut().link = Some(Link::Failed(fault)), + Event::Listed { path, entries } => { + let cloud = app.cloud_mut(); + if path == cloud.mine.path { + cloud.mine.fill(entries); + } + } + Event::Shared(entries) => app.cloud_mut().shared.fill(entries), + Event::Read { entry, into, bytes } => { + app.cloud_mut().busy = None; + match bytes { + Ok(bytes) => opened(app, entry, into, bytes), + Err(Fault::NotLinked) => app.cloud_mut().link = Some(Link::Offered), + Err(fault) => { + let text = format!("{}. {}", fill(app, "{} could not be opened", &entry.name), fault.text(noun)); + app.say(text); + } + } + } + Event::Saved { uid, entry } => { + app.cloud_mut().busy = None; + match entry { + Ok(entry) => { + if app.cloud().save_as_target == Some(uid) { + app.cloud_mut().save_as_target = None; + } + app.mark_saved(uid); + stored(app, uid, entry); + } + // The one failure that must never be retried and never forced. + Err(Fault::Conflict) => { + app.drop_pending(uid); + match app.cloud().origins.get(&uid).cloned() { + Some(origin) => app.cloud_mut().conflict = Some(Conflict { uid, entry: origin.entry }), + None => app.say(Fault::Conflict.text(noun)), + } + } + Err(Fault::NotLinked) => { + app.drop_pending(uid); + app.cloud_mut().link = Some(Link::Offered); + } + Err(fault) => { + app.drop_pending(uid); + let text = format!("{} {}", app.tr(&format!("The {noun} was not saved.")), fault.text(noun)); + app.say(text); + } + } + } + } +} + +/// Bytes arrived. The application opens them. The document then remembers +/// where they came from. +fn opened(app: &mut A, entry: Entry, into: Option, bytes: Vec) { + let name = entry.name.clone(); + match app.open_bytes(&name, bytes) { + Ok(now) => { + if let Some(uid) = now { + app.cloud_mut().origins.insert(uid, Origin { entry }); + } + // A reload closes the document it replaced only once the new one is + // open. A read that fails leaves the user's work where it was. + if let (Some(old), Some(new)) = (into, now) + && old != new + { + let cloud = app.cloud_mut(); + cloud.origins.remove(&old); + app.drop_pending(old); + app.close(old); + } + if now.is_some() { + let said = fill(app, "Opened {} from the cloud.", &name); + app.cloud_mut().status = Some(said); + } + } + Err(reason) => app.say(reason), + } +} + +/// A save landed. The document now belongs to the entry the server returned, at +/// the version it returned. +fn stored(app: &mut A, uid: u64, entry: Entry) { + let name = entry.name.clone(); + let line = fill(app, "Saved {} to the cloud.", &name); + app.toast(fill(app, "Saved {} to the cloud", &name)); + let cloud = app.cloud_mut(); + cloud.conflict = None; + cloud.status = Some(line); + cloud.origins.insert(uid, Origin { entry }); +} + +/// Keeps asking whether the user has finished linking in their browser. +fn poll_link(app: &mut A) { + let now = app.cloud().clock; + let handle = { + let Some(Link::Waiting { handle: Some(handle), next_poll, .. }) = &mut app.cloud_mut().link else { return }; + if now < *next_poll { + return; + } + *next_poll = now + LINK_POLL; + handle.clone() + }; + submit(app, Job::LinkPoll(handle)); +} + +// ---------------------------------------------------------------- reporting + +/// The whole of the cloud state, for a control channel and for tests. +pub fn report(app: &A) -> Json { + let kind = app.kind(); + let cloud = app.cloud(); + let account = cloud.account.as_ref().map(|a| { + json!({ + "display": a.display, + "providerLinked": a.provider_linked, + "capabilities": a.capabilities.iter().map(|c| serde_json::to_value(c).unwrap_or_default()).collect::>(), + }) + }); + let came_from = origin(app) + .map(|o| json!({"id": o.entry.id, "room": o.entry.room, "name": o.entry.name, "etag": o.entry.etag, "writable": o.entry.writable})); + json!({ + "available": cloud.available(), + "account": account, + "accountError": cloud.account_fault.as_ref().map(Fault::code), + "folder": cloud.mine.path, + "entries": cloud.mine.entries.iter().map(|e| e.name.clone()).collect::>(), + "openable": cloud.mine.entries.iter().filter(|e| opens(e, kind)).map(|e| e.name.clone()).collect::>(), + "shared": cloud.shared.entries.iter().map(|e| json!({"name": e.name, "sharedBy": e.shared_by, "writable": e.writable, "openable": opens(e, kind)})).collect::>(), + "busy": cloud.busy.as_ref().map(Busy::text), + "link": match &cloud.link { + None => Json::Null, + Some(Link::Offered) => json!("offered"), + Some(Link::Starting) => json!("starting"), + Some(Link::Waiting { url, .. }) => json!({"waiting": url}), + Some(Link::Failed(fault)) => json!({"failed": fault.code()}), + }, + "conflict": cloud.conflict.as_ref().map(|c| json!({"name": c.entry.name})), + "origin": came_from, + "status": cloud.status, + "guest": cloud.guest.as_ref().map(|g| json!({"recipient": g.recipient, "readOnly": g.read_only})), + }) +} + +// ---------------------------------------------------------------- shared drawing + +/// Bytes as a person reads them. +pub fn size_text(bytes: Option) -> String { + let Some(bytes) = bytes else { return String::new() }; + const UNITS: [&str; 4] = ["bytes", "KB", "MB", "GB"]; + let mut size = bytes as f64; + let mut unit = 0; + while size >= 1024.0 && unit + 1 < UNITS.len() { + size /= 1024.0; + unit += 1; + } + match UNITS.get(unit) { + Some(name) if unit > 0 => format!("{size:.1} {name}"), + _ => format!("{bytes} bytes"), + } +} + +fn dim(ui: &mut Ui, style: &CloudStyle, text: &str) { + ui.label(RichText::new(text).font(egui::FontId::new(12.5, style.family.clone())).color(style.dim)); +} + +/// A bordered column with a heading. This is how the two Open sources sit side +/// by side. +fn column(ui: &mut Ui, style: &CloudStyle, heading: &str, body: impl FnOnce(&mut Ui)) { + egui::Frame::NONE.fill(style.surface).stroke(Stroke::new(1.0, style.border)).corner_radius(6.0).inner_margin(10).show(ui, |ui| { + ui.label(RichText::new(heading).font(egui::FontId::new(13.0, style.bold.clone())).color(style.text)); + ui.add_space(6.0); + egui::ScrollArea::vertical().id_salt(heading.to_owned()).max_height(300.0).auto_shrink([false, false]).show(ui, body); + }); +} + +/// One row in a file list, with a second line for the detail that matters on +/// that side of the page (a size for your own files, who shared it for +/// somebody else's). +fn entry_row(app: &A, ui: &mut Ui, entry: &Entry, detail: &str, reserve: f32) -> egui::Response { + let style = app.style(ui); + let width = (ui.available_width() - reserve).max(60.0); + let (rect, resp) = ui.allocate_exact_size(vec2(width, 40.0), Sense::click()); + let label = entry.name.clone(); + resp.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, &label)); + let p = ui.painter(); + if resp.hovered() { + p.rect_filled(rect, 4.0, style.hover); + } + app.paint_icon(p, Rect::from_center_size(pos2(rect.left() + 18.0, rect.center().y), vec2(18.0, 18.0)), entry.kind, style.text); + let (name_y, detail_y) = if detail.is_empty() { (rect.center().y, rect.center().y) } else { (rect.center().y - 8.0, rect.center().y + 9.0) }; + p.text(pos2(rect.left() + 38.0, name_y), Align2::LEFT_CENTER, &entry.name, egui::FontId::new(13.0, style.family.clone()), style.text); + if !detail.is_empty() { + p.text(pos2(rect.left() + 38.0, detail_y), Align2::LEFT_CENTER, detail, egui::FontId::new(11.0, style.family.clone()), style.dim); + } + resp +} diff --git a/crates/cloud-ui/src/cloud/pages.rs b/crates/cloud-ui/src/cloud/pages.rs new file mode 100644 index 000000000..86e71d1c8 --- /dev/null +++ b/crates/cloud-ui/src/cloud/pages.rs @@ -0,0 +1,519 @@ +//! The Backstage pages: File › Open and File › Save As, and the modal a +//! refused save puts up. +//! +//! Every side of a page is drawn only where the service reported the +//! capability behind it. A list under a heading the provider cannot fill reads +//! to a user as a broken window, so the heading goes too. + +use craft_cloud::{Capability, Entry, EntryKind}; +use egui::{RichText, Ui}; + +use super::{ + CloudApp, Link, Source, browse, column, converse, dim, document_name, entry_row, fill, link, load_shared, open_entry, opens, parent_of, save_as, + size_text, start, stem_of, +}; + +/// The character a label ends with when choosing it opens a dialog. +const ELLIPSIS: &str = "\u{2026}"; + +/// What an overflow menu asked for, deferred until the list is no longer being +/// drawn. Opening a dialog while borrowing the list is not possible. +enum Act { + Share(Entry), + Talk(Entry), +} + +/// The account line, or the reason there is nothing to show yet. +fn header(app: &mut A, ui: &mut Ui) { + let style = app.style(ui); + let mut retry = false; + match (&app.cloud().account, &app.cloud().account_fault) { + (_, Some(fault)) => { + let text = fault.text(app.kind().noun); + let again = app.tr("Try again"); + ui.horizontal(|ui| { + dim(ui, &style, &text); + if ui.button(again).clicked() { + retry = true; + } + }); + } + (Some(account), None) => { + let line = if account.display.is_empty() { app.tr("Signed in") } else { account.display.clone() }; + dim(ui, &style, &line); + } + (None, None) => { + let waiting = app.tr("Connecting to your cloud account…"); + dim(ui, &style, &waiting); + } + } + if retry { + let cloud = app.cloud_mut(); + cloud.account_fault = None; + cloud.asked_account = false; + start(app); + } +} + +/// The offer to link an account, and the wait while the browser is open. +/// Returns true when it drew, because there is nothing else to show until an +/// account exists. +/// +/// None of this is an error. The whole state means one thing: there is no +/// account yet, and linking one is a button away. +fn link_panel(app: &mut A, ui: &mut Ui) -> bool { + let Some(state) = app.cloud().link.clone() else { return false }; + let style = app.style(ui); + let noun = app.kind().noun; + let mut begin = false; + let mut cancel = false; + let mut browse_to: Option = None; + let words = LinkWords { + none_yet: app.tr("No cloud account is linked yet."), + why: app.tr(&format!("Link one to open and save {noun}s in your cloud storage.")), + link_one: app.tr("Link a cloud account"), + starting: app.tr("Starting…"), + finish: app.tr("Finish linking in your browser."), + waiting: app.tr("Waiting for your browser…"), + open_in_browser: app.tr("Open in browser"), + copy_link: app.tr("Copy link"), + cancel: app.tr("Cancel"), + again: app.tr("Try again"), + }; + egui::Frame::NONE.fill(style.soft).corner_radius(6.0).inner_margin(12).show(ui, |ui| match state { + Link::Offered => { + ui.label(RichText::new(&words.none_yet).font(egui::FontId::new(13.0, style.bold.clone())).color(style.text)); + dim(ui, &style, &words.why); + ui.add_space(8.0); + begin = ui.button(&words.link_one).clicked(); + } + Link::Starting => { + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(14.0)); + dim(ui, &style, &words.starting); + }); + } + Link::Waiting { url, .. } => { + ui.label(RichText::new(&words.finish).font(egui::FontId::new(13.0, style.bold.clone())).color(style.text)); + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(14.0)); + dim(ui, &style, &words.waiting); + }); + ui.add_space(6.0); + // A link alone is not enough. When the browser cannot be opened, + // or opens the wrong thing, the only way out is carrying the + // address across by hand, and a label cannot be selected. + ui.horizontal(|ui| { + if ui.button(&words.open_in_browser).clicked() { + browse_to = Some(url.clone()); + } + if ui.button(&words.copy_link).clicked() { + ui.ctx().copy_text(url.clone()); + } + }); + ui.add_space(4.0); + if ui.link(&url).clicked() { + browse_to = Some(url.clone()); + } + ui.add_space(8.0); + cancel = ui.button(&words.cancel).clicked(); + } + Link::Failed(fault) => { + ui.label(RichText::new(fault.text(noun)).font(egui::FontId::new(13.0, style.family.clone())).color(style.text)); + ui.add_space(8.0); + begin = ui.button(&words.again).clicked(); + } + }); + if let Some(url) = browse_to { + app.open_url(&url); + } + if begin { + link(app); + } else if cancel { + app.cloud_mut().link = Some(Link::Offered); + } + true +} + +/// The panel's strings, read before it is drawn. The application is borrowed +/// mutably inside the frame, so nothing can be asked of it there. +struct LinkWords { + none_yet: String, + why: String, + link_one: String, + starting: String, + finish: String, + waiting: String, + open_in_browser: String, + copy_link: String, + cancel: String, + again: String, +} + +/// The progress line for a read or a write in flight. +pub fn progress(app: &A, ui: &mut Ui) { + let Some(busy) = app.cloud().busy.clone() else { return }; + let style = app.style(ui); + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(15.0)); + ui.label(RichText::new(busy.text()).font(egui::FontId::new(12.5, style.family.clone())).color(style.text)); + }); +} + +/// The `…` beside a document, and what a person chose from it. +/// +/// Only the actions the provider actually offers appear. A greyed-out item says +/// the action exists and is not possible right now. An absent one says this +/// provider does not do that at all, and those are different facts. +fn row_actions(app: &A, ui: &mut Ui, entry: &Entry) -> Option { + let can = |c: Capability| app.cloud().account.as_ref().is_some_and(|a| a.can(c)); + let mut items = vec![crate::menu::MenuItem::new("open", app.tr("Open"))]; + if can(Capability::Sharing) { + items.push( + crate::menu::MenuItem::new("share", format!("{}{}", app.tr("Share"), ELLIPSIS)) + .detail(app.tr("See who this is shared with, and invite somebody")) + .separated(), + ); + } + if can(Capability::Conversation) { + items.push(crate::menu::MenuItem::new("talk", app.tr("Work together")).detail(app.tr("Open a conversation about this document"))); + } + let labels = crate::menu::MenuLabels { more: app.tr("More options"), ..Default::default() }; + // Salted by the handle. Two rows drawing the same control need two menus, + // and the handle is the one thing that differs between them. + ui.push_id(entry.id.clone(), |ui| crate::menu::overflow(ui, &items, &labels)).inner +} + +/// File › Open, the cloud part. Your own files sit on one side and what other +/// people shared with you sits on the other. +pub fn open_page(app: &mut A, ui: &mut Ui) { + start(app); + header(app, ui); + ui.add_space(8.0); + if link_panel(app, ui) { + return; + } + progress(app, ui); + // Hidden where the provider has no incoming shares at all. An empty list + // under that heading would read as a broken feature. + let shared_offered = app.cloud().account.as_ref().is_some_and(|a| a.can(Capability::SharedWithMe)); + if shared_offered && !app.cloud().shared.loaded && !app.cloud().shared.loading { + load_shared(app); + } + let mut pick: Option<(Entry, Source)> = None; + let mut go: Option = None; + let mut act: Option = None; + if shared_offered { + ui.columns(2, |columns| { + if let Some(ui) = columns.get_mut(0) { + my_files(app, ui, &mut pick, &mut go, &mut act); + } + if let Some(ui) = columns.get_mut(1) { + shared_files(app, ui, &mut pick, &mut act); + } + }); + } else { + my_files(app, ui, &mut pick, &mut go, &mut act); + } + match act { + // Sharing a document in the list, which is not the one that happens to + // be open. The dialog is told which. + Some(Act::Share(entry)) => app.sharing().open(entry.id.clone(), entry.name.clone()), + Some(Act::Talk(entry)) => converse(app, entry.id.clone()), + None => {} + } + if let Some(path) = go { + browse(app, &path); + } else if let Some((entry, source)) = pick { + app.cloud_mut().source = source; + open_entry(app, entry, None); + } + if let Some(status) = app.cloud().status.clone() { + let style = app.style(ui); + ui.add_space(10.0); + dim(ui, &style, &status); + } +} + +/// Your own files: where you are, a way up, then the folders and the documents +/// this application can open. +fn my_files(app: &mut A, ui: &mut Ui, pick: &mut Option<(Entry, Source)>, go: &mut Option, act: &mut Option) { + let style = app.style(ui); + let kind = app.kind(); + let folder = app.cloud().mine.clone(); + let heading = app.tr("My files"); + let (home, up, loading) = (app.tr("Home"), app.tr("Up"), app.tr("Loading…")); + let nothing = app.tr(&format!("Nothing here that {} can open.", app.app_name())); + column(ui, &style, &heading, |ui| { + let here = if folder.path.is_empty() { home } else { folder.path.clone() }; + ui.horizontal(|ui| { + if let Some(parent) = parent_of(&folder.path) + && ui.button(&up).clicked() + { + *go = Some(parent); + } + dim(ui, &style, &here); + }); + ui.add_space(4.0); + if folder.loading { + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(14.0)); + dim(ui, &style, &loading); + }); + return; + } + if let Some(fault) = &folder.error { + dim(ui, &style, &fault.text(kind.noun)); + return; + } + let mut shown = 0; + for entry in &folder.entries { + let is_folder = entry.kind == EntryKind::Folder; + if !is_folder && !opens(entry, kind) { + continue; + } + shown += 1; + let detail = if is_folder { String::new() } else { size_text(entry.size) }; + // A folder has nothing behind an ellipsis. Opening it is the only + // thing to do with one here. + let reserve = if is_folder { 0.0 } else { 26.0 }; + let (row, chose) = ui + .horizontal(|ui| { + let row = entry_row(app, ui, entry, &detail, reserve).clicked(); + let chose = if is_folder { None } else { row_actions(app, ui, entry) }; + (row, chose) + }) + .inner; + match chose.as_deref() { + Some("share") => *act = Some(Act::Share(entry.clone())), + Some("talk") => *act = Some(Act::Talk(entry.clone())), + Some("open") => *pick = Some((entry.clone(), Source::Mine)), + _ if row => { + if is_folder { + *go = Some(entry.path.clone()); + } else { + *pick = Some((entry.clone(), Source::Mine)); + } + } + _ => {} + } + } + if shown == 0 && folder.loaded { + dim(ui, &style, ¬hing); + } + }); +} + +/// What other people shared with you. One flat list, because an incoming share +/// has no folder of yours to sit in. Each row says who shared it. +fn shared_files(app: &mut A, ui: &mut Ui, pick: &mut Option<(Entry, Source)>, act: &mut Option) { + let style = app.style(ui); + let kind = app.kind(); + let shared = app.cloud().shared.clone(); + let heading = app.tr("Shared with me"); + let (loading, with_you, read_only) = (app.tr("Loading…"), app.tr("Shared with you"), app.tr("read-only")); + let nobody = app.tr(&format!("Nobody has shared a {} with you.", kind.noun)); + column(ui, &style, &heading, |ui| { + if shared.loading { + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(14.0)); + dim(ui, &style, &loading); + }); + return; + } + if let Some(fault) = &shared.error { + dim(ui, &style, &fault.text(kind.noun)); + return; + } + let mut shown = 0; + for entry in shared.entries.iter().filter(|e| opens(e, kind)) { + shown += 1; + let who = entry.shared_by.clone().unwrap_or_else(|| with_you.clone()); + let detail = if entry.writable { who } else { format!("{who} ({read_only})") }; + let (row, chose) = ui + .horizontal(|ui| { + let row = entry_row(app, ui, entry, &detail, 26.0).clicked(); + (row, row_actions(app, ui, entry)) + }) + .inner; + match chose.as_deref() { + Some("share") => *act = Some(Act::Share(entry.clone())), + Some("talk") => *act = Some(Act::Talk(entry.clone())), + _ if row || chose.is_some() => *pick = Some((entry.clone(), Source::Shared)), + _ => {} + } + } + if shown == 0 && shared.loaded { + dim(ui, &style, &nobody); + } + }); +} + +/// File › Save As, the cloud destination. Pick a folder, name the file, save. +/// Returns true when a save started, so a Backstage view can return to the +/// document. Hosts call [`super::cancel_save_as`] when leaving without saving, +/// or before opening this page for an ordinary File › Save As, to discard any +/// abandoned conflict-copy target and suggested name. +pub fn save_page(app: &mut A, ui: &mut Ui) -> bool { + let style = app.style(ui); + let kind = app.kind(); + start(app); + // The destination above already names the account. This line is here to + // say when something is wrong with it. + if app.cloud().account.is_none() || app.cloud().account_fault.is_some() { + header(app, ui); + ui.add_space(8.0); + } + if link_panel(app, ui) { + return false; + } + progress(app, ui); + if app.cloud().save_name.is_empty() { + let suggested = app.active().map(|uid| app.title(uid)).unwrap_or_default(); + app.cloud_mut().save_name = document_name(&suggested, kind); + } + let folder = app.cloud().mine.clone(); + let heading = app.tr("Folder"); + let (home, up, loading) = (app.tr("Home"), app.tr("Up"), app.tr("Loading…")); + let only_folder = app.tr(&format!("No folders here. The {} saves in this one.", kind.noun)); + let mut go: Option = None; + column(ui, &style, &heading, |ui| { + let here = if folder.path.is_empty() { home } else { folder.path.clone() }; + ui.horizontal(|ui| { + if let Some(parent) = parent_of(&folder.path) + && ui.button(&up).clicked() + { + go = Some(parent); + } + dim(ui, &style, &here); + }); + ui.add_space(4.0); + if folder.loading { + ui.horizontal(|ui| { + ui.add(egui::Spinner::new().size(14.0)); + dim(ui, &style, &loading); + }); + return; + } + if let Some(fault) = &folder.error { + dim(ui, &style, &fault.text(kind.noun)); + return; + } + let mut folders = 0; + for entry in folder.entries.iter().filter(|e| e.kind == EntryKind::Folder) { + folders += 1; + if entry_row(app, ui, entry, "", 0.0).clicked() { + go = Some(entry.path.clone()); + } + } + if folders == 0 && folder.loaded { + dim(ui, &style, &only_folder); + } + }); + if let Some(path) = go { + browse(app, &path); + } + ui.add_space(12.0); + let (file_name, save_label) = (app.tr("File name"), app.tr("Save to the cloud")); + let mut asked = false; + ui.horizontal(|ui| { + ui.label(file_name); + let typing = ui.add(egui::TextEdit::singleline(&mut app.cloud_mut().save_name).desired_width(280.0)); + asked = typing.lost_focus() && ui.input(|i| i.key_pressed(egui::Key::Enter)); + }); + ui.add_space(10.0); + let ready = app.cloud().busy.is_none() && !document_name(&app.cloud().save_name, kind).is_empty(); + if ui.add_enabled(ready, egui::Button::new(save_label)).clicked() { + asked = true; + } + if let Some(note) = app.save_note() { + ui.add_space(8.0); + dim(ui, &style, ¬e); + } + // A provider with no conditional writes cannot refuse one, so a save here + // can land on top of somebody else's. Said plainly, because the user is the + // only one who can decide whether that matters. + if app.cloud().account.as_ref().is_some_and(|a| !a.can(Capability::Etags)) { + let warning = app.tr("This cloud account cannot detect a save that would overwrite somebody else's changes."); + ui.add_space(4.0); + dim(ui, &style, &warning); + } + if asked && ready && app.ready_to_save() { + let (folder, name) = (app.cloud().mine.path.clone(), app.cloud().save_name.clone()); + match save_as(app, &folder, &name) { + Ok(_) => return true, + Err(error) => app.say(error), + } + } + false +} + +/// A save refused because the stored copy had moved on. +/// +/// Three ways out, and none of them throws anything away without saying so. +/// Reloading is the one a user usually wants, so it comes first. The text says +/// plainly that it discards their edits. +pub fn conflict_modal(app: &mut A, ctx: &egui::Context) { + let Some(conflict) = app.cloud().conflict.clone() else { return }; + let noun = app.kind().noun; + let words = ConflictWords { + title: app.tr(&format!("This {noun} was not saved")), + what: fill( + app, + "Somebody else saved {} while you were editing it. Nothing was written: saving now would overwrite their work.", + &conflict.entry.name, + ), + yours: app.tr("Your own changes are still open here. Reloading replaces them with the stored copy."), + reload: app.tr("Reload from the cloud"), + copy: app.tr(&format!("Save as a copy{ELLIPSIS}")), + keep: app.tr("Keep editing"), + }; + let mut reload = false; + let mut copy = false; + let mut dismiss = false; + egui::Modal::new(egui::Id::unique("craft-ui/cloud/conflict")).show(ctx, |ui| { + let style = app.style(ui); + ui.set_width(430.0); + ui.label(RichText::new(&words.title).font(egui::FontId::new(15.0, style.bold.clone()))); + ui.add_space(8.0); + ui.add(egui::Label::new(&words.what).wrap()); + ui.add_space(6.0); + ui.add(egui::Label::new(&words.yours).wrap()); + ui.add_space(12.0); + ui.horizontal(|ui| { + reload = ui.button(&words.reload).clicked(); + copy = ui.button(&words.copy).clicked(); + dismiss = ui.button(&words.keep).clicked(); + }); + }); + if reload { + // Reads the conflicted document back, never whichever tab happens to + // be active. `reload_active` acts on the active document, which is + // right for a host's own Reload command but wrong here: the window + // that triggered this modal may have moved on to another document + // while the refused save was on the wire. + app.cloud_mut().conflict = None; + open_entry(app, conflict.entry, Some(conflict.uid)); + } else if copy { + let name = document_name(&format!("{} (copy)", stem_of(&conflict.entry.name)), app.kind()); + let cloud = app.cloud_mut(); + cloud.conflict = None; + cloud.save_name = name; + // Save As must encode the conflicted document too, not whatever is + // active once the user actually clicks Save on that page. + cloud.save_as_target = Some(conflict.uid); + app.go_to_save_as(); + } else if dismiss { + app.cloud_mut().conflict = None; + } +} + +/// The modal's strings, read before it is drawn. +struct ConflictWords { + title: String, + what: String, + yours: String, + reload: String, + copy: String, + keep: String, +} diff --git a/crates/cloud-ui/src/cloud/tests.rs b/crates/cloud-ui/src/cloud/tests.rs new file mode 100644 index 000000000..875612144 --- /dev/null +++ b/crates/cloud-ui/src/cloud/tests.rs @@ -0,0 +1,573 @@ +//! The pages driven by an application that holds no documents. +//! +//! The point of these is the seam. A fake application answers every question +//! [`CloudApp`] asks and records what it was told to do, so what crosses the +//! boundary is visible without a spreadsheet, a service or a window. + +use std::sync::{Arc, Mutex}; + +use craft_cloud::{Capability, Entry, EntryKind}; + +use super::*; + +/// Everything the fake application was asked to do. +#[derive(Default)] +struct Did { + opened: Vec, + closed: Vec, + encoded: Vec, + /// The name each encode was asked for, which is where the bytes go. + encoded_as: Vec, + /// The content type beside it, where the provider gave one. + encoded_mime: Vec>, + marked_saved: Vec, + dropped: Vec, + said: Vec, + toasted: Vec, + urls: Vec, + conversations: Vec, + went_to_save_as: usize, +} + +const NOTES: DocumentKind = + DocumentKind { extensions: &["note", "txt"], mimes: &["text/plain", "application/x-note"], noun: "note", default_extension: "note" }; + +struct Notebook { + cloud: CloudFiles, + share: crate::share::ShareDialog, + presence: crate::presence::PresenceBar, + /// The document in the window, and what it is called. + open: Option<(u64, String)>, + /// What the next `open_bytes` answers with. + opens_as: Result, String>, + did: Arc>, +} + +impl Notebook { + fn new() -> Notebook { + Notebook { + cloud: CloudFiles::new(), + share: crate::share::ShareDialog::new(), + presence: crate::presence::PresenceBar::new(), + open: Some((1, "Untitled")).map(|(uid, name)| (uid, name.to_owned())), + opens_as: Ok(Some(1)), + did: Arc::new(Mutex::new(Did::default())), + } + } + + fn did(&self) -> std::sync::MutexGuard<'_, Did> { + self.did.lock().unwrap() + } +} + +impl CloudApp for Notebook { + fn cloud(&self) -> &CloudFiles { + &self.cloud + } + + fn cloud_mut(&mut self) -> &mut CloudFiles { + &mut self.cloud + } + + fn kind(&self) -> DocumentKind { + NOTES + } + + fn active(&self) -> Option { + self.open.as_ref().map(|(uid, _)| *uid) + } + + fn title(&self, _uid: u64) -> String { + self.open.as_ref().map(|(_, name)| name.clone()).unwrap_or_default() + } + + fn open_bytes(&mut self, name: &str, _bytes: Vec) -> Result, String> { + self.did().opened.push(name.to_owned()); + self.opens_as.clone() + } + + fn encode(&mut self, uid: u64, into: Destination<'_>) -> Result, String> { + self.did().encoded.push(uid); + self.did().encoded_as.push(into.name.to_owned()); + self.did().encoded_mime.push(into.mime.map(str::to_owned)); + Ok(b"a note".to_vec()) + } + + fn close(&mut self, uid: u64) { + self.did().closed.push(uid); + } + + fn mark_saved(&mut self, uid: u64) { + self.did().marked_saved.push(uid); + } + + fn drop_pending(&mut self, uid: u64) { + self.did().dropped.push(uid); + } + + fn sharing(&mut self) -> &mut crate::share::ShareDialog { + &mut self.share + } + + fn presence(&mut self) -> &mut crate::presence::PresenceBar { + &mut self.presence + } + + fn paint_icon(&self, _painter: &egui::Painter, _rect: egui::Rect, _kind: EntryKind, _colour: egui::Color32) {} + + fn open_url(&self, url: &str) { + self.did.lock().unwrap().urls.push(url.to_owned()); + } + + fn open_conversation(&self, url: &str) { + self.did.lock().unwrap().conversations.push(url.to_owned()); + } + + fn say(&mut self, text: String) { + self.did().said.push(text); + } + + fn toast(&mut self, text: String) { + self.did().toasted.push(text); + } + + fn go_to_save_as(&mut self) { + self.did().went_to_save_as += 1; + } + + fn app_name(&self) -> &str { + "Notes" + } +} + +/// A service that answers on the calling thread, so a job submitted during a +/// test is answered before the next line. +struct Service(Arc>>); + +impl CloudBackend for Service { + fn submit(&self, job: Job, post: Post) { + let answer = match &job { + Job::Account | Job::SignIn => Some(Event::Account(Ok(Account { + display: "Ada Lovelace".to_owned(), + capabilities: vec![Capability::Files, Capability::Etags], + provider_linked: true, + }))), + Job::List(path) => Some(Event::Listed { path: path.clone(), entries: Ok(vec![file("/Minutes.note"), folder("/Archive")]) }), + Job::Read { entry, into } => Some(Event::Read { entry: entry.clone(), into: *into, bytes: Ok(b"a note".to_vec()) }), + Job::Write { uid, entry, .. } => { + let mut stored = entry.clone(); + stored.etag = Some("v2".to_owned()); + Some(Event::Saved { uid: *uid, entry: Ok(stored) }) + } + _ => None, + }; + self.0.lock().unwrap().push(job); + if let Some(event) = answer { + post.send(event); + } + } +} + +fn file(path: &str) -> Entry { + Entry { + id: path.to_owned(), + room: format!("room:{path}"), + name: path.rsplit('/').next().unwrap_or(path).to_owned(), + path: path.to_owned(), + kind: EntryKind::File, + size: Some(2048), + modified: None, + mime: None, + etag: Some("v1".to_owned()), + writable: true, + shared_by: None, + } +} + +fn folder(path: &str) -> Entry { + Entry { kind: EntryKind::Folder, size: None, etag: None, ..file(path) } +} + +/// One frame's worth of draining, with no window. +fn pumped(app: &mut Notebook, ctx: &egui::Context) { + ctx.begin_pass(Default::default()); + pump(app, ctx); + // Nothing is painted here, so the pass's textures go nowhere. egui insists + // they are accounted for rather than dropped on the floor. + ctx.end_pass().textures_delta.clear(); +} + +fn wired() -> (Notebook, Arc>>, egui::Context) { + let mut app = Notebook::new(); + let jobs = Arc::new(Mutex::new(Vec::new())); + app.cloud.connect(Service(jobs.clone())); + (app, jobs, egui::Context::default()) +} + +#[test] +fn nothing_is_offered_until_a_service_is_wired() { + let app = Notebook::new(); + assert!(!available(&app), "a build with no service offers nothing cloud-shaped"); + assert_eq!(report(&app)["available"], false); +} + +#[test] +fn the_account_is_asked_for_once_per_run() { + let (mut app, jobs, ctx) = wired(); + start(&mut app); + start(&mut app); + let asked = jobs.lock().unwrap().iter().filter(|j| matches!(j, Job::Account)).count(); + assert_eq!(asked, 1, "a frame that asks again would ask on every frame"); + pumped(&mut app, &ctx); + assert_eq!(report(&app)["account"]["display"], "Ada Lovelace"); +} + +#[test] +fn only_the_documents_this_application_opens_are_offered() { + let (mut app, _jobs, ctx) = wired(); + start(&mut app); + pumped(&mut app, &ctx); + let listing = report(&app); + assert_eq!(listing["entries"], serde_json::json!(["Minutes.note", "Archive"])); + assert_eq!(listing["openable"], serde_json::json!(["Minutes.note"]), "a folder is not something to open"); +} + +#[test] +fn a_content_type_opens_a_document_with_no_extension() { + let mut exported = file("/exported"); + exported.mime = Some("text/plain; charset=utf-8".to_owned()); + assert!(opens(&exported, NOTES), "a provider that gives no extension still says what the bytes are"); + let mut picture = file("/holiday"); + picture.mime = Some("image/png".to_owned()); + assert!(!opens(&picture, NOTES)); + assert!(!opens(&folder("/Archive"), NOTES), "a folder opens nothing"); +} + +#[test] +fn a_typed_name_becomes_a_file_name_of_this_applications_own_kind() { + assert_eq!(document_name(" Minutes ", NOTES), "Minutes.note"); + assert_eq!(document_name("Minutes.txt", NOTES), "Minutes.txt", "an extension this application opens is kept"); + assert_eq!(document_name("Minutes.v2", NOTES), "Minutes.v2.note", "an unknown suffix is part of the name"); + assert_eq!(document_name("/a/b/Minutes", NOTES), "Minutes.note", "a pasted path cannot become a folder"); + assert_eq!(document_name(" ", NOTES), ""); +} + +#[test] +fn walking_up_from_the_root_has_nowhere_to_go() { + assert_eq!(parent_of(""), None); + assert_eq!(parent_of("/Archive"), Some(String::new())); + assert_eq!(parent_of("/Archive/2026"), Some("/Archive".to_owned())); +} + +#[test] +fn opening_hands_the_bytes_to_the_application_and_remembers_the_entry() { + let (mut app, _jobs, ctx) = wired(); + start(&mut app); + pumped(&mut app, &ctx); + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + assert_eq!(app.did().opened, vec!["Minutes.note".to_owned()], "the application alone turns bytes into a document"); + let origin = report(&app)["origin"].clone(); + assert_eq!(origin["id"], "/Minutes.note", "the opaque handle is kept for the save"); + assert_eq!(origin["etag"], "v1", "so is the version it was read at"); + assert_eq!(origin["room"], "room:/Minutes.note", "and the collaboration identity, which is not the handle"); +} + +#[test] +fn a_reload_closes_the_document_it_replaced_only_once_the_new_one_is_open() { + let (mut app, _jobs, ctx) = wired(); + app.opens_as = Ok(Some(2)); + open_entry(&mut app, file("/Minutes.note"), Some(1)); + pumped(&mut app, &ctx); + assert_eq!(app.did().closed, vec![1], "the one it replaced is gone"); + assert_eq!(app.did().dropped, vec![1], "and so is whatever was recorded about saving it"); + + // A read the application could not use leaves the user's work where it was. + let (mut app, _jobs, ctx) = wired(); + app.opens_as = Err("these bytes are not a note".to_owned()); + open_entry(&mut app, file("/Minutes.note"), Some(1)); + pumped(&mut app, &ctx); + assert!(app.did().closed.is_empty(), "nothing was closed, because nothing opened"); + assert_eq!(app.did().said, vec!["these bytes are not a note".to_owned()]); +} + +#[test] +fn a_document_the_application_took_elsewhere_is_not_announced() { + let (mut app, _jobs, ctx) = wired(); + // What an application answers while it prompts for a password. + app.opens_as = Ok(None); + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + assert_eq!(report(&app)["status"], serde_json::Value::Null); + assert_eq!(report(&app)["origin"], serde_json::Value::Null, "nothing came from the cloud yet"); +} + +#[test] +fn a_save_goes_out_under_the_version_the_document_was_read_at() { + let (mut app, jobs, ctx) = wired(); + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + save(&mut app).unwrap(); + assert_eq!(app.did().encoded, vec![1], "the application alone turns a document into bytes"); + assert_eq!(app.did().encoded_as, vec!["Minutes.note".to_owned()], "the bytes are asked for under the name they are going to"); + let condition = jobs.lock().unwrap().iter().find_map(|j| match j { + Job::Write { entry, .. } => Some(entry.etag.clone()), + _ => None, + }); + assert_eq!(condition, Some(Some("v1".to_owned())), "the etag it was read at is the condition"); + pumped(&mut app, &ctx); + assert_eq!(app.did().marked_saved, vec![1], "the version that reached the service is the saved one"); + assert_eq!(report(&app)["origin"]["etag"], "v2", "and the document moves on to the version the service returned"); +} + +#[test] +fn a_read_only_share_is_never_saved_over() { + let (mut app, _jobs, ctx) = wired(); + let mut theirs = file("/Team.note"); + theirs.writable = false; + open_entry(&mut app, theirs, None); + pumped(&mut app, &ctx); + assert!(!has_target(&app), "Save has nowhere of its own to go"); + let refused = save(&mut app).unwrap_err(); + assert!(refused.contains("reading only"), "and saying why names the fix: {refused}"); +} + +#[test] +fn a_refused_save_is_put_to_the_user_and_never_retried() { + let (mut app, jobs, ctx) = wired(); + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + jobs.lock().unwrap().clear(); + // What a service answers when somebody else saved first. + app.cloud.events.0.send(Event::Saved { uid: 1, entry: Err(Fault::Conflict) }).unwrap(); + pumped(&mut app, &ctx); + assert_eq!(report(&app)["conflict"]["name"], "Minutes.note", "the user is told, and asked what to do"); + assert_eq!(app.did().dropped, vec![1], "the version that did not land is forgotten"); + assert!(jobs.lock().unwrap().is_empty(), "nothing went out again on its own"); +} + +#[test] +fn no_account_yet_is_an_offer_to_link_and_never_an_error() { + let (mut app, _jobs, ctx) = wired(); + app.cloud.events.0.send(Event::Account(Err(Fault::NotLinked))).unwrap(); + pumped(&mut app, &ctx); + assert_eq!(report(&app)["link"], "offered"); + assert_eq!(report(&app)["accountError"], serde_json::Value::Null, "not having linked an account yet is not a failure"); + assert!(app.did().said.is_empty()); +} + +#[test] +fn a_browser_round_trip_is_polled_until_the_user_is_done() { + let (mut app, jobs, ctx) = wired(); + app.cloud.events.0.send(Event::Browser { url: "https://cloud.example/link/abc".to_owned(), handle: Some("abc".to_owned()) }).unwrap(); + pumped(&mut app, &ctx); + assert_eq!(app.did().urls, vec!["https://cloud.example/link/abc".to_owned()], "the browser is opened for them"); + assert_eq!(report(&app)["link"]["waiting"], "https://cloud.example/link/abc"); + + // The wait is not polled again until it is due. + jobs.lock().unwrap().clear(); + pumped(&mut app, &ctx); + assert!(jobs.lock().unwrap().iter().all(|j| !matches!(j, Job::LinkPoll(_))), "a poll every frame would be a poll every sixteen milliseconds"); + + if let Some(Link::Waiting { next_poll, .. }) = &mut app.cloud.link { + *next_poll = 0.0; + } + pumped(&mut app, &ctx); + assert!(jobs.lock().unwrap().iter().any(|j| matches!(j, Job::LinkPoll(_)))); +} + +#[test] +fn what_a_person_reads_is_about_their_own_kind_of_document() { + let app = Notebook::new(); + assert_eq!(Fault::Conflict.text(app.kind().noun), "Somebody else saved this note while you were editing it."); + assert_eq!(Fault::Conflict.code(), "conflict", "and the control channel reads the same fact as a word"); +} + +#[test] +fn working_together_needs_somewhere_for_the_room_to_be_keyed_on() { + let (mut app, jobs, ctx) = wired(); + app.cloud.account = Some(Account { display: "Ada".to_owned(), capabilities: vec![Capability::Conversation], provider_linked: true }); + assert!(can_converse(&app)); + // A document that has never been in the cloud has no handle. + work_together(&mut app); + assert_eq!(report(&app)["status"], "Save this note to the cloud first"); + assert!(jobs.lock().unwrap().iter().all(|j| !matches!(j, Job::Conversation(_)))); + + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + work_together(&mut app); + let asked = jobs.lock().unwrap().iter().any(|j| matches!(j, Job::Conversation(id) if id == "/Minutes.note")); + assert!(asked, "the provider is asked about the handle it issued"); +} + +#[test] +fn a_conversation_uses_the_hosts_chat_opener() { + let (mut app, _, ctx) = wired(); + app.cloud + .events + .0 + .send(Event::Conversation(Ok(craft_cloud::Conversation { url: "https://cloud.example.net/call/room".to_owned(), name: "Talk".to_owned() }))) + .unwrap(); + + pumped(&mut app, &ctx); + + assert_eq!(app.did().conversations, ["https://cloud.example.net/call/room"]); + assert!(app.did().urls.is_empty(), "ordinary browser links and conversations remain separate host decisions"); +} + +#[test] +fn signing_out_forgets_everything_this_window_knew() { + let (mut app, jobs, ctx) = wired(); + start(&mut app); + pumped(&mut app, &ctx); + open_entry(&mut app, file("/Minutes.note"), None); + pumped(&mut app, &ctx); + sign_out(&mut app); + let state = report(&app); + assert_eq!(state["account"], serde_json::Value::Null); + assert_eq!(state["origin"], serde_json::Value::Null); + assert_eq!(state["entries"], serde_json::json!([])); + assert!(jobs.lock().unwrap().iter().any(|j| matches!(j, Job::SignOut)), "the service is told, so the saved token goes too"); +} + +#[test] +fn bytes_are_said_the_way_a_person_reads_them() { + assert_eq!(size_text(None), ""); + assert_eq!(size_text(Some(512)), "512 bytes"); + assert_eq!(size_text(Some(2048)), "2.0 KB"); + assert_eq!(size_text(Some(5 * 1024 * 1024)), "5.0 MB"); +} + +#[test] +fn a_destination_is_named_after_the_account_it_belongs_to() { + let mut app = Notebook::new(); + assert_eq!(destination_name(&app), "Cloud storage", "two entries reading the same tell nobody which account this is"); + app.cloud.account = Some(Account { display: "Ada Lovelace".to_owned(), capabilities: Vec::new(), provider_linked: true }); + assert_eq!(destination_name(&app), "Ada Lovelace"); +} + +#[test] +fn the_contracts_own_conflict_is_the_one_a_save_must_not_retry() { + assert_eq!(Fault::from(craft_cloud::Error::Conflict("Minutes.note".to_owned())), Fault::Conflict); + assert_eq!(Fault::from(craft_cloud::Error::Unauthenticated), Fault::Unauthenticated); + assert!(matches!(Fault::from(craft_cloud::Error::Unsupported("sharing")), Fault::Refused(_))); +} + +#[test] +fn a_save_asks_for_the_bytes_under_the_name_they_are_going_to() { + // A document opened as one format and saved in the application's own would + // hand the user a file no other application reads, under a name that says + // it is readable. The application cannot avoid that without being told + // where the bytes are going. + let (mut app, _jobs, ctx) = wired(); + let mut sheet = file("/figures.csv"); + sheet.mime = Some("text/csv".to_owned()); + open_entry(&mut app, sheet, None); + pumped(&mut app, &ctx); + save(&mut app).unwrap(); + assert_eq!(app.did().encoded_as, vec!["figures.csv".to_owned()]); + assert_eq!(app.did().encoded_mime, vec![Some("text/csv".to_owned())], "the provider's own word for it comes too"); + + // And Save As, where the name is the one just typed rather than the one + // the document arrived under. + let (mut app, _jobs, ctx) = wired(); + open_entry(&mut app, file("/figures.csv"), None); + pumped(&mut app, &ctx); + save_as(&mut app, "", "a copy.note").unwrap(); + assert_eq!(app.did().encoded_as, vec!["a copy.note".to_owned()]); + assert_eq!(app.did().encoded_mime, vec![None], "nothing is there yet, so nothing says what it is"); +} + +#[test] +fn a_destination_reads_its_own_extension() { + assert_eq!(Destination::new("figures.csv").extension(), "csv"); + assert_eq!(Destination::new("FIGURES.CSV").extension(), "csv", "a shouted name is the same name"); + assert_eq!(Destination::new("report.2026.xlsx").extension(), "xlsx", "the last one wins"); + // A bare name, which is what a web application's export commonly has. + // Everything an application can learn is in the content type instead. + assert_eq!(Destination::new("exported").extension(), ""); + assert_eq!(Destination::new("trailing.").extension(), ""); +} + +// ---- somebody who followed a shared link ---------------------------------- + +/// One frame of the title bar's right-hand end, as the accessibility tree +/// reported it. +/// +/// Read off the tree rather than out of the state, because the question is +/// what a recipient can reach. A field saying "no menu" proves nothing about +/// what was drawn. +fn title_bar(app: &mut Notebook) -> Vec<(egui::accesskit::Role, String)> { + let ctx = egui::Context::default(); + ctx.enable_accesskit(); + let raw = egui::RawInput { screen_rect: Some(egui::Rect::from_min_size(egui::Pos2::ZERO, egui::vec2(400.0, 48.0))), ..Default::default() }; + let mut output = ctx.run_ui(raw, |ui| who(app, ui)); + output.textures_delta.clear(); + let Some(tree) = output.platform_output.accesskit_update.as_ref() else { return Vec::new() }; + tree.nodes + .iter() + .filter_map(|(_, node)| { + // egui puts a plain label's text in the accessibility value and a + // control's text in the label, so both are text on screen. + node.label().or_else(|| node.value()).map(|text| (node.role(), text.to_owned())) + }) + .collect() +} + +fn pressable(seen: &[(egui::accesskit::Role, String)]) -> Vec { + seen.iter().filter(|(role, _)| *role == egui::accesskit::Role::Button).map(|(_, text)| text.clone()).collect() +} + +fn reads(seen: &[(egui::accesskit::Role, String)], fragment: &str) -> bool { + seen.iter().any(|(_, text)| text.contains(fragment)) +} + +#[test] +fn a_recipient_is_named_and_offered_nothing() { + let mut app = Notebook::new(); + app.cloud.as_guest("outsider@example.org", false); + let seen = title_bar(&mut app); + assert!(reads(&seen, "outsider@example.org"), "a recipient has no account, so their own address is the identity to show: {seen:?}"); + // The whole point. Every item an account menu holds is a sign-out, a + // switch or a storage connection, and a recipient has none of those. + assert_eq!(pressable(&seen), Vec::::new(), "nothing here may be pressed: {seen:?}"); + for offer in ["Sign in", "Sign out", "Account", "Connect storage", "Add an account"] { + assert!(!reads(&seen, offer), "a recipient was offered {offer}"); + } +} + +#[test] +fn a_read_only_share_says_so_before_anybody_tries_to_save() { + let mut app = Notebook::new(); + app.cloud.as_guest("outsider@example.org", true); + assert!(reads(&title_bar(&mut app), "Reading only"), "finding out at the moment of saving means doing the work twice"); + + app.cloud.as_guest("outsider@example.org", false); + assert!(!reads(&title_bar(&mut app), "Reading only"), "a share that allows an edit must not say otherwise"); +} + +#[test] +fn an_address_of_only_spaces_leaves_no_badge() { + let mut app = Notebook::new(); + app.cloud.as_guest(" ", false); + assert!(app.cloud.guest().is_none(), "a badge with nothing on it reads as a fault"); + assert_eq!(title_bar(&mut app), Vec::new()); +} + +#[test] +fn a_signed_in_window_still_gets_its_account_badge() { + let (mut app, _jobs, ctx) = wired(); + start(&mut app); + pumped(&mut app, &ctx); + let seen = title_bar(&mut app); + assert!(!pressable(&seen).is_empty(), "somebody with an account still has a menu to reach: {seen:?}"); + assert!(reads(&seen, "Ada Lovelace")); +} + +#[test] +fn the_report_says_who_this_window_is_for() { + let mut app = Notebook::new(); + assert_eq!(report(&app)["guest"], serde_json::Value::Null, "most windows belong to nobody in particular yet"); + app.cloud.as_guest("outsider@example.org", true); + assert_eq!(report(&app)["guest"], serde_json::json!({"recipient": "outsider@example.org", "readOnly": true})); +} diff --git a/crates/cloud-ui/src/cloud/title.rs b/crates/cloud-ui/src/cloud/title.rs new file mode 100644 index 000000000..2535caf68 --- /dev/null +++ b/crates/cloud-ui/src/cloud/title.rs @@ -0,0 +1,173 @@ +//! The right-hand end of a title bar, plus the Save As destination. +//! +//! Who is signed in, who else is here, and Share. Every office suite puts +//! these three in the same corner, in that order. A person coming from one of +//! them looks there first. + +use egui::{RichText, Ui}; + +use super::{CloudApp, CopyFormat, Guest, available, fill, link, origin, sign_in, sign_out, work_together}; + +/// Who this window is for. Who else is in the document, beside them. +/// +/// Three cases, each a different person. Somebody signed in gets the account +/// badge and its menu. Somebody who followed a shared link gets their own +/// address and no menu, having no account to manage. A build with no service +/// configured gets neither. A badge that cannot sign anybody in would be a +/// control that fails on use. +/// +/// Nothing is asked for here. Drawing a badge must not begin a sign-in: a +/// worker signs in before any job it is given, and it then blocks polling the +/// browser for minutes. Starting that from a paint call pops a browser open at +/// launch and leaves every later job queued behind it. Signing in is a gesture, +/// so it waits for a press. +pub fn who(app: &mut A, ui: &mut Ui) { + match app.cloud().guest().cloned() { + Some(guest) => shared_with(app, ui, &guest), + None => account(app, ui), + } + // Who else is here, beside whoever this window belongs to. Nothing is + // drawn while a person is working alone, which keeps a solitary document + // looking like one. + if app.presence().shared() { + ui.add_space(6.0); + app.presence().show(ui); + } +} + +/// Who a shared link was sent to, for somebody with no account anywhere. +/// +/// A label and not a button. Every item an account menu holds is a sign-out, a +/// switch or a storage connection, and a recipient has none of those. A +/// control that opens a menu of failures is worse than no control. +fn shared_with(app: &mut A, ui: &mut Ui, guest: &Guest) { + let explained = fill(app, "This document was shared with {}", &guest.recipient); + let reading = app.tr("Reading only"); + let dim = ui.visuals().weak_text_color(); + if guest.read_only { + // Said where the account would be. Both answer what this window may + // do with the document in it. A recipient who finds out at the moment + // of saving has already done the work twice. + ui.label(RichText::new(reading).small().color(dim)); + ui.add_space(6.0); + } + ui.label(RichText::new(guest.recipient.as_str()).small().color(dim)).on_hover_text(explained); +} + +/// The account badge and its menu, for somebody signed in. +fn account(app: &mut A, ui: &mut Ui) { + if !available(app) { + return; + } + let service = app.service(); + let known = app.cloud().account.as_ref().map(|a| crate::account::Account { + // One account for now. The control already holds a list, so a second + // deployment is a second entry here and nothing else changes. + id: "default".to_owned(), + display: a.display.clone(), + email: None, + service, + linked: a.provider_linked, + }); + let new_accounts: Vec<_> = known.into_iter().collect(); + let cloud = app.cloud_mut(); + if cloud.accounts.accounts() != new_accounts.as_slice() { + cloud.accounts.set(new_accounts); + } + cloud.accounts.show(ui); + + while let Some(action) = app.cloud_mut().accounts.take_action() { + use crate::account::AccountAction as Act; + match action { + // Signing in and connecting storage are two different things. + // Signing in is the device flow against the service, which every + // job already triggers when there is no token. Asking who the + // account is therefore starts it. Linking storage comes after, and + // needs that session to exist first. + Act::SignIn | Act::AddAccount => { + app.cloud_mut().sign_in_from_menu = true; + sign_in(app); + } + Act::Link(_) => link(app), + Act::SignOut(_) => sign_out(app), + // One account, so there is nothing to switch to yet. + Act::Use(_) => {} + Act::Manage(_) => { + let host = app.service(); + if !host.is_empty() { + app.open_url(&format!("https://{host}/account")); + } + } + } + } +} + +/// Whether the Share split button can be drawn. +/// +/// False until the service says the provider supports sharing. An application +/// draws whatever it offered before. A button that fails on use is worse than +/// no button at all. +pub fn shares(app: &mut A) -> bool { + app.sharing().available() +} + +/// Share, as a split button. +/// +/// Pressing the label shares, which is what somebody wants most of the time. +/// The chevron carries the variations, and working together is one of them. +/// `copies` are the application's own Save a Copy formats. Those have nothing +/// in common between one application and the next. +/// +/// Answers with the identifier of a copy format, when that is what was chosen. +/// Everything else is carried out here. +pub fn share_button(app: &mut A, ui: &mut Ui, copies: &[CopyFormat]) -> Option { + let noun = app.kind().noun; + let mut items = Vec::new(); + if app.cloud().can_converse() { + let detail = app.tr(&format!("Open a chat about this {noun}")); + items.push(crate::menu::MenuItem::new("talk", app.tr("Open chat")).detail(detail)); + } + for (at, copy) in copies.iter().enumerate() { + let item = crate::menu::MenuItem::new(copy.id.clone(), copy.label.clone()); + // A rule above the first copy, so sharing and exporting read as two + // groups rather than one long list. + items.push(if at == 0 && !items.is_empty() { item.separated() } else { item }); + } + let labels = crate::menu::MenuLabels::default(); + let primary = app.tr("Share"); + match crate::menu::split(ui, &primary, &items, &labels)? { + crate::menu::SplitHit::Primary => { + // The handle the provider issued, which is what a share is about. + // A document that has never been in the cloud has none, and the + // dialog says so. + let (id, title) = match origin(app) { + Some(origin) => (origin.entry.id.clone(), origin.entry.name.clone()), + None => (String::new(), app.active().map(|uid| app.title(uid)).unwrap_or_default()), + }; + app.sharing().open(id, title); + None + } + crate::menu::SplitHit::Item(what) if what == "talk" => { + work_together(app); + None + } + crate::menu::SplitHit::Item(format) => Some(format), + } +} + +/// What to call the cloud destination on a Save As page. +/// +/// The account's own name. The destination then reads as the user's own +/// storage. Somebody with an account on two deployments needs to know which +/// one a document is about to land in. +pub fn destination_name(app: &A) -> String { + app.cloud().account.as_ref().map(|a| a.display.clone()).filter(|display| !display.is_empty()).unwrap_or_else(|| app.tr("Cloud storage")) +} + +/// Whether the cloud destination is the one to offer first. +/// +/// A document that came from the cloud is saved back there unless the user says +/// otherwise. One that came from this computer is not. +pub fn prefers_cloud(app: &A) -> bool { + available(app) && origin(app).is_some() +} diff --git a/crates/cloud-ui/src/lib.rs b/crates/cloud-ui/src/lib.rs new file mode 100644 index 000000000..74e2a1ad8 --- /dev/null +++ b/crates/cloud-ui/src/lib.rs @@ -0,0 +1,20 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] + +//! The share dialog, the cloud Open and Save pages, the account menu and the presence bar that +//! every Craft app shares. +//! +//! This is storytold main's cloud and share UI as main wrote it in craft-ui: raw egui, outside the +//! craft UI library's component contract, themes and tokens. It is to be ported onto the +//! framework's components. Until then the `craft-ui` facade re-exports `account`, `cloud`, `share` +//! and `presence` from here, with the same `share` and `cloud` features, so `craft_ui::…` paths +//! stay as on main. + +#[cfg(feature = "share")] +pub mod account; +mod buttons; +#[cfg(feature = "cloud")] +pub mod cloud; +pub mod menu; +pub mod presence; +#[cfg(feature = "share")] +pub mod share; diff --git a/crates/cloud-ui/src/menu.rs b/crates/cloud-ui/src/menu.rs new file mode 100644 index 000000000..70189a56f --- /dev/null +++ b/crates/cloud-ui/src/menu.rs @@ -0,0 +1,222 @@ +//! The two controls that offer more than one action. +//! +//! An overflow menu is the `…` that holds what did not earn a place on the +//! toolbar. A split button is a primary action with a chevron beside it, where +//! the chevron offers the variations. Share is the usual example. Most of the +//! time a person wants to share, and once in a while they want to copy a link +//! or start a call about the document instead. +//! +//! They are one module because they are the same control underneath. Building +//! them twice would mean getting the accessible naming right twice, and an +//! icon-only button that announces itself as an ellipsis character is useless +//! to anybody reading the screen rather than looking at it. +//! +//! Neither control knows what any item does. Each answers with the identifier +//! of the item a person chose. The application holds the meaning. + +use egui::{Response, RichText, Ui}; + +/// One line in a menu. +#[derive(Clone, Debug, Default, PartialEq, Eq)] +pub struct MenuItem { + /// What the caller recognises this by. Never shown. + pub id: String, + pub label: String, + /// A second line, smaller. Worth having where the label alone leaves a + /// person guessing what the action will do to their document. + pub detail: Option, + /// A leading glyph. Decoration only, so it is never the accessible name. + pub icon: Option, + pub enabled: bool, + /// Draw a rule above this item. A group of related actions reads as a + /// group only when something separates it from the last one. + pub separator_before: bool, +} + +impl MenuItem { + pub fn new(id: impl Into, label: impl Into) -> MenuItem { + MenuItem { id: id.into(), label: label.into(), enabled: true, ..MenuItem::default() } + } + + pub fn detail(mut self, detail: impl Into) -> MenuItem { + self.detail = Some(detail.into()); + self + } + + pub fn icon(mut self, icon: impl Into) -> MenuItem { + self.icon = Some(icon.into()); + self + } + + /// Present but unavailable, with a reason on hover. + /// + /// Greying an item out says the action exists and is not possible now. + /// Removing it says the action does not exist. They are different facts and + /// a person reads them differently. + pub fn disabled(mut self, why: impl Into) -> MenuItem { + self.enabled = false; + self.detail = Some(why.into()); + self + } + + pub fn separated(mut self) -> MenuItem { + self.separator_before = true; + self + } +} + +/// What a person did to a split button. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum SplitHit { + /// They pressed the button itself. + Primary, + /// They chose something from the chevron's menu. + Item(String), +} + +/// The accessible name of the chevron, and of the overflow button. +/// +/// Public so an application can translate them. A glyph is not a name, and +/// these two are the only strings in this module that are not supplied by the +/// caller. +#[derive(Clone, Debug)] +pub struct MenuLabels { + /// The `…` button. + pub more: String, + /// The chevron on a split button. `{action}` is replaced with the primary + /// action's own label, so a screen reader says "more share options" rather + /// than "more options" on a toolbar holding four of them. + pub more_for: String, +} + +impl Default for MenuLabels { + fn default() -> MenuLabels { + MenuLabels { more: "More options".into(), more_for: "More {action} options".into() } + } +} + +/// The `…` button and its menu. +/// +/// Answers with the identifier of the item chosen, if any. +pub fn overflow(ui: &mut Ui, items: &[MenuItem], labels: &MenuLabels) -> Option { + // A horizontal ellipsis, not three periods. Three periods are three + // characters to anything reading the screen aloud. + let button = egui::Button::new(RichText::new("\u{2026}").size(15.0)).frame(false); + let hit = ui.add(button); + let name = labels.more.clone(); + hit.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, name.as_str())); + let hit = hit.on_hover_text(labels.more.as_str()); + items_of(&hit, items) +} + +/// A primary action with a chevron beside it. +/// +/// The two halves are two controls. Pressing the label does the thing. Pressing +/// the chevron offers the variations. One control that did both would leave a +/// person guessing which half they had hit. +pub fn split(ui: &mut Ui, primary: &str, items: &[MenuItem], labels: &MenuLabels) -> Option { + let mut hit = None; + ui.horizontal(|ui| { + // The halves touch, so they read as one control with two parts. Square + // off the inside corners as well. Two default radii leave a pair of + // notches at the seam, which reads as two buttons that happen to abut. + ui.spacing_mut().item_spacing.x = 0.0; + let radius = ui.visuals().widgets.inactive.corner_radius; + // A toolbar that fills from its right edge hands this control a + // right-to-left layout, and whatever is added first lands furthest + // right. The label still belongs before the chevron, so the halves are + // added in the order that puts them there. + let backwards = ui.layout().main_dir() == egui::Direction::RightToLeft; + let (outer, inner) = if backwards { + (egui::CornerRadius { nw: 0, sw: 0, ..radius }, egui::CornerRadius { ne: 0, se: 0, ..radius }) + } else { + (egui::CornerRadius { ne: 0, se: 0, ..radius }, egui::CornerRadius { nw: 0, sw: 0, ..radius }) + }; + let label = |ui: &mut Ui, hit: &mut Option| { + if ui.add(egui::Button::new(primary).corner_radius(if backwards { inner } else { outer })).clicked() { + *hit = Some(SplitHit::Primary); + } + }; + let chevron = |ui: &mut Ui, hit: &mut Option| { + // Room for the triangle, which is painted rather than typed. + let more = ui.add(egui::Button::new(" ").corner_radius(if backwards { outer } else { inner })); + crate::buttons::chevron(ui, more.rect, ui.visuals().text_color()); + let name = labels.more_for.replace("{action}", &primary.to_lowercase()); + more.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, name.as_str())); + let more = more.on_hover_text(name.as_str()); + if let Some(id) = items_of(&more, items) { + *hit = Some(SplitHit::Item(id)); + } + }; + if backwards { + chevron(ui, &mut hit); + label(ui, &mut hit); + } else { + label(ui, &mut hit); + chevron(ui, &mut hit); + } + }); + hit +} + +/// The menu both controls open. +fn items_of(anchor: &Response, items: &[MenuItem]) -> Option { + let mut chosen = None; + egui::Popup::menu(anchor).show(|ui| { + ui.set_min_width(210.0); + let weak = ui.visuals().weak_text_color(); + for item in items { + if item.separator_before { + ui.separator(); + } + let label = match &item.icon { + Some(icon) => format!("{icon} {}", item.label), + None => item.label.clone(), + }; + let row = ui.add_enabled(item.enabled, egui::Button::new(label).frame(false)); + // The icon is decoration. The name is the label alone. + let name = item.label.clone(); + let enabled = item.enabled; + row.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, enabled, name.as_str())); + if row.clicked() { + chosen = Some(item.id.clone()); + ui.close(); + } + if let Some(detail) = &item.detail { + ui.label(RichText::new(detail.as_str()).small().color(weak)); + ui.add_space(2.0); + } + } + }); + chosen +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn an_item_is_enabled_until_it_is_not() { + assert!(MenuItem::new("copy", "Copy link").enabled); + let off = MenuItem::new("copy", "Copy link").disabled("this server forbids public links"); + assert!(!off.enabled); + assert_eq!(off.detail.as_deref(), Some("this server forbids public links")); + } + + #[test] + fn the_chevrons_name_says_which_action_it_belongs_to() { + let labels = MenuLabels::default(); + assert_eq!(labels.more_for.replace("{action}", "share"), "More share options"); + } + + #[test] + fn a_builder_keeps_what_it_was_given() { + let item = MenuItem::new("talk", "Work together").icon("\u{1f4de}").detail("Start a call").separated(); + assert_eq!(item.id, "talk"); + assert_eq!(item.label, "Work together"); + assert_eq!(item.icon.as_deref(), Some("\u{1f4de}")); + assert_eq!(item.detail.as_deref(), Some("Start a call")); + assert!(item.separator_before); + assert!(item.enabled); + } +} diff --git a/crates/cloud-ui/src/presence.rs b/crates/cloud-ui/src/presence.rs new file mode 100644 index 000000000..f429691bc --- /dev/null +++ b/crates/cloud-ui/src/presence.rs @@ -0,0 +1,424 @@ +//! Who else is in the document. +//! +//! A person editing alone and a person editing alongside three colleagues are +//! in very different situations. Only one of them has to worry about somebody +//! else changing the cell they are about to type in. An application that shows +//! nothing leaves them to find out by surprise. +//! +//! So this is a row of badges, one per person, with the count folded into a +//! final badge once the row would get long. It is the same control every +//! collaborative editor puts in the same corner, for the same reason. +//! +//! A peer's colour comes from the peer's own identifier. Two things need to +//! agree on it: the badge here, and whatever the document draws at that +//! person's cursor. Deriving it rather than assigning it means they agree with +//! no state passed between them, and the colour survives a reconnection. + +use egui::{Align, Color32, Layout, Response, RichText, Ui}; + +/// How wide a badge is, and how far the next one overlaps it. +const BADGE: f32 = 24.0; +const OVERLAP: f32 = 7.0; + +/// Somebody else in the document right now. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Peer { + /// The session's own identifier, stable for as long as they are connected. + pub id: String, + /// What to show. A display name, never an identity. + pub display: String, + /// Where they are working, when the document can say. A spreadsheet knows + /// the cell. A word processor knows the page. Shown on hover only. + pub at: Option, +} + +impl Peer { + pub fn new(id: impl Into, display: impl Into) -> Peer { + Peer { id: id.into(), display: display.into(), at: None } + } + + /// Where they are working, for the tooltip. + pub fn at(mut self, at: impl Into) -> Peer { + self.at = Some(at.into()); + self + } + + /// The letter on the badge. + pub fn initial(&self) -> String { + self.display.chars().next().map(|c| c.to_uppercase().to_string()).unwrap_or_else(|| "?".to_owned()) + } + + /// This peer's colour. + pub fn colour(&self) -> Color32 { + colour_for(&self.id) + } +} + +/// How many colours the wheel carries. +/// +/// Sixteen, spaced evenly. More than that and neighbouring slots stop being +/// distinguishable, which defeats the point of having them. +pub const SLOTS: usize = 16; + +/// The colour in one slot of the wheel. +pub fn slot(index: usize) -> Color32 { + let step = 360.0 / SLOTS as f32; + // Alternate the lightness as the wheel turns, so two neighbouring hues are + // also two different weights. Hue alone is not enough for anybody who sees + // colour differently from the person who chose it. + let dim = index % 2 == 1; + hsv((index % SLOTS) as f32 * step, if dim { 0.66 } else { 0.52 }, if dim { 0.68 } else { 0.84 }) +} + +/// Which slot an identifier would like. +fn preferred(id: &str) -> usize { + // FNV-1a, which is small and has no dependency. + let mut hash: u32 = 0x811c_9dc5; + for byte in id.as_bytes() { + hash ^= u32::from(*byte); + hash = hash.wrapping_mul(0x0100_0193); + } + // Then an avalanche. FNV alone leaves keys that differ in one byte close + // together, and session ids from one relay run in sequence. + hash ^= hash >> 16; + hash = hash.wrapping_mul(0x7feb_352d); + hash ^= hash >> 15; + hash = hash.wrapping_mul(0x846c_a68b); + hash ^= hash >> 16; + hash as usize % SLOTS +} + +/// A stable colour for one identifier, with nobody else to consider. +/// +/// Public because the badge is not the only thing that needs it. Use +/// [`colours_for`] wherever a whole room is on screen. This one cannot promise +/// anything about the other people in it. +pub fn colour_for(id: &str) -> Color32 { + slot(preferred(id)) +} + +/// Colours for a whole room, every one distinguishable from the others. +/// +/// Each peer prefers the slot its identifier hashes to. A peer whose slot is +/// already taken moves to the next free one, walking the list in a fixed order +/// so the answer does not depend on who connected first. +/// +/// A document drawing remote cursors calls this with the same identifiers and +/// gets the same answer, which is what makes a cursor and the badge above it +/// the same person. That holds on one screen whatever else is happening, +/// since both calls see that client's own list. +/// +/// Two clients mid-transition can disagree for a frame or two. One has seen +/// somebody join and the other has not, so the walk resolves differently +/// until both lists match. It settles by itself, and nobody is comparing two +/// screens while it does. The durable fix is for the relay to hand out slots +/// with the peer list, which takes a protocol change. +/// +/// Beyond [`SLOTS`] peers the wheel repeats, since there is no seventeenth +/// colour anybody could tell from the first sixteen. +pub fn colours_for(ids: &[String]) -> Vec { + let mut order: Vec = (0..ids.len()).collect(); + order.sort_by(|a, b| ids[*a].cmp(&ids[*b])); + + let mut taken = [false; SLOTS]; + let mut out = vec![Color32::BLACK; ids.len()]; + for position in order { + let want = preferred(&ids[position]); + let mut at = want; + for step in 0..SLOTS { + at = (want + step) % SLOTS; + if !taken[at] { + break; + } + } + taken[at] = true; + out[position] = slot(at); + } + out +} + +fn hsv(hue: f32, saturation: f32, value: f32) -> Color32 { + let c = value * saturation; + let h = hue / 60.0; + let x = c * (1.0 - ((h % 2.0) - 1.0).abs()); + let (r, g, b) = match h as u32 { + 0 => (c, x, 0.0), + 1 => (x, c, 0.0), + 2 => (0.0, c, x), + 3 => (0.0, x, c), + 4 => (x, 0.0, c), + _ => (c, 0.0, x), + }; + let m = value - c; + let to_byte = |f: f32| (f.clamp(0.0, 1.0) * 255.0).round() as u8; + Color32::from_rgb(to_byte(r + m), to_byte(g + m), to_byte(b + m)) +} + +/// Strings, so an application can translate them. +#[derive(Clone, Debug)] +pub struct PresenceLabels { + /// Said when nobody else is here. An application may leave this empty to + /// draw nothing at all in that case. + pub alone: String, + /// With one other person. `{name}` is replaced. + pub with_one: String, + /// With several. `{count}` is replaced. + pub with_many: String, + /// The badge that stands for the people who did not fit. `{count}` is + /// replaced. + pub and_more: String, + /// The accessible name of the whole row. + pub who: String, +} + +impl Default for PresenceLabels { + fn default() -> PresenceLabels { + PresenceLabels { + alone: String::new(), + with_one: "Editing with {name}".into(), + with_many: "Editing with {count} others".into(), + and_more: "{count} more".into(), + who: "Who is here".into(), + } + } +} + +/// The row of badges. +#[derive(Clone)] +pub struct PresenceBar { + peers: Vec, + /// How many badges to draw before folding the rest into a count. Four is + /// what fits beside a title bar without crowding it. + shown: usize, + labels: PresenceLabels, + /// Whether to write the sentence beside the badges. A narrow toolbar wants + /// the badges alone. + summary: bool, +} + +impl Default for PresenceBar { + fn default() -> PresenceBar { + PresenceBar::new() + } +} + +impl PresenceBar { + pub fn new() -> PresenceBar { + PresenceBar { peers: Vec::new(), shown: 4, labels: PresenceLabels::default(), summary: true } + } + + pub fn with_labels(mut self, labels: PresenceLabels) -> PresenceBar { + self.labels = labels; + self + } + + /// How many badges before the row folds into a count. + pub fn with_shown(mut self, shown: usize) -> PresenceBar { + self.shown = shown.max(1); + self + } + + /// Draw the badges only, with no sentence beside them. + pub fn badges_only(mut self) -> PresenceBar { + self.summary = false; + self + } + + /// Replace the set of people in the document. + /// + /// Takes the whole set rather than a change, because a session that missed + /// a departure would otherwise show somebody who left until the next + /// reconnection. + pub fn set(&mut self, peers: Vec) { + self.peers = peers; + } + + pub fn peers(&self) -> &[Peer] { + &self.peers + } + + /// Whether anybody else is here. An application draws nothing when this is + /// false, which keeps a solitary document looking like one. + pub fn shared(&self) -> bool { + !self.peers.is_empty() + } + + /// What the row says in words. Also the accessible summary. + pub fn summary(&self) -> String { + match self.peers.len() { + 0 => self.labels.alone.clone(), + 1 => self.peers.first().map(|p| self.labels.with_one.replace("{name}", &p.display)).unwrap_or_default(), + n => self.labels.with_many.replace("{count}", &n.to_string()), + } + } + + /// Draw it. Answers with the peer a person clicked, when they clicked one. + /// + /// A click is worth answering because a name is where "take me to what + /// they are editing" belongs. The application decides whether it can. + pub fn show(&mut self, ui: &mut Ui) -> Option { + if self.peers.is_empty() { + if !self.labels.alone.is_empty() { + ui.label(RichText::new(self.labels.alone.as_str()).small().color(ui.visuals().weak_text_color())); + } + return None; + } + + let mut clicked = None; + ui.horizontal(|ui| { + // Badges overlap, the way a stack of cards does. Without it four + // circles read as four separate controls instead of one group. + ui.spacing_mut().item_spacing.x = -OVERLAP; + // Right to left, so the first person sits on top of the stack. + // + // Allocated to just the width the badges need. A right-to-left + // layout given the whole container takes it, which pushes the row + // to the far edge of a toolbar and strands the sentence after it. + let shown = self.peers.len().min(self.shown); + let hidden = self.peers.len().saturating_sub(self.shown); + let count = shown + usize::from(hidden > 0); + let width = BADGE + (count.saturating_sub(1) as f32) * (BADGE - OVERLAP); + ui.allocate_ui_with_layout(egui::vec2(width, BADGE), Layout::right_to_left(Align::Center), |ui| { + if hidden > 0 { + let more = self.labels.and_more.replace("{count}", &hidden.to_string()); + let weak = ui.visuals().widgets.inactive.bg_fill; + let badge = badge(ui, &format!("+{hidden}"), weak, ui.visuals().text_color()); + badge.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, more.as_str())); + badge.on_hover_text(self.peers.iter().skip(self.shown).map(|p| p.display.as_str()).collect::>().join("\n")); + } + let ids: Vec = self.peers.iter().map(|p| p.id.clone()).collect(); + let colours = colours_for(&ids); + for (at, peer) in self.peers.iter().enumerate().take(self.shown).rev() { + let ink = colours.get(at).copied().unwrap_or_else(|| peer.colour()); + let hit = badge(ui, &peer.initial(), ink, Color32::WHITE); + let name = peer.display.clone(); + hit.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, name.as_str())); + let tip = match &peer.at { + Some(at) => format!("{}\n{at}", peer.display), + None => peer.display.clone(), + }; + if hit.on_hover_text(tip).clicked() { + clicked = Some(peer.id.clone()); + } + } + }); + if self.summary { + ui.spacing_mut().item_spacing.x = 8.0; + ui.label(RichText::new(self.summary()).small().color(ui.visuals().weak_text_color())); + } + }); + clicked + } +} + +/// One round badge. Painted as a button so it is focusable and announces +/// itself, which a bare circle would not. +fn badge(ui: &mut Ui, text: &str, fill: Color32, ink: Color32) -> Response { + let button = egui::Button::new(RichText::new(text).color(ink).size(11.0).strong()) + .fill(fill) + .corner_radius(BADGE / 2.0) + .min_size(egui::vec2(BADGE, BADGE)) + .stroke(egui::Stroke::new(1.5, ui.visuals().panel_fill)); + ui.add(button) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn a_colour_is_the_same_every_time_for_the_same_peer() { + assert_eq!(colour_for("session-a"), colour_for("session-a")); + } + + /// How far apart two colours are, summed over the channels. Crude, and + /// enough to tell "two different oranges" from "orange and teal". + fn apart(a: Color32, b: Color32) -> i32 { + (i32::from(a.r()) - i32::from(b.r())).abs() + (i32::from(a.g()) - i32::from(b.g())).abs() + (i32::from(a.b()) - i32::from(b.b())).abs() + } + + fn ids(of: &[&str]) -> Vec { + of.iter().map(|s| (*s).to_owned()).collect() + } + + #[test] + fn a_room_of_sequential_ids_is_a_room_of_distinguishable_colours() { + // The shape a relay actually hands out. A colour derived from one id + // alone cannot promise this, which is how six people came out looking + // like two. + let room = ids(&["s1", "s2", "s3", "s4", "s5", "s6"]); + let colours = colours_for(&room); + for (i, a) in colours.iter().enumerate() { + for (j, b) in colours.iter().enumerate().skip(i + 1) { + let distance = apart(*a, *b); + assert!(distance >= 60, "{} and {} are {distance} apart", room[i], room[j]); + } + } + } + + #[test] + fn a_full_wheel_is_still_all_distinct() { + let room: Vec = (0..SLOTS).map(|n| format!("session-{n}")).collect(); + let colours = colours_for(&room); + for (i, a) in colours.iter().enumerate() { + for (j, b) in colours.iter().enumerate().skip(i + 1) { + assert!(apart(*a, *b) > 0, "{} and {} share a colour", room[i], room[j]); + } + } + } + + #[test] + fn the_same_room_always_gets_the_same_colours() { + let room = ids(&["b", "a", "c"]); + assert_eq!(colours_for(&room), colours_for(&room)); + } + + #[test] + fn the_answer_does_not_depend_on_who_connected_first() { + let one = colours_for(&ids(&["a", "b", "c"])); + let other = colours_for(&ids(&["c", "b", "a"])); + // Same people, listed backwards. Each still gets the colour it had. + assert_eq!(one, other.into_iter().rev().collect::>()); + } + + #[test] + fn a_colour_is_dark_enough_to_hold_white_text() { + for id in ["a", "b", "zzz", "session-41", "", "\u{1f600}"] { + let c = colour_for(id); + // Rec. 601 luma, which is what readability of white ink tracks. + let luma = 0.299 * f32::from(c.r()) + 0.587 * f32::from(c.g()) + 0.114 * f32::from(c.b()); + assert!(luma < 200.0, "{id:?} gave a colour too pale for white text, luma {luma}"); + } + } + + #[test] + fn an_empty_room_is_not_shared_and_says_nothing() { + let bar = PresenceBar::new(); + assert!(!bar.shared()); + assert_eq!(bar.summary(), ""); + } + + #[test] + fn one_other_person_is_named_and_several_are_counted() { + let mut bar = PresenceBar::new(); + bar.set(vec![Peer::new("1", "Ann Reed")]); + assert_eq!(bar.summary(), "Editing with Ann Reed"); + bar.set(vec![Peer::new("1", "Ann Reed"), Peer::new("2", "Bob Vine")]); + assert_eq!(bar.summary(), "Editing with 2 others"); + } + + #[test] + fn a_departure_leaves_nobody_behind() { + let mut bar = PresenceBar::new(); + bar.set(vec![Peer::new("1", "Ann Reed"), Peer::new("2", "Bob Vine")]); + bar.set(vec![Peer::new("1", "Ann Reed")]); + assert_eq!(bar.peers().len(), 1, "the whole set replaces the old one"); + } + + #[test] + fn an_initial_survives_a_name_that_starts_oddly() { + assert_eq!(Peer::new("1", "ann").initial(), "A"); + assert_eq!(Peer::new("1", "").initial(), "?"); + assert_eq!(Peer::new("1", "\u{e9}lodie").initial(), "\u{c9}"); + } +} diff --git a/crates/cloud-ui/src/share/backend.rs b/crates/cloud-ui/src/share/backend.rs new file mode 100644 index 000000000..5c0981834 --- /dev/null +++ b/crates/cloud-ui/src/share/backend.rs @@ -0,0 +1,170 @@ +//! Where the share dialog's work happens, which is never on the frame. +//! +//! Every call a share needs is blocking, and a blocking call inside `update()` +//! freezes the window for as long as the server takes. So the dialog states +//! what it wants and reads answers off a channel, and something behind this +//! trait does the waiting. +//! +//! The dialog itself opens no socket, which keeps it buildable for the web +//! and testable with no server. A host supplies the half that does, and this +//! crate never learns what it reaches. + +use craft_cloud::{Capability, Contact, Permission, Share, ShareTarget}; + +/// One thing the dialog needs done. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Request { + /// What the provider behind the service can actually do. + Capabilities, + /// People matching what has been typed so far. + Lookup { query: String, limit: usize }, + /// Who already has access to one document. + Access { id: String }, + /// Give several people access at once. + Grant(Grant), + /// Take one existing share away. + Withdraw { share_id: String }, + /// Where this document could be saved, so it can be shared. + /// + /// Asked for only when there is nothing to share yet. A list rather than a + /// single answer, because more than one provider may be configured and the + /// user picks. + Destinations, + /// Link an account for a destination that is configured but not connected. + Link { destination: String }, + /// One contact's picture, by the URL that contact carried. + /// + /// A separate request because a search answering with ten people must not + /// cost ten pictures before anybody has looked at them. The dialog asks + /// for a picture when it first paints the row that needs it, once per URL. + Avatar { url: String }, +} + +/// A share to create, as the dialog has it. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Grant { + /// A key the recipient must present. Only meaningful for a link share, and + /// refused by a server that does not allow one. + pub password: Option, + /// The document, as an opaque handle the app was given. + pub id: String, + pub targets: Vec, + pub permission: Permission, + pub note: Option, + pub notify: bool, +} + +/// What came back. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Answer { + Capabilities { + capabilities: Vec, + /// Whether this user has a cloud account attached at all. + linked: bool, + }, + Lookup(Vec), + Access(Vec), + /// Partial success is the ordinary case, so both halves come back. + Granted { + shared: Vec, + failed: Vec, + }, + Withdrawn { + share_id: String, + }, + Destinations(Vec), + /// An account was linked, so the destinations are worth asking for again. + Linked, + Avatar { + url: String, + /// Encoded image bytes, in whatever format the server sent. Decoding + /// is egui's image loaders' job, which the application installs. + bytes: Vec, + }, +} + +/// Somewhere a document could be saved. +/// +/// `account` is what makes this choosable. Two entries reading "Cloud" tell +/// nobody which of their accounts a document is about to land in, which is the +/// one thing somebody needs to know before pressing it. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Destination { + /// Opaque to the dialog, handed back with the save. + pub id: String, + /// What to show, such as the service's own name. + pub name: String, + /// Which account, when one is linked. + pub account: Option, + /// False when the destination is configured but has no account yet. The + /// dialog offers a sign-in rather than a save. + pub linked: bool, +} + +/// One recipient a share did not reach. +/// +/// Named rather than counted. Sharing with five people where one address is +/// wrong shares with four and says which one failed. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct Failure { + pub target: ShareTarget, + pub code: String, + pub detail: String, +} + +/// Where one answer goes. +/// +/// Carries the sequence number of the request it answers. Autocomplete fires +/// per keystroke, and a service is free to answer the third query before the +/// second, so the dialog keeps the newest sequence it asked for and drops +/// anything older. Without that the list flickers between a stale set of +/// matches and a current one. +pub struct Replier { + seq: u64, + tx: std::sync::mpsc::Sender<(u64, Result)>, +} + +impl Replier { + pub(crate) fn new(seq: u64, tx: std::sync::mpsc::Sender<(u64, Result)>) -> Replier { + Replier { seq, tx } + } + + /// Which request this answers. + pub fn seq(&self) -> u64 { + self.seq + } + + /// Another handle to the same answer slot, for a backend that has to give + /// up after moving the first one into a worker. + pub fn dup(&self) -> Replier { + Replier { seq: self.seq, tx: self.tx.clone() } + } + + pub fn answer(self, answer: Answer) { + self.deliver(Ok(answer)); + } + + /// Say why it could not be done, in words a user can read. + pub fn refuse(self, reason: impl Into) { + self.deliver(Err(reason.into())); + } + + /// A dropped receiver means the dialog closed, which is not a failure. + fn deliver(self, result: Result) { + let _ = self.tx.send((self.seq, result)); + } +} + +impl std::fmt::Debug for Replier { + fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + f.debug_struct("Replier").field("seq", &self.seq).finish() + } +} + +/// Somewhere a [`Request`] can run without blocking a frame. +/// +/// `submit` must return immediately. The answer arrives through `reply` +/// whenever it is ready, or never, which the dialog survives. +pub trait ShareBackend { + fn submit(&self, request: Request, reply: Replier); +} diff --git a/crates/cloud-ui/src/share/mod.rs b/crates/cloud-ui/src/share/mod.rs new file mode 100644 index 000000000..e38067411 --- /dev/null +++ b/crates/cloud-ui/src/share/mod.rs @@ -0,0 +1,1465 @@ +//! One share dialog, the same one in every Craft app. +//! +//! What it offers is what a person asks for when they say "share this": pick +//! several people by typing a few letters of a name, choose whether they may +//! look or change, add a note, decide whether an email goes out, and see who +//! already has access so one of them can be taken away again. +//! +//! Three things shape the implementation. +//! +//! Nothing here opens a socket. Every call goes through [`ShareBackend`], and +//! nothing here reaches the network. A host writes the backend, and this +//! module never learns what it talks to. +//! this file. +//! +//! Nothing here blocks. Answers arrive on a channel and are read once per +//! frame. Autocomplete waits [`DEBOUNCE`] after the last keystroke before it +//! asks anything, and an answer to a query the user has already typed past is +//! dropped rather than painted, so the list cannot flicker backwards. +//! +//! Nothing here is assumed about the provider. [`ShareDialog::available`] is +//! false until the service says sharing exists, and an app hides its Share +//! control rather than offering a button that fails. Contacts and mail are +//! reported separately and are hidden the same way. + +use std::collections::HashMap; +use std::sync::mpsc::{Receiver, Sender}; +use std::time::Duration; + +use craft_cloud::{Capability, Contact, Permission, Share, ShareTarget}; +use egui::{Align, Align2, Color32, Context, CornerRadius, FontId, Id, Layout, Response, RichText, Sense, Ui, UiBuilder, Vec2}; + +mod backend; +#[cfg(test)] +mod tests; + +pub use backend::{Answer, Destination, Failure, Grant, Replier, Request, ShareBackend}; + +/// How long after the last keystroke the dialog asks for matches. +/// +/// A lookup per keystroke would ask five times for "annie" and paint whichever +/// answer happened to arrive last. +pub const DEBOUNCE: Duration = Duration::from_millis(200); + +/// How many matches one lookup asks for. +const MATCHES: usize = 8; + +/// Shortest query worth asking about. One letter matches most of an address +/// book and tells the user nothing. +const MIN_QUERY: usize = 2; + +/// Contact pictures held at once. Reached only by a long session of searching; +/// the whole cache is dropped rather than evicted one entry at a time. +const AVATARS: usize = 256; + +/// How long before an unanswered capability question is asked again, so one +/// unreachable moment does not hide Share for the rest of the session. +const RETRY: f64 = 20.0; + +const AVATAR: f32 = 20.0; +const AVATAR_RADIUS: u8 = 10; + +/// The id of the recipient field, for an app that wants to focus it. +const QUERY: &str = "craft-ui/share/query"; + +type Inbox = (u64, Result); + +/// Every string the dialog shows, so an application can translate it. +/// +/// The defaults are English. Nothing else in `craft-ui` localizes, and this +/// does not change that: the dialog holds the strings an app gives it and +/// translates nothing itself. +#[derive(Clone, Debug)] +pub struct ShareLabels { + pub title: String, + pub recipients: String, + pub recipient_hint: String, + pub searching: String, + pub no_matches: String, + pub add_address: String, + pub group: String, + pub permission: String, + pub can_view: String, + pub can_edit: String, + pub note: String, + pub notify: String, + pub no_mail: String, + pub share: String, + pub sharing: String, + pub close: String, + pub remove: String, + pub shared_with: String, + pub not_shared_with: String, + pub access: String, + pub access_empty: String, + pub loading: String, + pub withdraw: String, + pub withdrawing: String, + pub copy_link: String, + pub anyone_with_link: String, + pub save_first: String, + /// Shown under "Can edit", the way an office suite explains a permission + /// rather than leaving a bare radio button to carry the meaning. + pub can_edit_detail: String, + pub can_view_detail: String, + pub message_hint: String, + pub send: String, + pub manage_access: String, + pub upload_first: String, + pub name_hint: String, + pub saving: String, + pub save_and_share: String, + pub sign_in: String, + pub attach_instead: String, + pub create_link: String, + pub key_hint: String, + pub key_required_note: String, + pub link_copied: String, +} + +impl Default for ShareLabels { + fn default() -> ShareLabels { + ShareLabels { + title: "Share".into(), + recipients: "Share with".into(), + recipient_hint: "Add a name, group, or email".into(), + searching: "Looking…".into(), + no_matches: "No matches".into(), + add_address: "Press Return to share with this address".into(), + group: "group".into(), + permission: "They may".into(), + can_view: "View".into(), + can_edit: "Edit".into(), + note: "Note (optional)".into(), + notify: "Notify by email".into(), + no_mail: "This server cannot send mail".into(), + share: "Share".into(), + sharing: "Sharing…".into(), + close: "Close".into(), + remove: "Remove".into(), + shared_with: "Shared with".into(), + not_shared_with: "Not shared with".into(), + access: "Who has access".into(), + access_empty: "Nobody else yet".into(), + loading: "Loading…".into(), + withdraw: "Withdraw".into(), + withdrawing: "Withdrawing…".into(), + copy_link: "Copy link".into(), + anyone_with_link: "Anyone with the link".into(), + save_first: "Save this document to the cloud before sharing it.".into(), + can_edit_detail: "Make any changes".into(), + can_view_detail: "Cannot make changes".into(), + message_hint: "Add a message".into(), + send: "Send".into(), + manage_access: "Who has access".into(), + upload_first: "Save this document somewhere to share it.".into(), + name_hint: "Name this document".into(), + saving: "Saving\u{2026}".into(), + save_and_share: "Save and share".into(), + sign_in: "Sign in".into(), + attach_instead: "Attach a copy instead".into(), + create_link: "Get a link".into(), + key_hint: "Key (optional)".into(), + key_required_note: "This server requires a key on a link.".into(), + link_copied: "Link copied".into(), + } + } +} + +/// What the provider behind the service actually does. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +struct Provider { + sharing: bool, + contacts: bool, + mail: bool, + /// Public links at all. An administrator can forbid them. + links: bool, + /// A key on a link. + key: bool, + /// The server insists on one, so a link cannot be made without it. + key_required: bool, +} + +/// One contact picture, asked for at most once. +#[derive(Clone, Debug, PartialEq, Eq)] +enum Avatar { + /// Asked for under this sequence number; nothing to paint yet. + Pending(u64), + /// Bytes handed to egui under this URI, for the application's image + /// loaders to decode. + Ready(String), + /// Asked once and refused. Initials are painted instead, and it is never + /// asked for again. + Missing, +} + +/// Somebody the user has picked. +#[derive(Clone, Debug, PartialEq, Eq)] +struct Chosen { + target: ShareTarget, + label: String, + detail: Option, + avatar: Option, +} + +/// The dialog's state while it is open on one document. +struct Sheet { + id: String, + title: String, + query: String, + /// When the query last changed, for the debounce. `None` when settled. + typed: Option, + /// The newest lookup asked for. An answer to anything older is dropped. + lookup: Option, + searching: bool, + matches: Vec, + chosen: Vec, + permission: Permission, + note: String, + notify: bool, + /// Who already has access. `None` until the answer arrives. + access: Option>, + access_seq: Option, + /// Withdrawals in flight, as (request, share). + withdrawing: Vec<(u64, String)>, + granting: Option, + /// Where it could be saved. `None` until the answer arrives. + destinations: Option>, + destinations_seq: Option, + link_seq: Option, + /// Which one is selected, by id. + destination: Option, + /// The name typed while the document still has nowhere to live. + save_as: String, + /// The save in flight, if one is. + saving: Option, + save_error: Option, + /// The key to put on a link, while one is being made. + link_key: String, + /// The last share's outcome, kept on screen until the next one. + shared: Vec, + failed: Vec, + /// A refusal that stopped a whole call, as opposed to one recipient. + error: Option, +} + +impl Sheet { + fn new(id: String, title: String) -> Sheet { + Sheet { + destinations: None, + destinations_seq: None, + link_seq: None, + destination: None, + save_as: title.clone(), + saving: None, + save_error: None, + link_key: String::new(), + id, + title, + query: String::new(), + typed: None, + lookup: None, + searching: false, + matches: Vec::new(), + chosen: Vec::new(), + permission: Permission::View, + note: String::new(), + notify: true, + access: None, + access_seq: None, + withdrawing: Vec::new(), + granting: None, + shared: Vec::new(), + failed: Vec::new(), + error: None, + } + } +} + +/// Something the drawing pass decided and the dialog carries out afterwards. +/// +/// Drawing holds the open sheet, so it cannot also reach the request channel. +/// Collecting intentions and acting on them once the frame is painted keeps +/// both honest. +enum Act { + Lookup(String), + /// Save a document that has nowhere to live yet, into one destination. + SaveAs { + destination: String, + name: String, + }, + /// Connect an account for a destination that has none. + Link(String), + Grant(Grant), + Withdraw(String), + Avatar(String), + Close, +} + +/// A save the dialog is waiting on the application to do. +/// +/// Taken once. The application serialises the open document, puts it where +/// `destination` says, and reports back with [`ShareDialog::saved`] or +/// [`ShareDialog::save_failed`]. Prefer [`ShareDialog::saved_if`] / +/// [`ShareDialog::save_failed_if`] with [`SaveRequest::generation`] when the +/// save is asynchronous, so a completion for a closed or replaced sheet is +/// dropped without the application inventing its own epoch. +#[derive(Clone, Debug, PartialEq, Eq)] +pub struct SaveRequest { + /// Which destination, as the dialog was told by [`Destination::id`]. + pub destination: String, + /// What the user called it. + pub name: String, + /// Open-sheet generation when this request was taken. Pass to + /// [`ShareDialog::saved_if`] / [`ShareDialog::save_failed_if`]. + pub generation: u64, +} + +/// What the dialog may offer this frame. +#[derive(Clone, Copy)] +struct Allowed { + contacts: bool, + mail: bool, + links: bool, + key: bool, + key_required: bool, +} + +/// A share dialog. +/// +/// Create one per window, call [`ShareDialog::connect`] once a backend exists, +/// call [`ShareDialog::show`] every frame, and open it from a Share control +/// that is drawn only while [`ShareDialog::available`] is true. +pub struct ShareDialog { + backend: Option>, + tx: Sender, + rx: Receiver, + seq: u64, + provider: Option, + /// When the capability question was last asked. + asked: Option, + open: Option, + /// Keyed by the URL the contact carried, so reopening the dialog does not + /// fetch the same faces again. + avatars: HashMap, + /// A save the application has not picked up yet. + wants_save: Option, + /// Bumped on every [`ShareDialog::open`] and [`ShareDialog::close`]. A save + /// completion from an earlier open is ignored when this no longer matches + /// [`ShareDialog::pending_save_generation`]. + sheet_generation: u64, + /// Generation of the open sheet when [`ShareDialog::take_save_request`] + /// last handed a save to the application. + pending_save_generation: Option, + labels: ShareLabels, +} + +impl Default for ShareDialog { + fn default() -> ShareDialog { + ShareDialog::new() + } +} + +impl ShareDialog { + pub fn new() -> ShareDialog { + let (tx, rx) = std::sync::mpsc::channel(); + ShareDialog { + backend: None, + tx, + rx, + seq: 0, + provider: None, + asked: None, + open: None, + avatars: HashMap::new(), + wants_save: None, + sheet_generation: 0, + pending_save_generation: None, + labels: ShareLabels::default(), + } + } + + /// Attach the thing that does the waiting. + /// + /// The first frame after this asks what the provider can do, which is what + /// decides whether sharing is offered at all. + pub fn connect(&mut self, backend: impl ShareBackend + 'static) { + self.backend = Some(Box::new(backend)); + self.provider = None; + self.asked = None; + } + + pub fn connected(&self) -> bool { + self.backend.is_some() + } + + /// Replace the dialog's strings, for a localized application. + pub fn with_labels(mut self, labels: ShareLabels) -> ShareDialog { + self.labels = labels; + self + } + + pub fn labels_mut(&mut self) -> &mut ShareLabels { + &mut self.labels + } + + /// Whether sharing can be offered. + /// + /// False until the service says the provider supports it and an account is + /// linked. An application draws no Share control while this is false: a + /// hidden feature is better than a button that fails on use. + /// Ask the provider again what it can do. + /// + /// The answer is kept once it arrives, so a host that signs somebody + /// in after the first answer has to say so. Without this the dialog + /// keeps the answer it got while nobody was signed in, and Share + /// stays unavailable for the rest of the run. + pub fn refresh(&mut self) { + self.provider = None; + self.asked = None; + } + + pub fn available(&self) -> bool { + self.provider.is_some_and(|p| p.sharing) + } + + /// Open on one document. + /// + /// `id` is the handle the application was given for it, passed back + /// untouched. An empty one means the document has never been saved to the + /// cloud, which the dialog says rather than failing on Share. Does nothing + /// while sharing is unavailable. + pub fn open(&mut self, id: impl Into, title: impl Into) { + if !self.available() { + return; + } + self.sheet_generation = self.sheet_generation.wrapping_add(1); + self.wants_save = None; + let id = id.into(); + self.open = Some(Sheet::new(id.clone(), title.into())); + if id.is_empty() { + // Nothing to share yet, so the dialog opens on the places it could + // go. Asked for here rather than on the first frame, so the list is + // usually there by the time anybody looks. + let seq = self.issue(Request::Destinations); + if let Some(sheet) = &mut self.open { + sheet.destinations_seq = Some(seq); + } + } + if !id.is_empty() { + let seq = self.issue(Request::Access { id }); + if let Some(sheet) = &mut self.open { + sheet.access_seq = Some(seq); + } + } + } + + /// A save the application should perform, if one was asked for. + /// + /// Taken, so it is handled once. Stamps [`SaveRequest::generation`] with + /// the open sheet's generation. Call [`ShareDialog::saved`] / + /// [`ShareDialog::save_failed`] (dialog-side pending guard) or + /// [`ShareDialog::saved_if`] / [`ShareDialog::save_failed_if`] with that + /// generation when the work finishes; otherwise the dialog waits. + pub fn take_save_request(&mut self) -> Option { + let mut request = self.wants_save.take()?; + request.generation = self.sheet_generation; + self.pending_save_generation = Some(request.generation); + Some(request) + } + + /// The document was saved, and this is the handle the provider issued. + /// + /// Ignored when the dialog has closed, reopened on another document, or + /// taken a newer save since [`ShareDialog::take_save_request`]. + pub fn saved(&mut self, id: impl Into, name: impl Into) { + if !self.save_completion_applies() { + return; + } + self.pending_save_generation = None; + self.finish_saved(id, name); + } + + /// Like [`ShareDialog::saved`], but applies only when `generation` matches + /// the open sheet's generation. + pub fn saved_if(&mut self, generation: u64, id: impl Into, name: impl Into) { + if self.open.is_none() || self.sheet_generation != generation { + return; + } + self.pending_save_generation = None; + self.finish_saved(id, name); + } + + /// The save did not happen, and this is why. + /// + /// Ignored under the same conditions as [`ShareDialog::saved`]. + pub fn save_failed(&mut self, reason: impl Into) { + if !self.save_completion_applies() { + return; + } + self.pending_save_generation = None; + if let Some(sheet) = &mut self.open { + sheet.saving = None; + sheet.save_error = Some(reason.into()); + } + } + + /// Like [`ShareDialog::save_failed`], but applies only when `generation` + /// matches the open sheet's generation. + pub fn save_failed_if(&mut self, generation: u64, reason: impl Into) { + if self.open.is_none() || self.sheet_generation != generation { + return; + } + self.pending_save_generation = None; + if let Some(sheet) = &mut self.open { + sheet.saving = None; + sheet.save_error = Some(reason.into()); + } + } + + /// Generation of the sheet currently open, for callers that track their + /// own save epoch. Zero when the dialog is closed. + pub fn sheet_generation(&self) -> u64 { + if self.open.is_some() { self.sheet_generation } else { 0 } + } + + fn save_completion_applies(&self) -> bool { + self.pending_save_generation.is_some_and(|g| g == self.sheet_generation) + } + + fn finish_saved(&mut self, id: impl Into, name: impl Into) { + if self.open.is_none() { + return; + } + let id = id.into(); + if let Some(sheet) = &mut self.open { + sheet.saving = None; + sheet.save_error = None; + sheet.id = id.clone(); + sheet.title = name.into(); + } + // The document exists now, so ask who already has access, exactly as + // opening on a saved document would. + let seq = self.issue(Request::Access { id }); + if let Some(sheet) = &mut self.open { + sheet.access_seq = Some(seq); + } + } + + pub fn is_open(&self) -> bool { + self.open.is_some() + } + + pub fn close(&mut self) { + self.open = None; + self.sheet_generation = self.sheet_generation.wrapping_add(1); + self.wants_save = None; + } + + /// Who the last share reached, and who it did not. + pub fn outcome(&self) -> (&[Share], &[Failure]) { + match &self.open { + Some(sheet) => (&sheet.shared, &sheet.failed), + None => (&[], &[]), + } + } + + /// The recipient field's id, for an application that wants to focus it. + pub fn query_field_id() -> Id { + Id::unique(QUERY) + } + + /// One frame, as a modal over the window. Call this unconditionally: + /// answers are collected here whether the dialog is open or not. + pub fn show(&mut self, ctx: &Context) { + self.collect(ctx); + if self.open.is_none() { + return; + } + let modal = egui::Modal::new(Id::unique("craft-ui/share")).show(ctx, |ui| { + ui.set_min_width(440.0); + ui.set_max_width(560.0); + self.contents(ui); + }); + if modal.should_close() { + self.close(); + } + } + + /// One frame's contents without the modal chrome, for an application that + /// hosts the dialog in its own panel. + pub fn show_in(&mut self, ui: &mut Ui) { + self.collect(ui.ctx()); + if self.open.is_some() { + self.contents(ui); + } + } + + fn contents(&mut self, ui: &mut Ui) { + let allowed = match self.provider { + Some(p) => Allowed { contacts: p.contacts, mail: p.mail, links: p.links, key: p.key, key_required: p.key_required }, + None => Allowed { contacts: false, mail: false, links: false, key: false, key_required: false }, + }; + let mut acts = Vec::new(); + { + let Some(sheet) = self.open.as_mut() else { return }; + draw(ui, sheet, &self.avatars, &self.labels, allowed, &mut acts); + } + self.apply(ui.ctx(), acts); + } + + // ---- the channel ------------------------------------------------------ + + fn issue(&mut self, request: Request) -> u64 { + self.seq += 1; + let seq = self.seq; + if let Some(backend) = &self.backend { + backend.submit(request, Replier::new(seq, self.tx.clone())); + } + seq + } + + fn collect(&mut self, ctx: &Context) { + while let Ok((seq, result)) = self.rx.try_recv() { + self.receive(ctx, seq, result); + } + let now = ctx.input(|i| i.time); + if self.backend.is_some() && self.provider.is_none() && self.asked.is_none_or(|at| now - at >= RETRY) { + self.asked = Some(now); + self.issue(Request::Capabilities); + } + } + + fn receive(&mut self, ctx: &Context, seq: u64, result: Result) { + let answer = match result { + Ok(answer) => answer, + Err(reason) => return self.refused(seq, reason), + }; + // Set while an answer leaves something else worth asking for; issued + // once the open sheet is no longer borrowed. + let mut reload = None; + match answer { + Answer::Capabilities { capabilities, linked } => { + self.provider = Some(Provider { + sharing: linked && capabilities.contains(&Capability::Sharing), + contacts: capabilities.contains(&Capability::Contacts), + // ShareNotify, not Mail. Mail means "can send arbitrary + // mail"; this box only asks the provider to tell the + // person being shared with, which is a far smaller claim + // and one most providers can honour. + mail: capabilities.contains(&Capability::ShareNotify), + links: capabilities.contains(&Capability::LinkShares), + key: capabilities.contains(&Capability::LinkPassword), + key_required: capabilities.contains(&Capability::LinkPasswordRequired), + }); + // A provider that cannot share must not leave a dialog up that + // was opened while the answer was still outstanding. + if !self.available() { + self.close(); + } + } + Answer::Lookup(found) => { + if let Some(sheet) = &mut self.open + && sheet.lookup == Some(seq) + { + sheet.matches = found; + sheet.searching = false; + } + } + Answer::Access(list) => { + if let Some(sheet) = &mut self.open + && sheet.access_seq == Some(seq) + { + sheet.access = Some(list); + sheet.access_seq = None; + } + } + Answer::Granted { shared, failed } => { + // A link was asked for in order to be handed out, so it goes + // to the clipboard without a second click. + if let Some(url) = shared.iter().find_map(|s| s.url.clone()) { + ctx.copy_text(url); + } + if let Some(sheet) = &mut self.open + && sheet.granting == Some(seq) + { + sheet.granting = None; + sheet.error = None; + // Recipients that went through leave the picker. The ones + // that did not stay in it, so a corrected retry is one + // press rather than a retyped list. + sheet.chosen.retain(|c| failed.iter().any(|f| f.target == c.target)); + sheet.shared = shared; + sheet.failed = failed; + if !sheet.shared.is_empty() { + reload = Some(sheet.id.clone()); + } + } + } + Answer::Destinations(list) => { + if let Some(sheet) = &mut self.open + && sheet.destinations_seq == Some(seq) + { + // One destination and nothing to choose between: pick it, + // so the only linked account is not a click somebody has + // to make for no reason. + if sheet.destination.is_none() + && let [only] = list.as_slice() + && only.linked + { + sheet.destination = Some(only.id.clone()); + } + sheet.destinations = Some(list); + sheet.destinations_seq = None; + } + } + Answer::Linked => { + // An account arrived, so the list is stale. + if let Some(sheet) = &mut self.open { + sheet.destinations = None; + } + let seq = self.issue(Request::Destinations); + if let Some(sheet) = &mut self.open { + sheet.destinations_seq = Some(seq); + } + } + Answer::Withdrawn { share_id } => { + if let Some(sheet) = &mut self.open { + sheet.withdrawing.retain(|(_, id)| *id != share_id); + if let Some(access) = &mut sheet.access { + access.retain(|s| s.id != share_id); + } + sheet.shared.retain(|s| s.id != share_id); + } + } + Answer::Avatar { url, bytes } => { + let uri = avatar_uri(&url); + ctx.include_bytes(uri.clone(), bytes); + self.avatars.insert(url, Avatar::Ready(uri)); + } + } + if let Some(id) = reload { + let seq = self.issue(Request::Access { id }); + if let Some(sheet) = &mut self.open { + sheet.access_seq = Some(seq); + } + } + } + + /// One request came back with a reason instead of an answer. + fn refused(&mut self, seq: u64, reason: String) { + // A picture nobody can fetch is not worth telling the user about, and + // is never asked for again. + if let Some(url) = self.avatars.iter().find(|(_, a)| **a == Avatar::Pending(seq)).map(|(url, _)| url.clone()) { + self.avatars.insert(url, Avatar::Missing); + return; + } + let Some(sheet) = &mut self.open else { return }; + if sheet.lookup == Some(seq) { + sheet.searching = false; + sheet.matches.clear(); + sheet.error = Some(reason); + } else if sheet.access_seq == Some(seq) { + sheet.access_seq = None; + sheet.access = Some(Vec::new()); + sheet.error = Some(reason); + } else if sheet.granting == Some(seq) { + sheet.granting = None; + sheet.error = Some(reason); + } else if sheet.withdrawing.iter().any(|(s, _)| *s == seq) { + sheet.withdrawing.retain(|(s, _)| *s != seq); + sheet.error = Some(reason); + } else if sheet.destinations_seq == Some(seq) { + sheet.destinations_seq = None; + sheet.destinations = Some(Vec::new()); + sheet.save_error = Some(reason); + } else if sheet.link_seq == Some(seq) { + sheet.link_seq = None; + sheet.save_error = Some(reason); + } + } + + fn apply(&mut self, ctx: &Context, acts: Vec) { + for act in acts { + match act { + Act::Close => self.close(), + Act::Lookup(query) => { + let seq = self.issue(Request::Lookup { query, limit: MATCHES }); + if let Some(sheet) = &mut self.open { + sheet.lookup = Some(seq); + sheet.searching = true; + } + } + Act::Grant(grant) => { + let seq = self.issue(Request::Grant(grant)); + if let Some(sheet) = &mut self.open { + sheet.granting = Some(seq); + sheet.shared.clear(); + sheet.failed.clear(); + sheet.error = None; + } + } + Act::SaveAs { destination, name } => { + // Handed to the application rather than the backend. Only + // it can turn the open document into bytes, and a share + // transport is the wrong place to pass a workbook through. + // `generation` is filled when taken; zero here is a placeholder. + self.wants_save = Some(SaveRequest { destination, name, generation: 0 }); + if let Some(sheet) = &mut self.open { + sheet.saving = Some(0); + sheet.save_error = None; + } + } + Act::Link(destination) => { + // The answer to this is usually a refusal carrying the URL + // to open, because launching a browser is the host + // application's business and not this crate's. + let seq = self.issue(Request::Link { destination }); + if let Some(sheet) = &mut self.open { + sheet.link_seq = Some(seq); + sheet.error = None; + } + } + Act::Withdraw(share_id) => { + let seq = self.issue(Request::Withdraw { share_id: share_id.clone() }); + if let Some(sheet) = &mut self.open { + sheet.withdrawing.push((seq, share_id)); + } + } + Act::Avatar(url) => { + if self.avatars.contains_key(&url) { + continue; + } + if self.avatars.len() >= AVATARS { + for (_, avatar) in self.avatars.drain() { + if let Avatar::Ready(uri) = avatar { + ctx.forget_image(&uri); + } + } + } + let seq = self.issue(Request::Avatar { url: url.clone() }); + self.avatars.insert(url, Avatar::Pending(seq)); + } + } + } + } +} + +// ---- drawing -------------------------------------------------------------- + +fn draw(ui: &mut Ui, sheet: &mut Sheet, avatars: &HashMap, labels: &ShareLabels, allowed: Allowed, acts: &mut Vec) { + let weak = ui.visuals().weak_text_color(); + let danger = ui.visuals().error_fg_color; + + // The document is named in the title, in quotes. This dialog gives other + // people access to one specific thing, and sharing the wrong one is the + // mistake it exists to prevent. + ui.horizontal(|ui| { + let heading = if sheet.title.is_empty() { labels.title.clone() } else { format!("{} \u{201c}{}\u{201d}", labels.title, sheet.title) }; + ui.label(RichText::new(heading).strong().size(15.0)); + ui.with_layout(Layout::right_to_left(Align::Center), |ui| { + let close = egui::Button::new(RichText::new("\u{00d7}").size(18.0)).frame(false); + if ui.add(close).on_hover_text(labels.close.as_str()).clicked() { + acts.push(Act::Close); + } + }); + }); + ui.add_space(8.0); + + // Nothing to share yet. The old build stopped here with a sentence and a + // Close button, naming the obstacle and leaving somebody to deal with it + // elsewhere. Saving is the first step of sharing now. + if sheet.id.is_empty() { + save_first(ui, sheet, labels, acts); + return; + } + + // Who, and what they may do, on one row. The permission applies to these + // recipients, so it belongs beside them. A separate pair of radio buttons + // further down reads as an unrelated setting. + ui.horizontal_top(|ui| { + let width = (ui.available_width() - 104.0).max(160.0); + ui.allocate_ui(egui::vec2(width, 0.0), |ui| { + recipients(ui, sheet, avatars, labels, allowed, acts); + }); + permission_menu(ui, sheet, labels); + }); + // Only once something has actually been asked. "No matches" under an + // untouched field reads as a failure before any search ran. + if sheet.searching || !sheet.matches.is_empty() || sheet.query.trim().chars().count() >= MIN_QUERY { + matches(ui, sheet, avatars, labels, allowed, acts); + } + + ui.add_space(6.0); + + // The message, as a bordered area with its own placeholder. People write a + // sentence here, not a value, and a label above a one-line field invites + // neither. + // TextEdit draws its own border, so no group around it. Wrapping one in a + // Frame::group gives two nested borders. + ui.add( + egui::TextEdit::multiline(&mut sheet.note) + .hint_text(labels.message_hint.as_str()) + .desired_width(f32::INFINITY) + .desired_rows(3) + .char_limit(500), + ); + + ui.add_space(8.0); + + // One primary action, on the right where the eye finishes. Notify sits + // beside it rather than loose in the middle of the form. + // A link, for anybody who has no account. Drawn only where the server + // allows public links, because an administrator can forbid them and a + // button that always fails is worse than no button. + if allowed.links { + ui.horizontal(|ui| { + if allowed.key { + ui.add(egui::TextEdit::singleline(&mut sheet.link_key).hint_text(labels.key_hint.as_str()).password(true).desired_width(150.0)); + } + // A key the server insists on cannot be skipped, so the control + // stays disabled until one is typed. + let keyed = !sheet.link_key.trim().is_empty(); + let ready = keyed || !allowed.key_required; + if ui.add_enabled(ready, egui::Button::new(labels.create_link.as_str())).clicked() { + acts.push(Act::Grant(Grant { + id: sheet.id.clone(), + targets: vec![ShareTarget::Link], + permission: sheet.permission, + note: Some(sheet.note.trim().to_owned()).filter(|n| !n.is_empty()), + notify: false, + password: Some(sheet.link_key.trim().to_owned()).filter(|k| !k.is_empty()), + })); + } + if allowed.key_required && !keyed { + ui.label(RichText::new(labels.key_required_note.as_str()).small().color(weak)); + } + }); + ui.add_space(6.0); + } + + ui.horizontal(|ui| { + if allowed.mail { + ui.checkbox(&mut sheet.notify, labels.notify.as_str()); + } else { + // Reported, never assumed. A server with no mail is said to have + // none, instead of being given a box that quietly does nothing. + sheet.notify = false; + ui.add_enabled(false, egui::Checkbox::new(&mut sheet.notify, labels.notify.as_str())).on_disabled_hover_text(labels.no_mail.as_str()); + } + + ui.with_layout(Layout::right_to_left(Align::Center), |ui| { + let busy = sheet.granting.is_some(); + let ready = !sheet.chosen.is_empty() && !busy; + let label = if busy { labels.sharing.clone() } else { labels.send.clone() }; + let send = egui::Button::new(RichText::new(label).strong()).fill(ui.visuals().selection.bg_fill).min_size(egui::vec2(88.0, 26.0)); + if ui.add_enabled(ready, send).clicked() { + acts.push(Act::Grant(Grant { + id: sheet.id.clone(), + password: None, + targets: sheet.chosen.iter().map(|c| c.target.clone()).collect(), + permission: sheet.permission, + note: Some(sheet.note.trim().to_owned()).filter(|n| !n.is_empty()), + notify: sheet.notify, + })); + } + if ui.button(labels.close.as_str()).clicked() { + acts.push(Act::Close); + } + }); + }); + + outcome(ui, sheet, labels, danger); + + // Who already holds the document, open. Folding it hid the one fact + // a person needs before adding anybody else. It still folds on request. + ui.add_space(4.0); + egui::CollapsingHeader::new(RichText::new(labels.manage_access.as_str()).color(weak)) + .id_salt("craft-ui/share/manage-access") + .default_open(true) + .show(ui, |ui| { + access(ui, sheet, labels, weak, acts); + }); +} + +/// Where to put it, then what to call it. +/// +/// A document with no handle cannot be shared. Rather than saying so and +/// stopping, this offers the places it could go, each naming the account it +/// would land in, with a sign-in for any that is configured without one. +/// +/// A list, because there is rarely only one answer. A second provider is an +/// implementation of the contracts, and this is where it shows up. +fn save_first(ui: &mut Ui, sheet: &mut Sheet, labels: &ShareLabels, acts: &mut Vec) { + let weak = ui.visuals().weak_text_color(); + ui.label(labels.upload_first.as_str()); + ui.add_space(8.0); + + let Some(destinations) = sheet.destinations.clone() else { + ui.horizontal(|ui| { + ui.spinner(); + ui.label(RichText::new(labels.loading.as_str()).color(weak)); + }); + return; + }; + + for destination in &destinations { + let chosen = sheet.destination.as_deref() == Some(destination.id.as_str()); + let stroke = if chosen { ui.visuals().selection.stroke } else { ui.visuals().widgets.noninteractive.bg_stroke }; + let row = egui::Frame::group(ui.style()) + .stroke(stroke) + .show(ui, |ui| { + ui.set_width(ui.available_width()); + ui.horizontal(|ui| { + ui.vertical(|ui| { + ui.label(RichText::new(destination.name.as_str()).strong()); + // The account, because two entries both reading + // "Cloud" tell nobody which one a document is about to + // land in. + let under = if destination.linked { destination.account.clone().unwrap_or_default() } else { labels.sign_in.clone() }; + ui.label(RichText::new(under).small().color(weak)); + }); + }); + }) + .response + .interact(egui::Sense::click()); + if row.clicked() { + if destination.linked { + sheet.destination = Some(destination.id.clone()); + } else { + acts.push(Act::Link(destination.id.clone())); + } + } + ui.add_space(4.0); + } + + if let Some(problem) = &sheet.save_error { + ui.add_space(4.0); + ui.label(RichText::new(problem).color(ui.visuals().error_fg_color)); + } + + let Some(into) = sheet.destination.clone() else { return }; + + ui.add_space(8.0); + let saving = sheet.saving.is_some(); + ui.add_enabled(!saving, egui::TextEdit::singleline(&mut sheet.save_as).hint_text(labels.name_hint.as_str()).desired_width(f32::INFINITY)); + + ui.add_space(8.0); + ui.horizontal(|ui| { + let named = !sheet.save_as.trim().is_empty(); + let label = if saving { labels.saving.clone() } else { labels.save_and_share.clone() }; + let button = egui::Button::new(RichText::new(label).strong()).fill(ui.visuals().selection.bg_fill).min_size(egui::vec2(124.0, 26.0)); + if ui.add_enabled(named && !saving, button).clicked() { + acts.push(Act::SaveAs { destination: into.clone(), name: sheet.save_as.trim().to_owned() }); + } + if ui.button(labels.close.as_str()).clicked() { + acts.push(Act::Close); + } + }); +} + +/// The permission picker, as a menu with a line of explanation under each +/// choice. +/// +/// Two radio buttons reading View and Edit leave the difference to be guessed. +/// Only the permissions the contracts can actually keep are offered: a choice +/// the server cannot honour is worse than one fewer choice. +fn permission_menu(ui: &mut Ui, sheet: &mut Sheet, labels: &ShareLabels) { + let current = match sheet.permission { + Permission::Edit => labels.can_edit.as_str(), + Permission::View => labels.can_view.as_str(), + }; + // A triangle, so it reads as something that opens. Painted rather than + // typed: the character is missing from the default font set, where it + // renders as a box. + let button = ui.button(format!("{current} ")); + crate::buttons::chevron(ui, button.rect, ui.visuals().text_color()); + // The padding makes room for the triangle. It is layout, so it must not + // reach anybody reading the screen aloud. + button.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, true, current)); + egui::Popup::menu(&button).show(|ui| { + ui.set_min_width(190.0); + for (value, name, detail) in [ + (Permission::Edit, labels.can_edit.as_str(), labels.can_edit_detail.as_str()), + (Permission::View, labels.can_view.as_str(), labels.can_view_detail.as_str()), + ] { + let chosen = sheet.permission == value; + if ui.selectable_label(chosen, RichText::new(name).strong()).clicked() { + sheet.permission = value; + ui.close(); + } + ui.label(RichText::new(detail).small().color(ui.visuals().weak_text_color())); + ui.add_space(2.0); + } + }); +} + +/// The chips, and the field that adds another. +fn recipients(ui: &mut Ui, sheet: &mut Sheet, avatars: &HashMap, labels: &ShareLabels, allowed: Allowed, acts: &mut Vec) { + let now = ui.input(|i| i.time); + egui::Frame::group(ui.style()).show(ui, |ui| { + ui.horizontal_wrapped(|ui| { + let mut remove = None; + for (i, chosen) in sheet.chosen.iter().enumerate() { + if chip(ui, avatars, chosen, labels, acts).clicked() { + remove = Some(i); + } + } + if let Some(i) = remove.filter(|i| *i < sheet.chosen.len()) { + sheet.chosen.remove(i); + } + + let field = ui.add( + egui::TextEdit::singleline(&mut sheet.query) + .id(ShareDialog::query_field_id()) + .hint_text(labels.recipient_hint.as_str()) + // Fills whatever the chips left. A fixed width leaves a + // short field floating in a frame twice as wide. + .desired_width(ui.available_width().max(120.0)), + ); + if field.changed() { + sheet.typed = Some(now); + } + // Backspace on an empty field takes the last chip back, which is + // what every other recipient field does. + if field.has_focus() && sheet.query.is_empty() && ui.input(|i| i.key_pressed(egui::Key::Backspace)) { + sheet.chosen.pop(); + } + if field.lost_focus() && ui.input(|i| i.key_pressed(egui::Key::Enter)) { + commit(sheet); + } + }); + }); + + // The debounce. Asking per keystroke asks five times for "annie" and + // paints whichever answer happens to arrive last. + if let Some(at) = sheet.typed { + let wait = DEBOUNCE.as_secs_f64(); + if now - at >= wait { + sheet.typed = None; + let query = sheet.query.trim().to_owned(); + if allowed.contacts && query.chars().count() >= MIN_QUERY { + // Set here rather than when the request is issued, so the + // frame that fires it does not read as "no matches". + sheet.searching = true; + acts.push(Act::Lookup(query)); + } else { + sheet.matches.clear(); + sheet.searching = false; + } + } else { + // Without this the frame that fires the lookup only arrives when + // something else happens to ask for a repaint. + ui.ctx().request_repaint_after(Duration::from_secs_f64((wait - (now - at)).clamp(0.0, wait))); + } + } +} + +/// Take whatever has been typed as a recipient: the first match if there is +/// one, otherwise an address if it looks like one. +fn commit(sheet: &mut Sheet) { + let typed = sheet.query.trim().to_lowercase(); + + // An exact match wins. Somebody who typed a whole address that belongs to + // an account should get the account, because a share to an account appears + // in their files rather than only in their inbox. + if let Some(exact) = sheet + .matches + .iter() + .find(|c| c.id.to_lowercase() == typed || c.email.as_deref().is_some_and(|e| e.to_lowercase() == typed) || c.name.to_lowercase() == typed) + .cloned() + { + choose(sheet, &exact); + return; + } + + // Then whatever was typed, if it is an address. The list is a convenience + // and not the set of permitted answers: taking its first row here would + // share with whoever happened to match the opening characters of an + // address somebody typed out in full. + if let Some(address) = address(&sheet.query) { + add(sheet, ShareTarget::Email(address.clone()), address, None, None); + return; + } + + // Otherwise the best the list has, which is what a partial name means. + if let Some(contact) = sheet.matches.first().cloned() { + choose(sheet, &contact); + } +} + +fn matches(ui: &mut Ui, sheet: &mut Sheet, avatars: &HashMap, labels: &ShareLabels, allowed: Allowed, acts: &mut Vec) { + let weak = ui.visuals().weak_text_color(); + // Somebody with no account on this server is reached by address or not at + // all, so the one way to do that is said out loud. A dialog that hides it + // leaves the user guessing which keys work. + if sheet.matches.is_empty() + && address(&sheet.query).is_some() + && !sheet.chosen.iter().any(|c| c.target == ShareTarget::Email(sheet.query.trim().to_owned())) + { + ui.label(RichText::new(labels.add_address.as_str()).color(weak)); + } + if !allowed.contacts { + return; + } + if sheet.searching && sheet.matches.is_empty() { + ui.label(RichText::new(labels.searching.as_str()).color(weak)); + return; + } + if sheet.matches.is_empty() { + if sheet.typed.is_none() && sheet.query.trim().chars().count() >= MIN_QUERY && address(&sheet.query).is_none() { + ui.label(RichText::new(labels.no_matches.as_str()).color(weak)); + } + return; + } + let mut pick = None; + egui::ScrollArea::vertical().max_height(150.0).id_salt("craft-ui/share/matches").show(ui, |ui| { + for (i, contact) in sheet.matches.iter().enumerate() { + if row(ui, avatars, contact, labels, acts).clicked() { + pick = Some(i); + } + } + }); + if let Some(contact) = pick.and_then(|i| sheet.matches.get(i).cloned()) { + choose(sheet, &contact); + } +} + +fn outcome(ui: &mut Ui, sheet: &Sheet, labels: &ShareLabels, danger: Color32) { + if let Some(error) = &sheet.error { + ui.colored_label(danger, error.as_str()); + } + if !sheet.shared.is_empty() { + let who: Vec = sheet.shared.iter().map(|s| share_label(s, labels)).collect(); + ui.label(format!("{}: {}", labels.shared_with, who.join(", "))); + } + // One line each. Five recipients with one bad address shares with four and + // names the one that failed; collapsing that into a single error would + // hide both halves. + for failure in &sheet.failed { + ui.colored_label(danger, format!("{} {}: {}", labels.not_shared_with, target_label(&failure.target, labels), describe(failure))); + } +} + +fn describe(failure: &Failure) -> String { + if failure.detail.trim().is_empty() { failure.code.clone() } else { failure.detail.clone() } +} + +fn access(ui: &mut Ui, sheet: &Sheet, labels: &ShareLabels, weak: Color32, acts: &mut Vec) { + // The header above already names this list. Naming it twice reads as + // two headings for one thing. + let Some(list) = &sheet.access else { + ui.label(RichText::new(labels.loading.as_str()).color(weak)); + return; + }; + if list.is_empty() { + ui.label(RichText::new(labels.access_empty.as_str()).color(weak)); + return; + } + egui::ScrollArea::vertical().max_height(160.0).id_salt("craft-ui/share/access").show(ui, |ui| { + for share in list { + ui.horizontal(|ui| { + ui.label(share_label(share, labels)); + let permission = match share.permission { + Permission::View => labels.can_view.as_str(), + Permission::Edit => labels.can_edit.as_str(), + }; + ui.label(RichText::new(permission).color(weak)); + ui.with_layout(Layout::right_to_left(Align::Center), |ui| { + let busy = sheet.withdrawing.iter().any(|(_, id)| *id == share.id); + // A bin, with the word on hover. The row is already a + // line of text; a second word on it reads as more content + // rather than as the control it is. + let glyph = if busy { "\u{22ef}" } else { "\u{1f5d1}" }; + let bin = egui::Button::new(RichText::new(glyph).size(15.0)).frame(false); + let hint = if busy { labels.withdrawing.as_str() } else { labels.withdraw.as_str() }; + let pressed = ui.add_enabled(!busy, bin); + // A glyph is not a name. Left alone this button announces itself + // to a screen reader as a wastebasket character, so the word goes + // on explicitly. + pressed.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, !busy, hint)); + if pressed.on_hover_text(hint).clicked() { + acts.push(Act::Withdraw(share.id.clone())); + } + if let Some(url) = &share.url + && ui.small_button(labels.copy_link.as_str()).clicked() + { + ui.ctx().copy_text(url.clone()); + } + }); + }); + if let Some(note) = &share.note + && !note.trim().is_empty() + { + ui.label(RichText::new(note.as_str()).color(weak).small()); + } + } + }); +} + +// ---- pieces --------------------------------------------------------------- + +/// One picked recipient. The whole chip is the remove control. +fn chip(ui: &mut Ui, avatars: &HashMap, chosen: &Chosen, labels: &ShareLabels, acts: &mut Vec) -> Response { + let background = ui.painter().add(egui::Shape::Noop); + let inner = ui.scope_builder(UiBuilder::new().sense(Sense::click()), |ui| { + // A selectable label senses click and drag of its own, and one drawn + // inside a clickable row wins the hit test over the row itself. For + // narrow rows like a chip the pointer lands on the text nearly always, + // so the press would be swallowed and the chip never removed. + ui.style_mut().interaction.selectable_labels = false; + ui.horizontal(|ui| { + ui.add_space(3.0); + picture(ui, avatars, chosen.avatar.as_deref(), &chosen.label, acts); + ui.label(chosen.label.as_str()); + // The same cross the dialog closes with. U+2715 is absent from + // the default font set, where it renders as a box. + ui.label(RichText::new("×").color(ui.visuals().weak_text_color())); + ui.add_space(1.0); + }); + }); + let response = inner.response; + let fill = if response.hovered() { ui.visuals().widgets.hovered.bg_fill } else { ui.visuals().widgets.inactive.bg_fill }; + ui.painter().set(background, egui::Shape::rect_filled(response.rect, CornerRadius::same(AVATAR_RADIUS), fill)); + let label = format!("{} {}", labels.remove, chosen.label); + response.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, ui.is_enabled(), label.clone())); + // The address, where there is one. Two colleagues share a display name + // often enough that a chip reading "Ann Reed" is not an identity. + let hint = match &chosen.detail { + Some(detail) if !detail.is_empty() => format!("{} · {detail}", labels.remove), + _ => labels.remove.clone(), + }; + response.on_hover_text(hint) +} + +/// One match in the autocomplete list. +fn row(ui: &mut Ui, avatars: &HashMap, contact: &Contact, labels: &ShareLabels, acts: &mut Vec) -> Response { + let background = ui.painter().add(egui::Shape::Noop); + let width = ui.available_width(); + let inner = ui.scope_builder(UiBuilder::new().sense(Sense::click()), |ui| { + // A selectable label senses click and drag of its own, and one drawn + // inside a clickable row wins the hit test over the row itself. For + // narrow rows like a chip the pointer lands on the text nearly always, + // so the press would be swallowed and the chip never removed. + ui.style_mut().interaction.selectable_labels = false; + ui.set_min_width(width); + ui.horizontal(|ui| { + ui.add_space(3.0); + picture(ui, avatars, contact.avatar.as_deref(), &contact.name, acts); + ui.label(contact.name.as_str()); + let detail = if contact.is_group { format!("({})", labels.group) } else { contact.email.clone().unwrap_or_default() }; + if !detail.is_empty() { + ui.label(RichText::new(detail).color(ui.visuals().weak_text_color())); + } + }); + }); + let response = inner.response; + if response.hovered() { + ui.painter().set(background, egui::Shape::rect_filled(response.rect, CornerRadius::same(4), ui.visuals().widgets.hovered.bg_fill)); + } + let label = contact.name.clone(); + response.widget_info(|| egui::WidgetInfo::labeled(egui::Role::Button, ui.is_enabled(), label.clone())); + response +} + +/// A contact picture, or initials while there is none. +/// +/// A picture is asked for here, as the row that needs it is painted, and only +/// when that row is actually on screen. A search answering with ten people +/// therefore costs no pictures at all until they are looked at, and the ones +/// scrolled past below the fold cost nothing either. `avatars` holds every URL +/// ever asked about, the refusals included, so nothing is asked for twice. +fn picture(ui: &mut Ui, avatars: &HashMap, url: Option<&str>, label: &str, acts: &mut Vec) { + let size = Vec2::splat(AVATAR); + let (rect, _) = ui.allocate_exact_size(size, Sense::hover()); + match url.and_then(|u| avatars.get(u)) { + Some(Avatar::Ready(uri)) => { + let image = egui::Image::from_uri(uri.clone()).fit_to_exact_size(size).corner_radius(CornerRadius::same(AVATAR_RADIUS)); + if image.load_for_size(ui.ctx(), size).is_ok() { + image.paint_at(ui, rect); + return; + } + } + Some(_) => {} + None => { + if let Some(url) = url.filter(|_| ui.is_rect_visible(rect)) { + acts.push(Act::Avatar(url.to_owned())); + } + } + } + ui.painter().circle_filled(rect.center(), AVATAR / 2.0, ui.visuals().widgets.inactive.bg_fill); + ui.painter().text(rect.center(), Align2::CENTER_CENTER, initials(label), FontId::proportional(AVATAR * 0.42), ui.visuals().text_color()); +} + +fn initials(label: &str) -> String { + label.split_whitespace().filter_map(|word| word.chars().next()).take(2).flat_map(|c| c.to_uppercase()).collect() +} + +/// A stable URI for one avatar's bytes. egui caches by URI, so two contacts +/// must never share one. +fn avatar_uri(url: &str) -> String { + use std::hash::{Hash as _, Hasher as _}; + let mut hasher = std::hash::DefaultHasher::new(); + url.hash(&mut hasher); + format!("bytes://craft-ui/share/avatar/{:016x}", hasher.finish()) +} + +fn choose(sheet: &mut Sheet, contact: &Contact) { + // What the provider said, never a guess from the id. A contact with no + // account is reachable only by address, and sharing that address as a user + // id fails with "not found", because no such user exists. + let target = contact.target.clone(); + add(sheet, target, contact.name.clone(), contact.email.clone(), contact.avatar.clone()); +} + +/// Add one recipient, unless it is already there. +fn add(sheet: &mut Sheet, target: ShareTarget, label: String, detail: Option, avatar: Option) { + if !sheet.chosen.iter().any(|c| c.target == target) { + sheet.chosen.push(Chosen { target, label, detail, avatar }); + } + sheet.query.clear(); + sheet.matches.clear(); + sheet.typed = None; + sheet.searching = false; + sheet.lookup = None; +} + +/// What the user typed, when it is an address and not a name. +/// +/// Deliberately shallow. The server decides whether an address exists, and a +/// strict local check would refuse valid addresses it had not heard of. +fn address(typed: &str) -> Option { + let typed = typed.trim(); + if typed.chars().any(char::is_whitespace) { + return None; + } + let (user, host) = typed.split_once('@')?; + if user.is_empty() || host.len() < 3 || !host.contains('.') || host.starts_with('.') || host.ends_with('.') || host.contains('@') { + return None; + } + Some(typed.to_owned()) +} + +/// What to call the person or group a share is with. +/// +/// The handle is the fallback. Showing an account id to somebody who knows +/// that person by name tells them nothing, and two colleagues with similar +/// ids are indistinguishable. +fn share_label(share: &Share, labels: &ShareLabels) -> String { + match share.display.as_deref().filter(|name| !name.trim().is_empty()) { + Some(name) => match share.target { + ShareTarget::Group(_) => format!("{name} ({})", labels.group), + _ => name.to_owned(), + }, + None => target_label(&share.target, labels), + } +} + +fn target_label(target: &ShareTarget, labels: &ShareLabels) -> String { + match target { + ShareTarget::User(id) => id.clone(), + ShareTarget::Group(id) => format!("{id} ({})", labels.group), + ShareTarget::Email(address) => address.clone(), + ShareTarget::Link => labels.anyone_with_link.clone(), + } +} diff --git a/crates/cloud-ui/src/share/tests.rs b/crates/cloud-ui/src/share/tests.rs new file mode 100644 index 000000000..dfdb3eb1e --- /dev/null +++ b/crates/cloud-ui/src/share/tests.rs @@ -0,0 +1,527 @@ +//! The dialog's state machine, with no server and no window. +//! +//! What matters here is what the dialog does with answers: that it offers +//! nothing until the service says sharing exists, that an answer the user has +//! typed past is thrown away rather than painted, that a share reaching four +//! of five people says which one it missed, and that a picture nobody can +//! fetch is asked for once. + +use std::sync::{Arc, Mutex}; + +use super::*; + +/// A backend that records what was asked and answers nothing, so a test +/// decides when each answer arrives and in which order. +#[derive(Clone, Default)] +struct Silent(Arc>>); + +impl Silent { + fn seen(&self) -> Vec { + self.0.lock().map(|seen| seen.clone()).unwrap_or_default() + } +} + +impl ShareBackend for Silent { + fn submit(&self, request: Request, _reply: Replier) { + if let Ok(mut seen) = self.0.lock() { + seen.push(request); + } + } +} + +fn can(capabilities: Vec) -> Answer { + Answer::Capabilities { capabilities, linked: true } +} + +fn everything() -> Answer { + can(vec![Capability::Sharing, Capability::Contacts, Capability::Mail]) +} + +/// A connected dialog that has been told sharing works, open on one document. +fn ready() -> (Context, ShareDialog, Silent) { + let ctx = Context::default(); + let backend = Silent::default(); + let mut dialog = ShareDialog::new(); + dialog.connect(backend.clone()); + dialog.collect(&ctx); + dialog.receive(&ctx, 1, Ok(everything())); + dialog.open("files/budget.xlsx", "Budget"); + (ctx, dialog, backend) +} + +fn person(id: &str, name: &str) -> Contact { + Contact { + id: id.into(), + target: ShareTarget::User(id.into()), + name: name.into(), + email: Some(format!("{id}@example.com")), + avatar: None, + is_group: false, + } +} + +fn share(id: &str, target: ShareTarget) -> Share { + Share { id: id.into(), target, display: None, permission: Permission::View, url: None, note: None, created: None } +} + +#[test] +fn a_share_is_labelled_with_the_name_the_provider_gave() { + let labels = ShareLabels::default(); + let mut one = share("s1", ShareTarget::User("adunn".to_owned())); + assert_eq!(super::share_label(&one, &labels), "adunn", "the handle is all there is"); + one.display = Some("Ada Lovelace".to_owned()); + assert_eq!(super::share_label(&one, &labels), "Ada Lovelace"); + // A provider that answers with an empty string has said nothing. + one.display = Some(" ".to_owned()); + assert_eq!(super::share_label(&one, &labels), "adunn"); + + let mut team = share("s2", ShareTarget::Group("eng".to_owned())); + team.display = Some("Engineering".to_owned()); + assert_eq!(super::share_label(&team, &labels), format!("Engineering ({})", labels.group)); + + // A link is not a person and never carries one. + assert_eq!(super::share_label(&share("s3", ShareTarget::Link), &labels), labels.anyone_with_link); +} + +#[test] +fn nothing_is_offered_until_the_service_says_sharing_exists() { + let ctx = Context::default(); + let backend = Silent::default(); + let mut dialog = ShareDialog::new(); + assert!(!dialog.available(), "an unconnected dialog cannot share"); + + dialog.connect(backend.clone()); + assert_eq!(backend.seen(), Vec::new(), "connecting alone asks nothing"); + dialog.collect(&ctx); + assert_eq!(backend.seen(), vec![Request::Capabilities]); + + // Still unanswered: the question is outstanding, so the answer is no. + assert!(!dialog.available()); + dialog.open("files/budget.xlsx", "Budget"); + assert!(!dialog.is_open(), "the dialog must not open before the answer"); + + // A provider with files but no sharing hides the feature rather than + // offering a button that fails. + dialog.receive(&ctx, 1, Ok(can(vec![Capability::Files, Capability::Contacts]))); + assert!(!dialog.available()); + dialog.open("files/budget.xlsx", "Budget"); + assert!(!dialog.is_open()); + + dialog.receive(&ctx, 1, Ok(everything())); + assert!(dialog.available()); + dialog.open("files/budget.xlsx", "Budget"); + assert!(dialog.is_open()); +} + +#[test] +fn an_unlinked_account_cannot_share_even_where_the_provider_can() { + let ctx = Context::default(); + let mut dialog = ShareDialog::new(); + dialog.connect(Silent::default()); + dialog.receive(&ctx, 1, Ok(Answer::Capabilities { capabilities: vec![Capability::Sharing], linked: false })); + assert!(!dialog.available()); +} + +#[test] +fn losing_sharing_closes_a_dialog_that_was_already_up() { + let (ctx, mut dialog, _) = ready(); + assert!(dialog.is_open()); + dialog.receive(&ctx, 1, Ok(can(vec![Capability::Files]))); + assert!(!dialog.is_open(), "a dialog that cannot do anything must not stay up"); +} + +#[test] +fn opening_asks_who_already_has_access() { + let (_ctx, dialog, backend) = ready(); + assert_eq!(backend.seen(), vec![Request::Capabilities, Request::Access { id: "files/budget.xlsx".into() }]); + assert!(dialog.is_open()); +} + +#[test] +fn an_unsaved_document_asks_where_it_could_go_and_never_about_a_handle() { + let ctx = Context::default(); + let backend = Silent::default(); + let mut dialog = ShareDialog::new(); + dialog.connect(backend.clone()); + dialog.collect(&ctx); + dialog.receive(&ctx, 1, Ok(everything())); + dialog.open("", "Book1"); + assert!(dialog.is_open()); + // Sharing an unsaved document means saving it first. The dialog therefore + // needs somewhere to offer. It asks nothing about a handle. There is none. + assert_eq!(backend.seen(), vec![Request::Capabilities, Request::Destinations]); + assert!(!backend.seen().iter().any(|r| matches!(r, Request::Access { .. })), "there is no handle to ask about"); +} + +#[test] +fn an_answer_the_user_has_typed_past_is_dropped() { + let (ctx, mut dialog, _) = ready(); + let early = dialog.issue(Request::Lookup { query: "an".into(), limit: MATCHES }); + let late = dialog.issue(Request::Lookup { query: "ann".into(), limit: MATCHES }); + if let Some(sheet) = &mut dialog.open { + sheet.lookup = Some(late); + sheet.searching = true; + } + + // The first query answers second, which is what a service under load + // does. Painting it would show matches for "an" under the text "ann". + dialog.receive(&ctx, late, Ok(Answer::Lookup(vec![person("ann", "Ann Reed")]))); + dialog.receive(&ctx, early, Ok(Answer::Lookup(vec![person("andy", "Andy Shaw"), person("anna", "Anna Beck")]))); + + let sheet = dialog.open.as_ref().expect("still open"); + assert_eq!(sheet.matches.len(), 1); + assert_eq!(sheet.matches.first().map(|c| c.name.as_str()), Some("Ann Reed")); + assert!(!sheet.searching); +} + +#[test] +fn several_recipients_can_be_picked_and_each_only_once() { + let (_ctx, mut dialog, _) = ready(); + let sheet = dialog.open.as_mut().expect("open"); + for contact in [person("ann", "Ann Reed"), person("bob", "Bob Vine"), person("ann", "Ann Reed")] { + choose(sheet, &contact); + } + choose( + sheet, + &Contact { + id: "finance".into(), + target: ShareTarget::Group("finance".into()), + name: "Finance".into(), + email: None, + avatar: None, + is_group: true, + }, + ); + + let picked: Vec<&ShareTarget> = sheet.chosen.iter().map(|c| &c.target).collect(); + assert_eq!( + picked, + vec![&ShareTarget::User("ann".into()), &ShareTarget::User("bob".into()), &ShareTarget::Group("finance".into())], + "a group shares as a group, and picking the same person twice adds one chip" + ); + assert!(sheet.query.is_empty(), "picking clears what was typed"); +} + +#[test] +fn a_share_reaching_four_of_five_names_the_fifth() { + let (ctx, mut dialog, _) = ready(); + let sheet = dialog.open.as_mut().expect("open"); + for who in ["ann", "bob", "cal", "dee"] { + choose(sheet, &person(who, who)); + } + add(sheet, ShareTarget::Email("nobody@@".into()), "nobody@@".into(), None, None); + let granting = dialog.issue(Request::Grant(Grant { + id: "files/budget.xlsx".into(), + password: None, + targets: Vec::new(), + permission: Permission::Edit, + note: None, + notify: true, + })); + if let Some(sheet) = &mut dialog.open { + sheet.granting = Some(granting); + } + + let shared: Vec = + ["ann", "bob", "cal", "dee"].iter().enumerate().map(|(i, who)| share(&format!("s{i}"), ShareTarget::User((*who).into()))).collect(); + let failed = + vec![Failure { target: ShareTarget::Email("nobody@@".into()), code: "invalid_address".into(), detail: "nobody@@ is not an address".into() }]; + dialog.receive(&ctx, granting, Ok(Answer::Granted { shared, failed })); + + let (shared, failed) = dialog.outcome(); + assert_eq!(shared.len(), 4); + assert_eq!(failed.len(), 1, "a wrong address is named, not folded into one error"); + assert_eq!(failed.first().map(|f| f.detail.as_str()), Some("nobody@@ is not an address")); + + // The four that went through leave the picker; the one that did not stays, + // so correcting it is one edit rather than a retyped list. + let left = dialog.open.as_ref().expect("open"); + assert_eq!(left.chosen.len(), 1); + assert_eq!(left.chosen.first().map(|c| &c.target), Some(&ShareTarget::Email("nobody@@".into()))); +} + +#[test] +fn a_refusal_that_stopped_the_whole_call_is_not_a_failed_recipient() { + let (ctx, mut dialog, _) = ready(); + let granting = dialog.issue(Request::Grant(Grant { + id: "files/budget.xlsx".into(), + password: None, + targets: vec![ShareTarget::User("ann".into())], + permission: Permission::View, + note: None, + notify: false, + })); + if let Some(sheet) = &mut dialog.open { + sheet.granting = Some(granting); + } + dialog.receive(&ctx, granting, Err("sign in again".into())); + + let sheet = dialog.open.as_ref().expect("open"); + assert_eq!(sheet.error.as_deref(), Some("sign in again")); + assert!(sheet.failed.is_empty()); + assert!(sheet.granting.is_none(), "the button must come back"); +} + +#[test] +fn a_successful_share_reloads_who_has_access() { + let (ctx, mut dialog, backend) = ready(); + let granting = dialog.issue(Request::Grant(Grant { + id: "files/budget.xlsx".into(), + password: None, + targets: vec![ShareTarget::User("ann".into())], + permission: Permission::View, + note: None, + notify: false, + })); + if let Some(sheet) = &mut dialog.open { + sheet.granting = Some(granting); + } + dialog.receive(&ctx, granting, Ok(Answer::Granted { shared: vec![share("s1", ShareTarget::User("ann".into()))], failed: Vec::new() })); + let asked = backend.seen().iter().filter(|r| **r == Request::Access { id: "files/budget.xlsx".into() }).count(); + assert_eq!(asked, 2, "the list is stale the moment a share succeeds"); +} + +#[test] +fn withdrawing_takes_it_off_the_list_and_only_then() { + let (ctx, mut dialog, backend) = ready(); + let access = dialog.open.as_ref().and_then(|s| s.access_seq).expect("asked"); + dialog.receive( + &ctx, + access, + Ok(Answer::Access(vec![share("s1", ShareTarget::User("ann".into())), share("s2", ShareTarget::Group("finance".into()))])), + ); + dialog.apply(&ctx, vec![Act::Withdraw("s1".into())]); + + let waiting = dialog.open.as_ref().expect("open"); + assert_eq!(waiting.access.as_ref().map(Vec::len), Some(2), "it stays until the server agrees"); + assert_eq!(waiting.withdrawing.len(), 1); + assert!(backend.seen().contains(&Request::Withdraw { share_id: "s1".into() })); + + let seq = waiting.withdrawing.first().map(|(seq, _)| *seq).expect("in flight"); + dialog.receive(&ctx, seq, Ok(Answer::Withdrawn { share_id: "s1".into() })); + let after = dialog.open.as_ref().expect("open"); + assert_eq!(after.access.as_ref().map(|a| a.iter().map(|s| s.id.as_str()).collect::>()), Some(vec!["s2"])); + assert!(after.withdrawing.is_empty()); +} + +#[test] +fn a_refused_withdrawal_leaves_the_share_and_says_why() { + let (ctx, mut dialog, _) = ready(); + let access = dialog.open.as_ref().and_then(|s| s.access_seq).expect("asked"); + dialog.receive(&ctx, access, Ok(Answer::Access(vec![share("s1", ShareTarget::User("ann".into()))]))); + dialog.apply(&ctx, vec![Act::Withdraw("s1".into())]); + let seq = dialog.open.as_ref().and_then(|s| s.withdrawing.first().map(|(seq, _)| *seq)).expect("in flight"); + dialog.receive(&ctx, seq, Err("you do not own this share".into())); + + let sheet = dialog.open.as_ref().expect("open"); + assert_eq!(sheet.access.as_ref().map(Vec::len), Some(1)); + assert!(sheet.withdrawing.is_empty(), "the button must come back"); + assert_eq!(sheet.error.as_deref(), Some("you do not own this share")); +} + +#[test] +fn a_picture_is_asked_for_once_and_a_refusal_is_remembered() { + let (ctx, mut dialog, backend) = ready(); + let url = "https://cloud.example.com/avatar/ann/64"; + dialog.apply(&ctx, vec![Act::Avatar(url.into()), Act::Avatar(url.into())]); + let asked = backend.seen().iter().filter(|r| **r == Request::Avatar { url: url.into() }).count(); + assert_eq!(asked, 1, "one row painted twice is one picture"); + + let seq = match dialog.avatars.get(url) { + Some(Avatar::Pending(seq)) => *seq, + other => panic!("expected a pending picture, got {other:?}"), + }; + dialog.receive(&ctx, seq, Err("this build does not fetch contact pictures".into())); + assert_eq!(dialog.avatars.get(url), Some(&Avatar::Missing)); + + // Refused once is refused. Painting the row again must not ask again. + dialog.apply(&ctx, vec![Act::Avatar(url.into())]); + let asked = backend.seen().iter().filter(|r| **r == Request::Avatar { url: url.into() }).count(); + assert_eq!(asked, 1); + + // And a refused picture is the dialog's business, not the user's. + assert_eq!(dialog.open.as_ref().and_then(|s| s.error.clone()), None); +} + +#[test] +fn an_unanswered_capability_question_is_asked_again_later() { + let ctx = Context::default(); + let backend = Silent::default(); + let mut dialog = ShareDialog::new(); + dialog.connect(backend.clone()); + dialog.collect(&ctx); + dialog.collect(&ctx); + assert_eq!(backend.seen().len(), 1, "a question already outstanding is not asked every frame"); + + dialog.asked = Some(-RETRY); + dialog.collect(&ctx); + assert_eq!(backend.seen().len(), 2, "one unreachable moment must not hide Share for the session"); + + dialog.receive(&ctx, 2, Ok(everything())); + dialog.asked = Some(-RETRY); + dialog.collect(&ctx); + assert_eq!(backend.seen().len(), 2, "an answered question is not asked again"); +} + +#[test] +fn what_counts_as_an_address() { + for typed in ["ann@example.com", " ann.reed+tag@mail.example.co.uk "] { + assert!(address(typed).is_some(), "{typed} is an address"); + } + for typed in ["ann", "ann@", "@example.com", "ann@example", "ann reed@example.com", "ann@.com", "a@b@c.com", ""] { + assert!(address(typed).is_none(), "{typed} is not an address"); + } + assert_eq!(address(" ann@example.com "), Some("ann@example.com".to_owned()), "the trim is kept"); +} + +#[test] +fn initials_come_from_the_name_and_never_from_an_index() { + assert_eq!(initials("Ann Reed"), "AR"); + assert_eq!(initials("ann"), "A"); + assert_eq!(initials("Ann Marie Reed"), "AM"); + assert_eq!(initials(""), ""); + assert_eq!(initials(" "), ""); + assert_eq!(initials("Ærø Ødegård"), "ÆØ"); + assert_eq!(initials("张 伟"), "张伟"); +} + +#[test] +fn every_kind_of_recipient_reads_as_something() { + let labels = ShareLabels::default(); + assert_eq!(target_label(&ShareTarget::User("ann".into()), &labels), "ann"); + assert_eq!(target_label(&ShareTarget::Group("finance".into()), &labels), "finance (group)"); + assert_eq!(target_label(&ShareTarget::Email("ann@example.com".into()), &labels), "ann@example.com"); + assert_eq!(target_label(&ShareTarget::Link, &labels), "Anyone with the link"); +} + +#[test] +fn a_failure_with_no_detail_still_says_something() { + let bare = Failure { target: ShareTarget::Link, code: "forbidden".into(), detail: " ".into() }; + assert_eq!(describe(&bare), "forbidden"); + let told = Failure { target: ShareTarget::Link, code: "forbidden".into(), detail: "link shares are off".into() }; + assert_eq!(describe(&told), "link shares are off"); +} + +#[test] +fn two_contacts_never_share_one_picture_cache_entry() { + let one = avatar_uri("https://cloud.example.com/avatar/ann/64"); + let two = avatar_uri("https://cloud.example.com/avatar/anna/64"); + assert_ne!(one, two); + assert_eq!(one, avatar_uri("https://cloud.example.com/avatar/ann/64"), "the same URL is the same entry"); + assert!(one.starts_with("bytes://"), "egui's own loaders have to recognize it"); +} + +fn ready_unsaved() -> (Context, ShareDialog, Silent) { + let ctx = Context::default(); + let backend = Silent::default(); + let mut dialog = ShareDialog::new(); + dialog.connect(backend.clone()); + dialog.collect(&ctx); + dialog.receive(&ctx, 1, Ok(everything())); + dialog.open("", "Book1"); + (ctx, dialog, backend) +} + +fn start_save(dialog: &mut ShareDialog, ctx: &Context, destination: &str, name: &str) -> u64 { + dialog.apply(ctx, vec![Act::SaveAs { destination: destination.into(), name: name.into() }]); + let request = dialog.take_save_request().expect("save was handed to the application"); + assert_ne!(request.generation, 0, "taken saves carry the open sheet generation"); + request.generation +} + +#[test] +fn a_stale_save_completion_after_close_does_nothing() { + let (ctx, mut dialog, backend) = ready_unsaved(); + let generation = start_save(&mut dialog, &ctx, "cloud", "Budget"); + dialog.close(); + assert!(!dialog.is_open()); + + dialog.saved("files/wrong.xlsx", "Wrong"); + dialog.saved_if(generation, "files/wrong.xlsx", "Wrong"); + assert!(!dialog.is_open()); + assert!( + !backend.seen().iter().any(|r| matches!(r, Request::Access { id } if id == "files/wrong.xlsx")), + "a completion after close must not ask about the saved handle" + ); +} + +#[test] +fn a_stale_save_completion_after_reopening_another_document_does_nothing() { + let (ctx, mut dialog, backend) = ready_unsaved(); + let generation = start_save(&mut dialog, &ctx, "cloud", "Budget"); + dialog.close(); + dialog.open("files/other.xlsx", "Other"); + assert_eq!(dialog.open.as_ref().map(|s| s.id.as_str()), Some("files/other.xlsx")); + + dialog.saved("files/budget.xlsx", "Budget"); + dialog.saved_if(generation, "files/budget.xlsx", "Budget"); + let sheet = dialog.open.as_ref().expect("still open on the other document"); + assert_eq!(sheet.id, "files/other.xlsx"); + assert_eq!(sheet.title, "Other"); + assert!(sheet.saving.is_none()); + assert!( + !backend.seen().iter().any(|r| matches!(r, Request::Access { id } if id == "files/budget.xlsx")), + "the first document's completion must not rebind the second" + ); +} + +#[test] +fn a_save_completion_on_the_same_open_updates_the_sheet() { + let (ctx, mut dialog, backend) = ready_unsaved(); + let generation = start_save(&mut dialog, &ctx, "cloud", "Budget"); + + dialog.saved_if(generation, "files/budget.xlsx", "Budget"); + let sheet = dialog.open.as_ref().expect("open"); + assert_eq!(sheet.id, "files/budget.xlsx"); + assert_eq!(sheet.title, "Budget"); + assert!(sheet.saving.is_none()); + assert!(backend.seen().iter().any(|r| matches!(r, Request::Access { id } if id == "files/budget.xlsx"))); +} + +#[test] +fn take_save_request_returns_the_open_sheet_generation() { + let (ctx, mut dialog, _) = ready_unsaved(); + let before = dialog.sheet_generation(); + assert_ne!(before, 0); + dialog.apply(&ctx, vec![Act::SaveAs { destination: "cloud".into(), name: "Budget".into() }]); + let request = dialog.take_save_request().expect("taken"); + assert_eq!(request.generation, before); + assert_eq!(request.destination, "cloud"); + assert_eq!(request.name, "Budget"); +} + +#[test] +fn a_closed_dialog_still_collects_and_reports_nothing() { + let (ctx, mut dialog, _) = ready(); + dialog.close(); + assert!(!dialog.is_open()); + dialog.receive(&ctx, 99, Ok(Answer::Lookup(vec![person("ann", "Ann Reed")]))); + dialog.receive(&ctx, 99, Err("gone".into())); + let (shared, failed) = dialog.outcome(); + assert!(shared.is_empty() && failed.is_empty()); +} + +#[test] +fn pressing_return_takes_the_first_match_or_an_address() { + let (_ctx, mut dialog, _) = ready(); + let sheet = dialog.open.as_mut().expect("open"); + + // With matches on screen, Return takes the one at the top. + sheet.query = "an".into(); + sheet.matches = vec![person("ann", "Ann Reed"), person("andy", "Andy Shaw")]; + commit(sheet); + assert_eq!(sheet.chosen.first().map(|c| &c.target), Some(&ShareTarget::User("ann".into()))); + + // With none, an address is taken as itself. Somebody with no account on + // this server is reached by address or not at all. + sheet.query = "outside@example.com".into(); + commit(sheet); + assert_eq!(sheet.chosen.len(), 2); + assert_eq!(sheet.chosen.last().map(|c| &c.target), Some(&ShareTarget::Email("outside@example.com".into()))); + + // A name that matched nothing is not a recipient. + sheet.query = "nobody".into(); + commit(sheet); + assert_eq!(sheet.chosen.len(), 2); + assert_eq!(sheet.query, "nobody", "and what was typed is left alone to be corrected"); +} diff --git a/crates/cloud-ui/tests/renders.rs b/crates/cloud-ui/tests/renders.rs new file mode 100644 index 000000000..3fdff1d0e --- /dev/null +++ b/crates/cloud-ui/tests/renders.rs @@ -0,0 +1,343 @@ +//! Gated on the `share` feature, which is off by default. +#![cfg(feature = "share")] + +//! Renders of the shared controls, for review. +//! +//! The other suites read the accessibility tree and never look at pixels. That +//! catches wrong wording and missing names. It cannot show whether a dialog +//! looks like it belongs in an office suite, and these two controls will sit in +//! every Craft app, so somebody has to be able to see them. +//! +//! Writes nothing unless `CRAFT_UI_RENDERS` names a directory. A suite that +//! wrote files on every run would turn a checkout dirty by testing it. +//! +//! ```sh +//! CRAFT_UI_RENDERS=/tmp/renders cargo test -p craft-cloud-ui --all-features --test renders +//! ``` + +use std::cell::RefCell; +use std::path::PathBuf; +use std::rc::Rc; +use std::sync::{Arc, Mutex}; + +use craft_cloud::{Capability, Contact, Permission, Share, ShareTarget}; +use craft_cloud_ui::account::{Account, AccountMenu}; +use craft_cloud_ui::presence::{Peer, PresenceBar}; +use craft_cloud_ui::share::{Answer, Failure, Replier, Request, ShareBackend, ShareDialog}; +use egui::{Context, Event, FullOutput, PointerButton, Pos2, RawInput, Rect, Theme, Visuals, accesskit, pos2, vec2}; +use egui_kittest::{TestRenderer, wgpu::WgpuTestRenderer}; + +const DOCUMENT: &str = "files/Budget 2026.xlsx"; + +/// A backend that answers what a control needs and parks the rest. +#[derive(Clone, Default)] +struct Fake { + capabilities: Vec, + access: Vec, + parked: Arc>>, +} + +impl ShareBackend for Fake { + fn submit(&self, request: Request, reply: Replier) { + match &request { + Request::Capabilities => { + reply.answer(Answer::Capabilities { capabilities: self.capabilities.clone(), linked: true }); + } + Request::Access { .. } => reply.answer(Answer::Access(self.access.clone())), + _ => { + if let Ok(mut parked) = self.parked.lock() { + parked.push((request, reply)); + } + } + } + } +} + +impl Fake { + fn answer(&self, answer: Answer) { + let taken = self.parked.lock().ok().and_then(|mut p| if p.is_empty() { None } else { Some(p.remove(0)) }); + if let Some((_, reply)) = taken { + reply.answer(answer); + } + } +} + +/// One control, driven frame by frame, with the pixels kept. +struct Shot { + ctx: Context, + /// One renderer per context. A renderer shared between two contexts + /// takes a texture id from the first and is then asked by the second + /// to free one it never registered. + renderer: WgpuTestRenderer, + time: f64, + size: [f32; 2], + typing: bool, + /// The ground the control is painted on. Without it the render carries a + /// transparent background, which reads as a rendering fault. + fill: egui::Color32, +} + +impl Shot { + fn new(theme: Theme, size: [f32; 2]) -> Shot { + let ctx = Context::default(); + ctx.enable_accesskit(); + let visuals = if theme == Theme::Dark { Visuals::dark() } else { Visuals::light() }; + let fill = visuals.panel_fill; + ctx.set_visuals(visuals); + ctx.all_styles_mut(|style| { + style.animation_time = 0.0; + style.visuals.text_cursor.blink = false; + }); + Shot { ctx, renderer: WgpuTestRenderer::new(), time: 0.0, size, typing: false, fill } + } + + fn frame(&mut self, events: Vec, mut draw: impl FnMut(&mut egui::Ui)) -> FullOutput { + self.time += 1.0 / 60.0; + let raw = RawInput { + screen_rect: Some(Rect::from_min_size(Pos2::ZERO, vec2(self.size[0], self.size[1]))), + time: Some(self.time), + events, + ..Default::default() + }; + let ctx = self.ctx.clone(); + if self.typing { + ctx.memory_mut(|m| m.request_focus(ShareDialog::query_field_id())); + } + let fill = self.fill; + let size = self.size; + let mut output = ctx.run_ui(raw, |ui| { + let screen = Rect::from_min_size(Pos2::ZERO, vec2(size[0], size[1])); + ui.painter().rect_filled(screen, 0.0, fill); + draw(ui); + }); + // Every frame's delta has to reach the renderer. The font atlas arrives + // on the first frame, and a renderer that saw only the last one paints + // no text at all. + self.renderer.handle_delta(&mut output.textures_delta); + output + } + + /// Write what the last frame drew. + fn save(&mut self, into: &std::path::Path, name: &str, theme: Theme, output: &FullOutput) { + let image = self.renderer.render(&self.ctx, output).expect("an offscreen renderer is required to write renders"); + let suffix = if theme == Theme::Dark { "dark" } else { "light" }; + let path = into.join(format!("{name}-{suffix}.png")); + image.save(&path).expect("the render directory must be writable"); + println!("wrote {}", path.display()); + } + + /// Press the control carrying this exact accessible name. + fn click(&mut self, label: &str, draw: &mut impl FnMut(&mut egui::Ui)) { + let output = self.frame(Vec::new(), &mut *draw); + let Some(at) = control(&output, label) else { panic!("nothing to click named {label:?}; on screen are {:?}", controls(&output)) }; + self.frame(vec![Event::PointerMoved(at)], &mut *draw); + self.frame(vec![press(at, true)], &mut *draw); + self.frame(vec![press(at, false)], &mut *draw); + } +} + +fn press(at: Pos2, down: bool) -> Event { + Event::PointerButton { pos: at, button: PointerButton::Primary, pressed: down, modifiers: egui::Modifiers::default() } +} + +struct Seen { + role: accesskit::Role, + label: String, + bounds: Option, + disabled: bool, +} + +impl Seen { + fn interactive(&self) -> bool { + matches!(self.role, accesskit::Role::Button | accesskit::Role::TextInput | accesskit::Role::CheckBox | accesskit::Role::Link) + } + + fn at(&self) -> Option { + self.bounds.map(|b| pos2(((b.x0 + b.x1) / 2.0) as f32, ((b.y0 + b.y1) / 2.0) as f32)) + } +} + +fn seen(output: &FullOutput) -> Vec { + let Some(update) = &output.platform_output.accesskit_update else { return Vec::new() }; + update + .nodes + .iter() + .filter_map(|(_, node)| { + node.label().or_else(|| node.value()).map(|text| Seen { + role: node.role(), + label: text.to_owned(), + bounds: node.bounds(), + disabled: node.is_disabled(), + }) + }) + .collect() +} + +fn control(output: &FullOutput, label: &str) -> Option { + seen(output).iter().find(|s| s.interactive() && !s.disabled && s.label == label).and_then(Seen::at) +} + +fn controls(output: &FullOutput) -> Vec { + seen(output).into_iter().filter(Seen::interactive).map(|s| s.label).collect() +} + +fn person(id: &str, name: &str) -> Contact { + Contact { + id: id.into(), + target: ShareTarget::User(id.into()), + name: name.into(), + email: Some(format!("{id}@example.com")), + avatar: None, + is_group: false, + } +} + +fn existing(id: &str, target: ShareTarget, permission: Permission) -> Share { + Share { id: id.into(), target, display: None, permission, url: None, note: None, created: None } +} + +fn ordinary() -> Vec { + vec![Capability::Files, Capability::Sharing, Capability::Contacts, Capability::ShareNotify, Capability::LinkShares] +} + +#[test] +fn renders_of_every_state_in_both_themes() { + let Ok(directory) = std::env::var("CRAFT_UI_RENDERS") else { + println!("set CRAFT_UI_RENDERS to a directory to write renders"); + return; + }; + let into = PathBuf::from(directory); + std::fs::create_dir_all(&into).expect("the render directory must be creatable"); + for theme in [Theme::Light, Theme::Dark] { + // ---- the account control ------------------------------------------- + let mut shot = Shot::new(theme, [320.0, 300.0]); + // A fresh menu is a signed-out one, which is the first state. + let mut draw = { + let mut menu = AccountMenu::new(); + move |ui: &mut egui::Ui| menu.show(ui) + }; + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, "account-signed-out", theme, &output); + + for (name, linked) in [("account-no-storage", false), ("account-linked", true)] { + let mut shot = Shot::new(theme, [320.0, 300.0]); + let mut draw = { + let mut menu = AccountMenu::new(); + menu.set(vec![ + Account { + id: "work".into(), + display: "Will Dunn".into(), + email: Some("will@example.com".into()), + service: "collabcraft.example.com".into(), + linked, + }, + Account { + id: "personal".into(), + display: "Will at home".into(), + email: Some("will@example.net".into()), + service: "cloud.example.net".into(), + linked: true, + }, + ]); + move |ui: &mut egui::Ui| menu.show(ui) + }; + // The menu is behind the badge, so it takes a press to show. + shot.click("Account, Will Dunn", &mut draw); + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, name, theme, &output); + } + + // ---- who else is here ---------------------------------------------- + let mut shot = Shot::new(theme, [420.0, 80.0]); + let mut bar = PresenceBar::new(); + bar.set(vec![ + Peer::new("s1", "Ann Reed").at("editing B4"), + Peer::new("s2", "Bob Vine").at("editing D12"), + Peer::new("s3", "Cal Nye"), + Peer::new("s4", "Dee Shaw"), + Peer::new("s5", "Eve Marsh"), + Peer::new("s6", "Fay Orr"), + ]); + let mut draw = move |ui: &mut egui::Ui| { + ui.add_space(24.0); + bar.show(ui); + }; + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, "presence", theme, &output); + + // ---- the share dialog ---------------------------------------------- + let cases: Vec<(&str, Vec, Vec, &str)> = vec![ + ("dialog-fresh", ordinary(), Vec::new(), DOCUMENT), + ( + "dialog-who-has-access", + ordinary(), + vec![ + existing("s1", ShareTarget::User("ann".into()), Permission::Edit), + existing("s2", ShareTarget::Group("finance".into()), Permission::View), + ], + DOCUMENT, + ), + ("dialog-no-link-shares", vec![Capability::Sharing, Capability::Contacts], Vec::new(), DOCUMENT), + ("dialog-unsaved", ordinary(), Vec::new(), ""), + ]; + + for (name, capabilities, access, id) in cases { + let mut shot = Shot::new(theme, [620.0, 560.0]); + let fake = Fake { capabilities, access, parked: Arc::default() }; + let mut dialog = ShareDialog::new(); + dialog.connect(fake.clone()); + let held = Rc::new(RefCell::new(dialog)); + let mut draw = { + let held = Rc::clone(&held); + move |ui: &mut egui::Ui| held.borrow_mut().show_in(ui) + }; + // One frame asks what the provider can do, the next reads the answer. + shot.frame(Vec::new(), &mut draw); + shot.frame(Vec::new(), &mut draw); + held.borrow_mut().open(id.to_owned(), "Budget 2026"); + shot.frame(Vec::new(), &mut draw); + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, name, theme, &output); + } + + // ---- recipients picked, then one of them refused ------------------- + let fake = Fake { capabilities: ordinary(), access: Vec::new(), parked: Arc::default() }; + let mut dialog = ShareDialog::new(); + dialog.connect(fake.clone()); + let held = Rc::new(RefCell::new(dialog)); + let mut draw = { + let held = Rc::clone(&held); + move |ui: &mut egui::Ui| held.borrow_mut().show_in(ui) + }; + let mut shot = Shot::new(theme, [620.0, 560.0]); + // One frame asks what the provider can do, the next reads the answer. + // Opening before that answer arrives does nothing, which is the point + // of a control that refuses to appear when it cannot work. + shot.frame(Vec::new(), &mut draw); + shot.frame(Vec::new(), &mut draw); + held.borrow_mut().open(DOCUMENT.to_owned(), "Budget 2026"); + shot.frame(Vec::new(), &mut draw); + shot.typing = true; + shot.frame(vec![Event::Text("an".to_owned())], &mut draw); + shot.time += 0.25; + shot.frame(Vec::new(), &mut draw); + fake.answer(Answer::Lookup(vec![person("ann", "Ann Reed")])); + shot.frame(Vec::new(), &mut draw); + shot.click("Ann Reed", &mut draw); + shot.typing = false; + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, "dialog-recipients", theme, &output); + + shot.click("Send", &mut draw); + fake.answer(Answer::Granted { + shared: vec![existing("s1", ShareTarget::User("ann".into()), Permission::View)], + failed: vec![Failure { + target: ShareTarget::User("bob".into()), + code: "invalid_address".into(), + detail: "bob@example.con was rejected".into(), + }], + }); + let output = shot.frame(Vec::new(), &mut draw); + shot.save(&into, "dialog-partial-failure", theme, &output); + } +} diff --git a/crates/cloud-ui/tests/share_dialog.rs b/crates/cloud-ui/tests/share_dialog.rs new file mode 100644 index 000000000..4b43bca6e --- /dev/null +++ b/crates/cloud-ui/tests/share_dialog.rs @@ -0,0 +1,589 @@ +//! Gated on the `share` feature, which is off by default. +#![cfg(feature = "share")] + +//! The share dialog driven through its real widgets, offscreen. +//! +//! Every assertion here reads the accessibility tree the dialog actually +//! produced, or the requests it actually sent, rather than its private state. +//! No window is opened, no GPU is touched and no server is contacted: the +//! backend is a fake that parks each request until a test answers it, which is +//! also how answers are made to arrive late or in the wrong order. + +use std::sync::{Arc, Mutex}; + +use craft_cloud::{Capability, Contact, Permission, Share, ShareTarget}; +use craft_cloud_ui::share::{Answer, Failure, Replier, Request, ShareBackend, ShareDialog}; +use egui::{Context, Event, FullOutput, Modifiers, PointerButton, Pos2, RawInput, Rect, accesskit, pos2, vec2}; + +const SCREEN: [f32; 2] = [620.0, 900.0]; +const DOCUMENT: &str = "files/Budget 2026.xlsx"; + +#[derive(Default)] +struct Log { + seen: Vec, + parked: Vec<(Request, Replier)>, +} + +/// A backend that answers what the dialog needs to get going and parks the +/// rest, so a test decides when each answer arrives. +#[derive(Clone)] +struct Fake { + log: Arc>, + capabilities: Vec, + access: Vec, +} + +impl Fake { + fn new(capabilities: Vec, access: Vec) -> Fake { + Fake { log: Arc::new(Mutex::new(Log::default())), capabilities, access } + } + + fn seen(&self) -> Vec { + self.log.lock().map(|log| log.seen.clone()).unwrap_or_default() + } + + fn parked(&self) -> Vec { + self.log.lock().map(|log| log.parked.iter().map(|(r, _)| r.clone()).collect()).unwrap_or_default() + } + + /// Answer the request that has waited longest, which is the ordinary case. + fn answer(&self, answer: Answer) { + self.answer_nth(0, answer); + } + + /// Answer the request parked at `index`, oldest first, so a test can + /// deliver a late answer after a newer one. + fn answer_nth(&self, index: usize, answer: Answer) { + let Some((_, reply)) = self.take(index) else { panic!("nothing is waiting at {index}") }; + reply.answer(answer); + } + + /// Take one parked request back, to refuse it or inspect its contents. + fn take(&self, index: usize) -> Option<(Request, Replier)> { + self.log.lock().ok().and_then(|mut log| if index < log.parked.len() { Some(log.parked.remove(index)) } else { None }) + } +} + +impl ShareBackend for Fake { + fn submit(&self, request: Request, reply: Replier) { + let Ok(mut log) = self.log.lock() else { return }; + log.seen.push(request.clone()); + match &request { + Request::Capabilities => { + reply.answer(Answer::Capabilities { capabilities: self.capabilities.clone(), linked: true }); + } + Request::Access { .. } => reply.answer(Answer::Access(self.access.clone())), + _ => log.parked.push((request, reply)), + } + } +} + +struct Harness { + ctx: Context, + dialog: ShareDialog, + time: f64, + typing: bool, +} + +impl Harness { + fn new(capabilities: Vec, access: Vec) -> (Harness, Fake) { + let ctx = Context::default(); + ctx.enable_accesskit(); + ctx.all_styles_mut(|style| { + style.animation_time = 0.0; + style.visuals.text_cursor.blink = false; + }); + let fake = Fake::new(capabilities, access); + let mut dialog = ShareDialog::new(); + dialog.connect(fake.clone()); + let mut harness = Harness { ctx, dialog, time: 0.0, typing: false }; + // One frame asks what the provider can do, the next reads the answer. + harness.frame(Vec::new()); + harness.frame(Vec::new()); + (harness, fake) + } + + /// An ordinary deployment: files, sharing, contacts and mail. + fn everything() -> (Harness, Fake) { + Harness::new( + // Everything, which has to include ShareNotify. Notifying a + // recipient of a share is a separate ability from sending + // arbitrary mail, and the box is gated on the former. + vec![Capability::Files, Capability::Sharing, Capability::Contacts, Capability::Mail, Capability::ShareNotify], + Vec::new(), + ) + } + + fn frame(&mut self, events: Vec) -> FullOutput { + self.time += 1.0 / 60.0; + let raw = RawInput { + screen_rect: Some(Rect::from_min_size(Pos2::ZERO, vec2(SCREEN[0], SCREEN[1]))), + time: Some(self.time), + events, + ..Default::default() + }; + let ctx = self.ctx.clone(); + if self.typing { + // Keeping the recipient field focused is what a user holding the + // caret there does; nothing else in the dialog wants focus. + ctx.memory_mut(|m| m.request_focus(ShareDialog::query_field_id())); + } + let dialog = &mut self.dialog; + let mut output = ctx.run_ui(raw, |ui| dialog.show_in(ui)); + output.textures_delta.clear(); + output + } + + /// Let the clock run, for the debounce. + fn wait(&mut self, seconds: f64) -> FullOutput { + self.time += seconds; + self.frame(Vec::new()) + } + + fn open(&mut self) { + self.dialog.open(DOCUMENT, "Budget 2026.xlsx"); + assert!(self.dialog.is_open(), "the dialog should have opened"); + self.frame(Vec::new()); + } + + /// Type into the recipient field, then let the debounce elapse. + fn type_and_settle(&mut self, text: &str) { + self.typing = true; + self.frame(vec![Event::Text(text.to_owned())]); + self.wait(0.25); + } + + fn click(&mut self, label: &str) { + let output = self.frame(Vec::new()); + let Some(at) = control(&output, label) else { + panic!("nothing to click labelled {label:?}; the controls on screen are {:?}", controls(&output)) + }; + self.frame(vec![Event::PointerMoved(at)]); + self.frame(vec![press(at, true)]); + self.frame(vec![press(at, false)]); + self.frame(Vec::new()); + } +} + +fn press(at: Pos2, pressed: bool) -> Event { + Event::PointerButton { pos: at, button: PointerButton::Primary, pressed, modifiers: Modifiers::NONE } +} + +fn key(key: egui::Key) -> Event { + Event::Key { key, physical_key: None, pressed: true, repeat: false, modifiers: Modifiers::NONE } +} + +/// One widget as the accessibility tree reported it. +struct Seen { + role: accesskit::Role, + label: String, + bounds: Option, + disabled: bool, +} + +impl Seen { + /// Something a pointer can act on, as opposed to a piece of text. + fn interactive(&self) -> bool { + matches!(self.role, accesskit::Role::Button | accesskit::Role::RadioButton | accesskit::Role::CheckBox) + } + + fn at(&self) -> Option { + self.bounds.map(|b| pos2(((b.x0 + b.x1) / 2.0) as f32, ((b.y0 + b.y1) / 2.0) as f32)) + } +} + +fn seen(output: &FullOutput) -> Vec { + let Some(tree) = output.platform_output.accesskit_update.as_ref() else { return Vec::new() }; + tree.nodes + .iter() + .filter_map(|(_, node)| { + // egui puts a plain label's text in the accessibility value and a + // control's text in the label, so both are text on screen. + node.label().or_else(|| node.value()).map(|text| Seen { + role: node.role(), + label: text.to_owned(), + bounds: node.bounds(), + disabled: node.is_disabled(), + }) + }) + .collect() +} + +/// Where to click the control carrying this exact label. +fn control(output: &FullOutput, label: &str) -> Option { + seen(output).iter().find(|s| s.interactive() && !s.disabled && s.label == label).and_then(Seen::at) +} + +fn controls(output: &FullOutput) -> Vec { + seen(output).into_iter().filter(Seen::interactive).map(|s| s.label).collect() +} + +/// The buttons alone, which is what a chip and a match row are. +fn buttons(output: &FullOutput) -> Vec { + seen(output).into_iter().filter(|s| s.role == accesskit::Role::Button).map(|s| s.label).collect() +} + +/// Every piece of text on screen, for asserting what the user was told. +fn text(output: &FullOutput) -> Vec { + seen(output).into_iter().map(|s| s.label).collect() +} + +/// The primary action, taken from the defaults the dialog actually draws. +/// A literal here drifts the moment the wording changes. +const SEND: &str = "Send"; + +/// The permission dropdown, chevron included. It is a menu, not a toggle. +const PERMISSION: &str = "View"; + +fn says(output: &FullOutput, fragment: &str) -> bool { + text(output).iter().any(|line| line.contains(fragment)) +} + +fn person(id: &str, name: &str) -> Contact { + Contact { + id: id.into(), + target: ShareTarget::User(id.into()), + name: name.into(), + email: Some(format!("{id}@example.com")), + avatar: None, + is_group: false, + } +} + +fn group(id: &str, name: &str) -> Contact { + Contact { id: id.into(), target: ShareTarget::Group(id.into()), name: name.into(), email: None, avatar: None, is_group: true } +} + +fn existing(id: &str, target: ShareTarget, permission: Permission) -> Share { + Share { id: id.into(), target, display: None, permission, url: None, note: None, created: None } +} + +fn lookup(found: Vec) -> Answer { + Answer::Lookup(found) +} + +// ---- the picker ----------------------------------------------------------- + +#[test] +fn typing_a_few_letters_offers_matches_and_picking_them_builds_chips() { + let (mut h, fake) = Harness::everything(); + h.open(); + + h.type_and_settle("an"); + h.frame(Vec::new()); + assert_eq!( + fake.parked(), + vec![Request::Lookup { query: "an".into(), limit: 8 }], + "one lookup for the whole burst of typing, not one per keystroke" + ); + + fake.answer(lookup(vec![person("ann", "Ann Reed"), person("andy", "Andy Shaw"), group("finance", "Finance")])); + let output = h.frame(Vec::new()); + for name in ["Ann Reed", "Andy Shaw", "Finance"] { + assert!(buttons(&output).iter().any(|b| b == name), "{name} should be offered; saw {:?}", buttons(&output)); + } + + // Three recipients, picked one after another. Each lands as a chip whose + // whole body is the control that takes it back again. + h.click("Ann Reed"); + h.type_and_settle("an"); + fake.answer(lookup(vec![person("andy", "Andy Shaw")])); + h.frame(Vec::new()); + h.click("Andy Shaw"); + h.type_and_settle("fin"); + fake.answer(lookup(vec![group("finance", "Finance")])); + h.frame(Vec::new()); + h.click("Finance"); + + let output = h.frame(Vec::new()); + for name in ["Remove Ann Reed", "Remove Andy Shaw", "Remove Finance"] { + assert!(buttons(&output).iter().any(|b| b == name), "{name} should be a chip; saw {:?}", buttons(&output)); + } +} + +#[test] +fn a_chip_takes_one_recipient_back_and_leaves_the_others() { + let (mut h, fake) = Harness::everything(); + h.open(); + for (query, found) in [("an", person("ann", "Ann Reed")), ("bo", person("bob", "Bob Vine")), ("ca", person("cal", "Cal Nye"))] { + h.type_and_settle(query); + fake.answer(lookup(vec![found.clone()])); + h.frame(Vec::new()); + h.click(&found.name); + } + h.typing = false; + + h.click("Remove Bob Vine"); + let output = h.frame(Vec::new()); + assert!(buttons(&output).iter().any(|b| b == "Remove Ann Reed")); + assert!(buttons(&output).iter().any(|b| b == "Remove Cal Nye")); + assert!(!buttons(&output).iter().any(|b| b == "Remove Bob Vine"), "the removed chip is gone; saw {:?}", buttons(&output)); + + // And the share that follows carries the two that are left. + h.click(SEND); + let parked = fake.parked(); + let Some(Request::Grant(grant)) = parked.first() else { panic!("expected a share, saw {parked:?}") }; + assert_eq!(grant.targets, vec![ShareTarget::User("ann".into()), ShareTarget::User("cal".into())]); +} + +#[test] +fn an_answer_the_user_has_typed_past_never_reaches_the_list() { + let (mut h, fake) = Harness::everything(); + h.open(); + + // Two bursts of typing, so two lookups are outstanding at once. + h.type_and_settle("an"); + h.frame(Vec::new()); + h.type_and_settle("ann"); + h.frame(Vec::new()); + assert_eq!(fake.parked().len(), 2); + + // The newer one answers first and the older one arrives late, which is + // what a service under load does. + fake.answer_nth(1, lookup(vec![person("ann", "Ann Reed")])); + h.frame(Vec::new()); + fake.answer_nth(0, lookup(vec![person("andy", "Andy Shaw"), person("anna", "Anna Beck")])); + let output = h.frame(Vec::new()); + + assert!(buttons(&output).iter().any(|b| b == "Ann Reed"), "the current answer stays"); + assert!(!says(&output, "Andy Shaw"), "the stale answer must not flicker in"); + assert!(!says(&output, "Anna Beck")); +} + +#[test] +fn one_letter_is_not_worth_asking_about() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.type_and_settle("a"); + h.frame(Vec::new()); + assert!(fake.parked().is_empty(), "a single letter matches most of an address book"); + + h.frame(vec![Event::Text("n".to_owned())]); + h.wait(0.25); + h.frame(Vec::new()); + assert_eq!(fake.parked(), vec![Request::Lookup { query: "an".into(), limit: 8 }]); +} + +#[test] +fn nothing_is_asked_until_the_typing_stops() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.typing = true; + // Five keystrokes inside the debounce window. + for letter in ["a", "n", "n", "i", "e"] { + h.frame(vec![Event::Text(letter.to_owned())]); + h.wait(0.03); + } + assert!(fake.parked().is_empty(), "nothing asked while the user is still typing"); + + h.wait(0.25); + h.frame(Vec::new()); + assert_eq!(fake.parked(), vec![Request::Lookup { query: "annie".into(), limit: 8 }], "one question for the whole word"); +} + +// ---- what a share says ---------------------------------------------------- + +#[test] +fn sharing_with_five_where_one_address_is_wrong_names_the_one_that_failed() { + let (mut h, fake) = Harness::everything(); + h.open(); + for (query, found) in [("an", person("ann", "Ann Reed")), ("bo", person("bob", "Bob Vine"))] { + h.type_and_settle(query); + fake.answer(lookup(vec![found.clone()])); + h.frame(Vec::new()); + h.click(&found.name); + } + h.typing = false; + h.click(SEND); + + fake.answer(Answer::Granted { + shared: vec![existing("s1", ShareTarget::User("ann".into()), Permission::View)], + failed: vec![Failure { + target: ShareTarget::User("bob".into()), + code: "invalid_address".into(), + detail: "bob@example.con was rejected".into(), + }], + }); + let output = h.frame(Vec::new()); + + assert!(says(&output, "Shared with"), "the ones that went through are named"); + assert!(says(&output, "ann")); + assert!(says(&output, "Not shared with"), "and so is the one that did not"); + assert!(says(&output, "bob@example.con was rejected"), "with the reason, not a count; saw {:?}", text(&output)); + + // The failed recipient stays in the picker so a correction is one edit. + assert!(buttons(&output).iter().any(|b| b == "Remove Bob Vine")); + assert!(!buttons(&output).iter().any(|b| b == "Remove Ann Reed"), "the one that worked has left"); +} + +#[test] +fn a_refusal_that_stopped_everything_is_shown_as_itself() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.type_and_settle("an"); + fake.answer(lookup(vec![person("ann", "Ann Reed")])); + h.frame(Vec::new()); + h.click("Ann Reed"); + h.typing = false; + h.click(SEND); + + let Some((_, reply)) = fake.take(0) else { panic!("expected a share in flight") }; + reply.refuse("sign in again"); + let output = h.frame(Vec::new()); + + assert!(says(&output, "sign in again")); + assert!(!says(&output, "Not shared with"), "a refusal is not a per-recipient failure"); + assert!(control(&output, SEND).is_some(), "the button comes back"); +} + +#[test] +fn a_note_and_a_permission_travel_with_the_share() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.type_and_settle("an"); + fake.answer(lookup(vec![person("ann", "Ann Reed")])); + h.frame(Vec::new()); + h.click("Ann Reed"); + h.typing = false; + // The permission is a menu now, so it takes opening before choosing. + h.click(PERMISSION); + h.click("Edit"); + h.click(SEND); + + let parked = fake.parked(); + let Some(Request::Grant(grant)) = parked.first() else { panic!("expected a share, saw {parked:?}") }; + assert_eq!(grant.permission, Permission::Edit); + assert_eq!(grant.id, DOCUMENT, "the handle goes back untouched"); + assert!(grant.notify, "mail works here, and the box is ticked by default"); + assert_eq!(grant.note, None, "an empty note is no note"); +} + +#[test] +fn a_server_that_cannot_send_mail_is_never_promised_a_notification() { + let (mut h, fake) = Harness::new(vec![Capability::Sharing, Capability::Contacts], Vec::new()); + h.open(); + h.type_and_settle("an"); + fake.answer(lookup(vec![person("ann", "Ann Reed")])); + h.frame(Vec::new()); + h.click("Ann Reed"); + h.typing = false; + h.click(SEND); + + let parked = fake.parked(); + let Some(Request::Grant(grant)) = parked.first() else { panic!("expected a share, saw {parked:?}") }; + assert!(!grant.notify, "a checkbox for mail a server cannot send must not be honoured"); +} + +#[test] +fn a_server_without_contacts_asks_nobody_anything() { + let (mut h, fake) = Harness::new(vec![Capability::Sharing], Vec::new()); + h.open(); + h.type_and_settle("ann"); + h.frame(Vec::new()); + assert!(fake.parked().is_empty(), "there is no address book to search"); +} + +// ---- who already has access ---------------------------------------------- + +#[test] +fn who_has_access_is_listed_and_one_can_be_withdrawn() { + let (mut h, fake) = Harness::new( + vec![Capability::Sharing, Capability::Contacts, Capability::Mail], + vec![ + existing("s1", ShareTarget::User("ann".into()), Permission::Edit), + existing("s2", ShareTarget::Group("finance".into()), Permission::View), + ], + ); + h.open(); + let output = h.frame(Vec::new()); + assert!(says(&output, "Who has access")); + assert!(says(&output, "ann")); + assert!(says(&output, "finance (group)")); + assert_eq!(buttons(&output).iter().filter(|b| *b == "Withdraw").count(), 2); + + h.click("Withdraw"); + assert!(fake.seen().iter().any(|r| matches!(r, Request::Withdraw { share_id } if share_id == "s1" || share_id == "s2"))); + + // It stays on the list until the server agrees it is gone. + let output = h.frame(Vec::new()); + assert!(says(&output, "Withdrawing…")); + let Some((Request::Withdraw { share_id }, reply)) = fake.take(0) else { panic!("expected a withdrawal in flight") }; + reply.answer(Answer::Withdrawn { share_id: share_id.clone() }); + let output = h.frame(Vec::new()); + assert_eq!(buttons(&output).iter().filter(|b| *b == "Withdraw").count(), 1, "one left"); +} + +#[test] +fn a_document_nobody_has_been_given_says_so() { + let (mut h, _fake) = Harness::everything(); + h.open(); + let output = h.frame(Vec::new()); + assert!(says(&output, "Nobody else yet")); +} + +// ---- what the dialog refuses to offer ------------------------------------- + +#[test] +fn a_server_without_sharing_draws_no_dialog_at_all() { + let (mut h, fake) = Harness::new(vec![Capability::Files, Capability::Contacts], Vec::new()); + assert!(!h.dialog.available()); + h.dialog.open(DOCUMENT, "Budget 2026.xlsx"); + assert!(!h.dialog.is_open(), "a feature the provider lacks is hidden, not offered"); + let output = h.frame(Vec::new()); + assert!(buttons(&output).is_empty(), "nothing to click; saw {:?}", buttons(&output)); + assert!(!fake.seen().iter().any(|r| matches!(r, Request::Access { .. })), "and nothing was asked about the document"); +} + +#[test] +fn an_unsaved_document_is_told_to_save_rather_than_refused_by_the_server() { + let (mut h, fake) = Harness::everything(); + h.dialog.open("", "Book1"); + let output = h.frame(Vec::new()); + assert!(says(&output, "Save this document somewhere to share it.")); + assert!(control(&output, SEND).is_none(), "there is nothing to share yet"); + assert!(!fake.seen().iter().any(|r| matches!(r, Request::Access { .. }))); +} + +#[test] +fn closing_puts_the_dialog_away() { + let (mut h, _fake) = Harness::everything(); + h.open(); + h.click("Close"); + assert!(!h.dialog.is_open()); + let output = h.frame(Vec::new()); + assert!(buttons(&output).is_empty()); +} + +#[test] +fn a_typed_address_says_how_to_add_it_and_adding_it_works() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.type_and_settle("outside@example.com"); + fake.answer(lookup(Vec::new())); + let output = h.frame(Vec::new()); + assert!(says(&output, "Press Return to share with this address"), "saw {:?}", text(&output)); + assert!(!says(&output, "No matches"), "an address that matched nobody is still a recipient"); + + // Return takes it, and the share carries it as an address. + h.frame(vec![key(egui::Key::Enter)]); + h.frame(Vec::new()); + h.typing = false; + let output = h.frame(Vec::new()); + assert!(buttons(&output).iter().any(|b| b == "Remove outside@example.com"), "saw {:?}", buttons(&output)); + + h.click(SEND); + let parked = fake.parked(); + let Some(Request::Grant(grant)) = parked.first() else { panic!("expected a share, saw {parked:?}") }; + assert_eq!(grant.targets, vec![ShareTarget::Email("outside@example.com".into())]); +} + +#[test] +fn a_name_that_matched_nobody_is_not_offered_as_an_address() { + let (mut h, fake) = Harness::everything(); + h.open(); + h.type_and_settle("nobody"); + fake.answer(lookup(Vec::new())); + let output = h.frame(Vec::new()); + assert!(says(&output, "No matches")); + assert!(!says(&output, "Press Return")); +} diff --git a/crates/cloud/Cargo.toml b/crates/cloud/Cargo.toml new file mode 100644 index 000000000..055feff39 --- /dev/null +++ b/crates/cloud/Cargo.toml @@ -0,0 +1,15 @@ +[package] +name = "craft-cloud" +version.workspace = true +edition.workspace = true +license.workspace = true +repository.workspace = true +rust-version.workspace = true +description = "What a cloud provider offers the Craft apps: files, sharing, contacts, notifications and mail as contracts, with no vendor and no IO" + +[lints] +workspace = true + +[dependencies] +serde = { workspace = true } +thiserror = { workspace = true } diff --git a/crates/cloud/src/error.rs b/crates/cloud/src/error.rs new file mode 100644 index 000000000..ede71ac0c --- /dev/null +++ b/crates/cloud/src/error.rs @@ -0,0 +1,68 @@ +//! One error type for every contract. +//! +//! The cases are the ones a caller acts on differently. A UI shows a different +//! thing for "you may not" than for "the server is unreachable", and a save +//! retries on a conflict where it would not on a refusal. + +use thiserror::Error; + +#[derive(Debug, Error)] +pub enum Error { + /// The provider could not be reached. Worth retrying. + #[error("the provider could not be reached: {0}")] + Unreachable(String), + + /// The credential was rejected. The user has to sign in again. + #[error("the provider rejected the credential")] + Unauthenticated, + + /// Authenticated, and not allowed to do this. Signing in again will not + /// help, so a UI must not offer it. + #[error("not permitted: {0}")] + Forbidden(String), + + /// No such document, folder or share. + #[error("{what} not found: {id}")] + NotFound { what: &'static str, id: String }, + + /// The document changed since the caller last read it. A save that would + /// have overwritten somebody else's work lands here. + #[error("{0} changed since you opened it")] + Conflict(String), + + /// The provider does not offer this at all. + /// + /// Distinct from [`Error::Forbidden`]: there is nothing to grant. A UI + /// hides the feature rather than explaining it. + #[error("this provider does not support {0}")] + Unsupported(&'static str), + + /// The answer did not match the protocol. + #[error("malformed {what}: {detail}")] + Malformed { what: &'static str, detail: String }, + + /// A name or path could not be used safely. Carried, never panicked. + #[error("invalid {what}: {detail}")] + Invalid { what: &'static str, detail: String }, +} + +impl Error { + pub fn not_found(what: &'static str, id: impl Into) -> Error { + Error::NotFound { what, id: id.into() } + } + + pub fn malformed(what: &'static str, detail: impl Into) -> Error { + Error::Malformed { what, detail: detail.into() } + } + + pub fn invalid(what: &'static str, detail: impl Into) -> Error { + Error::Invalid { what, detail: detail.into() } + } + + /// Whether trying again could succeed without the user doing anything. + pub fn is_transient(&self) -> bool { + matches!(self, Error::Unreachable(_)) + } +} + +pub type Result = std::result::Result; diff --git a/crates/cloud/src/lib.rs b/crates/cloud/src/lib.rs new file mode 100644 index 000000000..1f4fe0930 --- /dev/null +++ b/crates/cloud/src/lib.rs @@ -0,0 +1,189 @@ +//! What a cloud provider has to offer the Craft apps, and nothing about who +//! provides it. +//! +//! Every capability here is an RFC or an ordinary HTTP API that many systems +//! implement. Files are WebDAV. Contacts are CardDAV. Calendars are CalDAV. +//! Sharing and notification are the only genuinely vendor-shaped parts, and +//! they are small. So there is no reason for an app to know which server it is +//! talking to, and no reason to write the same logic again for the next one. +//! +//! Nothing in this crate opens a socket. Each trait is implemented by a +//! provider crate that brings its own transport, which keeps this testable +//! with no server and keeps the contracts honest about what they need. +//! +//! No type here names a vendor. If a field only makes sense for one product, +//! it belongs in that provider's crate. +//! +//! Nothing here says where an implementation runs. A local adapter may +//! implement these traits against a provider directly, and an application may +//! consume them that way. The contracts do not care. +//! +//! CollabCraft chooses otherwise for its own apps. They reach one service, and +//! that service is the single place a provider is configured, a credential is +//! held and a permission is decided. A desktop binary carrying a provider +//! credential leaks one the moment somebody copies the file, which is what +//! that arrangement exists to prevent. It is a deployment policy, and this +//! crate imposes it on nobody. + +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] + +mod error; +mod types; + +pub use error::{Error, Result}; +pub use types::{ + Capability, Contact, Conversation, Entry, EntryKind, Identity, MailMessage, Notification, Permission, Share, ShareOptions, ShareTarget, +}; + +/// Reading and writing documents. +/// +/// `list` and `shared_with_me` are separate because they answer different +/// questions. One is a folder's contents, the other is everything another +/// person has given this user access to, which has no single parent folder. +pub trait Files { + /// One folder's contents. An empty path means the user's root. + fn list(&self, path: &str) -> Result>; + + /// Everything shared with this user, wherever it lives. + /// + /// A provider with no concept of this returns an empty list rather than an + /// error, because "nobody has shared anything with you" and "this server + /// cannot tell you" look the same to a file picker. + fn shared_with_me(&self) -> Result>; + + /// One document's bytes. + fn read(&self, id: &str) -> Result>; + + /// A byte range of one document. + /// + /// Defaulted to a full [`read`](Self::read) and a slice, so providers that have no + /// ranged GET still satisfy the trait. A provider with real range support + /// overrides this. + fn read_range(&self, id: &str, offset: u64, length: u64) -> Result> { + let bytes = self.read(id)?; + let start = usize::try_from(offset).unwrap_or(usize::MAX); + if start >= bytes.len() { + return Ok(Vec::new()); + } + let take = usize::try_from(length).unwrap_or(usize::MAX); + let end = start.saturating_add(take).min(bytes.len()); + Ok(bytes[start..end].to_vec()) + } + + /// Replace one document's bytes. + /// + /// `if_match` carries the etag the caller last saw. A provider that + /// supports conditional writes uses it to refuse a save that would + /// overwrite somebody else's, returning [`Error::Conflict`]. Passing + /// `None` means "write regardless", which is what a Save As does. + fn write(&self, id: &str, bytes: &[u8], if_match: Option<&str>) -> Result; + + /// Create a document and return it. + fn create(&self, folder: &str, name: &str, bytes: &[u8]) -> Result; + + /// One document's metadata, without its bytes. + fn stat(&self, id: &str) -> Result; +} + +/// Giving other people access to a document. +/// +/// Persisting a share through the provider matters more than it looks. A share +/// recorded only by the caller would be invisible in the provider's own file +/// manager, so the two would disagree about who can open what. The provider +/// stays the authority. +pub trait Sharing { + /// Share a document. + /// + /// A link share has no recipient, so [`ShareTarget::Link`] is how a caller + /// asks for one. The returned [`Share::url`] is what to hand out. + fn share(&self, id: &str, with: &ShareTarget, permission: Permission, options: &ShareOptions) -> Result; + + /// Who currently has access. + fn shares(&self, id: &str) -> Result>; + + /// Withdraw one share. + fn unshare(&self, share_id: &str) -> Result<()>; +} + +/// Looking people up, for a share dialog's autocomplete. +/// +/// This is the only thing the share dialog needs, so it is the only thing the +/// contract exposes. A full address book API would be a bigger surface for no +/// gain. +pub trait Contacts { + /// People matching a partial name or address. + /// + /// `limit` exists because this runs on every keystroke. A provider is free + /// to return fewer. + fn search(&self, query: &str, limit: usize) -> Result>; +} + +/// Telling somebody something happened. +/// +/// Separate from [`Mail`] on purpose. An in-app notification is cheap, arrives +/// instantly and is read in context. An email is none of those and is the +/// right choice for somebody who is not currently in the app. A share usually +/// wants both. +pub trait Notifications { + fn notify(&self, user: &str, notification: &Notification) -> Result<()>; +} + +/// Sending mail as the provider. +pub trait Mail { + fn send(&self, message: &MailMessage) -> Result<()>; +} + +/// Who the caller is, according to the provider. +pub trait Accounts { + /// Resolve the signed-in user. + fn me(&self) -> Result; +} + +/// Working together on a document, through whatever the provider calls it. +/// +/// Defaulted throughout. A provider without the feature writes an empty +/// `impl` and reports [`Capability::Conversation`] as absent. The caller +/// then draws no control at all. +pub trait Conversations { + /// What this provider calls the feature. `None` where it has none. + /// + /// Separate from the capability on purpose. The name is a property of + /// the provider. Whether it is available is a property of the + /// instance, and an administrator decides that one. + fn conversation_name(&self) -> Option { + None + } + + /// Start a conversation about a document, or join the one already there. + /// + /// Two people pressing the same control have to arrive in the same + /// place, so this is expected to be idempotent for a given document. + /// + /// `id` is the provider's own handle and means nothing outside the + /// account it came from. A conversation is therefore keyed on the + /// provider, the account and the document together, and `self` carries + /// the first two. A document copied into another account is a different + /// document to its provider, so it gets a conversation of its own. + /// Nothing here can attach one account's thread to another's. + fn conversation(&self, _id: &str, _title: &str) -> Result { + Err(Error::Unsupported("conversations")) + } +} + +/// Everything one provider can do. +/// +/// A provider implements the capabilities it has and reports the rest as +/// absent, so a caller can hide a share button on a server with no sharing +/// rather than offering a feature that will fail. +pub trait Provider: Files + Sharing + Contacts + Notifications + Mail + Accounts + Conversations { + /// A stable identifier, such as `nextcloud`. Used in configuration and + /// logs, never shown to a user. + fn id(&self) -> &str; + + /// What this provider actually supports. + fn capabilities(&self) -> Vec; + + fn supports(&self, capability: Capability) -> bool { + self.capabilities().contains(&capability) + } +} diff --git a/crates/cloud/src/types.rs b/crates/cloud/src/types.rs new file mode 100644 index 000000000..ab8c005a1 --- /dev/null +++ b/crates/cloud/src/types.rs @@ -0,0 +1,216 @@ +//! The data the contracts pass around. +//! +//! Every type here is plain and vendor-neutral. A field that only means +//! something to one product belongs in that provider's crate. + +use serde::{Deserialize, Serialize}; + +/// What a provider can do. +/// +/// Reported rather than assumed, so a caller hides a share button on a +/// server without sharing instead of offering a feature that fails on use. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum Capability { + Files, + SharedWithMe, + Sharing, + Contacts, + Notifications, + Mail, + /// Conditional writes, so a save can refuse to clobber a newer version. + Etags, + /// Public links. Absent on a server that forbids them, and the dialog then + /// offers no Copy link rather than a button that fails. + LinkShares, + /// A key on a public link. This is what most places mean when they talk + /// about sharing with somebody who has no account. + LinkPassword, + /// The server requires that key, so a link cannot be made without one. + LinkPasswordRequired, + /// An expiry date on a share. + ShareExpiry, + /// The provider can tell a recipient that something was shared with them. + /// + /// Distinct from [`Capability::Mail`], which is about sending arbitrary + /// mail. A provider commonly has this and not that: it will notify the + /// person a share names without offering any way to send mail in general. + ShareNotify, + /// A conversation about a document, such as a call or a chat room. + /// + /// Every provider that has this calls it something else, so the name + /// comes from [`crate::Conversations::conversation_name`]. Reported + /// separately from that name: a provider knows what it would call the + /// feature whether or not an administrator installed it. + Conversation, +} + +/// A file or folder. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Entry { + /// An opaque handle for reading, writing and sharing this entry. + /// + /// Only the provider that issued it may interpret it. A caller passes it + /// back and never parses it. + pub id: String, + /// The stable identity used for a collaboration room. + /// + /// Separate from `id` on purpose. A provider's read and write handle is + /// often a path, and a path changes when somebody renames or moves the + /// file. A room keyed on that would silently split in two mid-session, + /// with each half seeing only its own edits. This one survives a rename. + pub room: String, + /// What to show the user. + pub name: String, + /// Where it sits, for a breadcrumb. Never a handle. + pub path: String, + pub kind: EntryKind, + /// Bytes, absent for a folder. + pub size: Option, + /// RFC 3339. Absent when the provider does not say. + pub modified: Option, + /// For matching a document to the app that opens it. + pub mime: Option, + /// The version the caller last saw, for a conditional write. + pub etag: Option, + /// Whether this user may change it. A read-only share still lists. + pub writable: bool, + /// Who shared it, when it came from somebody else. + pub shared_by: Option, +} + +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum EntryKind { + File, + Folder, +} + +/// A person, as a share dialog needs them. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Contact { + /// What the provider wants back when sharing with this person. + pub id: String, + /// How to share with them, decided by the provider and never guessed. + /// + /// The distinction is not cosmetic. A contact with an account is a user + /// share. One known only by address is an email share. Sharing an address + /// as though it were a user id fails with "not found", because no such + /// user exists, and nothing in `id` alone says which case this is. + pub target: ShareTarget, + /// What to show. A display name where there is one. + pub name: String, + pub email: Option, + /// An avatar, as a URL the client may fetch. Never image bytes: a search + /// returning ten people would otherwise carry ten pictures nobody asked + /// for yet. + pub avatar: Option, + /// A group rather than a person. Shown differently and shared differently. + pub is_group: bool, +} + +/// Who to share with. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case", tag = "kind", content = "id")] +pub enum ShareTarget { + User(String), + Group(String), + /// Somebody with no account, reached by address. + Email(String), + /// Anybody holding the link. + Link, +} + +/// What a share allows. +/// +/// Deliberately coarse. Providers disagree on the fine detail, and a dialog +/// offering a distinction the server cannot keep is worse than one that does +/// not. +#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(rename_all = "snake_case")] +pub enum Permission { + /// Open and read. No edits reach the document. + View, + /// Open and edit. + Edit, +} + +/// Everything optional about a share. +/// +/// A struct rather than more positional arguments. The list grew past the +/// point where a call site reads correctly, and a provider that cannot honour +/// one of these needs to see which it was given. +#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)] +pub struct ShareOptions { + /// Shown to the recipient. + pub note: Option, + /// Send mail where the provider can. + pub notify: bool, + /// A key the recipient must present. Only meaningful for a link, and + /// refused by a server that does not allow one. + pub password: Option, + /// `YYYY-MM-DD`. After this the share stops working. + pub expires: Option, +} + +/// Where to go to work together on a document. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Conversation { + /// Where to join. Handed to a browser, or to the provider's own app. + pub url: String, + /// What the provider calls the feature, for the control's wording. A + /// menu item reading "Work together in Talk" is built from this. + pub name: String, +} + +/// A share that exists. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Share { + pub id: String, + pub target: ShareTarget, + /// What to call the recipient, where the provider says. + /// + /// A share carries the handle the server wants back, which for a user is + /// an account id. People are not known to each other by account id. A + /// provider that knows the difference says so here. + pub display: Option, + pub permission: Permission, + /// Present for a link share, absent otherwise. + pub url: Option, + pub note: Option, + /// RFC 3339. + pub created: Option, +} + +/// Something worth telling a user about, in the app. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Notification { + /// A short machine-readable kind, such as `document_shared`. Lets a client + /// decide how to render without parsing prose. + pub kind: String, + pub subject: String, + pub body: Option, + /// Where to go when it is clicked. + pub link: Option, +} + +/// An email to send. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct MailMessage { + pub to: Vec, + pub subject: String, + pub body: String, + /// Whether `body` is HTML. Plain text otherwise. + pub html: bool, +} + +/// The signed-in user, as the provider sees them. +#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +pub struct Identity { + /// The provider's identifier for this account. + pub id: String, + /// What to show. Never an identity: two people can share a display name. + pub display: String, + pub email: Option, + pub avatar: Option, +} diff --git a/crates/cms/README.md b/crates/cms/README.md index b3a178704..43b9f26da 100644 --- a/crates/cms/README.md +++ b/crates/cms/README.md @@ -81,6 +81,12 @@ Buffers are checked once per call, before any pixel is written. the exact and float paths compare each pixel with white; all other colours are left as the profiles give them. With a profile whose white falls between its nodes (`coated-cmyk`: 0.4 % C), the last step to white is that much larger than its neighbours. +* Black preservation (opt-in, `BlackPreserving`): for CMYK → CMYK, a colour with exactly zero + C, M and Y comes out as exactly `(0, 0, 0, K')`, where `K'` is the destination black whose + K-only L* equals the source's (both K ramps sampled at 1024 points when the transform is + built, with its intent and BPC). The test is exact zero, so an input with any chromatic ink + takes the ordinary path. Absolute colorimetric, non-CMYK profiles and K ramps that reverse at + one of the 1024 samples are refused (a reversal between samples is not detected). ## Built-in profiles (all CC0-1.0, generated by this crate) diff --git a/crates/cms/profiles/craft-coated-fogra39.icc b/crates/cms/profiles/craft-coated-fogra39.icc index 13590238e..1ef3cad1f 100644 Binary files a/crates/cms/profiles/craft-coated-fogra39.icc and b/crates/cms/profiles/craft-coated-fogra39.icc differ diff --git a/crates/cms/src/black.rs b/crates/cms/src/black.rs new file mode 100644 index 000000000..f80defeef --- /dev/null +++ b/crates/cms/src/black.rs @@ -0,0 +1,205 @@ +//! K-only black preservation for CMYK → CMYK transforms. +//! +//! A CMYK → CMYK transform goes through the three-component PCS, so black alone (C = M = Y = 0) +//! comes out as a four-ink mix. ISO 32000-2 §8.6.5.7 notes that this loses fidelity in the black +//! component. ICC defines no black preservation; this is a named policy the caller opts into. +//! +//! [`BlackPreserving`] converts like its [`Transform`], except that a colour with exactly zero +//! cyan, magenta and yellow becomes exactly `(0, 0, 0, K')`. `K'` is the destination black whose +//! K-only L* equals the source's, both measured to Lab with the transform's own intent and BPC +//! setting: both ramps are sampled once, at construction, and the destination ramp is inverted. +//! A source black darker than the destination's maximum black maps to K = 1. The test is exact zero, so the transform is discontinuous at C = M = Y = 0: an input +//! with any chromatic ink takes the ordinary path. + +use crate::transform::{Transform, TransformOptions}; +use crate::{Builtin, CmsError, ColorSpace, Intent, Profile, invalid_arg}; + +/// Samples along each K-only ramp. Linear interpolation between samples of a smooth ramp is far +/// below the 16-bit quantum. +const K_SAMPLES: usize = 1024; +/// Slack for the monotonicity checks (L* units, K units). +const MONOTONIC_EPS: f64 = 1e-6; + +/// A CMYK → CMYK transform that keeps black-only colours black-only. +#[derive(Debug)] +pub struct BlackPreserving { + transform: Transform, + /// Destination K for source K at `i / (K_SAMPLES - 1)`; `K_SAMPLES` values in `[0, 1]`. + curve: Vec, + /// Source K from which the source black is at least as dark as the destination's darkest: + /// mapped to exactly 1. Infinite when the destination's black is the darker. + saturate: f32, + /// The mapping at the 256 8-bit source codes, already quantised. + curve8: [u8; 256], +} + +impl BlackPreserving { + /// Transform from `src` to `dst` with black preservation. + /// + /// Errors with [`CmsError::InvalidArgument`] when either profile is not CMYK or the intent is + /// absolute colorimetric (which reproduces the source's paper and black, so there is no + /// black to map), and with [`CmsError::Unsupported`] when a profile's K-only ramp is not + /// monotonic at its 1024 samples (black that gets lighter as K rises has no equal-lightness + /// inverse; a reversal between samples is not detected). Other errors + /// are those of [`Transform::with_options`]. + pub fn new(src: &Profile, dst: &Profile, opts: TransformOptions) -> Result { + if src.color_space != ColorSpace::Cmyk || dst.color_space != ColorSpace::Cmyk { + return Err(invalid_arg("black preservation needs CMYK source and destination profiles")); + } + if opts.intent == Intent::AbsoluteColorimetric { + return Err(invalid_arg("black preservation does not apply to absolute colorimetric")); + } + let transform = Transform::with_options(src, dst, opts)?; + let src_l = k_ramp_lightness(src, opts)?; + let dst_l = k_ramp_lightness(dst, opts)?; + let (curve, saturate) = k_curve(&src_l, &dst_l)?; + let mut curve8 = [0u8; 256]; + for (code, slot) in curve8.iter_mut().enumerate() { + *slot = quantise(map(&curve, saturate, code as f32 / 255.0), 255.0) as u8; + } + Ok(BlackPreserving { transform, curve, saturate, curve8 }) + } + + /// The ordinary transform, which every colour with chromatic ink goes through. Converting with + /// it directly does not preserve black. + pub fn transform(&self) -> &Transform { + &self.transform + } + + /// Destination K for a black-only source colour of `k` (clamped to `[0, 1]`). + pub fn map_k(&self, k: f32) -> f32 { + map(&self.curve, self.saturate, k) + } + + /// Exact evaluation of one colour; slices as in [`Transform::eval`]. + pub fn eval(&self, input: &[f32], out: &mut [f32]) -> Result<(), CmsError> { + self.transform.eval(input, out)?; + self.patch_one(input, out); + Ok(()) + } + + /// Lookup-table evaluation of one colour; slices as in [`Transform::eval`]. + pub fn eval_fast(&self, input: &[f32], out: &mut [f32]) -> Result<(), CmsError> { + self.transform.eval_fast(input, out)?; + self.patch_one(input, out); + Ok(()) + } + + /// Converts float pixels; layout and errors as in [`Transform::convert_f32`]. + pub fn convert_f32(&self, src: &[f32], src_stride: usize, dst: &mut [f32], dst_stride: usize, copy_extra: bool) -> Result<(), CmsError> { + self.transform.convert_f32(src, src_stride, dst, dst_stride, copy_extra)?; + for (s, d) in src.chunks_exact(src_stride).zip(dst.chunks_exact_mut(dst_stride)) { + self.patch_one(s, d); + } + Ok(()) + } + + /// Converts 8-bit pixels; layout and errors as in [`Transform::convert_u8`]. + pub fn convert_u8(&self, src: &[u8], src_stride: usize, dst: &mut [u8], dst_stride: usize, copy_extra: bool) -> Result<(), CmsError> { + self.transform.convert_u8(src, src_stride, dst, dst_stride, copy_extra)?; + for (s, d) in src.chunks_exact(src_stride).zip(dst.chunks_exact_mut(dst_stride)) { + if let ([0, 0, 0, k, ..], [c, m, y, kd, ..]) = (s, d) { + (*c, *m, *y) = (0, 0, 0); + *kd = self.curve8[usize::from(*k)]; + } + } + Ok(()) + } + + /// Converts 16-bit pixels; layout and errors as in [`Transform::convert_u16`]. + pub fn convert_u16(&self, src: &[u16], src_stride: usize, dst: &mut [u16], dst_stride: usize, copy_extra: bool) -> Result<(), CmsError> { + self.transform.convert_u16(src, src_stride, dst, dst_stride, copy_extra)?; + for (s, d) in src.chunks_exact(src_stride).zip(dst.chunks_exact_mut(dst_stride)) { + if let ([0, 0, 0, k, ..], [c, m, y, kd, ..]) = (s, d) { + (*c, *m, *y) = (0, 0, 0); + *kd = quantise(self.map_k(f32::from(*k) / 65535.0), 65535.0) as u16; + } + } + Ok(()) + } + + fn patch_one(&self, input: &[f32], out: &mut [f32]) { + if let ([0.0, 0.0, 0.0, k, ..], [c, m, y, kd, ..]) = (input, out) { + (*c, *m, *y) = (0.0, 0.0, 0.0); + *kd = self.map_k(*k); + } + } +} + +/// The sampled mapping from the source to the destination K-only ramp, and the source K at +/// which the destination's darkest black is reached (the `saturate` field). +fn k_curve(src_l: &[f64], dst_l: &[f64]) -> Result<(Vec, f32), CmsError> { + let curve: Vec = src_l.iter().map(|&l| invert(dst_l, l) as f32).collect(); + if !curve.windows(2).all(|w| f64::from(w[0]) - f64::from(w[1]) <= MONOTONIC_EPS) { + return Err(CmsError::Unsupported("black preservation: the K mapping is not monotonic".into())); + } + let saturate = match (src_l.last(), dst_l.last()) { + (Some(&s), Some(&d)) if s < d => invert(src_l, d) as f32, + _ => f32::INFINITY, + }; + Ok((curve, saturate)) +} + +/// L* of `p`'s K-only ramp at `K_SAMPLES` points, light to dark; refused when it is not +/// non-increasing. +fn k_ramp_lightness(p: &Profile, opts: TransformOptions) -> Result, CmsError> { + let to_lab = Transform::with_options(p, Builtin::LabD50.profile(), TransformOptions { precise_float: true, ..opts })?; + let mut ramp = Vec::with_capacity(K_SAMPLES); + let mut lab = [0.0f32; 3]; + for i in 0..K_SAMPLES { + let k = i as f32 / (K_SAMPLES - 1) as f32; + to_lab.eval(&[0.0, 0.0, 0.0, k], &mut lab)?; + ramp.push(f64::from(lab[0]) * 100.0); + } + if !ramp.iter().all(|l| l.is_finite()) || !ramp.windows(2).all(|w| w[1] - w[0] <= MONOTONIC_EPS) { + return Err(CmsError::Unsupported("black preservation: a K-only ramp is not monotonic".into())); + } + Ok(ramp) +} + +/// The K in `[0, 1]` at which the non-increasing `ramp` reaches `target`, clamped to its ends. +fn invert(ramp: &[f64], target: f64) -> f64 { + let (Some(&first), Some(&last)) = (ramp.first(), ramp.last()) else { return 0.0 }; + if ramp.len() < 2 || target >= first { + return 0.0; + } + if target <= last { + return 1.0; + } + // ramp[lo] > target >= ramp[hi] + let (mut lo, mut hi) = (0usize, ramp.len() - 1); + while hi - lo > 1 { + let mid = lo + (hi - lo) / 2; + if ramp.get(mid).is_some_and(|&v| v > target) { + lo = mid; + } else { + hi = mid; + } + } + let (a, b) = (ramp.get(lo).copied().unwrap_or(first), ramp.get(hi).copied().unwrap_or(last)); + let t = if a - b > MONOTONIC_EPS { (a - target) / (a - b) } else { 0.0 }; + (lo as f64 + t) / (ramp.len() - 1) as f64 +} + +/// Linear interpolation in `curve` (samples over `[0, 1]`) at `k`, clamped; 1 from `saturate`. +fn map(curve: &[f32], saturate: f32, k: f32) -> f32 { + let Some(&last) = curve.last() else { return 0.0 }; + let k = if k.is_nan() { 0.0 } else { k.clamp(0.0, 1.0) }; + if k >= saturate { + return 1.0; + } + let x = k * (curve.len() - 1) as f32; + let i = x.floor() as usize; + match (curve.get(i), curve.get(i + 1)) { + (Some(&a), Some(&b)) => a + (b - a) * (x - i as f32), + _ => last, + } +} + +fn quantise(v: f32, max: f32) -> f32 { + (v.clamp(0.0, 1.0) * max + 0.5).floor() +} + +#[cfg(test)] +#[path = "black_tests.rs"] +mod tests; diff --git a/crates/cms/src/black_tests.rs b/crates/cms/src/black_tests.rs new file mode 100644 index 000000000..8752cdaa2 --- /dev/null +++ b/crates/cms/src/black_tests.rs @@ -0,0 +1,149 @@ +use super::*; + +fn coated() -> &'static Profile { + Builtin::CoatedCmyk.profile() +} +fn fogra() -> &'static Profile { + Builtin::CoatedFogra39.profile() +} +fn opts() -> TransformOptions { + TransformOptions::default() +} + +/// L* of a CMYK colour under `p`, measured as the transform with `o` measures it. +fn lightness(p: &Profile, o: TransformOptions, cmyk: [f32; 4]) -> f32 { + let t = Transform::with_options(p, Builtin::LabD50.profile(), o).unwrap(); + let mut lab = [0.0f32; 3]; + t.eval(&cmyk, &mut lab).unwrap(); + lab[0] * 100.0 +} + +#[test] +fn the_plain_transform_turns_black_into_four_inks() { + // What the policy is for: without it, black alone gains chromatic ink across presses. + let t = Transform::with_options(coated(), fogra(), opts()).unwrap(); + let mut out = [0.0f32; 4]; + t.eval(&[0.0, 0.0, 0.0, 0.5], &mut out).unwrap(); + assert!(out[..3].iter().any(|v| *v > 0.01), "{out:?}"); +} + +#[test] +fn black_only_stays_black_only_on_every_path() { + for (src, dst) in [(coated(), fogra()), (fogra(), coated()), (fogra(), fogra())] { + let bp = BlackPreserving::new(src, dst, opts()).unwrap(); + for k in [0.0f32, 0.1, 0.5, 0.9, 1.0] { + for fast in [false, true] { + let mut out = [1.0f32; 4]; + if fast { bp.eval_fast(&[0.0, 0.0, 0.0, k], &mut out) } else { bp.eval(&[0.0, 0.0, 0.0, k], &mut out) }.unwrap(); + assert_eq!(out[..3], [0.0; 3], "k {k} fast {fast}"); + assert_eq!(out[3], bp.map_k(k)); + } + } + let src8: Vec = (0..=255u8).flat_map(|k| [0, 0, 0, k, 7]).collect(); + let mut dst8 = vec![0u8; src8.len()]; + bp.convert_u8(&src8, 5, &mut dst8, 5, true).unwrap(); + for (k, px) in dst8.as_chunks::<5>().0.iter().enumerate() { + assert_eq!(px[..3], [0; 3], "u8 k {k}"); + assert!((f32::from(px[3]) - bp.map_k(k as f32 / 255.0) * 255.0).abs() <= 0.5, "u8 k {k}: {}", px[3]); + assert_eq!(px[4], 7, "extra channel copied"); + } + let src16: Vec = (0..=64u16).flat_map(|k| [0, 0, 0, k * 1023]).collect(); + let mut dst16 = vec![0u16; src16.len()]; + bp.convert_u16(&src16, 4, &mut dst16, 4, false).unwrap(); + for (px, k) in dst16.as_chunks::<4>().0.iter().zip(src16.as_chunks::<4>().0) { + assert_eq!(px[..3], [0; 3], "u16 {k:?}"); + assert!((f32::from(px[3]) - bp.map_k(f32::from(k[3]) / 65535.0) * 65535.0).abs() <= 0.5, "u16 {k:?}: {}", px[3]); + } + let srcf: Vec = (0..=10).flat_map(|k| [0.0, 0.0, 0.0, k as f32 / 10.0]).collect(); + let mut dstf = vec![0.0f32; srcf.len()]; + bp.convert_f32(&srcf, 4, &mut dstf, 4, false).unwrap(); + for (px, k) in dstf.as_chunks::<4>().0.iter().zip(srcf.as_chunks::<4>().0) { + assert_eq!(*px, [0.0, 0.0, 0.0, bp.map_k(k[3])], "f32 {k:?}"); + } + } +} + +#[test] +fn the_destination_black_matches_the_source_lightness() { + // Measured worst error over 201 K steps, both directions, both intents, BPC on and off: + // 0.007 L*. + for intent in [Intent::RelativeColorimetric, Intent::Perceptual] { + for bpc in [true, false] { + let o = TransformOptions { intent, bpc, ..opts() }; + for (src, dst) in [(coated(), fogra()), (fogra(), coated())] { + let bp = BlackPreserving::new(src, dst, o).unwrap(); + let dst_black = lightness(dst, o, [0.0, 0.0, 0.0, 1.0]); + for k in [0.1f32, 0.3, 0.5, 0.7, 0.9, 1.0] { + let want = lightness(src, o, [0.0, 0.0, 0.0, k]); + if want <= dst_black { + assert_eq!(bp.map_k(k), 1.0, "darker than the destination's black clamps to K = 1"); + continue; + } + let got = lightness(dst, o, [0.0, 0.0, 0.0, bp.map_k(k)]); + assert!((got - want).abs() < 0.02, "{intent:?} bpc {bpc} k {k}: L* {got} for {want}"); + } + assert_eq!(bp.map_k(0.0), 0.0, "paper stays paper"); + assert!(bp.map_k(1.0) > 0.95, "full black stays near full black: {}", bp.map_k(1.0)); + assert!(bp.map_k(0.25) < bp.map_k(0.75)); + } + } + } + let same = BlackPreserving::new(fogra(), fogra(), opts()).unwrap(); + for k in [0.0f32, 0.2, 0.6, 1.0] { + assert!((same.map_k(k) - k).abs() < 1e-3, "{k} -> {}", same.map_k(k)); + } +} + +#[test] +fn colours_with_any_chromatic_ink_take_the_ordinary_path() { + let bp = BlackPreserving::new(coated(), fogra(), opts()).unwrap(); + for input in [[1e-6f32, 0.0, 0.0, 0.5], [0.0, 0.2, 0.0, 0.5], [0.3, 0.3, 0.3, 0.0], [0.0, 0.0, 1.0, 1.0]] { + let (mut a, mut b) = ([0.0f32; 4], [0.0f32; 4]); + bp.eval(&input, &mut a).unwrap(); + bp.transform().eval(&input, &mut b).unwrap(); + assert_eq!(a, b, "{input:?}"); + } + let src = [1u8, 0, 0, 128, 0, 1, 0, 128]; + let (mut a, mut b) = ([0u8; 8], [0u8; 8]); + bp.convert_u8(&src, 4, &mut a, 4, false).unwrap(); + bp.transform().convert_u8(&src, 4, &mut b, 4, false).unwrap(); + assert_eq!(a, b); +} + +#[test] +fn refusals_and_hostile_values() { + let srgb = Builtin::Srgb.profile(); + assert!(matches!(BlackPreserving::new(srgb, fogra(), opts()), Err(CmsError::InvalidArgument(_)))); + assert!(matches!(BlackPreserving::new(fogra(), srgb, opts()), Err(CmsError::InvalidArgument(_)))); + let abs = TransformOptions { intent: Intent::AbsoluteColorimetric, ..opts() }; + assert!(matches!(BlackPreserving::new(fogra(), coated(), abs), Err(CmsError::InvalidArgument(_)))); + let bp = BlackPreserving::new(coated(), fogra(), opts()).unwrap(); + for k in [f32::NAN, f32::INFINITY, f32::NEG_INFINITY, -1.0, 2.0] { + assert!((0.0..=1.0).contains(&bp.map_k(k)), "{k}"); + } + let mut out = [0.0f32; 4]; + assert!(bp.eval(&[0.0; 3], &mut out).is_err(), "short input"); + assert!(bp.convert_u8(&[0, 0, 0, 9, 0], 4, &mut [0u8; 4], 4, false).is_err(), "partial pixel"); + assert_eq!(invert(&[], 50.0), 0.0); + assert_eq!(invert(&[100.0], 50.0), 0.0); + assert_eq!(invert(&[100.0, 0.0], 150.0), 0.0); + assert_eq!(invert(&[100.0, 0.0], -5.0), 1.0); + assert!((invert(&[100.0, 50.0, 0.0], 25.0) - 0.75).abs() < 1e-12); + assert_eq!(map(&[], f32::INFINITY, 0.5), 0.0); +} + +#[test] +fn black_beyond_the_destination_maximum_maps_to_full_black_between_samples() { + // Source L* = 100 (1 - K), destination L* = 100 - 50 K: from K = 0.5 the source is darker + // than any destination black, and 0.5 falls between the 1024 samples. + let ramp = |f: fn(f64) -> f64| (0..K_SAMPLES).map(|i| f(i as f64 / (K_SAMPLES - 1) as f64)).collect::>(); + let (src, dst) = (ramp(|k| 100.0 * (1.0 - k)), ramp(|k| 100.0 - 50.0 * k)); + let (curve, saturate) = k_curve(&src, &dst).unwrap(); + assert!((saturate - 0.5).abs() < 1e-6, "{saturate}"); + for k in [0.5001f32, 0.6, 1.0] { + assert_eq!(map(&curve, saturate, k), 1.0, "{k}"); + } + assert!((map(&curve, saturate, 0.25) - 0.5).abs() < 1e-4); + let (_, never) = k_curve(&dst, &src).unwrap(); + assert_eq!(never, f32::INFINITY, "a lighter source never saturates"); +} diff --git a/crates/cms/src/lib.rs b/crates/cms/src/lib.rs index 949164b51..8c2176a98 100644 --- a/crates/cms/src/lib.rs +++ b/crates/cms/src/lib.rs @@ -19,6 +19,7 @@ //! CIE 15, and Adobe's published black point compensation paper. #![forbid(unsafe_code)] +pub mod black; pub mod builtin; mod builtin_v2; pub mod clut; @@ -40,6 +41,7 @@ pub mod transform; mod write; pub mod write_v2; +pub use black::BlackPreserving; pub use builtin::Builtin; pub use clut::Clut; pub use curve::Curve; diff --git a/crates/cms/src/profile.rs b/crates/cms/src/profile.rs index eac2e4500..786750479 100644 --- a/crates/cms/src/profile.rs +++ b/crates/cms/src/profile.rs @@ -224,7 +224,8 @@ pub struct Profile { pub b2a: [Option; 3], /// The bytes this profile was parsed from (or encoded to), kept for byte-exact embedding. pub(crate) bytes: Option>>, - pub(crate) hash: std::sync::OnceLock, + /// Lazily computed content hash: a cache, not part of the profile's identity. + pub(crate) hash: HashCache, } impl Profile { @@ -385,7 +386,7 @@ impl Profile { /// fixed-key 64-bit hash, so a crafted profile can share another's: equal hashes only narrow /// the search, [`Profile::same_bytes`] decides. pub fn content_hash(&self) -> u64 { - *self.hash.get_or_init(|| { + *self.hash.0.get_or_init(|| { use std::hash::{Hash, Hasher}; let mut h = std::collections::hash_map::DefaultHasher::new(); self.to_bytes().hash(&mut h); @@ -594,7 +595,7 @@ mod tests { /// `p` with the content hash of `other`: the hash is a fixed-key 64-bit SipHash, so a /// crafted profile can have another's (#8613). Setting it stands in for finding one. fn with_hash_of(p: &Profile, other: &Profile) -> Profile { - let p = Profile { hash: std::sync::OnceLock::from(other.content_hash()), ..p.clone() }; + let p = Profile { hash: HashCache(std::sync::OnceLock::from(other.content_hash())), ..p.clone() }; assert_eq!(p.content_hash(), other.content_hash()); p } @@ -633,3 +634,15 @@ mod tests { assert_eq!(eval(&cached(srgb, lab, opts).unwrap()), sr); } } + +/// A profile's lazily computed content hash. Whether it has been computed yet depends on who asked +/// first (a shared built-in profile is hashed by whichever caller runs first), so it never takes part +/// in a profile's equality. +#[derive(Clone, Debug, Default)] +pub(crate) struct HashCache(std::sync::OnceLock); + +impl PartialEq for HashCache { + fn eq(&self, _: &Self) -> bool { + true + } +} diff --git a/crates/cms/src/synth.rs b/crates/cms/src/synth.rs index d80eb2be9..cb2c2f397 100644 --- a/crates/cms/src/synth.rs +++ b/crates/cms/src/synth.rs @@ -19,6 +19,9 @@ //! L* is scaled onto the device black, chroma is softly compressed against a gamut boundary //! descriptor sampled from the forward model — then solved as above. //! +//! That is [`GamutMapping::Legacy`]. [`GamutMapping::Oklab`] maps out-of-gamut colours in Oklab +//! instead and gives saturation its own table; the Coated FOGRA39 built-in uses it. +//! //! The model is plausible for coated offset, not a measured characterisation: use a real //! profile from your print provider for production print. //! @@ -51,6 +54,11 @@ pub struct CmykParams { pub k_max: f64, /// Exponent of the black generation curve above `gcr_start`. pub gcr_gamma: f64, + /// Black generation as a curve of `[gray component, black]` points with increasing gray + /// components in `[0, 1]`, interpolated linearly and held flat beyond the ends. Empty by + /// default: black is then `k_max` times the ramp of `gcr_start` and `gcr_gamma` (the curve + /// of the shipped Photocraft profile). + pub gcr_curve: Vec<[f64; 2]>, /// Tone value increase at 50 % for C, M, Y, K. pub tvi: [f64; 4], /// Grid points of the AToB (4D) and BToA (3D) tables. @@ -63,6 +71,32 @@ pub struct CmykParams { /// encoding and separates to a trace of ink. Off by default, which keeps the bytes of the /// shipped Photocraft profile. pub white_on_node: bool, + /// How the BToA tables bring colours into the gamut. [`GamutMapping::Legacy`] by default, + /// which keeps the bytes of the shipped Photocraft profile. + pub mapping: GamutMapping, +} + +/// How the BToA tables map colours the printer cannot reach. +#[derive(Clone, Copy, Debug, PartialEq)] +pub enum GamutMapping { + /// The shipped Photocraft profile: out-of-gamut colours land on the closest reachable + /// colour (ΔE76); perceptual scales L* onto the device black and compresses Lab chroma; + /// saturation shares the perceptual table. + Legacy, + /// Gamut mapping in Oklab, whose hue lines stay perceptually constant (a CIELAB hue line + /// from a saturated blue toward grey drifts toward purple; an Oklab one does not): + /// + /// * **Colorimetric**: in-gamut colours separate exactly. An out-of-gamut colour takes the + /// closest colour the printer reaches in Oklab, lightness and hue weighted above chroma, + /// and more so the further outside it is; black is generated from the clipped colour, so + /// inks the clip drives to 100 % stay there. + /// * **Perceptual** and **saturation**: the ICC v4 perceptual reference black is mapped + /// onto the device black linearly in XYZ (as black point compensation does) for neutrals, + /// fading out with Oklab chroma, so greys separate as with colorimetric + BPC and colourful + /// colours keep their lightness. Perceptual then compresses Oklab chroma above `knee` × + /// the gamut boundary into the boundary; saturation scales Oklab chroma by `saturation` + /// and clips as colorimetric does. + Oklab { knee: f64, saturation: f64 }, } impl Default for CmykParams { @@ -74,10 +108,12 @@ impl Default for CmykParams { gcr_start: 0.2, k_max: 0.95, gcr_gamma: 1.1, + gcr_curve: Vec::new(), tvi: [0.14, 0.14, 0.14, 0.17], grid_a2b: 11, grid_b2a: 21, white_on_node: false, + mapping: GamutMapping::Legacy, } } } @@ -189,6 +225,11 @@ impl Forward for TableForward { /// Bounded least-squares solve for C, M, Y given K, minimising ΔE76 to `target`, subject to /// `C + M + Y ≤ limit` (projected Levenberg–Marquardt with a numerical Jacobian). fn solve_cmy(model: &F, target: [f64; 3], k: f64, limit: f64, seeds: &[[f64; 3]]) -> ([f64; 3], f64) { + solve_cmy_by(model, k, limit, seeds, |l| [l[0] - target[0], l[1] - target[1], l[2] - target[2]]) +} + +/// [`solve_cmy`] minimising the norm of `residual(lab)` instead of ΔE76. +fn solve_cmy_by(model: &F, k: f64, limit: f64, seeds: &[[f64; 3]], residual: impl Fn([f64; 3]) -> [f64; 3]) -> ([f64; 3], f64) { let project = |mut x: [f64; 3]| { for _ in 0..4 { for v in &mut x { @@ -208,10 +249,7 @@ fn solve_cmy(model: &F, target: [f64; 3], k: f64, limit: f6 } x }; - let err = |x: [f64; 3]| { - let l = model.lab([x[0], x[1], x[2], k]); - [l[0] - target[0], l[1] - target[1], l[2] - target[2]] - }; + let err = |x: [f64; 3]| residual(model.lab([x[0], x[1], x[2], k])); let norm2 = |e: [f64; 3]| e[0] * e[0] + e[1] * e[1] + e[2] * e[2]; let mut best = ([0.0; 3], f64::INFINITY); for seed in seeds { @@ -281,13 +319,32 @@ fn solve_cmy(model: &F, target: [f64; 3], k: f64, limit: f6 const SEEDS: [[f64; 3]; 5] = [[0.3, 0.3, 0.3], [0.05, 0.05, 0.05], [0.8, 0.8, 0.8], [0.9, 0.2, 0.2], [0.2, 0.9, 0.9]]; +/// Black for a gray component `g` (the smallest of C, M, Y without black). +fn gcr(p: &CmykParams, g: f64) -> f64 { + let Some(first) = p.gcr_curve.first() else { + // The Photocraft profile's curve. + return if g <= p.gcr_start { 0.0 } else { p.k_max * ((g - p.gcr_start) / (1.0 - p.gcr_start)).powf(p.gcr_gamma) }; + }; + let mut k = first[1]; + for w in p.gcr_curve.windows(2) { + let ([g0, k0], [g1, k1]) = (w[0], w[1]); + if g >= g1 { + k = k1; + } else if g > g0 { + k = k0 + (k1 - k0) * (g - g0) / (g1 - g0); + break; + } + } + k.clamp(0.0, 1.0) +} + /// Colorimetric separation of a relative Lab target: GCR black generation then a CMY solve. pub fn separate(model: &F, p: &CmykParams, target: [f64; 3], warm: Option<[f64; 4]>) -> ([f64; 4], f64) { let mut seeds: Vec<[f64; 3]> = warm.map(|w| vec![[w[0], w[1], w[2]]]).unwrap_or_default(); seeds.extend_from_slice(&SEEDS); let (cmy0, _) = solve_cmy(model, target, 0.0, 3.0, &seeds); let g = cmy0[0].min(cmy0[1]).min(cmy0[2]); - let k = if g <= p.gcr_start { 0.0 } else { p.k_max * ((g - p.gcr_start) / (1.0 - p.gcr_start)).powf(p.gcr_gamma) }; + let k = gcr(p, g); let mut seeds2 = vec![[(cmy0[0] - k).max(0.0), (cmy0[1] - k).max(0.0), (cmy0[2] - k).max(0.0)], cmy0]; seeds2.extend_from_slice(&seeds); let (cmy, de) = solve_cmy(model, target, k, (p.tac - k).max(0.0), &seeds2); @@ -389,6 +446,187 @@ impl Gbd { } } +/// ΔE76 under which a separation counts as reaching its target. +const REACH: f64 = 1.5; +/// Oklab chroma beyond any printable colour: the top of the boundary search. +const OKLAB_CHROMA_MAX: f64 = 0.5; +/// Oklab chroma above which the perceptual and saturation tables no longer lift black: they lift +/// neutrals fully, and less the more colourful a colour is. +const LIFT_CHROMA: f64 = 0.1; +/// Weight of lightness and hue against chroma when a colour just outside the gamut is clipped. +const CLIP_WEIGHT: f64 = 1.5; +/// Growth of that weight with the squared share of chroma the clip loses. +const CLIP_WEIGHT_GROWTH: f64 = 200.0; + +// Oklab (Björn Ottosson, 2020): XYZ (D65) → cone response → cube root → Lab-like axes. +const OKLAB_M1: math::Mat3 = + [[0.8189330101, 0.3618667424, -0.1288597137], [0.0329845436, 0.9293118715, 0.0361456387], [0.0482003018, 0.2643662691, 0.6338517070]]; +const OKLAB_M2: math::Mat3 = + [[0.2104542553, 0.7936177850, -0.0040720468], [1.9779984951, -2.4285922050, 0.4505937099], [0.0259040371, 0.7827717662, -0.8086757660]]; +const OKLAB_M1_INV: math::Mat3 = + [[1.2270138511, -0.5577999807, 0.2812561490], [-0.0405801784, 1.1122568696, -0.0716766787], [-0.0763812845, -0.4214819784, 1.5861632204]]; +const OKLAB_M2_INV: math::Mat3 = [[1.0, 0.3963377774, 0.2158037573], [1.0, -0.1055613458, -0.0638541728], [1.0, -0.0894841775, -1.2914855480]]; + +/// The [`GamutMapping::Oklab`] separations of one forward model. +struct OklabMapper<'a, F: Forward + ?Sized> { + model: &'a F, + p: &'a CmykParams, + knee: f64, + saturation: f64, + /// XYZ scale that maps the v4 perceptual reference black onto the device black (the white + /// stays fixed): `v' = a·v + w·(1 − a)`. + black_scale: f64, + to_d65: math::Mat3, + to_d50: math::Mat3, +} + +impl<'a, F: Forward + ?Sized> OklabMapper<'a, F> { + fn new(model: &'a F, p: &'a CmykParams, knee: f64, saturation: f64) -> Self { + let d65 = math::xy_to_xyz(math::D65_XY); + // The darkest neutral the printer reaches. + let (black, _) = separate(model, p, [0.0, 0.0, 0.0], None); + let device = math::lab_to_xyz([model.lab(black)[0], 0.0, 0.0], math::D50)[1]; + let reference = crate::transform::PERCEPTUAL_BLACK[1]; + OklabMapper { + model, + p, + knee, + saturation, + black_scale: (1.0 - device) / (1.0 - reference), + to_d65: math::bradford(math::D50, d65), + to_d50: math::bradford(d65, math::D50), + } + } + + fn oklab(&self, lab: [f64; 3]) -> [f64; 3] { + let xyz = math::apply(&self.to_d65, math::lab_to_xyz(lab, math::D50)); + math::apply(&OKLAB_M2, math::apply(&OKLAB_M1, xyz).map(f64::cbrt)) + } + + fn lab(&self, ok: [f64; 3]) -> [f64; 3] { + let lms = math::apply(&OKLAB_M2_INV, ok).map(|v| v * v * v); + math::xyz_to_lab(math::apply(&self.to_d50, math::apply(&OKLAB_M1_INV, lms)), math::D50) + } + + /// The most chroma (scale of `ok`'s chroma in `[0, top]`) the printer reaches at `ok`'s + /// lightness and hue, and its separation; `None` when even the neutral is out of reach. + fn boundary(&self, ok: [f64; 3], top: f64, warm: Option<[f64; 4]>) -> Option<(f64, [f64; 4])> { + let (grey, d) = separate(self.model, self.p, self.lab([ok[0], 0.0, 0.0]), warm); + if d > REACH { + return None; + } + let (mut lo, mut hi, mut best) = (0.0, top, grey); + for _ in 0..14 { + let mid = 0.5 * (lo + hi); + let (c, d) = separate(self.model, self.p, self.lab([ok[0], ok[1] * mid, ok[2] * mid]), Some(best)); + if d <= REACH { + lo = mid; + best = c; + } else { + hi = mid; + } + } + Some((lo, best)) + } + + /// Colorimetric: exact in gamut; outside, the closest colour the printer reaches in Oklab, + /// lightness and hue weighted above chroma, and more so the further outside the colour is. + fn clip(&self, lab: [f64; 3], warm: Option<[f64; 4]>) -> [f64; 4] { + let (cmyk, de) = separate(self.model, self.p, lab, warm); + if de <= REACH { + return cmyk; + } + let ok = self.oklab(lab); + let c0 = ok[1].hypot(ok[2]); + // Unit vectors along the colour's chroma and hue directions. + let (u, v) = if c0 > 1e-9 { ([ok[1] / c0, ok[2] / c0], [-ok[2] / c0, ok[1] / c0]) } else { ([1.0, 0.0], [0.0, 1.0]) }; + // Lightness and hue errors weighted by `w`, chroma error by 1; scaled by 100 so the + // solver's step tolerances suit it as they suit ΔE76. + let residual = |w: f64| { + move |l: [f64; 3]| { + let o = self.oklab(l); + let (da, db) = (o[1] - ok[1], o[2] - ok[2]); + [100.0 * w * (o[0] - ok[0]), 100.0 * (da * u[0] + db * u[1]), 100.0 * w * (da * v[0] + db * v[1])] + } + }; + let solve = |w: f64, k: f64, from: [f64; 3]| { + let mut seeds = vec![from]; + seeds.extend_from_slice(&SEEDS); + solve_cmy_by(self.model, k, (self.p.tac - k).max(0.0), &seeds, residual(w)).0 + }; + // A first clip without black measures how far outside the colour is. A colour just + // outside may give up a little lightness and hue to keep its chroma (a red reaches the + // full magenta and yellow edge); one far outside keeps its lightness and hue and loses + // chroma (a saturated blue does not slide along the gamut surface). + let first = solve(CLIP_WEIGHT, 0.0, [cmyk[0], cmyk[1], cmyk[2]]); + let o = self.oklab(self.model.lab([first[0], first[1], first[2], 0.0])); + let loss = if c0 > 1e-9 { (1.0 - o[1].hypot(o[2]) / c0).clamp(0.0, 1.0) } else { 0.0 }; + let w = CLIP_WEIGHT * (1.0 + CLIP_WEIGHT_GROWTH * loss * loss); + let free = solve(w, 0.0, first); + let norm = |c: [f64; 4]| residual(w)(self.model.lab(c)).iter().map(|v| v * v).sum::(); + // Candidates, the closest kept: the separation itself (a colour it nearly reaches stays + // continuous with its in-gamut neighbours), the clip with the separation's black, and + // the clip with black generated from the black-free clip's gray component (inks the + // clip drives to 100 % stay there and black replaces the rest). + let mut best = (norm(cmyk), cmyk); + for k in [cmyk[3], gcr(self.p, free[0].min(free[1]).min(free[2]))] { + for from in [[cmyk[0], cmyk[1], cmyk[2]], free] { + let cmy = solve(w, k, from); + let c = [cmy[0], cmy[1], cmy[2], k]; + let n = norm(c); + if n < best.0 { + best = (n, c); + } + } + } + // Near paper white the gamut narrows to a point: the separation's closest colour keeps + // light tints' chroma where holding lightness would drop them toward bare paper, and + // the table nodes there carry the in-gamut tints between them. The inks blend from the + // clip at L* 85 to the separation at L* 95. + let clip_share = ((95.0 - lab[0]) / 10.0).clamp(0.0, 1.0); + std::array::from_fn(|i| clip_share * best.1[i] + (1.0 - clip_share) * cmyk[i]) + } + + /// Maps the v4 perceptual reference black onto the device black, linearly in XYZ, for + /// neutrals; colourful colours keep their lightness. + fn lift_black(&self, lab: [f64; 3]) -> [f64; 3] { + let ok = self.oklab(lab); + let neutral = (1.0 - ok[1].hypot(ok[2]) / LIFT_CHROMA).clamp(0.0, 1.0); + let a = 1.0 - neutral * (1.0 - self.black_scale); + let xyz = math::lab_to_xyz(lab, math::D50); + math::xyz_to_lab(std::array::from_fn(|i| a * xyz[i] + math::D50[i] * (1.0 - a)), math::D50) + } + + fn perceptual(&self, lab: [f64; 3], warm: Option<[f64; 4]>) -> [f64; 4] { + let lab = self.lift_black(lab); + let ok = self.oklab(lab); + let c = ok[1].hypot(ok[2]); + if c < 1e-9 { + return self.clip(lab, warm); + } + let Some((s, edge)) = self.boundary(ok, OKLAB_CHROMA_MAX / c, warm) else { + return self.clip(lab, warm); + }; + // Chroma above the knee is compressed smoothly into the boundary chroma `cb`. + let cb = s * c; + let knee = self.knee * cb; + if c <= knee { + return self.clip(lab, warm); + } + let c2 = knee + (cb - knee) * ((c - knee) / (cb - knee).max(1e-9)).tanh(); + let f = c2 / c; + if f >= s { + return edge; + } + self.clip(self.lab([ok[0], ok[1] * f, ok[2] * f]), Some(edge)) + } + + fn saturation(&self, lab: [f64; 3], warm: Option<[f64; 4]>) -> [f64; 4] { + let ok = self.oklab(self.lift_black(lab)); + self.clip(self.lab([ok[0], ok[1] * self.saturation, ok[2] * self.saturation]), warm) + } +} + fn lab_node_legacy(i: usize, n: usize) -> f64 { i as f64 / (n - 1) as f64 } @@ -425,6 +663,18 @@ fn white_node_curve(l_axis: bool, x: f64) -> f64 { } fn b2a_table(model: &F, p: &CmykParams, gbd: Option<&Gbd>) -> Result { + b2a_table_with(p, |lab, warm| { + let target = match gbd { + Some(g) => g.compress(lab), + None => lab, + }; + separate(model, p, target, warm).0 + }) +} + +/// Samples a BToA table: `node` separates each relative Lab node, warm-started from the +/// previous node along b. +fn b2a_table_with(p: &CmykParams, node: impl Fn([f64; 3], Option<[f64; 4]>) -> [f64; 4] + Sync) -> Result { let n = p.grid_b2a.max(2); let nodes = n * n * n; let step = (n - 1) as f64; @@ -440,11 +690,7 @@ fn b2a_table(model: &F, p: &CmykParams, gbd: Option<&Gbd>) } else { decode_v2([lab_node_legacy(li, n), lab_node_legacy(ai, n), lab_node_legacy(bi, n)]) }; - let target = match gbd { - Some(g) => g.compress(lab), - None => lab, - }; - let (cmyk, _) = if p.white_on_node && lab == [100.0, 0.0, 0.0] { ([0.0; 4], 0.0) } else { separate(model, p, target, warm) }; + let cmyk = if p.white_on_node && lab == [100.0, 0.0, 0.0] { [0.0; 4] } else { node(lab, warm) }; warm = Some(cmyk); out.extend(cmyk.map(|v| v as f32)); } @@ -466,6 +712,15 @@ fn check_grids(p: &CmykParams) -> Result<(), CmsError> { if p.white_on_node && p.grid_b2a.is_multiple_of(2) { return Err(invalid_arg(format!("white on a node needs an odd BToA grid, not {}", p.grid_b2a))); } + let valid = |v: &[f64; 2]| v.iter().all(|x| (0.0..=1.0).contains(x)); + if !p.gcr_curve.iter().all(valid) || p.gcr_curve.windows(2).any(|w| w[1][0] <= w[0][0]) { + return Err(invalid_arg(format!("black generation curve {:?} needs points in [0, 1] with increasing gray components", p.gcr_curve))); + } + if let GamutMapping::Oklab { knee, saturation } = p.mapping + && !((0.0..1.0).contains(&knee) && saturation.is_finite() && saturation > 0.0) + { + return Err(invalid_arg(format!("Oklab gamut mapping needs a knee in [0, 1) and a positive saturation, not {knee} and {saturation}"))); + } Ok(()) } @@ -524,11 +779,23 @@ pub fn cmyk_profile_from_model(model: &F, paper: [f64; 3], } fn lut_profile(model: &F, a2b: Clut, paper: [f64; 3], p: &CmykParams) -> Result { - let gbd = Gbd::new(model, p); - let colorimetric = b2a_table(model, p, None)?; - let perceptual = b2a_table(model, p, Some(&gbd))?; + let (perceptual, colorimetric, saturation) = match p.mapping { + GamutMapping::Legacy => { + let gbd = Gbd::new(model, p); + let colorimetric = b2a_table(model, p, None)?; + let perceptual = b2a_table(model, p, Some(&gbd))?; + (perceptual.clone(), colorimetric, perceptual) + } + GamutMapping::Oklab { knee, saturation } => { + let m = OklabMapper::new(model, p, knee, saturation); + let colorimetric = b2a_table_with(p, |lab, warm| m.clip(lab, warm))?; + let perceptual = b2a_table_with(p, |lab, warm| m.perceptual(lab, warm))?; + let saturation = b2a_table_with(p, |lab, warm| m.saturation(lab, warm))?; + (perceptual, colorimetric, saturation) + } + }; let a2b = lut16(a2b, false); - let (b0, b1) = (lut16(perceptual, p.white_on_node), lut16(colorimetric, p.white_on_node)); + let (b0, b1, b2) = (lut16(perceptual, p.white_on_node), lut16(colorimetric, p.white_on_node), lut16(saturation, p.white_on_node)); Ok(Profile { version: (4, 0x30), class: ProfileClass::Output, @@ -544,7 +811,7 @@ fn lut_profile(model: &F, a2b: Clut, paper: [f64; 3], p: &C trc: None, gray_trc: None, a2b: [Some(a2b.clone()), Some(a2b.clone()), Some(a2b)], - b2a: [Some(b0.clone()), Some(b1), Some(b0)], + b2a: [Some(b0), Some(b1), Some(b2)], bytes: None, hash: Default::default(), } @@ -555,3 +822,48 @@ fn lut_profile(model: &F, a2b: Clut, paper: [f64; 3], p: &C pub fn coated_cmyk() -> Result { cmyk_profile(&CmykParams::default()) } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn oklab_mapping_refuses_bad_parameters() { + for (knee, saturation) in [(1.0, 1.0), (-0.1, 1.0), (f64::NAN, 1.0), (0.5, 0.0), (0.5, f64::INFINITY), (0.5, f64::NAN)] { + let p = CmykParams { grid_a2b: 2, grid_b2a: 2, mapping: GamutMapping::Oklab { knee, saturation }, ..CmykParams::default() }; + assert!(cmyk_profile(&p).is_err(), "knee {knee}, saturation {saturation}"); + } + } + + #[test] + fn black_generation_curve() { + let p = CmykParams { gcr_curve: vec![[0.0, 0.0], [0.5, 0.2], [1.0, 0.9]], ..CmykParams::default() }; + for (g, k) in [(-1.0, 0.0), (0.0, 0.0), (0.25, 0.1), (0.5, 0.2), (0.75, 0.55), (1.0, 0.9), (2.0, 0.9)] { + assert!((gcr(&p, g) - k).abs() < 1e-12, "g {g}: {} != {k}", gcr(&p, g)); + } + for curve in [vec![[0.5, 0.2], [0.5, 0.3]], vec![[0.5, 0.2], [0.2, 0.3]], vec![[0.0, 1.5]], vec![[f64::NAN, 0.0]]] { + let p = CmykParams { grid_a2b: 2, grid_b2a: 2, gcr_curve: curve.clone(), ..CmykParams::default() }; + assert!(cmyk_profile(&p).is_err(), "{curve:?}"); + } + } + + #[test] + fn oklab_round_trips() { + let m = CmykModel::coated(CmykParams::default().tvi); + let p = CmykParams::default(); + let mapper = OklabMapper::new(&m, &p, 0.65, 1.05); + for lab in [[50.0, 0.0, 0.0], [44.0, 63.7, 47.0], [31.9, 32.9, -76.8], [90.0, -5.0, 80.0]] { + let back = mapper.lab(mapper.oklab(lab)); + // The published matrices carry 10 digits, so the inverses are exact to about 1e-5 ΔE. + assert!(math::delta_e76(lab, back) < 1e-3, "{lab:?} -> {back:?}"); + } + } + + #[test] + fn oklab_profile_has_three_tables() { + let p = CmykParams { grid_a2b: 5, grid_b2a: 5, mapping: GamutMapping::Oklab { knee: 0.65, saturation: 1.05 }, ..CmykParams::default() }; + let profile = cmyk_profile(&p).unwrap(); + let [Some(b0), Some(b1), Some(b2)] = &profile.b2a else { panic!("missing BToA tables") }; + assert!(b0 != b1 && b0 != b2, "perceptual shares a table"); + } +} diff --git a/crates/cms/src/transform.rs b/crates/cms/src/transform.rs index d1a96e3b5..20df3f791 100644 --- a/crates/cms/src/transform.rs +++ b/crates/cms/src/transform.rs @@ -58,7 +58,7 @@ const OUT_TABLE: usize = GpuMatrixShaper::OUTPUT_ENTRIES; const _: () = assert!(OUT_TABLE.is_power_of_two()); /// ICC v4 perceptual reference medium black (ICC.1:2010 §6.3.4.4), XYZ. -const PERCEPTUAL_BLACK: [f64; 3] = [0.00336, 0.0034731, 0.00287]; +pub(crate) const PERCEPTUAL_BLACK: [f64; 3] = [0.00336, 0.0034731, 0.00287]; /// Accelerated representation of a transform. #[derive(Debug)] diff --git a/crates/cms/tests/fogra39.rs b/crates/cms/tests/fogra39.rs index f3c375656..806bff713 100644 --- a/crates/cms/tests/fogra39.rs +++ b/crates/cms/tests/fogra39.rs @@ -12,8 +12,8 @@ //! ([`synth::cmyk_profile_from_model`]). use craft_cms::math::{self, delta_e2000}; -use craft_cms::synth::{self, CmykParams, Forward}; -use craft_cms::{Builtin, Intent, Transform}; +use craft_cms::synth::{self, CmykParams, Forward, GamutMapping}; +use craft_cms::{Builtin, Intent, Profile, Transform}; const DATA: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/tests/data/FOGRA39.txt"); const PROFILE: &str = concat!(env!("CARGO_MANIFEST_DIR"), "/profiles/craft-coated-fogra39.icc"); @@ -336,8 +336,10 @@ fn regen_coated_fogra39() { description: Builtin::CoatedFogra39.description().into(), copyright: craft_cms::builtin::COATED_FOGRA39_COPYRIGHT.into(), tac: 3.3, + gcr_curve: vec![[0.0, 0.0], [0.2, 0.05], [0.5, 0.205], [0.67, 0.5], [1.0, 0.95]], grid_b2a: 33, white_on_node: true, + mapping: GamutMapping::Oklab { knee: 0.65, saturation: 1.05 }, ..CmykParams::default() }; let profile = synth::cmyk_profile_from_model(&f, paper(&p), ¶ms).unwrap(); @@ -381,3 +383,66 @@ fn stand_in_separations_respect_the_ink_limit() { } } } + +/// sRGB patches and their separations by the reference application (Convert to Profile to +/// Coated FOGRA39, dither on), CMYK % per intent: relative + BPC, relative, perceptual, +/// saturation, absolute. Measured for storytold/photocraft#14267. +const REFERENCE_SEPARATIONS: [([u8; 3], [[f32; 4]; 5]); 3] = [ + ( + [200, 30, 30], + [[14.5, 97.7, 95.3, 4.3], [13.3, 100.0, 100.0, 5.5], [18.0, 96.9, 92.9, 8.6], [14.9, 100.0, 100.0, 5.9], [8.6, 100.0, 100.0, 2.4]], + ), + ([30, 60, 200], [[91.8, 75.3, 0.0, 0.0], [94.5, 76.5, 0.0, 0.0], [94.5, 77.7, 0.0, 0.0], [93.7, 76.9, 0.0, 0.0], [92.6, 74.9, 0.0, 0.0]]), + ( + [128, 128, 128], + [[49.0, 38.4, 38.4, 20.0], [49.8, 39.2, 38.8, 21.2], [49.0, 38.4, 38.4, 20.0], [49.0, 38.4, 38.4, 20.0], [46.7, 36.9, 38.4, 18.4]], + ), +]; + +const SEPARATION_INTENTS: [(Intent, bool); 5] = [ + (Intent::RelativeColorimetric, true), + (Intent::RelativeColorimetric, false), + (Intent::Perceptual, true), + (Intent::Saturation, true), + (Intent::AbsoluteColorimetric, false), +]; + +fn fogra39() -> &'static Profile { + let p = Builtin::CoatedFogra39.profile(); + assert_eq!(p.description, Builtin::CoatedFogra39.description(), "the shipped profile parses"); + p +} + +fn separation(intent: Intent, bpc: bool, rgb: [u8; 3]) -> [f32; 4] { + let t = Transform::new(Builtin::Srgb.profile(), fogra39(), intent, bpc).unwrap(); + let mut o = [0.0f32; 4]; + t.eval(&rgb.map(|v| v as f32 / 255.0), &mut o).unwrap(); + o.map(|v| v * 100.0) +} + +/// sRGB → Coated FOGRA39 matches the reference application's inks on a red, a saturated blue +/// and a mid grey for every intent. Most land within 2 % per ink; red at the magenta–yellow +/// edge lands between table nodes that are and are not clipped, which costs up to 2.2 % with +/// the 33³ BToA tables. +#[test] +fn separates_like_the_reference_application() { + let mut worst = 0.0f32; + for (rgb, want) in REFERENCE_SEPARATIONS { + for ((intent, bpc), want) in SEPARATION_INTENTS.into_iter().zip(want) { + let got = separation(intent, bpc, rgb); + let diff = (0..4).map(|i| (got[i] - want[i]).abs()).fold(0.0f32, f32::max); + eprintln!("{rgb:?} {intent:?} bpc {bpc}: {got:.1?} reference {want:?} (max {diff:.1})"); + worst = worst.max(diff); + } + } + assert!(worst <= 2.5, "worst ink difference {worst} %"); +} + +/// Saturation has its own table: a red separates with more magenta and yellow than +/// perceptual, whose chroma compression takes some back. +#[test] +fn saturation_and_perceptual_separate_differently() { + let red = [200, 30, 30]; + let (perceptual, saturation) = (separation(Intent::Perceptual, true, red), separation(Intent::Saturation, true, red)); + assert!(saturation[1] > perceptual[1] + 1.0 && saturation[2] > perceptual[2] + 1.0, "perceptual {perceptual:?}, saturation {saturation:?}"); +} diff --git a/crates/craft/Cargo.toml b/crates/craft/Cargo.toml index d3593672c..12df7209c 100644 --- a/crates/craft/Cargo.toml +++ b/crates/craft/Cargo.toml @@ -193,6 +193,16 @@ craft-palette = { workspace = true, optional = true } craft-press-print = { workspace = true, optional = true } craft-score = { workspace = true, optional = true } craft-ssip = { workspace = true, optional = true } +craft-cloud = { workspace = true, optional = true } +craft-cloud-local = { workspace = true, optional = true } +craft-cloud-ui = { workspace = true, optional = true } +craft-har = { workspace = true, optional = true } +craft-java-class = { workspace = true, optional = true } +craft-jsonc = { workspace = true, optional = true } +craft-pcap = { workspace = true, optional = true } +craft-sourcemap = { workspace = true, optional = true } +craft-wasm = { workspace = true, optional = true } +craft-xfdf = { workspace = true, optional = true } [features] ui = [ @@ -261,6 +271,7 @@ audio-aac-decode = ["audio", "craft-audio/aac-decode"] audio-aac-encode = ["audio", "craft-audio/aac-encode"] audio-ac3-decode = ["audio", "craft-audio/ac3-decode"] audio-ac3-encode = ["audio", "craft-audio/ac3-encode"] +audio-adpcm = ["audio", "craft-audio/adpcm"] audio-alac-decode = ["audio", "craft-audio/alac-decode"] audio-alac-encode = ["audio", "craft-audio/alac-encode"] audio-decode = ["audio", "craft-audio/decode"] @@ -269,10 +280,16 @@ audio-eac3-encode = ["audio", "craft-audio/eac3-encode"] audio-encode = ["audio", "craft-audio/encode"] audio-flac-decode = ["audio", "craft-audio/flac-decode"] audio-flac-encode = ["audio", "craft-audio/flac-encode"] +audio-g722 = ["audio", "craft-audio/g722"] +audio-g726 = ["audio", "craft-audio/g726"] +audio-gsm = ["audio", "craft-audio/gsm"] +audio-gsm-decode = ["audio", "craft-audio/gsm-decode"] +audio-gsm-encode = ["audio", "craft-audio/gsm-encode"] audio-lossless-encode = ["audio", "craft-audio/lossless-encode"] audio-mp3-decode = ["audio", "craft-audio/mp3-decode"] audio-mp3-encode = ["audio", "craft-audio/mp3-encode"] audio-mpa-decode = ["audio", "craft-audio/mpa-decode"] +audio-mpa-encode = ["audio", "craft-audio/mpa-encode"] audio-opus-decode = ["audio", "craft-audio/opus-decode"] audio-opus-encode = ["audio", "craft-audio/opus-encode"] audio-pcm-encode = ["audio", "craft-audio/pcm-encode"] @@ -281,8 +298,11 @@ audio-qoa = ["audio", "craft-audio/qoa"] audio-qoa-decode = ["audio", "craft-audio/qoa-decode"] audio-qoa-encode = ["audio", "craft-audio/qoa-encode"] audio-rayon = ["audio", "craft-audio/rayon"] +audio-sbc = ["audio", "craft-audio/sbc"] audio-serde = ["audio", "craft-audio/serde"] audio-symphonia = ["audio", "craft-audio/symphonia"] +audio-vmd-decode = ["audio", "craft-audio/vmd-decode"] +audio-vorbis-decode = ["audio", "craft-audio/vorbis-decode"] audio-vorbis-encode = ["audio", "craft-audio/vorbis-encode"] automation = ["dep:craft-automation", "keymap"] @@ -296,11 +316,20 @@ captions = ["dep:craft-captions"] cfb = ["dep:craft-cfb"] +cloud = ["dep:craft-cloud"] + +cloud-local = ["dep:craft-cloud-local"] + +cloud-ui = ["dep:craft-cloud-ui"] +cloud-ui-cloud = ["cloud-ui", "craft-cloud-ui/cloud"] +cloud-ui-share = ["cloud-ui", "craft-cloud-ui/share"] + cms = ["dep:craft-cms"] codepage = ["dep:craft-codepage"] color = ["dep:craft-color"] + color-ui = ["dep:craft-color-ui", "keymap", "settings", "window", "platform"] control = ["dep:craft-control"] @@ -419,11 +448,14 @@ gridcraft-format = ["dep:craft-gridcraft-format"] gzip = ["dep:craft-gzip"] +har = ["dep:craft-har"] + hdr = ["dep:craft-hdr"] heif = ["dep:craft-heif"] heif-decode = ["heif", "craft-heif/decode"] heif-metadata = ["heif", "craft-heif/metadata"] +heif-test-support = ["heif", "craft-heif/test-support"] heif-testdata = ["heif", "craft-heif/testdata"] html = ["dep:craft-html"] @@ -452,11 +484,15 @@ indd = ["dep:craft-indd"] ipc = ["dep:craft-ipc"] +java-class = ["dep:craft-java-class"] + jmap = ["dep:craft-jmap"] jpeg = ["dep:craft-jpeg"] jpeg-parallel = ["jpeg", "craft-jpeg/parallel"] +jsonc = ["dep:craft-jsonc"] + jsonrpc = ["dep:craft-jsonrpc"] jsonrpc-async-lines = ["jsonrpc", "craft-jsonrpc/async-lines"] @@ -501,6 +537,7 @@ media-mpegts = ["media", "craft-media/mpegts"] media-mxf = ["media", "craft-media/mxf"] media-ogg = ["media", "craft-media/ogg"] media-serde = ["media", "craft-media/serde"] +media-vmd = ["media", "craft-media/vmd"] media-source = ["dep:craft-media-source"] @@ -543,6 +580,8 @@ pages = ["dep:craft-pages"] palette = ["dep:craft-palette"] +pcap = ["dep:craft-pcap"] + pcraft-bundle = ["dep:craft-pcraft-bundle"] pcraft-format = ["dep:craft-pcraft-format"] @@ -556,6 +595,7 @@ pdf-interpret = ["pdf", "craft-pdf/interpret"] pdf-paths = ["pdf", "craft-pdf/paths"] pdf-raster = ["pdf", "craft-pdf/raster"] pdf-read = ["pdf", "craft-pdf/read"] +pdf-test-support = ["pdf", "craft-pdf/test-support"] pdf-write = ["pdf", "craft-pdf/write"] pdf-write-pdf = ["pdf", "craft-pdf/write-pdf"] pdf-write-raster = ["pdf", "craft-pdf/write-raster"] @@ -607,9 +647,11 @@ ps-write = ["ps", "craft-ps/write"] psd = ["dep:craft-psd"] psd-corpus = ["psd", "craft-psd/corpus"] psd-serde = ["psd", "craft-psd/serde"] +psd-test-support = ["psd", "craft-psd/test-support"] psd-testgen = ["psd", "craft-psd/testgen"] pst = ["dep:craft-pst"] +pst-test-support = ["pst", "craft-pst/test-support"] pst-test-writer = ["pst", "craft-pst/test-writer"] quit = ["dep:craft-quit"] @@ -665,6 +707,8 @@ smime = ["dep:craft-smime"] sniff = ["dep:craft-sniff"] +sourcemap = ["dep:craft-sourcemap"] + ssip = ["dep:craft-ssip"] stencilcraft-document = ["dep:craft-stencilcraft-document"] @@ -770,7 +814,9 @@ timeline-otio = ["timeline", "craft-timeline/otio"] timeline-xml = ["timeline", "craft-timeline/xml"] ui-app = ["ui", "craft-ui/app"] +ui-cloud = ["ui", "craft-ui/cloud"] ui-color_fonts = ["ui", "craft-ui/color_fonts"] +ui-share = ["ui", "craft-ui/share"] ui-snapshot = ["ui", "craft-ui/snapshot"] ui-system_fonts = ["ui", "craft-ui/system_fonts"] ui-testing = ["ui", "craft-ui/testing"] @@ -799,6 +845,7 @@ video-ffv1 = ["video", "craft-video/ffv1"] video-h264 = ["video", "craft-video/h264"] video-h264-decode = ["video", "craft-video/h264-decode"] video-h264-encode = ["video", "craft-video/h264-encode"] +video-hap = ["video", "craft-video/hap"] video-hevc = ["video", "craft-video/hevc"] video-hevc-decode = ["video", "craft-video/hevc-decode"] video-hevc-encode = ["video", "craft-video/hevc-encode"] @@ -809,7 +856,10 @@ video-mpeg2-encode = ["video", "craft-video/mpeg2-encode"] video-mpeg4 = ["video", "craft-video/mpeg4"] video-mpeg4-encode = ["video", "craft-video/mpeg4-encode"] video-prores = ["video", "craft-video/prores"] +video-screen-video = ["video", "craft-video/screen-video"] video-threads = ["video", "craft-video/threads"] +video-vmd = ["video", "craft-video/vmd"] +video-vmd-decode = ["video", "craft-video/vmd-decode"] video-vp8 = ["video", "craft-video/vp8"] video-vp8-decode = ["video", "craft-video/vp8-decode"] video-vp8-encode = ["video", "craft-video/vp8-encode"] @@ -817,6 +867,8 @@ video-vp9 = ["video", "craft-video/vp9"] video-vp9-decode = ["video", "craft-video/vp9-decode"] video-vp9-encode = ["video", "craft-video/vp9-encode"] +wasm = ["dep:craft-wasm"] + web-api = ["dep:craft-web-api"] web-host = ["dep:craft-web-host"] @@ -833,15 +885,24 @@ wordmodel-test-support = ["wordmodel", "craft-wordmodel/test-support"] xcf = ["dep:craft-xcf"] +xfdf = ["dep:craft-xfdf"] + xfl = ["dep:craft-xfl"] xls = ["dep:craft-xls"] +xls-test-support = ["xls", "craft-xls/test-support"] xlsx = ["dep:craft-xlsx"] +xlsx-test-support = ["xlsx", "craft-xlsx/test-support"] xml = ["dep:craft-xml"] y4m = ["dep:craft-y4m"] zip = ["dep:craft-zip"] +zip-lenient = ["zip", "craft-zip/lenient"] +zip-lenient-bzip2 = ["zip", "craft-zip/lenient-bzip2"] +zip-lenient-lzma = ["zip", "craft-zip/lenient-lzma"] +zip-lenient-zstd = ["zip", "craft-zip/lenient-zstd"] +zip-serde = ["zip", "craft-zip/serde"] zip-test-support = ["zip", "craft-zip/test-support"] diff --git a/crates/craft/src/lib.rs b/crates/craft/src/lib.rs index c71b03463..9d26141e8 100644 --- a/crates/craft/src/lib.rs +++ b/crates/craft/src/lib.rs @@ -35,6 +35,12 @@ pub use craft_browse as browse; pub use craft_captions as captions; #[cfg(feature = "cfb")] pub use craft_cfb as cfb; +#[cfg(feature = "cloud")] +pub use craft_cloud as cloud; +#[cfg(feature = "cloud-local")] +pub use craft_cloud_local as cloud_local; +#[cfg(feature = "cloud-ui")] +pub use craft_cloud_ui as cloud_ui; #[cfg(feature = "cms")] pub use craft_cms as cms; #[cfg(feature = "codepage")] @@ -133,6 +139,8 @@ pub use craft_gif as gif; pub use craft_gridcraft_format as gridcraft_format; #[cfg(feature = "gzip")] pub use craft_gzip as gzip; +#[cfg(feature = "har")] +pub use craft_har as har; #[cfg(feature = "hdr")] pub use craft_hdr as hdr; #[cfg(feature = "heif")] @@ -155,10 +163,14 @@ pub use craft_imaging as imaging; pub use craft_indd as indd; #[cfg(feature = "ipc")] pub use craft_ipc as ipc; +#[cfg(feature = "java-class")] +pub use craft_java_class as java_class; #[cfg(feature = "jmap")] pub use craft_jmap as jmap; #[cfg(feature = "jpeg")] pub use craft_jpeg as jpeg; +#[cfg(feature = "jsonc")] +pub use craft_jsonc as jsonc; #[cfg(feature = "jsonrpc")] pub use craft_jsonrpc as jsonrpc; #[cfg(feature = "jxl")] @@ -221,6 +233,8 @@ pub use craft_ora as ora; pub use craft_pages as pages; #[cfg(feature = "palette")] pub use craft_palette as palette; +#[cfg(feature = "pcap")] +pub use craft_pcap as pcap; #[cfg(feature = "pcraft-bundle")] pub use craft_pcraft_bundle as pcraft_bundle; #[cfg(feature = "pcraft-format")] @@ -291,6 +305,8 @@ pub use craft_sketch as sketch; pub use craft_smime as smime; #[cfg(feature = "sniff")] pub use craft_sniff as sniff; +#[cfg(feature = "sourcemap")] +pub use craft_sourcemap as sourcemap; #[cfg(feature = "ssip")] pub use craft_ssip as ssip; #[cfg(feature = "stencilcraft-document")] @@ -336,6 +352,8 @@ pub use craft_vectorcraft_format as vectorcraft_format; pub use craft_vectordrawable as vectordrawable; #[cfg(feature = "video")] pub use craft_video as video; +#[cfg(feature = "wasm")] +pub use craft_wasm as wasm; #[cfg(feature = "web-api")] pub use craft_web_api as web_api; #[cfg(feature = "web-host")] @@ -348,6 +366,8 @@ pub use craft_window as window; pub use craft_wordmodel as wordmodel; #[cfg(feature = "xcf")] pub use craft_xcf as xcf; +#[cfg(feature = "xfdf")] +pub use craft_xfdf as xfdf; #[cfg(feature = "xfl")] pub use craft_xfl as xfl; #[cfg(feature = "xls")] diff --git a/crates/dds/src/lib.rs b/crates/dds/src/lib.rs index 183ec4fa1..685ce81dd 100644 --- a/crates/dds/src/lib.rs +++ b/crates/dds/src/lib.rs @@ -430,6 +430,7 @@ pub struct Texture<'a> { encoding: Encoding, /// Where the top level's pixel data starts. start: usize, + levels: u32, } impl<'a> Texture<'a> { @@ -456,7 +457,8 @@ impl<'a> Texture<'a> { if width == 0 || height == 0 { return Err(bad("texture dimensions must be nonzero")); } - Ok(Texture { bytes: b, flags, width, height, encoding, start }) + let levels = le32(b, 28)?.max(1).min(mip_levels(width, height)); + Ok(Texture { bytes: b, flags, width, height, encoding, start, levels }) } pub fn width(&self) -> u32 { @@ -472,6 +474,51 @@ impl<'a> Texture<'a> { self.encoding.layout() } + /// Number of declared mip levels, capped by the chain down to one pixel. + pub fn levels(&self) -> u32 { + self.levels + } + + /// The encoding named by the header, including unsigned BC4 and BC5. + pub fn compression(&self) -> DdsCompression { + match self.encoding { + Encoding::Masks { .. } | Encoding::Unorm16 { .. } => DdsCompression::None, + Encoding::Bc1 => DdsCompression::Bc1, + Encoding::Bc2 => DdsCompression::Bc2, + Encoding::Bc3 => DdsCompression::Bc3, + Encoding::Bc4 => DdsCompression::Bc4, + Encoding::Bc5 => DdsCompression::Bc5, + } + } + + /// A borrowed view of one mip level, without allocating or decoding pixels. + /// Lower levels are tightly packed; only the top level uses the header's row pitch. + pub fn mip_level(&self, index: u32) -> Result, DdsError> { + if index >= self.levels { + return Err(bad("mip level index is outside the declared chain")); + } + let (mut width, mut height, mut start) = (self.width, self.height, self.start); + for i in 0..index { + let pitch = if i == 0 && self.flags & DDSD_PITCH != 0 { Some(le32(self.bytes, 20)?) } else { None }; + let (_, size) = self.encoding.level_layout(width, height, pitch)?; + start = start.checked_add(size).ok_or_else(|| bad("mip offset overflow"))?; + if start > self.bytes.len() { + return Err(bad("truncated mip data")); + } + width = (width / 2).max(1); + height = (height / 2).max(1); + } + Ok(Texture { + bytes: self.bytes, + flags: if index == 0 { self.flags } else { self.flags & !DDSD_PITCH }, + width, + height, + encoding: self.encoding, + start, + levels: self.levels - index, + }) + } + /// The top mip level's pixels in [`Texture::layout`], bounded by [`DEFAULT_MAX_DECODE_BYTES`]. pub fn decode(&self) -> Result, DdsError> { self.decode_with_limit(DEFAULT_MAX_DECODE_BYTES) diff --git a/crates/dds/tests/boundary.rs b/crates/dds/tests/boundary.rs index ecd3aac11..3a891f73a 100644 --- a/crates/dds/tests/boundary.rs +++ b/crates/dds/tests/boundary.rs @@ -44,3 +44,53 @@ fn default_budget_rejects_oversized_header_before_payload_or_allocation() { assert!(matches!(texture.decode(), Err(craft_dds::DdsError::LimitExceeded { limit: craft_dds::DEFAULT_MAX_DECODE_BYTES, .. }))); assert!(matches!(texture.decode_with_limit(u64::MAX), Err(craft_dds::DdsError::Malformed(_)))); } + +#[test] +fn mip_views_reuse_shared_decoders_and_keep_their_bounds() { + for (compression, layout, channels) in [ + (DdsCompression::None, Layout::Gray, 1), + (DdsCompression::Bc1, Layout::Rgba, 4), + (DdsCompression::Bc4, Layout::Gray, 1), + (DdsCompression::Bc5, Layout::Rgb, 3), + ] { + let bytes = encode(4, 4, layout, &vec![71; 16 * channels], DdsOptions { compression, mipmaps: true }).unwrap(); + let texture = Texture::parse(&bytes).unwrap(); + assert_eq!(texture.levels(), 3); + assert_eq!(texture.compression(), compression); + assert!(texture.mip_level(3).is_err()); + assert!(texture.mip_level(u32::MAX).is_err()); + for (index, side) in [(0, 4), (1, 2), (2, 1)] { + let level = texture.mip_level(index).unwrap(); + assert_eq!((level.width(), level.height()), (side, side)); + let len = side as usize * side as usize * channels; + assert!(matches!(level.decode_with_limit((len - 1) as u64), Err(craft_dds::DdsError::LimitExceeded { .. }))); + assert_eq!(level.decode_with_limit(len as u64).unwrap().len(), len); + } + let nested = texture.mip_level(1).unwrap().mip_level(1).unwrap(); + assert_eq!(nested.decode().unwrap(), texture.mip_level(2).unwrap().decode().unwrap()); + } +} + +#[test] +fn sixteen_bit_mip_views_preserve_samples_and_stored_offsets() { + for (layout, channels) in [(Layout::Gray, 1), (Layout::GrayA, 2), (Layout::Rgba, 4)] { + let pixels: Vec = (0..16).flat_map(|p| (0..channels).map(move |c| (p * 400 + c * 31 + 7) as u16)).collect(); + let bytes = craft_dds::encode16(4, 4, layout, &pixels, DdsOptions { compression: DdsCompression::None, mipmaps: true }).unwrap(); + let texture = Texture::parse(&bytes).unwrap(); + assert_eq!(texture.compression(), DdsCompression::None); + assert_eq!(texture.levels(), 3); + assert_eq!(texture.decode16().unwrap(), pixels); + for (index, averages) in [(1, vec![1000, 1800, 4200, 5000]), (2, vec![3000])] { + let expected: Vec = averages.iter().flat_map(|p| (0..channels).map(move |c| (p + c * 31 + 7) as u16)).collect(); + let level = texture.mip_level(index).unwrap(); + let budget = (expected.len() * 2) as u64; + assert!(matches!(level.decode16_with_limit(budget - 1), Err(craft_dds::DdsError::LimitExceeded { .. }))); + assert_eq!(level.decode16_with_limit(budget).unwrap(), expected); + let rounded: Vec = expected.iter().map(|&v| ((u32::from(v) + 128) / 257) as u8).collect(); + assert_eq!(level.decode().unwrap(), rounded); + } + assert_eq!(texture.mip_level(1).unwrap().mip_level(1).unwrap().decode16().unwrap(), texture.mip_level(2).unwrap().decode16().unwrap()); + let truncated = Texture::parse(&bytes[..bytes.len() - 1]).unwrap(); + assert!(truncated.mip_level(2).unwrap().decode16().is_err()); + } +} diff --git a/crates/design-lint/Cargo.toml b/crates/design-lint/Cargo.toml index fc8e27bef..ccf1124dd 100644 --- a/crates/design-lint/Cargo.toml +++ b/crates/design-lint/Cargo.toml @@ -10,6 +10,7 @@ repository.workspace = true publish = false [dependencies] +dunce = "1" proc-macro2 = { version = "1", features = ["span-locations"] } quote = "1" serde = { workspace = true } diff --git a/crates/design-lint/src/structure.rs b/crates/design-lint/src/structure.rs index 1e591b23d..1dd5b1da1 100644 --- a/crates/design-lint/src/structure.rs +++ b/crates/design-lint/src/structure.rs @@ -88,7 +88,8 @@ fn unknown_crates(root: &Path, meta: &Metadata, maps: &LayerMaps) -> Vec Vec { // Source paths come from cargo metadata, which resolves `..` and links; the root must be resolved the same way. - let root = &std::fs::canonicalize(root).unwrap_or_else(|_| root.to_owned()); + // `dunce` drops the `\\?\` prefix Windows' canonical paths carry, which metadata's paths lack. + let root = &dunce::canonicalize(root).unwrap_or_else(|_| root.to_owned()); let mut sites = Vec::new(); for tree in index.trees.values() { let mut files: Vec<&PathBuf> = tree.modules.values().map(|m| &m.file).collect(); @@ -96,7 +97,7 @@ fn source_sites(root: &Path, index: &Index) -> Vec { files.dedup(); for file in files { if let Some(parsed) = index.files.get(file) { - sites.extend(scan_parsed(&relative(root, file).to_string_lossy(), &parsed.src, Some(&parsed.file))); + sites.extend(scan_parsed(&relative(root, file).to_string_lossy().replace('\\', "/"), &parsed.src, Some(&parsed.file))); } } } diff --git a/crates/design-lint/tests/contract_rules.rs b/crates/design-lint/tests/contract_rules.rs index 33a6ccff5..90ac096ac 100644 --- a/crates/design-lint/tests/contract_rules.rs +++ b/crates/design-lint/tests/contract_rules.rs @@ -83,7 +83,7 @@ fn type_facts_cross_files_of_a_crate() { let root = Path::new(FIXTURES).join("tree"); let scope = scope().layer("src/chips", 5).crate_tree(&root, "fx", "src/lib.rs").unwrap(); let report = check_with_scope(&Config::new(["src/chips"]), &root, &scope).unwrap(); - let hits: Vec<_> = report.findings.iter().map(|f| (f.path.display().to_string(), f.rule)).collect(); + let hits: Vec<_> = report.findings.iter().map(|f| (f.path.display().to_string().replace('\\', "/"), f.rule)).collect(); assert_eq!( hits, [ diff --git a/crates/docpath/src/links/tests.rs b/crates/docpath/src/links/tests.rs index 9270462f2..9af33f7fc 100644 --- a/crates/docpath/src/links/tests.rs +++ b/crates/docpath/src/links/tests.rs @@ -19,12 +19,15 @@ fn identity_for(bytes: &[u8], secs: u64) -> LinkIdentity { identity_of(&mut Cursor::new(bytes), bytes.len() as u64, Some(stamp(secs))).unwrap() } +/// An absolute path on every platform: Windows needs a drive. +const FILE: &str = if cfg!(windows) { r"C:\m\a.png" } else { "/m/a.png" }; + // Same stamp: Ok without `identity`; new mtime, same fingerprint: Ok; new bytes: Modified; read error: Unreadable. #[test] fn a_touched_file_is_ok_and_a_changed_file_is_modified() { let recorded = identity_for(b"hello world", 10); - let l = link("/m/a.png", Some(recorded)); - let at = |bytes: &[u8], secs: u64| FakeLinkFiles::new().with("/m/a.png", bytes, secs); + let l = link(FILE, Some(recorded)); + let at = |bytes: &[u8], secs: u64| FakeLinkFiles::new().with(FILE, bytes, secs); let same = at(b"hello world", 10); assert_eq!(status(&l, None, &same), LinkStatus::Ok); @@ -32,10 +35,10 @@ fn a_touched_file_is_ok_and_a_changed_file_is_modified() { assert_eq!(status(&l, None, &at(b"hello world", 99)), LinkStatus::Ok); assert_eq!(status(&l, None, &at(b"hello w0rld", 99)), LinkStatus::Modified); assert_eq!(status(&l, None, &at(b"hello", 99)), LinkStatus::Modified); - let locked = at(b"hello world", 99).unreadable("/m/a.png"); + let locked = at(b"hello world", 99).unreadable(FILE); assert_eq!(status(&l, None, &locked), LinkStatus::Unreadable); assert_eq!(status(&l, None, &FakeLinkFiles::new()), LinkStatus::Missing); - assert_eq!(status(&link("/m/a.png", None), None, &at(b"x", 1)), LinkStatus::Ok); + assert_eq!(status(&link(FILE, None), None, &at(b"x", 1)), LinkStatus::Ok); let embedded = Link { embedded: true, ..l }; assert_eq!(status(&embedded, None, &FakeLinkFiles::new()), LinkStatus::Embedded); } diff --git a/crates/draw/tests/it/corner.rs b/crates/draw/tests/it/corner.rs index 123b6bf0e..b014cb1a4 100644 --- a/crates/draw/tests/it/corner.rs +++ b/crates/draw/tests/it/corner.rs @@ -82,8 +82,7 @@ fn apex_radius_after_drag(down: f32) -> f64 { fixture.settle(); let widget = fixture.by_label("Corner 1 of 3").expect("the apex has a widget"); fixture.drag(&widget, vec2(0.0, down)); - let radius = host.borrow()[0].corners[0].radius; - radius + host.borrow()[0].corners[0].radius } /// The apex of a triangle is a corner like any other: pulling its widget inward rounds it, and the further the diff --git a/crates/drawingml/src/table/styles.rs b/crates/drawingml/src/table/styles.rs index cae3e0dd8..9be968088 100644 --- a/crates/drawingml/src/table/styles.rs +++ b/crates/drawingml/src/table/styles.rs @@ -211,6 +211,26 @@ fn style_def(w: &mut Writer, id: &str, name: &str) { /// opened file defined (`defs`), written back as they were read. A generated style is named /// `"{name_prefix} {label}"` (`"Acme Medium 2 Accent 1"`). pub fn table_styles_xml(used: &[String], defs: &[crate::table::TableStyleDef], name_prefix: &str) -> Vec { + table_styles_xml_with(used, defs.iter().map(|d| (d.id.as_str(), d.raw.as_str())), name_prefix, |raw| { + crate::xmlx::parse(raw.as_bytes()).is_ok_and(|x| x.is(Local("tblStyle"))) + }) +} + +/// Write table style definitions without copying a caller's model or raw XML. +/// +/// `defs` yields `(id, raw_xml)` in file order and must replay the same sequence when cloned. +/// `valid` retains the caller's bounded XML-admission policy; accepted fragments are emitted +/// verbatim. It must reject fragments the caller cannot safely preserve. The ordinary +/// [`table_styles_xml`] API continues to use this crate's bounded parser. +/// +/// Input/output budgets remain caller-owned. Duplicate selection, case handling, and validation +/// order match [`table_styles_xml`]; invalid first definitions do not fall through to later ones. +pub fn table_styles_xml_with<'a>( + used: &[String], + defs: impl Iterator + Clone, + name_prefix: &str, + mut valid: impl FnMut(&str) -> bool, +) -> Vec { let mut w = Writer::document(); w.tag("a:tblStyleLst").attr("xmlns:a", NS_A).attr("def", "{5C22544A-7EE6-4342-B048-85BDC9FD1C3A}").open(); let names = crate::table::table_styles(); @@ -218,19 +238,19 @@ pub fn table_styles_xml(used: &[String], defs: &[crate::table::TableStyleDef], n // definitions by lower-case id (the first wins). let mut done: std::collections::HashSet<&str> = std::collections::HashSet::new(); let mut done_lower: std::collections::HashSet = std::collections::HashSet::new(); - let mut def_of: std::collections::HashMap = std::collections::HashMap::new(); - for d in defs { - def_of.entry(d.id.to_ascii_lowercase()).or_insert(d); + let mut def_of: std::collections::HashMap = std::collections::HashMap::new(); + for (id, raw) in defs.clone() { + def_of.entry(id.to_ascii_lowercase()).or_insert(raw); } for s in used { if !done.insert(s.as_str()) { continue; } done_lower.insert(s.to_ascii_lowercase()); - if let Some(d) = def_of.get(&s.to_ascii_lowercase()) - && crate::xmlx::parse(d.raw.as_bytes()).is_ok_and(|x| x.is(Local("tblStyle"))) + if let Some(raw) = def_of.get(&s.to_ascii_lowercase()) + && valid(raw) { - w.raw(&d.raw); + w.raw(raw); continue; } let (_, define) = guid_for_style(s); @@ -241,13 +261,13 @@ pub fn table_styles_xml(used: &[String], defs: &[crate::table::TableStyleDef], n style_def(&mut w, s, &name); } // Styles the file defined but no table uses still belong to the deck. - for d in defs { - if done_lower.contains(&d.id.to_ascii_lowercase()) { + for (id, raw) in defs { + if done_lower.contains(&id.to_ascii_lowercase()) { continue; } - if crate::xmlx::parse(d.raw.as_bytes()).is_ok_and(|x| x.is(Local("tblStyle"))) { - done_lower.insert(d.id.to_ascii_lowercase()); - w.raw(&d.raw); + if valid(raw) { + done_lower.insert(id.to_ascii_lowercase()); + w.raw(raw); } } w.close(); @@ -258,6 +278,27 @@ pub fn table_styles_xml(used: &[String], defs: &[crate::table::TableStyleDef], n mod tests { use super::*; + #[test] + fn borrowed_writer_preserves_model_api_and_validation_order() { + let defs = [ + crate::table::TableStyleDef { id: "custom".into(), raw: "".into(), ..Default::default() }, + crate::table::TableStyleDef { id: "CUSTOM".into(), raw: "".into(), ..Default::default() }, + ]; + let used = vec!["custom".into(), "custom".into(), "light1-accent1".into()]; + let borrowed = || defs.iter().map(|d| (d.id.as_str(), d.raw.as_str())); + assert_eq!( + table_styles_xml(&used, &defs, "App"), + table_styles_xml_with(&used, borrowed(), "App", |raw| { crate::xmlx::parse(raw.as_bytes()).is_ok_and(|x| x.is(Local("tblStyle"))) }) + ); + let mut checked = Vec::new(); + let bytes = table_styles_xml_with(&used, borrowed(), "App", |raw| { + checked.push(raw.to_owned()); + false + }); + assert_eq!(checked, [""]); + assert!(!String::from_utf8(bytes).unwrap().contains("duplicate=")); + } + #[test] fn style_parts_follow_schema_order() { const ORDER: [&str; 14] = [ diff --git a/crates/har/Cargo.toml b/crates/har/Cargo.toml new file mode 100644 index 000000000..c9a1b9f0b --- /dev/null +++ b/crates/har/Cargo.toml @@ -0,0 +1,13 @@ +[package] +name = "craft-har" +description = "Typed HTTP Archive capture reader with explicit input admission" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true +[lints] +workspace = true +[dependencies] +serde_json = { workspace = true } +thiserror = { workspace = true } diff --git a/crates/har/src/lib.rs b/crates/har/src/lib.rs new file mode 100644 index 000000000..8f8fba2cb --- /dev/null +++ b/crates/har/src/lib.rs @@ -0,0 +1,230 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +#![forbid(unsafe_code)] + +//! HTTP Archive (HAR 1.2) captures, read into typed records. No redaction happens here; callers +//! decide what to keep. Capture headers and bodies can contain secrets: redact before display or sharing. +//! `parse` preserves compatibility and parses the whole JSON before limiting returned entries. +//! Use `parse_bounded` to cap admitted bytes; this is not a precise allocator or output-byte limit. + +use serde_json::Value; + +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum HarError { + #[error("not valid JSON: {0}")] + BadJson(String), + #[error("not a HAR capture: {0}")] + NotHar(&'static str), +} + +#[derive(Debug, Clone, Default, PartialEq)] +pub struct Har { + pub version: Option, + pub creator: Option, + pub pages: usize, + pub entries: Vec, + pub declared_entries: usize, + pub truncated: bool, +} + +#[derive(Debug, Clone, Default, PartialEq)] +pub struct HarEntry { + /// 0-based position in `log.entries`. + pub ordinal: usize, + pub started: Option, + pub time_ms: Option, + pub resource_type: Option, + pub server_ip: Option, + pub request: HarRequest, + pub response: HarResponse, + /// blocked, dns, connect, send, wait, receive, ssl (negative values mean "not applicable"). + pub timings: Vec<(String, f64)>, +} + +#[derive(Debug, Clone, Default, PartialEq)] +pub struct HarRequest { + pub method: String, + pub url: String, + pub http_version: Option, + pub headers: Vec<(String, String)>, + pub cookie_names: Vec, + pub post: Option, + pub body_size: Option, +} + +#[derive(Debug, Clone, Default, PartialEq)] +pub struct HarBody { + pub mime: Option, + pub text: Option, + /// Form parameter names (values are deliberately not surfaced by this type's users). + pub params: Vec<(String, Option)>, +} + +#[derive(Debug, Clone, Default, PartialEq)] +pub struct HarResponse { + pub status: i64, + pub status_text: Option, + pub http_version: Option, + pub headers: Vec<(String, String)>, + pub cookie_names: Vec, + pub redirect_url: Option, + pub content_size: Option, + pub mime: Option, + pub text: Option, + /// `base64` when `text` is base64-encoded. + pub encoding: Option, + pub body_size: Option, +} + +fn s(v: &Value, k: &str) -> Option { + v.get(k).and_then(Value::as_str).map(String::from) +} + +fn pairs(v: Option<&Value>) -> Vec<(String, String)> { + v.and_then(Value::as_array) + .map(|a| { + a.iter() + .filter_map(|h| Some((h.get("name")?.as_str()?.to_string(), h.get("value").and_then(Value::as_str).unwrap_or_default().to_string()))) + .collect() + }) + .unwrap_or_default() +} + +fn names(v: Option<&Value>) -> Vec { + v.and_then(Value::as_array).map(|a| a.iter().filter_map(|c| c.get("name")?.as_str().map(String::from)).collect()).unwrap_or_default() +} + +/// Parse a HAR document, keeping at most `max_entries` entries. +pub fn parse(json: &[u8], max_entries: usize) -> Result { + let json = json.strip_prefix(&[0xef, 0xbb, 0xbf]).unwrap_or(json); + let v: Value = serde_json::from_slice(json).map_err(|e| HarError::BadJson(e.to_string()))?; + let log = v.get("log").ok_or(HarError::NotHar("no \"log\" object"))?; + let entries = log.get("entries").and_then(Value::as_array).ok_or(HarError::NotHar("no \"log.entries\" array"))?; + let mut har = Har { + version: s(log, "version"), + creator: log + .get("creator") + .map(|c| format!("{} {}", s(c, "name").unwrap_or_default(), s(c, "version").unwrap_or_default()).trim().to_string()), + pages: log.get("pages").and_then(Value::as_array).map_or(0, Vec::len), + declared_entries: entries.len(), + ..Default::default() + }; + for (i, e) in entries.iter().enumerate() { + if har.entries.len() >= max_entries { + har.truncated = true; + break; + } + let req = e.get("request").unwrap_or(&Value::Null); + let res = e.get("response").unwrap_or(&Value::Null); + let content = res.get("content").unwrap_or(&Value::Null); + let post = req.get("postData").filter(|p| p.is_object()).map(|p| HarBody { + mime: s(p, "mimeType"), + text: s(p, "text"), + params: p + .get("params") + .and_then(Value::as_array) + .map(|a| a.iter().filter_map(|x| Some((x.get("name")?.as_str()?.to_string(), s(x, "value")))).collect()) + .unwrap_or_default(), + }); + let timings = e + .get("timings") + .and_then(Value::as_object) + .map(|m| m.iter().filter_map(|(k, v)| Some((k.clone(), v.as_f64()?))).collect()) + .unwrap_or_default(); + har.entries.push(HarEntry { + ordinal: i, + started: s(e, "startedDateTime"), + time_ms: e.get("time").and_then(Value::as_f64), + resource_type: s(e, "_resourceType"), + server_ip: s(e, "serverIPAddress"), + request: HarRequest { + method: s(req, "method").unwrap_or_default(), + url: s(req, "url").unwrap_or_default(), + http_version: s(req, "httpVersion"), + headers: pairs(req.get("headers")), + cookie_names: names(req.get("cookies")), + post, + body_size: req.get("bodySize").and_then(Value::as_i64), + }, + response: HarResponse { + status: res.get("status").and_then(Value::as_i64).unwrap_or(0), + status_text: s(res, "statusText"), + http_version: s(res, "httpVersion"), + headers: pairs(res.get("headers")), + cookie_names: names(res.get("cookies")), + redirect_url: s(res, "redirectURL").filter(|u| !u.is_empty()), + content_size: content.get("size").and_then(Value::as_i64), + mime: s(content, "mimeType"), + text: s(content, "text"), + encoding: s(content, "encoding"), + body_size: res.get("bodySize").and_then(Value::as_i64), + }, + timings, + }); + } + Ok(har) +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn reads_a_har_with_a_utf8_bom() { + let capture = br#"{"log":{"entries":[]}}"#; + let mut encoded = vec![0xef, 0xbb, 0xbf]; + encoded.extend_from_slice(capture); + assert_eq!(parse(&encoded, 1).unwrap(), parse(capture, 1).unwrap()); + assert!(parse(&[0xef, 0xbb], 1).is_err()); + } + + #[test] + fn parses_minimal_har() { + let j = br#"{"log":{"version":"1.2","creator":{"name":"x","version":"1"},"entries":[ + {"startedDateTime":"2026-01-01T00:00:00Z","time":12.5, + "request":{"method":"POST","url":"https://api.example.test/v1/items/42","headers":[{"name":"Cookie","value":"s=1"}],"cookies":[{"name":"s","value":"1"}], + "postData":{"mimeType":"application/json","text":"{\"a\":1}"}}, + "response":{"status":201,"headers":[],"content":{"size":2,"mimeType":"application/json","text":"{}"}}, + "timings":{"wait":10,"receive":2.5}}]}}"#; + let h = parse(j, 10).unwrap(); + assert_eq!(h.entries.len(), 1); + let e = &h.entries[0]; + assert_eq!(e.request.method, "POST"); + assert_eq!(e.response.status, 201); + assert_eq!(e.request.cookie_names, vec!["s"]); + assert_eq!(e.timings.len(), 2); + } + + #[test] + fn rejects_non_har() { + assert!(parse(b"{}", 1).is_err()); + assert!(parse(b"nope", 1).is_err()); + assert!(parse(br#"{"log":{"entries":[1,null,"x"]}}"#, 10).is_ok()); + } +} + +/// Reject oversized input before parsing its JSON. `max_entries` only limits returned records. +pub fn parse_bounded(json: &[u8], max_entries: usize, max_bytes: usize) -> Result { + if json.len() > max_bytes { + return Err(HarError::NotHar("input byte limit exceeded")); + } + parse(json, max_entries) +} + +#[cfg(test)] +mod admission_tests { + use super::*; + #[test] + fn input_admission_and_entry_limits_are_independent() { + let input = br#"{"log":{"entries":[null,{}]}}"#; + assert_eq!(parse_bounded(input, 2, input.len()).unwrap(), parse(input, 2).unwrap()); + assert_eq!(parse_bounded(b"bad JSON", 1, 0), Err(HarError::NotHar("input byte limit exceeded"))); + let empty = parse_bounded(input, 0, input.len()).unwrap(); + assert!(empty.truncated && empty.entries.is_empty()); + assert_eq!(empty.declared_entries, 2); + let one = parse_bounded(input, 1, input.len()).unwrap(); + assert!(one.truncated); + assert_eq!(one.entries.len(), 1); + assert_eq!(one.entries[0].ordinal, 0); + assert!(!parse_bounded(input, 2, input.len()).unwrap().truncated); + } +} diff --git a/crates/image-codecs/src/bmp_probe.rs b/crates/image-codecs/src/bmp_probe.rs index 5b47721bc..89f6a3b97 100644 --- a/crates/image-codecs/src/bmp_probe.rs +++ b/crates/image-codecs/src/bmp_probe.rs @@ -1,5 +1,7 @@ //! Header-only BMP dimensions and pixel-data coverage, without allocating a canvas. +use crate::error::CodecError; + /// Recognize a BMP file header with a supported DIB header kind. /// /// This is a format-routing check, not full validation: dimensions and pixel data may still @@ -13,6 +15,115 @@ pub fn is_supported_header(b: &[u8]) -> bool { false } +/// Wrap a DIB (a BMP without its 14-byte `BITMAPFILEHEADER`, as the Windows clipboard holds one +/// for `CF_DIB` and `CF_DIBV5`) as a BMP file the decoders here read. The pixel offset is computed +/// from the header with saturating arithmetic, so a hostile header cannot overflow; whether the +/// pixel data exists is left to the decoder. Apply [`dib_layout`] first for clipboard DIBs. +/// +/// # Errors +/// +/// Returns [`CodecError::LimitExceeded`] when the output (`dib.len() + 14` bytes) cannot be allocated. +pub fn dib_to_bmp(dib: &[u8]) -> Result, CodecError> { + let u16_at = |at: usize| dib.get(at..at + 2).and_then(|b| b.try_into().ok()).map(u16::from_le_bytes); + let u32_at = |at: usize| dib.get(at..at + 4).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes); + let bi_size = u32_at(0).unwrap_or(40); + let offset = if bi_size == 12 { + let bpp = u16_at(10).unwrap_or(24); + let palette = if bpp <= 8 { (1u32 << bpp) * 3 } else { 0 }; + 14 + bi_size + palette + } else { + let bpp = u16_at(14).unwrap_or(24); + let compression = u32_at(16).unwrap_or(0); + let clr_used = u32_at(32).unwrap_or(0); + let palette_entries = if clr_used != 0 { + clr_used + } else if bpp <= 8 { + 1u32 << bpp + } else { + 0 + }; + // The masks of a 52- or 56-byte (V2/V3) header are inside the header; only the other + // header kinds carry them as 12 further bytes before the pixels. + let masks = if compression == 3 && bi_size >= 40 && !matches!(bi_size, 52 | 56) { 12 } else { 0 }; + 14u32.saturating_add(bi_size).saturating_add(masks).saturating_add(palette_entries.saturating_mul(4)) + }; + let total = dib.len().saturating_add(14); + let file_size = u32::try_from(total).unwrap_or(u32::MAX); + let mut bmp = Vec::new(); + bmp.try_reserve_exact(total).map_err(|_| CodecError::LimitExceeded(format!("a {total}-byte BMP")))?; + bmp.extend_from_slice(b"BM"); + bmp.extend_from_slice(&file_size.to_le_bytes()); + bmp.extend_from_slice(&[0u8; 4]); + bmp.extend_from_slice(&offset.to_le_bytes()); + bmp.extend_from_slice(dib); + Ok(bmp) +} + +/// Put a clipboard DIB with a V4 or V5 header (108 bytes or more) in the layout the decoder reads. +/// A 32-bit one whose alpha mask is set but whose compression says `BI_RGB` is marked +/// `BI_BITFIELDS` (with the usual colour masks when it gives none), so its alpha is kept as +/// Windows programs mean it; arboard makes the same change. Bit fields then need the colour masks +/// after the header too, where Windows puts a copy and the decoder skips them; a DIB without that +/// copy gets it. Any other DIB comes back unchanged, as does one whose 12 extra bytes cannot be +/// allocated. +pub fn dib_layout(mut dib: Vec) -> Vec { + let u32_at = |d: &[u8], at: usize| d.get(at..at + 4).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes); + let Some(size) = u32_at(&dib, 0).filter(|&s| s >= 108).and_then(|s| usize::try_from(s).ok()) else { return dib }; + let put = |d: &mut Vec, at: usize, v: u32| { + if let Some(b) = d.get_mut(at..at + 4) { + b.copy_from_slice(&v.to_le_bytes()); + } + }; + // Decide everything first and mutate only after the 12-byte reservation succeeded, so a failed + // allocation returns the DIB unchanged. + let promote = dib.get(14..16) == Some(&[32, 0]) && u32_at(&dib, 16) == Some(0) && u32_at(&dib, 52) == Some(0xFF00_0000); + let default_masks = promote && (40..52).step_by(4).all(|at| u32_at(&dib, at) == Some(0)); + let mut masks = dib.get(40..52).and_then(|b| <[u8; 12]>::try_from(b).ok()); + if default_masks { + let mut m = [0u8; 12]; + m[0..4].copy_from_slice(&0x00FF_0000u32.to_le_bytes()); + m[4..8].copy_from_slice(&0x0000_FF00u32.to_le_bytes()); + m[8..12].copy_from_slice(&0x0000_00FFu32.to_le_bytes()); + masks = Some(m); + } + let bitfields = promote || u32_at(&dib, 16) == Some(3); + // Bytes equal to the masks right after the header are a copy only when more bytes follow than + // the pixels need; otherwise they are the pixels (e.g. a 3x1 V5 DIB with pixels equal to the masks). + let has_copy = |m: &[u8; 12]| { + dib.get(size..size.saturating_add(12)) == Some(m.as_slice()) && pixel_bytes(&dib).is_none_or(|need| dib.len().saturating_sub(size) > need) + }; + let insert = match masks { + Some(m) if bitfields && size <= dib.len() && !has_copy(&m) => Some(m), + _ => None, + }; + if insert.is_some() && dib.try_reserve(12).is_err() { + return dib; + } + if promote { + put(&mut dib, 16, 3); + if default_masks { + put(&mut dib, 40, 0x00FF_0000); + put(&mut dib, 44, 0x0000_FF00); + put(&mut dib, 48, 0x0000_00FF); + } + } + if let Some(m) = insert { + dib.splice(size..size, m); + } + dib +} + +/// Bytes of pixel rows (4-byte aligned stride) the info-header dimensions of `dib` call for, or +/// `None` when width, height or bit count cannot be read. +fn pixel_bytes(dib: &[u8]) -> Option { + let i32_at = |at: usize| dib.get(at..at + 4).and_then(|b| b.try_into().ok()).map(i32::from_le_bytes); + let w = u64::try_from(i32_at(4)?).ok()?; + let h = u64::from(i32_at(8)?.unsigned_abs()); + let bpp = u64::from(u16::from_le_bytes(dib.get(14..16)?.try_into().ok()?)); + let stride = w.checked_mul(bpp)?.div_ceil(32).checked_mul(4)?; + usize::try_from(stride.checked_mul(h)?).ok() +} + /// Coverage of the declared pixel array. Row byte counts include row padding; RLE coverage /// counts the pixels drawn by commands and may be smaller than the canvas. #[derive(Clone, Copy, Debug, PartialEq, Eq)] @@ -174,4 +285,335 @@ mod tests { b[0] = b'X'; assert!(!is_supported_header(&b)); } + + // The WordCraft originals, kept verbatim as the oracle. + fn oracle_dib_to_bmp(dib: &[u8]) -> Vec { + let u16_at = |at: usize| dib.get(at..at + 2).and_then(|b| b.try_into().ok()).map(u16::from_le_bytes); + let u32_at = |at: usize| dib.get(at..at + 4).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes); + let bi_size = u32_at(0).unwrap_or(40); + let offset = if bi_size == 12 { + let bpp = u16_at(10).unwrap_or(24); + let palette = if bpp <= 8 { (1u32 << bpp) * 3 } else { 0 }; + 14 + bi_size + palette + } else { + let bpp = u16_at(14).unwrap_or(24); + let compression = u32_at(16).unwrap_or(0); + let clr_used = u32_at(32).unwrap_or(0); + let palette_entries = if clr_used != 0 { + clr_used + } else if bpp <= 8 { + 1u32 << bpp + } else { + 0 + }; + let masks = if compression == 3 && bi_size >= 40 { 12 } else { 0 }; + 14u32.saturating_add(bi_size).saturating_add(masks).saturating_add(palette_entries.saturating_mul(4)) + }; + let file_size = u32::try_from(14 + dib.len()).unwrap_or(u32::MAX); + let mut bmp = Vec::with_capacity(14 + dib.len()); + bmp.extend_from_slice(b"BM"); + bmp.extend_from_slice(&file_size.to_le_bytes()); + bmp.extend_from_slice(&[0u8; 4]); + bmp.extend_from_slice(&offset.to_le_bytes()); + bmp.extend_from_slice(dib); + bmp + } + + fn oracle_dib_layout(mut dib: Vec) -> Vec { + let u32_at = |d: &[u8], at: usize| d.get(at..at + 4).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes); + let Some(size) = u32_at(&dib, 0).filter(|&s| s >= 108).and_then(|s| usize::try_from(s).ok()) else { return dib }; + let put = |d: &mut Vec, at: usize, v: u32| { + if let Some(b) = d.get_mut(at..at + 4) { + b.copy_from_slice(&v.to_le_bytes()); + } + }; + if dib.get(14..16) == Some(&[32, 0]) && u32_at(&dib, 16) == Some(0) && u32_at(&dib, 52) == Some(0xFF00_0000) { + put(&mut dib, 16, 3); + if (40..52).step_by(4).all(|at| u32_at(&dib, at) == Some(0)) { + put(&mut dib, 40, 0x00FF_0000); + put(&mut dib, 44, 0x0000_FF00); + put(&mut dib, 48, 0x0000_00FF); + } + } + if u32_at(&dib, 16) == Some(3) + && size <= dib.len() + && let Some(masks) = dib.get(40..52).map(<[u8]>::to_vec) + && dib.get(size..size + 12) != Some(masks.as_slice()) + { + dib.splice(size..size, masks); + } + dib + } + + fn core(bpp: u16) -> Vec { + let mut d = Vec::new(); + d.extend_from_slice(&12u32.to_le_bytes()); + d.extend_from_slice(&2u16.to_le_bytes()); + d.extend_from_slice(&2u16.to_le_bytes()); + d.extend_from_slice(&1u16.to_le_bytes()); + d.extend_from_slice(&bpp.to_le_bytes()); + d.resize(12 + 64, 7); + d + } + + #[allow(clippy::too_many_arguments)] + fn info(size: u32, bpp: u16, comp: u32, clr_used: u32, masks: [u32; 4], tail: usize) -> Vec { + let mut d = vec![0u8; size.clamp(40, 124) as usize]; + d[0..4].copy_from_slice(&size.to_le_bytes()); + d[4..8].copy_from_slice(&2i32.to_le_bytes()); + d[8..12].copy_from_slice(&2i32.to_le_bytes()); + d[12..14].copy_from_slice(&1u16.to_le_bytes()); + d[14..16].copy_from_slice(&bpp.to_le_bytes()); + d[16..20].copy_from_slice(&comp.to_le_bytes()); + d[32..36].copy_from_slice(&clr_used.to_le_bytes()); + for (i, m) in masks.iter().enumerate() { + if let Some(b) = d.get_mut(40 + 4 * i..44 + 4 * i) { + b.copy_from_slice(&m.to_le_bytes()); + } + } + d.extend((0..tail).map(|i| (i * 31 + 5) as u8)); + d + } + + fn corpus() -> Vec> { + let mut v = Vec::new(); + for bpp in [1, 4, 8, 24, 0, 99] { + v.push(core(bpp)); + } + for bpp in [1u16, 4, 8, 16, 24, 32, 0, 255] { + for clr in [0u32, 1, 5, 256, u32::MAX] { + v.push(info(40, bpp, 0, clr, [0; 4], 40)); + } + } + for (size, comp, masks) in [ + (40, 3, [0xFF0000, 0xFF00, 0xFF, 0]), + (40, 3, [0; 4]), + (52, 3, [0xFF0000, 0xFF00, 0xFF, 0]), + (108, 3, [0xFF0000, 0xFF00, 0xFF, 0xFF00_0000]), + (108, 0, [0xFF0000, 0xFF00, 0xFF, 0xFF00_0000]), + (108, 0, [0, 0, 0, 0xFF00_0000]), + (108, 0, [0; 4]), + (124, 3, [0xFF0000, 0xFF00, 0xFF, 0xFF00_0000]), + (124, 0, [0, 0, 0, 0xFF00_0000]), + (124, 0, [1, 0, 0, 0xFF00_0000]), + (124, 0, [0xFF0000, 0xFF00, 0xFF, 0]), + (124, 1, [0, 0, 0, 0xFF00_0000]), + (124, 3, [1, 2, 3, 4]), + (0, 0, [0; 4]), + (12, 0, [0; 4]), + (u32::MAX, 3, [0; 4]), + (u32::MAX, 0, [0; 4]), + (200, 3, [9; 4]), + ] { + for bpp in [8u16, 16, 32] { + for clr in [0u32, 2, u32::MAX] { + v.push(info(size, bpp, comp, clr, masks, 48)); + } + } + } + // 52/56-byte bitfields headers with and without a pixel tail, and 3x1 V5 DIBs. + for size in [52, 56] { + v.push(info(size, 32, 3, 0, [0xFF0000, 0xFF00, 0xFF, 0xFF00_0000], 4)); + v.push(info(size, 32, 3, 0, [0xFF0000, 0xFF00, 0xFF, 0xFF00_0000], 0)); + } + v.push(v5_3x1(false)); + v.push(v5_3x1(true)); + v + } + + /// 3x1 32-bit V5 BI_BITFIELDS whose three pixels equal the colour masks; with `copy` the DIB + /// also holds the real 12-byte mask copy before the pixels. + fn v5_3x1(copy: bool) -> Vec { + let masks = [0x00FF_0000u32, 0x0000_FF00, 0x0000_00FF]; + let mut d = info(124, 32, 3, 0, [masks[0], masks[1], masks[2], 0xFF00_0000], 0); + d[4..8].copy_from_slice(&3i32.to_le_bytes()); + d[8..12].copy_from_slice(&1i32.to_le_bytes()); + for _ in 0..usize::from(copy) + 1 { + for m in masks { + d.extend_from_slice(&m.to_le_bytes()); + } + } + d + } + + fn dib_u32(d: &[u8], at: usize) -> Option { + d.get(at..at + 4).and_then(|b| b.try_into().ok()).map(u32::from_le_bytes) + } + + /// Fixed case 1: a 52- or 56-byte BI_BITFIELDS header holds its masks itself, so `dib_to_bmp` + /// no longer adds the 12 appended-mask bytes the WordCraft original added to the pixel offset. + fn bmp_offset_fixed(dib: &[u8]) -> bool { + matches!(dib_u32(dib, 0).unwrap_or(40), 52 | 56) && dib_u32(dib, 16) == Some(3) + } + + /// Fixed case 2: the original read 12 pixel bytes equal to the masks (exact-length payload) as a + /// mask copy and inserted nothing. Returns the corrected output when `cut` is such a case. + fn exact_length_fixed(cut: &[u8]) -> Option> { + let o = oracle_dib_layout(cut.to_vec()); + let size = usize::try_from(dib_u32(&o, 0).filter(|&s| s >= 108)?).ok()?; + let need = pixel_bytes(&o)?; + let same = o.len() == cut.len() + && dib_u32(&o, 16) == Some(3) + && size <= o.len() + && o.get(size..size + 12).is_some() + && o.get(size..size + 12) == o.get(40..52) + && o.len() - size <= need; + if !same { + return None; + } + let mut want = o.clone(); + want.splice(size..size, o[40..52].to_vec()); + Some(want) + } + + #[test] + fn dib_helpers_match_the_wordcraft_originals_byte_for_byte() { + let (mut total, mut offset_cases, mut exact_cases) = (0usize, 0usize, 0usize); + for dib in corpus() { + for n in 0..=dib.len() { + let cut = &dib[..n]; + total += 1; + let fixed_layout = exact_length_fixed(cut); + match &fixed_layout { + Some(want) => { + exact_cases += 1; + assert_eq!(&dib_layout(cut.to_vec()), want, "exact-length layout len {n}"); + } + None => assert_eq!(dib_layout(cut.to_vec()), oracle_dib_layout(cut.to_vec()), "layout len {n}"), + } + if bmp_offset_fixed(cut) { + offset_cases += 1; + let (new, old) = (dib_to_bmp(cut).unwrap(), oracle_dib_to_bmp(cut)); + assert_eq!(new[..10], old[..10]); + assert_eq!(new[14..], old[14..]); + let (a, b) = (dib_u32(&new, 10).unwrap(), dib_u32(&old, 10).unwrap()); + assert_eq!(a.saturating_add(12), b, "offset len {n}"); + } else { + assert_eq!(dib_to_bmp(cut).unwrap(), oracle_dib_to_bmp(cut), "bmp len {n}"); + } + let both = dib_layout(cut.to_vec()); + let old_both = oracle_dib_layout(cut.to_vec()); + if fixed_layout.is_none() && !bmp_offset_fixed(&both) { + assert_eq!(dib_to_bmp(&both).unwrap(), oracle_dib_to_bmp(&old_both)); + } + } + } + eprintln!("corpus cases {total}: 52/56-byte bitfields offset {offset_cases}, exact-length payload {exact_cases}"); + assert!(offset_cases > 0 && exact_cases > 0); + } + + #[test] + fn dib_helpers_survive_pseudo_random_bytes() { + let mut x = 0x9E37_79B9_7F4A_7C15u64; + for len in 0..300usize { + let d: Vec = (0..len) + .map(|_| { + x ^= x << 13; + x ^= x >> 7; + x ^= x << 17; + x as u8 + }) + .collect(); + let laid = dib_layout(d.clone()); + if exact_length_fixed(&d).is_none() && !bmp_offset_fixed(&laid) { + assert_eq!(dib_to_bmp(&laid).unwrap(), oracle_dib_to_bmp(&oracle_dib_layout(d))); + } + } + } + + #[test] + fn huge_palette_count_saturates_the_offset() { + let b = dib_to_bmp(&info(40, 8, 0, u32::MAX, [0; 4], 8)).unwrap(); + assert_eq!(u32::from_le_bytes([b[10], b[11], b[12], b[13]]), u32::MAX); + let b = dib_to_bmp(&info(u32::MAX, 8, 3, u32::MAX, [0; 4], 8)).unwrap(); + assert_eq!(u32::from_le_bytes([b[10], b[11], b[12], b[13]]), u32::MAX); + } + + #[test] + fn wrapped_dibs_decode_and_keep_alpha() { + // 2x2 32-bit V5, BI_RGB with an alpha mask, bottom-up BGRA pixels. + let mut d = info(124, 32, 0, 0, [0, 0, 0, 0xFF00_0000], 0); + let px = [[1u8, 2, 3, 255], [4, 5, 6, 128], [7, 8, 9, 64], [10, 11, 12, 0]]; + for p in px { + d.extend_from_slice(&p); + } + let bmp = dib_to_bmp(&dib_layout(d)).unwrap(); + let img = crate::decode(&bmp).unwrap(); + let alphas: Vec = img.to_rgba8().chunks(4).map(|p| u16::from(p[3])).collect(); + assert_eq!(alphas, [64, 0, 255, 128]); + // 24-bit plain DIB and a 12-byte core 8-bit one open too. + let mut d = info(40, 24, 0, 0, [0; 4], 0); + d.extend_from_slice(&[0, 0, 255, 0, 255, 0, 0, 0, 0, 255, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]); + assert!(crate::decode(&dib_to_bmp(&d).unwrap()).is_ok()); + let mut c = core(8); + c.truncate(12); + c.extend((0..256 * 3).map(|i| i as u8)); + c.extend_from_slice(&[0, 1, 0, 0, 2, 3, 0, 0]); + assert!(crate::decode(&dib_to_bmp(&c).unwrap()).is_ok()); + } + + /// 1x1 32-bit BI_BITFIELDS DIB, one pixel B=10 G=20 R=30 A=128, with the given header size. + fn one_pixel(size: u32) -> Vec { + let mut d = info(size, 32, 3, 0, [0xFF0000, 0xFF00, 0xFF, 0xFF00_0000], 0); + d[4..8].copy_from_slice(&1i32.to_le_bytes()); + d[8..12].copy_from_slice(&1i32.to_le_bytes()); + if size == 40 { + for m in [0xFF0000u32, 0xFF00, 0xFF] { + d.extend_from_slice(&m.to_le_bytes()); + } + } + d.extend_from_slice(&[10, 20, 30, 128]); + d + } + + #[test] + fn bitfields_pixel_offset_for_each_header_size_decodes() { + for size in [40u32, 52, 56] { + let bmp = dib_to_bmp(&one_pixel(size)).unwrap(); + let off = 14 + size + if size == 40 { 12 } else { 0 }; + assert_eq!(dib_u32(&bmp, 10), Some(off), "offset for {size}"); + let img = crate::decode(&bmp).unwrap_or_else(|e| panic!("{size}-byte header: {e:?}")); + let rgba = img.to_rgba8(); + assert_eq!(&rgba[..3], &[30, 20, 10], "size {size}"); + if size == 56 { + assert_eq!(rgba[3], 128); + } + } + // V5: the header's masks, a copy inserted by `dib_layout`, then the pixel. + let bmp = dib_to_bmp(&dib_layout(one_pixel(124))).unwrap(); + assert_eq!(&crate::decode(&bmp).unwrap().to_rgba8()[..4], &[30, 20, 10, 128]); + } + + #[test] + fn exact_length_pixels_equal_to_the_masks_are_not_a_mask_copy() { + let d = v5_3x1(false); + let laid = dib_layout(d.clone()); + assert_eq!(laid.len(), d.len() + 12); + assert_eq!(laid[124..136], d[40..52]); + assert_eq!(oracle_dib_layout(d).len(), laid.len() - 12, "the original skipped the insertion"); + let img = crate::decode(&dib_to_bmp(&laid).unwrap()).unwrap().to_rgba8(); + assert_eq!(img.len(), 12); + // pixel 0 is 0x00FF0000 (blue 0, green 0, red 255 under the masks). + assert_eq!(&img[..3], &[255, 0, 0]); + // A real copy followed by the pixels is left alone. + let real = v5_3x1(true); + assert_eq!(dib_layout(real.clone()), real); + assert!(crate::decode(&dib_to_bmp(&real).unwrap()).is_ok()); + } + + #[test] + fn layout_decides_before_it_mutates() { + // BI_RGB V5 with an alpha mask and no colour masks: promoted and given a copy together. + let mut d = info(124, 32, 0, 0, [0, 0, 0, 0xFF00_0000], 16); + d[4..8].copy_from_slice(&2i32.to_le_bytes()); + let laid = dib_layout(d.clone()); + assert_eq!(laid.len(), d.len() + 12); + assert_eq!(dib_u32(&laid, 16), Some(3)); + // Unreadable dimensions keep the byte-equality rule. + let mut odd = info(108, 32, 3, 0, [1, 2, 3, 0], 0); + odd[4..8].copy_from_slice(&(-1i32).to_le_bytes()); + let copy = odd[40..52].to_vec(); + odd.extend_from_slice(©); + assert_eq!(dib_layout(odd.clone()), odd); + } } diff --git a/crates/image-codecs/src/codecs/jpeg.rs b/crates/image-codecs/src/codecs/jpeg.rs index 415a5d717..56593a5f5 100644 --- a/crates/image-codecs/src/codecs/jpeg.rs +++ b/crates/image-codecs/src/codecs/jpeg.rs @@ -86,6 +86,83 @@ fn held_coefficients(marker: u8, seg: &[u8], scan_components: Option) -> u64 factors.iter().map(|&(fh, fv)| mcus * fh * fv * 64 * 2).sum() } +/// Bytes of DCT coefficients to budget for before decoding hostile `b`: the larger of +/// [`crate::JpegInfo::held_coefficients`]'s rule (first frame; SOF2, or SOF0/SOF1 whose first +/// scan lacks components; 8-bit only; sampling factors as written) and a coarser one that +/// keeps a progressive JPEG's coefficients for the whole picture: +/// - every SOF2, SOF6, SOF10 and SOF14 header before the first scan counts, at any precision, and +/// the largest wins; each charges 2 bytes a coefficient: per component, `2 * 64 * h * v` per +/// MCU, with `h` and `v` clamped to 1..=4 and the MCUs covering the frame at the largest `h`, `v`; +/// - a header that can't be followed (a segment that is cut, a length under 2, a frame header +/// without its components, no `0xFF` where a marker belongs) charges the costliest frame, +/// four components sampled 4 × 4, at the first frame's size (as `scan_metadata` reads it), and 0 without one. +/// +/// Never less than either rule. Frames `craft-jpeg` decodes (arithmetic, lossless, 12-bit) +/// enforce `max_alloc` on their own buffers, and SOF6/SOF14 (hierarchical) are not decoded at all, +/// so charging them is only a conservative budget. Arithmetic saturates; the scan is linear. +pub(crate) fn worst_case_coefficients(b: &[u8]) -> u64 { + let m = scan_metadata(b); + let mut at = 2usize; + let mut most = 0u64; + let first: Option<(u64, u64)> = m.frame.map(|(w, h, _)| (u64::from(w), u64::from(h))); + let mut broken = false; + while !broken { + if b.get(at) != Some(&0xFF) { + broken = true; + break; + } + while b.get(at) == Some(&0xFF) { + at += 1; + } + let Some(&code) = b.get(at) else { + broken = true; + break; + }; + at += 1; + match code { + 0xD8 | 0x01 | 0xD0..=0xD7 => continue, + 0xD9 | 0xDA => break, + _ => {} + } + let len = match (b.get(at), b.get(at + 1)) { + (Some(&hi), Some(&lo)) => usize::from(u16::from_be_bytes([hi, lo])), + _ => 0, + }; + let Some(seg) = (len >= 2).then(|| b.get(at + 2..at + len)).flatten() else { + broken = true; + break; + }; + if matches!(code, 0xC2 | 0xC6 | 0xCA | 0xCE) { + match progressive_frame_coefficients(seg) { + Some(held) => most = most.max(held), + None => { + broken = true; + break; + } + } + } + at += len; + } + if broken && let Some((w, h)) = first { + let mcus = w.div_ceil(32).saturating_mul(h.div_ceil(32)); + most = most.max(mcus.saturating_mul(2 * 64 * 16 * 4)); + } + most.max(m.held_coefficients) +} + +/// [`worst_case_coefficients`]'s charge for one frame header `sof` (after its length). +fn progressive_frame_coefficients(sof: &[u8]) -> Option { + let height = u64::from(u16::from_be_bytes([*sof.get(1)?, *sof.get(2)?])); + let width = u64::from(u16::from_be_bytes([*sof.get(3)?, *sof.get(4)?])); + let n = usize::from(*sof.get(5)?); + let comps = sof.get(6..6usize.checked_add(n.checked_mul(3)?)?)?; + let factors: Vec<(u64, u64)> = + comps.as_chunks::<3>().0.iter().map(|&[_, f, _]| (u64::from(f >> 4).clamp(1, 4), u64::from(f & 15).clamp(1, 4))).collect(); + let (hmax, vmax) = factors.iter().fold((1, 1), |(h, v), &(a, b)| (h.max(a), v.max(b))); + let mcus = width.div_ceil(8 * hmax).saturating_mul(height.div_ceil(8 * vmax)); + Some(factors.iter().fold(0u64, |sum, &(h, v)| sum.saturating_add(mcus.saturating_mul(2 * 64 * h * v)))) +} + /// Walk the marker segments up to SOS and collect metadata. pub(crate) fn scan_metadata(b: &[u8]) -> JpegMeta { let mut m = JpegMeta::default(); @@ -825,6 +902,170 @@ mod tests { assert_eq!(held(&frame(0xC2, 12, &[0x11, 0x11, 0x11], None)), Some(0)); } + /// The consumer's own estimate (WordCraft's `jpeg_coefficients`), ported as the oracle that + /// `worst_case_coefficients` must never undercut. + fn oracle(bytes: &[u8]) -> u64 { + fn worst(bytes: &[u8]) -> u64 { + let Some((w, h)) = info(bytes).map(|i| (i.width, i.height)) else { return 0 }; + let mcus = u64::from(w).div_ceil(32) * u64::from(h).div_ceil(32); + mcus.saturating_mul(2 * 64 * 16 * 4) + } + fn frame(sof: &[u8]) -> Option { + let height = u64::from(u16::from_be_bytes([*sof.get(1)?, *sof.get(2)?])); + let width = u64::from(u16::from_be_bytes([*sof.get(3)?, *sof.get(4)?])); + let n = usize::from(*sof.get(5)?); + let s: Vec<(u64, u64)> = sof + .get(6..6 + 3 * n)? + .as_chunks::<3>() + .0 + .iter() + .map(|&[_, s, _]| (u64::from(s >> 4).clamp(1, 4), u64::from(s & 15).clamp(1, 4))) + .collect(); + let (hm, vm) = s.iter().fold((1, 1), |(h, v), &(a, b)| (h.max(a), v.max(b))); + let mcus = width.div_ceil(8 * hm).checked_mul(height.div_ceil(8 * vm))?; + s.iter().try_fold(0u64, |sum, &(h, v)| sum.checked_add(mcus.checked_mul(2 * 64 * h * v)?)) + } + let mut at = 2; + let mut most = 0u64; + loop { + if bytes.get(at) != Some(&0xFF) { + return worst(bytes).max(most); + } + while bytes.get(at) == Some(&0xFF) { + at += 1; + } + let Some(&code) = bytes.get(at) else { return worst(bytes).max(most) }; + at += 1; + match code { + 0xD8 | 0x01 | 0xD0..=0xD7 => continue, + 0xD9 | 0xDA => return most, + _ => {} + } + let len = match (bytes.get(at), bytes.get(at + 1)) { + (Some(&hi), Some(&lo)) => usize::from(u16::from_be_bytes([hi, lo])), + _ => 0, + }; + let Some(seg) = bytes.get(at + 2..at + len).filter(|_| len >= 2) else { return worst(bytes).max(most) }; + if matches!(code, 0xC2 | 0xC6 | 0xCA | 0xCE) { + let Some(h) = frame(seg) else { return worst(bytes).max(most) }; + most = most.max(h); + } + at += len; + } + } + + /// A JPEG header: each frame is (marker, precision, width, height, sampling bytes), then an + /// optional scan of `scan` components, then EOI. + fn header(frames: &[(u8, u8, u16, u16, &[u8])], scan: Option) -> Vec { + let mut b = vec![0xFF, 0xD8]; + for &(marker, precision, w, h, f) in frames { + b.extend_from_slice(&[0xFF, marker]); + b.extend_from_slice(&(8 + 3 * f.len() as u16).to_be_bytes()); + b.push(precision); + b.extend_from_slice(&h.to_be_bytes()); + b.extend_from_slice(&w.to_be_bytes()); + b.push(f.len() as u8); + for (i, &s) in f.iter().enumerate() { + b.extend_from_slice(&[i as u8 + 1, s, 0]); + } + } + if let Some(n) = scan { + b.extend_from_slice(&[0xFF, 0xDA, 0, 6 + 2 * n, n]); + (1..=n).for_each(|c| b.extend_from_slice(&[c, 0])); + b.extend_from_slice(&[0, 63, 0]); + } + b.extend_from_slice(&[0xFF, 0xD9]); + b + } + + /// Never less than the oracle or `held_coefficients`; equal to the larger on valid headers. + #[test] + fn worst_case_coefficients_covers_both_rule_sets() { + const C3: &[u8] = &[0x22, 0x11, 0x11]; + const G: &[u8] = &[0x11]; + let cases: Vec> = vec![ + header(&[(0xC0, 8, 640, 480, C3)], Some(3)), + header(&[(0xC0, 8, 640, 480, G)], Some(1)), + header(&[(0xC0, 8, 640, 480, C3)], Some(1)), + header(&[(0xC1, 8, 640, 480, C3)], None), + header(&[(0xC2, 8, 640, 480, C3)], Some(1)), + header(&[(0xC2, 12, 640, 480, C3)], Some(1)), + header(&[(0xC6, 8, 640, 480, C3)], None), + header(&[(0xCA, 8, 640, 480, C3)], None), + header(&[(0xCE, 8, 640, 480, C3)], None), + header(&[(0xC0, 8, 64, 64, G), (0xC2, 8, 6000, 4000, C3), (0xC2, 8, 100, 100, C3)], Some(1)), + header(&[(0xC2, 8, 640, 480, &[0x00, 0x00, 0x00])], None), + header(&[(0xC2, 8, 640, 480, &[0xFF, 0xFF, 0xFF, 0xFF])], None), + header(&[(0xC2, 8, 65535, 65535, &[0x44; 4])], None), + header(&[(0xC0, 8, 65535, 65535, &[0xFF; 4])], Some(1)), + header(&[], None), + vec![0xFF, 0xD8], + vec![], + b"not a jpeg at all".to_vec(), + ]; + for b in &cases { + let held = scan_metadata(b).held_coefficients; + let got = worst_case_coefficients(b); + assert!(got >= oracle(b) && got >= held, "{b:02x?}"); + assert!(got >= info(b).map_or(0, |i| i.held_coefficients)); + } + let at = |i: usize| worst_case_coefficients(&cases[i]); + // Equal to the oracle where the shared rule charges nothing extra. + for i in [0, 1, 6, 7, 8, 9, 10, 12, 14] { + assert_eq!(at(i), oracle(&cases[i]), "case {i}"); + } + // Where it does, the shared figure wins (the oracle misses a short first scan). + assert_eq!(oracle(&cases[2]), 0); + assert_eq!(at(2), scan_metadata(&cases[2]).held_coefficients); + // Unclamped factors (15 × 15) charge the shared rule more than the clamped oracle. + assert_eq!(at(11), scan_metadata(&cases[11]).held_coefficients); + assert!(at(11) > oracle(&cases[11])); + assert!(at(2) > 0 && at(3) == 0 && at(0) == 0); + // 12-bit and arithmetic progressive frames are charged though craft-jpeg limits itself. + assert_eq!(at(5), at(4)); + // Sampling factors clamp: 0 acts as 1, 15 as 4. + assert_eq!(at(10), 80 * 60 * 3 * 128); + assert_eq!(at(12), 2048 * 2048 * 4 * 2 * 64 * 16); + // The largest of several frames wins. + assert_eq!(at(9), oracle(&header(&[(0xC2, 8, 6000, 4000, C3)], None))); + } + + /// A cut header charges the costliest frame at its size; every prefix and random damage stays + /// bounded, never panics and never undercuts the oracle. + #[test] + fn worst_case_coefficients_hostile_input() { + let full = header(&[(0xC2, 8, 6000, 4000, &[0x22, 0x11, 0x11])], Some(1)); + let cut = &full[..full.len() - 8]; + // Cut inside the component list: a frame the scan can't read, at its own size. + let sof_cut = &full[..14]; + assert_eq!(worst_case_coefficients(sof_cut), oracle(sof_cut)); + assert_eq!(worst_case_coefficients(cut), oracle(cut)); + let mut bases = vec![full.clone(), header(&[(0xC0, 8, 6000, 4000, &[0x11; 3])], Some(1))]; + bases.push(header(&[(0xC2, 8, 65535, 65535, &[0xFF; 4])], None)); + let mut seed = 0x9E37_79B9_7F4A_7C15u64; + let mut next = move || { + seed = seed.wrapping_mul(6_364_136_223_846_793_005).wrapping_add(1_442_695_040_888_963_407); + (seed >> 33) as usize + }; + for base in &bases { + for n in 0..=base.len() { + let b = &base[..n]; + let got = worst_case_coefficients(b); + assert!(got >= oracle(b) && got < 1 << 50); + } + for _ in 0..2000 { + let mut b = base.clone(); + for _ in 0..=next() % 4 { + let i = next() % b.len(); + b[i] = next() as u8; + } + b.truncate(next() % (b.len() + 1)); + let got = worst_case_coefficients(&b); + assert!(got >= oracle(&b) && got >= scan_metadata(&b).held_coefficients && got < 1 << 50); + } + } + } + /// An APP1 Extended XMP fragment (GUID, total size, offset, data). fn extended_xmp(offset: u32) -> Vec { let mut seg = EXTENDED_XMP_HEADER.to_vec(); diff --git a/crates/image-codecs/src/lib.rs b/crates/image-codecs/src/lib.rs index dc2ac2933..47e3f12e3 100644 --- a/crates/image-codecs/src/lib.rs +++ b/crates/image-codecs/src/lib.rs @@ -307,6 +307,15 @@ pub fn jpeg_info(bytes: &[u8]) -> Option { jpeg::info(bytes) } +/// Bytes of DCT coefficients to budget for a JPEG before decoding it: never less than +/// [`JpegInfo::held_coefficients`] nor than the whole-picture estimate of every progressive +/// frame header (SOF2, SOF6, SOF10, SOF14 at any precision, sampling clamped to 1..=4), and the +/// costliest frame at the first size read when the header can't be followed. 0 without a +/// readable frame. See the function body's rules for the precise charges. +pub fn jpeg_worst_case_coefficients(bytes: &[u8]) -> u64 { + jpeg::worst_case_coefficients(bytes) +} + /// PCX's dimensions are available from its fixed-size header without decoding the RLE rows. pub fn pcx_dimensions(bytes: &[u8]) -> Option<(u32, u32)> { codecs::pcx::dimensions(bytes) diff --git a/crates/image-codecs/src/png_probe.rs b/crates/image-codecs/src/png_probe.rs index 73f1199eb..e7af74334 100644 --- a/crates/image-codecs/src/png_probe.rs +++ b/crates/image-codecs/src/png_probe.rs @@ -136,6 +136,93 @@ pub fn color_chunks(b: &[u8]) -> Option { Some(result) } +/// Most chunks [`pixel_model`] walks before the image data; each chunk is at least 12 bytes. +const MAX_PROBE_CHUNKS: usize = 1 << 16; + +/// Pixel model of a PNG, from `IHDR` and the chunk headers before the first `IDAT`. +#[derive(Clone, Copy, Debug, PartialEq, Eq)] +pub struct PixelModel { + pub width: u32, + pub height: u32, + /// `IHDR` bit depth (1, 2, 4, 8 or 16). + pub bit_depth: u8, + /// `IHDR` colour type (0 grey, 2 RGB, 3 palette, 4 grey+alpha, 6 RGBA). + pub color_type: u8, + /// A `tRNS` chunk precedes the image data; it adds alpha to grey, RGB and palette images. + pub has_trns: bool, +} + +impl PixelModel { + /// Channels of the decoded buffer (palette expands to RGB; `tRNS` adds an alpha channel). + pub fn channels(&self) -> u8 { + let base = match self.color_type { + 0 => 1, + 2 | 3 => 3, + 4 => 2, + _ => 4, + }; + base + u8::from(self.has_trns && matches!(self.color_type, 0 | 2 | 3)) + } + + /// Bytes per pixel of the buffer a decoder that expands sub-byte samples to 8 bits gives: + /// `channels * (2 if bit_depth == 16 else 1)`. + pub fn bytes_per_pixel(&self) -> u8 { + self.channels() * if self.bit_depth == 16 { 2 } else { 1 } + } + + /// Whether the image has transparency (alpha colour type or `tRNS`). + pub fn has_alpha(&self) -> bool { + matches!(self.color_type, 4 | 6) || self.has_trns + } +} + +/// Dimensions, bit depth, colour type and `tRNS` presence without inflating anything (an `iCCP` +/// profile is skipped, not decompressed). Walks at most 65,536 chunk headers and stops at `IDAT`; +/// `IEND` or the end of the input before `IDAT` is an error. Does not validate CRCs. +/// A caller gets its `(width, height, bytes_per_pixel, alpha)` as +/// `(m.width, m.height, u64::from(m.bytes_per_pixel()), m.has_alpha())`. +pub fn pixel_model(b: &[u8]) -> Result { + if !b.starts_with(b"\x89PNG\r\n\x1a\n") { + return Err(err("bad signature")); + } + let be32 = |p: usize| b.get(p..p.checked_add(4)?).and_then(|v| <[u8; 4]>::try_from(v).ok()).map(u32::from_be_bytes); + if be32(8) != Some(13) || b.get(12..16) != Some(b"IHDR") { + return Err(err("missing IHDR")); + } + let ihdr = b.get(16..29).ok_or_else(|| err("truncated IHDR"))?; + let (width, height) = (be32(16).unwrap_or(0), be32(20).unwrap_or(0)); + let (bit_depth, color_type) = (ihdr[8], ihdr[9]); + if width == 0 || height == 0 || width > i32::MAX as u32 || height > i32::MAX as u32 { + return Err(err("dimensions out of range")); + } + let depth_ok = match color_type { + 0 => matches!(bit_depth, 1 | 2 | 4 | 8 | 16), + 3 => matches!(bit_depth, 1 | 2 | 4 | 8), + 2 | 4 | 6 => matches!(bit_depth, 8 | 16), + _ => false, + }; + if !depth_ok { + return Err(err("invalid IHDR")); + } + let mut has_trns = false; + let mut p = 8usize; + for _ in 0..MAX_PROBE_CHUNKS { + let len = be32(p).ok_or_else(|| err("truncated"))?; + let kind = p.checked_add(4).and_then(|k| b.get(k..k.checked_add(4)?)).ok_or_else(|| err("truncated"))?; + match kind { + b"IDAT" => return Ok(PixelModel { width, height, bit_depth, color_type, has_trns }), + b"IEND" => return Err(err("no image data")), + b"tRNS" => has_trns = true, + _ => {} + } + if len > i32::MAX as u32 { + return Err(err("chunk length out of range")); + } + p = p.checked_add(12).and_then(|q| q.checked_add(len as usize)).ok_or_else(|| err("truncated"))?; + } + Err(CodecError::LimitExceeded("PNG chunk count".into())) +} + #[cfg(test)] mod tests { use super::*; @@ -187,4 +274,140 @@ mod tests { assert!(!color.srgb); assert!(color_chunks(b"not png").is_none()); } + + /// WordCraft's `png_chunks` (crates/geom/src/picture.rs) as the differential oracle. + fn oracle(bytes: &[u8]) -> Option<(u32, u32, u64, bool)> { + let be = |at: usize| bytes.get(at..at.checked_add(4)?).and_then(|b| <[u8; 4]>::try_from(b).ok()).map(u32::from_be_bytes); + if bytes.get(12..16) != Some(b"IHDR".as_slice()) { + return None; + } + let (width, height) = (be(16)?, be(20)?); + let (depth, color) = (*bytes.get(24)?, *bytes.get(25)?); + let mut trns = false; + let mut at = 8usize; + loop { + let len = usize::try_from(be(at)?).ok()?; + match bytes.get(at.checked_add(4)?..at.checked_add(8)?)? { + b"IDAT" => break, + b"IEND" => return None, + b"tRNS" => trns = true, + _ => {} + } + at = at.checked_add(12)?.checked_add(len)?; + } + let (channels, alpha) = match color { + 0 => (1 + u64::from(trns), trns), + 2 | 3 => (3 + u64::from(trns), trns), + 4 => (2, true), + 6 => (4, true), + _ => return None, + }; + Some((width, height, channels * if depth == 16 { 2 } else { 1 }, alpha)) + } + + fn tuple(b: &[u8]) -> Option<(u32, u32, u64, bool)> { + pixel_model(b).ok().map(|m| (m.width, m.height, u64::from(m.bytes_per_pixel()), m.has_alpha())) + } + + fn png_with(depth: u8, color: u8, before_idat: &[(&[u8; 4], Vec)]) -> Vec { + let mut bytes = b"\x89PNG\r\n\x1a\n".to_vec(); + let mut ihdr = Vec::new(); + ihdr.extend_from_slice(&5u32.to_be_bytes()); + ihdr.extend_from_slice(&7u32.to_be_bytes()); + ihdr.extend_from_slice(&[depth, color, 0, 0, 0]); + chunk(&mut bytes, b"IHDR", &ihdr); + for (k, d) in before_idat { + chunk(&mut bytes, k, d); + } + chunk(&mut bytes, b"IDAT", &[1, 2, 3]); + chunk(&mut bytes, b"IEND", &[]); + bytes + } + + #[test] + fn pixel_model_matches_oracle_for_every_color_type_depth_and_trns() { + let valid: [(u8, &[u8]); 5] = [(0, &[1, 2, 4, 8, 16]), (2, &[8, 16]), (3, &[1, 2, 4, 8]), (4, &[8, 16]), (6, &[8, 16])]; + for (color, depths) in valid { + for &depth in depths { + for trns in [false, true] { + let extra: Vec<(&[u8; 4], Vec)> = if trns { vec![(b"tRNS", vec![0, 0])] } else { vec![] }; + let bytes = png_with(depth, color, &extra); + assert!(tuple(&bytes).is_some(), "color {color} depth {depth}"); + assert_eq!(tuple(&bytes), oracle(&bytes), "color {color} depth {depth} trns {trns}"); + } + } + } + } + + #[test] + fn pixel_model_known_values() { + let m = pixel_model(&png_with(16, 2, &[(b"tRNS", vec![0; 6])])).unwrap(); + assert_eq!((m.width, m.height, m.channels(), m.bytes_per_pixel(), m.has_alpha()), (5, 7, 4, 8, true)); + let m = pixel_model(&png_with(4, 3, &[])).unwrap(); + assert_eq!((m.bytes_per_pixel(), m.has_alpha()), (3, false)); + } + + #[test] + fn pixel_model_skips_a_huge_iccp_without_inflating() { + let junk = vec![0xAB; 20 << 20]; + let bytes = png_with(8, 2, &[(b"iCCP", junk), (b"tRNS", vec![0; 6])]); + assert_eq!(tuple(&bytes), oracle(&bytes)); + assert_eq!(tuple(&bytes), Some((5, 7, 4, true))); + } + + #[test] + fn pixel_model_malformed_inputs_agree_with_oracle_and_never_panic() { + let full = png_with(8, 6, &[(b"tRNS", vec![0]), (b"gAMA", vec![0; 4])]); + for n in 0..=full.len() { + let cut = &full[..n]; + let got = tuple(cut); + // an Err where the oracle answers can only be a stricter header check + if got.is_some() { + assert_eq!(got, oracle(cut), "prefix {n}"); + } + } + assert!(pixel_model(&full[..33]).is_err()); + // missing IHDR + let mut bad = full.clone(); + bad[12..16].copy_from_slice(b"IHDX"); + assert!(pixel_model(&bad).is_err() && oracle(&bad).is_none()); + // chunk length overflow: a length past the input, then one past i32::MAX + for len in [u32::MAX, i32::MAX as u32, 0x7fff_fff0] { + let mut o = full.clone(); + o[33..37].copy_from_slice(&len.to_be_bytes()); + assert!(pixel_model(&o).is_err(), "len {len:#x}"); + assert_eq!(tuple(&o), oracle(&o)); + } + // IEND before IDAT, unknown colour type, zero size, bad signature + let mut iend = png_with(8, 2, &[]); + let at = iend.windows(4).position(|w| w == b"IDAT").unwrap(); + iend[at..at + 4].copy_from_slice(b"IEND"); + assert!(pixel_model(&iend).is_err() && oracle(&iend).is_none()); + assert!(pixel_model(&png_with(8, 5, &[])).is_err()); + let mut zero = png_with(8, 2, &[]); + zero[16..20].copy_from_slice(&0u32.to_be_bytes()); + assert!(pixel_model(&zero).is_err()); + assert!(pixel_model(b"not a png").is_err()); + // deterministic pseudo-random corruption + let mut s = 0x9e37_79b9u32; + for _ in 0..2000 { + let mut f = full.clone(); + for _ in 0..3 { + s = s.wrapping_mul(1_664_525).wrapping_add(1_013_904_223); + let i = (s >> 8) as usize % f.len(); + f[i] = (s >> 24) as u8; + } + let _ = pixel_model(&f); + } + } + + #[test] + fn pixel_model_many_tiny_chunks_and_the_chunk_cap() { + let many: Vec<(&[u8; 4], Vec)> = (0..10_000).map(|_| (b"tEXt", Vec::new())).chain([(b"tRNS", vec![0])]).collect(); + let bytes = png_with(8, 0, &many); + assert_eq!(tuple(&bytes), oracle(&bytes)); + assert_eq!(tuple(&bytes), Some((5, 7, 2, true))); + let over: Vec<(&[u8; 4], Vec)> = (0..MAX_PROBE_CHUNKS + 1).map(|_| (b"tEXt", Vec::new())).collect(); + assert!(matches!(pixel_model(&png_with(8, 0, &over)), Err(CodecError::LimitExceeded(_)))); + } } diff --git a/crates/image-codecs/src/webp_probe.rs b/crates/image-codecs/src/webp_probe.rs index 4a31def00..1c22411dc 100644 --- a/crates/image-codecs/src/webp_probe.rs +++ b/crates/image-codecs/src/webp_probe.rs @@ -32,6 +32,25 @@ pub fn header(bytes: &[u8]) -> Result<(u32, u32, u16), CodecError> { Ok((w, h, orientation)) } +/// Whether a WebP carries transparency, from the first chunk only (nothing is decoded): +/// `VP8X` flag bit 0x10, `VP8L` `alpha_is_used`, plain `VP8` never. +pub fn has_alpha(bytes: &[u8]) -> Result { + let err = |s: &str| CodecError::malformed(Format::WebP, s); + if bytes.get(..4) != Some(b"RIFF") || bytes.get(8..12) != Some(b"WEBP") { + return Err(err("bad signature")); + } + match bytes.get(12..16) { + Some(b"VP8X") => Ok(bytes.get(20).ok_or_else(|| err("truncated VP8X"))? & 0x10 != 0), + // 0x2f signature byte, then 14+14 size bits, then the alpha_is_used bit (bit 28) + Some(b"VP8L") => match bytes.get(20..25) { + Some([0x2f, a, b, c, d]) => Ok(u32::from_le_bytes([*a, *b, *c, *d]) >> 28 & 1 != 0), + _ => Err(err("bad VP8L header")), + }, + Some(b"VP8 ") => Ok(false), + _ => Err(err("no image data")), + } +} + #[cfg(test)] mod tests { use super::*; @@ -71,4 +90,39 @@ mod tests { bytes.push(0); assert!(header(&bytes).is_err()); } + + #[test] + fn has_alpha_reads_vp8x_vp8l_and_plain_vp8() { + for (layout, want) in [(crate::ChannelLayout::Rgb, false), (crate::ChannelLayout::Rgba, true)] { + let n = layout.channels(); + let image = crate::Image::from_u8(2, 3, layout, vec![42; 6 * n]).unwrap(); + let bytes = crate::encode(&image, Format::WebP, &crate::EncodeOptions::default()).unwrap(); + assert_eq!(has_alpha(&bytes).unwrap(), want); + } + let riff = |chunk: &[u8; 4], body: &[u8]| { + let mut v = b"RIFF\0\0\0\0WEBP".to_vec(); + v.extend_from_slice(chunk); + v.extend_from_slice(&(body.len() as u32).to_le_bytes()); + v.extend_from_slice(body); + v + }; + let mut x = [0u8; 10]; + assert!(!has_alpha(&riff(b"VP8X", &x)).unwrap()); + x[0] = 0x10; + assert!(has_alpha(&riff(b"VP8X", &x)).unwrap()); + assert!(!has_alpha(&riff(b"VP8 ", &[0; 10])).unwrap()); + assert!(has_alpha(&riff(b"VP8L", &[0x2f, 0, 0, 0, 0x10])).unwrap()); + assert!(!has_alpha(&riff(b"VP8L", &[0x2f, 0, 0, 0, 0])).unwrap()); + } + + #[test] + fn has_alpha_rejects_malformed_prefixes() { + let full = [b"RIFF\0\0\0\0WEBPVP8X\x0a\0\0\0".as_slice(), &[0x10; 10]].concat(); + for n in 0..20 { + assert!(has_alpha(&full[..n]).is_err(), "prefix {n}"); + } + assert!(has_alpha(&full[..21]).is_ok()); + assert!(has_alpha(b"RIFF\0\0\0\0WEBPVP8L\x05\0\0\0\x2e").is_err()); + assert!(has_alpha(b"junk").is_err()); + } } diff --git a/crates/image-codecs/tests/it/malformed.rs b/crates/image-codecs/tests/it/malformed.rs index ec06109e0..b247bdfc6 100644 --- a/crates/image-codecs/tests/it/malformed.rs +++ b/crates/image-codecs/tests/it/malformed.rs @@ -76,9 +76,11 @@ fn truncated_files_mostly_error() { #[test] fn bit_flips_never_panic() { + // CRAFT_HOSTILE_DIVISOR=N (pull requests) runs 1/N of the flips. + let rounds = 150usize.div_ceil(craft_media_testkit::hostile::divisor()); let mut rng = common::Rng::new(42); for (f, bytes) in samples() { - for _ in 0..150 { + for _ in 0..rounds { let mut b = bytes.clone(); let flips = 1 + (rng.next_u64() % 4) as usize; for _ in 0..flips { @@ -92,8 +94,11 @@ fn bit_flips_never_panic() { #[test] fn byte_overwrites_in_header_never_panic() { - for (f, bytes) in samples() { - for i in 0..bytes.len().min(64) { + // CRAFT_HOSTILE_DIVISOR=N (pull requests) overwrites every N-th byte, from a different offset + // for each sample, so the samples together still reach every header position. + let step = craft_media_testkit::hostile::divisor(); + for (k, (f, bytes)) in samples().into_iter().enumerate() { + for i in (0..bytes.len().min(64)).filter(|i| (i + k) % step == 0) { for v in [0x00, 0x7F, 0xFF] { let mut b = bytes.clone(); b[i] = v; diff --git a/crates/image-codecs/tests/it/tiff_pages.rs b/crates/image-codecs/tests/it/tiff_pages.rs index 7501be936..7f6708f88 100644 --- a/crates/image-codecs/tests/it/tiff_pages.rs +++ b/crates/image-codecs/tests/it/tiff_pages.rs @@ -820,15 +820,18 @@ fn poke(bytes: &[u8]) { #[test] fn zoo_decodes_and_never_panics_when_cut_or_corrupted() { - for f in zoo() { + // CRAFT_HOSTILE_DIVISOR=N (pull requests) runs every N-th cut and flip, from a different offset + // for each file, and 1/N of the random rounds. + let step = craft_media_testkit::hostile::divisor(); + for (k, f) in zoo().into_iter().enumerate() { let info = tiff_info(&f).unwrap(); for i in 0..info.pages.len() { decode_tiff_page(&f, i, &DecodeOptions::default()).unwrap(); } - for cut in 0..f.len() { + for cut in (0..f.len()).filter(|cut| (cut + k) % step == 0) { poke(&f[..cut]); } - for i in 0..f.len() { + for i in (0..f.len()).filter(|i| (i + k) % step == 0) { for flip in [0xffu8, 0x80, 0x01] { let mut g = f.clone(); g[i] ^= flip; @@ -836,7 +839,7 @@ fn zoo_decodes_and_never_panics_when_cut_or_corrupted() { } } let mut r = Rng::new(f.len() as u64); - for _ in 0..300 { + for _ in 0..300usize.div_ceil(step) { let mut g = f.clone(); for _ in 0..4 { let i = (r.next_u64() as usize) % g.len(); diff --git a/crates/java-class/Cargo.toml b/crates/java-class/Cargo.toml new file mode 100644 index 000000000..6dfbd16e5 --- /dev/null +++ b/crates/java-class/Cargo.toml @@ -0,0 +1,13 @@ +[package] +name="craft-java-class" +description="Java class-file inspection and JVM bytecode decoding with retained bounds and partial reports" +version.workspace=true +edition.workspace=true +license.workspace=true +rust-version.workspace=true +repository.workspace=true +[lints] +workspace=true +[dependencies] +serde={workspace=true} +thiserror={workspace=true} diff --git a/crates/java-class/src/bytes.rs b/crates/java-class/src/bytes.rs new file mode 100644 index 000000000..bc26aea19 --- /dev/null +++ b/crates/java-class/src/bytes.rs @@ -0,0 +1,51 @@ +//! Checked little/big-endian reads over untrusted bytes. Every read returns `None` when out of range. + +#[derive(Debug, Clone, Copy)] +pub struct Reader<'a> { + data: &'a [u8], +} + +impl<'a> Reader<'a> { + pub fn new(data: &'a [u8]) -> Self { + Reader { data } + } + + pub fn slice(&self, off: usize, len: usize) -> Option<&'a [u8]> { + let end = off.checked_add(len)?; + self.data.get(off..end) + } + + pub fn u8(&self, off: usize) -> Option { + self.data.get(off).copied() + } + + fn arr(&self, off: usize) -> Option<[u8; N]> { + self.slice(off, N)?.try_into().ok() + } + + pub fn u16_be(&self, off: usize) -> Option { + self.arr(off).map(u16::from_be_bytes) + } + + pub fn u32_be(&self, off: usize) -> Option { + self.arr(off).map(u32::from_be_bytes) + } + + pub fn u64_be(&self, off: usize) -> Option { + self.arr(off).map(u64::from_be_bytes) + } +} + +/// Decode one modified UTF-8 code unit. Invalid bytes consume only themselves, +/// so a damaged sequence cannot hide valid text or borrow missing bytes. +pub(crate) fn mutf8_unit(bytes: &[u8]) -> (u16, usize) { + match bytes { + [a @ 0x00..=0x7f, ..] => (u16::from(*a), 1), + [0xc0, 0x80, ..] => (0, 2), + [a @ 0xc2..=0xdf, b @ 0x80..=0xbf, ..] => ((u16::from(*a & 0x1f) << 6) | u16::from(*b & 0x3f), 2), + [a @ 0xe0..=0xef, b @ 0x80..=0xbf, c @ 0x80..=0xbf, ..] if *a != 0xe0 || *b >= 0xa0 => { + ((u16::from(*a & 0x0f) << 12) | (u16::from(*b & 0x3f) << 6) | u16::from(*c & 0x3f), 3) + } + _ => (0xfffd, 1), + } +} diff --git a/crates/java-class/src/descriptor.rs b/crates/java-class/src/descriptor.rs new file mode 100644 index 000000000..3f4b32bd7 --- /dev/null +++ b/crates/java-class/src/descriptor.rs @@ -0,0 +1,19 @@ +// Descriptor display helper retained from the source DEX reader. +pub fn java_name(desc: &str) -> String { + let dims = desc.chars().take_while(|&c| c == '[').count(); + let base = desc.get(dims..).unwrap_or(""); + let name = match base { + "V" => "void".to_string(), + "Z" => "boolean".to_string(), + "B" => "byte".to_string(), + "S" => "short".to_string(), + "C" => "char".to_string(), + "I" => "int".to_string(), + "J" => "long".to_string(), + "F" => "float".to_string(), + "D" => "double".to_string(), + b if b.starts_with('L') && b.ends_with(';') => b.get(1..b.len() - 1).unwrap_or("").replace('/', "."), + b => b.to_string(), + }; + format!("{name}{}", "[]".repeat(dims.min(255))) +} diff --git a/crates/java-class/src/java_class.rs b/crates/java-class/src/java_class.rs new file mode 100644 index 000000000..4b751ec3e --- /dev/null +++ b/crates/java-class/src/java_class.rs @@ -0,0 +1,1082 @@ +//! Java `.class` files (JVMS): the magic and version, the constant pool (every tag including +//! `MethodHandle`/`MethodType`/`Dynamic`/`InvokeDynamic`/`Module`/`Package`), access flags, the +//! this/super class and interfaces, fields and methods with their attributes (`Code` with its +//! exception table and line numbers, `ConstantValue`, `Exceptions`, `Signature`), and the +//! class-level `SourceFile`, `InnerClasses` and annotation attributes (type names, best-effort). +//! +//! Counts and lengths are checked against the file size, strings are decoded from modified UTF-8, +//! and every read is bounds-checked, so hostile input yields warnings, not panics. + +use crate::bytes::Reader; +use crate::java_ops::{self, Insn}; +use crate::{FormatError, descriptor as dex}; +use serde::Serialize; + +/// Most constant-pool entries, fields, methods, attributes or interfaces we read from one file. +const MAX_ITEMS: usize = 1 << 20; +/// Most attributes per element. +const MAX_ATTRS: usize = 64 * 1024; +/// Deepest annotation/element-value nesting we walk. +const MAX_ANNO_DEPTH: usize = 32; + +/// One constant-pool entry. Index 0 and the slot after a `Long`/`Double` are `Unusable`. +#[derive(Debug, Clone, PartialEq)] +pub enum Const { + Unusable, + Utf8(String), + Integer(i32), + Float(f32), + Long(i64), + Double(f64), + /// `name_index` → a Utf8 internal name. + Class(u16), + /// `string_index` → a Utf8. + String(u16), + /// `class_index`, `name_and_type_index`. + FieldRef(u16, u16), + MethodRef(u16, u16), + InterfaceMethodRef(u16, u16), + /// `name_index`, `descriptor_index`. + NameAndType(u16, u16), + /// `reference_kind`, `reference_index`. + MethodHandle(u8, u16), + /// `descriptor_index`. + MethodType(u16), + /// `bootstrap_method_attr_index`, `name_and_type_index`. + Dynamic(u16, u16), + InvokeDynamic(u16, u16), + Module(u16), + Package(u16), +} + +/// The class-file version. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +pub struct Version { + pub major: u16, + pub minor: u16, +} + +impl Version { + /// A friendly Java platform label (`Java 8`, `Java 17`, `Java 1.3`). + pub fn java_label(self) -> String { + match self.major { + 45..=48 => format!("Java 1.{}", self.major - 44), + m if m >= 49 => format!("Java {}", m - 44), + m => format!("pre-standard (major {m})"), + } + } +} + +/// An exception-table row of a `Code` attribute. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct ExceptionEntry { + pub start_pc: u16, + pub end_pc: u16, + pub handler_pc: u16, + /// Dotted caught type; `None` is catch-all (a `finally` or `catch (Throwable)` with index 0). + pub catch_type: Option, +} + +/// A parsed `Code` attribute. +#[derive(Debug, Clone, Default, PartialEq, Eq)] +pub struct Code { + pub max_stack: u16, + pub max_locals: u16, + pub bytecode: Vec, + pub exceptions: Vec, + /// `(start_pc, line)` from the `LineNumberTable`. + pub line_numbers: Vec<(u16, u16)>, +} + +/// A field or method. +#[derive(Debug, Clone, Default, PartialEq)] +pub struct Member { + pub access: u16, + pub name: String, + pub descriptor: String, + /// The generic `Signature` attribute, if present. + pub signature: Option, + /// A field's `ConstantValue`, rendered to text. + pub constant_value: Option, + /// A method's declared `throws` types (dotted). + pub exceptions: Vec, + /// A method's code. + pub code: Option, + pub deprecated: bool, + /// The `Synthetic` attribute (separate from the access flag). + pub synthetic_attr: bool, +} + +/// An `InnerClasses` row. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct InnerClass { + pub inner: Option, + pub outer: Option, + /// Simple name; `None` for an anonymous class. + pub name: Option, + pub access: u16, +} + +/// A parsed class file. +#[derive(Debug, Clone)] +pub struct ClassFile { + pub version: Version, + pub access: u16, + /// Internal name of this class (`com/example/Main`). + pub this_class: String, + /// Internal name of the superclass; `None` only for `java/lang/Object` and modules. + pub super_class: Option, + /// Internal names of the implemented interfaces. + pub interfaces: Vec, + pub fields: Vec, + pub methods: Vec, + pub source_file: Option, + pub signature: Option, + pub inner_classes: Vec, + /// Class-level annotation types (dotted), with `(runtime)`/`(class)` visibility. + pub annotations: Vec, + /// Bootstrap method handle and static arguments, indexed by dynamic pool constants. + pub bootstrap_methods: Vec<(u16, Vec)>, + pub pool: Vec, + pub warnings: Vec, +} + +// --------------------------------------------------------------------------------------------- +// Names, descriptors and access flags + +/// `java/lang/String` → `java.lang.String`; `[Ljava/lang/String;` → `java.lang.String[]`. +pub fn internal_to_dotted(name: &str) -> String { + if name.starts_with('[') { dex::java_name(name) } else { name.replace('/', ".") } +} + +/// A field descriptor (`Ljava/lang/String;`, `[I`, `I`) as a Java type. +pub fn field_type(desc: &str) -> String { + dex::java_name(desc) +} + +/// Read parameter descriptors up to the closing parenthesis and return the remaining return descriptor. +fn split_types(s: &str) -> Option<(Vec, &str)> { + let b = s.as_bytes(); + let mut out = Vec::new(); + let mut i = 0usize; + while i < b.len() && out.len() < MAX_ITEMS { + if b.get(i) == Some(&b')') { + return Some((out, s.get(i + 1..)?)); + } + let start = i; + while b.get(i) == Some(&b'[') { + i += 1; + } + match b.get(i) { + Some(b'L') => match s.get(i..).and_then(|r| r.find(';')) { + Some(semi) => i = i + semi + 1, + None => i = b.len(), + }, + Some(_) => i += 1, + None => break, + } + match s.get(start..i) { + Some(t) if !t.is_empty() => out.push(t.to_string()), + _ => break, + } + } + None +} + +/// Parameter types and return type of a method descriptor (`(Ljava/lang/String;I)V`). +pub fn method_params(desc: &str) -> (Vec, String) { + let Some(rest) = desc.strip_prefix('(') else { return (Vec::new(), "?".into()) }; + let Some((params, ret)) = split_types(rest) else { return (Vec::new(), "?".into()) }; + (params.iter().map(|t| field_type(t)).collect(), field_type(ret)) +} + +/// What a set of access flags belongs to. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum AccessKind { + Class, + Field, + Method, + InnerClass, +} + +/// Human names of the set access flags. +pub fn access_flags(flags: u16, kind: AccessKind) -> Vec<&'static str> { + let mut v = Vec::new(); + let common: &[(u16, &str)] = &[(0x0001, "public"), (0x0002, "private"), (0x0004, "protected"), (0x0008, "static"), (0x0010, "final")]; + for (bit, name) in common { + if flags & bit != 0 { + v.push(*name); + } + } + match kind { + AccessKind::Method => { + for (bit, name) in [ + (0x0020u16, "synchronized"), + (0x0040, "bridge"), + (0x0080, "varargs"), + (0x0100, "native"), + (0x0400, "abstract"), + (0x0800, "strictfp"), + (0x1000, "synthetic"), + ] { + if flags & bit != 0 { + v.push(name); + } + } + } + AccessKind::Field => { + for (bit, name) in [(0x0040u16, "volatile"), (0x0080, "transient"), (0x1000, "synthetic"), (0x4000, "enum")] { + if flags & bit != 0 { + v.push(name); + } + } + } + AccessKind::Class | AccessKind::InnerClass => { + for (bit, name) in [ + (0x0020u16, "super"), + (0x0200, "interface"), + (0x0400, "abstract"), + (0x1000, "synthetic"), + (0x2000, "annotation"), + (0x4000, "enum"), + (0x8000, "module"), + ] { + if flags & bit != 0 { + // "super" is an internal marker on classes; hide it unless it is the only flag of note. + if name == "super" && kind == AccessKind::Class { + continue; + } + v.push(name); + } + } + } + } + v +} + +/// A resolved reference to a field or method. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct Ref { + /// Internal owner name (`java/lang/System`). + pub owner: String, + pub name: String, + pub descriptor: String, +} + +impl Ref { + /// `java.lang.System.out:java.io.PrintStream` style display. A field descriptor is shown as a + /// Java type; a method descriptor is left in its raw `(args)ret` form. + pub fn display(&self) -> String { + let ty = if self.descriptor.starts_with('(') { self.descriptor.clone() } else { field_type(&self.descriptor) }; + format!("{}.{}:{}", internal_to_dotted(&self.owner), self.name, ty) + } +} + +// --------------------------------------------------------------------------------------------- +// Modified UTF-8 + +/// Decode a modified-UTF-8 byte run (class-file `Utf8` content) to a String. +fn decode_mutf8(bytes: &[u8]) -> String { + let mut units: Vec = Vec::new(); + let mut i = 0usize; + while i < bytes.len() { + let (unit, consumed) = crate::bytes::mutf8_unit(bytes.get(i..).unwrap_or_default()); + units.push(unit); + i += consumed; + } + String::from_utf16_lossy(&units) +} + +// --------------------------------------------------------------------------------------------- +// Cursor + +struct Cursor<'a> { + r: Reader<'a>, + pos: usize, +} + +impl<'a> Cursor<'a> { + fn new(data: &'a [u8]) -> Self { + Cursor { r: Reader::new(data), pos: 0 } + } + fn u8(&mut self) -> Option { + let v = self.r.u8(self.pos)?; + self.pos += 1; + Some(v) + } + fn u16(&mut self) -> Option { + let v = self.r.u16_be(self.pos)?; + self.pos += 2; + Some(v) + } + fn u32(&mut self) -> Option { + let v = self.r.u32_be(self.pos)?; + self.pos += 4; + Some(v) + } + fn u64(&mut self) -> Option { + let v = self.r.u64_be(self.pos)?; + self.pos += 8; + Some(v) + } + fn take(&mut self, n: usize) -> Option<&'a [u8]> { + let s = self.r.slice(self.pos, n)?; + self.pos += n; + Some(s) + } +} + +// --------------------------------------------------------------------------------------------- +// Parsing + +/// True when the bytes begin a Java class file (0xCAFEBABE and a plausible major version). +/// A big-endian Mach-O fat binary shares the magic but has a small arch count where the version +/// is, so it fails the major-version check. +pub fn is_class(data: &[u8]) -> bool { + if !data.starts_with(&[0xca, 0xfe, 0xba, 0xbe]) { + return false; + } + let r = Reader::new(data); + matches!(r.u16_be(6), Some(major) if (45..=255).contains(&major)) +} + +fn utf8_of(pool: &[Const], idx: u16) -> &str { + match pool.get(idx as usize) { + Some(Const::Utf8(s)) => s.as_str(), + _ => "", + } +} + +/// Parse a class file. +pub fn parse(data: &[u8]) -> Result { + if !data.starts_with(&[0xca, 0xfe, 0xba, 0xbe]) { + return Err(FormatError::Malformed("not a Java class file (no 0xCAFEBABE magic)".into())); + } + let mut c = Cursor::new(data); + let mut warnings = Vec::new(); + let _magic = c.u32(); + let minor = c.u16().ok_or_else(|| FormatError::Truncated("version".into()))?; + let major = c.u16().ok_or_else(|| FormatError::Truncated("version".into()))?; + if major < 45 { + return Err(FormatError::Unsupported(format!("class major version {major} is below 45 (not a standard class file)"))); + } + let version = Version { major, minor }; + let cp_count = c.u16().ok_or_else(|| FormatError::Truncated("constant pool count".into()))?; + if cp_count == 0 { + return Err(FormatError::Malformed("constant pool count is zero".into())); + } + let pool = parse_pool(&mut c, cp_count, &mut warnings)?; + let access = c.u16().ok_or_else(|| FormatError::Truncated("access flags".into()))?; + let this_idx = c.u16().ok_or_else(|| FormatError::Truncated("this_class".into()))?; + let super_idx = c.u16().ok_or_else(|| FormatError::Truncated("super_class".into()))?; + let this_class = class_name_at(&pool, this_idx); + let super_class = if super_idx == 0 { None } else { Some(class_name_at(&pool, super_idx)) }; + // Interfaces + let n_iface = c.u16().ok_or_else(|| FormatError::Truncated("interfaces count".into()))? as usize; + let mut interfaces = Vec::new(); + for _ in 0..n_iface.min(MAX_ITEMS) { + let Some(i) = c.u16() else { + warnings.push("interface list ended early".into()); + break; + }; + interfaces.push(class_name_at(&pool, i)); + } + // Fields + let fields = parse_members(&mut c, &pool, &mut warnings, "field")?; + // Methods + let methods = parse_members(&mut c, &pool, &mut warnings, "method")?; + // Class attributes + let (attrs, complete) = read_attrs(&mut c, &pool); + if !complete { + warnings.push("class attribute table ended early".into()); + } + let mut source_file = None; + let mut signature = None; + let mut inner_classes = Vec::new(); + let mut annotations = Vec::new(); + let mut bootstrap_methods = Vec::new(); + for a in &attrs { + match a.name { + "SourceFile" => { + if let Some(i) = Reader::new(a.info).u16_be(0) { + source_file = Some(utf8_of(&pool, i).to_string()); + } + } + "Signature" => { + if let Some(i) = Reader::new(a.info).u16_be(0) { + signature = Some(utf8_of(&pool, i).to_string()); + } + } + "BootstrapMethods" => match bootstrap_table(a.info) { + Some(table) => bootstrap_methods = table, + None => warnings.push("invalid BootstrapMethods table".into()), + }, + "InnerClasses" => inner_classes = parse_inner_classes(a.info, &pool), + "RuntimeVisibleAnnotations" => annotations.extend(parse_annotation_types(a.info, &pool, "runtime")), + "RuntimeInvisibleAnnotations" => annotations.extend(parse_annotation_types(a.info, &pool, "class")), + _ => {} + } + } + Ok(ClassFile { + version, + access, + this_class, + super_class, + interfaces, + fields, + methods, + source_file, + signature, + inner_classes, + annotations, + bootstrap_methods, + pool, + warnings, + }) +} + +fn parse_pool(c: &mut Cursor<'_>, cp_count: u16, warnings: &mut Vec) -> Result, FormatError> { + let mut pool = vec![Const::Unusable]; // index 0 + let mut i = 1u16; + while i < cp_count { + let tag = c.u8().ok_or_else(|| FormatError::Truncated("constant pool entry".into()))?; + let entry = match tag { + 1 => { + let len = c.u16().ok_or_else(|| FormatError::Truncated("Utf8 length".into()))? as usize; + let bytes = c.take(len).ok_or_else(|| FormatError::Truncated("Utf8 bytes".into()))?; + Const::Utf8(decode_mutf8(bytes)) + } + 3 => Const::Integer(c.u32().ok_or_else(|| trunc("Integer"))? as i32), + 4 => Const::Float(f32::from_bits(c.u32().ok_or_else(|| trunc("Float"))?)), + 5 => Const::Long(c.u64().ok_or_else(|| trunc("Long"))? as i64), + 6 => Const::Double(f64::from_bits(c.u64().ok_or_else(|| trunc("Double"))?)), + 7 => Const::Class(c.u16().ok_or_else(|| trunc("Class"))?), + 8 => Const::String(c.u16().ok_or_else(|| trunc("String"))?), + 9 => Const::FieldRef(c.u16().ok_or_else(|| trunc("Fieldref"))?, c.u16().ok_or_else(|| trunc("Fieldref"))?), + 10 => Const::MethodRef(c.u16().ok_or_else(|| trunc("Methodref"))?, c.u16().ok_or_else(|| trunc("Methodref"))?), + 11 => Const::InterfaceMethodRef(c.u16().ok_or_else(|| trunc("InterfaceMethodref"))?, c.u16().ok_or_else(|| trunc("InterfaceMethodref"))?), + 12 => Const::NameAndType(c.u16().ok_or_else(|| trunc("NameAndType"))?, c.u16().ok_or_else(|| trunc("NameAndType"))?), + 15 => Const::MethodHandle(c.u8().ok_or_else(|| trunc("MethodHandle"))?, c.u16().ok_or_else(|| trunc("MethodHandle"))?), + 16 => Const::MethodType(c.u16().ok_or_else(|| trunc("MethodType"))?), + 17 => Const::Dynamic(c.u16().ok_or_else(|| trunc("Dynamic"))?, c.u16().ok_or_else(|| trunc("Dynamic"))?), + 18 => Const::InvokeDynamic(c.u16().ok_or_else(|| trunc("InvokeDynamic"))?, c.u16().ok_or_else(|| trunc("InvokeDynamic"))?), + 19 => Const::Module(c.u16().ok_or_else(|| trunc("Module"))?), + 20 => Const::Package(c.u16().ok_or_else(|| trunc("Package"))?), + other => { + return Err(FormatError::Malformed(format!("unknown constant pool tag {other} at index {i}"))); + } + }; + let wide = matches!(entry, Const::Long(_) | Const::Double(_)); + let next = i + .checked_add(if wide { 2 } else { 1 }) + .filter(|next| *next <= cp_count) + .ok_or_else(|| FormatError::Malformed(format!("constant pool entry {i} has no reserved second slot")))?; + pool.push(entry); + if wide { + pool.push(Const::Unusable); + } + i = next; + } + if pool.len() > MAX_ITEMS { + warnings.push("constant pool is unusually large".into()); + } + Ok(pool) +} + +fn trunc(what: &str) -> FormatError { + FormatError::Truncated(format!("constant pool {what}")) +} + +struct RawAttr<'a, 'p> { + // Many attributes can reference one long constant-pool name. The pool + // already owns it for the entire parse; a per-attribute copy amplifies it. + name: &'p str, + info: &'a [u8], +} + +/// Return the complete attributes in the readable prefix and whether the whole table was read. +fn read_attrs<'a, 'p>(c: &mut Cursor<'a>, pool: &'p [Const]) -> (Vec>, bool) { + let mut out = Vec::new(); + let Some(n) = c.u16().map(usize::from) else { return (out, false) }; + for _ in 0..n.min(MAX_ATTRS) { + let (Some(ni), Some(len)) = (c.u16(), c.u32()) else { return (out, false) }; + let Some(info) = c.take(len as usize) else { return (out, false) }; + out.push(RawAttr { name: utf8_of(pool, ni), info }); + } + (out, n <= MAX_ATTRS) +} + +fn bootstrap_table(data: &[u8]) -> Option)>> { + let mut cursor = Cursor::new(data); + let mut table = Vec::new(); + for _ in 0..cursor.u16()? { + let handle = cursor.u16()?; + let count = usize::from(cursor.u16()?); + let args = cursor.take(count * 2)?.as_chunks::<2>().0.iter().map(|b| u16::from_be_bytes(*b)).collect(); + table.push((handle, args)); + } + (cursor.pos == data.len()).then_some(table) +} + +fn parse_members(c: &mut Cursor<'_>, pool: &[Const], warnings: &mut Vec, what: &str) -> Result, FormatError> { + let n = c.u16().ok_or_else(|| FormatError::Truncated(format!("{what} count")))? as usize; + let mut out = Vec::new(); + for _ in 0..n.min(MAX_ITEMS) { + let (Some(access), Some(name_idx), Some(desc_idx)) = (c.u16(), c.u16(), c.u16()) else { + warnings.push(format!("{what} table ended early")); + break; + }; + let mut m = + Member { access, name: utf8_of(pool, name_idx).to_string(), descriptor: utf8_of(pool, desc_idx).to_string(), ..Default::default() }; + let (attrs, _) = read_attrs(c, pool); + for a in attrs { + match a.name { + "Code" => m.code = parse_code(a.info, pool), + "ConstantValue" => { + if let Some(i) = Reader::new(a.info).u16_be(0) { + m.constant_value = Some(const_display(pool, i)); + } + } + "Exceptions" => m.exceptions = parse_exceptions_attr(a.info, pool), + "Signature" => { + if let Some(i) = Reader::new(a.info).u16_be(0) { + m.signature = Some(utf8_of(pool, i).to_string()); + } + } + "Deprecated" => m.deprecated = true, + "Synthetic" => m.synthetic_attr = true, + _ => {} + } + } + out.push(m); + } + Ok(out) +} + +fn parse_code(info: &[u8], pool: &[Const]) -> Option { + let mut c = Cursor::new(info); + let max_stack = c.u16()?; + let max_locals = c.u16()?; + let code_len = c.u32()? as usize; + let bytecode = c.take(code_len)?.to_vec(); + let n_exc = c.u16()? as usize; + let mut exceptions = Vec::new(); + for _ in 0..n_exc.min(MAX_ITEMS) { + let (Some(start_pc), Some(end_pc), Some(handler_pc), Some(catch)) = (c.u16(), c.u16(), c.u16(), c.u16()) else { break }; + exceptions.push(ExceptionEntry { start_pc, end_pc, handler_pc, catch_type: (catch != 0).then(|| class_name_at(pool, catch)) }); + } + let mut line_numbers = Vec::new(); + let (attrs, _) = read_attrs(&mut c, pool); + for a in attrs { + if a.name == "LineNumberTable" { + let mut lc = Cursor::new(a.info); + let n = lc.u16().unwrap_or(0) as usize; + for _ in 0..n.min(MAX_ITEMS) { + let (Some(pc), Some(line)) = (lc.u16(), lc.u16()) else { break }; + line_numbers.push((pc, line)); + } + } + } + Some(Code { max_stack, max_locals, bytecode, exceptions, line_numbers }) +} + +fn parse_exceptions_attr(info: &[u8], pool: &[Const]) -> Vec { + let mut c = Cursor::new(info); + let n = c.u16().unwrap_or(0) as usize; + let mut out = Vec::new(); + for _ in 0..n.min(MAX_ITEMS) { + let Some(i) = c.u16() else { break }; + out.push(class_name_at(pool, i)); + } + out +} + +fn parse_inner_classes(info: &[u8], pool: &[Const]) -> Vec { + let mut c = Cursor::new(info); + let n = c.u16().unwrap_or(0) as usize; + let mut out = Vec::new(); + for _ in 0..n.min(MAX_ITEMS) { + let (Some(inner), Some(outer), Some(name), Some(access)) = (c.u16(), c.u16(), c.u16(), c.u16()) else { break }; + out.push(InnerClass { + inner: (inner != 0).then(|| class_name_at(pool, inner)), + outer: (outer != 0).then(|| class_name_at(pool, outer)), + name: (name != 0).then(|| utf8_of(pool, name).to_string()), + access, + }); + } + out +} + +/// Extract annotation type names (dotted) from a `Runtime*Annotations` attribute, best-effort. +fn parse_annotation_types(info: &[u8], pool: &[Const], visibility: &str) -> Vec { + let mut c = Cursor::new(info); + let n = c.u16().unwrap_or(0) as usize; + let mut out = Vec::new(); + for _ in 0..n.min(MAX_ITEMS) { + match read_annotation(&mut c, pool, 0) { + Some(t) => out.push(format!("{t} ({visibility})")), + None => break, + } + } + out +} + +/// Read one `annotation` structure, returning its (dotted) type name; advances past its values. +fn read_annotation(c: &mut Cursor<'_>, pool: &[Const], depth: usize) -> Option { + if depth > MAX_ANNO_DEPTH { + return None; + } + let type_idx = c.u16()?; + let n_pairs = c.u16()? as usize; + let type_name = field_type(utf8_of(pool, type_idx)); + for _ in 0..n_pairs.min(MAX_ITEMS) { + let _name_idx = c.u16()?; + skip_element_value(c, pool, depth + 1)?; + } + Some(type_name) +} + +fn skip_element_value(c: &mut Cursor<'_>, pool: &[Const], depth: usize) -> Option<()> { + if depth > MAX_ANNO_DEPTH { + return None; + } + let tag = c.u8()?; + match tag { + b'B' | b'C' | b'D' | b'F' | b'I' | b'J' | b'S' | b'Z' | b's' | b'c' => { + c.u16()?; + } + b'e' => { + c.u16()?; + c.u16()?; + } + b'@' => { + read_annotation(c, pool, depth + 1)?; + } + b'[' => { + let n = c.u16()? as usize; + for _ in 0..n.min(MAX_ITEMS) { + skip_element_value(c, pool, depth + 1)?; + } + } + _ => return None, + } + Some(()) +} + +/// Internal class name at a `Class` constant index (`java/lang/String` or `[I`). +fn class_name_at(pool: &[Const], idx: u16) -> String { + match pool.get(idx as usize) { + Some(Const::Class(name_idx)) => utf8_of(pool, *name_idx).to_string(), + _ => format!(""), + } +} + +/// Render a loadable constant (for `ldc`/`ConstantValue`) to text. +fn const_display(pool: &[Const], idx: u16) -> String { + match pool.get(idx as usize) { + Some(Const::Integer(v)) => v.to_string(), + Some(Const::Float(v)) => format!("{v}f"), + Some(Const::Long(v)) => format!("{v}L"), + Some(Const::Double(v)) => v.to_string(), + Some(Const::String(s)) => format!("{:?}", utf8_of(pool, *s)), + Some(Const::Class(n)) => format!("{}.class", internal_to_dotted(utf8_of(pool, *n))), + Some(Const::MethodHandle(k, _)) => format!("MethodHandle(kind {k})"), + Some(Const::MethodType(d)) => format!("MethodType({})", utf8_of(pool, *d)), + _ => format!("#{idx}"), + } +} + +// --------------------------------------------------------------------------------------------- +// Resolution and formatting on a parsed class + +impl ClassFile { + /// The Utf8 at `idx`, or an empty string. + pub fn utf8(&self, idx: u16) -> &str { + utf8_of(&self.pool, idx) + } + + /// The dotted name of this class. + pub fn name_dotted(&self) -> String { + internal_to_dotted(&self.this_class) + } + + /// Resolve a `Fieldref`/`Methodref`/`InterfaceMethodref` index to owner, name and descriptor. + pub fn resolve_ref(&self, idx: u16) -> Option { + let (class_idx, nat_idx) = match self.pool.get(idx as usize)? { + Const::FieldRef(c, n) | Const::MethodRef(c, n) | Const::InterfaceMethodRef(c, n) => (*c, *n), + _ => return None, + }; + let owner = class_name_at(&self.pool, class_idx); + let (name, descriptor) = self.name_and_type(nat_idx); + Some(Ref { owner, name, descriptor }) + } + + /// Resolve a `NameAndType` index to (name, descriptor). + pub fn name_and_type(&self, idx: u16) -> (String, String) { + match self.pool.get(idx as usize) { + Some(Const::NameAndType(n, d)) => (self.utf8(*n).to_string(), self.utf8(*d).to_string()), + _ => (format!(""), String::new()), + } + } + + /// The (name, descriptor) of an `InvokeDynamic` (or `Dynamic`) constant's `NameAndType`. + pub fn name_and_type_of_indy(&self, idx: u16) -> Option<(String, String)> { + match self.pool.get(idx as usize)? { + Const::InvokeDynamic(_, nat) | Const::Dynamic(_, nat) => Some(self.name_and_type(*nat)), + _ => None, + } + } + + /// Dotted class name at a `Class` constant index. + pub fn class_dotted(&self, idx: u16) -> String { + internal_to_dotted(&class_name_at(&self.pool, idx)) + } + + /// A Java-style method signature (`public static void log(java.lang.String)`). + pub fn method_signature(&self, m: &Member) -> String { + let (params, ret) = method_params(&m.descriptor); + let flags = access_flags(m.access, AccessKind::Method).join(" "); + let params = params.join(", "); + if m.name == "" || m.name == "" { + format!("{}{}{}({params})", flags, if flags.is_empty() { "" } else { " " }, m.name).trim().to_string() + } else { + format!("{}{}{} {}({params})", flags, if flags.is_empty() { "" } else { " " }, ret, m.name).trim().to_string() + } + } + + /// Render one decoded instruction with its constant-pool reference resolved. + pub fn format_insn(&self, i: &Insn) -> String { + let mut operand = String::new(); + if let Some(cp) = i.cp_index { + operand = match i.opcode { + 0x12..=0x14 => const_display(&self.pool, cp), + 0xb2..=0xb5 => self.resolve_ref(cp).map(|r| r.display()).unwrap_or_else(|| format!("#{cp}")), + 0xb6..=0xb9 => self + .resolve_ref(cp) + .map(|r| format!("{}.{}{}", internal_to_dotted(&r.owner), r.name, r.descriptor)) + .unwrap_or_else(|| format!("#{cp}")), + 0xba => { + // invokedynamic: show the bootstrap name:descriptor + match self.pool.get(cp as usize) { + Some(Const::InvokeDynamic(_, nat)) => { + let (n, d) = self.name_and_type(*nat); + format!("{n}{d}") + } + _ => format!("#{cp}"), + } + } + 0xbb | 0xbd | 0xc0 | 0xc1 | 0xc5 => self.class_dotted(cp), + _ => format!("#{cp}"), + }; + } else if i.opcode == 0xbc { + // newarray + operand = java_ops::array_type(i.int.unwrap_or(0)).to_string(); + } else if i.opcode == 0x84 { + // iinc local, const + operand = format!("{}, {}", i.local.unwrap_or(0), i.int.unwrap_or(0)); + } else if let Some(l) = i.local { + operand = l.to_string(); + } else if let Some(v) = i.int { + operand = v.to_string(); + } else if let Some(b) = i.branch { + operand = format!("{b}"); + } + if i.opcode == 0xc5 { + // multianewarray class, dims + operand = format!("{}, {}", operand, i.int.unwrap_or(0)); + } + let mut s = if operand.is_empty() { i.name.to_string() } else { format!("{} {}", i.name, operand) }; + if let Some(sw) = &i.switch { + let cases: Vec = sw.pairs.iter().take(32).map(|(k, t)| format!("{k} -> {t}")).collect(); + s.push_str(&format!(" # default -> {}; {}", sw.default, cases.join(", "))); + } + s + } +} + +// --------------------------------------------------------------------------------------------- +// References + +/// One place a method's bytecode refers to a class, method or field. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct Reference { + /// The calling method, `owner.name:descriptor`. + pub caller: String, + /// Byte offset in the caller's code. + pub pc: u32, + pub instruction: &'static str, + /// Direct member/type use or a method handle, method type or bootstrap linkage. + pub kind: &'static str, + pub target: String, +} + +fn class_component(name: &str) -> Option<&str> { + if name.starts_with('[') { name.trim_start_matches('[').strip_prefix('L')?.strip_suffix(';') } else { Some(name) } +} + +fn descriptor_mentions(mut descriptor: &str, owner: &str) -> bool { + while let Some((_, rest)) = descriptor.split_once('L') { + let Some((class, tail)) = rest.split_once(';') else { return false }; + if class == owner { + return true; + } + descriptor = tail; + } + false +} + +/// Resolve a loadable constant to its named dependency, retaining the linkage role. +fn constant_dependency(cf: &ClassFile, idx: u16, owner: &str, method: Option<&str>, bootstrap: bool) -> Option<(&'static str, String)> { + match cf.pool.get(usize::from(idx))? { + Const::Class(utf) if method.is_none() => { + let name = cf.utf8(*utf); + (class_component(name) == Some(owner)).then(|| ("type", internal_to_dotted(name))) + } + Const::MethodType(utf) if method.is_none() => { + let desc = cf.utf8(*utf); + descriptor_mentions(desc, owner).then(|| ("method-type", desc.to_owned())) + } + Const::MethodHandle(kind, target) => { + let member = cf.pool.get(usize::from(*target))?; + let valid = matches!( + (kind, member), + (1..=4, Const::FieldRef(..)) + | (5 | 8, Const::MethodRef(..)) + | (6 | 7, Const::MethodRef(..) | Const::InterfaceMethodRef(..)) + | (9, Const::InterfaceMethodRef(..)) + ); + let target = cf.resolve_ref(*target)?; + (valid && (!bootstrap || matches!(*kind, 6 | 8)) && target.owner == owner && method.is_none_or(|m| *kind >= 5 && target.name == m)) + .then(|| (if bootstrap { "bootstrap-method" } else { "method-handle" }, target.display())) + } + _ => None, + } +} + +/// Every instruction in `cf` that refers to the internal class `owner` (optionally only calls to +/// its methods named `method`). The bool is true when decoding or the reference limit stops a scan early. +pub fn references(cf: &ClassFile, owner: &str, method: Option<&str>, max: usize) -> (Vec, bool) { + let mut out = Vec::new(); + let mut incomplete = false; + // A single bootstrap record may be referenced by every instruction in a class. + let mut linkage_budget = 200_000usize; + for m in &cf.methods { + let Some(code) = &m.code else { continue }; + let caller = Ref { owner: cf.this_class.clone(), name: m.name.clone(), descriptor: m.descriptor.clone() }.display(); + let (insns, complete) = java_ops::decode(&code.bytecode, 200_000); + incomplete |= !complete; + for i in &insns { + let Some(cp) = i.cp_index else { continue }; + if matches!(i.opcode, 0x12..=0x14 | 0xba) { + let link = match (cf.pool.get(usize::from(cp)), i.opcode) { + (Some(Const::Dynamic(n, _)), 0x12..=0x14) | (Some(Const::InvokeDynamic(n, _)), 0xba) => Some(*n), + (Some(Const::Class(_) | Const::MethodType(_) | Const::MethodHandle(..)), 0x12 | 0x13) => None, + _ => continue, + }; + let record = link.and_then(|idx| cf.bootstrap_methods.get(usize::from(idx))); + let (handle, args): (u16, &[u16]) = record.map_or((cp, &[][..]), |(h, a)| (*h, a)); + let mut seen = std::collections::BTreeSet::new(); + for (index, &operand) in std::iter::once(&handle).chain(args).enumerate() { + let Some(left) = linkage_budget.checked_sub(1) else { return (out, true) }; + linkage_budget = left; + let is_bootstrap = index == 0 && record.is_some(); + if seen.insert((operand, is_bootstrap)) + && let Some((kind, target)) = constant_dependency(cf, operand, owner, method, is_bootstrap) + { + if out.len() >= max { + return (out, true); + } + out.push(Reference { caller: caller.clone(), pc: i.pc, instruction: i.name, kind, target }); + } + } + continue; + } + let hit = match i.opcode { + 0xb6..=0xb9 => { + cf.resolve_ref(cp).and_then(|r| (r.owner == owner && method.is_none_or(|n| r.name == n)).then(|| ("method", r.display()))) + } + 0xb2..=0xb5 if method.is_none() => cf.resolve_ref(cp).and_then(|r| (r.owner == owner).then(|| ("field", r.display()))), + 0xbb | 0xbd | 0xc0 | 0xc1 | 0xc5 if method.is_none() => { + let name = class_name_at(&cf.pool, cp); + (class_component(&name) == Some(owner)).then_some(("type", internal_to_dotted(&name))) + } + _ => None, + }; + if let Some((kind, target)) = hit { + if out.len() >= max { + return (out, true); + } + out.push(Reference { caller: caller.clone(), pc: i.pc, instruction: i.name, kind, target }); + } + } + } + (out, incomplete) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::test_support::java as fx; + + /// Two valid static methods: a one-dimensional allocation and a two-dimensional one. + fn array_reference_class(component: &str, array: &str) -> ClassFile { + let utf8 = |s: &str| { + let mut bytes = vec![1]; + bytes.extend_from_slice(&(s.len() as u16).to_be_bytes()); + bytes.extend_from_slice(s.as_bytes()); + bytes + }; + let pool = [ + utf8("sample/ArrayUses"), + vec![7, 0, 1], + utf8("java/lang/Object"), + vec![7, 0, 3], + utf8("Code"), + utf8("row"), + utf8(&format!("()[L{component};")), + utf8("grid"), + utf8(&format!("(){array}")), + utf8(component), + vec![7, 0, 10], + utf8(array), + vec![7, 0, 12], + ]; + let mut bytes = vec![0xca, 0xfe, 0xba, 0xbe, 0, 0, 0, 52, 0, 14]; + bytes.extend(pool.into_iter().flatten()); + // public/super, this, super, no interfaces or fields, two methods. + bytes.extend_from_slice(&[0, 0x21, 0, 2, 0, 4, 0, 0, 0, 0, 0, 2]); + for (name, descriptor, code) in [(6u16, 7u16, vec![4, 0xbd, 0, 11, 0xb0]), (8, 9, vec![4, 4, 0xc5, 0, 13, 2, 0xb0])] { + for word in [9u16, name, descriptor, 1, 5] { + bytes.extend_from_slice(&word.to_be_bytes()); + } + bytes.extend_from_slice(&(12u32 + code.len() as u32).to_be_bytes()); + bytes.extend_from_slice(&[0, 2, 0, 0]); // max_stack, max_locals + bytes.extend_from_slice(&(code.len() as u32).to_be_bytes()); + bytes.extend_from_slice(&code); + bytes.extend_from_slice(&[0, 0, 0, 0]); // exception table and nested attributes + } + bytes.extend_from_slice(&[0, 0]); // class attributes + let cf = parse(&bytes).unwrap(); + assert!(cf.warnings.is_empty(), "{:?}", cf.warnings); + cf + } + + #[test] + fn parentheses_in_reference_types_are_part_of_the_class_name() { + let (params, result) = method_params("(Lpkg/A)B;[Lpkg/C(D;J)Lpkg/R)S;"); + assert_eq!(params, ["pkg.A)B", "pkg.C(D[]", "long"]); + assert_eq!(result, "pkg.R)S"); + } + + #[test] + fn object_arrays_reference_the_component_class() { + let cf = array_reference_class("java/lang/String", "[[Ljava/lang/String;"); + let (refs, more) = references(&cf, "java/lang/String", None, 10); + assert!(!more); + assert_eq!(refs.len(), 2, "{refs:?}"); + assert_eq!((refs[0].instruction, refs[0].pc), ("anewarray", 1)); + assert_eq!((refs[1].instruction, refs[1].pc), ("multianewarray", 2)); + assert_eq!(refs[1].target, "java.lang.String[][]"); + let (limited, more) = references(&cf, "java/lang/String", None, 1); + assert_eq!(limited, refs[..1]); + assert!(more); + assert_eq!(references(&cf, "java/lang/String", Some("grid"), 10), (Vec::new(), false)); + assert_eq!(references(&cf, "java/lang/Integer", None, 10), (Vec::new(), false)); + } + + #[test] + fn array_components_keep_class_names_beginning_with_l() { + for component in ["Leaf", "LLeaf"] { + let cf = array_reference_class(component, &format!("[[L{component};")); + let (refs, more) = references(&cf, component, None, 10); + assert_eq!(refs.len(), 2, "{component}: {refs:?}"); + assert!(!more); + } + } + + #[test] + fn primitive_arrays_do_not_reference_a_class_named_after_the_descriptor() { + let cf = array_reference_class("I", "[[I"); + let (refs, more) = references(&cf, "I", None, 10); + assert!(!more); + assert_eq!(refs.len(), 1, "{refs:?}"); + assert_eq!(refs[0].instruction, "anewarray"); + } + + #[test] + fn parses_fixture() { + let data = fx::hello_class(); + let cf = parse(&data).unwrap(); + assert!(cf.warnings.is_empty(), "{:?}", cf.warnings); + assert_eq!(cf.this_class, "com/example/Hello"); + assert_eq!(cf.super_class.as_deref(), Some("java/lang/Object")); + assert_eq!(cf.interfaces, vec!["java/lang/Runnable"]); + assert_eq!(cf.source_file.as_deref(), Some("Hello.java")); + assert!(cf.version.major >= 45); + // field + let f = cf.fields.iter().find(|f| f.name == "count").unwrap(); + assert_eq!(field_type(&f.descriptor), "int"); + // run() loads a string and calls println + let run = cf.methods.iter().find(|m| m.name == "run").unwrap(); + assert_eq!(cf.method_signature(run), "public void run()"); + let code = run.code.as_ref().unwrap(); + let (ins, complete) = java_ops::decode(&code.bytecode, 1000); + assert!(complete, "{ins:?}"); + let text: Vec = ins.iter().map(|i| cf.format_insn(i)).collect(); + assert!(text.iter().any(|t| t == "getstatic java.lang.System.out:java.io.PrintStream"), "{text:?}"); + assert!(text.iter().any(|t| t.starts_with("ldc \"Hello")), "{text:?}"); + assert!(text.iter().any(|t| t == "invokevirtual java.io.PrintStream.println(Ljava/lang/String;)V"), "{text:?}"); + // references to System from this class + let (refs, more) = references(&cf, "java/lang/System", None, 100); + assert!(!more); + assert!(refs.iter().any(|r| r.kind == "field" && r.target.contains("out")), "{refs:?}"); + } + + #[test] + fn helpers() { + assert_eq!(internal_to_dotted("java/lang/String"), "java.lang.String"); + assert_eq!(internal_to_dotted("[Ljava/lang/String;"), "java.lang.String[]"); + assert_eq!(method_params("(Ljava/lang/String;I)V"), (vec!["java.lang.String".to_string(), "int".to_string()], "void".to_string())); + assert_eq!(method_params("()I"), (Vec::new(), "int".to_string())); + assert_eq!(Version { major: 52, minor: 0 }.java_label(), "Java 8"); + assert_eq!(Version { major: 65, minor: 0 }.java_label(), "Java 21"); + assert_eq!(decode_mutf8(&[0xc0, 0x80, 0x41]), "\0A"); + } + + #[test] + fn hostile() { + let data = fx::hello_class(); + let walk = |cf: &ClassFile| { + let _ = cf.name_dotted(); + for m in cf.methods.iter().chain(&cf.fields) { + let _ = cf.method_signature(m); + if let Some(code) = &m.code { + let (ins, _) = java_ops::decode(&code.bytecode, 10_000); + for i in &ins { + let _ = cf.format_insn(i); + } + } + } + let _ = references(cf, "java/lang/System", None, 100); + }; + for m in crate::test_support::mutations(&data) { + if let Ok(cf) = parse(&m) { + walk(&cf); + } + } + for len in 0..data.len() { + if let Ok(cf) = parse(&data[..len]) { + walk(&cf); + } + } + for seed in 0..64 { + let mut n = crate::test_support::noise(seed, 2048); + n[..4].copy_from_slice(&[0xca, 0xfe, 0xba, 0xbe]); + n[6] = 0; + n[7] = 52; + if let Ok(cf) = parse(&n) { + walk(&cf); + } + } + } +} diff --git a/crates/java-class/src/java_ops.rs b/crates/java-class/src/java_ops.rs new file mode 100644 index 000000000..46e5cdf30 --- /dev/null +++ b/crates/java-class/src/java_ops.rs @@ -0,0 +1,711 @@ +//! JVM bytecode: the opcode table (every defined opcode plus the `wide`, `tableswitch` and +//! `lookupswitch` variable-length forms) and a decoder for each instruction. Pure decoding; +//! constant-pool index operands are resolved by the caller (see [`crate::java_class`]). + +use serde::Serialize; + +/// The shape of an opcode's operands. +#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize)] +pub enum Operands { + /// No operands. + None, + /// One signed byte immediate (`bipush`). + Byte, + /// One signed short immediate (`sipush`). + Short, + /// A one-byte local-variable index. + Local, + /// `iinc`: a one-byte local index and a signed byte increment. + LocalConst, + /// A two-byte signed branch offset. + Branch2, + /// A four-byte signed branch offset (`goto_w`, `jsr_w`). + Branch4, + /// A one-byte constant-pool index (`ldc`). + Cp1, + /// A two-byte constant-pool index. + Cp2, + /// `newarray`: a one-byte primitive array type. + NewArray, + /// `invokeinterface`: a two-byte index, a count byte and a zero byte. + InvokeInterface, + /// `invokedynamic`: a two-byte index and two zero bytes. + InvokeDynamic, + /// `multianewarray`: a two-byte class index and a dimension byte. + MultiANewArray, + /// `tableswitch` (variable length, 4-byte aligned). + TableSwitch, + /// `lookupswitch` (variable length, 4-byte aligned). + LookupSwitch, + /// `wide`: a prefix that widens the following load/store/ret/iinc. + Wide, + /// A reserved or unknown opcode. + Reserved, +} + +/// One opcode slot. +#[derive(Debug, Clone, Copy)] +pub struct Op { + pub name: &'static str, + pub operands: Operands, +} + +const fn op(name: &'static str, operands: Operands) -> Op { + Op { name, operands } +} + +/// The opcode table entry for `b`. +pub fn opcode(b: u8) -> Op { + use Operands as O; + match b { + 0x00 => op("nop", O::None), + 0x01 => op("aconst_null", O::None), + 0x02 => op("iconst_m1", O::None), + 0x03 => op("iconst_0", O::None), + 0x04 => op("iconst_1", O::None), + 0x05 => op("iconst_2", O::None), + 0x06 => op("iconst_3", O::None), + 0x07 => op("iconst_4", O::None), + 0x08 => op("iconst_5", O::None), + 0x09 => op("lconst_0", O::None), + 0x0a => op("lconst_1", O::None), + 0x0b => op("fconst_0", O::None), + 0x0c => op("fconst_1", O::None), + 0x0d => op("fconst_2", O::None), + 0x0e => op("dconst_0", O::None), + 0x0f => op("dconst_1", O::None), + 0x10 => op("bipush", O::Byte), + 0x11 => op("sipush", O::Short), + 0x12 => op("ldc", O::Cp1), + 0x13 => op("ldc_w", O::Cp2), + 0x14 => op("ldc2_w", O::Cp2), + 0x15 => op("iload", O::Local), + 0x16 => op("lload", O::Local), + 0x17 => op("fload", O::Local), + 0x18 => op("dload", O::Local), + 0x19 => op("aload", O::Local), + 0x1a => op("iload_0", O::None), + 0x1b => op("iload_1", O::None), + 0x1c => op("iload_2", O::None), + 0x1d => op("iload_3", O::None), + 0x1e => op("lload_0", O::None), + 0x1f => op("lload_1", O::None), + 0x20 => op("lload_2", O::None), + 0x21 => op("lload_3", O::None), + 0x22 => op("fload_0", O::None), + 0x23 => op("fload_1", O::None), + 0x24 => op("fload_2", O::None), + 0x25 => op("fload_3", O::None), + 0x26 => op("dload_0", O::None), + 0x27 => op("dload_1", O::None), + 0x28 => op("dload_2", O::None), + 0x29 => op("dload_3", O::None), + 0x2a => op("aload_0", O::None), + 0x2b => op("aload_1", O::None), + 0x2c => op("aload_2", O::None), + 0x2d => op("aload_3", O::None), + 0x2e => op("iaload", O::None), + 0x2f => op("laload", O::None), + 0x30 => op("faload", O::None), + 0x31 => op("daload", O::None), + 0x32 => op("aaload", O::None), + 0x33 => op("baload", O::None), + 0x34 => op("caload", O::None), + 0x35 => op("saload", O::None), + 0x36 => op("istore", O::Local), + 0x37 => op("lstore", O::Local), + 0x38 => op("fstore", O::Local), + 0x39 => op("dstore", O::Local), + 0x3a => op("astore", O::Local), + 0x3b => op("istore_0", O::None), + 0x3c => op("istore_1", O::None), + 0x3d => op("istore_2", O::None), + 0x3e => op("istore_3", O::None), + 0x3f => op("lstore_0", O::None), + 0x40 => op("lstore_1", O::None), + 0x41 => op("lstore_2", O::None), + 0x42 => op("lstore_3", O::None), + 0x43 => op("fstore_0", O::None), + 0x44 => op("fstore_1", O::None), + 0x45 => op("fstore_2", O::None), + 0x46 => op("fstore_3", O::None), + 0x47 => op("dstore_0", O::None), + 0x48 => op("dstore_1", O::None), + 0x49 => op("dstore_2", O::None), + 0x4a => op("dstore_3", O::None), + 0x4b => op("astore_0", O::None), + 0x4c => op("astore_1", O::None), + 0x4d => op("astore_2", O::None), + 0x4e => op("astore_3", O::None), + 0x4f => op("iastore", O::None), + 0x50 => op("lastore", O::None), + 0x51 => op("fastore", O::None), + 0x52 => op("dastore", O::None), + 0x53 => op("aastore", O::None), + 0x54 => op("bastore", O::None), + 0x55 => op("castore", O::None), + 0x56 => op("sastore", O::None), + 0x57 => op("pop", O::None), + 0x58 => op("pop2", O::None), + 0x59 => op("dup", O::None), + 0x5a => op("dup_x1", O::None), + 0x5b => op("dup_x2", O::None), + 0x5c => op("dup2", O::None), + 0x5d => op("dup2_x1", O::None), + 0x5e => op("dup2_x2", O::None), + 0x5f => op("swap", O::None), + 0x60 => op("iadd", O::None), + 0x61 => op("ladd", O::None), + 0x62 => op("fadd", O::None), + 0x63 => op("dadd", O::None), + 0x64 => op("isub", O::None), + 0x65 => op("lsub", O::None), + 0x66 => op("fsub", O::None), + 0x67 => op("dsub", O::None), + 0x68 => op("imul", O::None), + 0x69 => op("lmul", O::None), + 0x6a => op("fmul", O::None), + 0x6b => op("dmul", O::None), + 0x6c => op("idiv", O::None), + 0x6d => op("ldiv", O::None), + 0x6e => op("fdiv", O::None), + 0x6f => op("ddiv", O::None), + 0x70 => op("irem", O::None), + 0x71 => op("lrem", O::None), + 0x72 => op("frem", O::None), + 0x73 => op("drem", O::None), + 0x74 => op("ineg", O::None), + 0x75 => op("lneg", O::None), + 0x76 => op("fneg", O::None), + 0x77 => op("dneg", O::None), + 0x78 => op("ishl", O::None), + 0x79 => op("lshl", O::None), + 0x7a => op("ishr", O::None), + 0x7b => op("lshr", O::None), + 0x7c => op("iushr", O::None), + 0x7d => op("lushr", O::None), + 0x7e => op("iand", O::None), + 0x7f => op("land", O::None), + 0x80 => op("ior", O::None), + 0x81 => op("lor", O::None), + 0x82 => op("ixor", O::None), + 0x83 => op("lxor", O::None), + 0x84 => op("iinc", O::LocalConst), + 0x85 => op("i2l", O::None), + 0x86 => op("i2f", O::None), + 0x87 => op("i2d", O::None), + 0x88 => op("l2i", O::None), + 0x89 => op("l2f", O::None), + 0x8a => op("l2d", O::None), + 0x8b => op("f2i", O::None), + 0x8c => op("f2l", O::None), + 0x8d => op("f2d", O::None), + 0x8e => op("d2i", O::None), + 0x8f => op("d2l", O::None), + 0x90 => op("d2f", O::None), + 0x91 => op("i2b", O::None), + 0x92 => op("i2c", O::None), + 0x93 => op("i2s", O::None), + 0x94 => op("lcmp", O::None), + 0x95 => op("fcmpl", O::None), + 0x96 => op("fcmpg", O::None), + 0x97 => op("dcmpl", O::None), + 0x98 => op("dcmpg", O::None), + 0x99 => op("ifeq", O::Branch2), + 0x9a => op("ifne", O::Branch2), + 0x9b => op("iflt", O::Branch2), + 0x9c => op("ifge", O::Branch2), + 0x9d => op("ifgt", O::Branch2), + 0x9e => op("ifle", O::Branch2), + 0x9f => op("if_icmpeq", O::Branch2), + 0xa0 => op("if_icmpne", O::Branch2), + 0xa1 => op("if_icmplt", O::Branch2), + 0xa2 => op("if_icmpge", O::Branch2), + 0xa3 => op("if_icmpgt", O::Branch2), + 0xa4 => op("if_icmple", O::Branch2), + 0xa5 => op("if_acmpeq", O::Branch2), + 0xa6 => op("if_acmpne", O::Branch2), + 0xa7 => op("goto", O::Branch2), + 0xa8 => op("jsr", O::Branch2), + 0xa9 => op("ret", O::Local), + 0xaa => op("tableswitch", O::TableSwitch), + 0xab => op("lookupswitch", O::LookupSwitch), + 0xac => op("ireturn", O::None), + 0xad => op("lreturn", O::None), + 0xae => op("freturn", O::None), + 0xaf => op("dreturn", O::None), + 0xb0 => op("areturn", O::None), + 0xb1 => op("return", O::None), + 0xb2 => op("getstatic", O::Cp2), + 0xb3 => op("putstatic", O::Cp2), + 0xb4 => op("getfield", O::Cp2), + 0xb5 => op("putfield", O::Cp2), + 0xb6 => op("invokevirtual", O::Cp2), + 0xb7 => op("invokespecial", O::Cp2), + 0xb8 => op("invokestatic", O::Cp2), + 0xb9 => op("invokeinterface", O::InvokeInterface), + 0xba => op("invokedynamic", O::InvokeDynamic), + 0xbb => op("new", O::Cp2), + 0xbc => op("newarray", O::NewArray), + 0xbd => op("anewarray", O::Cp2), + 0xbe => op("arraylength", O::None), + 0xbf => op("athrow", O::None), + 0xc0 => op("checkcast", O::Cp2), + 0xc1 => op("instanceof", O::Cp2), + 0xc2 => op("monitorenter", O::None), + 0xc3 => op("monitorexit", O::None), + 0xc4 => op("wide", O::Wide), + 0xc5 => op("multianewarray", O::MultiANewArray), + 0xc6 => op("ifnull", O::Branch2), + 0xc7 => op("ifnonnull", O::Branch2), + 0xc8 => op("goto_w", O::Branch4), + 0xc9 => op("jsr_w", O::Branch4), + 0xca => op("breakpoint", O::None), + 0xfe => op("impdep1", O::None), + 0xff => op("impdep2", O::None), + _ => op("unknown", O::Reserved), + } +} + +/// The primitive array type for a `newarray` atype operand. +pub fn array_type(atype: i32) -> &'static str { + match atype { + 4 => "boolean", + 5 => "char", + 6 => "float", + 7 => "double", + 8 => "byte", + 9 => "short", + 10 => "int", + 11 => "long", + _ => "?", + } +} + +/// A decoded `tableswitch`/`lookupswitch`. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct Switch { + /// Absolute byte offset of the default branch. + pub default: i64, + /// `(key, absolute target)` pairs in listing order. + pub pairs: Vec<(i32, i64)>, +} + +/// One decoded instruction. +#[derive(Debug, Clone, PartialEq, Eq, Serialize)] +pub struct Insn { + /// Byte offset from the start of the method's code. + pub pc: u32, + pub opcode: u8, + pub name: &'static str, + /// Total length in bytes, including operands. + pub len: u32, + /// Local-variable index operand (load/store/ret/iinc). + #[serde(skip_serializing_if = "Option::is_none")] + pub local: Option, + /// Integer immediate (`bipush`/`sipush`/`iinc` increment/`newarray` type/`multianewarray` dims). + #[serde(skip_serializing_if = "Option::is_none")] + pub int: Option, + /// Constant-pool index operand (resolved by the caller). + #[serde(skip_serializing_if = "Option::is_none")] + pub cp_index: Option, + /// Absolute byte offset of a branch target. + #[serde(skip_serializing_if = "Option::is_none")] + pub branch: Option, + /// A switch table when the opcode is `tableswitch`/`lookupswitch`. + #[serde(skip_serializing_if = "Option::is_none")] + pub switch: Option, + /// True when this instruction was prefixed by `wide`. + #[serde(skip_serializing_if = "std::ops::Not::not")] + pub wide: bool, +} + +/// Most entries decoded from one switch table. +const MAX_SWITCH: usize = 1 << 20; + +fn s8(code: &[u8], at: usize) -> Option { + code.get(at).map(|&b| i32::from(b as i8)) +} +fn u16b(code: &[u8], at: usize) -> Option { + Some(u16::from(*code.get(at)?) << 8 | u16::from(*code.get(at + 1)?)) +} +fn s16(code: &[u8], at: usize) -> Option { + u16b(code, at).map(|v| i32::from(v as i16)) +} +fn s32(code: &[u8], at: usize) -> Option { + Some(i32::from(*code.get(at)?) << 24 | i32::from(*code.get(at + 1)?) << 16 | i32::from(*code.get(at + 2)?) << 8 | i32::from(*code.get(at + 3)?)) +} + +fn base(pc: usize, opcode: u8, name: &'static str) -> Insn { + Insn { pc: pc as u32, opcode, name, len: 1, local: None, int: None, cp_index: None, branch: None, switch: None, wide: false } +} + +/// Decode one instruction at `pc`, or `None` for invalid or incomplete operands. +pub fn decode_one(code: &[u8], pc: usize) -> Option { + let b = *code.get(pc)?; + let o = opcode(b); + let mut insn = base(pc, b, o.name); + let rel = |d: i32| pc as i64 + i64::from(d); + match o.operands { + Operands::None | Operands::Reserved => {} + Operands::Byte => { + insn.int = Some(s8(code, pc + 1)?); + insn.len = 2; + } + Operands::Short => { + insn.int = Some(s16(code, pc + 1)?); + insn.len = 3; + } + Operands::Local => { + insn.local = Some(u16::from(*code.get(pc + 1)?)); + insn.len = 2; + } + Operands::LocalConst => { + insn.local = Some(u16::from(*code.get(pc + 1)?)); + insn.int = Some(s8(code, pc + 2)?); + insn.len = 3; + } + Operands::Branch2 => { + insn.branch = Some(rel(s16(code, pc + 1)?)); + insn.len = 3; + } + Operands::Branch4 => { + insn.branch = Some(rel(s32(code, pc + 1)?)); + insn.len = 5; + } + Operands::Cp1 => { + insn.cp_index = Some(u16::from(*code.get(pc + 1)?)); + insn.len = 2; + } + Operands::Cp2 => { + insn.cp_index = Some(u16b(code, pc + 1)?); + insn.len = 3; + } + Operands::NewArray => { + let atype = *code.get(pc + 1)?; + if !(4..=11).contains(&atype) { + return None; + } + insn.int = Some(i32::from(atype)); + insn.len = 2; + } + Operands::InvokeInterface => { + insn.cp_index = Some(u16b(code, pc + 1)?); + if *code.get(pc + 3)? == 0 || *code.get(pc + 4)? != 0 { + return None; + } + insn.len = 5; + } + Operands::InvokeDynamic => { + insn.cp_index = Some(u16b(code, pc + 1)?); + if *code.get(pc + 3)? != 0 || *code.get(pc + 4)? != 0 { + return None; + } + insn.len = 5; + } + Operands::MultiANewArray => { + insn.cp_index = Some(u16b(code, pc + 1)?); + let dimensions = *code.get(pc + 3)?; + if dimensions == 0 { + return None; + } + insn.int = Some(i32::from(dimensions)); + insn.len = 4; + } + Operands::Wide => return decode_wide(code, pc), + Operands::TableSwitch => return decode_tableswitch(code, pc), + Operands::LookupSwitch => return decode_lookupswitch(code, pc), + } + if pc.checked_add(insn.len as usize)? > code.len() { + return None; + } + Some(insn) +} + +fn decode_wide(code: &[u8], pc: usize) -> Option { + let real = *code.get(pc + 1)?; + if !matches!(real, 0x15..=0x19 | 0x36..=0x3a | 0x84 | 0xa9) { + return None; + } + let o = opcode(real); + let mut insn = base(pc, real, o.name); + insn.wide = true; + if real == 0x84 { + // wide iinc: 2-byte local, 2-byte signed const + insn.local = Some(u16b(code, pc + 2)?); + insn.int = Some(s16(code, pc + 4)?); + insn.len = 6; + } else { + // wide load/store/ret: 2-byte local + insn.local = Some(u16b(code, pc + 2)?); + insn.len = 4; + } + if pc.checked_add(insn.len as usize)? > code.len() { + return None; + } + Some(insn) +} + +/// Padding so the operand word after a switch opcode is 4-byte aligned from the code start. +fn switch_pad(pc: usize) -> usize { + (4 - ((pc + 1) % 4)) % 4 +} + +fn decode_tableswitch(code: &[u8], pc: usize) -> Option { + let mut at = pc + 1 + switch_pad(pc); + let default = rel_i64(pc, s32(code, at)?); + let low = s32(code, at + 4)?; + let high = s32(code, at + 8)?; + at += 12; + if high < low { + return None; + } + let count = usize::try_from(i64::from(high) - i64::from(low) + 1).ok()?; + if count > MAX_SWITCH { + return None; + } + let end = at.checked_add(count.checked_mul(4)?)?; + code.get(at..end)?; + let mut pairs = Vec::with_capacity(count); + for i in 0..count { + let off = s32(code, at + i * 4)?; + pairs.push((low.wrapping_add(i as i32), rel_i64(pc, off))); + } + let mut insn = base(pc, 0xaa, "tableswitch"); + insn.switch = Some(Switch { default, pairs }); + insn.len = (end - pc) as u32; + Some(insn) +} + +fn decode_lookupswitch(code: &[u8], pc: usize) -> Option { + let mut at = pc + 1 + switch_pad(pc); + let default = rel_i64(pc, s32(code, at)?); + let npairs = s32(code, at + 4)?; + at += 8; + if npairs < 0 { + return None; + } + let count = npairs as usize; + if count > MAX_SWITCH { + return None; + } + let end = at.checked_add(count.checked_mul(8)?)?; + code.get(at..end)?; + let mut pairs = Vec::with_capacity(count); + let mut previous = None; + for i in 0..count { + let key = s32(code, at + i * 8)?; + if previous.is_some_and(|previous| key <= previous) { + return None; + } + previous = Some(key); + let off = s32(code, at + i * 8 + 4)?; + pairs.push((key, rel_i64(pc, off))); + } + let mut insn = base(pc, 0xab, "lookupswitch"); + insn.switch = Some(Switch { default, pairs }); + insn.len = (end - pc) as u32; + Some(insn) +} + +fn rel_i64(pc: usize, off: i32) -> i64 { + pc as i64 + i64::from(off) +} + +/// Decode a whole method body, stopping at `max` instructions. `complete` is false when a +/// instruction has invalid/incomplete operands or the cap was hit. +pub fn decode(code: &[u8], max: usize) -> (Vec, bool) { + let mut out = Vec::new(); + let mut pc = 0usize; + let mut complete = true; + while pc < code.len() { + if out.len() >= max { + complete = false; + break; + } + match decode_one(code, pc) { + Some(i) => { + pc += (i.len as usize).max(1); + out.push(i); + } + None => { + complete = false; + break; + } + } + } + (out, complete) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn lookup(pc: usize, keys: &[i32]) -> Vec { + let mut code = vec![0; pc]; + code.push(0xab); + while !code.len().is_multiple_of(4) { + code.push(0); + } + code.extend_from_slice(&0i32.to_be_bytes()); + code.extend_from_slice(&(keys.len() as i32).to_be_bytes()); + for key in keys { + code.extend_from_slice(&key.to_be_bytes()); + code.extend_from_slice(&0i32.to_be_bytes()); + } + code + } + + #[test] + fn lookup_keys_must_increase_strictly() { + for keys in [&[1, 1][..], &[1, 0], &[0, -1], &[i32::MIN, i32::MAX, i32::MIN]] { + for pc in 0..4 { + let mut code = lookup(pc, keys); + code.push(0xb1); + assert!(decode_one(&code, pc).is_none(), "pc {pc}, keys {keys:?}"); + let (decoded, complete) = decode(&code, 100); + assert!(!complete); + assert_eq!(decoded.len(), pc, "preserve preceding nops, stop before the bad switch"); + } + } + } + + #[test] + fn lookup_keys_use_signed_order_at_every_alignment() { + for keys in [&[][..], &[i32::MIN, -1, 0, i32::MAX]] { + for pc in 0..4 { + let code = lookup(pc, keys); + let insn = decode_one(&code, pc).unwrap(); + assert_eq!(insn.len as usize, code.len() - pc); + let switch = insn.switch.unwrap(); + assert_eq!(switch.default, pc as i64); + assert_eq!(switch.pairs, keys.iter().map(|&key| (key, pc as i64)).collect::>()); + assert!(decode(&code, 100).1); + } + } + } + + #[test] + fn switch_payloads_must_be_complete() { + for pc in 0..4 { + let lookup = lookup(pc, &[-1, 1]); + let mut dense = vec![0; pc]; + dense.push(0xaa); + while !dense.len().is_multiple_of(4) { + dense.push(0); + } + for word in [0i32, i32::MAX - 1, i32::MAX, 0, 0] { + dense.extend_from_slice(&word.to_be_bytes()); + } + for code in [lookup, dense] { + assert!(decode_one(&code, pc).is_some()); + for end in pc + 1..code.len() { + assert!(decode_one(&code[..end], pc).is_none(), "pc {pc}, end {end}"); + } + } + } + } + + #[test] + fn switch_counts_cannot_reserve_an_absent_table() { + let mut lookup = lookup(0, &[]); + lookup[8..12].copy_from_slice(&(MAX_SWITCH as i32).to_be_bytes()); + assert!(decode_one(&lookup, 0).is_none()); + for (low, high) in [(0i32, MAX_SWITCH as i32 - 1), (i32::MIN, i32::MAX)] { + let mut dense = vec![0xaa, 0, 0, 0]; + for word in [0, low, high] { + dense.extend_from_slice(&word.to_be_bytes()); + } + assert!(decode_one(&dense, 0).is_none()); + } + } + + #[test] + fn table_covers_defined_opcodes() { + let mut named = 0; + for b in 0..=255u8 { + if opcode(b).name != "unknown" { + named += 1; + } + } + // 0x00..=0xca is 203 opcodes, plus impdep1/impdep2. + assert_eq!(named, 203 + 2); + assert_eq!(opcode(0xb6).name, "invokevirtual"); + assert_eq!(opcode(0x10).name, "bipush"); + assert_eq!(opcode(0xc4).name, "wide"); + } + + #[test] + fn decodes_core_formats() { + // iconst_1; bipush 7; istore_1; goto +3 ; (pad to reach len) return + let code = [0x04, 0x10, 0x07, 0x3c, 0xa7, 0x00, 0x03, 0xb1]; + let (ins, complete) = decode(&code, 100); + assert!(complete, "{ins:?}"); + assert_eq!(ins[0].name, "iconst_1"); + assert_eq!(ins[1].name, "bipush"); + assert_eq!(ins[1].int, Some(7)); + assert_eq!(ins[2].name, "istore_1"); + assert_eq!(ins[3].name, "goto"); + assert_eq!(ins[3].branch, Some(7)); // pc 4 + 3 + assert_eq!(ins[4].name, "return"); + } + + #[test] + fn decodes_invoke_and_wide() { + // invokevirtual #5 ; invokeinterface #6 count 2 ; wide iload 300 + let code = [0xb6, 0x00, 0x05, 0xb9, 0x00, 0x06, 0x02, 0x00, 0xc4, 0x15, 0x01, 0x2c]; + let (ins, complete) = decode(&code, 100); + assert!(complete); + assert_eq!(ins[0].name, "invokevirtual"); + assert_eq!(ins[0].cp_index, Some(5)); + assert_eq!(ins[0].len, 3); + assert_eq!(ins[1].name, "invokeinterface"); + assert_eq!(ins[1].cp_index, Some(6)); + assert_eq!(ins[1].len, 5); + assert_eq!(ins[2].name, "iload"); + assert!(ins[2].wide); + assert_eq!(ins[2].local, Some(300)); + assert_eq!(ins[2].len, 4); + } + + #[test] + fn decodes_switches() { + // tableswitch at pc 0: pad 3, default +40, low 1, high 2, offsets +10, +20 + let mut code = vec![0xaa, 0, 0, 0]; + code.extend_from_slice(&40i32.to_be_bytes()); + code.extend_from_slice(&1i32.to_be_bytes()); + code.extend_from_slice(&2i32.to_be_bytes()); + code.extend_from_slice(&10i32.to_be_bytes()); + code.extend_from_slice(&20i32.to_be_bytes()); + let i = decode_one(&code, 0).unwrap(); + assert_eq!(i.name, "tableswitch"); + let sw = i.switch.unwrap(); + assert_eq!(sw.default, 40); + assert_eq!(sw.pairs, vec![(1, 10), (2, 20)]); + assert_eq!(i.len as usize, code.len()); + + // lookupswitch at pc 0: pad 3, default +4, npairs 1, (key 99 -> +8) + let mut lk = vec![0xab, 0, 0, 0]; + lk.extend_from_slice(&4i32.to_be_bytes()); + lk.extend_from_slice(&1i32.to_be_bytes()); + lk.extend_from_slice(&99i32.to_be_bytes()); + lk.extend_from_slice(&8i32.to_be_bytes()); + let l = decode_one(&lk, 0).unwrap(); + let sw = l.switch.unwrap(); + assert_eq!(sw.default, 4); + assert_eq!(sw.pairs, vec![(99, 8)]); + } + + #[test] + fn hostile() { + for seed in 0..256 { + let n = crate::test_support::noise(seed, 512); + let _ = decode(&n, 10_000); + } + // truncated operands never panic + let _ = decode(&[0xb6, 0x00], 10); + let _ = decode(&[0xaa, 0, 0, 0, 0, 0, 0, 0], 10); + let _ = decode(&[0xab, 0, 0, 0, 0, 0, 0, 0, 0x7f, 0xff, 0xff, 0xff], 10); + let _ = decode(&[0xc4], 10); + } +} diff --git a/crates/java-class/src/lib.rs b/crates/java-class/src/lib.rs new file mode 100644 index 000000000..4d135e16b --- /dev/null +++ b/crates/java-class/src/lib.rs @@ -0,0 +1,50 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +#![forbid(unsafe_code)] +//! Java class-file inspection and JVM bytecode decoding. Never executes bytecode. +//! Retains source item, attribute and annotation-depth limits and partial reports. +mod bytes; +mod descriptor; +pub mod java_class; +pub mod java_ops; +pub use java_class::*; +#[cfg(test)] +mod test_support; +/// File admission errors; damaged optional structures retain partial-report warnings. +#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)] +pub enum JavaClassError { + #[error("the file ends early ({0})")] + Truncated(String), + #[error("the file is malformed ({0})")] + Malformed(String), + #[error("not supported: {0}")] + Unsupported(String), +} +use JavaClassError as FormatError; + +#[cfg(test)] +#[path = "regressions/java_array_operands.rs"] +mod java_array_operands; + +#[cfg(test)] +#[path = "regressions/java_attribute_names.rs"] +mod java_attribute_names; + +#[cfg(test)] +#[path = "regressions/java_constant_pool_slots.rs"] +mod java_constant_pool_slots; + +#[cfg(test)] +#[path = "regressions/java_invoke_operands.rs"] +mod java_invoke_operands; + +#[cfg(test)] +#[path = "regressions/java_linkage_references.rs"] +mod java_linkage_references; + +#[cfg(test)] +#[path = "regressions/java_truncated_attributes.rs"] +mod java_truncated_attributes; + +#[cfg(test)] +#[path = "regressions/java_wide_opcodes.rs"] +mod java_wide_opcodes; diff --git a/crates/java-class/src/regressions/java_array_operands.rs b/crates/java-class/src/regressions/java_array_operands.rs new file mode 100644 index 000000000..b5867db52 --- /dev/null +++ b/crates/java-class/src/regressions/java_array_operands.rs @@ -0,0 +1,48 @@ +use crate::java_ops::{decode, decode_one}; + +#[test] +fn invalid_primitive_array_types_stop_before_the_allocation() { + for atype in (0..=u8::MAX).filter(|value| !(4..=11).contains(value)) { + assert!(decode_one(&[0xbc, atype], 0).is_none(), "atype {atype}"); + let (instructions, complete) = decode(&[0, 0xbc, atype, 0xb1], 100); + assert!(!complete, "atype {atype}"); + assert_eq!(instructions.len(), 1); + assert_eq!(instructions[0].name, "nop"); + } +} + +#[test] +fn zero_dimension_multidimensional_allocations_are_not_complete_bytecode() { + assert!(decode_one(&[0xc5, 0, 1, 0], 0).is_none()); + let (instructions, complete) = decode(&[0, 0xc5, 0, 1, 0, 0xb1], 100); + assert!(!complete); + assert_eq!(instructions.len(), 1); + assert_eq!(instructions[0].name, "nop"); +} + +#[test] +fn every_defined_primitive_type_and_nonzero_dimension_remains_decodable() { + for atype in 4..=11 { + let (instructions, complete) = decode(&[0xbc, atype, 0xb1], 100); + assert!(complete); + assert_eq!(instructions.len(), 2); + assert_eq!(instructions[0].int, Some(i32::from(atype))); + assert_eq!(instructions[0].len, 2); + } + for dimensions in 1..=u8::MAX { + let instruction = decode_one(&[0, 0xc5, 0x12, 0x34, dimensions], 1).unwrap(); + assert_eq!(instruction.pc, 1); + assert_eq!(instruction.cp_index, Some(0x1234)); + assert_eq!(instruction.int, Some(i32::from(dimensions))); + assert_eq!(instruction.len, 4); + } +} + +#[test] +fn incomplete_array_operands_remain_rejected() { + for instruction in [&[0xbc, 10][..], &[0xc5, 0, 1, 2][..]] { + for end in 1..instruction.len() { + assert!(decode_one(&instruction[..end], 0).is_none()); + } + } +} diff --git a/crates/java-class/src/regressions/java_attribute_names.rs b/crates/java-class/src/regressions/java_attribute_names.rs new file mode 100644 index 000000000..c506ed0c9 --- /dev/null +++ b/crates/java-class/src/regressions/java_attribute_names.rs @@ -0,0 +1,132 @@ +use crate::java_class::{self, ClassFile, Const}; + +#[derive(Clone, Copy, Debug)] +enum Scope { + Class, + Field, + Method, + Code, +} + +fn u16b(out: &mut Vec, n: u16) { + out.extend_from_slice(&n.to_be_bytes()); +} + +fn u32b(out: &mut Vec, n: u32) { + out.extend_from_slice(&n.to_be_bytes()); +} + +fn utf8(out: &mut Vec, text: &str) { + out.push(1); + u16b(out, text.len() as u16); + out.extend_from_slice(text.as_bytes()); +} + +fn attr(name: u16, info: &[u8]) -> Vec { + let mut out = Vec::new(); + u16b(&mut out, name); + u32b(&mut out, info.len() as u32); + out.extend_from_slice(info); + out +} + +fn attributes(out: &mut Vec, repeated: u16, known: &[Vec]) { + u16b(out, repeated + known.len() as u16); + for _ in 0..repeated { + out.extend_from_slice(&attr(5, &[])); + } + for bytes in known { + out.extend_from_slice(bytes); + } +} + +// A valid shared CONSTANT_Utf8 is named by every unknown attribute. Known +// attributes follow it, so avoiding name copies must not discard their facts. +fn fixture(scope: Scope, repeated: u16) -> Vec { + let mut out = vec![0xca, 0xfe, 0xba, 0xbe, 0, 0, 0, 52]; + u16b(&mut out, 17); + utf8(&mut out, "AttributeFixture"); // 1 + out.push(7); + u16b(&mut out, 1); // 2: this class + utf8(&mut out, "java/lang/Object"); // 3 + out.push(7); + u16b(&mut out, 3); // 4: superclass + utf8(&mut out, &format!("org.example.{}", "A".repeat(usize::from(u16::MAX) - 12))); // 5 + for text in ["SourceFile", "AttributeFixture.java", "field", "I"] { + utf8(&mut out, text); // 6..9 + } + out.push(3); + u32b(&mut out, 42); // 10 + for text in ["ConstantValue", "run", "()V", "Code", "LineNumberTable", "Deprecated"] { + utf8(&mut out, text); // 11..16 + } + for word in [0x0021, 2, 4, 0, 1, 0x0019, 8, 9] { + u16b(&mut out, word); + } + attributes(&mut out, if matches!(scope, Scope::Field) { repeated } else { 0 }, &[attr(11, &10u16.to_be_bytes()), attr(16, &[])]); + for word in [1, 0x0009, 12, 13] { + u16b(&mut out, word); + } + let mut code = vec![0, 0, 0, 0, 0, 0, 0, 1, 0xb1, 0, 0]; + attributes(&mut code, if matches!(scope, Scope::Code) { repeated } else { 0 }, &[attr(15, &[0, 1, 0, 0, 0, 7])]); + attributes(&mut out, if matches!(scope, Scope::Method) { repeated } else { 0 }, &[attr(14, &code)]); + attributes(&mut out, if matches!(scope, Scope::Class) { repeated } else { 0 }, &[attr(6, &7u16.to_be_bytes())]); + out +} + +fn check_facts(parsed: &ClassFile) { + assert!(parsed.warnings.is_empty(), "{:?}", parsed.warnings); + assert_eq!(parsed.this_class, "AttributeFixture"); + assert_eq!(parsed.super_class.as_deref(), Some("java/lang/Object")); + assert_eq!(parsed.source_file.as_deref(), Some("AttributeFixture.java")); + assert_eq!(parsed.fields.len(), 1); + assert_eq!(parsed.fields[0].name, "field"); + assert_eq!(parsed.fields[0].constant_value.as_deref(), Some("42")); + assert!(parsed.fields[0].deprecated); + assert_eq!(parsed.methods.len(), 1); + assert_eq!(parsed.methods[0].name, "run"); + let code = parsed.methods[0].code.as_ref().unwrap(); + assert_eq!(code.bytecode, [0xb1]); + assert_eq!(code.line_numbers, [(0, 7)]); + assert!(matches!(&parsed.pool[5], Const::Utf8(name) if name.len() == usize::from(u16::MAX))); +} + +#[test] +fn known_attributes_survive_repeated_unknown_names_at_every_scope() { + for scope in [Scope::Class, Scope::Field, Scope::Method, Scope::Code] { + check_facts(&java_class::parse(&fixture(scope, 64)).unwrap()); + } +} + +fn memory_case(scope: Scope) { + let bytes = fixture(scope, 4096); + assert!(bytes.len() < 100_000); + check_facts(&java_class::parse(&bytes).unwrap()); +} + +// Run each ignored case separately with a 128 MiB process address-space limit. +// The original parser copies 256 MiB of one attribute name; the fixture itself +// is under 100 KiB. These checks deliberately make no timing assertion. +#[test] +#[ignore = "run separately under a process memory limit"] +fn repeated_class_attribute_names_fit_in_bounded_memory() { + memory_case(Scope::Class); +} + +#[test] +#[ignore = "run separately under a process memory limit"] +fn repeated_field_attribute_names_fit_in_bounded_memory() { + memory_case(Scope::Field); +} + +#[test] +#[ignore = "run separately under a process memory limit"] +fn repeated_method_attribute_names_fit_in_bounded_memory() { + memory_case(Scope::Method); +} + +#[test] +#[ignore = "run separately under a process memory limit"] +fn repeated_code_attribute_names_fit_in_bounded_memory() { + memory_case(Scope::Code); +} diff --git a/crates/java-class/src/regressions/java_constant_pool_slots.rs b/crates/java-class/src/regressions/java_constant_pool_slots.rs new file mode 100644 index 000000000..15ad88567 --- /dev/null +++ b/crates/java-class/src/regressions/java_constant_pool_slots.rs @@ -0,0 +1,53 @@ +use crate::{FormatError, java_class}; + +fn class_with_pool(count: u16, pool: &[u8]) -> Vec { + let mut bytes = vec![0xca, 0xfe, 0xba, 0xbe, 0, 0, 0, 52]; + bytes.extend_from_slice(&count.to_be_bytes()); + bytes.extend_from_slice(pool); + bytes.extend_from_slice(&[0; 14]); + bytes +} + +#[test] +fn a_wide_constant_needs_its_reserved_slot() { + for tag in [5, 6] { + let mut pool = vec![tag]; + pool.extend_from_slice(&[0; 8]); + let bytes = class_with_pool(2, &pool); + assert!(matches!(java_class::parse(&bytes), Err(FormatError::Malformed(message)) if message.contains("second slot"))); + } +} + +#[test] +fn the_largest_pool_cannot_overflow_on_a_trailing_wide_constant() { + for tag in [5, 6] { + let mut pool = [3, 0, 0, 0, 0].repeat(usize::from(u16::MAX) - 2); + pool.push(tag); + pool.extend_from_slice(&[0; 8]); + let bytes = class_with_pool(u16::MAX, &pool); + assert!(matches!(java_class::parse(&bytes), Err(FormatError::Malformed(message)) if message.contains("second slot"))); + } +} + +#[test] +fn a_wide_constant_with_two_remaining_slots_is_retained() { + for tag in [5, 6] { + for count in [3, u16::MAX] { + let mut pool = [3, 0, 0, 0, 0].repeat(usize::from(count) - 3); + pool.push(tag); + pool.extend_from_slice(&[0; 8]); + let parsed = java_class::parse(&class_with_pool(count, &pool)).unwrap(); + assert_eq!(parsed.pool.len(), usize::from(count)); + assert!(matches!(parsed.pool.last(), Some(java_class::Const::Unusable))); + assert!(matches!(parsed.pool[usize::from(count) - 2], java_class::Const::Long(_) | java_class::Const::Double(_))); + } + } +} + +#[test] +fn ordinary_final_constants_and_existing_classes_still_parse() { + let parsed = java_class::parse(&class_with_pool(2, &[3, 0, 0, 0, 7])).unwrap(); + assert_eq!(parsed.pool, vec![java_class::Const::Unusable, java_class::Const::Integer(7)]); + let parsed = java_class::parse(&crate::test_support::java::hello_class()).unwrap(); + assert!(!parsed.methods.is_empty()); +} diff --git a/crates/java-class/src/regressions/java_invoke_operands.rs b/crates/java-class/src/regressions/java_invoke_operands.rs new file mode 100644 index 000000000..a99d8803b --- /dev/null +++ b/crates/java-class/src/regressions/java_invoke_operands.rs @@ -0,0 +1,76 @@ +use crate::java_class; +use crate::java_ops::{decode, decode_one}; + +#[test] +fn invokeinterface_requires_a_count_and_zero_reserved_byte() { + for code in [[0xb9, 0, 1, 0, 0], [0xb9, 0, 1, 1, 1], [0xb9, 0, 1, 255, 255]] { + assert!(decode_one(&code, 0).is_none(), "{code:?}"); + assert!(!decode(&code, 16).1); + } +} + +#[test] +fn invokedynamic_requires_both_reserved_bytes_to_be_zero() { + for code in [[0xba, 0, 1, 1, 0], [0xba, 0, 1, 0, 1], [0xba, 0, 1, 255, 255]] { + assert!(decode_one(&code, 0).is_none(), "{code:?}"); + assert!(!decode(&code, 16).1); + } +} + +#[test] +fn valid_and_truncated_invocations_keep_their_boundaries() { + for count in [1, 2, 255] { + let instruction = decode_one(&[0xb9, 0x12, 0x34, count, 0], 0).unwrap(); + assert_eq!(instruction.cp_index, Some(0x1234)); + assert_eq!(instruction.len, 5); + } + let instruction = decode_one(&[0xba, 0x12, 0x34, 0, 0], 0).unwrap(); + assert_eq!(instruction.cp_index, Some(0x1234)); + for code in [[0xb9, 0, 1, 1, 0], [0xba, 0, 1, 0, 0]] { + for len in 1..5 { + assert!(decode_one(&code[..len], 0).is_none()); + } + } + let (instructions, complete) = decode(&[0xb9, 0, 1, 1, 0, 0xba, 0, 2, 0, 0, 0xb1], 16); + assert!(complete); + assert_eq!(instructions.len(), 3); + assert_eq!(instructions[2].pc, 10); +} + +fn reference_class() -> java_class::ClassFile { + let mut class = java_class::parse(&crate::test_support::java::hello_class()).unwrap(); + class.methods.retain(|method| method.name == "run"); + class +} + +#[test] +fn malformed_invocations_mark_reference_scans_incomplete() { + let valid = reference_class(); + let (expected, incomplete) = java_class::references(&valid, "java/io/PrintStream", None, 10); + assert!(!incomplete); + assert_eq!(expected.len(), 1); + for invalid in [[0xb9, 0, 1, 0, 0], [0xb9, 0, 1, 1, 1], [0xba, 0, 1, 1, 0], [0xba, 0, 1, 0, 1]] { + let mut class = valid.clone(); + let code = &mut class.methods[0].code.as_mut().unwrap().bytecode; + let later_reference = code.clone(); + *code = invalid.to_vec(); + code.extend_from_slice(&later_reference); + let (found, incomplete) = java_class::references(&class, "java/io/PrintStream", None, 10); + assert!(found.is_empty()); + assert!(incomplete, "invalid invocation must not hide an unfinished reference scan: {invalid:?}"); + } +} + +#[test] +fn incomplete_scans_keep_earlier_references_and_scan_other_methods() { + let mut class = reference_class(); + let mut later_method = class.methods[0].clone(); + later_method.name = "later".into(); + class.methods[0].code.as_mut().unwrap().bytecode.extend_from_slice(&[0xba, 0, 1, 1, 0]); + class.methods.push(later_method); + let (found, incomplete) = java_class::references(&class, "java/io/PrintStream", None, 10); + assert!(incomplete); + assert_eq!(found.len(), 2); + assert!(found[0].caller.contains(".run:(")); + assert!(found[1].caller.contains(".later:(")); +} diff --git a/crates/java-class/src/regressions/java_linkage_references.rs b/crates/java-class/src/regressions/java_linkage_references.rs new file mode 100644 index 000000000..7c05abe94 --- /dev/null +++ b/crates/java-class/src/regressions/java_linkage_references.rs @@ -0,0 +1,97 @@ +use crate::java_class::{parse, references}; + +/// A method with a chosen load or call, plus a dynamic call site and a dynamic constant with distinct bootstrap signatures. +fn class(code: &[u8]) -> Vec { + fn utf(s: &str) -> Vec { + let mut b = vec![1]; + b.extend((s.len() as u16).to_be_bytes()); + b.extend(s.bytes()); + b + } + let pool = [ + utf("Uses"), + vec![7, 0, 1], + utf("java/lang/Object"), + vec![7, 0, 3], + utf("run"), + utf("()V"), + utf("Code"), + utf("BootstrapMethods"), + utf("Target"), + vec![7, 0, 9], + utf("apply"), + vec![12, 0, 11, 0, 6], + vec![10, 0, 10, 0, 12], + vec![15, 6, 0, 13], + utf("Factory"), + vec![7, 0, 15], + utf("boot"), + vec![12, 0, 17, 0, 28], + vec![10, 0, 16, 0, 18], + vec![15, 6, 0, 19], + utf("([LTarget;)V"), + vec![16, 0, 21], + vec![18, 0, 0, 0, 12], + utf("value"), + utf("I"), + vec![12, 0, 24, 0, 25], + vec![17, 0, 1, 0, 26], + utf( + "(Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/invoke/MethodType;Ljava/lang/invoke/MethodHandle;)Ljava/lang/invoke/CallSite;", + ), + utf("(Ljava/lang/invoke/MethodHandles$Lookup;Ljava/lang/String;Ljava/lang/Class;)I"), + vec![12, 0, 17, 0, 29], + vec![10, 0, 16, 0, 30], + vec![15, 6, 0, 31], + ]; + let mut bytes = vec![0xca, 0xfe, 0xba, 0xbe, 0, 0, 0, 55]; + bytes.extend((pool.len() as u16 + 1).to_be_bytes()); + for e in pool { + bytes.extend(e); + } + bytes.extend([0, 0x21, 0, 2, 0, 4, 0, 0, 0, 0, 0, 1, 0, 9, 0, 5, 0, 6, 0, 1, 0, 7]); + bytes.extend(((12 + code.len()) as u32).to_be_bytes()); + bytes.extend([0, 3, 0, 0]); + bytes.extend((code.len() as u32).to_be_bytes()); + bytes.extend(code); + bytes.extend([0, 0, 0, 0]); + let boots = [0, 2, 0, 20, 0, 1, 0, 14, 0, 32, 0, 0]; + bytes.extend([0, 1, 0, 8]); + bytes.extend((boots.len() as u32).to_be_bytes()); + bytes.extend(boots); + bytes +} +fn kinds(code: &[u8], owner: &str, method: Option<&str>) -> Vec<&'static str> { + let cf = parse(&class(code)).unwrap(); + let (hits, partial) = references(&cf, owner, method, 10); + assert!(!partial); + hits.into_iter().map(|r| r.kind).collect() +} +#[test] +fn class_literal_has_a_use_site() { + assert_eq!(kinds(&[0x12, 10, 0x57, 0xb1], "Target", None), ["type"]); +} +#[test] +fn literal_method_handle_finds_its_member() { + assert_eq!(kinds(&[0x12, 14, 0x57, 0xb1], "Target", Some("apply")), ["method-handle"]); +} +#[test] +fn method_type_mentions_object_array_components() { + assert_eq!(kinds(&[0x12, 22, 0x57, 0xb1], "Target", None), ["method-type"]); +} +#[test] +fn dynamic_call_exposes_factory_dependency() { + assert_eq!(kinds(&[0xba, 0, 23, 0, 0, 0xb1], "Factory", Some("boot")), ["bootstrap-method"]); +} +#[test] +fn dynamic_call_exposes_static_method_handle_argument() { + assert_eq!(kinds(&[0xba, 0, 23, 0, 0, 0xb1], "Target", Some("apply")), ["method-handle"]); +} +#[test] +fn dynamic_constant_exposes_bootstrap_dependency() { + assert_eq!(kinds(&[0x12, 27, 0x57, 0xb1], "Factory", Some("boot")), ["bootstrap-method"]); +} +#[test] +fn unused_bootstrap_does_not_introduce_a_reference() { + assert!(kinds(&[0xb1], "Factory", None).is_empty()); +} diff --git a/crates/java-class/src/regressions/java_truncated_attributes.rs b/crates/java-class/src/regressions/java_truncated_attributes.rs new file mode 100644 index 000000000..700640f33 --- /dev/null +++ b/crates/java-class/src/regressions/java_truncated_attributes.rs @@ -0,0 +1,46 @@ +use crate::java_class::parse; +use crate::test_support::java::hello_class; + +/// The fixture ends in a class attribute count and a single two-byte SourceFile attribute. +const ATTRIBUTE_TABLE_BYTES: usize = 10; + +/// Every cut of the attribute count, header or body leaves a partial class report. +#[test] +fn incomplete_class_attribute_table_reports_a_warning() { + let data = hello_class(); + let start = data.len() - ATTRIBUTE_TABLE_BYTES; + for end in start..data.len() { + let class = parse(&data[..end]).unwrap(); + assert_eq!(class.methods.len(), 4); + assert!(class.source_file.is_none()); + assert!(class.warnings.iter().any(|warning| warning.contains("class attribute table")), "cut at {}", end - start); + } +} + +/// A complete attribute stays available when a subsequent attribute is cut short. +#[test] +fn completed_class_attributes_survive_a_truncated_record() { + let mut data = hello_class(); + let start = data.len() - ATTRIBUTE_TABLE_BYTES; + data[start..start + 2].copy_from_slice(&2u16.to_be_bytes()); + data.extend_from_slice(&[0, 1, 0, 0, 0, 2, 0]); + let class = parse(&data).unwrap(); + assert_eq!(class.source_file.as_deref(), Some("Hello.java")); + assert!(class.warnings.iter().any(|warning| warning.contains("class attribute table"))); +} + +/// Complete, empty and unknown class attributes do not trigger a truncation warning. +#[test] +fn complete_class_attribute_tables_are_accepted() { + let mut data = hello_class(); + let start = data.len() - ATTRIBUTE_TABLE_BYTES; + let original = parse(&data).unwrap(); + assert_eq!(original.source_file.as_deref(), Some("Hello.java")); + assert!(original.warnings.is_empty()); + data[start..start + 2].copy_from_slice(&2u16.to_be_bytes()); + data.extend_from_slice(&[0, 1, 0, 0, 0, 1, 0]); + assert!(parse(&data).unwrap().warnings.is_empty()); + data.truncate(start + 2); + data[start..].fill(0); + assert!(parse(&data).unwrap().warnings.is_empty()); +} diff --git a/crates/java-class/src/regressions/java_wide_opcodes.rs b/crates/java-class/src/regressions/java_wide_opcodes.rs new file mode 100644 index 000000000..85c03ffaa --- /dev/null +++ b/crates/java-class/src/regressions/java_wide_opcodes.rs @@ -0,0 +1,33 @@ +use crate::java_ops::{decode, decode_one}; + +#[test] +fn only_defined_wide_opcodes_are_accepted() { + for op in 0..=255u8 { + let valid = matches!(op, 0x15..=0x19 | 0x36..=0x3a | 0x84 | 0xa9); + let code = [0xc4, op, 0x01, 0x2c, 0xff, 0xfe]; + assert_eq!(decode_one(&code, 0).is_some(), valid, "opcode {op:#x}"); + } +} + +#[test] +fn invalid_wide_does_not_invent_a_method_body() { + let (instructions, complete) = decode(&[0x00, 0xc4, 0xb1, 0, 1, 0xb1], 32); + assert!(!complete); + assert_eq!(instructions.len(), 1); + assert_eq!(instructions[0].name, "nop"); +} + +#[test] +fn wide_locals_and_signed_increments_are_preserved() { + for op in [0x15, 0x16, 0x17, 0x18, 0x19, 0x36, 0x37, 0x38, 0x39, 0x3a, 0xa9] { + let instruction = decode_one(&[0xc4, op, 0xff, 0xff], 0).unwrap(); + assert_eq!(instruction.local, Some(u16::MAX)); + assert_eq!(instruction.len, 4); + assert!(instruction.wide); + } + let instruction = decode_one(&[0xc4, 0x84, 0x01, 0x2c, 0xff, 0xfe], 0).unwrap(); + assert_eq!(instruction.local, Some(300)); + assert_eq!(instruction.int, Some(-2)); + assert_eq!(instruction.len, 6); + assert!(decode_one(&[0xc4, 0x84, 0x00, 1], 0).is_none()); +} diff --git a/crates/java-class/src/test_support.rs b/crates/java-class/src/test_support.rs new file mode 100644 index 000000000..45853e807 --- /dev/null +++ b/crates/java-class/src/test_support.rs @@ -0,0 +1,316 @@ +/// Deterministic pseudo-random bytes (xorshift) for fuzz-like loops. +pub fn noise(seed: u64, len: usize) -> Vec { + let mut x = seed.wrapping_mul(0x9e37_79b9_7f4a_7c15) | 1; + (0..len) + .map(|_| { + x ^= x << 13; + x ^= x >> 7; + x ^= x << 17; + x as u8 + }) + .collect() +} + +/// Every way to damage a sample used by robustness tests: truncations at many lengths and +/// single-byte corruptions spread across the file. +pub fn mutations(sample: &[u8]) -> Vec> { + let mut out = Vec::new(); + let n = sample.len(); + let step = (n / 64).max(1); + let mut len = 0; + while len < n { + out.push(sample[..len].to_vec()); + len += step; + } + for (i, seed) in (0..n).step_by(step).zip(1u64..) { + let mut m = sample.to_vec(); + let noise = noise(seed, 8); + for (j, v) in noise.iter().enumerate() { + if let Some(b) = m.get_mut(i + j) { + *b = *v; + } + } + out.push(m); + let mut m = sample.to_vec(); + if let Some(b) = m.get_mut(i) { + *b = 0xff; + } + out.push(m); + } + out +} + +pub mod java { + use std::collections::HashMap; + + /// A constant-pool builder that interns entries and tracks the double slot after `Long`/`Double`. + #[derive(Default)] + struct Pool { + items: Vec>, + /// Next free index (1-based; accounts for long/double taking two slots). + count: u16, + cache: HashMap, + } + + impl Pool { + fn new() -> Self { + Pool { items: Vec::new(), count: 1, cache: HashMap::new() } + } + fn add(&mut self, bytes: Vec, slots: u16) -> u16 { + let idx = self.count; + self.items.push(bytes); + self.count += slots; + idx + } + fn utf8(&mut self, s: &str) -> u16 { + let key = format!("u:{s}"); + if let Some(&i) = self.cache.get(&key) { + return i; + } + let mut b = vec![1u8]; + b.extend_from_slice(&(s.len() as u16).to_be_bytes()); + b.extend_from_slice(s.as_bytes()); + let i = self.add(b, 1); + self.cache.insert(key, i); + i + } + fn class(&mut self, name: &str) -> u16 { + let n = self.utf8(name); + let key = format!("c:{name}"); + if let Some(&i) = self.cache.get(&key) { + return i; + } + let mut b = vec![7u8]; + b.extend_from_slice(&n.to_be_bytes()); + let i = self.add(b, 1); + self.cache.insert(key, i); + i + } + fn string(&mut self, s: &str) -> u16 { + let u = self.utf8(s); + let mut b = vec![8u8]; + b.extend_from_slice(&u.to_be_bytes()); + self.add(b, 1) + } + fn nat(&mut self, name: &str, desc: &str) -> u16 { + let n = self.utf8(name); + let d = self.utf8(desc); + let mut b = vec![12u8]; + b.extend_from_slice(&n.to_be_bytes()); + b.extend_from_slice(&d.to_be_bytes()); + self.add(b, 1) + } + fn reff(&mut self, tag: u8, owner: &str, name: &str, desc: &str) -> u16 { + let c = self.class(owner); + let nt = self.nat(name, desc); + let mut b = vec![tag]; + b.extend_from_slice(&c.to_be_bytes()); + b.extend_from_slice(&nt.to_be_bytes()); + self.add(b, 1) + } + fn long(&mut self, v: i64) -> u16 { + let mut b = vec![5u8]; + b.extend_from_slice(&v.to_be_bytes()); + self.add(b, 2) + } + /// The serialized constant pool and the count field. + fn finish(&self) -> (Vec, u16) { + (self.items.concat(), self.count) + } + } + + fn u16b(v: &mut Vec, x: u16) { + v.extend_from_slice(&x.to_be_bytes()); + } + fn u32b(v: &mut Vec, x: u32) { + v.extend_from_slice(&x.to_be_bytes()); + } + + /// Build an attribute: name_index, length, body. + fn attr(name_idx: u16, body: Vec) -> Vec { + let mut v = Vec::new(); + u16b(&mut v, name_idx); + u32b(&mut v, body.len() as u32); + v.extend_from_slice(&body); + v + } + + /// A method's `Code` attribute body (max_stack, max_locals, code, exception table, no nested attrs). + fn code_body(max_stack: u16, max_locals: u16, code: &[u8], exc: &[(u16, u16, u16, u16)]) -> Vec { + let mut v = Vec::new(); + u16b(&mut v, max_stack); + u16b(&mut v, max_locals); + u32b(&mut v, code.len() as u32); + v.extend_from_slice(code); + u16b(&mut v, exc.len() as u16); + for (s, e, h, t) in exc { + u16b(&mut v, *s); + u16b(&mut v, *e); + u16b(&mut v, *h); + u16b(&mut v, *t); + } + u16b(&mut v, 0); // nested attributes count + v + } + + /// A method_info: access, name, descriptor, and one already-built Code attribute. + fn method(p: &mut Pool, access: u16, name: &str, desc: &str, code_attribute: Vec) -> Vec { + let name_idx = p.utf8(name); + let desc_idx = p.utf8(desc); + let mut v = Vec::new(); + u16b(&mut v, access); + u16b(&mut v, name_idx); + u16b(&mut v, desc_idx); + u16b(&mut v, 1); // one attribute + v.extend_from_slice(&code_attribute); + v + } + + /// Assemble a whole class from its parts. + #[allow(clippy::too_many_arguments)] + fn assemble( + pool: &Pool, + access: u16, + this_c: u16, + super_c: u16, + interfaces: &[u16], + fields: &[Vec], + methods: &[Vec], + class_attrs: &[Vec], + ) -> Vec { + let (cp, count) = pool.finish(); + let mut v = Vec::new(); + v.extend_from_slice(&[0xca, 0xfe, 0xba, 0xbe]); + u16b(&mut v, 0); // minor + u16b(&mut v, 52); // major (Java 8) + u16b(&mut v, count); + v.extend_from_slice(&cp); + u16b(&mut v, access); + u16b(&mut v, this_c); + u16b(&mut v, super_c); + u16b(&mut v, interfaces.len() as u16); + for i in interfaces { + u16b(&mut v, *i); + } + u16b(&mut v, fields.len() as u16); + for f in fields { + v.extend_from_slice(f); + } + u16b(&mut v, methods.len() as u16); + for m in methods { + v.extend_from_slice(m); + } + u16b(&mut v, class_attrs.len() as u16); + for a in class_attrs { + v.extend_from_slice(a); + } + v + } + + pub const HELLO: &str = "Hello, Craft!"; + + /// `public class com.example.Hello implements Runnable` with a `count` field, a `BIG` long + /// constant, ``, `run()` (System.out.println("Hello, Craft!")), `pick(int)` (a tableswitch) + /// and `guarded()` (a try/catch over the println call). + pub fn hello_class() -> Vec { + let mut p = Pool::new(); + let this_c = p.class("com/example/Hello"); + let obj_c = p.class("java/lang/Object"); + let runnable_c = p.class("java/lang/Runnable"); + let code_attr = p.utf8("Code"); + + // fields: int count; static final long BIG; + let count_name = p.utf8("count"); + let i_desc = p.utf8("I"); + let big_name = p.utf8("BIG"); + let j_desc = p.utf8("J"); + let constval_attr = p.utf8("ConstantValue"); + let big_val = p.long(0x1122_3344_5566_7788); + + // refs used by code + let obj_init = p.reff(10, "java/lang/Object", "", "()V"); + let sysout = p.reff(9, "java/lang/System", "out", "Ljava/io/PrintStream;"); + let hello = p.string(HELLO); + let println = p.reff(10, "java/io/PrintStream", "println", "(Ljava/lang/String;)V"); + let rt_exc = p.class("java/lang/RuntimeException"); + + // (): aload_0; invokespecial Object.; return + let mut init = vec![0x2a, 0xb7]; + init.extend_from_slice(&obj_init.to_be_bytes()); + init.push(0xb1); + let init_m = method(&mut p, 0x0001, "", "()V", attr(code_attr, code_body(1, 1, &init, &[]))); + + // run(): getstatic System.out; ldc "Hello"; invokevirtual println; return + let mut run = vec![0xb2]; + run.extend_from_slice(&sysout.to_be_bytes()); + run.push(0x12); + run.push(hello as u8); // ldc (1-byte index; pool is small) + run.push(0xb6); + run.extend_from_slice(&println.to_be_bytes()); + run.push(0xb1); + let run_m = method(&mut p, 0x0001, "run", "()V", attr(code_attr, code_body(2, 1, &run, &[]))); + + // pick(int): iload_0; tableswitch{0->L0,1->L1,default->Ldef}; L0: bipush 10; ireturn; L1: bipush 20; ireturn; Ldef: iconst_m1; ireturn + // offsets: iload_1@0; tableswitch@1 (pad 2) ends @24; L0@24; L1@27; Ldef@30 + let mut pick = vec![0x1b, 0xaa, 0x00, 0x00]; + u32b(&mut pick, 29); // default -> 1+29 = 30 + u32b(&mut pick, 0); // low + u32b(&mut pick, 1); // high + u32b(&mut pick, 23); // case 0 -> 1+23 = 24 + u32b(&mut pick, 26); // case 1 -> 1+26 = 27 + debug_assert_eq!(pick.len(), 24); + pick.extend_from_slice(&[0x10, 10, 0xac]); // @24: bipush 10; ireturn + pick.extend_from_slice(&[0x10, 20, 0xac]); // @27: bipush 20; ireturn + pick.extend_from_slice(&[0x02, 0xac]); // @30: iconst_m1; ireturn + let pick_m = method(&mut p, 0x0001, "pick", "(I)I", attr(code_attr, code_body(1, 1, &pick, &[]))); + + // guarded(): try { System.out.println("Hello"); } catch (RuntimeException e) {} (then return) + // 0: getstatic(3) ; 3: ldc(2) ; 5: invokevirtual(3) ; 8: goto +5 ->13 ; 11: astore_1 ; 12: return ; 13: return + let mut g = vec![0xb2]; + g.extend_from_slice(&sysout.to_be_bytes()); + g.push(0x12); + g.push(hello as u8); + g.push(0xb6); + g.extend_from_slice(&println.to_be_bytes()); + g.extend_from_slice(&[0xa7, 0x00, 0x05]); // @8 goto -> 13 + g.push(0x4c); // @11 astore_1 + g.push(0xb1); // @12 return + g.push(0xb1); // @13 return + let guarded_m = method(&mut p, 0x0001, "guarded", "()V", attr(code_attr, code_body(2, 2, &g, &[(0, 8, 11, rt_exc)]))); + + // field infos + let field = |p: &mut Pool, access: u16, name_idx: u16, desc_idx: u16, attrs: &[Vec]| -> Vec { + let _ = p; + let mut v = Vec::new(); + u16b(&mut v, access); + u16b(&mut v, name_idx); + u16b(&mut v, desc_idx); + u16b(&mut v, attrs.len() as u16); + for a in attrs { + v.extend_from_slice(a); + } + v + }; + let count_f = field(&mut p, 0x0002, count_name, i_desc, &[]); // private int count + let mut cv = Vec::new(); + u16b(&mut cv, big_val); + let big_f = field(&mut p, 0x0019, big_name, j_desc, &[attr(constval_attr, cv)]); // public static final long BIG + + let source_attr = p.utf8("SourceFile"); + let source_val = p.utf8("Hello.java"); + let mut sf = Vec::new(); + u16b(&mut sf, source_val); + let source = attr(source_attr, sf); + + assemble( + &p, + 0x0021, // public super + this_c, + obj_c, + &[runnable_c], + &[count_f, big_f], + &[init_m, run_m, pick_m, guarded_m], + &[source], + ) + } +} diff --git a/crates/jpeg/src/encode.rs b/crates/jpeg/src/encode.rs index 548f4c9f9..fb5fe183c 100644 --- a/crates/jpeg/src/encode.rs +++ b/crates/jpeg/src/encode.rs @@ -419,6 +419,34 @@ pub fn encode_baseline( sub: ChromaSubsampling, app_segments: &[(u8, Vec)], ) -> Result, EncodeError> { + validate_encode(data, width, height, channels, app_segments)?; + Ok(encode(data, width, height, channels, quality, sub, app_segments)) +} + +/// Encode the same optimized baseline JPEG as [`encode_baseline`], trading a second DCT pass +/// for working memory independent of image height. This path is sequential even when the +/// `parallel` feature is enabled. It retains only one MCU row of conversion planes and writes +/// directly into the returned encoded buffer: no image-wide tokens or duplicate coded buffer. +/// +/// Scratch consists of at most `24 * width + 8` floats (odd-width 4:2:0), plus fixed-size coding tables. +/// The caller still owns the input pixels and the returned JPEG; this is not a cap on output +/// size or a replacement for the caller's image/admission budget. Geometry, quality, metadata, +/// Huffman tables and restart boundaries match [`encode_baseline`] byte for byte. +#[allow(clippy::too_many_arguments)] +pub fn encode_baseline_low_memory( + data: &[u8], + width: usize, + height: usize, + channels: usize, + quality: u8, + sub: ChromaSubsampling, + app_segments: &[(u8, Vec)], +) -> Result, EncodeError> { + validate_encode(data, width, height, channels, app_segments)?; + Ok(encode_impl(data, width, height, channels, quality, sub, app_segments, true, true)) +} + +fn validate_encode(data: &[u8], width: usize, height: usize, channels: usize, app_segments: &[(u8, Vec)]) -> Result<(), EncodeError> { let fits = width.checked_mul(height).and_then(|n| n.checked_mul(channels)).is_some_and(|n| n <= data.len()); if !fits || width == 0 || height == 0 || width > 65_535 || height > 65_535 || !matches!(channels, 1 | 3 | 4) { return Err(EncodeError::InvalidInput(format!("{width}x{height}, {channels} channels, {} bytes", data.len()))); @@ -426,7 +454,7 @@ pub fn encode_baseline( if app_segments.iter().any(|(marker, payload)| !(0xE0..=0xEF).contains(marker) || payload.len() > 65_533) { return Err(EncodeError::InvalidInput("APP markers must be 0xE0..=0xEF with payloads no larger than 65533 bytes".into())); } - Ok(encode(data, width, height, channels, quality, sub, app_segments)) + Ok(()) } /// [`encode`], with optimized Huffman tables or (`optimize` false) the Annex K example tables. @@ -440,6 +468,21 @@ fn encode_with( sub: ChromaSubsampling, app_segments: &[(u8, Vec)], optimize: bool, +) -> Vec { + encode_impl(data, width, height, channels, quality, sub, app_segments, optimize, false) +} + +#[allow(clippy::too_many_arguments)] +fn encode_impl( + data: &[u8], + width: usize, + height: usize, + channels: usize, + quality: u8, + sub: ChromaSubsampling, + app_segments: &[(u8, Vec)], + optimize: bool, + low_memory: bool, ) -> Vec { // The public entry takes caller-sized dimensions: refuse (an empty output) what would size an allocation from // them or index past `data`, rather than panic or allocate for them. @@ -509,6 +552,8 @@ fn encode_with( planes.push(Plane { w: cw, h: crows.len(), data: cb }); planes.push(Plane { w: cw, h: crows.len(), data: cr }); } + #[cfg(test)] + low_memory_tests::record_planes(planes.iter().map(|p| p.data.len()).sum()); planes }; @@ -519,45 +564,58 @@ fn encode_with( let (mx, my) = (width.div_ceil(mcu_w), height.div_ceil(mcu_h)); // restart interval: whole MCU rows per band, ≤ 65535 MCUs, enough bands to keep all cores busy let rows_per_band = (my / 64).clamp(1, (65_535 / mx.max(1)).max(1)); - let bands: Vec = (0..my.div_ceil(rows_per_band)).collect(); + let num_bands = my.div_ceil(rows_per_band); + let bands: Vec = if low_memory { Vec::new() } else { (0..num_bands).collect() }; // first pass: each band's quantized blocks as symbols, with their counts per table (DC // prediction restarts per band, as the restart markers say) - let tokenize_band = |band: &usize| -> (Vec, [Freq; 4]) { + let visit_band = |band: &usize, emit: &mut dyn FnMut(&[i16; 64], &mut i32, bool)| { let (mut blk, mut q) = ([0f32; 64], [0i16; 64]); - let (mut tokens, mut freq) = (Vec::new(), [[0u64; 256]; 4]); let mut pred = [0i32; 3]; let (m0, m1) = (band * rows_per_band, ((band + 1) * rows_per_band).min(my)); - // the band's planes, its MCU row `m0` at their top (blocks past the image's bottom repeat its last row, - // which is the band's last row then) - let planes = convert(m0 * mcu_h..(m1 * mcu_h).min(height), m0 * 8..(m1 * 8).min(ch)); for mcu_y in m0..m1 { - let mcu_y = mcu_y - m0; + // Convert only the current MCU row. DC predictors still span the original band, + // so its symbols/restart decisions are identical to whole-band conversion. + let planes = convert(mcu_y * mcu_h..((mcu_y + 1) * mcu_h).min(height), mcu_y * 8..((mcu_y + 1) * 8).min(ch)); for mcu_x in 0..mx { for vy in 0..vs { for hx in 0..hs { - planes[0].block(mcu_x * hs + hx, mcu_y * vs + vy, &mut blk); + planes[0].block(mcu_x * hs + hx, vy, &mut blk); fdct_quant(&blk, &rl, &mut q); - tokenize_block(&q, &mut pred[0], false, &mut tokens, &mut freq); + emit(&q, &mut pred[0], false); } } if !gray { for (plane, pred) in planes.iter().zip(pred.iter_mut()).take(3).skip(1) { - plane.block(mcu_x, mcu_y, &mut blk); + plane.block(mcu_x, 0, &mut blk); fdct_quant(&blk, &rc, &mut q); - tokenize_block(&q, pred, true, &mut tokens, &mut freq); + emit(&q, pred, true); } } } } + }; + let tokenize_band = |band: &usize| -> (Vec, [Freq; 4]) { + let (mut tokens, mut freq) = (Vec::new(), [[0u64; 256]; 4]); + visit_band(band, &mut |q, pred, chroma| tokenize_block(q, pred, chroma, &mut tokens, &mut freq)); + #[cfg(test)] + low_memory_tests::record_tokens(tokens.len()); (tokens, freq) }; #[cfg(feature = "parallel")] - let tokenized: Vec<(Vec, [Freq; 4])> = bands.par_iter().map(tokenize_band).collect(); + let tokenized: Vec<(Vec, [Freq; 4])> = if low_memory { Vec::new() } else { bands.par_iter().map(tokenize_band).collect() }; #[cfg(not(feature = "parallel"))] - let tokenized: Vec<(Vec, [Freq; 4])> = bands.iter().map(tokenize_band).collect(); + let tokenized: Vec<(Vec, [Freq; 4])> = if low_memory { Vec::new() } else { bands.iter().map(tokenize_band).collect() }; // the tables: DC luma, AC luma, DC chroma, AC chroma let tables: [([u8; 16], Vec); 4] = if optimize { let mut total = [[0u64; 256]; 4]; + if low_memory { + for band in 0..num_bands { + visit_band(&band, &mut |q, pred, chroma| { + let base = if chroma { 2 } else { 0 }; + block_symbols(q, pred, |ac, symbol, _, _| total[base + ac as usize][symbol & 0xFF] += 1); + }); + } + } for (_, f) in &tokenized { for (t, f) in total.iter_mut().zip(f) { for (t, f) in t.iter_mut().zip(f) { @@ -577,9 +635,9 @@ fn encode_with( let huff = tables.each_ref().map(|(bits, vals)| Huff::new(bits, vals)); // second pass: code the symbols #[cfg(feature = "parallel")] - let coded: Vec> = tokenized.into_par_iter().map(|(t, _)| write_tokens(&t, &huff)).collect(); + let coded: Vec> = if low_memory { Vec::new() } else { tokenized.into_par_iter().map(|(t, _)| write_tokens(&t, &huff)).collect() }; #[cfg(not(feature = "parallel"))] - let coded: Vec> = tokenized.into_iter().map(|(t, _)| write_tokens(&t, &huff)).collect(); + let coded: Vec> = if low_memory { Vec::new() } else { tokenized.into_iter().map(|(t, _)| write_tokens(&t, &huff)).collect() }; // headers let mut out = Vec::with_capacity(coded.iter().map(Vec::len).sum::() + 4096); @@ -617,7 +675,7 @@ fn encode_with( dht(&mut out, 0x11, acb, acv); } let interval = (rows_per_band * mx) as u16; - if coded.len() > 1 { + if num_bands > 1 { segment(&mut out, 0xDD, &interval.to_be_bytes()); } if gray { @@ -625,11 +683,32 @@ fn encode_with( } else { segment(&mut out, 0xDA, &[3, 1, 0x00, 2, 0x11, 3, 0x11, 0, 63, 0]); } - let last = coded.len().saturating_sub(1); - for (i, c) in coded.iter().enumerate() { - out.extend_from_slice(c); - if i < last { - out.extend_from_slice(&[0xFF, 0xD0 + (i % 8) as u8]); + if low_memory { + let last = num_bands.saturating_sub(1); + for i in 0..num_bands { + // Continue directly in the final buffer, resetting entropy bits at the same band + // boundaries as the retained-token path. Only the output grows with image height. + let mut bits = Bits { out, acc: 0, n: 0 }; + visit_band(&i, &mut |q, pred, chroma| { + let base = if chroma { 2 } else { 0 }; + block_symbols(q, pred, |ac, symbol, extra, n| { + let (code, len) = huff[base + ac as usize].code[symbol & 0xFF]; + bits.put(code as u32, len as u32); + bits.put(extra & 0xFFFF, n & 0xF); + }); + }); + out = bits.finish(); + if i < last { + out.extend_from_slice(&[0xFF, 0xD0 + (i % 8) as u8]); + } + } + } else { + let last = coded.len().saturating_sub(1); + for (i, c) in coded.iter().enumerate() { + out.extend_from_slice(c); + if i < last { + out.extend_from_slice(&[0xFF, 0xD0 + (i % 8) as u8]); + } } } out.extend_from_slice(&[0xFF, 0xD9]); @@ -877,3 +956,7 @@ mod tests { assert!(psnr(&src, &px) > 35.0); } } + +#[cfg(test)] +#[path = "encode_low_memory_tests.rs"] +mod low_memory_tests; diff --git a/crates/jpeg/src/encode_low_memory_tests.rs b/crates/jpeg/src/encode_low_memory_tests.rs new file mode 100644 index 000000000..de45f8dfe --- /dev/null +++ b/crates/jpeg/src/encode_low_memory_tests.rs @@ -0,0 +1,155 @@ +use super::*; +use std::cell::Cell; + +thread_local! { + static STATS: Cell<(usize, usize)> = const { Cell::new((0, 0)) }; +} + +pub(super) fn record_planes(samples: usize) { + STATS.with(|s| { + let (peak, tokens) = s.get(); + s.set((peak.max(samples), tokens)); + }); +} +pub(super) fn record_tokens(count: usize) { + STATS.with(|s| { + let (peak, tokens) = s.get(); + s.set((peak, tokens + count)); + }); +} + +fn noise(len: usize) -> Vec { + let mut seed = 0x89ab_cdefu32; + (0..len) + .map(|_| { + seed ^= seed << 13; + seed ^= seed >> 17; + seed ^= seed << 5; + seed as u8 + }) + .collect() +} + +fn compare(src: &[u8], w: usize, h: usize, ch: usize, q: u8, sub: ChromaSubsampling, app: &[(u8, Vec)]) { + let expected = encode_baseline(src, w, h, ch, q, sub, app).unwrap(); + STATS.with(|s| s.set((0, 0))); + let actual = encode_baseline_low_memory(src, w, h, ch, q, sub, app).unwrap(); + assert_eq!(actual, expected, "{w}x{h} channels={ch} quality={q} subsampling={sub:?}"); + let (peak, tokens) = STATS.with(Cell::get); + assert!(peak <= 24 * w + 8, "MCU-row scratch exceeded: {peak}"); + assert_eq!(tokens, 0, "low-memory mode retained entropy tokens"); +} + +#[test] +fn all_sampling_and_channels_match_retained_tokens_byte_for_byte() { + for (w, h) in [(1, 1), (7, 9), (17, 31), (33, 65), (17, 1025)] { + for ch in [1, 3, 4] { + let src = noise(w * h * ch); + for sub in [ChromaSubsampling::S444, ChromaSubsampling::S422, ChromaSubsampling::S420] { + for q in [0, 1, 25, 50, 90, 100, 255] { + compare(&src, w, h, ch, q, sub, &[]); + } + } + } + } +} + +#[test] +fn high_entropy_hd_and_wide_frames_keep_only_one_mcu_row() { + for (w, h) in [(1920, 1080), (65_535, 1)] { + let src = noise(w * h * 3); + compare(&src, w, h, 3, 100, ChromaSubsampling::S444, &[]); + } +} + +#[test] +fn metadata_empty_tables_and_extra_source_bytes_keep_exact_output() { + let app = [(0xe0, b"custom density".to_vec()), (0xe2, vec![73; 65_533])]; + for ch in [1, 3, 4] { + let src = vec![127; 19 * 23 * ch + 5]; + compare(&src, 19, 23, ch, 75, ChromaSubsampling::S420, &app); + } +} + +#[test] +fn checked_admission_matches_original_without_panics() { + for (w, h, ch) in [(0, 1, 3), (1, 0, 3), (1, 1, 0), (1, 1, 2), (usize::MAX, 2, 4), (65_536, 1, 1), (1, 65_536, 1), (4, 4, 3)] { + let src = vec![0; if w == 65_536 || h == 65_536 { 65_536 } else { 8 }]; + let old = encode_baseline(&src, w, h, ch, 90, ChromaSubsampling::S444, &[]); + let new = encode_baseline_low_memory(&src, w, h, ch, 90, ChromaSubsampling::S444, &[]); + assert!(new.is_err()); + assert_eq!(new, old); + } + for app in [vec![(0xdf, vec![])], vec![(0xf0, vec![])], vec![(0xe1, vec![0; 65_534])]] { + assert_eq!( + encode_baseline_low_memory(&[0; 3], 1, 1, 3, 90, ChromaSubsampling::S444, &app), + encode_baseline(&[0; 3], 1, 1, 3, 90, ChromaSubsampling::S444, &app) + ); + } +} + +// Generated with the immutable pre-change encoder at craft-libs +// 937ac93c5cf3cd4b6a81e195b078fe161eb081b9, not the refactored token-retaining path. +// Odd chroma edges and 1025/2049-row inputs exercise multi-row restart bands. +#[test] +fn prechange_encoded_bytes_remain_pinned_across_band_boundaries() { + let cases = [ + (1, 1, 1, 1, 444, 159, 0xe3bd59145381ba57), + (1, 1, 1, 75, 422, 159, 0xcb2b103914bbdbd3), + (1, 1, 1, 100, 420, 160, 0xd9f640613efb6abf), + (1, 1, 3, 1, 444, 284, 0x61d2772b8fd9df17), + (1, 1, 3, 75, 422, 286, 0xa0e03ab7efa23296), + (1, 1, 3, 100, 420, 288, 0x5660667f1abd0a63), + (1, 1, 4, 1, 444, 284, 0x61d2772b8fd9df17), + (1, 1, 4, 75, 422, 286, 0xa0e03ab7efa23296), + (1, 1, 4, 100, 420, 288, 0x5660667f1abd0a63), + (17, 31, 1, 1, 444, 240, 0xf8d277e9499253d4), + (17, 31, 1, 75, 422, 515, 0xa6946d4f144bf243), + (17, 31, 1, 100, 420, 793, 0xbb3db259708d8951), + (17, 31, 3, 1, 444, 363, 0xff2b5b41ffb3f81b), + (17, 31, 3, 75, 422, 877, 0x0374ffb527378dfe), + (17, 31, 3, 100, 420, 1220, 0x2feeedfa90885737), + (17, 31, 4, 1, 444, 366, 0xde7f8d1330e436eb), + (17, 31, 4, 75, 422, 879, 0xb1559fbfc3ee0cf6), + (17, 31, 4, 100, 420, 1214, 0xaf5dcf12d28c8e88), + (33, 65, 1, 1, 444, 388, 0xbee80491e42c8fd2), + (33, 65, 1, 75, 422, 1470, 0x284f4eb78b785ca5), + (33, 65, 1, 100, 420, 2576, 0xa81cc94015f326dc), + (33, 65, 3, 1, 444, 526, 0xf75b4036acc30874), + (33, 65, 3, 75, 422, 2322, 0x6fbc56bd9a1eec70), + (33, 65, 3, 100, 420, 3796, 0xcad25051562ac816), + (33, 65, 4, 1, 444, 527, 0x4bfedc11153de4c1), + (33, 65, 4, 75, 422, 2309, 0x47bf11bf32bac6a4), + (33, 65, 4, 100, 420, 3775, 0x64c2303fde273cd1), + (17, 1025, 1, 1, 444, 2017, 0x242f4a95d8579612), + (17, 1025, 1, 75, 422, 10728, 0xfe49408f379bdffb), + (17, 1025, 1, 100, 420, 19686, 0x1355b995e38d6467), + (17, 1025, 3, 1, 444, 2137, 0x4e319440cb6946c2), + (17, 1025, 3, 75, 422, 17682, 0xf456c63b731dde8f), + (17, 1025, 3, 100, 420, 29015, 0x0631001154b128cf), + (17, 1025, 4, 1, 444, 2155, 0xa2de9c1d77e62aa6), + (17, 1025, 4, 75, 422, 17648, 0x7d85fbdf56061f0c), + (17, 1025, 4, 100, 420, 29010, 0x4848eeb93daf1df2), + (19, 2049, 1, 1, 444, 3531, 0x9b93cf219ff85796), + (19, 2049, 1, 75, 422, 26283, 0xb160523444397608), + (19, 2049, 1, 100, 420, 51883, 0xc5c26836c0a976c6), + (19, 2049, 3, 1, 444, 3303, 0x26eaac2272e1fdb8), + (19, 2049, 3, 75, 422, 42745, 0x38b9843fb54db698), + (19, 2049, 3, 100, 420, 79868, 0xd6a7917af19682f7), + (19, 2049, 4, 1, 444, 3343, 0x6bf577903528692f), + (19, 2049, 4, 75, 422, 42706, 0x0e62366274593a93), + (19, 2049, 4, 100, 420, 79804, 0x867d05cf9d944599), + ]; + for (w, h, ch, q, sampling, len, hash) in cases { + let sub = match sampling { + 444 => ChromaSubsampling::S444, + 422 => ChromaSubsampling::S422, + _ => ChromaSubsampling::S420, + }; + let src = noise(w * h * ch); + for actual in [encode_baseline(&src, w, h, ch, q, sub, &[]).unwrap(), encode_baseline_low_memory(&src, w, h, ch, q, sub, &[]).unwrap()] { + let actual_hash = actual.iter().fold(0xcbf29ce484222325u64, |h, b| (h ^ u64::from(*b)).wrapping_mul(0x100000001b3)); + assert_eq!((actual.len(), actual_hash), (len, hash), "{w}x{h} channels={ch} quality={q} sampling={sampling}"); + } + } +} diff --git a/crates/jpeg/src/lib.rs b/crates/jpeg/src/lib.rs index 4a2be3628..0d4735676 100644 --- a/crates/jpeg/src/lib.rs +++ b/crates/jpeg/src/lib.rs @@ -285,7 +285,7 @@ mod tests; /// Baseline JPEG encoder (8-bit, Huffman-coded sequential DCT). mod encode; -pub use encode::{ChromaSubsampling, EncodeError, encode_baseline}; +pub use encode::{ChromaSubsampling, EncodeError, encode_baseline, encode_baseline_low_memory}; mod app14; pub use app14::adobe_transform; diff --git a/crates/jsonc/Cargo.toml b/crates/jsonc/Cargo.toml new file mode 100644 index 000000000..eca4538cf --- /dev/null +++ b/crates/jsonc/Cargo.toml @@ -0,0 +1,12 @@ +[package] +name = "craft-jsonc" +description = "Span-preserving JSON/JSONC object editor with strict mode and caller-controlled input admission" +version.workspace = true +edition.workspace = true +license.workspace = true +rust-version.workspace = true +repository.workspace = true +[lints] +workspace = true +[dependencies] +serde_json = { workspace = true } diff --git a/crates/jsonc/src/lib.rs b/crates/jsonc/src/lib.rs new file mode 100644 index 000000000..003b9b02d --- /dev/null +++ b/crates/jsonc/src/lib.rs @@ -0,0 +1,619 @@ +#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)] +#![forbid(unsafe_code)] + +//! A small JSON-with-comments editor that changes only the bytes it must. +//! +//! The text is tokenized (comments and trailing commas tolerated), parsed into a tree that keeps +//! every value's byte span, and edits are applied by splicing new text into the original. Comments, +//! formatting and key order elsewhere in the file are untouched. In strict mode comments and +//! trailing commas are rejected (for clients whose own parser is strict JSON). + +use serde_json::{Map, Value}; + +/// Deepest nesting accepted (hostile files must not blow the stack). +const MAX_DEPTH: usize = 128; + +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +enum Tok { + LBrace, + RBrace, + LBracket, + RBracket, + Colon, + Comma, + Str, + Scalar, +} + +#[derive(Debug, Clone, Copy)] +struct Token { + kind: Tok, + start: usize, + end: usize, +} + +/// A parsed value with its span in the source. +#[derive(Debug, Clone)] +pub struct Node { + pub start: usize, + pub end: usize, + pub kind: NodeKind, +} + +#[derive(Debug, Clone)] +pub enum NodeKind { + Object { members: Vec, trailing_comma: bool }, + Array(Vec), + Scalar(Value), +} + +#[derive(Debug, Clone)] +pub struct Member { + pub key: String, + pub key_start: usize, + pub value: Node, +} + +/// A parsed document: the original text plus the tree. +#[derive(Debug, Clone)] +pub struct Doc { + pub text: String, + /// `None` for an empty (or whitespace/comment-only) file. + pub root: Option, + tokens: Vec, +} + +fn tokenize(text: &str, strict: bool) -> Result, String> { + let b = text.as_bytes(); + let mut i = 0usize; + if text.starts_with('\u{feff}') { + if strict { + return Err("byte-order mark is not allowed".into()); + } + i = 3; + } + let mut out = Vec::new(); + while let Some(&c) = b.get(i) { + match c { + b' ' | b'\t' | b'\r' | b'\n' => i += 1, + b'/' if b.get(i + 1) == Some(&b'/') => { + if strict { + return Err(format!("comment at byte {i} is not allowed in strict JSON")); + } + while let Some(&c) = b.get(i) { + if matches!(c, b'\r' | b'\n') { + break; + } + i += 1; + } + } + b'/' if b.get(i + 1) == Some(&b'*') => { + if strict { + return Err(format!("comment at byte {i} is not allowed in strict JSON")); + } + let start = i; + i += 2; + loop { + match b.get(i) { + None => return Err(format!("unterminated comment starting at byte {start}")), + Some(b'*') if b.get(i + 1) == Some(&b'/') => { + i += 2; + break; + } + Some(_) => i += 1, + } + } + } + b'{' | b'}' | b'[' | b']' | b':' | b',' => { + let kind = match c { + b'{' => Tok::LBrace, + b'}' => Tok::RBrace, + b'[' => Tok::LBracket, + b']' => Tok::RBracket, + b':' => Tok::Colon, + _ => Tok::Comma, + }; + out.push(Token { kind, start: i, end: i + 1 }); + i += 1; + } + b'"' => { + let start = i; + i += 1; + loop { + match b.get(i) { + None => return Err(format!("unterminated string starting at byte {start}")), + Some(b'\\') => i += 2, + Some(b'"') => { + i += 1; + break; + } + Some(b'\n') => return Err(format!("line break inside string at byte {i}")), + Some(_) => i += 1, + } + } + out.push(Token { kind: Tok::Str, start, end: i }); + } + c if c == b'-' || c.is_ascii_alphanumeric() || c == b'.' || c == b'+' => { + let start = i; + while let Some(&c) = b.get(i) { + if c == b'-' || c.is_ascii_alphanumeric() || c == b'.' || c == b'+' { + i += 1; + } else { + break; + } + } + out.push(Token { kind: Tok::Scalar, start, end: i }); + } + _ => return Err(format!("unexpected character at byte {i}")), + } + } + Ok(out) +} + +struct Parser<'a> { + text: &'a str, + toks: &'a [Token], + pos: usize, + strict: bool, +} + +impl Parser<'_> { + fn peek(&self) -> Option { + self.toks.get(self.pos).copied() + } + + fn next(&mut self) -> Result { + let t = self.peek().ok_or_else(|| "unexpected end of file".to_string())?; + self.pos += 1; + Ok(t) + } + + fn slice(&self, t: Token) -> &str { + self.text.get(t.start..t.end).unwrap_or_default() + } + + fn value(&mut self, depth: usize) -> Result { + if depth > MAX_DEPTH { + return Err("nested too deeply".into()); + } + let t = self.next()?; + match t.kind { + Tok::LBrace => { + let mut members = Vec::new(); + let mut trailing_comma = false; + loop { + let n = self.peek().ok_or("unterminated object")?; + if n.kind == Tok::RBrace { + self.pos += 1; + if trailing_comma && self.strict { + return Err(format!("trailing comma before byte {}", n.start)); + } + return Ok(Node { start: t.start, end: n.end, kind: NodeKind::Object { members, trailing_comma } }); + } + if !members.is_empty() && !trailing_comma { + return Err(format!("expected , or }} at byte {}", n.start)); + } + let k = self.next()?; + if k.kind != Tok::Str { + return Err(format!("expected a key at byte {}", k.start)); + } + let key: String = serde_json::from_str(self.slice(k)).map_err(|e| format!("bad key at byte {}: {e}", k.start))?; + let c = self.next()?; + if c.kind != Tok::Colon { + return Err(format!("expected : at byte {}", c.start)); + } + let value = self.value(depth + 1)?; + members.push(Member { key, key_start: k.start, value }); + trailing_comma = false; + if self.peek().is_some_and(|t| t.kind == Tok::Comma) { + self.pos += 1; + trailing_comma = true; + } + } + } + Tok::LBracket => { + let mut items = Vec::new(); + let mut comma = false; + loop { + let n = self.peek().ok_or("unterminated array")?; + if n.kind == Tok::RBracket { + self.pos += 1; + if comma && self.strict { + return Err(format!("trailing comma before byte {}", n.start)); + } + return Ok(Node { start: t.start, end: n.end, kind: NodeKind::Array(items) }); + } + if !items.is_empty() && !comma { + return Err(format!("expected , or ] at byte {}", n.start)); + } + items.push(self.value(depth + 1)?); + comma = false; + if self.peek().is_some_and(|t| t.kind == Tok::Comma) { + self.pos += 1; + comma = true; + } + } + } + Tok::Str | Tok::Scalar => { + let v: Value = serde_json::from_str(self.slice(t)).map_err(|_| format!("bad value at byte {}", t.start))?; + Ok(Node { start: t.start, end: t.end, kind: NodeKind::Scalar(v) }) + } + _ => Err(format!("unexpected token at byte {}", t.start)), + } + } +} + +impl Node { + pub fn to_value(&self) -> Value { + match &self.kind { + NodeKind::Scalar(v) => v.clone(), + NodeKind::Array(items) => Value::Array(items.iter().map(Node::to_value).collect()), + NodeKind::Object { members, .. } => { + let mut m = Map::new(); + for mem in members { + m.insert(mem.key.clone(), mem.value.to_value()); + } + Value::Object(m) + } + } + } + + fn member(&self, key: &str) -> Option<&Member> { + match &self.kind { + NodeKind::Object { members, .. } => members.iter().rev().find(|m| m.key == key), + _ => None, + } + } +} + +/// Parse `text`. `strict` rejects comments, trailing commas and a BOM. +/// +/// Compatibility entry point: no implicit byte cap. Callers must bound input and +/// edit values according to their context. Nesting is capped at 128; token/tree +/// storage scales with input. Use [`parse_bounded`] to reject oversized text +/// before tokenization. This does not impose an edit-output budget. +pub fn parse(text: &str, strict: bool) -> Result { + let tokens = tokenize(text, strict)?; + if tokens.is_empty() { + return Ok(Doc { text: text.to_string(), root: None, tokens }); + } + let mut p = Parser { text, toks: &tokens, pos: 0, strict }; + let root = p.value(0)?; + if p.pos != tokens.len() { + return Err("extra content after the top-level value".into()); + } + if !matches!(root.kind, NodeKind::Object { .. }) { + return Err("the top level must be an object".into()); + } + Ok(Doc { text: text.to_string(), root: Some(root), tokens }) +} + +impl Doc { + pub fn to_value(&self) -> Value { + self.root.as_ref().map(Node::to_value).unwrap_or_else(|| Value::Object(Map::new())) + } + + /// The value at `path` (object keys only). + pub fn get(&self, path: &[&str]) -> Option { + let mut node = self.root.as_ref()?; + for k in path { + node = &node.member(k)?.value; + } + Some(node.to_value()) + } + + fn line_start(&self, pos: usize) -> usize { + self.text.get(..pos).and_then(|s| s.rfind(['\r', '\n'])).map(|i| i + 1).unwrap_or(0) + } + + fn indent_at(&self, pos: usize) -> String { + let ls = self.line_start(pos); + self.text.get(ls..).unwrap_or_default().chars().take_while(|c| *c == ' ' || *c == '\t').collect() + } + + /// True when only whitespace precedes `pos` on its line. + fn first_on_line(&self, pos: usize) -> bool { + let ls = self.line_start(pos); + self.text.get(ls..pos).is_some_and(|s| s.trim().is_empty()) + } + + /// Set `path` to `value`, creating intermediate objects. Returns the new text. + pub fn set(&self, path: &[&str], value: &Value) -> Result { + let Some((last, parents)) = path.split_last() else { return Err("empty path".into()) }; + let Some(root) = &self.root else { + // No object yet: retain comments, whitespace and an optional BOM before the new one. + let mut v = value.clone(); + for k in path.iter().rev() { + let mut m = Map::new(); + m.insert((*k).to_string(), v); + v = Value::Object(m); + } + let mut s = self.text.clone(); + let eol = self.eol(); + if !s.is_empty() && !s.ends_with(['\r', '\n']) { + s.push_str(eol); + } + s.push_str(&render(&v, "", eol)); + s.push_str(eol); + return Ok(s); + }; + // Walk down as far as the path exists. + let mut node = root; + let mut depth = 0; + for k in parents { + match node.member(k) { + Some(m) if matches!(m.value.kind, NodeKind::Object { .. }) => { + node = &m.value; + depth += 1; + } + Some(_) => return Err(format!("\"{k}\" exists but is not an object")), + None => break, + } + } + if depth == parents.len() + && let Some(m) = node.member(last) + { + // Replace the existing value in place. + let indent = self.indent_at(m.key_start); + let rendered = render(value, &indent, self.eol()); + return Ok(splice(&self.text, &[(m.value.start, m.value.end, rendered)])); + } + // Insert a new member (holding the rest of the path) into `node`. + let rest = path.get(depth..).unwrap_or_default(); + let Some((first, tail)) = rest.split_first() else { return Err("empty path".into()) }; + let mut v = value.clone(); + for k in tail.iter().rev() { + let mut m = Map::new(); + m.insert((*k).to_string(), v); + v = Value::Object(m); + } + self.insert_member(node, first, &v) + } + + /// Preserve CRLF and CR-only documents; otherwise use LF. + fn eol(&self) -> &'static str { + if self.text.contains("\r\n") { + "\r\n" + } else if self.text.contains('\r') && !self.text.contains('\n') { + "\r" + } else { + "\n" + } + } + + /// Add `key: value` as the last member of `obj`, indented like the members already there. + fn insert_member(&self, obj: &Node, key: &str, value: &Value) -> Result { + let NodeKind::Object { members, trailing_comma } = &obj.kind else { return Err("not an object".into()) }; + let close = obj.end.saturating_sub(1); + let close_indent = self.indent_at(obj.start); + let indent = match members.first() { + Some(m) if self.first_on_line(m.key_start) => self.indent_at(m.key_start), + _ => format!("{close_indent} "), + }; + let eol = self.eol(); + let key_json = serde_json::to_string(key).map_err(|e| e.to_string())?; + // An object whose members all end in a comma gets a new member that does too. + let comma = if *trailing_comma { "," } else { "" }; + let member = format!("{indent}{key_json}: {}{comma}", render(value, &indent, eol)); + let mut edits = Vec::new(); + if let Some(last) = members.last() + && !trailing_comma + { + edits.push((last.value.end, last.value.end, ",".to_string())); + } + if self.first_on_line(close) && !members.is_empty() { + let ls = self.line_start(close); + edits.push((ls, ls, format!("{member}{eol}"))); + } else { + // `{}` or `{ "a": 1 }` on one line: open it up. + let inner_end = close; + let before = self.text.get(..inner_end).unwrap_or_default(); + let trimmed_end = before.trim_end().len().max(obj.start + 1); + edits.push((trimmed_end, inner_end, format!("{eol}{member}{eol}{close_indent}"))); + } + Ok(splice(&self.text, &edits)) + } + + /// Remove every member at `path`. Returns the new text, or `None` if it was not there. + pub fn remove(&self, path: &[&str]) -> Option { + let (last, parents) = path.split_last()?; + let mut node = self.root.as_ref()?; + for k in parents { + node = &node.member(k)?.value; + } + let NodeKind::Object { members, .. } = &node.kind else { return None }; + let mut edits = Vec::new(); + // Remove members separately so comments between duplicates survive. + // A final run's leading comma is a separate edit for the same reason. + for run in members.split(|m| m.key != *last) { + let Some(first) = run.first() else { continue }; + let before_idx = self.tokens.partition_point(|t| t.end <= first.key_start); + let before = before_idx.checked_sub(1).and_then(|i| self.tokens.get(i)).copied().filter(|t| t.kind == Tok::Comma); + for member in run { + let after_idx = self.tokens.partition_point(|t| t.start < member.value.end); + let after = self.tokens.get(after_idx).copied().filter(|t| t.kind == Tok::Comma); + let with_comma = after.is_none_or(|c| self.text.get(member.value.end..c.start).is_some_and(|gap| gap.trim().is_empty())); + let member_end = if with_comma { after.map(|t| t.end).unwrap_or(member.value.end) } else { member.value.end }; + let rest = self.text.get(member_end..).unwrap_or_default(); + let line_rest = rest.split(['\r', '\n']).next().unwrap_or_default(); + let own_lines = self.first_on_line(member.key_start) && line_rest.trim().is_empty(); + let (start, end) = if own_lines { + let line_end = member_end + line_rest.len(); + let eol_len = + if self.text.get(line_end..).is_some_and(|s| s.starts_with("\r\n")) { 2 } else { usize::from(rest.len() > line_rest.len()) }; + (self.line_start(member.key_start), line_end + eol_len) + } else { + (member.key_start, member_end) + }; + edits.push((start, end, String::new())); + if !with_comma && let Some(c) = after { + edits.push((c.start, c.end, String::new())); + } + // The last member had no comma after it, so the one before it goes: leaving it + // would add a trailing comma the file didn't have, which plain JSON readers refuse. + if after.is_none() + && let Some(c) = before + { + edits.push((c.start, c.end, String::new())); + } + } + } + (!edits.is_empty()).then(|| splice(&self.text, &edits)) + } +} + +/// Pretty-print `value` with continuation lines indented by `indent`. +fn render(value: &Value, indent: &str, eol: &str) -> String { + let s = serde_json::to_string_pretty(value).unwrap_or_else(|_| "null".into()); + let mut out = String::new(); + for (i, line) in s.lines().enumerate() { + if i > 0 { + out.push_str(eol); + out.push_str(indent); + } + out.push_str(line); + } + out +} + +/// Apply non-overlapping edits `(start, end, replacement)`. +fn splice(text: &str, edits: &[(usize, usize, String)]) -> String { + let mut sorted: Vec<&(usize, usize, String)> = edits.iter().collect(); + sorted.sort_by_key(|e| (e.0, e.1)); + let mut out = String::with_capacity(text.len() + 256); + let mut pos = 0; + for (s, e, r) in sorted { + if *s < pos { + continue; + } + out.push_str(text.get(pos..*s).unwrap_or_default()); + out.push_str(r); + pos = *e; + } + out.push_str(text.get(pos..).unwrap_or_default()); + out +} + +#[cfg(test)] +mod tests { + use super::*; + use serde_json::json; + + const FIXTURE: &str = r#"// user settings +{ + /* theme */ + "theme": "dark", // trailing note + "mcpServers": { + "other": { "command": "x" }, // keep me + }, +} +"#; + + #[test] + fn set_keeps_crlf_line_endings() { + for src in ["{\r\n \"a\": 1\r\n}\r\n", "{}\r\n"] { + let d = parse(src, true).unwrap(); + let out = d.set(&["z"], &json!({"k": [1]})).unwrap(); + assert_eq!(out.matches('\n').count(), out.matches("\r\n").count(), "mixed line endings: {out:?}"); + assert_eq!(parse(&out, true).unwrap().get(&["z", "k"]), Some(json!([1]))); + } + } + + #[test] + fn a_carriage_return_ends_a_line_comment() { + let text = "// editor settings\r{\r \"keep\": 1, // explanation\r \"port\": 2\r}\r"; + let doc = parse(text, false).unwrap(); + assert_eq!(doc.get(&["keep"]), Some(json!(1))); + let updated = doc.set(&["port"], &json!(3)).unwrap(); + assert_eq!(updated, text.replace('2', "3")); + assert_eq!(parse(&updated, false).unwrap().get(&["port"]), Some(json!(3))); + assert!(parse(text, true).is_err()); + } + + #[test] + fn parses_comments_and_trailing_commas() { + let d = parse(FIXTURE, false).unwrap(); + assert_eq!(d.get(&["mcpServers", "other", "command"]), Some(json!("x"))); + assert!(parse(FIXTURE, true).is_err()); + assert!(parse("{\"a\": 1,}", true).is_err()); + assert!(parse("{\"a\": 1}", true).is_ok()); + assert!(parse("[1]", false).is_err()); + assert!(parse("{", false).is_err()); + assert!(parse("", false).unwrap().root.is_none()); + } + + #[test] + fn insert_keeps_comments_and_reparses() { + let d = parse(FIXTURE, false).unwrap(); + let new = d.set(&["mcpServers", "craft-anything"], &json!({"command": "/x/craft-anything-cli", "args": ["mcp"]})).unwrap(); + assert!(new.contains("// keep me") && new.contains("/* theme */") && new.contains("// user settings")); + let d2 = parse(&new, false).unwrap(); + assert_eq!(d2.get(&["mcpServers", "craft-anything", "args"]), Some(json!(["mcp"]))); + assert_eq!(d2.get(&["mcpServers", "other", "command"]), Some(json!("x"))); + // replace in place + let new2 = d2.set(&["mcpServers", "craft-anything"], &json!({"command": "y"})).unwrap(); + let d3 = parse(&new2, false).unwrap(); + assert_eq!(d3.get(&["mcpServers", "craft-anything"]), Some(json!({"command": "y"}))); + // remove restores the original exactly + assert_eq!(d3.remove(&["mcpServers", "craft-anything"]).unwrap(), FIXTURE); + } + + #[test] + fn creates_missing_tables_and_handles_empty() { + let d = parse("{}", true).unwrap(); + let new = d.set(&["mcp", "servers", "k"], &json!(1)).unwrap(); + assert_eq!(parse(&new, true).unwrap().get(&["mcp", "servers", "k"]), Some(json!(1))); + let d = parse("{\n \"a\": 1\n}\n", true).unwrap(); + let new = d.set(&["s", "k"], &json!(true)).unwrap(); + assert_eq!(new, "{\n \"a\": 1,\n \"s\": {\n \"k\": true\n }\n}\n"); + let empty = parse(" \n", false).unwrap().set(&["s", "k"], &json!(2)).unwrap(); + assert_eq!(parse(&empty, true).unwrap().get(&["s", "k"]), Some(json!(2))); + let one_line = parse(r#"{"a": {"b": 1}}"#, true).unwrap().set(&["a", "c"], &json!(2)).unwrap(); + assert_eq!(parse(&one_line, true).unwrap().to_value(), json!({"a": {"b": 1, "c": 2}})); + } + + #[test] + fn remove_first_middle_last() { + let text = "{\n \"a\": 1,\n \"b\": 2,\n \"c\": 3\n}\n"; + let d = parse(text, true).unwrap(); + for (k, rest) in [("a", json!({"b":2,"c":3})), ("b", json!({"a":1,"c":3})), ("c", json!({"a":1,"b":2}))] { + let t = d.remove(&[k]).unwrap(); + assert_eq!(parse(&t, true).unwrap().to_value(), rest, "{t}"); + } + assert!(d.remove(&["zz"]).is_none()); + let single = parse("{\"a\": 1}", true).unwrap().remove(&["a"]).unwrap(); + assert_eq!(parse(&single, true).unwrap().to_value(), json!({})); + } + + #[test] + fn hostile_input_never_panics() { + for s in ["{\"a\":", "{\"a\" 1}", "{,}", "\"\\", "/*", "{\"a\":[1,,2]}", "{\"a\":1}}", &"[".repeat(1000), "\u{feff}{}"] { + let _ = parse(s, false); + let _ = parse(s, true); + } + assert!(parse("\u{feff}{}", false).is_ok()); + } +} + +/// Reject input larger than `max_bytes` before tokenizing, then use [`parse`]. +/// This bounds admitted input, not allocator overhead or subsequent edit output. +pub fn parse_bounded(text: &str, strict: bool, max_bytes: usize) -> Result { + if text.len() > max_bytes { + return Err(format!("JSONC input exceeds {max_bytes} bytes")); + } + parse(text, strict) +} + +#[cfg(test)] +mod admission_tests { + use super::*; + #[test] + fn byte_limit_is_explicit_and_precedes_syntax_work() { + assert!(parse_bounded("{}", false, 2).is_ok()); + assert_eq!(parse_bounded("{", false, 0).unwrap_err(), "JSONC input exceeds 0 bytes"); + assert!(parse_bounded("", false, 0).is_ok()); + let text = "{\"é\":1}"; + assert!(parse_bounded(text, false, text.len() - 1).is_err()); + assert_eq!(parse_bounded(text, false, text.len()).unwrap().to_value(), parse(text, false).unwrap().to_value()); + } +} diff --git a/crates/mcp-server/src/lib.rs b/crates/mcp-server/src/lib.rs index 17e6827c4..66568fc05 100644 --- a/crates/mcp-server/src/lib.rs +++ b/crates/mcp-server/src/lib.rs @@ -15,7 +15,7 @@ mod server; pub use content::{Contents, base64, image_result, text_result}; pub use schema::{Effect, check_arguments, object, string, tool}; -pub use server::{Incoming, Info, PROTOCOL_VERSION, Reference, SUPPORTED_VERSIONS, Server, Tools, read_message, response}; +pub use server::{Incoming, Info, Options, PROTOCOL_VERSION, Reference, SUPPORTED_VERSIONS, Server, Tools, read_message, response}; #[cfg(test)] mod tests; diff --git a/crates/mcp-server/src/server.rs b/crates/mcp-server/src/server.rs index b7ed05027..e0d064da5 100644 --- a/crates/mcp-server/src/server.rs +++ b/crates/mcp-server/src/server.rs @@ -4,7 +4,7 @@ use std::io::{BufRead, Write}; use serde_json::{Value, json}; -use crate::content::Contents; +use crate::content::{Contents, text_result}; use crate::schema::{check_arguments, check_prompt_arguments}; /// The newest protocol revision we speak; offered when the client asks for one we don't know. @@ -88,9 +88,25 @@ pub struct Info { pub max_line: usize, } +/// Opt-in behaviour for apps with their own conventions; `Options::default()` is what [`Server::new`] +/// does. Set with [`Server::with_options`]. +#[derive(Clone, Debug, Default)] +pub struct Options { + /// Sent as `serverInfo.websiteUrl` at `initialize` (MCP 2025-06-18) when set. + pub website_url: Option, + /// Report a `tools/call` whose arguments fail the check against the tool's schema, or whose + /// tool is unknown, as a tool result with `isError: true` and the message as text, not as a + /// JSON-RPC -32602 error. For apps whose clients read every tool failure from the result. + pub tool_errors_as_results: bool, + /// Refuse a request whose `id` is neither a string nor a number (JSON-RPC 2.0) with -32600 and + /// a null id, instead of echoing the id back. + pub strict_request_ids: bool, +} + /// An MCP server over the app's [`Tools`]. pub struct Server { info: Info, + options: Options, tools: T, initialized: bool, } @@ -157,7 +173,13 @@ pub fn response(id: Value, result: Value) -> Value { impl Server { pub fn new(info: Info, tools: T) -> Self { - Self { info, tools, initialized: false } + Self { info, options: Options::default(), tools, initialized: false } + } + /// This server with `options` ([`Options`]) in place of the defaults. + #[must_use] + pub fn with_options(mut self, options: Options) -> Self { + self.options = options; + self } pub fn tools(&mut self) -> &mut T { &mut self.tools @@ -215,7 +237,11 @@ impl Server { if o.contains_key("result") || o.contains_key("error") { return None; } - return Some(error(id.unwrap_or(Value::Null), INVALID_REQUEST, "missing `method`")); + let echoed = match id { + Some(id) if !self.options.strict_request_ids || id.is_string() || id.is_number() => id, + _ => Value::Null, + }; + return Some(error(echoed, INVALID_REQUEST, "missing `method`")); }; let params = o.get("params").cloned().unwrap_or(Value::Null); let Some(id) = id else { @@ -224,6 +250,9 @@ impl Server { } return None; }; + if self.options.strict_request_ids && !(id.is_string() || id.is_number()) { + return Some(error(Value::Null, INVALID_REQUEST, "`id` must be a string or number")); + } Some(match self.request(method, ¶ms) { Ok(r) => response(id, r), Err((code, m)) => error(id, code, m), @@ -236,10 +265,14 @@ impl Server { let asked = params.get("protocolVersion").and_then(Value::as_str).unwrap_or(PROTOCOL_VERSION); let version = if SUPPORTED_VERSIONS.contains(&asked) { asked } else { PROTOCOL_VERSION }; let Info { name, title, version: server_version, .. } = self.info; + let mut server_info = json!({"name": name, "title": title, "version": server_version}); + if let Some(url) = &self.options.website_url { + server_info["websiteUrl"] = json!(url); + } Ok(json!({ "protocolVersion": version, "capabilities": self.capabilities(), - "serverInfo": {"name": name, "title": title, "version": server_version}, + "serverInfo": server_info, "instructions": self.tools.instructions(), })) } @@ -251,7 +284,9 @@ impl Server { None | Some(Value::Null) => json!({}), Some(a) => a.clone(), }; - check_arguments(&self.tools.list(), name, &args).map_err(|e| (INVALID_PARAMS, e))?; + if let Err(e) = check_arguments(&self.tools.list(), name, &args) { + return if self.options.tool_errors_as_results { Ok(text_result(e, true)) } else { Err((INVALID_PARAMS, e)) }; + } Ok(self.tools.call(name, &args)) } "resources/list" => Ok(json!({"resources": self.tools.resources()})), diff --git a/crates/mcp-server/src/tests.rs b/crates/mcp-server/src/tests.rs index b687ee2e8..3f8f8d315 100644 --- a/crates/mcp-server/src/tests.rs +++ b/crates/mcp-server/src/tests.rs @@ -1,7 +1,8 @@ use serde_json::{Value, json}; use crate::{ - Contents, Effect, Info, PROTOCOL_VERSION, Reference, SUPPORTED_VERSIONS, Server, Tools, check_arguments, object, string, text_result, tool, + Contents, Effect, Info, Options, PROTOCOL_VERSION, Reference, SUPPORTED_VERSIONS, Server, Tools, check_arguments, object, string, text_result, + tool, }; /// One app's tools: `echo` and `level`, nothing behind them (no engine, no design). `log` records @@ -366,3 +367,131 @@ fn every_call_runs_right_after_its_listing() { reply(&mut s, &json!([call("level", json!({})), call("echo", json!({"text": "b"}))])); assert_eq!(s.tools().log, ["list", "list", "call echo", "list", "list", "call level", "list", "call echo"]); } + +fn with(options: Options) -> Server { + Server::new(info(), Echo::default()).with_options(options) +} + +fn call_msg(id: u64, name: &str, args: Value) -> Value { + json!({"jsonrpc": "2.0", "id": id, "method": "tools/call", "params": {"name": name, "arguments": args}}) +} + +/// `websiteUrl` is sent only when set. +#[test] +fn website_url_is_sent_only_when_set() { + let init = json!({"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {}}); + let off = reply(&mut with(Options::default()), &init).unwrap(); + assert!(off["result"]["serverInfo"].get("websiteUrl").is_none(), "{off}"); + let on = reply(&mut with(Options { website_url: Some("https://example.org/echo".into()), ..Options::default() }), &init).unwrap(); + assert_eq!(on["result"]["serverInfo"]["websiteUrl"], "https://example.org/echo"); + assert_eq!(on["result"]["serverInfo"]["name"], "echo"); +} + +/// With `tool_errors_as_results`, argument failures and unknown tools are `isError` results that +/// carry the message and never run the tool; other errors stay JSON-RPC errors. +#[test] +fn tool_errors_as_results_replaces_invalid_params() { + let mut s = with(Options { tool_errors_as_results: true, ..Options::default() }); + let bad = [ + call_msg(1, "echo", json!({})), + call_msg(2, "echo", json!({"text": 3})), + call_msg(3, "echo", json!({"text": "a", "loud": true})), + call_msg(4, "shout", json!({})), + call_msg(5, "echo", json!([])), + call_msg(6, "echo", json!("text")), + call_msg(7, "echo", json!(7)), + ]; + for msg in &bad { + let r = reply(&mut s, msg).unwrap(); + assert!(r.get("error").is_none(), "{r}"); + assert_eq!(r["result"]["isError"], true, "{r}"); + assert!(r["result"]["content"][0]["text"].as_str().is_some_and(|t| !t.is_empty()), "{r}"); + } + let r = reply(&mut s, &bad[0]).unwrap(); + assert_eq!(r["result"]["content"][0]["text"], "echo: missing required argument `text`"); + assert!(s.tools().calls.is_empty()); + let ok = reply(&mut s, &call_msg(8, "echo", json!({"text": "hi"}))).unwrap(); + assert_eq!(ok["result"], json!({"content": [{"type": "text", "text": "hi"}]})); + let nomethod = reply(&mut s, &json!({"jsonrpc": "2.0", "id": 9, "method": "nope"})).unwrap(); + assert_eq!(nomethod["error"]["code"], -32601); + let noname = reply(&mut s, &json!({"jsonrpc": "2.0", "id": 10, "method": "tools/call", "params": {}})).unwrap(); + assert_eq!(noname["error"]["code"], -32602); + // Unchanged with the option off. + let mut off = with(Options::default()); + for msg in &bad { + assert_eq!(reply(&mut off, msg).unwrap()["error"]["code"], -32602); + } +} + +/// With `strict_request_ids`, an id that is not a string or number is -32600 with a null id; the +/// tool never runs. Off, such ids are echoed as before. Notifications have no id and are unaffected. +#[test] +fn strict_request_ids_refuse_other_id_types() { + let odd = [json!(null), json!(true), json!({"a": 1}), json!([1])]; + let mut on = with(Options { strict_request_ids: true, ..Options::default() }); + let mut off = with(Options::default()); + for id in &odd { + let msg = json!({"jsonrpc": "2.0", "id": id, "method": "tools/call", "params": {"name": "echo", "arguments": {"text": "x"}}}); + let r = reply(&mut on, &msg).unwrap(); + assert_eq!(r["error"]["code"], -32600, "{id}: {r}"); + assert_eq!(r["id"], Value::Null); + let r = reply(&mut off, &json!({"jsonrpc": "2.0", "id": id, "method": "ping"})).unwrap(); + assert_eq!(r["id"], *id); + assert_eq!(r["result"], json!({})); + } + assert!(on.tools().calls.is_empty()); + for id in [json!("a"), json!(1), json!(1.5), json!(-3)] { + let r = reply(&mut on, &json!({"jsonrpc": "2.0", "id": id, "method": "ping"})).unwrap(); + assert_eq!(r["result"], json!({}), "{id}"); + } + assert!(reply(&mut on, ¬ification()).is_none()); +} + +/// The missing-`method` error follows the same id rule: strict mode echoes only string and number +/// ids and answers with a null id for the rest; off, ids are echoed as before. +#[test] +fn strict_request_ids_apply_to_the_missing_method_error() { + let mut on = with(Options { strict_request_ids: true, ..Options::default() }); + let mut off = with(Options::default()); + for id in [json!(true), json!({"a": 1}), json!([1])] { + let msg = json!({"jsonrpc": "2.0", "id": id}); + let r = reply(&mut on, &msg).unwrap(); + assert_eq!((r["error"]["code"].clone(), r["id"].clone()), (json!(-32600), Value::Null), "{id}"); + assert_eq!(reply(&mut off, &msg).unwrap()["id"], id); + } + for id in [json!("a"), json!(7)] { + assert_eq!(reply(&mut on, &json!({"jsonrpc": "2.0", "id": id})).unwrap()["id"], id); + } + assert_eq!(reply(&mut on, &json!({"jsonrpc": "2.0"})).unwrap()["id"], Value::Null); +} + +/// Hostile input with every option on: oversized and non-UTF-8 lines, odd ids and wrongly typed +/// arguments are answered and serving goes on, and nothing panics. +#[test] +fn every_option_on_survives_hostile_input() { + let mut input = vec![b'x'; (1 << 16) + 10]; + input.push(b'\n'); + input.extend_from_slice(b"\xff\xfe\n"); + for id in ["null", "true", "{}", "[]", "\"s\"", "1e999"] { + input.extend_from_slice( + format!( + "{{\"jsonrpc\":\"2.0\",\"id\":{id},\"method\":\"tools/call\",\"params\":{{\"name\":\"echo\",\"arguments\":{{\"text\":{id}}}}}}}\n" + ) + .as_bytes(), + ); + } + for args in ["null", "1", "\"a\"", "[]", "{\"text\":[1]}", "{\"text\":{}}"] { + input.extend_from_slice( + format!("{{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{{\"name\":\"level\",\"arguments\":{args}}}}}\n").as_bytes(), + ); + } + input.extend_from_slice(json!({"jsonrpc": "2.0", "id": 9, "method": "ping"}).to_string().as_bytes()); + let mut output = Vec::new(); + let options = Options { website_url: Some("https://example.org".into()), tool_errors_as_results: true, strict_request_ids: true }; + with(options).serve(std::io::Cursor::new(input), &mut output).unwrap(); + let replies: Vec = String::from_utf8(output).unwrap().lines().map(|l| serde_json::from_str(l).unwrap()).collect(); + assert_eq!(replies.len(), 2 + 6 + 6 + 1, "{replies:?}"); + assert_eq!(replies[0]["error"]["code"], -32600); + assert_eq!(replies[1]["error"]["code"], -32700); + assert_eq!(replies.last().map(|r| &r["result"]), Some(&json!({}))); +} diff --git a/crates/media-testkit/src/hostile.rs b/crates/media-testkit/src/hostile.rs index f40021986..ddfc55f79 100644 --- a/crates/media-testkit/src/hostile.rs +++ b/crates/media-testkit/src/hostile.rs @@ -3,9 +3,9 @@ //! thread with a time limit for each case. [`Rng`], [`mutations`] and the other names here are //! `craft_testkit`'s. +pub use craft_testkit::hostile::{DIVISOR_VARIABLE, MAX_CASES, Mutation, Mutations, Rng, mutations}; #[cfg(not(target_arch = "wasm32"))] -pub use craft_testkit::hostile::{HammerConfig, HammerError}; -pub use craft_testkit::hostile::{MAX_CASES, Mutation, Mutations, Rng, mutations}; +pub use craft_testkit::hostile::{HammerConfig, HammerError, divisor}; /// The variable that multiplies [`hammer`]'s iterations. #[cfg(not(target_arch = "wasm32"))] @@ -17,8 +17,10 @@ const MULTIPLIER_VARIABLE: &str = "CRAFT_MEDIA_HOSTILE_MULT"; /// Panics on the first case that panics or does not finish, naming `name`, the case, its length and /// the panic's message. /// -/// `CRAFT_MEDIA_HOSTILE_MULT=10` runs ten times the iterations (soak runs). A value that is not a -/// whole number above zero panics, naming the variable, before `run` is called. +/// `CRAFT_MEDIA_HOSTILE_MULT=10` runs ten times the iterations (soak runs), and +/// `CRAFT_HOSTILE_DIVISOR=8` every eighth truncation and an eighth of the iterations (pull +/// requests). A value that is not a whole number above zero panics, naming the variable, before +/// `run` is called. #[cfg(not(target_arch = "wasm32"))] #[track_caller] pub fn hammer(name: &str, seed: &[u8], iters: usize, run: impl Fn(&[u8]) + Send + Sync + 'static) { diff --git a/crates/media-testkit/src/lib.rs b/crates/media-testkit/src/lib.rs index 58d274451..dde9c9b39 100644 --- a/crates/media-testkit/src/lib.rs +++ b/crates/media-testkit/src/lib.rs @@ -13,12 +13,15 @@ //! //! [`hostile::hammer`] runs a parser over every truncation and mutations of a valid input and fails //! on a panic or a case that does not finish in time; `CRAFT_MEDIA_HOSTILE_MULT=10` runs ten times -//! the iterations. It and [`with_deadline`] call `craft_testkit`. +//! the iterations and `CRAFT_HOSTILE_DIVISOR=8` an eighth of them. It and [`with_deadline`] call +//! `craft_testkit`. +//! [`vmd`] writes Sierra VMD fixtures, which ffmpeg can read but not write. //! //! Failing loudly is what a test helper is for: a wrong `CRAFT_MEDIA_*` setting or an unwritable //! fixture directory panics, which fails the test that asked. pub mod hostile; +pub mod vmd; use std::path::{Path, PathBuf}; use std::process::Command; diff --git a/crates/media-testkit/src/vmd.rs b/crates/media-testkit/src/vmd.rs new file mode 100644 index 000000000..c7068f19c --- /dev/null +++ b/crates/media-testkit/src/vmd.rs @@ -0,0 +1,343 @@ +//! Sierra VMD fixture writer. ffmpeg reads VMD but cannot write it, so the VMD tests build their +//! files here and use ffmpeg only to decode them. Written from the public format description +//! (); the packers favour coverage of every coding +//! mode over compression. + +use crate::hostile::Rng; + +/// Bytes of the file header. +pub const HEADER_LEN: usize = 816; + +/// The audio fields of the header. +#[derive(Clone, Copy, Debug)] +pub struct Audio { + /// Samples per second. + pub sample_rate: u16, + /// The frame length field as stored: negative for 16-bit sound. + pub frame_length: i16, + /// Number of sound buffers. + pub buffers: u16, + /// Audio flags (0x8000 old stereo, 0x200 new stereo). + pub flags: u16, +} + +/// What the header says. +#[derive(Clone, Debug)] +pub struct Spec { + /// Picture width in pixels. + pub width: u16, + /// Picture height in pixels. + pub height: u16, + /// Left coordinate of the picture. + pub left: u16, + /// Top coordinate of the picture. + pub top: u16, + /// 256 R-G-B triplets of 6-bit components. + pub palette: [u8; 768], + /// Size of the unpack buffer for LZ-packed frames. + pub unpack: u32, + /// Video codec version (header bytes 4-5). + pub codec_version: u16, + /// The sound, if the file has any. + pub audio: Option