diff --git a/docs/.vuepress/config/sidebar/en.ts b/docs/.vuepress/config/sidebar/en.ts index c9a631c37..d86b69103 100755 --- a/docs/.vuepress/config/sidebar/en.ts +++ b/docs/.vuepress/config/sidebar/en.ts @@ -68,7 +68,8 @@ export const sidebarEn: SidebarConfig = { '/en/config/transports/quic.md', '/en/config/transports/tcp.md', '/en/config/transports/websocket.md', - '/en/config/transports/httpupgrade.md' + '/en/config/transports/httpupgrade.md', + '/en/config/transports/splithttp.md' ], }, ], diff --git a/docs/.vuepress/config/sidebar/zh.ts b/docs/.vuepress/config/sidebar/zh.ts index 6ffa2c112..87d1bf69a 100755 --- a/docs/.vuepress/config/sidebar/zh.ts +++ b/docs/.vuepress/config/sidebar/zh.ts @@ -69,7 +69,8 @@ export const sidebarZh: SidebarConfig = { '/config/transports/quic.md', '/config/transports/tcp.md', '/config/transports/websocket.md', - '/config/transports/httpupgrade.md' + '/config/transports/httpupgrade.md', + '/config/transports/splithttp.md' ], }, ], diff --git a/docs/config/transport.md b/docs/config/transport.md index e2e3aec57..0c42c5737 100644 --- a/docs/config/transport.md +++ b/docs/config/transport.md @@ -63,6 +63,10 @@ 针对 HTTPUpragde 连接的配置。 +> `splithttpSettings`: [SplitHttpObject](./transports/splithttp.md) + +针对 SplitHTTP 连接的配置。 + > `dsSettings`: [DomainSocketObject](./transports/domainsocket.md) 针对 Domain Socket 连接的配置。 diff --git a/docs/config/transports/splithttp.md b/docs/config/transports/splithttp.md new file mode 100644 index 000000000..e333d76c4 --- /dev/null +++ b/docs/config/transports/splithttp.md @@ -0,0 +1,56 @@ +# SplitHTTP + +::: tip +Help me I don't know chinese. +::: + +Uses HTTP chunked-transfer encoding for download, and multiple HTTP requests for upload. + +Can be deployed on CDNs that do not support WebSocket, but there are still some requirements: + +- The CDN must support HTTP chunked transfer encoding in a streaming fashion, + no response buffering. The transport will send the `X-Accel-Buffering: no` + response header, but only some CDNs respect this. + + If the connection hangs, most likely this part does not work. + +- The CDN must disable caching, or caching should include the query string in cache key. + +Download performance should be similar to WebSocket, but upload is limited. + +Like WebSocket transport, SplitHTTP parses the `X-Forwarded-For` header for logging. + +## SplitHttpObject + +The `SplitHttpObject` corresponds to the `splithttpSettings` section under transport configurations. + +```json +{ + "path": "/", + "host": "xray.com", + "headers": { + "key": "value" + } +} +``` + +> `path`: string + +HTTP path used by the connection. Defaults to `"/"`. + +> `host`: string + +HTTP Host sent by the connection. Empty by default. If this value is empty on the server, the host header sent by clients will not be validated. + +If the `Host` header has been defined on the server in any way, the server will validate if the `Host` header matches. + +The current priority of the `Host` header sent by clients: `host` > `headers` > `address` + +> `headers`: map \{string: string\} + +Customized HTTP headers defined in key-value pairs. Defaults to empty. + +## Known issues + +ALPN negotiation is currently not correctly implemented. HTTPS connections +always assume HTTP/2 prior knowledge. diff --git a/docs/en/config/transport.md b/docs/en/config/transport.md index 11c2fc8a6..a92462224 100644 --- a/docs/en/config/transport.md +++ b/docs/en/config/transport.md @@ -27,6 +27,7 @@ The `TransportObject` corresponds to the `transport` property in the config root "dsSettings": {}, "grpcSettings": {}, "httpupgradeSettings": {} + "splithttpSettings": {} } } ``` @@ -63,6 +64,10 @@ Configures HTTPUpgrade connections. Configures Domain Socket connections. +> `splithttpSettings`: [SplitHttpObject](./transports/splithttp.md) + +Configures SplitHTTP connections. + ## StreamSettingsObject `StreamSettingsObject` corresponds to the `streamSettings` property in the inbound or outbound config. Each inbound or outbound can be configured with different transports and can use `streamSettings` to specify local configs. @@ -80,6 +85,7 @@ Configures Domain Socket connections. "dsSettings": {}, "grpcSettings": {}, "httpupgradeSettings": {}, + "splithttpSettings": {}, "sockopt": { "mark": 0, "tcpMaxSeg": 1440, @@ -157,6 +163,10 @@ Configures the current Domain Socket connection. Valid only when Domain Socket i Configures the current HTTPUpragde connection. Valid only when HTTPUpgrade is used. Same schema as global. +> `splithttpSettings`: [SplitHttpObject](./transports/splithttp.md) + +Configures SplitHTTP connections. Valid only when SplitHTTP is used. Same schema as global. + > `sockopt`: [SockoptObject](#sockoptobject) Configures transparent proxies. diff --git a/docs/en/config/transports/splithttp.md b/docs/en/config/transports/splithttp.md new file mode 100644 index 000000000..e4ecee761 --- /dev/null +++ b/docs/en/config/transports/splithttp.md @@ -0,0 +1,52 @@ +# SplitHTTP + +Uses HTTP chunked-transfer encoding for download, and multiple HTTP requests for upload. + +Can be deployed on CDNs that do not support WebSocket, but there are still some requirements: + +- The CDN must support HTTP chunked transfer encoding in a streaming fashion, + no response buffering. The transport will send the `X-Accel-Buffering: no` + response header, but only some CDNs respect this. + + If the connection hangs, most likely this part does not work. + +- The CDN must disable caching, or caching should include the query string in cache key. + +Download performance should be similar to WebSocket, but upload is limited. + +Like WebSocket transport, SplitHTTP parses the `X-Forwarded-For` header for logging. + +## SplitHttpObject + +The `SplitHttpObject` corresponds to the `splithttpSettings` section under transport configurations. + +```json +{ + "path": "/", + "host": "xray.com", + "headers": { + "key": "value" + } +} +``` + +> `path`: string + +HTTP path used by the connection. Defaults to `"/"`. + +> `host`: string + +HTTP Host sent by the connection. Empty by default. If this value is empty on the server, the host header sent by clients will not be validated. + +If the `Host` header has been defined on the server in any way, the server will validate if the `Host` header matches. + +The current priority of the `Host` header sent by clients: `host` > `headers` > `address` + +> `headers`: map \{string: string\} + +Customized HTTP headers defined in key-value pairs. Defaults to empty. + +## Known issues + +ALPN negotiation is currently not correctly implemented. HTTPS connections +always assume HTTP/2 prior knowledge.