quic

package
v1.18.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 20, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package quic implements the TON QUIC transport: RFC 7250 raw-public-key (Ed25519/ADNL) mutual authentication over QUIC v1, with the quic.message/quic.query/quic.answer framing used by the reference C++ node.

It is built on github.com/xssnick/quic-go-ton — a fork of quic-go bundled with an RFC 7250-patched crypto/tls — so the whole stack stays pure Go.

Index

Constants

View Source 
const ALPN = "ton"

ALPN is the application protocol negotiated for TON QUIC.

View Source 
const DefaultMaxObjectSize = 4 << 20

DefaultMaxObjectSize caps how many bytes a single stream object may carry. The value follows the C++ node's initial local bidi stream receive window.

Variables

View Source 
var ErrNoQueryHandler = errors.New("quic: peer query handler is not set")

ErrNoQueryHandler is returned when a peer receives quic.query but has no handler.

View Source 
var ErrPeerClosed = errors.New("quic: peer is closed")

ErrPeerClosed is returned when a peer has no live QUIC connection.

Functions

This section is empty.

Types

type Answer 

type Answer struct {
	Data []byte `tl:"bytes"`
}

Answer is a TL quic.answer object.

type Client 

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

Client is an outbound TON QUIC connection to a single peer.

func Dial 

func Dial(ctx context.Context, addr string, localKey ed25519.PrivateKey, expectedPeer ed25519.PublicKey) (*Client, error)

Dial establishes a TON QUIC connection to addr ("host:port"), authenticating with localKey and requiring the server to present expectedPeer's raw public key. The context bounds the handshake.

func (*Client) Close 

func (c *Client) Close() error

Close tears down the connection.

func (*Client) PeerID 

func (c *Client) PeerID() []byte

PeerID returns a copy of the authenticated ADNL id of the remote endpoint.

func (*Client) PeerKey 

func (c *Client) PeerKey() ed25519.PublicKey

PeerKey returns a copy of the authenticated Ed25519 public key of the remote endpoint.

func (*Client) Query 

func (c *Client) Query(ctx context.Context, payload []byte, maxAnswer int64) ([]byte, error)

Query sends a quic.query and returns the quic.answer payload. maxAnswer, when positive, overrides the default answer size cap.

func (*Client) SendMessage 

func (c *Client) SendMessage(ctx context.Context, payload []byte) error

SendMessage sends a fire-and-forget quic.message.

type ConnectionHandler 

type ConnectionHandler func(peer *Peer) error

ConnectionHandler is called once when a Gateway sees a new (local, peer) path.

type Gateway 

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

Gateway manages TON QUIC peers keyed by (local ADNL id, peer ADNL id).

func NewGateway 

func NewGateway(keys ...ed25519.PrivateKey) (*Gateway, error)

NewGateway builds a Gateway hosting the given local Ed25519 identities.

func (*Gateway) Close 

func (g *Gateway) Close() error

Close closes the Gateway server and all active peers.

func (*Gateway) Dial 

func (g *Gateway) Dial(ctx context.Context, local, peer ed25519.PublicKey, addr string) (*Peer, error)

Dial establishes or reuses a peer path from local to peer.

func (*Gateway) DialDefault 

func (g *Gateway) DialDefault(ctx context.Context, peer ed25519.PublicKey, addr string) (*Peer, error)

DialDefault establishes or reuses a peer path from the default local identity.

func (*Gateway) ID 

func (g *Gateway) ID() []byte

ID returns a copy of the default local ADNL id.

func (*Gateway) Identities 

func (g *Gateway) Identities() []ed25519.PublicKey

Identities returns the local Ed25519 public keys hosted by the Gateway.

func (*Gateway) Peer 

func (g *Gateway) Peer(local, peer ed25519.PublicKey) *Peer

Peer returns the currently known peer for a path, if any.

func (*Gateway) PublicKey 

func (g *Gateway) PublicKey() ed25519.PublicKey

PublicKey returns a copy of the default local Ed25519 public key.

func (*Gateway) Serve 

func (g *Gateway) Serve(pc net.PacketConn) error

Serve listens on pc and accepts inbound TON QUIC connections.

func (*Gateway) SetConnectionHandler 

func (g *Gateway) SetConnectionHandler(handler ConnectionHandler)

SetConnectionHandler sets the handler called for newly discovered paths.

type Handler 

type Handler struct {
	// OnQuery handles a quic.query and returns the answer payload. Required.
	OnQuery func(ctx context.Context, from ed25519.PublicKey, payload []byte) ([]byte, error)
	// OnMessage handles a fire-and-forget quic.message. Optional.
	OnMessage func(ctx context.Context, from ed25519.PublicKey, payload []byte)
	// contains filtered or unexported fields
}

Handler processes inbound stream objects for a Server.

type Identity 

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

Identity is a local ADNL identity backed by an Ed25519 private key.

func NewIdentity 

func NewIdentity(key ed25519.PrivateKey) (Identity, error)

NewIdentity builds an Identity from an Ed25519 private key.

func (Identity) ID 

func (i Identity) ID() []byte

ID returns a copy of the ADNL short id of this identity.

func (Identity) PublicKey 

func (i Identity) PublicKey() ed25519.PublicKey

PublicKey returns the identity's Ed25519 public key.

type Message 

type Message struct {
	Data []byte `tl:"bytes"`
}

Message is a TL quic.message object.

type Peer 

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

Peer is a managed TON QUIC path between one local id and one peer id.

func (*Peer) Close 

func (p *Peer) Close() error

Close closes all live connections for this path.

func (*Peer) LocalID 

func (p *Peer) LocalID() []byte

LocalID returns a copy of the local ADNL id for this path.

func (*Peer) PeerID 

func (p *Peer) PeerID() []byte

PeerID returns a copy of the remote ADNL id for this path.

func (*Peer) PeerKey 

func (p *Peer) PeerKey() ed25519.PublicKey

PeerKey returns a copy of the remote Ed25519 public key for this path.

func (*Peer) Query 

func (p *Peer) Query(ctx context.Context, payload []byte, maxAnswer int64) ([]byte, error)

Query sends a quic.query on the path and returns the answer payload.

func (*Peer) RemoteAddr 

func (p *Peer) RemoteAddr() string

RemoteAddr returns the last known remote QUIC address.

func (*Peer) SendMessage 

func (p *Peer) SendMessage(ctx context.Context, payload []byte) error

SendMessage sends a fire-and-forget quic.message on the path.

func (*Peer) SetDisconnectHandler 

func (p *Peer) SetDisconnectHandler(handler PeerDisconnectHandler)

SetDisconnectHandler sets the handler called when the path is closed.

func (*Peer) SetMessageHandler 

func (p *Peer) SetMessageHandler(handler PeerMessageHandler)

SetMessageHandler sets the handler for inbound quic.message streams.

func (*Peer) SetQueryHandler 

func (p *Peer) SetQueryHandler(handler PeerQueryHandler)

SetQueryHandler sets the handler for inbound quic.query streams.

type PeerDisconnectHandler 

type PeerDisconnectHandler func(peer *Peer)

PeerDisconnectHandler is called after the path loses all live connections or is closed.

type PeerMessageHandler 

type PeerMessageHandler func(ctx context.Context, payload []byte)

PeerMessageHandler handles inbound quic.message streams for a Peer.

type PeerQueryHandler 

type PeerQueryHandler func(ctx context.Context, payload []byte) ([]byte, error)

PeerQueryHandler handles inbound quic.query streams for a Peer.

type Query 

type Query struct {
	Data []byte `tl:"bytes"`
}

Query is a TL quic.query object.

type Server 

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

Server accepts TON QUIC connections on a net.PacketConn and dispatches inbound query/message streams to a Handler.

func NewServer 

func NewServer(handler Handler, keys ...ed25519.PrivateKey) (*Server, error)

NewServer builds a Server hosting the given Ed25519 identities. The first key is the default identity used when a client sends no SNI; additional keys are reachable by their ADNL-id SNI.

func (*Server) Close 

func (s *Server) Close() error

Close stops the server and releases its socket.

func (*Server) Serve 

func (s *Server) Serve(pc net.PacketConn) error

Serve listens on pc and blocks serving connections until Close is called or a fatal accept error occurs.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.