SpotiFLAC-Mobile/NETWORK_STORAGE.md

# Network storage

Open Settings → Network storage in Material or Mornye. Add a named connection,
choose the protocol, enter its address and optional credentials, then choose
**Connect and save**. The app checks access before saving. Edit the connection
to change credentials or remove it. Removing a connection never deletes files
from the server.

- SMB: `smb://nas/Music/`, optional username, password, and domain. Defaults to
  port 445; explicit ports are supported. The native libsmb2 client negotiates
  SMB 2.0.2, 2.1, 3.0, 3.0.2 or 3.1.1 and supports required signing and encryption.
  SMB1 is never offered. Leave the domain empty unless your server requires it.
  OpenWRT can run Samba4 or ksmbd; use the share name and the same account as
  the other client. Guest access is only attempted when credentials are blank,
  never as an automatic fallback after a named account fails.
- WebDAV: `https://nas.example/dav/music/`, optional HTTP Basic authentication.
  Routers such as GL.iNet use self-signed HTTPS certificates. If validation
  fails, the connection form shows the server origin and SHA-256 fingerprint.
  **Trust certificate and retry** saves that exact certificate exception with
  the connection only after a successful access check. Changing the server
  address or certificate requires a new approval. This applies to browsing,
  artwork, metadata and audio requests through the same transport; certificate
  checking stays enabled for other servers. Paste the `https://` link supplied
  by the router, including its WebDAV port (e.g. 6008), rather than `dav://`.
  GL.iNet documents its self-signed certificate behavior at
  https://docs.gl-inet.com/router/en/4/interface_guide/network_storage/.
- HTTP/HTTPS: direct audio URL or an HTML directory index. This does not scrape
  arbitrary websites, access cloud account APIs, or discover media hidden behind
  JavaScript/login forms. Use the final directory URL; canonical trailing-slash
  redirects are supported. Cross-origin redirects are rejected.

Connections are stored in the platform secure store. Playback sessions contain
opaque connection IDs and relative paths instead of server credentials. A
random-token loopback proxy handles GET, HEAD and byte ranges. Files stream on
demand without making a full local copy; HTTP seeking depends on the server's
range support. Requests have a 20-second connection/read-inactivity timeout.

Browsing alone does not add anything to the Library. Inside an SMB or WebDAV
folder, choose **Add folder to Library** to index that folder and its subfolders.
The source can then be rescanned, disabled or removed in Local Library settings.
Scans read one file's tags at a time and persist embedded artwork on the device;
audio stays on the server. Failed folder/tag reads preserve previously indexed
rows, and a temporarily unreachable NAS does not hide the cached collection.
Network Library tracks use the built-in player and remote file editing/deletion
is unavailable. Adding a folder does not make it a download destination.

## Download destination

Choose **Settings → Files → Network download destination**, browse to an SMB or
WebDAV folder, and select **Download to this folder**. The same button is present
when browsing Network storage normally. A temporary write/delete probe must
succeed before the selection is saved. **Use local download folder** restores
the previously configured local/SAF destination. HTTP directory indexes are
read-only.

Each queued download records its selected network destination. Audio is first
downloaded to a private per-item staging directory. Metadata, embedded cover,
lyrics, track ReplayGain, extension post-processing and automatic conversion
finish locally. Folder organization and the final filename are retained when
uploading; an existing name receives a numbered suffix instead of being
overwritten. LRC sidecars, when enabled, are uploaded alongside the audio.

Transfers stream bounded chunks to a hidden `.part` file, verify its size and
publish with a non-overwriting SMB rename or WebDAV MOVE (`Overwrite: F`, as
specified in https://www.rfc-editor.org/rfc/rfc4918.html#section-9.9.3).
libsmb2 also sets `replace_if_exist=0` for rename. Completion/history is published
only after the transfer succeeds, so the normal Library download history
refresh exposes the playable `network://` entry immediately. Credentials stay
in the secure connection store, never in the transfer journal or history.

A failed transfer retains finalized local audio and an atomic on-disk journal.
Retry, including after an app restart, uploads that audio again without fetching
or processing the song again. A lost publication response is reconciled by
streaming SHA-256 comparison before adopting an existing remote file. Local
staging is removed after history completion or when a failed item is dismissed.
An unreachable NAS may leave a hidden partial file until the same transfer is
retried; existing completed music is never deleted.

Network destinations currently use the shared Flutter queue even when Native
Download Worker is enabled, because the autonomous worker cannot yet perform
the network publication handoff. Keep the app open until upload finishes; this
does not promise transfers after force-stop or indefinite iOS background time.
Track ReplayGain is supported; later album-wide ReplayGain rewriting across
already-published tracks is not. Failed uploads occupy staging space until
retried or removed.

Selecting a song queues audio files in its current folder. Titles initially use
filenames; standard `cover.jpg`, `folder.jpg`, `front.jpg`, `cover.png` and
`folder.png` images in that folder provide initial artwork. When a song plays
or its Lyrics/Details view opens, embedded metadata and lyrics are read using
the same native tag parsers as local files. Embedded artwork takes precedence
over the folder image. LRC timestamps embedded in the lyrics use the regular
synchronized lyrics renderer; plain lyrics remain plain text.

Metadata uses 256 KiB range reads through the same proxy for SMB, WebDAV and
HTTP. Tags at the end of M4A files are reached by seeking past audio data. Each
read has a 20-second budget and a 16 MiB transfer cap, with bounded memory and
cover caches. Playback and Lyrics share in-flight reads and cache results for
five minutes. Large HTTP files require server byte-range support; a tag read
failure leaves playback available with filename/folder artwork fallbacks.

Remote metadata editing, separate sidecar lyric files, offline downloads,
AutoMix and direct USB/DAP bit-perfect output are not part of this browser.
Normal playback uses the platform audio decoder, so codec support follows the
device.

## Validation

`flutter test test/network_upload_test.dart test/network_download_destination_test.dart`
checks authenticated WebDAV writes, MKCOL, MOVE, collision handling, sidecars,
interrupted transfers, lost responses, restart journals, and destination UI in
both themes. The SMB upload test uses the pinned native library and a disposable
Samba fixture with encryption mandatory:
`python3 scripts/test_network_smb3_server.py --port 1446 --writable` and
`TEST_SMB_UPLOAD=1 TEST_SMB_PORT=1446 TEST_SMB_LIBRARY=<host-library> flutter test test/network_smb_upload_test.dart`.
It validates upload, non-overwriting publication and retry reconciliation in
existing folders. This host's unprivileged macOS Samba creates new directories
with mode 000 even with its own smbclient; nested folder creation is covered by
the WebDAV fixture, not claimed as a successful SMB host-device check.

`flutter test test/network_storage_service_test.dart test/network_storage_screen_test.dart`
checks URL/path handling, HTML/WebDAV parsing, authenticated HTTP transport,
range/HEAD requests, connection persistence/removal and browser navigation.

For the optional signed, authenticated SMB2 test, install `impacket` in a
temporary Python virtual environment and run `scripts/test_network_smb_server.py`.
Then run `TEST_SMB=1 flutter test test/network_storage_service_test.dart`.
Set `TEST_SMB_PORT` for the fixture's port (default 1445). For host Flutter tests,
set `TEST_SMB_LIBRARY` to the matching libsmb2 native binary from the pinned
dart_smb2 release. Stop the fixture after testing. `network_smb_transport_test.dart`
captures the actual negotiation packet and checks that SMB3 is offered without
an SMB1 negotiate. Run the same service test against Samba restricted to each
SMB2/3 dialect, with signing mandatory and encryption required for SMB3 tests.

The pinned dart_smb2 0.1.3 plugin verifies native download checksums at build time
(libsmb2-r8). Its LGPL library is dynamically linked. License text is included
in the app's licenses; corresponding build scripts, patches and source are at
https://github.com/ales-drnz/libsmb2-scripts and
https://github.com/sahlberg/libsmb2.

Samba4 fixture (isolated account database, loopback only, no system service):
`python3 scripts/test_network_smb3_server.py --dialect SMB3_11 --encryption required`.
Use `--dialect SMB3_00`, `SMB3_02`, `SMB2_10` or `SMB2_02` to constrain negotiation;
SMB2 requires `--encryption off`. Guest validation uses `--guest --encryption off`
on a second port, passed to the test as `TEST_SMB_GUEST_PORT`.

Android emulator transport validation:
`flutter test integration_test/network_smb_test.dart -d emulator-5554 --dart-define=SMB_TEST_URL=smb://10.0.2.2:1445/MUSIC/`.
For the iOS simulator, use `127.0.0.1` instead of `10.0.2.2`.

The transport was validated against an isolated Samba 4.25 server with mandatory
signing for SMB 2.0.2/2.1 and mandatory encryption for SMB 3.0/3.0.2/3.1.1.
Checks cover empty/WORKGROUP domains, explicit guest access, failed credentials,
share enumeration, file listing, HEAD and byte ranges. These fixtures validate
protocol behavior, not the configuration of a particular OpenWRT router.

`flutter test integration_test/network_playback_test.dart -d <device>` exercises
the real native tag reader with embedded FLAC tags/lyrics and verifies bounded
range transfers and cache reuse. It also exercises the platform decoder with
silent WAV data through the loopback proxy, including preparation, playback
and seeking.

`cargo test -p spotiflac-mobile network_tags --lib` from `rust_backend` checks
FLAC metadata/cover extraction, seeking past M4A audio to tail tags, and rejection
of external URLs and large non-range responses. Flutter metadata service tests
cover shared reads, recoverable failures, and embedded cover caching; the Now
Playing tests also check that network lyrics use the shared metadata result.