XTLS Vision: Defer Splice handoff until write completes by HeXis-YS · Pull Request #5737 · XTLS/Xray-core

HeXis-YS · 2026-02-27T20:52:58Z

Summary

This PR addresses an intermittent Vision handoff race that can lead to TLS stream breakage (ERR_SSL_PROTOCOL_ERROR), as reported in #4878.

Root Cause

In VisionWriter.WriteMultiBuffer, inbound.CanSpliceCopy could become 1 before the current direct-write buffer had fully flushed.
That allowed splice mode to start while Vision was still writing to the same socket, creating a race at the handoff boundary.

Changes

Updated VisionWriter.WriteMultiBuffer in proxy/proxy.go:
- keep splice readiness in a local variable during direct-write switch;
- perform w.Writer.WriteMultiBuffer(mb) first;
- only then set inbound.CanSpliceCopy = 1 (if still eligible).

This keeps existing Vision behavior intact while making splice handoff ordering deterministic.

RPRX · 2026-03-02T08:43:28Z

@yuhan6665

yuhan6665 · 2026-03-03T03:34:50Z

@HeXis-YS thanks for your work.
I understand you want to make sure the buffer is written first and cleared, and then send the signal by setting the CanSpliceCopy flag. Although I believe there are more than one thread (reader) running and more than one buffer involved. So your proposal maybe better in some cases, but maybe not in others.
My test is this - see if we can get rid of the time.Sleep() in CopyRawConnIfExist() completely, and only rely on code signal to switch to splice copy - I feel like we may need another signal. If we can do that we probably really solve the root cause.

Copilot

Pull request overview

This PR aims to eliminate an intermittent XTLS Vision splice handoff race (reported in #4878) by making splice enablement happen deterministically only after the relevant direct write completes, and by refactoring splice-copy state transitions behind session helper methods.

Changes:

Adds a session-level splice readiness signal (spliceCopySignal) and helper methods (ArmSpliceCopy, EnableSpliceCopy, DisableSpliceCopy, SpliceCopyReady).
Updates many inbounds/outbounds to use the new splice-copy helper methods instead of mutating CanSpliceCopy directly.
Adjusts Vision splice handoff logic in proxy/proxy.go to defer enabling splice until after WriteMultiBuffer returns, and updates splice gating checks to use SpliceCopyReady/State.

Reviewed changes

Copilot reviewed 26 out of 26 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
`common/session/splice.go`	Introduces splice readiness signaling + helper APIs for Inbound/Outbound splice-copy state.
`common/session/session.go`	Adds internal `spliceCopy` field to `Inbound`/`Outbound` session metadata.
`proxy/proxy.go`	Defers Vision splice enable until after write completion; updates splice checks to use new helpers.
`proxy/socks/server.go`	Uses new splice-copy helpers for arming/enabling/disabling splice.
`proxy/socks/client.go`	Uses new splice-copy helpers for arming/enabling splice during request/response handling.
`proxy/http/server.go`	Uses new splice-copy helpers for arming/enabling/disabling splice around CONNECT handling.
`proxy/http/client.go`	Uses new splice-copy helpers for arming/enabling splice in response path.
`proxy/vless/inbound/inbound.go`	Replaces direct `CanSpliceCopy` manipulation with helper methods in flow handling.
`proxy/vless/outbound/outbound.go`	Replaces direct `CanSpliceCopy` manipulation with helper methods in flow handling.
`proxy/vmess/inbound/inbound.go`	Disables splice via helper method.
`proxy/vmess/outbound/outbound.go`	Disables splice via helper method.
`proxy/trojan/server.go`	Disables splice via helper method.
`proxy/trojan/client.go`	Disables splice via helper method.
`proxy/shadowsocks/server.go`	Disables splice via helper method.
`proxy/shadowsocks/client.go`	Disables splice via helper method.
`proxy/shadowsocks_2022/inbound.go`	Disables splice via helper method.
`proxy/shadowsocks_2022/inbound_multi.go`	Disables splice via helper method.
`proxy/shadowsocks_2022/inbound_relay.go`	Disables splice via helper method.
`proxy/shadowsocks_2022/outbound.go`	Disables splice via helper method.
`proxy/hysteria/server.go`	Disables splice via helper method.
`proxy/hysteria/client.go`	Disables splice via helper method.
`proxy/wireguard/server.go`	Uses helper method to disable splice; minor formatting alignment in `routingInfo`.
`proxy/wireguard/client.go`	Uses helper method to disable splice.
`proxy/freedom/freedom.go`	Uses helper method to enable splice.
`proxy/dokodemo/dokodemo.go`	Uses helper method to enable splice.
`common/mux/server.go`	Disables splice for mux connections via helper method.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-03T07:31:58Z

common/session/splice.go

+func (i *Inbound) EnableSpliceCopy() {
+	if i.CanSpliceCopy == 3 {
+		return
+	}
+	if i.spliceCopy != nil {
+		i.spliceCopy.once.Do(func() {
+			close(i.spliceCopy.ready)
+		})
+	}
+	i.CanSpliceCopy = 1


EnableSpliceCopy / SpliceCopyReady access i.spliceCopy multiple times without any synchronization. Since these flags are checked/updated across goroutines (splice loop vs protocol handlers), DisableSpliceCopy() can nil spliceCopy between the nil-check and subsequent field access, leading to a potential nil-pointer panic (and still a data race). Consider (1) capturing sc := i.spliceCopy once and only using sc (including inside the once.Do closure), and (2) adding proper synchronization (e.g., atomic.Pointer + atomic.Int32, or a mutex) so CanSpliceCopy/spliceCopy updates are race-free.

Copilot · 2026-03-03T07:31:59Z

common/session/splice.go

+func (i *Inbound) SpliceCopyReady() bool {
+	if i.spliceCopy != nil {
+		select {
+		case <-i.spliceCopy.ready:
+			return true
+		default:
+			return false
+		}


SpliceCopyReady checks i.spliceCopy != nil and then reads i.spliceCopy.ready again in the select. If another goroutine calls DisableSpliceCopy() concurrently, this can panic due to i.spliceCopy becoming nil between those two reads. At minimum, read the pointer once into a local variable before the select; ideally also guard reads/writes to spliceCopy/CanSpliceCopy with atomics or a mutex.

HeXis-YS · 2026-03-03T09:48:47Z

@yuhan6665
I have tested it on my server and it works fine. However, my test scenarios are very limited.
Please feel free to test. Any ideas or suggestions are welcome.

yuhan6665 · 2026-03-03T12:43:38Z

~~Can you try remove time.Sleep() in CopyRawConnIfExist() and test it again?~~ nevermind I just see you did it

yuhan6665 · 2026-03-07T03:37:33Z

@HeXis-YS sorry but I can't understand what you added for the ready channel. I don't think it does anything more since there is no other new code signal than the existing place to call EnableSpliceCopy()
If you agree, can you remove the three new commits? And keep the removal of time.sleep() in CopyRawConnIfExist()

Maybe we can do a beta release and see if the issue is fixed.

Fangliding · 2026-03-07T04:21:37Z

话说vless入站不是早就改成dispatchlink不走pipe了吗就一个gouroutine在搬东西还有竞争?

HeXis-YS · 2026-03-07T10:09:01Z

Done.
These 3 commits were actually intended to fix the problem raised by Copilot, but it seems Copilot wasn't that smart.

yuhan6665 · 2026-03-07T12:49:43Z

话说vless入站不是早就改成dispatchlink不走pipe了吗就一个gouroutine在搬东西还有竞争?

Seems you are right, let's give it a try

proxy: defer Vision splice handoff until write completes

8a4f12d

proxy: add explicit splice handoff signal

d38b22f

Copilot AI review requested due to automatic review settings March 3, 2026 07:27

Copilot started reviewing on behalf of HeXis-YS March 3, 2026 07:27 View session

Copilot AI reviewed Mar 3, 2026

View reviewed changes

HeXis-YS added 2 commits March 3, 2026 15:42

session: synchronize splice copy state

bdc2ddd

session: lock splice state initialization

639095e

revert: drop splice handoff signal changes

0f72e8f

yuhan6665 approved these changes Mar 7, 2026

View reviewed changes

RPRX force-pushed the main branch 2 times, most recently from 9529a82 to 2320416 Compare March 22, 2026 13:36

RPRX changed the title ~~proxy: defer Vision splice handoff until write completes~~ XTLS Vision: Defer Splice handoff until write completes Mar 22, 2026

RPRX merged commit f926ee4 into XTLS:main Mar 22, 2026
39 checks passed

RPRX mentioned this pull request Mar 22, 2026

Fix occasional SSL protocol error in XTLS Vision direct copy mode #5520

Closed

BrewTestBot mentioned this pull request Mar 27, 2026

xray 26.3.27 Homebrew/homebrew-core#274677

Merged

1 task

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

XTLS Vision: Defer Splice handoff until write completes#5737

XTLS Vision: Defer Splice handoff until write completes#5737
RPRX merged 5 commits intoXTLS:mainfrom
HeXis-YS:fix-vision

HeXis-YS commented Feb 27, 2026

Uh oh!

RPRX commented Mar 2, 2026

Uh oh!

yuhan6665 commented Mar 3, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Mar 3, 2026

Uh oh!

Copilot AI Mar 3, 2026

Uh oh!

HeXis-YS commented Mar 3, 2026 •

edited

Loading

Uh oh!

yuhan6665 commented Mar 3, 2026 •

edited

Loading

Uh oh!

yuhan6665 commented Mar 7, 2026

Uh oh!

Fangliding commented Mar 7, 2026

Uh oh!

HeXis-YS commented Mar 7, 2026 •

edited

Loading

Uh oh!

yuhan6665 commented Mar 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

HeXis-YS commented Feb 27, 2026

Summary

Root Cause

Changes

Uh oh!

RPRX commented Mar 2, 2026

Uh oh!

yuhan6665 commented Mar 3, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 3, 2026

Choose a reason for hiding this comment

Uh oh!

HeXis-YS commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yuhan6665 commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yuhan6665 commented Mar 7, 2026

Uh oh!

Fangliding commented Mar 7, 2026

Uh oh!

HeXis-YS commented Mar 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

yuhan6665 commented Mar 7, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

HeXis-YS commented Mar 3, 2026 •

edited

Loading

yuhan6665 commented Mar 3, 2026 •

edited

Loading

HeXis-YS commented Mar 7, 2026 •

edited

Loading