masque-go

The Proxy type implements an RFC 9298 CONNECT-UDP proxy. It provides methods to proxy UDP traffic over HTTP/3 streams.

There are two primary ways to use it:

1. Proxy(w http.ResponseWriter, r *ProxyRequest): This is the high-level method. It resolves the target address from r.Target, dials a new UDP connection, and then handles the proxying. It automatically manages the lifecycle of the UDP connection.
2. ProxyConnectedSocket(w http.ResponseWriter, r *ProxyRequest, conn *net.UDPConn): This provides more control. You provide an already established *net.UDPConn. This method is responsible for closing the connection before returning.

Important Constraints:

• When implementing the handler, you MUST NOT call w.WriteHeader() on the http.ResponseWriter yourself if you want the Proxy methods to manage the response status and headers (like Proxy-Status and Capsule-Protocol). The Proxy methods handle writing the status code and headers.
• The Proxy methods will set the Capsule-Protocol header and write http.StatusOK automatically.

```go
// Example conceptual usage within an HTTP/3 handler
func (s *Server) HandleProxyRequest(w http.ResponseWriter, r *http.Request) {
    // r would be cast or treated as a *ProxyRequest
    proxyReq := r.(*ProxyRequest)
    
    // Use the Proxy instance to handle the connection
    err := s.proxy.Proxy(w, proxyReq)
    if err != nil {
        // Handle error
    }
}
```埋

Use ParseProxyRequest to parse incoming HTTP CONNECT requests intended for a UDP proxy. This function validates the request method, protocol, and host against a provided URI template.

If parsing fails, it returns a *ProxyRequestParseError. It is recommended to reject the request using the HTTPStatus field provided in the error to ensure the client receives the correct HTTP response code (e.g., 405 Method Not Allowed or 400 Bad Request).

Successful parsing returns a *ProxyRequest containing the Target (the destination host:port) and the original Host.

import (
	"net/http"
	"github.com/yosida95/uritemplate/v3"
	"github.com/your-project/masque"
)

// Assuming 'template' is a pre-configured *uritemplate.Template
proxyReq, err := masque.ParseProxyRequest(httpRequest, template)
if err != nil {
	if parseErr, ok := err.(*masque.ProxyRequestParseError); ok {
		// Use parseErr.HTTPStatus to respond to the client
		// e.g., http.Error(w, parseErr.Error(), parseErr.HTTPStatus)
	}
}
// Use proxyReq.Target to establish the UDP connection

The ClientConn type represents a single connection to a proxy server. You can use it to establish multiple proxied connections (CONNECT-UDP) over that single proxy connection using the Dial method.

To use Dial, you must provide a *Request object containing the target destination. The method returns a *Conn (the proxied connection), an *http.Response (the server's response to the CONNECT request), and an error.

Requirements for successful Dialing:

• The Request must have a non-nil URL.
• The Request must have a host specified.
• The proxy server must have enabled Extended CONNECT and Datagrams in its settings.

If the server responds with a status code outside the 200-299 range, Dial will return an error along with the response.

// Assuming c is an initialized *masque.ClientConn and req is a valid *masque.Request
conn, resp, err := c.Dial(req)
if err != nil {
	// Handle error
}
// Use conn for proxied communication
// Use resp to inspect proxy-specific headers if needed

The ProxyConnectedSocket method allows you to proxy traffic using a UDP connection that you have already established or configured.

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

Behavior:

• Requires the http.ResponseWriter to implement the http3.HTTPStreamer interface to access the underlying QUIC stream.
• Sets the Capsule-Protocol header on the response.
• Writes http.StatusOK to the response.
• Spawns two goroutines to handle bidirectional data flow:
  • proxyConnSend: Reads datagrams from the QUIC stream and writes them to the UDP connection. It expects datagrams to potentially contain a contextID (via quicvarint), but currently only proxies the raw UDP payload if the contextID is 0.
  • proxyConnReceive: Reads from the UDP connection and sends datagrams back through the QUIC stream.
• Note: This method closes the provided conn before returning.
• Note: It discards any capsules sent on the request stream.

// Assuming 'conn' is an existing *net.UDPConn
err := proxy.ProxyConnectedSocket(w, proxyRequest, conn)