v5.2 - Annual Wrap-Up 🎁

📝 Release Notes

This release is expected to be the final update in 2021, with mostly QoL improvements and bug fixes.

• SDK: Updated to .NET 6.
• Outline API key: Made CertSha256 optional.
• Group removals now trigger a recalculation of user data usage.
• Telegram bot: Register commands that handle sensitive information only for private chats.
• Telegram bot: Automatically split long reports that can't fit in one message into separate messages.
• Telegram bot: Performance improvements of string processing using ReadOnlySpan<char>.
• Fix: Renaming users in non-Outline groups no longer gives error messages.
• Outline: Not-linked error messages now include the group name.
• Outline: Warn instead of throwing arbitrary errors when trying to rotate passwords in non-Outline groups.
• Outline: Added --all option to the rotate password command.

2021 is an especially difficult year for many of us. The pandemic is not going away. New variants. Booster shots. Restrictions and mandates. COVID burnouts. The future looks grim.

For this project, 2021 saw some major changes and many many new features. We (and by we I mean I 😜) started using GitHub actions to automate building and testing. We published packages to NuGet and AUR (Arch User Repository). We introduced a Telegram bot to help with user interactions. We added an API server to replace the static file online config generator.

In 2022, we plan to shift all operations from the CLI to the API server. Just edit a simple config file, spin up the server, and you are ready to go. To achieve this, we have to integrate all existing logic in the CLI into the API server, expand the API server to support federation with other servers. The API server will run independently on all participating servers, so it has to support interacting with different backends. It's going to be a lot of work. Hopefully 2022 won't suck as much as 2021 does, and we can continue to deliver awesome new features!

🐛 Known Issues

• 🎉 No known issues!

📦 Packaging

Note: this naming convention applies to all packages.

Filename	Build type
ss-uri-gen-v5.2-linux-arm64.tar.zst	.NET 6 - Linux ARM64 self-contained
ss-uri-gen-v5.2-linux-x64.tar.zst	.NET 6 - Linux x64 self-contained
ss-uri-gen-v5.2-linux.tar.zst	.NET 6 - Linux Any CPU framework-dependent
ss-uri-gen-v5.2-windows-arm64.7z	.NET 6 - Windows ARM64 self-contained
ss-uri-gen-v5.2-windows-arm64.zip	.NET 6 - Windows ARM64 self-contained
ss-uri-gen-v5.2-windows-x64.7z	.NET 6 - Windows x64 self-contained
ss-uri-gen-v5.2-windows-x64.zip	.NET 6 - Windows x64 self-contained
ss-uri-gen-v5.2-windows.7z	.NET 6 - Windows Any CPU framework-dependent
ss-uri-gen-v5.2-windows.zip	.NET 6 - Windows Any CPU framework-dependent

© 2021 database64128

v5.1 - Swift Domination 🏊

📝 Release Notes

• 🌐 API server: Enable Swagger UI and ReDoc UI in all hosting environments. Links to these UI endpoints are included in online config links.
• 📦 NuGet package: XML docs are now generated and included in the package.
• 📄 Online Config: Updated to latest OOCv1 spec.
• 🛠️ Bug fixes and improvements
  • API server: X-Real-IP is now prioritized over X-Forwarded-For. See the documentation for more information.
  • Online config: Node group is now included in delivery server object.
  • Online config: Fixed an issue where the delivery document contains outdated data usage metrics.
  • Online config: Fixed an issue where getting online config in V2Ray outbound format throws an exception when there are servers with plugins.
  • Cleanup: Use base64url utils from Shadowsocks package.
  • Cleanup: Use ss:// URI builder from Shadowsocks package.
  • Telegram bot: Merged /list_node_annotations into /list_nodes.

🐛 Known Issues

• 🎉 No known issues!

📦 Packaging

Note: this naming convention applies to all packages.

Filename	Build type
ss-uri-gen-v5.1-linux-arm64.tar.zst	.NET 5 - Linux ARM64 self-contained
ss-uri-gen-v5.1-linux-x64.tar.zst	.NET 5 - Linux x64 self-contained
ss-uri-gen-v5.1-linux.tar.zst	.NET 5 - Linux Any CPU framework-dependent
ss-uri-gen-v5.1-windows-arm64.7z	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v5.1-windows-arm64.zip	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v5.1-windows-x64.7z	.NET 5 - Windows x64 self-contained
ss-uri-gen-v5.1-windows-x64.zip	.NET 5 - Windows x64 self-contained
ss-uri-gen-v5.1-windows.7z	.NET 5 - Windows Any CPU framework-dependent
ss-uri-gen-v5.1-windows.zip	.NET 5 - Windows Any CPU framework-dependent

© 2021 database64128

v5.0 - Dynamic Consistency 🪆

📝 Release Notes

• 🌐 API server: Shadowsocks URI Generator API Server provides an API endpoint for basic management tasks and online config.
  • Online config support for Open Online Config, SIP008, and V2Ray outbound format. This obsoletes the legacy static online config generator.
  • Simple queries to filter and sort servers: sortByName, tag, group, nodeOwner, groupOwner.
  • CLI and Telegram bot commands for the generation of API URLs and tokens: online-config get-links and /get_online_config_links.
• 🐶 Node and group ownership: Set an owner for individual nodes and groups. Node owners are included in OOCv1 and SIP008 JSON files.
• 🏷️ Tags: The nodes can be annotated with tags for filtering and selection. Use CLI commands to bulk add/edit/remove tags. Tags are included in OOCv1 and SIP008 JSON files.
• 📦 NuGet package: The ShadowsocksUriGenerator library is now published at NuGet. The package is automatically updated on each new release.
• 🛠️ Bug fixes and improvements
  • Added CLI and bot commands to list annotations (owner, tags).
  • Removed the legacy group list-credentials command. Use group list-members instead.
  • The legacy static online config generator has been renamed from OnlineConfig to SIP008StaticGen for clarity.
  • The legacy static online config generator has been updated to support ownership and tags.
  • The bundled systemd unit file ss-uri-gen.service no longer invokes the static online config generator. Use the API server with ss-uri-gen-server.service instead.
  • The string representation of an amount of data now uses K/M/G/T/P/EiB with a conversion rate of 1024 between each unit instead of K/M/G/T/P/EB.
  • Telegram bot: Executing /get_group_data_usage without specifying a group defaults to groups owned by the user.
  • Telegram bot: Do not trim quotation marks in command arguments.
  • Updated project descriptions and documents.

🐛 Known Issues

• 🎉 No known issues!

📦 Packaging

Note: this naming convention applies to all packages.

Filename	Build type
ss-uri-gen-v5.0-linux-arm64.tar.zst	.NET 5 - Linux ARM64 self-contained
ss-uri-gen-v5.0-linux-x64.tar.zst	.NET 5 - Linux x64 self-contained
ss-uri-gen-v5.0-linux.tar.zst	.NET 5 - Linux Any CPU framework-dependent
ss-uri-gen-v5.0-windows-arm64.7z	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v5.0-windows-arm64.zip	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v5.0-windows-x64.7z	.NET 5 - Windows x64 self-contained
ss-uri-gen-v5.0-windows-x64.zip	.NET 5 - Windows x64 self-contained
ss-uri-gen-v5.0-windows.7z	.NET 5 - Windows Any CPU framework-dependent
ss-uri-gen-v5.0-windows.zip	.NET 5 - Windows Any CPU framework-dependent

© 2021 database64128

v4.3 - Hidden Elegance 🦋

📝 Release Notes

• 🐶 Chatbot: The Telegram bot has been refactored to follow a more modular architecture design, as seen in CubicBot. Other changes include:
  • Changed to use QueuedUpdateReceiver to asynchronously stream updates.
  • Reply format has been tweaked to look better in chats.
  • Removed unnecessary uses of MarkdownV2. All MarkdownV2 uses are now processed in a unified way to ensure all characters are properly escaped.
  • You can now configure a service name to display in the welcome message.
• 🔢 Export data usage metrics as CSV: The report command in the CLI and the bot now supports exporting data usage by group and by user as separate CSV files.
• ✂️ Cleaner tables: The data remaining column in data usage tables will be omitted if the displayed data has no data limit.
• 🌐 Open Online Config (OOC): This project intends to be a reference implementation of the Open Online Config Version 1 protocol, which is still being worked on as of this release. All mentions of SIP008 have been updated to OOCv1, since OOCv1 is backwards compatible with SIP008.
• 🛠️ Bug fixes and improvements
  • The total data remaining in reports will only be calculated if every group has a data limit.

🐛 Known Issues

• 🎉 No known issues!

📦 Packaging

Note: this applies to the chatbot and the rescue tool as well.

Filename	Build type
ss-uri-gen-v4.3-linux-arm64.tar.zst	.NET 5 - Linux ARM64 self-contained
ss-uri-gen-v4.3-linux-x64.tar.zst	.NET 5 - Linux x64 self-contained
ss-uri-gen-v4.3-linux.tar.zst	.NET 5 - Linux Any CPU framework-dependent
ss-uri-gen-v4.3-windows-arm64.7z	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v4.3-windows-arm64.zip	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v4.3-windows-x64.7z	.NET 5 - Windows x64 self-contained
ss-uri-gen-v4.3-windows-x64.zip	.NET 5 - Windows x64 self-contained
ss-uri-gen-v4.3-windows.7z	.NET 5 - Windows Any CPU framework-dependent
ss-uri-gen-v4.3-windows.zip	.NET 5 - Windows Any CPU framework-dependent

© 2021 database64128

v4.2 - Compact Persistency 🪨

📝 Release Notes

• 🪗 More compact tables: Table column widths are now calculated using only the retrieved data, instead of all local data. Plugin and plugin options columns are now omitted if the nodes to display have no plugins.
• 🛠️ Bug fixes and improvements
  • Fixed Outline server password rotation.
  • Updated to use GitHub-native Dependabot.
  • Total data used and remaining will be recalculated when removing linked Outline server.
  • Fixed config persistency issues by updating JSON serialization options to only omit default values when writing data JSON files.

🐛 Known Issues

• 🎉 No known issues!

📦 Packaging

Note: this applies to the chatbot and the rescue tool as well.

Filename	Build type
ss-uri-gen-v4.2-linux-arm64.tar.zst	.NET 5 - Linux ARM64 self-contained
ss-uri-gen-v4.2-linux-x64.tar.zst	.NET 5 - Linux x64 self-contained
ss-uri-gen-v4.2-linux.tar.zst	.NET 5 - Linux Any CPU framework-dependent
ss-uri-gen-v4.2-windows-arm64.7z	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v4.2-windows-arm64.zip	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v4.2-windows-x64.7z	.NET 5 - Windows x64 self-contained
ss-uri-gen-v4.2-windows-x64.zip	.NET 5 - Windows x64 self-contained
ss-uri-gen-v4.2-windows.7z	.NET 5 - Windows Any CPU framework-dependent
ss-uri-gen-v4.2-windows.zip	.NET 5 - Windows Any CPU framework-dependent

© 2021 database64128

v4.1 - Quality of Life Matters! 🧬

📝 Release Notes

• 🌊 Async streams: Bulk operations involving Outline API requests are now streaming the results back. This allows any error message to be shown immediately when it's available. Previously all error messages from a bulk operation are combined and shown when the whole operation completes.
• 🌋 Error handling: Code related to exception handling has been refactored to strictly follow a new guideline. This ensures reliable error handling and returns error messages with more details.
• 🔏 Input validation: Validate Shadowsocks AEAD method to only accept standard methods. Validate Outline API keys to prevent unexpected unsecure connections.
• 🛠️ Bug fixes and improvements
  • This version fixed an issue where invoking any Outline server command that targets all groups generates errors on non-Outline groups.
  • The project now depends on System.Linq.Async and System.Interactive.Async.
  • This version refined Outline server association logic to be more reliable.
  • This version refined the logic of setting Outline admin key username to avoid unnecessary API operations.
  • The outline-server get command now prints admin key username if there's an admin key present.
  • This version removed a previous workaround for command argument types by avoiding using nullable reference types as command argument types.
  • This version optimized some data models to be explicitly mutable or immutable.

🐛 Known Issues

• 🎉 No known issues!

📦 Packaging

Note: this applies to the chatbot and the rescue tool as well.

Filename	Build type
ss-uri-gen-v4.1-linux-arm64.tar.zst	.NET 5 - Linux ARM64 self-contained
ss-uri-gen-v4.1-linux-x64.tar.zst	.NET 5 - Linux x64 self-contained
ss-uri-gen-v4.1-linux.tar.zst	.NET 5 - Linux Any CPU framework-dependent
ss-uri-gen-v4.1-windows-arm64.7z	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v4.1-windows-arm64.zip	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v4.1-windows-x64.7z	.NET 5 - Windows x64 self-contained
ss-uri-gen-v4.1-windows-x64.zip	.NET 5 - Windows x64 self-contained
ss-uri-gen-v4.1-windows.7z	.NET 5 - Windows Any CPU framework-dependent
ss-uri-gen-v4.1-windows.zip	.NET 5 - Windows Any CPU framework-dependent

© 2021 database64128

v4.0 - Extraordinarily Within the Limit! 🪧

📝 Release Notes

• 🏗️ Major refactoring: The project has been restructured and split into several library and CLI projects to make it easier to maintain. Beware of these changes!
• 🗃️ Reliable file operations: The reliability of the file operations has been significantly improved. Each time a write operation occurs, one previous version of the config file is now preserved with a .old suffix.
• ☑️ Command validations: This version implemented new custom command parsers and validators to make sure proper arguments and options are passed before proceeding to command invocation.
• 💳 Group credential management: Add, remove, and list credentials directly in groups. You can also add a user to multiple groups with the same credential across all groups.
• ⛑️ Rescue tool: Lost your main config files by accident? You can now reconstruct config from the generated online config with the new rescue tool. The rescue tool works best if you have grouped online config enabled.
• 📶 Data limit: The new version brings full support for Outline server's data limit feature. Each user and group now has one global data limit and one per-key data limit. In each group you can also set custom data limits on each user. This change brings a breaking change of config file format. The new version will automatically update the config for you. The compatibility layer for previous formats might get removed in v5.0. New commands for data limit related tasks are also ready in CLI and Telegram bot.
• 🛠️ Bug fixes and improvements
  • Each command now prints detailed execution result and returns an integer as the result. You can now rely on the return value of the program to determine if the operation is successful.
  • We have removed the obsolete publish profiles. Follow the guide in README.md for build steps.
  • The project description has been updated to better reflect the current status and the intended use of the project.
  • We optimized the Credential type to remove redundant code and improve reliability.
  • We have removed unused, obsolete settings (OutlineServerDeployOnChange and OnlineConfigUpdateDataUsageOnGeneration) to reduce confusion.
  • We have updated the Outline API client logic to make sure the local state always syncs with the Outline server.
  • The nullable Credential type has been renamed to Memberinfo to better reflect its new purpose in the context of data limit support.
  • The Credentials dictionary has been renamed to Memberships since it actually stores user-group mappings since v3.0.
  • We have added a new setting OutlineServerApplyDataLimitOnAssociation to control whether the group's per-user data limit is applied to the Outline server when establishing an association with it. It defaults to true.
  • The Telegram bot now uses nightly upstream NuGet packages. The most significant change is the type of the user ID from int to long.
  • The Telegram bot now registers its supported commands on startup. You don't have to manually register commands anymore.
  • Errors when setting the admin key username on Outline server association are now omitted, because the admin key may have been deleted. Explicitly setting the admin username via the set command still returns proper error messages as expected.
  • A lot of cleanups have happened between this version and the previous one. The code quality has significantly improved.

🐛 Known Issues

• 🎉 No known issues!

📦 Packaging

Note: this applies to the chatbot and the rescue tool as well.

Filename	Build type
ss-uri-gen-v4.0-linux-arm64.tar.zst	.NET 5 - Linux ARM64 self-contained
ss-uri-gen-v4.0-linux-x64.tar.zst	.NET 5 - Linux x64 self-contained
ss-uri-gen-v4.0-linux.tar.zst	.NET 5 - Linux Any CPU framework-dependent
ss-uri-gen-v4.0-windows-arm64.7z	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v4.0-windows-arm64.zip	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v4.0-windows-x64.7z	.NET 5 - Windows x64 self-contained
ss-uri-gen-v4.0-windows-x64.zip	.NET 5 - Windows x64 self-contained
ss-uri-gen-v4.0-windows.7z	.NET 5 - Windows Any CPU framework-dependent
ss-uri-gen-v4.0-windows.zip	.NET 5 - Windows Any CPU framework-dependent

© 2021 database64128

v3.6 - Easy Bulky 🛍️

📝 Release Notes

• ☑️ We added new command options to simplify bulk operations, like adding all users to a new group, or assigning all groups to a new user.
• 🕸️ We added new command options to make it easier to filter out the information you want.
• 🛠️ Bug fixes and improvements
  • System.CommandLine has been updated to address issues in previous versions.
  • Missing command arguments are now properly handled.
  • We added VSCode config with build tasks and launch settings.
  • We added systemd unit files for scheduled tasks and Telegram bot.
  • The Telegram bot now has its own icon.
  • The Telegram bot now trims leading spaces as well as trailing spaces in bot command parameters.

🐛 Known Issues

• 🧢 The server data limit setter is not tested and is not guaranteed to work. We will work on this feature in a later version.
• ⚙ The new OutlineServerDeployOnChange option hasn't been properly implemented yet, and might get removed in the next release.
• 🔼 Outline integrations: Remember to run update after changing Outline server's settings or renaming a user. We are looking to add mechanisms to automatically trigger updates after these actions in a future version.

📦 Packaging

Note: this applies to the chatbot as well.

Filename	Build type
ss-uri-gen-v3.6-linux-arm64.tar.zst	.NET 5 - Linux ARM64 self-contained
ss-uri-gen-v3.6-linux-x64.tar.zst	.NET 5 - Linux x64 self-contained
ss-uri-gen-v3.6-linux.tar.zst	.NET 5 - Linux Any CPU framework-dependent
ss-uri-gen-v3.6-windows-arm64.7z	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v3.6-windows-arm64.zip	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v3.6-windows-x64.7z	.NET 5 - Windows x64 self-contained
ss-uri-gen-v3.6-windows-x64.zip	.NET 5 - Windows x64 self-contained
ss-uri-gen-v3.6-windows.7z	.NET 5 - Windows Any CPU framework-dependent
ss-uri-gen-v3.6-windows.zip	.NET 5 - Windows Any CPU framework-dependent

© 2021 database64128

v3.5 - Look Who's Here to Help You! 🤖

📝 Release Notes

• 🤖 Telegram bot: A simple and configurable chatbot that makes your life easier. Run your own bot and try it!
• 📄 Usage report: Use report to generate a usage report that summarizes data usage in the last 30 days.
• ✏ Optimized command output: Tables in command output are now drawn with the maximum content length in each column taken into account.
• 🎫 Bug fixes and improvements
  • We fixed the issue where deleting a group would leave dangling user associations behind.
  • We added an option to allow the removal of credentials from users when unlinking an Outline server.
  • We added a new command that lists group members.
  • We fixed the issue where sometimes an empty sequence could throw an exception.

🐛 Known Issues

• 🧢 The server data limit setter is not tested and is not guaranteed to work. We will work on this feature in a later version.
• ⚙ The new OutlineServerDeployOnChange option hasn't been properly implemented yet, and might get removed in the next release.
• 🔼 Outline integrations: Remember to run update after changing Outline server's settings or renaming a user. We are looking to add mechanisms to automatically trigger updates after these actions in a future version.

📦 Packaging

Note: this applies to the chatbot as well.

Filename	Build type
ss-uri-gen-v3.5-linux-arm64.tar.zst	.NET 5 - Linux ARM64 self-contained
ss-uri-gen-v3.5-linux-x64.tar.zst	.NET 5 - Linux x64 self-contained
ss-uri-gen-v3.5-linux.tar.zst	.NET 5 - Linux Any CPU framework-dependent
ss-uri-gen-v3.5-windows-arm64.7z	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v3.5-windows-arm64.zip	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v3.5-windows-x64.7z	.NET 5 - Windows x64 self-contained
ss-uri-gen-v3.5-windows-x64.zip	.NET 5 - Windows x64 self-contained
ss-uri-gen-v3.5-windows.7z	.NET 5 - Windows Any CPU framework-dependent
ss-uri-gen-v3.5-windows.zip	.NET 5 - Windows Any CPU framework-dependent

© 2021 database64128

v3.4 - Interaction as a Service 🖖

📝 Release Notes

• 🚶‍♀️ Interactive mode (REPL): .NET applications have high startup overhead. And using this tool usually requires running a series of commands. Spinning up the application multiple times, only to do one simple task during each run, is extremely inefficient. To address the issue, we added interactive mode. Use i or interactive to enter interactive mode. Then run commands as you usually do.
• 🛑 Deactivation of nodes: Sometimes, for whatever reason, one of your nodes are expected be down for an extended period of time. But it's still not long enough to convince you to remove the node from the system. However, the inconvenience of still having the node delivered and showing up can be frustrating. To help with this situation, we added a new feature to allow you to deactivate nodes without deleting them. Deactivated nodes are excluded from delivery (online config and ss:// links). So they won't bother you ever again.
• ⚙ Service mode: Run as a service to execute tasks periodically. Pull from Outline servers to get updates. Deploy local configurations to Outline servers. Generate online config after Outline server pulls finish.
• ✏ Command alias: We added alias for common commands, so you don't have to type long and boring full command names!
• ☃ Bug fixes and improvements
  • We optimized how we build self-contained binaries to reduce the size by over 50%. Binary sizes matter!
  • We implemented CancellationToken for Outline API client to allow graceful cancelations of API queries at any time.
  • We improved resource management by implementing dispose pattern for Group and Nodes to properly dispose API client.
  • We removed buggy workflow components to improve workflow reliability.

🐛 Known Issues

• 🧢 The data limit API we implemented is based on a newer API proposal. Per-user data limit won't work on production Outline servers. Server data limit is not tested and is not guaranteed to work. We will work on this feature in a later version.
• ⚙ The new OutlineServerDeployOnChange option hasn't been properly implemented yet, and will not work.
• 🔼 Outline integrations: Remember to run update after changing Outline server's settings or renaming a user. We are looking to add mechanisms to automatically trigger updates after these actions in a future version.

📦 Packaging

Filename	Build type
ss-uri-gen-v3.4-linux-arm64.tar.zst	.NET 5 - Linux ARM64 self-contained
ss-uri-gen-v3.4-linux-x64.tar.zst	.NET 5 - Linux x64 self-contained
ss-uri-gen-v3.4-linux.tar.zst	.NET 5 - Linux Any CPU framework-dependent
ss-uri-gen-v3.4-windows-arm64.7z	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v3.4-windows-arm64.zip	.NET 5 - Windows ARM64 self-contained
ss-uri-gen-v3.4-windows-x64.7z	.NET 5 - Windows x64 self-contained
ss-uri-gen-v3.4-windows-x64.zip	.NET 5 - Windows x64 self-contained
ss-uri-gen-v3.4-windows.7z	.NET 5 - Windows Any CPU framework-dependent
ss-uri-gen-v3.4-windows.zip	.NET 5 - Windows Any CPU framework-dependent

© 2021 database64128