SagerNet / SagerNet/sing-box

[Feature request] MASQUE support, modeled similarly to WireGuard endpoint

Open
#4,000 1 comment 24 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
Go
Stars
38.2k
Forks
4.6k
Avg merge
19d 15h
Merged PRs (30d)
1

Description

I would like to request MASQUE client support in sing-box.

My suggestion is to consider CONNECT-IP first, and to model it closer to the existing WireGuard endpoint design, instead of treating it as a regular outbound proxy protocol.

Why I think it fits the WireGuard model better

From an implementation and routing perspective, MASQUE CONNECT-IP looks much closer to an IP tunnel than to a normal stream proxy:

  • it needs local tunnel addresses
  • it carries full IP packets instead of only independent TCP streams
  • TCP and UDP can share the same L3 tunnel path
  • DNS and route handling need to avoid tunnel loops

Because of that, it seems conceptually closer to WireGuard than to SOCKS / HTTP / VMess / VLESS / Trojan style outbounds.

In other words, if sing-box ever supports MASQUE CONNECT-IP, an endpoint-style design may be more natural than a traditional outbound-style design.

Reference

There is already a practical implementation in mihomo:

That implementation is useful as a reference because it treats MASQUE as an IP tunnel over HTTP/3 + QUIC, which is the main reason I think the WireGuard endpoint model is a better comparison point than a normal proxy outbound.

Scope suggestion

A reasonable initial scope could be:

  • client-side support only
  • prioritize CONNECT-IP
  • model it similarly to WireGuard endpoint behavior
  • support TCP and UDP through the IP tunnel path

Possible later work:

  • CONNECT-UDP
  • server-side support
  • vendor-specific compatibility options only when needed
Rough configuration idea
{
  "type": "masque",
  "tag": "masque-ep",
  "server": "example.com",
  "server_port": 443,
  "address": ["172.16.0.2/32", "fd00::2/128"],
  "url": "https://example.com/masque",
  "tls": {
    "enabled": true,
    "server_name": "example.com"
  }
}

This is only a rough example. The main point is not the exact schema, but the idea that MASQUE CONNECT-IP may fit better as a WireGuard-like endpoint.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing mihomo's adapter/outbound/masque.go and transport/masque/masque.go to understand the referenced CONNECT-IP implementation and its HTTP/3 and QUIC handling. Then compare that model with sing-box's existing WireGuard endpoint design. Done means a client-side CONNECT-IP implementation supporting TCP and UDP through an IP-tunnel-style endpoint, with routing and DNS behavior that avoids tunnel loops.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
networking
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.