flutter_sing_box 2.0.1

flutter_sing_box: ^2.0.1 copied to clipboard

Documentation #

• Update the showcase project name (clash_sing → clash-sing) in README / README_CN to match the renamed repository

⚠️ Breaking change #

• ProxyState is now a sealed class (was an enum); each state is its own final class: ProxyStopped / ProxyStarting / ProxyStarted / ProxyStopping
  • ProxyStopped carries a nullable errMessage (non-null = abnormal stop, e.g. start failure or core crash) with value-based == / hashCode; the other three states are const singletons
  • Existing == ProxyState.started-style comparisons keep working via preserved static const compatibility constants (ProxyState.stopped / .starting / .started / .stopping); exhaustive switches over the old enum must migrate to type patterns (case ProxyStopped():)
  • The name getter and fromName() keep their original semantics
• Windows: start() / restart() no longer throw on failure; the failure reason is emitted as ProxyStopped(errMessage: ...) on proxyStateStream (also resetting the state machine from starting), making the state stream the single source of truth for startup failures — aligned with the Android native alert path; callers awaiting these futures can no longer catch failures from the returned future

Features #

• Android proxyStateStream: abnormal-stop events from the native side (EventSink.error(code: "Stopped", message)) now surface their error message as ProxyStopped.errMessage instead of being swallowed

Dependencies #

• Upgrade sing-box core to 1.14.0: Android (libbox, jitpack) 1.13.21 → 1.14.0; Windows sing-box.exe / libcronet.dll binaries upgraded in sync

Compatibility (adapting to libbox 1.14.0 breaking API changes, aligned with upstream sing-box-for-android 1.14.0) #

• PlatformInterface: remove the deleted systemCertificates(); add default implementations for 13 new interface methods (shell / bridge / neighbor-table monitoring, etc., treated as "unsupported"); getInterfaces() now includes gateway info
• TunOptions: dnsServerAddress changed from a single value to an iterator; openTun migrated to dnsMode + multiple DNS server writes
• CommandServerHandler: implement triggerNativeCrash() / connectSSHAgent()
• CommandClientHandler: implement writeOutbounds() (this plugin does not subscribe to that command; empty implementation)
• Notification API: identifier semantics changed to a notification tag; the sendNotification channel is now derived from typeID; add cancelNotification
• Remove the Libbox.redirectStderr() call deleted by libbox (Setup() now redirects stderr to CrashReport-<source>.log automatically)

Features #

• Configuration model extensions, adding sing-box 1.14.0 fields:
  • DnsRule: add race / rcode / tag fields; action made nullable with the RuleAction.route default removed; rules narrowed to List<DnsRule>; matchResponse relaxed to dynamic
  • RouteRule: action made nullable with the RuleAction.route default removed
  • RuleSet: add local rules (inline rule-set); remove the deprecated downloadDetour
  • Outbound: add hopInterval / hopIntervalMax / bbrProfile / disableChromeParrot / realm (Hysteria2-related) fields
  • Route / SingBox: add defaultHttpClient / httpClients fields
  • ClientGroupItem: tag / type changed to mutable fields

⚠️ Runtime behavior notes #

• sing-box 1.14.0 hard-removes the legacy DNS server format (legacy dns.servers) deprecated since 1.12: old-format configs fail immediately at startup; user configs must use the new DNS format (the new format generated by the Clash/Base64 config converters in this plugin is unaffected)

🎉 Milestone: official Windows platform support #

Promoted from the "in development" state of 1.1.5 to officially usable: the desktop hosts the sing-box process as a system service, with system proxy settings and real-time Clash API logs.

⚠️ Breaking Changes #

• Minimum environment requirements raised: Dart SDK ^3.11.0 → ^3.12.0, Flutter >=3.41.0 → >=3.44.0

Features #

• Official Windows platform support:
  • Add SystemProxyService: set/clear the Windows system proxy via FFI
  • Add the ProxyMode enum and the defaultMixedPort constant; CsSettingsStorage adds proxyMode / mixedPort / systemProxyActive settings
  • emitProxyState linked with system proxy on/off; init adds crash self-recovery logic
  • Add Clash API real-time log subscription (logStream): WebSocket-based connection to the /logs endpoint with automatic reconnection and a custom API port
• Resource extraction enhancements: compare the SHA256 of resources and target files in memory to avoid temp-file writes and cleanup; for running exes exclusively locked on Windows (errno 32), fall back to renaming the old file to .old before writing the new one
• Network layer DioClient adds an allowBadCertificates switch to control certificate validation at runtime, fixing request failures on the Windows desktop caused by incomplete certificate chains of subscription sites

Fixes #

• Fix the Windows Clash log level mapping error (warning → warn)
• Fix missing await on asynchronous calls in Windows service operations (status check, install, uninstall, start, stop) and resource copy methods

Improvements #

• Migrate the Android build script from Groovy (build.gradle) to Kotlin DSL (build.gradle.kts), requiring AGP 9.0.1 / Kotlin 2.3.20 / Java 17
• Remove unnecessary Android permissions
• Simplify the Windows platform asset configuration in pubspec.yaml
• Example: upgrade the Android build toolchain (Gradle / AGP / Kotlin / SDK); migrate the UI layer from flutter/material to material_ui

Dependencies #

• Upgrade the sing-box core (Android libbox / Windows sing-box.exe): 1.13.15 → 1.13.21
• Upgrade MMKV: 2.4.1 → 2.4.2 (2.4.1 has an MSVC cbridge crash on Windows)
• Upgrade dio: → ^5.11.1
• Remove the path_provider dependency

Features #

• Add Windows platform support (in development; the desktop hosts the sing-box process as a system service, compensating for the lack of a VPN Service on desktop platforms):
  • Add service management APIs: installService / uninstallService / queryServiceStatus, installed via PowerShell runas elevation with status polling to determine the result
  • Implement Windows VPN control and proxy state listening (proxyStateStream)
  • Add HelperCli, wrapping all CLI subcommands of clash_sing_helper.exe (status / stop / install / uninstall / start)
• Windows Clash API support:
  • Add Clash configuration models and an HTTP client
  • Implement Clash mode reading and switching (clashModeStream, setClashMode)
  • Implement proxy group fetching, outbound switching and URL latency testing
• The storage layer adds Clash API port and test URL settings

Improvements #

• Upgrade Android libbox (sing-box core): 1.13.14 → 1.13.15
• Upgrade Windows sing-box.exe to 1.13.15
• The Clash API port adapts to changes dynamically
• Remove the unused location permission on Android

Fixes #

• Fix the Windows Clash HTTP client proxy type mapping error
• Fix Windows Clash proxy group parsing and type conversion logic

Refactoring #

• Refactor the service install API: parameters collapsed into a HelperConfig object; hardcoded paths extracted into constants
• Promote service management capabilities (uninstall / start / stop) to the platform abstraction layer and facade
• Optimize proxy state stream controller initialization and state dispatch logic
• FlutterSingBoxWindows delegates to HelperCli, removing the migrated helper methods

Dependencies #

• Upgrade dio: → ^5.10.0

Dependencies #

• Upgrade Android libbox (sing-box core): 1.13.12 → 1.13.14

Features #

• Add naive protocol outbound type support
• Add a standalone TLS configuration model (tls.dart)
• Add a domainResolver field to the Outbound model
• Add domain_resolver and tls fields to the DNS Server model

Fixes #

• Fix the DNS Server model path field type: List<String> → String

Improvements #

• Remove the sniff_override_destination option from the sing-box template config

Documentation #

• Fully document public APIs with English dartdoc comments, covering constants, providers, services, network, storage, etc., improving the pub.flutter-io.cn documentation coverage score

Dependencies #

• Upgrade device_info_plus: ^12.2.0 → ^13.1.0
• Upgrade package_info_plus: ^9.0.0 → ^10.1.0

⚠️ Breaking Changes #

• Minimum environment requirements raised: Dart SDK ^3.9.0 → ^3.11.0, Flutter >=3.3.0 → >=3.41.0
• Fix the Android plugin package name typo: com.clashsiing.flutter_sing_box → com.clashsing.flutter_sing_box (update native references or consumer-rules configurations accordingly, if any)
• Introduce the freezed code generation framework, adding freezed and freezed_annotation dependencies

Features #

• Add Rule Set configuration support and optimize the sing-box config template structure
• Support a custom User-Agent for subscription requests, with a built-in default User-Agent generator
• Greatly extend the sing-box configuration model fields: Outbound adds username, quic, etc.; DNS / Route models gain many additional fields
• Add a standalone storage module with the KeyValueStorage abstract interface (MMKV / Memory implementations)
• Add CsSettingsStorage for per-app proxy settings
• Add the ClientLog data model
• Profile adds the outboundsCount field and supports fetching all Profile IDs
• Add the defaultTestUrl constant

Improvements #

• Cache the sing-box version string to avoid repeated fetches (performance optimization)
• Add explicitToJson to models, fixing JSON serialization of nested models
• Refactor the VPN service startup logic, caching event stream state
• Upgrade JSON serialization dependencies: json_annotation → 4.12.0, json_serializable → 6.14.0
• Remove the android:process=":remote" attribute from VpnService

Fixes #

• Fix VPN service restart
• Fix Clash mode setting and connection management issues
• Fix the Android service shutdown logic
• Add a null guard for logSink in appendLogs to avoid a null pointer exception

Refactoring #

• Refactor the storage layer: ProfileManager renamed to ProfileStorage, replacing direct MMKV calls with the KeyValueStorage abstract interface
• Migrate ClientGroupItem / ClientGroup to freezed data classes
• Make some Route and RuleSet fields optional for flexibility
• Refactor the Android service implementation and update dependencies
• Clean up the deprecated custom module and debug code

Features #

• Add app-level proxy mode (disable / exclude / include)
• Support per-app proxy rules via the app list

Improvements #

• Update the MMKV dependency to 2.4.0
• Optimize app list storage (JSON array format)
• Update the Android build environment (Kotlin 2.3.20, Gradle 8.14.4)

Refactoring #

• Remove the sniff field from the Inbound model
• Refactor the app list data structure (List/Set conversion optimization)

• Update sing-box dependency to 1.12.25 for Android.

• Route Rule: Added IP CIDR and port filtering support
  • New fields: ip_cidr, source_ip_cidr, port, port_range, source_port, source_port_range
  • Enhanced traffic matching with IP and port-based routing
  • Full JSON serialization support with backward compatibility

Features #

• Add DNS rule action configuration and new domain matching fields
• Add RuleAction constants for routing rules

Improvements #

• Optimize proxy configuration template and simplify DNS/route rules
• Adjust default log level from trace to info
• Update User-Agent string for better compatibility

Refactoring #

• Remove remote rule set configuration (geoip-cn, geosite-cn)
• Simplify configuration structure and improve performance
• Make Route fields optional for flexibility

• Update sing-box dependency to 1.12.24 for Android.

• Update sing-box dependency to 1.12.23 for Android.

• Update sing-box dependency to 1.12.22 for Android.

• Update sing-box dependency to 1.12.20 for Android.

• Update libbox dependency to 1.12.19 for Android.
• Update documentation and project links in README.
• Bump version to 1.0.4.

• Add getSingBoxVersion() API to retrieve the underlying sing-box core version.
• Optimize memory usage and stability for long-running VPN services.
• Improve error handling during remote profile synchronization.
• Update dependencies to latest versions (dio, mmkv, package_info_plus, etc.).
• Minor bug fixes and performance improvements.

• Improve package description and API documentation coverage to increase pub score.
• Add comprehensive README with features, platform support, and basic usage.
• Add Chinese documentation (README_CN.md).
• Showcase projects using this plugin (clash_sing_app).

• Initial release of the flutter_sing_box plugin.
• Support for sing-box as a VPN service.
• Ability to import remote profiles.
• Clash API support for managing proxies and groups.
• UI for managing profiles and viewing connection status.
• Support for various protocols like Hysteria, TUIC, etc.
• Core functionalities like network service, profile management, and custom logging.
• Many bug fixes and performance improvements.