fix(finalmask): support stable fragment schema

[dr-hoseyn]

Summary

• emit both singular (length/delay) and plural (lengths/delays) FinalMask fragment fields
• apply compatibility to host subscription links, generated Xray subscriptions, and Core Editor inbound/outbound configs
• preserve newer multi-range behavior while using the first range as the stable-core fallback

Validation

• python -m pytest -q tests/test_finalmask_compatibility.py tests/test_subscription_clash_hysteria.py tests/test_subscription_clash_xhttp.py (15 passed)
• python -m pytest -q tests --ignore=tests/api --ignore=tests/test_review_admins_unit.py (173 passed, 2 skipped)
• python -m ruff check ...
• npm exec -- tsc --noEmit
• npm run build
• Core Kit validation accepts a config containing both schemas

Fixes #845

Summary by CodeRabbit

• Bug Fixes
  • Improved Xray final-mask compatibility by ensuring fragment settings include the expected singular length and delay values.
  • Preserved explicitly configured singular values while filling missing or empty values from their corresponding lists.
  • Applied compatibility handling consistently to inbound and outbound configurations.

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: 207867a3-227c-40d2-a36d-8cd56ecfb81d

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: d2f9efdd-8bb6-40ad-bc39-082e9249f5b4

📥 Commits

Reviewing files that changed from the base of the PR and between 630b33d and b3f7ca3.

📒 Files selected for processing (5)

• app/core/hosts.py
• app/models/host.py
• app/subscription/xray.py
• dashboard/src/features/core-editor/kit/xray-adapter.ts
• tests/test_finalmask_compatibility.py

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

Walkthrough

FinalMask serialization now emits singular and plural fragment fields. Backend host and subscription paths use the shared serializer. Dashboard compiled configurations normalize FinalMask settings for inbound and outbound entries.

Changes

FinalMask compatibility

Layer / File(s)	Summary
FinalMask serializer and validation app/models/host.py, tests/test_finalmask_compatibility.py	Adds shared FinalMask serialization, fragment-field fallback handling, and tests for explicit, empty, plural, and singular values.
Backend serialization integration app/core/hosts.py, app/subscription/xray.py	Routes host and subscription FinalMask output through the shared serializer.
Dashboard compiled-config normalization dashboard/src/features/core-editor/kit/xray-adapter.ts	Normalizes fragment fields in FinalMask settings for inbound and outbound compiled configuration entries.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Merge Risk: ⚪ Minimal · up to b3f7c

FinalMask configurations now include stable-core singular fragment fields alongside newer plural fields without changing multi-range values, allowing generated configurations to work across supported Xray-core schemas. No current merge-blocking risk remains.

Suggested reviewers: immohammad20000, x0sina, m03ed

Poem

A rabbit packs fields in a neat little row
Singular and plural now travel in tow
Fragment masks hop through each config gate
Tests guard the values at every state
Xray finds both names waiting in place

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 23.08% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 13 functions across 5 files.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: FinalMask support for the stable fragment schema.
Linked Issues check	✅ Passed	The changes satisfy issue #845 by emitting singular and plural FinalMask fragment fields across host subscriptions, generated Xray subscriptions, and Core Editor configurations. The implementation pre…
Out of Scope Changes check	✅ Passed	All modified files and added tests directly support FinalMask schema compatibility described in issue #845. No unrelated code changes are identified.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[dr-hoseyn]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.