masque

README

masque-go

masque-go is an implementation of the CONNECT-UDP protocol RFC 9298, based on quic-go. It provides both a client and a proxy implementation.

Detailed documentation can be found on quic-go.net.

Release Policy

masque-go always aims to support the latest two Go releases.

Contributing

We are always happy to welcome new contributors! If you have any questions, please feel free to reach out by opening an issue or leaving a comment.

Documentation

Index

• type Client
  • func (c *Client) Close() error
  • func (c *Client) Dial(ctx context.Context, proxyTemplate *uritemplate.Template, raddr *net.UDPAddr) (net.PacketConn, *http.Response, error)
  • func (c *Client) DialAddr(ctx context.Context, proxyTemplate *uritemplate.Template, target string) (net.PacketConn, *http.Response, error)
• type Proxy
  • func (s *Proxy) Close() error
  • func (s *Proxy) Proxy(w http.ResponseWriter, r *Request) error
  • func (s *Proxy) ProxyConnectedSocket(w http.ResponseWriter, _ *Request, conn *net.UDPConn) error
• type Request
  • func ParseRequest(r *http.Request, template *uritemplate.Template) (*Request, error)
• type RequestParseError
  • func (e *RequestParseError) Error() string
  • func (e *RequestParseError) Unwrap() error

Types

type Client

type Client struct {
	// TLSClientConfig is the TLS client config used when dialing the QUIC connection to the proxy.
	// It must set the "h3" ALPN.
	TLSClientConfig *tls.Config

	// QUICConfig is the QUIC config used when dialing the QUIC connection.
	QUICConfig *quic.Config
	// contains filtered or unexported fields
}

A Client establishes proxied connections to remote hosts, using a UDP proxy. Multiple flows can be proxied via the same connection to the proxy.

func (*Client) Close

func (c *Client) Close() error

Close closes the connection to the proxy. This immediately shuts down all proxied flows.

func (*Client) Dial

func (c *Client) Dial(ctx context.Context, proxyTemplate *uritemplate.Template, raddr *net.UDPAddr) (net.PacketConn, *http.Response, error)

Dial dials a proxied connection to a target server.

func (*Client) DialAddr

func (c *Client) DialAddr(ctx context.Context, proxyTemplate *uritemplate.Template, target string) (net.PacketConn, *http.Response, error)

DialAddr dials a proxied connection to a target server. The target address is sent to the proxy, and the DNS resolution is left to the proxy. The target must be given as a host:port.

type Proxy

type Proxy struct {
	// contains filtered or unexported fields
}

A Proxy is an RFC 9298 CONNECT-UDP proxy.

func (*Proxy) Close

func (s *Proxy) Close() error

Close closes the proxy, immeidately terminating all proxied flows.

func (*Proxy) Proxy

func (s *Proxy) Proxy(w http.ResponseWriter, r *Request) error

Proxy proxies a request on a newly created connected UDP socket. For more control over the UDP socket, use ProxyConnectedSocket. Applications may add custom header fields to the response header, but MUST NOT call WriteHeader on the http.ResponseWriter.

func (*Proxy) ProxyConnectedSocket

func (s *Proxy) ProxyConnectedSocket(w http.ResponseWriter, _ *Request, conn *net.UDPConn) error

ProxyConnectedSocket proxies a request on a connected UDP socket. Applications may add custom header fields to the response header, but MUST NOT call WriteHeader on the http.ResponseWriter. It closes the connection before returning.

type Request

type Request struct {
	Target string
}

Request is the parsed CONNECT-UDP request returned from ParseRequest. Target is the target server that the client requests to connect to. It can either be DNS name:port or an IP:port.

func ParseRequest

func ParseRequest(r *http.Request, template *uritemplate.Template) (*Request, error)

ParseRequest parses a CONNECT-UDP request. The template is the URI template that clients will use to configure this UDP proxy.

type RequestParseError

type RequestParseError struct {
	HTTPStatus int
	Err        error
}

RequestParseError is returned from ParseRequest if parsing the CONNECT-UDP request fails. It is recommended that the request is rejected with the corresponding HTTP status code.

func (*RequestParseError) Error

func (e *RequestParseError) Error() string

func (*RequestParseError) Unwrap

func (e *RequestParseError) Unwrap() error