github/Bose-SoundTouch
1
0
Fork 0
mirror of https://github.com/gesellix/Bose-SoundTouch.git synced 2026-08-18 08:36:13 +00:00
Code Issues Packages Projects Releases Wiki Activity

doc: remove mirroring and parity with Bose cloud

Browse Source
This commit is contained in:
Marcin Mennemann
2026-05-18 20:45:18 +02:00
committed by Tobias Gesellchen
parent e9565983f8
commit f1821d5995
6 changed files with 9 additions and 73 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/PARITY-IMPROVEMENTS.md
+1 -2
View File
@@ -37,9 +37,8 @@ This document summarizes the improvements made to the **Marge service** to impro
* **Device Identity**: Added `<serialNumber>` and `<updatedOn>` to both the top-level `<device>` and its `<attachedProduct>`, ensuring consistent device identification.
* **Field-Level Parity**: Mapped missing fields like `<contentItemType>` and `<productlabel>` to match upstream expectations.
* **Improved Source Matching**: Enhanced internal logic to correctly link presets and recents to their configured sources based on multiple identifiers (ID, Key, or Type).
* **Verified Parity Mismatch Fixes**: Comprehensive reproduction tests (`TestParityMismatchReproduction_V2` and `TestParityMismatchReproduction_V3`) now confirm parity for identified mismatches in `POST /recent` and `GET /recents`, including credentials and source-specific metadata.
* **Verified Parity Mismatch Fixes**: The reproduction test `TestParityMismatchReproduction_V2` confirms parity for identified mismatches in `POST /recent` and `GET /recents`, including credentials and source-specific metadata.
* **Unified Response Logic**: Refactored the code so that both `POST /recent` and `GET /recents` use the same formatting functions, guaranteeing consistency.
* **Robust Parity Detection**: Updated the local parity checker to be whitespace-insensitive for XML bodies, significantly reducing noise from minor indentation or newline differences.
* **Maintainable XML Generation**: Reduced cyclomatic complexity and code duplication in `marge.go` by extracting focused helper functions for mapping internal data to response-specific XML models.
---
docs/concepts/technical-specification.md
+5 -23
View File
@@ -22,7 +22,6 @@
│ SoundTouch Service │
├─────────────────────────────────────────────────────────────┤
│ HTTP Router & Middleware │
│ ├── Mirror Middleware (Enhanced) │
│ ├── Recorder Middleware │
│ ├── Disparity Detection │
│ └── Health Check Middleware │
@@ -35,12 +34,11 @@
├─────────────────────────────────────────────────────────────┤
│ Data Layer │
│ ├── Enhanced DataStore ├── Event Store │
│ ├── Mirror Cache ├── Metrics Store │
│ └── Configuration Store └── Session Store │
├─────────────────────────────────────────────────────────────┤
│ External Integrations │
│ ├── Bose Services (Mirror) ├── Device Discovery │
│ ├── BMX/TuneIn Services └── SSH/Setup Manager │
│ ├── Device Discovery ├── BMX/TuneIn Services │
│ └── SSH/Setup Manager │
└─────────────────────────────────────────────────────────────┘
```
@@ -69,10 +67,6 @@ pkg/service/
│ ├── processor.go
│ ├── queue.go
│ └── storage.go
├── mirror/ # Enhanced mirroring (extends existing)
│ ├── disparity.go
│ ├── analyzer.go
│ └── logger.go
├── health/ # System monitoring
│ ├── monitor.go
│ ├── metrics.go
@@ -115,20 +109,17 @@ type MigrationInfo struct {
CompletedAt *time.Time `json:"completed_at,omitempty"`
DevicesMigrated int `json:"devices_migrated"`
DevicesPending int `json:"devices_pending"`
MirrorActive bool `json:"mirror_active"`
Strategy string `json:"strategy"`
RollbackData string `json:"rollback_data,omitempty"`
}
type DataSourceConfig struct {
Local bool `json:"local"`
BoseMirror bool `json:"bose_mirror"`
Primary string `json:"primary"` // "local" or "bose"
}
type AccountSettings struct {
AutoMigration bool `json:"auto_migration"`
MirrorEndpoints []string `json:"mirror_endpoints"`
RetentionDays int `json:"retention_days"`
}
```
@@ -235,7 +226,6 @@ type EventSource string
const (
EventSourceWebSocket EventSource = "websocket"
EventSourceDiscovery EventSource = "discovery"
EventSourceMirror EventSource = "mirror"
EventSourceSystem EventSource = "system"
EventSourceAPI EventSource = "api"
EventSourceUser EventSource = "user"
@@ -336,12 +326,10 @@ Response: 200 OK
"migration_info": {
"started_at": "2024-01-18T09:00:00Z",
"devices_migrated": 1,
"devices_pending": 1,
"mirror_active": true
"devices_pending": 1
},
"data_sources": {
"local": true,
"bose_mirror": true,
"primary": "bose"
}
}
@@ -474,8 +462,7 @@ Response: 200 OK
"services": {
"account_manager": "healthy",
"lifecycle_manager": "healthy",
"event_processor": "healthy",
"mirror_service": "warning"
"event_processor": "healthy"
},
"statistics": {
"total_accounts": 5,
@@ -534,18 +521,15 @@ Response: 200 OK
"started_at": "2024-01-18T09:00:00Z",
"devices_migrated": 1,
"devices_pending": 1,
"mirror_active": true,
"strategy": "gradual"
},
"bose_account_id": "bose-original-id",
"data_sources": {
"local": true,
"bose_mirror": true,
"primary": "bose"
},
"settings": {
"auto_migration": false,
"mirror_endpoints": ["/v1/presets", "/v1/recents"],
"retention_days": 30
}
}
@@ -593,7 +577,7 @@ Response: 200 OK
},
"data_sources": {
"presets": "local",
"recents": "mirror_primary",
"recents": "local",
"sources": "local"
},
"migration": {
@@ -622,7 +606,6 @@ Response: 200 OK
2024-01-20T15:30:00.123Z|evt_12345|now_playing|websocket|{"source":"SPOTIFY","track":"Song Name","artist":"Artist Name","album":"Album Name"}
2024-01-20T15:30:30.456Z|evt_12346|volume_changed|websocket|{"volume":45,"muted":false,"previous_volume":40}
2024-01-20T15:31:00.789Z|evt_12347|preset_selected|websocket|{"preset":1,"source":"SPOTIFY","location":"spotify:track:123abc"}
2024-01-20T15:31:15.012Z|evt_12348|disparity_detected|mirror|{"endpoint":"/v1/presets","local_hash":"abc123","upstream_hash":"def456","severity":"medium"}
2024-01-20T15:32:00.345Z|evt_12349|health_check|system|{"response_time":42,"status":"healthy","connectivity":"online"}
```
@@ -852,7 +835,6 @@ go test -bench=. ./...
### Response Time Targets
- Local API requests: < 100ms (95th percentile)
- Mirror requests: < 200ms overhead (asynchronous)
- Discovery time: < 5s for network scan
### Resource Constraints
docs/concepts/upstream-service-simulation.md
+2 -5
View File
@@ -95,13 +95,11 @@ data/
"migration_status": {
"started_at": "2024-01-18T09:00:00Z",
"devices_migrated": 1,
"devices_pending": 2,
"mirror_active": true
"devices_pending": 2
},
"bose_account_id": "bose-original-id",
"data_sources": {
"local": true,
"bose_mirror": true,
"primary": "bose"
}
}
@@ -144,7 +142,7 @@ data/
},
"data_sources": {
"presets": "local",
"recents": "mirror_primary",
"recents": "local",
"sources": "local"
},
"migration": {
@@ -165,7 +163,6 @@ data/
2024-01-20T16:15:00Z|now_playing|websocket|{"source":"SPOTIFY","track":"Song Name","artist":"Artist Name"}
2024-01-20T16:15:30Z|volume_changed|websocket|{"volume":45,"muted":false}
2024-01-20T16:16:00Z|preset_selected|websocket|{"preset":1,"source":"SPOTIFY","location":"spotify:track:123"}
2024-01-20T16:18:00Z|disparity_detected|mirror|{"endpoint":"/v1/account/full","local_hash":"abc123","upstream_hash":"def456"}
2024-01-20T16:20:00Z|device_online|discovery|{"ip":"192.0.2.100","method":"mdns"}
```
docs/guides/CAPTURE-MIGRATION-TRAFFIC.md
-9
View File
@@ -50,9 +50,6 @@ make build-service
Service listens on `:8000` by default. Web UI: `http://localhost:8000`
> To also enable mirror mode (forward unhandled requests to official Bose servers
> for comparison), add: `--mirror-enabled --mirror-endpoints /streaming/`
---
## Step 2 — Start mitmproxy + Frida (new capture)
@@ -236,9 +233,6 @@ Endpoints the service doesn't handle return `404 Not Found`. Check:
```bash
# From service stats
curl -s http://localhost:8000/setup/interaction-stats | python3 -m json.tool
# List parity mismatches (local vs upstream divergence, if mirror enabled)
curl -s http://localhost:8000/setup/parity-mismatches | python3 -m json.tool
```
---
@@ -298,8 +292,6 @@ Settings applied in the web UI before migration:
| Target Domain | `soundtouch.local` (resolvable from speaker to `192.168.x.z`) |
| DNS Discovery | enabled |
| Upstream DNS | home Wi-Fi gateway |
| Mirroring | enabled (for tracing while Bose cloud is still up) |
| Mirrored endpoints | `/bmx/*`, `/streaming/*`, `/accounts/*`, `/v1/scmudc/*`, `/oauth/*` |
| Proxy logging | enabled, including bodies |
| Record interactions | enabled |
| Skip recording | `/setup/*`, `/web/*` |
@@ -361,7 +353,6 @@ All tests run from the **Devices → Migrate** panel after selecting the speaker
- Paired speaker to Bose account via app — succeeded ✅
- Set presets via app — worked ✅
- Mirroring active and functional during session ✅
- No visible errors in app behaviour; service logs and interaction recordings not yet reviewed in detail
### Known Shell Warning (safe to ignore)
docs/guides/SOUNDTOUCH-SERVICE.md
-33
View File
@@ -13,8 +13,6 @@ The service provides:
- **🌐 Web Management UI**: Browser-based interface for device management
- **💾 Persistent Data**: Store device configurations, presets, and usage statistics
- **📝 HTTP Recording**: Persist all interactions as re-playable `.http` files
- **🔄 Endpoint Mirroring**: Asynchronously mirror local requests to Bose cloud for parity testing
- **⚖️ Parity Logging**: Detect and record discrepancies between local and official Bose responses
- **📥 Session Archiving**: Download entire interaction sessions as `.tar.gz` for offline analysis
- **🔍 Auto-Discovery**: Automatically detect and configure SoundTouch devices
- **🔒 Offline Operation**: Continue using full device functionality without internet
@@ -170,8 +168,6 @@ The service supports multiple ways to configure its behavior. When multiple sour
| `ENABLE_DNS_DISCOVERY` | `--dns-discovery` | Enable DNS discovery server | `false` |
| `DNS_UPSTREAM` | `--dns-upstream` | Upstream DNS server for non-Bose queries | `8.8.8.8` |
| `DNS_BIND_ADDR` | `--dns-bind` | Bind address for the DNS discovery server (standard port `:53` is required for DNS/DHCP migration) | `:53` |
| `MIRROR_ENABLED` | | Enable background mirroring of specific endpoints to Bose cloud | `false` |
| `MIRROR_ENDPOINTS` | | Comma-separated list of path patterns to mirror (e.g., `/streaming/account/*/device/*/recent`) | `[]` |
| `INTERNAL_PATHS` | `--internal-paths` | Paths for internal requests to exclude from recording (e.g., `/setup/*`, `/web/*`) | `[]` |
| `DISCOVERY_DISABLED` | | Disable automated device discovery | `false` |
| `STOCKHOLM_DIR` | `--stockholm-dir` | Path to extracted Stockholm frontend directory — enables the Stockholm UI when set | *(disabled)* |
@@ -379,34 +375,6 @@ You can enable and configure the DNS server via the Web UI or environment variab
#### Manual Discovery via DNS
Even without migrating a device, you can use the DNS server to discover what a device is querying by manually setting your router's DNS or the device's DNS to point to the AfterTouch service.
## Endpoint Mirroring & Parity Logging
The SoundTouch service includes a powerful **Mirroring** feature that allows you to handle requests locally while simultaneously forwarding them to the official Bose cloud in the background. This is primarily used for maintaining long-term compatibility and verifying the accuracy of the local emulation.
### How Mirroring Works
When an endpoint is configured for mirroring:
1. **GET Requests**: Handled locally first (Primary). The response is returned to the speaker immediately. In the background, the same request is sent to Bose.
2. **POST/PUT/DELETE Requests**: Handled locally first. The service then synchronously (but without blocking the speaker's response) forwards the request to Bose to ensure the "official" account state stays in sync with your local changes (e.g., updating a preset).
### Parity Logging
The **Parity Logger** automatically compares the response from your local service with the one received from Bose. If it detects any discrepancies, it:
1. Logs a warning to the console: `[PARITY] Mismatch detected for GET /...`
2. Saves a detailed JSON report to `data/parity_mismatches/`.
Each report includes the full request, both response bodies, and a summary of what differed (status codes, content types, or missing/different XML tags).
### Configuration
Mirroring is configured via the **Settings** tab in the Web UI or through global settings:
- **Mirror Enabled**: Master switch for the mirroring infrastructure.
- **Mirror Endpoints**: A list of URL path patterns to mirror. You can use wildcards (`*`) to match variable parts like account or device IDs.
- Example: `/streaming/account/*/device/*/recent`
- Example: `/accounts/*/devices/*/presets/*`
Mirrored requests are also recorded in the **Interaction Log** under the category `upstream-mirror`, allowing you to see side-by-side exactly how our service's behavior compares to the official one.
## API Reference
### Discovery & Setup
@@ -825,7 +793,6 @@ Clears all recorded DNS discovery data from memory and disk.
- `/bmx/tunein/v1/*`: TuneIn radio emulation.
- `/marge/accounts/*`: Account and device management.
- `/marge/updates/soundtouch`: Software update emulation.
- `/proxy/*`: Logging proxy for original Bose services.
## Troubleshooting
docs/images/README.md
+1 -1
View File
@@ -6,7 +6,7 @@ Screenshots and diagrams referenced by the documentation.
| File | Shows | Used in |
|------|-------|---------|
| `ui-settings.png` | AfterTouch web UI — Settings tab (Target Domain, DNS Discovery, Mirroring) | Migration Guide |
| `ui-settings.png` | AfterTouch web UI — Settings tab (Target Domain, DNS Discovery) | Migration Guide |
| `ui-devices.png` | AfterTouch web UI — Devices tab (discovered speakers with Sync/Migrate actions) | Migration Guide |
| `ui-sync.png` | AfterTouch web UI — Data Sync tab (successful sync result) | Migration Guide |
| `ui-migration.png` | AfterTouch web UI — Migration tab (HTTPS test, DNS test, method selector) | Migration Guide |