DragonSpirit/NXST
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

finish refactor, add docs and CI
CI / Build NRO (push) Has been cancelled
Details
CI / Upload release asset (push) Has been cancelled
Details
CI / Format check (push) Has been cancelled
Details
CI / Layering check (push) Has been cancelled
Details

Browse Source
This commit is contained in:
Nikolai Fedorov
2026-04-27 01:49:41 +03:00
parent dc65a4c8a9
commit 7bd6a90bde
9 changed files with 502 additions and 207 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/build.yml
+72
View File
@@ -0,0 +1,72 @@
name: CI
on:
push:
pull_request:
jobs:
nro:
name: Build NRO
runs-on: ubuntu-latest
container:
image: devkitpro/devkita64:latest
steps:
- uses: actions/checkout@v4
with:
submodules: recursive
- name: Configure
run: cmake --preset switch
- name: Build
run: cmake --build build -j$(nproc)
- uses: actions/upload-artifact@v4
with:
name: NXST-${{ github.sha }}
path: build/NXST.nro
release:
name: Upload release asset
runs-on: ubuntu-latest
needs: nro
if: startsWith(github.ref, 'refs/tags/v')
permissions:
contents: write
steps:
- uses: actions/download-artifact@v4
with:
name: NXST-${{ github.sha }}
- uses: softprops/action-gh-release@v2
with:
files: NXST.nro
format:
name: Format check
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install clang-format
run: sudo apt-get install -y clang-format
- name: Check formatting
run: |
find src include \( -name '*.cpp' -o -name '*.hpp' \) \
| xargs clang-format --dry-run --Werror
layering:
name: Layering check
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: UI must not include net/sys headers
run: |
! grep -rE '^#include\s*[<"](arpa/inet|sys/socket|pthread)' src/ui/
CHANGELOG.md
+34
View File
@@ -0,0 +1,34 @@
# Changelog
All notable changes to NXST follow [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
Version numbers are calendar-based (`MM.DD.YYYY`) until the protocol stabilises.
---
## [Unreleased]
### Changed
- Full architectural refactor (8 phases):
- Layered directory structure: `src/` + `include/nxst/` mirroring domain / infra / service / ui
- CMake build system replacing Makefile
- `nxst::TransferService` — all network state and threads moved out of UI layer
- `nxst::Result<T>` tagged-union type replacing `std::tuple<bool, Result, std::string>`
- RAII handles: `FsFileSystemHandle`, `FileHandle`
- Logger rewritten with `nxst::log` namespace and compile-time format checking
- snake_case filenames and identifiers throughout
### Fixed
- `mkdir(path, 777)` was decimal (octal `01411`) — corrected to `0777`
- Logger format args were silently dropped (double-substitution bug)
- `new u8[]` / `malloc` in IO paths replaced with `std::vector`
---
## [04.26.2026]
### Added
- Initial public release: save transfer between two Nintendo Switch consoles over local Wi-Fi
- Multicast discovery (UDP `239.0.0.1:8081`) + TCP file transfer (`:8080`)
- Send and Receive modes with progress overlay and cancel support
- Automatic save backup before transfer
- Restore replaces live save data and commits to the save device
CMakePresets.json
+17
View File
@@ -0,0 +1,17 @@
{
"version": 6,
"configurePresets": [
{
"name": "switch",
"displayName": "Nintendo Switch",
"toolchainFile": "$env{DEVKITPRO}/cmake/Switch.cmake",
"binaryDir": "${sourceDir}/build"
}
],
"buildPresets": [
{
"name": "switch",
"configurePreset": "switch"
}
]
}
LICENSE
+30
View File
@@ -0,0 +1,30 @@
GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The GNU General Public License is a free, copyleft license for
software and other kinds of works.
For the full license text see <https://www.gnu.org/licenses/gpl-3.0.txt>.
-------------------------------------------------------------------------------
NXST includes code derived from Checkpoint by Bernardo Giordano / FlagBrew,
licensed under GPLv3. The derived files are:
src/infra/fs/io.cpp
src/domain/account.cpp
src/domain/title.cpp
include/nxst/infra/fs/filesystem.hpp
src/infra/fs/filesystem.cpp
src/infra/fs/directory.cpp
All original NXST code is also released under the GNU General Public
License v3 or later, to satisfy the license inheritance requirement.
Original Checkpoint repository: https://github.com/BernardoGiordano/Checkpoint
Makefile
-204
View File
@@ -1,204 +0,0 @@
#---------------------------------------------------------------------------------
.SUFFIXES:
#---------------------------------------------------------------------------------
ifeq ($(strip $(DEVKITPRO)),)
$(error "Please set DEVKITPRO in your environment. export DEVKITPRO=<path to>/devkitpro")
endif
TOPDIR ?= $(CURDIR)
include $(DEVKITPRO)/libnx/switch_rules
#---------------------------------------------------------------------------------
# TARGET is the name of the output
# BUILD is the directory where object files & intermediate files will be placed
# SOURCES is a list of directories containing source code
# DATA is a list of directories containing data files
# INCLUDES is a list of directories containing header files
# EXEFS_SRC is the optional input directory containing data copied into exefs, if anything this normally should only contain "main.npdm".
# ROMFS is the directory containing data to be added to RomFS, relative to the Makefile (Optional)
#
# NO_ICON: if set to anything, do not use icon.
# NO_NACP: if set to anything, no .nacp file is generated.
# APP_TITLE is the name of the app stored in the .nacp file (Optional)
# APP_AUTHOR is the author of the app stored in the .nacp file (Optional)
# APP_VERSION is the version of the app stored in the .nacp file (Optional)
# APP_TITLEID is the titleID of the app stored in the .nacp file (Optional)
# ICON is the filename of the icon (.jpg), relative to the project folder.
# If not set, it attempts to use one of the following (in this order):
# - <Project name>.jpg
# - icon.jpg
# - <libnx folder>/default_icon.jpg
#---------------------------------------------------------------------------------
TARGET := NXST
BUILD := build
SOURCES := src/app src/domain src/infra/net src/infra/fs src/infra/sys src/service src/ui lib/Plutonium/source
INCLUDES := include lib/Plutonium/include
EXEFS_SRC := exefs_src
APP_TITLE := NXST
APP_AUTHOR := DragonSpirit
APP_VERSION := 04.26.2026
ICON := icon.png
#---------------------------------------------------------------------------------
# options for code generation
#---------------------------------------------------------------------------------
ARCH := -march=armv8-a+crc+crypto -mtune=cortex-a57 -mtp=soft -fPIE
CFLAGS += -g -O2 -ffunction-sections $(ARCH) $(DEFINES)
CFLAGS += $(INCLUDE) -D__SWITCH__ -D_GNU_SOURCE=1
CXXFLAGS:= $(CFLAGS) -fno-rtti -fno-exceptions -std=gnu++17 -g
ASFLAGS := -g $(ARCH)
LDFLAGS = -specs=$(DEVKITPRO)/libnx/switch.specs -g $(ARCH) -Wl,-Map,$(notdir $*.map)
PKGCONF := $(DEVKITPRO)/portlibs/switch/bin/aarch64-none-elf-pkg-config
PKG_LIBS := SDL2_ttf SDL2_gfx SDL2_image SDL2_mixer freetype2 harfbuzz minizip libpng libjpeg libwebp glesv2 egl glapi zlib
LIBS := -lpu $(shell $(PKGCONF) --libs $(PKG_LIBS)) -ldrm_nouveau -lharfbuzz -lfreetype -lz
#---------------------------------------------------------------------------------
# list of directories containing libraries, this must be the top level containing
# include and lib
#---------------------------------------------------------------------------------
LIBDIRS := $(PORTLIBS) $(LIBNX) $(CURDIR)/lib/Plutonium
#---------------------------------------------------------------------------------
# no real need to edit anything past this point unless you need to add additional
# rules for different file extensions
#---------------------------------------------------------------------------------
ifneq ($(BUILD),$(notdir $(CURDIR)))
#---------------------------------------------------------------------------------
export OUTPUT := $(CURDIR)/$(TARGET)
export TOPDIR := $(CURDIR)
export VPATH := $(foreach dir,$(SOURCES),$(CURDIR)/$(dir)) \
$(foreach dir,$(DATA),$(CURDIR)/$(dir))
export DEPSDIR := $(CURDIR)/$(BUILD)
CFILES := $(foreach dir,$(SOURCES),$(notdir $(wildcard $(dir)/*.c)))
CPPFILES := $(foreach dir,$(SOURCES),$(notdir $(wildcard $(dir)/*.cpp)))
SFILES := $(foreach dir,$(SOURCES),$(notdir $(wildcard $(dir)/*.s)))
BINFILES := $(foreach dir,$(DATA),$(notdir $(wildcard $(dir)/*.*)))
#---------------------------------------------------------------------------------
# use CXX for linking C++ projects, CC for standard C
#---------------------------------------------------------------------------------
ifeq ($(strip $(CPPFILES)),)
#---------------------------------------------------------------------------------
export LD := $(CC)
#---------------------------------------------------------------------------------
else
#---------------------------------------------------------------------------------
export LD := $(CXX)
#---------------------------------------------------------------------------------
endif
#---------------------------------------------------------------------------------
export OFILES_BIN := $(addsuffix .o,$(BINFILES))
export OFILES_SRC := $(CPPFILES:.cpp=.o) $(CFILES:.c=.o) $(SFILES:.s=.o)
export OFILES := $(OFILES_BIN) $(OFILES_SRC)
export HFILES_BIN := $(addsuffix .h,$(subst .,_,$(BINFILES)))
export INCLUDE := $(foreach dir,$(INCLUDES),-I$(CURDIR)/$(dir)) \
$(foreach dir,$(LIBDIRS),-I$(dir)/include) \
-I$(CURDIR)/$(BUILD)
export LIBPATHS := $(foreach dir,$(LIBDIRS),-L$(dir)/lib)
export BUILD_EXEFS_SRC := $(TOPDIR)/$(EXEFS_SRC)
ifeq ($(strip $(ICON)),)
icons := $(wildcard *.jpg)
ifneq (,$(findstring $(TARGET).jpg,$(icons)))
export APP_ICON := $(TOPDIR)/$(TARGET).jpg
else
ifneq (,$(findstring icon.jpg,$(icons)))
export APP_ICON := $(TOPDIR)/icon.jpg
endif
endif
else
export APP_ICON := $(TOPDIR)/$(ICON)
endif
ifeq ($(strip $(NO_ICON)),)
export NROFLAGS += --icon=$(APP_ICON)
endif
ifeq ($(strip $(NO_NACP)),)
export NROFLAGS += --nacp=$(CURDIR)/$(TARGET).nacp
endif
ifneq ($(APP_TITLEID),)
export NACPFLAGS += --titleid=$(APP_TITLEID)
endif
ifneq ($(ROMFS),)
export NROFLAGS += --romfsdir=$(CURDIR)/$(ROMFS)
endif
.PHONY: $(BUILD) clean all
#---------------------------------------------------------------------------------
all: $(BUILD)
$(BUILD):
@[ -d $@ ] || mkdir -p $@
@$(MAKE) --no-print-directory -C $(BUILD) -f $(CURDIR)/Makefile
#---------------------------------------------------------------------------------
clean:
@echo clean ...
@rm -fr $(BUILD) $(TARGET).pfs0 $(TARGET).nso $(TARGET).nro $(TARGET).nacp $(TARGET).elf $(TARGET).lst
cleanbuild: clean all
#---------------------------------------------------------------------------------
send: $(BUILD)
@nxlink $(TARGET).nro
debug: $(BUILD)
@nxlink -s $(TARGET).nro
else
.PHONY: all
DEPENDS := $(OFILES:.o=.d)
#---------------------------------------------------------------------------------
# main targets
#---------------------------------------------------------------------------------
all : $(OUTPUT).pfs0 $(OUTPUT).nro
$(OUTPUT).pfs0 : $(OUTPUT).nso
$(OUTPUT).nso : $(OUTPUT).elf
ifeq ($(strip $(NO_NACP)),)
$(OUTPUT).nro : $(OUTPUT).elf $(OUTPUT).nacp
else
$(OUTPUT).nro : $(OUTPUT).elf
endif
$(OUTPUT).elf : $(OFILES)
$(OFILES_SRC) : $(HFILES_BIN)
#---------------------------------------------------------------------------------
# you need a rule like this for each extension you use as binary data
#---------------------------------------------------------------------------------
%.bin.o %_bin.h : %.bin
#---------------------------------------------------------------------------------
@echo $(notdir $<)
@$(bin2o)
-include $(DEPENDS)
#---------------------------------------------------------------------------------------
endif
#---------------------------------------------------------------------------------------
PLAN.md
+3 -3
View File
@@ -11,10 +11,10 @@
| 4 | Make → CMake migration | ✅ Done | M (~1d) | devkitpro `Switch.cmake` toolchain |
| 5 | TransferService extraction | ✅ Done | L (~2d) | kill globals, sever UI ↔ net coupling |
| 6 | `Result<T>` + RAII | ✅ Done | M (~1d) | tagged union, OS handle wrappers, fix raw memory |
| 7 | Documentation + license | ☐ Not started | S (~half-day) | README, ARCHITECTURE, PROTOCOL, CHANGELOG, GPLv3 LICENSE |
| 8 | CI | ☐ Not started | S (~2h) | GitHub Actions, `.nro` artifact, format check, layering check |
| 7 | Documentation + license | ✅ Done | S (~half-day) | README, ARCHITECTURE, PROTOCOL, CHANGELOG, GPLv3 LICENSE |
| 8 | CI | ✅ Done | S (~2h) | GitHub Actions, `.nro` artifact, format check, layering check |
**Active phase:** Phase 7 — Documentation + license.
**Active phase:** — All phases complete.
**Last updated:** 2026-04-27.
Mark a phase `🟡 In progress` when starting and `✅ Done` when verified on hardware. Keep this table the source of truth.
README.md
+88
View File
@@ -0,0 +1,88 @@
# NXST
Transfer save data between two Nintendo Switch consoles over local Wi-Fi.
Pick a game, pick a user. One Switch sends; the other receives. The sender backs up its own save first, so you can never lose data in transit.
---
## Install
1. Download `NXST.nro` from [Releases](../../releases).
2. Copy it to `/switch/NXST/NXST.nro` on your SD card.
3. Launch via hbmenu (hold R while starting any game, or Album).
Both Switches must be on the same Wi-Fi network. No router configuration needed — discovery uses UDP multicast.
---
## Usage
**Sender** (the Switch whose save you want to copy):
1. Open NXST → select a title → press **A** → **Transfer**.
2. Wait for "Waiting for receiver…" to change to "Transferring…".
**Receiver** (the Switch that will receive the save):
1. Open NXST → select the same title → press **A** → **Receive**.
2. Wait. The save is restored automatically when the transfer finishes.
Press **B** on either side to cancel mid-transfer.
Logs are written to `/switch/NXST/log.log`.
---
## Build
**Prerequisites:** [devkitPro](https://devkitpro.org/wiki/Getting_Started) with `switch-dev` and `switch-portlibs` packages, plus `cmake ≥ 3.20`.
```bash
# Clone with submodules (Plutonium UI)
git clone --recurse-submodules https://github.com/your-username/NXST.git
cd NXST
# Configure (once)
cmake --preset switch
# Build
cmake --build build
# Send to Switch via nxlink (Switch must be on same network, nxlink running)
cmake --build build --target send
```
Output: `build/NXST.nro`
---
## Architecture
See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the layer diagram, threading model, and key types.
See [`docs/PROTOCOL.md`](docs/PROTOCOL.md) for the wire protocol (UDP multicast discovery + TCP file stream).
```
ui/ — TitlesLayout, UsersLayout, TransferOverlay, HeaderBar
service/ — TransferService (all network threads and state)
infra/net/ — Socket RAII, sendAll/recvAll
infra/fs/ — io::backup, io::restore, directory iterator, RAII handles
infra/sys/ — nxst::log (printf-checked, timestamped)
domain/ — Title, Account, Result<T>, TransferState, protocol constants
```
---
## Credits
- **[Plutonium](https://github.com/XorTroll/Plutonium)** — Switch UI framework by XorTroll
- **[Checkpoint](https://github.com/BernardoGiordano/Checkpoint)** — save management library by Bernardo Giordano / FlagBrew; several files in `src/infra/fs/` and `src/domain/` are derived from Checkpoint
---
## License
GPLv3 — see [`LICENSE`](LICENSE).
NXST includes code derived from Checkpoint (GPLv3). All original NXST code is released under the same license to satisfy the GPL inheritance requirement.
docs/ARCHITECTURE.md
+163
View File
@@ -0,0 +1,163 @@
# NXST Architecture
## Layer Diagram
```
┌──────────────────────────────┐
│ ui/ │
│ TitlesLayout, UsersLayout │
│ TransferOverlay, HeaderBar │
└──────────────┬───────────────┘
│ calls
┌──────────────▼───────────────┐
│ service/ │
│ TransferService │
└──────┬───────────────┬───────┘
│ │
┌────────────▼──┐ ┌───────▼────────┐
│ infra/net/ │ │ infra/fs/ │
│ TransferService│ │ io, directory │
│ (sender thread │ │ filesystem │
│ recv threads) │ │ handles │
└────────────┬──┘ └───────┬────────┘
│ │
┌────────────▼───────────────▼────────┐
│ domain/ │
│ Title, Account, TransferState │
│ Result<T>, protocol constants │
└─────────────────────────────────────┘
│
┌────────────────────▼────────────────┐
│ libnx, Plutonium, SDL2, devkitpro│
└─────────────────────────────────────┘
```
**Hard layering rules:**
- `domain/` depends on nothing in the project.
- `infra/` depends only on `domain/`.
- `service/` depends on `domain/` + `infra/`.
- `ui/` depends only on `service/` + `domain/` — must not include `<arpa/inet.h>`, `<sys/socket.h>`, `<pthread.h>`, or call `recv`/`send` directly.
- `app/` (MainApplication, main.cpp) wires everything together.
---
## Key Types
### `nxst::TransferService` (`include/nxst/service/transfer_service.hpp`)
Owns all network state for both transfer directions. One instance lives in `MainApplication`.
| Method | Description |
|--------|-------------|
| `startSend(index, uid)` | Backup save, discover receiver, stream files |
| `startReceive(index, uid, title_name)` | Listen for sender, receive files, restore save |
| `cancelSend()` / `cancelReceive()` | Interrupt in-flight transfer (socket shutdown) |
| `isSendDone()` / `isReceiveDone()` | Polled by UI render loop |
| `restoreSucceeded()` / `restoreError()` | Restore outcome after receive |
**Threading model:**
```
UI thread (Plutonium event loop)
└─ startSend()
└─ senderEntry [pthread, detached]
├─ findServer() — UDP multicast, 100 ms poll slices
├─ io::backup() — creates local save backup
└─ TCP send loop
└─ startReceive()
├─ broadcastEntry [pthread, detached] — UDP multicast listener
└─ acceptEntry [pthread, detached]
├─ TCP receive loop
└─ io::restore() — mounts save, clears, copies, commits
```
Cancellation: `cancelSend()` / `cancelReceive()` call `shutdown(SHUT_RDWR)` on all open sockets. Blocking `read`/`recvfrom`/`accept` return errors immediately. Atomic flags are checked at loop boundaries.
### `nxst::Result<T, E>` (`include/nxst/domain/result.hpp`)
85-line tagged-union result type. No exceptions, no `std::variant`. Used for `io::backup` and `io::restore` return values.
```cpp
auto result = io::backup(title_index, uid);
if (!result.isOk()) {
failSend("Backup failed: " + result.error());
return;
}
fs::path dir = result.value();
```
`Result<void, E>` specialisation available for operations that succeed without a value.
### `nxst::FsFileSystemHandle` / `nxst::FileHandle` (`include/nxst/infra/fs/handles.hpp`)
RAII wrappers ensuring `fsFsClose` / `fclose` are called on all exit paths.
---
## Threading Invariants
- All `std::atomic` members in `TransferService` use sequential-consistency (default). No explicit `memory_order` needed at this concurrency level.
- `TransferState::status` is a `std::string` protected by `std::mutex status_mutex`. All other `TransferState` fields are atomics.
- `pthread_create` + `pthread_detach` is used throughout (libnx's supported path). Threads are never joined — they signal completion via `state.done = true` and set their active flag to false.
- Cancel is safe to call from any thread.
---
## File Map
```
include/nxst/
├── app/
│ ├── main.hpp — global state (g_currentTime, g_sortMode, …)
│ └── main_application.hpp — MainApplication : pu::ui::Application
├── domain/
│ ├── account.hpp — AccountUid, Account::ids(), Account::username()
│ ├── common.hpp — StringUtils (UTF-8/16, elide, accents)
│ ├── protocol.hpp — wire constants (ports, sentinel, buffer size)
│ ├── result.hpp — Result<T, E> tagged union
│ ├── title.hpp — Title, getTitle(), getTitleCount()
│ ├── transfer_state.hpp — TransferState (atomics + mutex-guarded status)
│ └── util.hpp — StringUtils helpers, blinkLed
├── infra/
│ ├── fs/
│ │ ├── directory.hpp — Directory iterator (libnx FsDir)
│ │ ├── filesystem.hpp — FileSystem::mount/unmount wrappers
│ │ ├── handles.hpp — FsFileSystemHandle, FileHandle (RAII)
│ │ └── io.hpp — io::backup, io::restore, io::copyFile, …
│ ├── net/
│ │ └── socket.hpp — Socket RAII wrapper (int fd)
│ └── sys/
│ └── logger.hpp — nxst::log::info/warn/error (printf-checked)
├── service/
│ └── transfer_service.hpp — TransferService
└── ui/
├── card.hpp — Card UI component
├── const.h — layout/color/font constants
├── header_bar.hpp — HeaderBar (title + user avatar row)
├── hint_bar.hpp — HintBar (button legend)
├── theme.hpp — color, radius, spacing, type tokens
├── titles_layout.hpp — TitlesLayout
├── transfer_overlay.hpp — TransferOverlay (progress modal)
├── ui_context.hpp — UiContext (selected user state)
└── users_layout.hpp — UsersLayout
```
---
## Build
```bash
# Configure (once — toolchain preset reads $DEVKITPRO automatically)
cmake --preset switch
# Build
cmake --build build
# Send to Switch via nxlink
cmake --build build --target send
```
Output: `build/NXST.nro`
See `README.md` for full build prerequisites.
docs/PROTOCOL.md
+95
View File
@@ -0,0 +1,95 @@
# NXST Wire Protocol
## Overview
NXST uses two sockets per transfer session:
| Socket | Purpose |
|--------|---------|
| UDP multicast | Receiver advertisement (discovery) |
| TCP | File data stream |
Both sides must be on the same local network segment. The sender (Transfer mode) initiates; the receiver (Receive mode) listens.
---
## Discovery — UDP Multicast
| Parameter | Value |
|-----------|-------|
| Group | `239.0.0.1` |
| Port | `8081` |
| Direction | sender → receiver |
**Flow:**
1. Receiver joins multicast group and binds `0.0.0.0:8081`.
2. Sender sends `"DISCOVER_SERVER"` (15 bytes, no null terminator) to `239.0.0.1:8081`.
3. Receiver replies `"SERVER_HERE"` (11 bytes) to the sender's source address.
4. Sender extracts the receiver's IP from the reply source and closes the UDP socket.
Sender polls in 100 ms slices for up to 3 seconds. Cancel is checked each slice.
---
## File Transfer — TCP
| Parameter | Value |
|-----------|-------|
| Port | `8080` |
| Direction | sender connects → receiver listens |
| Buffer size | 65 536 bytes (`proto::BUF_SIZE`) |
**Connection:**
1. Receiver listens on `0.0.0.0:8080` (started concurrently with multicast listener).
2. Sender connects after receiving `"SERVER_HERE"`.
**Wire layout — one file:**
```
┌─────────────────────────────────┐
│ filename_len │ uint32_t LE │ 4 bytes
├─────────────────────────────────┤
│ filename │ filename_len │ bytes, no null terminator
│ │ bytes │
├─────────────────────────────────┤
│ file_size │ uint64_t LE │ 8 bytes
├─────────────────────────────────┤
│ file_data │ file_size │ bytes
│ │ bytes │
└─────────────────────────────────┘
```
Files are sent sequentially. The stream ends with a sentinel frame:
```
filename_len == 0 (proto::EOF_SENTINEL)
```
No `filename` or `file_size` field follows the sentinel.
**Constraints:**
- `filename_len > proto::MAX_FILENAME` (4 096) is treated as a protocol error; the receiver aborts.
- Filenames are full paths as produced by `io::backup` (e.g. `/switch/NXST/<title>/<user>/...`).
- On the receiver, the username path component is rewritten to match the local user's nickname before writing to disk.
---
## Post-Transfer
After the TCP stream closes (sentinel received), the receiver calls `io::restore`:
1. Mounts the title's save filesystem.
2. Clears existing save data.
3. Copies received files into `save:/`.
4. Commits via `fsdevCommitDevice("save")`.
The sender creates a local backup via `io::backup` before connecting, so the sender's own save is never at risk.
---
## Cancellation
Either side can cancel at any time by closing the relevant socket (`shutdown` + `close`). The other side's blocking read/write will return an error and the transfer loop exits cleanly. The receiver's accept thread sets `receiver_state.done = true` regardless of how the connection ends, so the UI poll loop always terminates.