mirror of
https://github.com/shadowsocks/ShadowsocksX-NG.git
synced 2026-11-01 15:43:45 +00:00
docs(domain): add managed plugin and plugin activation semantics
Wayfinder #19: plugin program references persist verbatim, only managed plugins are selectable, unavailable plugins are invalid activation candidates, and plugin options are sensitive in their entirety.
This commit is contained in:
+5
-2
@@ -10,6 +10,7 @@
|
||||
- **Subscription group**: The fixed, source-owned configuration subtree provided by one subscription. Users cannot move or structurally edit its nodes. A subscription node's user-visible name/remark is one remote-derived value from `remarks`, falling back to the server address when absent; it has no local alias or note override. Local enablement remains a separate eligibility state.
|
||||
- **Active target**: The persisted server configuration or configuration group selected for proxying. When a group is active, the group UUID remains the target even when `sslocal` chooses an individual descendant server.
|
||||
- **Enabled**: A local eligibility state on a server configuration or configuration group. A node is effectively enabled only when it and every group ancestor are enabled.
|
||||
- **Managed plugin**: A SIP003 plugin executable that the product packages, hash-verifies, re-signs, and distributes only inside the app bundle. The managed set changes only with app releases; users cannot supply their own plugin executables.
|
||||
- **Proxy mode**: The user-facing way traffic is routed through the local proxy, such as PAC, global, manual, or an external PAC configuration.
|
||||
- **HTTP proxy mode**: A local proxy mode that accepts HTTP/HTTPS proxy requests directly through the Shadowsocks runtime; it does not require a separate adapter process.
|
||||
- **Legacy Privoxy adapter**: The frozen implementation's HTTP(S)-to-local-SOCKS5 bridge. It is a Legacy-only dependency and is not migrated into 2.0.
|
||||
@@ -19,7 +20,7 @@
|
||||
- **Legacy import**: The user-confirmed, read-only translation of a Legacy configuration snapshot into a separate manual group in 2.0. It neither starts proxying nor alters the Legacy source.
|
||||
- **Legacy handoff**: The separately confirmed transfer of proxy operation from Legacy to 2.0. It retires only positively identified Legacy runtime components while retaining Legacy data for rollback.
|
||||
- **Runtime configuration file**: The derived JSON document used by the external tunnel service for the active target; it is not the user-managed server configuration or subscription document.
|
||||
- **Sensitive information**: Server passwords, plugin options that contain credentials, and nonempty user-provided remote URLs, including subscription, external PAC, and custom GFW List URLs.
|
||||
- **Sensitive information**: Server passwords, plugin options (sensitive in their entirety), and nonempty user-provided remote URLs, including subscription, external PAC, and custom GFW List URLs.
|
||||
- **Credential exposure boundary**: This product reduces accidental disclosure and exposure to other user accounts, but does not guarantee protection against a compromised same-user process, root access, or APFS snapshots and backups; it does not promise secure erasure.
|
||||
- **Credential reference**: A non-secret association from a server configuration, subscription, or remote-URL setting to its durable credential; the credential value is kept outside the configuration tree and resolved only when needed.
|
||||
|
||||
@@ -31,6 +32,8 @@
|
||||
- Manual and subscription ownership form separate subtrees; a manual group cannot adopt subscription-owned nodes, and subscription-owned nodes cannot be moved into manual groups.
|
||||
- New manual servers always receive a new UUID rather than being deduplicated by endpoint or serialized content; Legacy migration preserves an available legacy UUID.
|
||||
- Effective enablement excludes a disabled group and its subtree or a disabled server leaf from activation.
|
||||
- A server configuration persists its SIP003 plugin program reference and plugin options verbatim. Editing offers only managed plugins as selections; a reference to a program outside the managed set remains stored but makes the server an invalid activation candidate, so activation including it is rejected atomically with a named reason and no silent fallback.
|
||||
- Plugin programs are distributed only as managed plugins; their availability changes only with app releases. If an active target's plugin becomes unavailable, the target is cleared and proxying stops without fallback.
|
||||
- Activating a server selects that one server. Activating a group recursively expands effectively enabled server leaves in explicit child order and passes them to the external proxy service; an empty result or an invalid enabled leaf rejects activation atomically.
|
||||
- The active target remains the selected node ID and is not silently replaced by a descendant chosen by `sslocal`. If it is deleted, disabled, empty, or invalid, the target is cleared and proxying stops rather than falling back silently.
|
||||
- After a committed edit to the active target's subtree, the target is re-expanded immediately: a valid non-empty result updates the runtime atomically; an empty or invalid result clears the target and stops proxying without fallback.
|
||||
@@ -43,7 +46,7 @@
|
||||
- Editing a subscription URL keeps the subscription, fixed group, and remote identity namespace; the last successful snapshot remains available until the new URL succeeds. To isolate a different source, delete the old subscription and create a new one. Deleting a subscription removes its source, fixed group, remote members, and local overlays after explicit confirmation; an active target is cleared and proxying stops without fallback.
|
||||
- A Legacy import reads a current snapshot and commits atomically; skipping leaves an import entry available, success prevents automatic repetition, and an explicitly requested re-import creates a separate manual group.
|
||||
- A unique, syntactically valid Legacy server UUID is preserved. An otherwise valid server with a missing, malformed, or duplicate UUID receives a fresh UUID; invalid records are omitted with a user-visible report, and an active target is kept only when it maps unambiguously.
|
||||
- Imported mode and target preferences never start proxying or write system proxy settings. Legacy passwords, plugin options, and user-provided remote URLs move to credential references; generated configurations, caches, diagnostics, logs, and binaries do not migrate.
|
||||
- Imported mode and target preferences never start proxying or write system proxy settings. Legacy passwords, plugin options, and user-provided remote URLs move to credential references; generated configurations, caches, diagnostics, logs, and binaries do not migrate. The imported plugin program reference is preserved verbatim even when 2.0 does not provide that plugin.
|
||||
- A Legacy handoff is an explicit second phase, not an import side effect. It may stop only positively identified Legacy runtime jobs after confirmation and must not broadly kill processes or automatically delete Legacy data.
|
||||
- The PAC HTTP endpoint and the external tunnel service's inbound listeners follow one shared listen scope, so a PAC URL or proxy address shared to another machine always points at a reachable proxy; loopback is the default scope.
|
||||
- The ports of the locally provided proxy endpoints are explicit user configuration: the system never rewrites a port on its own, and a port conflict rejects proxy start with an error naming the endpoint until the user explicitly chooses a new port.
|
||||
|
||||
Reference in New Issue
Block a user