Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 5 additions & 1 deletion docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -92,9 +92,13 @@ claims; it never performs an implicit second window restoration.
User configuration is stored as at most three named profiles in
`%LOCALAPPDATA%\SBMS\config-profiles-v1.json`. The collection, active profile
and per-profile revisions are committed atomically under a cross-process lock.
Each profile also has an instance id that is not reused when a deleted name
is created again. Saves compare that id together with the revision.
On first use, the existing `config-v2.json` is preserved and imported as the
`default` profile. The tray supports revision-checked live reloads without
changing a mapping that is already running. See
changing a mapping that is already running. A damaged profile collection is
left unchanged by ordinary profile commands. `sbms config reset --all --backup`
backs up the original bytes and rebuilds the entire collection. See
[configuration.md](configuration.md) for the storage, CLI, JSON and Rust API
contracts.

Expand Down
5 changes: 4 additions & 1 deletion docs/command-line.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,4 +20,7 @@ sbms shutdown
foreground session cleanly. A mapping plan can contain up to sixteen mirror and
stream-only groups. Up to three persistent configuration profiles can coexist;
see [Configuration profiles](configuration.md) for import, export,
activation and hot-reload interfaces.
activation and hot-reload interfaces. `sbms config reset` resets only the
active profile in a valid collection. `sbms config reset --all --backup`
backs up the raw profile file and rebuilds the entire collection; both flags
are required.
2 changes: 1 addition & 1 deletion docs/command-line.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,4 @@ sbms shutdown
`sbms list` 会列出 `--target` 所需的稳定显示器 ID。前台运行 `map` 时按
Enter,可以正常停止并完成恢复。映射计划最多可混合十六组本地镜像和纯串流
虚拟桌面。最多可以同时保存三套配置;导入、导出、激活和热加载接口见
[配置档案接口](configuration.md)。
[配置档案接口](configuration.md)。`sbms config reset` 只重置一份有效配置集合里的当前档案。`sbms config reset --all --backup` 会按原始字节备份整个配置集合,然后重建为默认集合;两个参数必须同时给出。该命令会丢弃全部档案和全局偏好,不会删除显示器覆盖、日志、串流凭据或旧版迁移文件。
122 changes: 106 additions & 16 deletions docs/configuration.md
Original file line number Diff line number Diff line change
@@ -1,11 +1,13 @@
# Configuration profiles

SBMS stores up to three persistent configuration profiles in
`%LOCALAPPDATA%\SBMS\config-profiles-v1.json`. The complete profile collection,
the active profile identifier, every profile revision and every nested
`AppConfig` are committed as one pretty-printed JSON document. Writes use a
cross-process mutex, a same-directory temporary file, `sync_all`, and a
write-through atomic replacement.
`%LOCALAPPDATA%\SBMS\config-profiles-v1.json`. The file name stays
`config-profiles-v1.json`; the document inside it is version 2. The complete
profile collection, the active profile identifier, every profile instance id,
every profile revision and every nested `AppConfig` are committed as one
pretty-printed JSON document. Writes use a cross-process mutex, a
same-directory temporary file, `sync_all`, and a write-through atomic
replacement.

The first profile operation imports the existing `config-v2.json` as the
`default` profile. The legacy file is left unchanged. If the old file is
Expand Down Expand Up @@ -34,6 +36,7 @@ sbms config reload
sbms config set-target <monitor-device-path>
sbms config clear-target
sbms config reset
sbms config reset --all --backup
```

- `path` prints the profile-store path.
Expand All @@ -53,12 +56,86 @@ sbms config reset
- `activate` atomically changes the active profile and requests a live reload.
- `delete` rejects the active profile and unknown profiles.
- `reload` requests that the running tray reload the already-active profile.
- `set-target`, `clear-target` and `reset` update only the active profile and
request a live reload.
- `set-target` and `clear-target` update only the active profile and request
a live reload.
- `reset` with no other arguments resets only the active profile inside a
valid collection. Other profiles and the global preferences
`launch_intro_disabled` and `auto_map_on_login` stay unchanged. A missing
profile store is created from the normal default. If the store is damaged,
unreadable, or uses a newer schema version, `reset` fails and does not write.
- `reset --all --backup` rebuilds the entire profile collection. Both flags are
required, in either order. Any other argument combination prints usage and
exits without writing.

A successful configuration commit is not rolled back when the tray is not
running. CLI output reports `reload=not-running`; the configuration is loaded
on the next tray or mapping start.
on the next tray or mapping start. After `reset --all --backup` commits,
`reload=failed` means the new collection is already on disk and only the tray
notification failed.

## Damaged profile collection

Ordinary profile commands, including `sbms config reset`, load the collection
before changing it. A truncated file, invalid JSON, or a version 1 collection
that fails semantic validation therefore cannot be repaired by `reset`. A
valid version 1 collection is migrated in place, as described below.

`sbms config reset --all --backup` is the explicit recovery command. Under the
existing cross-process profile lock it:

1. Reads the current `config-profiles-v1.json` bytes.
2. Writes those exact bytes to a new file in the same directory:
`config-profiles-v1.json.recovery-<pid>-<sequence>.bak`.
The file is created with `create_new` and flushed before the store is
replaced, so a later recovery cannot overwrite an earlier backup.
3. Atomically replaces the store with one `default` profile at revision 1 and
default global preferences.

The command discards every saved profile and both global preferences. It does
not delete display overrides, logs, stream credentials, `config-v2.json`, or
`config-v1.json`.

A numeric `version` greater than 2 is a newer schema. Recovery refuses it and
leaves the file unchanged, without writing a backup. A non-numeric `version`,
truncated JSON, or any other file whose schema version cannot be recognized is
damaged. Only this command can rebuild it. The command also accepts a valid
collection: it still backs up the raw bytes and replaces the whole collection.
The rebuilt collection receives new profile instance ids, so snapshots taken
before recovery no longer match.

Permission errors and other read/write failures are not treated as damage: the
source file stays in place. If the backup itself fails, nothing is replaced.
If the backup succeeds and the atomic replacement fails, the command reports
that recovery was not committed and leaves the backup in place.

```text
sbms config reset --all --backup
```

```text
recovered=default revision=1 backup=%LOCALAPPDATA%\SBMS\config-profiles-v1.json.recovery-<pid>-<sequence>.bak reload=not-running
```

## Profile instance migration

A valid version 1 collection has no instance ids. The first operation that
loads it, under the existing profile lock, allocates one UUID version-4
instance id per profile with `BCryptGenRandom` and atomically writes document
version 2. The following load reads those same ids. They are not generated
again during deserialization.

If allocating an id or the atomic write fails, the version 1 file stays in
place and the call returns an error. It does not return a snapshot whose ids
were never stored. A version 1 document that already contains `instance_id`,
or that fails semantic validation, is damaged and is not migrated. A version 2
document with an invalid or duplicate instance id is also rejected and left
unchanged.

SBMS 2.0.2 cannot read a version 2 collection. Deserialization fails on the
unknown `instance_id` field, and that build accepts only document version 1.
The failure returns before any write, so the newer file stays in place. A
build that treats every numeric version greater than 1 as a newer schema also
leaves a version 2 file unchanged.

## JSON exchange format

Expand All @@ -83,7 +160,10 @@ not the internal multi-profile collection:

Unknown fields, unsupported versions, empty or oversized group collections,
duplicate group IDs or mirror targets, invalid geometry and invalid selected
group IDs are rejected before any persistent state changes.
group IDs are rejected before any persistent state changes. An import file
cannot carry a profile instance id. `instance_id` is rejected as an unknown
field. Replacing an existing profile keeps that profile's instance id and
increases its revision. Creating a profile allocates a new instance id.

## Rendering options

Expand Down Expand Up @@ -130,21 +210,31 @@ controller reports both `running=false` and `busy=false`. Reload never restarts,
stops or mutates the active mapping. It changes the configuration used by the
next mapping start.

Each profile has a monotonically increasing revision. UI saves use a
profile-ID-and-revision compare-and-swap. A stale UI draft therefore cannot
overwrite a profile imported or activated by another process; the user must
reload before saving again.
Each profile has an instance id and a monotonically increasing revision. The
instance id is created with the profile. Copying a profile, deleting it and
creating the same name again, and rebuilding the whole collection all allocate
a new id. Renaming a profile, editing or replacing its contents, and
`sbms config reset` keep the id and increase the revision. UI saves compare
the active profile's name, instance id, and revision. A matching name and
revision are not enough after that name has been deleted and created again.
The save is refused with `Reload the configuration before saving`. The UI
shows that error and does not retry the stale draft.

## Rust interface

The public API is exported from `sbms::config`:

- `ConfigProfileStore::default_store()` locates the collection.
- `list`, `load_active` and `load_profile` return validated persistent state.
- `save_profile`, `save_active_as`, `activate`, `delete` and `update_active`
perform locked atomic transactions.
- `save_profile`, `save_active_as`, `activate`, `delete`, `update_active` and
`reset_active` perform locked atomic transactions.
- `recover_with_backup` is the locked recovery used by
`sbms config reset --all --backup`. It returns the new snapshot and the
backup path. `ConfigError::allows_profile_collection_recovery` is true only
for a damaged collection this build can rebuild.
- `save_active_if_revision` is the compare-and-swap save operation for a pinned
UI session.
UI session. It accepts the save only when the active profile's name,
instance id, and revision all match the caller's snapshot.
- `ConfigStore::load_strict` validates standalone import files; `save` writes
standalone exports atomically.
- `sbms::control::signal_config_reload` and `listen_for_config_reload` expose
Expand Down
Loading