connectip

README

Proxying IP over HTTP

connect-ip-go is an implementation of the CONNECT-IP protocol RFC 9484, allowing the proxying of IP packets in HTTP/3.

It is based on quic-go, and provides both a client and a proxy implementation.

At this point, it supports the following use cases:

• Remote Access VPN, see Section 8.1 of RFC 9484
• Site-to-Site VPN, see Section 8.2 of RFC 9484

Release Policy

connect-ip-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 AssignedAddress
• type CloseError
  • func (e *CloseError) Error() string
  • func (e *CloseError) Is(target error) bool
• type Conn
  • func Dial(ctx context.Context, conn *http3.ClientConn, template *uritemplate.Template) (*Conn, *http.Response, error)
  • func NewProxiedConn(str Http3Stream) *Conn
  • func (c *Conn) AdvertiseRoute(ctx context.Context, routes []IPRoute) error
  • func (c *Conn) AssignAddresses(ctx context.Context, prefixes []netip.Prefix) error
  • func (c *Conn) Close() error
  • func (c *Conn) LocalPrefixes(ctx context.Context) ([]netip.Prefix, error)
  • func (c *Conn) ReadPacket() (b []byte, err error)
  • func (c *Conn) ReadPacketBuffer() (*PacketBuffer, error)
  • func (c *Conn) Routes(ctx context.Context) ([]IPRoute, error)
  • func (c *Conn) TryReadPacket() (b []byte, err error)
  • func (c *Conn) TryReadPacketBuffer() (*PacketBuffer, error)
  • func (c *Conn) WritePacket(b []byte) (icmp []byte, err error)
  • func (c *Conn) WritePacketBuffer(buf []byte, offset, length int) (icmp []byte, err error)
  • func (c *Conn) WritePacketBufferOwned(buf []byte, offset, length int, owner PacketPayloadOwner) (icmp []byte, err error)
• type Http3Stream
• type IPRoute
  • func (r IPRoute) Prefixes() []netip.Prefix
• type PacketBuffer
  • func (b *PacketBuffer) Release()
• type PacketPayloadOwner
• type Proxy
  • func (s *Proxy) Proxy(w http.ResponseWriter, _ *Request) (*Conn, 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
• type RequestedAddress

Types

type AssignedAddress

type AssignedAddress struct {
	RequestID uint64
	IPPrefix  netip.Prefix
}

AssignedAddress represents an Assigned Address within an ADDRESS_ASSIGN capsule

type CloseError

type CloseError struct {
	Remote bool
}

func (*CloseError) Error

func (e *CloseError) Error() string

func (*CloseError) Is

func (e *CloseError) Is(target error) bool

type Conn

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

Conn is a connection that proxies IP packets over HTTP/3.

func Dial

func Dial(ctx context.Context, conn *http3.ClientConn, template *uritemplate.Template) (*Conn, *http.Response, error)

Dial dials a proxied connection to a target server.

func NewProxiedConn

func NewProxiedConn(str Http3Stream) *Conn

func (*Conn) AdvertiseRoute

func (c *Conn) AdvertiseRoute(ctx context.Context, routes []IPRoute) error

AdvertiseRoute informs the peer about available routes. This function can be called multiple times, but only the routes from the most recent call will be active. Previous route advertisements are overwritten by each new call to this function.

func (*Conn) AssignAddresses

func (c *Conn) AssignAddresses(ctx context.Context, prefixes []netip.Prefix) error

AssignAddresses assigned address prefixes to the peer. This function can be called multiple times, but only the addresses from the most recent call will be active. Previous address assignments are overwritten by each new call to this function.

func (*Conn) Close

func (c *Conn) Close() error

func (*Conn) LocalPrefixes

func (c *Conn) LocalPrefixes(ctx context.Context) ([]netip.Prefix, error)

LocalPrefixes returns the prefixes that the peer currently assigned. Note that at any point during the connection, the peer can change the assignment. It is therefore recommended to call this function in a loop.

func (*Conn) ReadPacket

func (c *Conn) ReadPacket() (b []byte, err error)

func (*Conn) ReadPacketBuffer

func (c *Conn) ReadPacketBuffer() (*PacketBuffer, error)

func (*Conn) Routes

func (c *Conn) Routes(ctx context.Context) ([]IPRoute, error)

Routes returns the routes that the peer currently advertised. Note that at any point during the connection, the peer can change the advertised routes. It is therefore recommended to call this function in a loop.

func (*Conn) TryReadPacket

func (c *Conn) TryReadPacket() (b []byte, err error)

TryReadPacket returns one already-queued IP packet without waiting for a future QUIC DATAGRAM. It is intended for bounded opportunistic draining. ReadPacket retains its blocking behavior for existing callers.

func (*Conn) TryReadPacketBuffer

func (c *Conn) TryReadPacketBuffer() (*PacketBuffer, error)

func (*Conn) WritePacket

func (c *Conn) WritePacket(b []byte) (icmp []byte, err error)

WritePacket writes an IP packet to the stream. If sending the packet fails, it might return an ICMP packet. It is the caller's responsibility to send the ICMP packet to the sender.

func (*Conn) WritePacketBuffer

func (c *Conn) WritePacketBuffer(buf []byte, offset, length int) (icmp []byte, err error)

WritePacketBuffer sends buf[offset:offset+length]. When offset provides the one-byte CONNECT-IP Context ID headroom, it prepends in place and avoids the CONNECT-IP allocation/copy. quic-go copies into its own datagram frame before returning, so callers may immediately reuse buf after this call.

func (*Conn) WritePacketBufferOwned

func (c *Conn) WritePacketBufferOwned(buf []byte, offset, length int, owner PacketPayloadOwner) (icmp []byte, err error)

WritePacketBufferOwned sends an IP packet while transferring ownership of buf to the asynchronous HTTP/3 / QUIC path. The owner is released by this method unless the owned lower layer accepts the buffer. Callers must not release owner after this method returns.

type Http3Stream

type Http3Stream = http3Stream

type IPRoute

type IPRoute struct {
	StartIP netip.Addr
	EndIP   netip.Addr
	// IPProtocol is the Internet Protocol Number for traffic that can be sent to this range.
	// If the value is 0, all protocols are allowed.
	IPProtocol uint8
}

IPRoute represents an IP Address Range

func (IPRoute) Prefixes

func (r IPRoute) Prefixes() []netip.Prefix

Prefixes returns the prefixes that this IP address range covers. Note that depending on the start and end addresses, this conversion can result in a large number of prefixes.

type PacketBuffer

type PacketBuffer quic.DatagramBuffer

PacketBuffer is a named pointer view over quic.DatagramBuffer. The buffer-aware receive path converts the pointer without allocating another handle object. Release and its exactly-once semantics are owned by the QUIC DatagramBuffer.

func (*PacketBuffer) Release

func (b *PacketBuffer) Release()

type PacketPayloadOwner

type PacketPayloadOwner interface{ Release() }

PacketPayloadOwner owns the caller's packet backing. WritePacketBufferOwned releases it on every non-transferred path and transfers it to the HTTP/3 / QUIC send queue only after that queue accepts the frame.

type Proxy

type Proxy struct{}

func (*Proxy) Proxy

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

type Request

type Request struct{}

Request is the parsed CONNECT-IP request returned from ParseRequest. It currently doesn't have any fields, since masque-go doesn't support IP flow forwarding.

func ParseRequest

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

ParseRequest parses a CONNECT-IP request. The template is the URI template that clients will use to configure this 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

type RequestedAddress

type RequestedAddress struct {
	RequestID uint64
	IPPrefix  netip.Prefix
}

RequestedAddress represents an Requested Address within an ADDRESS_REQUEST capsule