Skip to content

feat(xray): add an Xray backend driven by the operator config - #3

Merged
mrcsin merged 32 commits into
masterfrom
xray-config
Oct 14, 2026
Merged

mrcsin merged 32 commits into
masterfrom
xray-config

Conversation

@mrcsin

@mrcsin mrcsin commented Oct 14, 2026

Copy link
Copy Markdown
Owner

usher managed AmneziaWG only. This adds an Xray backend: the operator owns Xray's config.json, usher reads it read-only, keeps the users of the managed inbounds in step with usher.yml through HandlerService, and writes clients/<user>/<tag>.json plus a share link <tag>.txt.

  • Protocols: VLESS (raw+Reality, xhttp, ws, grpc, httpupgrade), Hysteria2 (salamander, port hopping), VMess and Trojan. TLS trust is CA by default, pinning opt-in.
  • Drift guard: each inbound in the file is compared with the running Xray; a missing inbound or another protocol leaves the tag untouched, so usher never sends an account of the wrong type.
  • Stale API socket after a hard kill is removed so the restart policy can start Xray again.
  • Breaking for operators: USHER_AWG_SOCKET is required for the awg backend; users.json moves to version 2 with a users.json.v1 backup. README has an upgrade section.
  • Plan: docs/plans/completed/20261014-xray-config-backend.md.

Verified: go test -race ./..., scripts/format.sh, golden tests for 9 shapes, and the Xray e2e suite (connect, switch off, restart, hard kill, drift, certificate rewrite) on a Linux host with Xray 26.10.10. The awg e2e runs here in CI for the first time on this branch.

mrcsin and others added 30 commits October 14, 2026 17:37
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Backend.Suffix becomes Suffixes, clients.Existing takes a list, and
USHER_DNS is parsed only when USHER_AWG_SOCKET is set.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Xray creates the lock as root with mode 0644, so the read-write open
failed for usher and every pass reported Xray down. The example compose
file now binds a host socket directory that usher can write.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Prepare returns structural validation errors so the pass skips Apply.
Only x-usher hint, enroll and render errors still revoke. Drift
compares the proxy type before Build and marks a failed comparison
unusable, so no account reaches a handler of another type.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
checkDrift skipped every inbound with an error, so an x-usher typo let
Apply revoke users from a running inbound it never compared with the
file. Only structural errors skip the comparison now.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
mrcsin and others added 2 commits October 14, 2026 21:52
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
@mrcsin
mrcsin merged commit 95f8d4a into master Oct 14, 2026
2 checks passed
@mrcsin
mrcsin deleted the xray-config branch October 14, 2026 19:27
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