Merge remote-tracking branch 'upstream/next' into histogram-native-expand

This commit is contained in:
aiongg committed 2026-11-18 05:28:58 +00:00
commit 04e1f2eda9
292 files changed
+34806 -1125

No files matched your search

+19 -7
View File
@@ -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'
+13
View File
@@ -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
+4 -24
View File
@@ -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'
+7 -19
View File
@@ -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
+7 -21
View File
@@ -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:
+12 -40
View File
@@ -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
+7 -3
View File
@@ -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
+5 -46
View File
@@ -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:
+5 -10
View File
@@ -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
+7 -21
View File
@@ -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
-46
View File
@@ -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
+16 -3
View File
@@ -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
+7 -19
View File
@@ -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
+7 -22
View File
@@ -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
+10 -22
View File
@@ -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 }}
-46
View File
@@ -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
+8 -19
View File
@@ -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
+9 -57
View File
@@ -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
+12 -19
View File
@@ -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.
+3 -8
View File
@@ -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
+34
View File
@@ -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
+8 -19
View File
@@ -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
+14 -61
View File
@@ -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
-51
View File
@@ -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' }}
+9 -17
View File
@@ -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
+3 -2
View File
@@ -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
-84
View File
@@ -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
+9 -20
View File
@@ -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
+8 -19
View File
@@ -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
+12 -18
View File
@@ -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
+6 -12
View File
@@ -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
+7 -18
View File
@@ -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
+9 -20
View File
@@ -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
+55 -39
View File
@@ -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 (<os>)` leg beside each `gate (<os>)` 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
+38
View File
@@ -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.
Generated
+139 -2
View File
@@ -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"
+11 -1
View File
@@ -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-<name> = { path = "crates/<name>" }`
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" }
+1 -1
View File
@@ -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)
+8 -1
View File
@@ -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<Self> {
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<u32> {
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")
+15
View File
@@ -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 }
+5
View File
@@ -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 |
+247
View File
@@ -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<usize> {
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<i16>) -> 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<Vec<i16>> {
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<Vec<u8>> {
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<i16> = 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<Vec<u8>> {
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<i16> = 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));
}
}
+56
View File
@@ -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<T> = std::result::Result<T, Error>;
/// 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)
}
+244
View File
@@ -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<usize> {
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<i16>) -> 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<Vec<i16>> {
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<Vec<u8>> {
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<i16> = 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<u8>, 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<Vec<u8>> {
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<i16> = 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());
}
}
+168
View File
@@ -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<Vec<i16>> {
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<Vec<u8>> {
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<i16> = 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());
}
}
+113
View File
@@ -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<Vec<i16>> {
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<Vec<u8>> {
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());
}
}
+693
View File
@@ -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<i16>) -> 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<u8>) -> 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<Vec<i16>, 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<Vec<u8>, 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<Vec<i16>, 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<Decoder> = 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<Vec<u8>, 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<Encoder> = 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);
}
}
+996
View File
@@ -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<i16>) -> 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<u8>) -> 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<u8>) -> 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<Vec<i16>, 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<Vec<u8>, 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<Vec<i16>, 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<Decoder> = 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<i16>> = 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<Vec<u8>, 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<Encoder> = 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<i16>> = 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<u8>> = 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);
}
}
+25 -4
View File
@@ -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<alac::Error> for AudioError {
}
}
#[cfg(feature = "vmd-decode")]
impl From<vmd::Error> 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<opus::encoder::Error> for AudioError {
fn from(e: opus::encoder::Error) -> Self {
+2 -2
View File
@@ -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};
+493
View File
@@ -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<T> = std::result::Result<T, EncodeError>;
/// 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<bool> {
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<u32> {
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<f32> = (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<Polyphase>,
/// Buffered input per channel, and how much of it is consumed.
input: Vec<Vec<f32>>,
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<Encoder> {
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<u8> {
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<u8> {
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<u8>) {
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::<f32>() / 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::<f32>() / 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<u8>) {
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<ChannelPlan> = 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);
}
}
+18
View File
@@ -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;
+192
View File
@@ -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 <https://wiki.multimedia.cx/index.php/VMD>
//! ("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<Decoder, Error> {
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<Vec<i16>, 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<i16>) -> 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(())
}
}
+96
View File
@@ -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<u32, Eop> {
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<bool, Eop> {
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})");
}
}
}
+409
View File
@@ -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<Node>,
/// The only used entry of a single-entry book.
single: Option<u32>,
/// `entries * dimensions` values when the book has a lookup table.
vectors: Vec<f32>,
}
/// `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<Node>, 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<Self, Error> {
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<u8> = 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::<Node>();
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::<f32>())
.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<u32> = (0..values).map(|_| r.read(value_bits).unwrap_or(0)).collect();
*budget -= total * std::mem::size_of::<f32>();
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<u32, Eop> {
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<Option<&[f32]>, 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<u8>, 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<u8> {
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::<Node>() + 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");
}
}
}
+385
View File
@@ -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<Eop> for Fail {
fn from(_: Eop) -> Self {
Fail::Eop
}
}
/// What a decoded floor gives to synthesis.
pub(super) enum FloorData {
One { y: Vec<i32>, step2: Vec<bool> },
Zero { amplitude: u32, coefficients: Vec<f32> },
}
pub(super) struct Floor0 {
order: usize,
rate: u32,
bark_map_size: u32,
amplitude_bits: u32,
amplitude_offset: u32,
books: Vec<usize>,
}
pub(super) struct Floor1 {
partition_class: Vec<usize>,
class_dimensions: Vec<usize>,
class_subclasses: Vec<u32>,
class_masterbook: Vec<usize>,
subclass_books: Vec<Vec<i32>>,
multiplier: i32,
range: i32,
xlist: Vec<i32>,
/// `(low, high)` neighbour positions of each X from index 2 on.
neighbours: Vec<(usize, usize)>,
/// Indices of `xlist` in ascending X order.
sorted: Vec<usize>,
}
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<Self, Error> {
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<usize> = (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<Option<FloorData>, 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<f32> {
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<Option<FloorData>, 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<f32> {
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<Option<FloorData>, 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<f32> = 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<f32> {
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<i64> = (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<f64> = 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);
}
}
+164
View File
@@ -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<Cpx>,
post: Vec<Cpx>,
fft_tw: Vec<Cpx>,
rev: Vec<usize>,
}
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<Cpx> = (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<f32> {
(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<f32> = (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<f64> = (0..n * 6).map(|i| ((i * 37 % 101) as f64 - 50.0) / 50.0).collect();
let w: Vec<f32> = 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<f32> = (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}");
}
}
}
+552
View File
@@ -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<T> = std::result::Result<T, Error>;
/// 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<String>,
}
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<BitReader<'_>> {
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<Identification> {
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<Comments> {
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<usize>,
/// `(floor, residue)` of each submap.
submaps: Vec<(usize, usize)>,
}
struct Mode {
long: bool,
mapping: usize,
}
struct Setup {
books: Vec<Codebook>,
floors: Vec<Floor>,
residues: Vec<Residue>,
mappings: Vec<Mapping>,
modes: Vec<Mode>,
}
/// 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<Setup> {
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<Vec<f32>>,
}
/// A Vorbis I packet decoder.
pub struct Decoder {
id: Identification,
comments: Comments,
setup: Setup,
imdct: [Imdct; 2],
slopes: [Vec<f32>; 2],
previous: Option<Previous>,
}
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<Self> {
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<f32> {
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<Vec<Vec<f32>>> {
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<f32>> = 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<Vec<Vec<f32>>> {
let zero = || vec![vec![0f32; half]; channels];
let setup = &self.setup;
// Floors, in channel order.
let mut floors: Vec<Option<FloorData>> = 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<bool> = 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<usize> = (0..channels).filter(|&c| mapping.mux[c] == i).collect();
if members.is_empty() {
continue;
}
let skip: Vec<bool> = 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<Vec<f32>>,
/// 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<Decoded> {
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<f32>], pcm: Vec<Vec<f32>>, 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::<f32>()) {
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");
}
}
+196
View File
@@ -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<usize>; 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<Self, Error> {
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<f32>]) {
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<f32>]) -> 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::<u8>::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
}
}
}
+263
View File
@@ -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,
];
+5 -2
View File
@@ -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;
+516
View File
@@ -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<i16> {
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<i16>, 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<u8>)> = 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<i16> {
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<i16> {
let mut bitpos = 0usize;
let mut get = |n: usize| -> Option<u32> {
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<u8>, Vec<i16>, Vec<i16>);
// ---- 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::<Vec<u8>>()).expect("write");
}
fn read_pcm(path: &Path) -> Vec<i16> {
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<u8>) {
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<u8> {
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<String> = 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::<Vec<_>>());
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<u8> = 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<Stream> = {
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<Vec<u8>> {
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<u8>]) -> Vec<u8> {
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<i16> = 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<i16> = 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<Vec<u8>> = x.chunks(4096 * channels).map(|c| swf::encode(c, channels, bits).expect("encode")).collect();
let ours: Vec<i16> = 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<i16> = 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);
}
}
}
+201
View File
@@ -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<i16> {
(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<i16> = 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<i16> = 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}");
}
+218
View File
@@ -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::<f64>() / (n as f64);
let mean_y = y.iter().map(|&v| v as f64).sum::<f64>() / (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<String> {
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<i16> = 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<i16> = 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:?}"
);
}
}
}
+24
View File
@@ -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;
+228
View File
@@ -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<f32> {
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::<f32>()
})
.collect()
}
fn noise(n: usize, amp: f32, seed: u64) -> Vec<f32> {
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<f32>], chunk: usize) -> Vec<u8> {
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<f32>,
min_snr: f64,
}
fn sig_chords(rate: u32, n: usize, c: usize) -> Vec<f32> {
chords(rate, n, 0.003 * c as f32)
}
fn sig_noise(_rate: u32, n: usize, c: usize) -> Vec<f32> {
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<Vec<f32>> {
(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<Vec<f32>>, 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<f32> = 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::<f64>() / 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);
}
}
+280
View File
@@ -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<u8>, Vec<i16>) {
let n = d.block_samples() * d.channels();
if d.bits() == 8 {
let bytes: Vec<u8> = (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<i16> = (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<u8>, Vec<i16>) {
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<i16> {
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<i16> = 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<u8>)| {
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<i16> = 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");
}
+230
View File
@@ -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<u8>,
headers: Vec<Vec<u8>>,
packets: Vec<Vec<u8>>,
}
fn parts(channels: usize) -> Parts {
let signal: Vec<Vec<f32>> = (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<u8>, 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<u8> {
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<u8>| 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(_))));
}
+216
View File
@@ -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<Vec<f32>> {
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<Vec<f32>> {
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<f32> = 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<f32>], theirs: &[Vec<f32>]) {
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<f32>], theirs: &[Vec<f32>], 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<f32> = {
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::<Vec<u8>>()).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<f32>> = 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]]);
}
@@ -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<u8>,
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<u32>)>) {
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<u8>,
coupling: Vec<(u8, u8)>,
}
fn identification(channels: u8) -> Vec<u8> {
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<u8> {
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<u8> {
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<bool> = (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<f32> = out.stdout.as_chunks::<4>().0.iter().map(|b| f32::from_le_bytes(*b)).collect();
let ch = usize::from(l.channels);
let theirs: Vec<Vec<f32>> = (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");
}
+10 -7
View File
@@ -49,18 +49,21 @@ fn monitor(files: &Arc<Disk>, jobs: &Arc<ManualJobs>) -> LinkMonitor<u32> {
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);
+6 -2
View File
@@ -101,11 +101,15 @@ fn linked_keys(result: &DialogResult<RelinkOutcome<u32>>) -> (Vec<u32>, Vec<u32>
(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();
+25
View File
@@ -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 }
+39
View File
@@ -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.
+510
View File
@@ -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<String>) -> 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<PathBuf, Fault> {
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, Fault> {
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<Vec<Entry>, 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<u8>), 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<Entry, Fault> {
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<Entry, Fault> {
// `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:?}");
}
}
}
+244
View File
@@ -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<Mutex<Vec<(String, Vec<u8>)>>>;
/// 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<Mutex<Vec<String>>>,
}
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<u64> {
None
}
fn title(&self, _uid: u64) -> String {
String::new()
}
fn open_bytes(&mut self, name: &str, bytes: Vec<u8>) -> Result<Option<u64>, String> {
self.opened.lock().unwrap().push((name.to_owned(), bytes));
Ok(Some(1))
}
fn encode(&mut self, _uid: u64, _into: Destination<'_>) -> Result<Vec<u8>, 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<u8> {
std::fs::read(root.join(name)).unwrap()
}
@@ -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<Mutex<Vec<(String, Vec<u8>)>>>;
struct Harness {
cloud: CloudFiles,
share: craft_ui::share::ShareDialog,
presence: craft_ui::presence::PresenceBar,
opened: OpenedDocs,
said: Arc<Mutex<Vec<String>>>,
}
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<u64> {
None
}
fn title(&self, _uid: u64) -> String {
String::new()
}
fn open_bytes(&mut self, name: &str, bytes: Vec<u8>) -> Result<Option<u64>, String> {
self.opened.lock().unwrap().push((name.to_owned(), bytes));
Ok(Some(1))
}
fn encode(&mut self, _uid: u64, _into: Destination<'_>) -> Result<Vec<u8>, 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<String> {
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);
}
@@ -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<u8>,
said: Arc<Mutex<Vec<String>>>,
}
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<u64> {
Some(1)
}
fn title(&self, _uid: u64) -> String {
String::new()
}
fn open_bytes(&mut self, _name: &str, bytes: Vec<u8>) -> Result<Option<u64>, String> {
self.body = bytes;
Ok(Some(1))
}
fn encode(&mut self, _uid: u64, _into: Destination<'_>) -> Result<Vec<u8>, 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}");
}
+34
View File
@@ -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"] }
+67
View File
@@ -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.
+449
View File
@@ -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<String>,
/// 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<String>, display: impl Into<String>) -> 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<Account>,
/// 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<String>,
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<AccountAction>, Receiver<AccountAction>),
}
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<Account>) {
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<AccountAction> {
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<Account> = 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}");
}
}
+18
View File
@@ -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,
));
}
+258
View File
@@ -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<String>, label: impl Into<String>) -> 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<u64>;
/// 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<u8>) -> Result<Option<u64>, 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<Vec<u8>, 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<String> {
None
}
/// The colours and faces to draw in.
fn style(&self, ui: &Ui) -> CloudStyle {
CloudStyle::from_visuals(ui.visuals())
}
}
+213
View File
@@ -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<u64> },
/// Save back over `entry`, refusing to overwrite a newer version.
Write { uid: u64, entry: Entry, bytes: Vec<u8> },
/// Save under a new name in `folder`.
Create { uid: u64, folder: String, name: String, bytes: Vec<u8> },
/// 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<Conversation, Fault>),
Account(Result<Account, Fault>),
/// 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<String>,
},
/// `Ok(true)` means the account is linked now.
Linked(Result<bool, Fault>),
Listed {
path: String,
entries: Result<Vec<Entry>, Fault>,
},
Shared(Result<Vec<Entry>, Fault>),
Read {
entry: Entry,
into: Option<u64>,
bytes: Result<Vec<u8>, Fault>,
},
Saved {
uid: u64,
entry: Result<Entry, Fault>,
},
}
/// 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<Event>,
/// 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<AtomicU64>,
issued: u64,
}
impl Post {
pub(crate) fn new(tx: Sender<Event>, generation: Arc<AtomicU64>) -> 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<Capability>,
/// 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<craft_cloud::Error> 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()),
}
}
}
+315
View File
@@ -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<String>,
encoded: Vec<u64>,
closed: Vec<u64>,
said: Vec<String>,
}
struct Tabs {
cloud: CloudFiles,
share: crate::share::ShareDialog,
presence: crate::presence::PresenceBar,
active: u64,
next_uid: u64,
log: Arc<Mutex<Log>>,
}
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<u64> {
Some(self.active)
}
fn title(&self, uid: u64) -> String {
format!("doc {uid}")
}
fn open_bytes(&mut self, name: &str, _bytes: Vec<u8>) -> Result<Option<u64>, 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<Vec<u8>, 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<Mutex<Vec<(Job, Post)>>>);
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<Mutex<Log>>) {
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<Mutex<Log>>) {
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()));
}
+901
View File
@@ -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<Entry>,
pub loading: bool,
pub error: Option<Fault>,
/// 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<Vec<Entry>, 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<String>,
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<Box<dyn CloudBackend>>,
events: (Sender<Event>, Receiver<Event>),
/// 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<Account>,
pub account_fault: Option<Fault>,
/// 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<Busy>,
pub link: Option<Link>,
pub conflict: Option<Conflict>,
/// Save As: the file name being typed.
pub save_name: String,
/// Documents that came from the cloud, by document uid.
pub origins: HashMap<u64, Origin>,
/// The last thing that happened, for the line under the page title.
pub status: Option<String>,
/// 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<Guest>,
/// 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<AtomicU64>,
/// 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<u64>,
}
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<String>, 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<A: CloudApp>(app: &A) -> bool {
app.cloud().available()
}
/// Whether the provider offers somewhere to talk about a document.
pub fn can_converse<A: CloudApp>(app: &A) -> bool {
app.cloud().can_converse()
}
/// Hands a job to the host's worker.
pub fn submit<A: CloudApp>(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<A: CloudApp>(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<A: CloudApp>(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<A: CloudApp>(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<A: CloudApp>(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<A: CloudApp>(app: &mut A) {
if !available(app) {
return;
}
app.cloud_mut().shared.begin("");
submit(app, Job::SharedWithMe);
}
/// Begins linking a cloud account.
pub fn link<A: CloudApp>(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<A: CloudApp>(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<A: CloudApp>(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<String> {
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<A: CloudApp>(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<A: CloudApp>(app: &mut A, entry: Entry, into: Option<u64>) {
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<A: CloudApp>(app: &mut A) -> Result<Json, String> {
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<A: CloudApp>(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<A: CloudApp>(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<A: CloudApp>(app: &mut A) -> Result<Json, String> {
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<A: CloudApp>(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<A: CloudApp>(app: &mut A, folder: &str, name: &str) -> Result<Json, String> {
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<A: CloudApp>(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<A: CloudApp>(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<A: CloudApp>(app: &mut A, entry: Entry, into: Option<u64>, bytes: Vec<u8>) {
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<A: CloudApp>(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<A: CloudApp>(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<A: CloudApp>(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::<Vec<_>>(),
})
});
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::<Vec<_>>(),
"openable": cloud.mine.entries.iter().filter(|e| opens(e, kind)).map(|e| e.name.clone()).collect::<Vec<_>>(),
"shared": cloud.shared.entries.iter().map(|e| json!({"name": e.name, "sharedBy": e.shared_by, "writable": e.writable, "openable": opens(e, kind)})).collect::<Vec<_>>(),
"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<u64>) -> 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<A: CloudApp>(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
}
+519
View File
@@ -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<A: CloudApp>(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<A: CloudApp>(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<String> = 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<A: CloudApp>(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<A: CloudApp>(app: &A, ui: &mut Ui, entry: &Entry) -> Option<String> {
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<A: CloudApp>(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<String> = None;
let mut act: Option<Act> = 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<A: CloudApp>(app: &mut A, ui: &mut Ui, pick: &mut Option<(Entry, Source)>, go: &mut Option<String>, act: &mut Option<Act>) {
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, &nothing);
}
});
}
/// 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<A: CloudApp>(app: &mut A, ui: &mut Ui, pick: &mut Option<(Entry, Source)>, act: &mut Option<Act>) {
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<A: CloudApp>(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<String> = 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, &note);
}
// 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<A: CloudApp>(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,
}
+573
View File
@@ -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<String>,
closed: Vec<u64>,
encoded: Vec<u64>,
/// The name each encode was asked for, which is where the bytes go.
encoded_as: Vec<String>,
/// The content type beside it, where the provider gave one.
encoded_mime: Vec<Option<String>>,
marked_saved: Vec<u64>,
dropped: Vec<u64>,
said: Vec<String>,
toasted: Vec<String>,
urls: Vec<String>,
conversations: Vec<String>,
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<Option<u64>, String>,
did: Arc<Mutex<Did>>,
}
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<u64> {
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<u8>) -> Result<Option<u64>, String> {
self.did().opened.push(name.to_owned());
self.opens_as.clone()
}
fn encode(&mut self, uid: u64, into: Destination<'_>) -> Result<Vec<u8>, 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<Mutex<Vec<Job>>>);
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<Mutex<Vec<Job>>>, 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<String> {
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::<String>::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}));
}
+173
View File
@@ -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<A: CloudApp>(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<A: CloudApp>(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<A: CloudApp>(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<A: CloudApp>(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<A: CloudApp>(app: &mut A, ui: &mut Ui, copies: &[CopyFormat]) -> Option<String> {
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<A: CloudApp>(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<A: CloudApp>(app: &A) -> bool {
available(app) && origin(app).is_some()
}
+20
View File
@@ -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;
+222
View File
@@ -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<String>,
/// A leading glyph. Decoration only, so it is never the accessible name.
pub icon: Option<String>,
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<String>, label: impl Into<String>) -> MenuItem {
MenuItem { id: id.into(), label: label.into(), enabled: true, ..MenuItem::default() }
}
pub fn detail(mut self, detail: impl Into<String>) -> MenuItem {
self.detail = Some(detail.into());
self
}
pub fn icon(mut self, icon: impl Into<String>) -> 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<String>) -> 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<String> {
// 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<SplitHit> {
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<SplitHit>| {
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<SplitHit>| {
// 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<String> {
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);
}
}
+424
View File
@@ -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<String>,
}
impl Peer {
pub fn new(id: impl Into<String>, display: impl Into<String>) -> 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<String>) -> 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<Color32> {
let mut order: Vec<usize> = (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<Peer>,
/// 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<Peer>) {
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<String> {
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::<Vec<_>>().join("\n"));
}
let ids: Vec<String> = 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<String> {
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<String> = (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::<Vec<_>>());
}
#[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}");
}
}
+170
View File
@@ -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<String>,
/// The document, as an opaque handle the app was given.
pub id: String,
pub targets: Vec<ShareTarget>,
pub permission: Permission,
pub note: Option<String>,
pub notify: bool,
}
/// What came back.
#[derive(Clone, Debug, PartialEq, Eq)]
pub enum Answer {
Capabilities {
capabilities: Vec<Capability>,
/// Whether this user has a cloud account attached at all.
linked: bool,
},
Lookup(Vec<Contact>),
Access(Vec<Share>),
/// Partial success is the ordinary case, so both halves come back.
Granted {
shared: Vec<Share>,
failed: Vec<Failure>,
},
Withdrawn {
share_id: String,
},
Destinations(Vec<Destination>),
/// 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<u8>,
},
}
/// 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<String>,
/// 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<Answer, String>)>,
}
impl Replier {
pub(crate) fn new(seq: u64, tx: std::sync::mpsc::Sender<(u64, Result<Answer, String>)>) -> 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<String>) {
self.deliver(Err(reason.into()));
}
/// A dropped receiver means the dialog closed, which is not a failure.
fn deliver(self, result: Result<Answer, String>) {
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);
}
File diff suppressed because it is too large. Load diff
+527
View File
@@ -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<Mutex<Vec<Request>>>);
impl Silent {
fn seen(&self) -> Vec<Request> {
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<Capability>) -> 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<Share> =
["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::<Vec<_>>()), 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");
}
+343
View File
@@ -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<Capability>,
access: Vec<Share>,
parked: Arc<Mutex<Vec<(Request, Replier)>>>,
}
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<Event>, 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<accesskit::Rect>,
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<Pos2> {
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<Seen> {
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<Pos2> {
seen(output).iter().find(|s| s.interactive() && !s.disabled && s.label == label).and_then(Seen::at)
}
fn controls(output: &FullOutput) -> Vec<String> {
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<Capability> {
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<Capability>, Vec<Share>, &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);
}
}
+589
View File
@@ -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<Request>,
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<Mutex<Log>>,
capabilities: Vec<Capability>,
access: Vec<Share>,
}
impl Fake {
fn new(capabilities: Vec<Capability>, access: Vec<Share>) -> Fake {
Fake { log: Arc::new(Mutex::new(Log::default())), capabilities, access }
}
fn seen(&self) -> Vec<Request> {
self.log.lock().map(|log| log.seen.clone()).unwrap_or_default()
}
fn parked(&self) -> Vec<Request> {
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<Capability>, access: Vec<Share>) -> (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<Event>) -> 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<accesskit::Rect>,
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<Pos2> {
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<Seen> {
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<Pos2> {
seen(output).iter().find(|s| s.interactive() && !s.disabled && s.label == label).and_then(Seen::at)
}
fn controls(output: &FullOutput) -> Vec<String> {
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<String> {
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<String> {
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<Contact>) -> 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"));
}
+15
View File
@@ -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 }
+68
View File
@@ -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<String>) -> Error {
Error::NotFound { what, id: id.into() }
}
pub fn malformed(what: &'static str, detail: impl Into<String>) -> Error {
Error::Malformed { what, detail: detail.into() }
}
pub fn invalid(what: &'static str, detail: impl Into<String>) -> 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<T> = std::result::Result<T, Error>;
+189
View File
@@ -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<Vec<Entry>>;
/// 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<Vec<Entry>>;
/// One document's bytes.
fn read(&self, id: &str) -> Result<Vec<u8>>;
/// 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<Vec<u8>> {
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<Entry>;
/// Create a document and return it.
fn create(&self, folder: &str, name: &str, bytes: &[u8]) -> Result<Entry>;
/// One document's metadata, without its bytes.
fn stat(&self, id: &str) -> Result<Entry>;
}
/// 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<Share>;
/// Who currently has access.
fn shares(&self, id: &str) -> Result<Vec<Share>>;
/// 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<Vec<Contact>>;
}
/// 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<Identity>;
}
/// 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<String> {
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<Conversation> {
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<Capability>;
fn supports(&self, capability: Capability) -> bool {
self.capabilities().contains(&capability)
}
}
Loaded 100 of 292 files, more files were not shown because too many files have changed in this diff. Show more