client

Documentation

Overview

Package client provides a WebTransport client with reconnection support.

Pool provides a pool of WebTransport connections for server-to-server communication. Connections are lazily created and reused.

Index

• type Client
  • func New(url string, opts ...Option) *Client
  • func (c *Client) AcceptStream(ctx context.Context) (*webtransport.Stream, error)
  • func (c *Client) Close() error
  • func (c *Client) Dial(ctx context.Context) error
  • func (c *Client) DialWithReconnect(ctx context.Context) error
  • func (c *Client) OpenStream(ctx context.Context) (*webtransport.Stream, error)
  • func (c *Client) ReceiveDatagram(ctx context.Context) ([]byte, error)
  • func (c *Client) SendDatagram(data []byte) error
  • func (c *Client) Session() *webtransport.Session
• type Option
  • func OnDisconnect(fn func(error)) Option
  • func OnReconnect(fn func()) Option
  • func WithCodec(cc codec.Codec) Option
  • func WithHeaders(h http.Header) Option
  • func WithInsecureSkipVerify() Option
  • func WithReconnect(min, max time.Duration) Option
• type Pool
  • func NewPool(url string, maxSize int, opts ...Option) *Pool
  • func (p *Pool) Close() error
  • func (p *Pool) Get(ctx context.Context) (*Client, error)
  • func (p *Pool) Size() int
• type SessionResumption
  • func (s SessionResumption) String() string
• type ZeroRTTClient
  • func NewZeroRTT(url string, cacheSize int, opts ...Option) *ZeroRTTClient
  • func (c *ZeroRTTClient) DialEarly(ctx context.Context) error
  • func (c *ZeroRTTClient) Handle0RTTRejection(ctx context.Context) error
  • func (c *ZeroRTTClient) Has0RTTTicket() bool
  • func (c *ZeroRTTClient) WaitHandshake(ctx context.Context) error

Types

type Client

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

Client is a WebTransport client with auto-reconnection.

func New

func New(url string, opts ...Option) *Client

New creates a new WebTransport client.

func (*Client) AcceptStream

func (c *Client) AcceptStream(ctx context.Context) (*webtransport.Stream, error)

AcceptStream accepts an incoming stream from the server.

func (*Client) Close

func (c *Client) Close() error

Close closes the connection.

func (*Client) Dial

func (c *Client) Dial(ctx context.Context) error

Dial connects to the WebTransport server.

func (*Client) DialWithReconnect

func (c *Client) DialWithReconnect(ctx context.Context) error

DialWithReconnect connects and automatically reconnects on disconnection. Blocks until the context is cancelled.

func (*Client) OpenStream

func (c *Client) OpenStream(ctx context.Context) (*webtransport.Stream, error)

OpenStream opens a bidirectional stream.

func (*Client) ReceiveDatagram

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

ReceiveDatagram receives a datagram.

func (*Client) SendDatagram

func (c *Client) SendDatagram(data []byte) error

SendDatagram sends an unreliable datagram.

func (*Client) Session

func (c *Client) Session() *webtransport.Session

Session returns the underlying session.

type Option

type Option func(*Client)

Option configures the Client.

func OnDisconnect

func OnDisconnect(fn func(error)) Option

OnDisconnect sets a callback for disconnections.

func OnReconnect

func OnReconnect(fn func()) Option

OnReconnect sets a callback for successful reconnections.

func WithCodec

func WithCodec(cc codec.Codec) Option

WithCodec sets the message codec (default: JSON).

func WithHeaders

func WithHeaders(h http.Header) Option

WithHeaders sets custom headers for the WebTransport handshake.

func WithInsecureSkipVerify

func WithInsecureSkipVerify() Option

WithInsecureSkipVerify disables TLS certificate verification (for development).

func WithReconnect

func WithReconnect(min, max time.Duration) Option

WithReconnect enables auto-reconnection with exponential backoff.

type Pool

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

Pool manages a pool of WebTransport clients to the same server. Useful for server-to-server communication where you need multiple concurrent sessions to the same backend.

func NewPool

func NewPool(url string, maxSize int, opts ...Option) *Pool

NewPool creates a connection pool.

func (*Pool) Close

func (p *Pool) Close() error

Close closes all connections in the pool.

func (*Pool) Get

func (p *Pool) Get(ctx context.Context) (*Client, error)

Get returns a connected client from the pool. Creates a new connection if the pool isn't full yet. Uses round-robin selection among existing connections.

func (*Pool) Size

func (p *Pool) Size() int

Size returns the current number of connections in the pool.

type SessionResumption

type SessionResumption int

SessionResumption describes the type of session establishment.

const (
	// FullHandshake means a complete TLS 1.3 handshake was performed.
	FullHandshake SessionResumption = iota
	// Resumed means TLS session resumption was used (1-RTT).
	Resumed
	// ZeroRTT means 0-RTT early data was sent.
	ZeroRTT
)

func (SessionResumption) String

func (s SessionResumption) String() string

type ZeroRTTClient

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

ZeroRTTClient extends Client with 0-RTT session resumption support. On the first connection, a normal handshake occurs and a TLS session ticket is cached. Subsequent connections attempt 0-RTT, sending data immediately without waiting for the handshake to complete.

0-RTT is safe for idempotent operations only (reads, subscriptions). For writes/mutations, wait for HandshakeComplete before sending.

func NewZeroRTT

func NewZeroRTT(url string, cacheSize int, opts ...Option) *ZeroRTTClient

NewZeroRTT creates a client with 0-RTT support. The cacheSize parameter controls how many session tickets to cache (default: 100).

func (*ZeroRTTClient) DialEarly

func (c *ZeroRTTClient) DialEarly(ctx context.Context) error

DialEarly connects using 0-RTT if a session ticket is available. On first connection, performs a normal handshake and caches the ticket. On subsequent connections, sends data immediately (0-RTT).

IMPORTANT: 0-RTT data can be replayed by attackers. Only send idempotent data before HandshakeComplete. Call WaitHandshake() before performing any mutations.

func (*ZeroRTTClient) Handle0RTTRejection

func (c *ZeroRTTClient) Handle0RTTRejection(ctx context.Context) error

Handle0RTTRejection should be called when 0-RTT is rejected by the server. It reconnects using a normal handshake.

func (*ZeroRTTClient) Has0RTTTicket

func (c *ZeroRTTClient) Has0RTTTicket() bool

Has0RTTTicket returns true if a session ticket is cached for the server, meaning the next connection will attempt 0-RTT.

func (*ZeroRTTClient) WaitHandshake

func (c *ZeroRTTClient) WaitHandshake(ctx context.Context) error

WaitHandshake blocks until the TLS handshake is fully complete. Call this before sending any non-idempotent data on a 0-RTT connection.