Skip to content

feat(sub): support dynamic template variables in subscription remarks#5430

Open
wahh3b-lgtm wants to merge 3 commits into
MHSanaei:mainfrom
wahh3b-lgtm:feature/dynamic-remark-variables
Open

feat(sub): support dynamic template variables in subscription remarks#5430
wahh3b-lgtm wants to merge 3 commits into
MHSanaei:mainfrom
wahh3b-lgtm:feature/dynamic-remark-variables

Conversation

@wahh3b-lgtm

@wahh3b-lgtm wahh3b-lgtm commented Jun 18, 2026

Copy link
Copy Markdown

Description

This Pull Request introduces a dynamic, zero-database-schema client remark templating system for generated subscription and configuration share links.

Currently, 3x-ui generates configuration remarks statically. This PR implements an opt-in, highly robust pre-processor mapping layer that allows administrators to define dynamic variables inside the Inbound Remark or Client Remark fields (e.g., 📊 Left: {DATA_LEFT} of {DATA_LIMIT} | {STATUS_EMOJI}). When a user updates their subscription or copies their link, these variables are dynamically resolved on-the-fly with their real-time bandwidth and expiration statistics.


Core Technical Features & Architecture

  1. Zero Database Schema Changes:
    No database columns were added or modified. The system is entirely backwards-compatible and opt-in. If an inbound or client remark does not contain { or } characters, the parser safely falls back to standard static naming.
  2. Zero-Dependency Core:
    Rather than introducing large external calendar libraries to go.mod for Persian Shamsi date calculations, this PR includes a highly optimized, lightweight inline mathematical Gregorian-to-Jalali conversion utility.
  3. Timezone-Aware Calculations:
    Standardized expiration calculations were migrated from UTC to the server's local timezone (.In(time.Local)) to resolve the off-by-one day error where clients under the Asia/Tehran timezone (UTC+3:30) would see their expiration day offset incorrectly.
  4. Performance & GC Optimization:
    All regular expressions are pre-compiled at the package level, and strings.Builder is used across string formatting paths to minimize heap allocations and avoid garbage collection (GC) pressure under heavy concurrent subscription requests.
  5. Robust String Parsing:
    Built-in character scanning safely handles unclosed braces, non-matching variables, and potential naming collisions on subsequent links (nameOnlyTemplate verification).

Supported Dynamic Variables

Administrators can use the following variables in the Inbound or Client Remark field (excluding {ADMIN_USERNAME}):

Variable Example Output Description
{USERNAME} Name The username or email of the client
{DATA_USAGE} 8.00 GB Formatted data used by the client
{DATA_LEFT} 92.00 GB Formatted remaining traffic
{DATA_LIMIT} 100.00 GB Formatted total traffic limit (displays "∞" if unlimited)
{DAYS_LEFT} 14 Remaining days before expiration
{EXPIRE_DATE} 2026-06-18 Gregorian expiry date
{JALALI_EXPIRE_DATE} 1405/03/28 Shamsi/Persian expiry date
{TIME_LEFT} 14d 6h 30m Remaining duration (days, hours, minutes)
{STATUS_EMOJI} Current status icon (✅ active, ⏳ expired, 🚫 limited)
{USAGE_PERCENTAGE} 8.0% Data usage percentage (empty if unlimited)
{PROTOCOL} VLESS Uppercased protocol
{TRANSPORT} xhttp Transport method (tcp, ws, grpc, xhttp, quic)

Example Usage

Template:

📊 {USAGE_PERCENTAGE} | 📉 {DATA_LEFT} of {DATA_LIMIT} | {STATUS_EMOJI}

Resolved Output (active client, 92GB left of 100GB):

📊 8.0% | 📉 92.00GB of 100.00GB | ✅

Resolved Output (expired client):

📊 100.0% | 📉 0.00GB of 10.00GB | ⏳

Files Modified

File Change
internal/sub/remark_vars.go Core engine: 6 new tokens, Jalali converter, single-brace translator, timezone fix
internal/sub/remark_vars_test.go 8 new test functions covering all new tokens and edge cases
internal/sub/service.go Transport parameter threading through all protocol link generators
internal/sub/host_sub.go Transport threading through host endpoint remark rendering
internal/sub/json_service.go Transport extraction for JSON subscription pipeline
internal/sub/clash_service.go Transport extraction for Clash subscription pipeline
internal/sub/endpoint.go Transport parameter in VMess endpoint link builder
internal/sub/endpoint_test.go Updated test for new transport parameter
.gitignore Added .mimocode exclusion

Testing & Quality Control

  • Test Suite: 25 unit tests in internal/sub/remark_vars_test.go and internal/sub/endpoint_test.go
  • Tests Passed: 25/25 assertions pass successfully
  • Coverage includes: timezone boundaries, edge-case math (unlimited traffic logic), single-bracket translation, Jalali calendar accuracy (verified against known reference dates), and first-link-only info stripping

@wahh3b-lgtm wahh3b-lgtm changed the title feat(sub): implement dynamic single-bracket remark variables with timezone-aware inline Jalali conversion feat(sub): support dynamic template variables in subscription remarks Jun 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant