package quic

import "golang.org/x/net/internal/quic"

Package quic is an experimental, incomplete implementation of the QUIC protocol. This package is a work in progress, and is not ready for use at this time.

This package implements (or will implement) RFC 9000, RFC 9001, and RFC 9002.

Index ¶

• type ApplicationError
• func (e *ApplicationError) Error() string
• func (e *ApplicationError) Is(err error) bool
• type Config
• type Conn
• func (c *Conn) Abort(err error)
• func (c *Conn) AcceptStream(ctx context.Context) (*Stream, error)
• func (c *Conn) Close() error
• func (c *Conn) NewSendOnlyStream(ctx context.Context) (*Stream, error)
• func (c *Conn) NewStream(ctx context.Context) (*Stream, error)
• func (c *Conn) String() string
• func (c *Conn) Wait(ctx context.Context) error
• type Listener
• func Listen(network, address string, config *Config) (*Listener, error)
• func (l *Listener) Accept(ctx context.Context) (*Conn, error)
• func (l *Listener) Close(ctx context.Context) error
• func (l *Listener) Dial(ctx context.Context, network, address string) (*Conn, error)
• func (l *Listener) LocalAddr() netip.AddrPort
• type Stream
• func (s *Stream) Close() error
• func (s *Stream) CloseContext(ctx context.Context) error
• func (s *Stream) CloseRead()
• func (s *Stream) CloseWrite()
• func (s *Stream) IsReadOnly() bool
• func (s *Stream) IsWriteOnly() bool
• func (s *Stream) Read(b []byte) (n int, err error)
• func (s *Stream) ReadContext(ctx context.Context, b []byte) (n int, err error)
• func (s *Stream) Reset(code uint64)
• func (s *Stream) Write(b []byte) (n int, err error)
• func (s *Stream) WriteContext(ctx context.Context, b []byte) (n int, err error)
• type StreamErrorCode
• func (e StreamErrorCode) Error() string

Types ¶

type ApplicationError ¶

type ApplicationError struct {
	Code   uint64
	Reason string
}

An ApplicationError is an application protocol error code (RFC 9000, Section 20.2). Application protocol errors may be sent when terminating a stream or connection.

func (*ApplicationError) Error ¶

func (e *ApplicationError) Error() string

func (*ApplicationError) Is ¶

func (e *ApplicationError) Is(err error) bool

Is reports a match if err is an *ApplicationError with a matching Code.

type Config ¶

type Config struct {
	// TLSConfig is the endpoint's TLS configuration.
	// It must be non-nil and include at least one certificate or else set GetCertificate.
	TLSConfig *tls.Config

	// MaxBidiRemoteStreams limits the number of simultaneous bidirectional streams
	// a peer may open.
	// If zero, the default value of 100 is used.
	// If negative, the limit is zero.
	MaxBidiRemoteStreams int64

	// MaxUniRemoteStreams limits the number of simultaneous unidirectional streams
	// a peer may open.
	// If zero, the default value of 100 is used.
	// If negative, the limit is zero.
	MaxUniRemoteStreams int64

	// MaxStreamReadBufferSize is the maximum amount of data sent by the peer that a
	// stream will buffer for reading.
	// If zero, the default value of 1MiB is used.
	// If negative, the limit is zero.
	MaxStreamReadBufferSize int64

	// MaxStreamWriteBufferSize is the maximum amount of data a stream will buffer for
	// sending to the peer.
	// If zero, the default value of 1MiB is used.
	// If negative, the limit is zero.
	MaxStreamWriteBufferSize int64

	// MaxConnReadBufferSize is the maximum amount of data sent by the peer that a
	// connection will buffer for reading, across all streams.
	// If zero, the default value of 1MiB is used.
	// If negative, the limit is zero.
	MaxConnReadBufferSize int64
}

A Config structure configures a QUIC endpoint. A Config must not be modified after it has been passed to a QUIC function. A Config may be reused; the quic package will also not modify it.

type Conn ¶

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

A Conn is a QUIC connection.

Multiple goroutines may invoke methods on a Conn simultaneously.

func (*Conn) Abort ¶

func (c *Conn) Abort(err error)

Abort closes the connection and returns immediately.

If err is nil, Abort sends a transport error of NO_ERROR to the peer. If err is an ApplicationError, Abort sends its error code and text. Otherwise, Abort sends a transport error of APPLICATION_ERROR with the error's text.

func (*Conn) AcceptStream ¶

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

AcceptStream waits for and returns the next stream created by the peer.

func (*Conn) Close ¶

func (c *Conn) Close() error

Close closes the connection.

Close is equivalent to:

conn.Abort(nil)
err := conn.Wait(context.Background())

func (*Conn) NewSendOnlyStream ¶

func (c *Conn) NewSendOnlyStream(ctx context.Context) (*Stream, error)

NewSendOnlyStream creates a unidirectional, send-only stream.

If the peer's maximum stream limit for the connection has been reached, NewSendOnlyStream blocks until the limit is increased or the context expires.

func (*Conn) NewStream ¶

func (c *Conn) NewStream(ctx context.Context) (*Stream, error)

NewStream creates a stream.

If the peer's maximum stream limit for the connection has been reached, NewStream blocks until the limit is increased or the context expires.

func (*Conn) String ¶

func (c *Conn) String() string

func (*Conn) Wait ¶

func (c *Conn) Wait(ctx context.Context) error

Wait waits for the peer to close the connection.

If the connection is closed locally and the peer does not close its end of the connection, Wait will return with a non-nil error after the drain period expires.

If the peer closes the connection with a NO_ERROR transport error, Wait returns nil. If the peer closes the connection with an application error, Wait returns an ApplicationError containing the peer's error code and reason. If the peer closes the connection with any other status, Wait returns a non-nil error.

type Listener ¶

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

A Listener listens for QUIC traffic on a network address. It can accept inbound connections or create outbound ones.

Multiple goroutines may invoke methods on a Listener simultaneously.

func Listen ¶

func Listen(network, address string, config *Config) (*Listener, error)

Listen listens on a local network address. The configuration config must be non-nil.

func (*Listener) Accept ¶

func (l *Listener) Accept(ctx context.Context) (*Conn, error)

Accept waits for and returns the next connection to the listener.

func (*Listener) Close ¶

func (l *Listener) Close(ctx context.Context) error

Close closes the listener. Any blocked operations on the Listener or associated Conns and Stream will be unblocked and return errors.

Close aborts every open connection. Data in stream read and write buffers is discarded. It waits for the peers of any open connection to acknowledge the connection has been closed.

func (*Listener) Dial ¶

func (l *Listener) Dial(ctx context.Context, network, address string) (*Conn, error)

Dial creates and returns a connection to a network address.

func (*Listener) LocalAddr ¶

func (l *Listener) LocalAddr() netip.AddrPort

LocalAddr returns the local network address.

type Stream ¶

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

func (*Stream) Close ¶

func (s *Stream) Close() error

Close closes the stream. See CloseContext for more details.

func (*Stream) CloseContext ¶

func (s *Stream) CloseContext(ctx context.Context) error

CloseContext closes the stream. Any blocked stream operations will be unblocked and return errors.

CloseContext flushes any data in the stream write buffer and waits for the peer to acknowledge receipt of the data. If the stream has been reset, it waits for the peer to acknowledge the reset. If the context expires before the peer receives the stream's data, CloseContext discards the buffer and returns the context error.

func (*Stream) CloseRead ¶

func (s *Stream) CloseRead()

CloseRead aborts reads on the stream. Any blocked reads will be unblocked and return errors.

CloseRead notifies the peer that the stream has been closed for reading. It does not wait for the peer to acknowledge the closure. Use CloseContext to wait for the peer's acknowledgement.

func (*Stream) CloseWrite ¶

func (s *Stream) CloseWrite()

CloseWrite aborts writes on the stream. Any blocked writes will be unblocked and return errors.

CloseWrite sends any data in the stream write buffer to the peer. It does not wait for the peer to acknowledge receipt of the data. Use CloseContext to wait for the peer's acknowledgement.

func (*Stream) IsReadOnly ¶

func (s *Stream) IsReadOnly() bool

IsReadOnly reports whether the stream is read-only (a unidirectional stream created by the peer).

func (*Stream) IsWriteOnly ¶

func (s *Stream) IsWriteOnly() bool

IsWriteOnly reports whether the stream is write-only (a unidirectional stream created locally).

func (*Stream) Read ¶

func (s *Stream) Read(b []byte) (n int, err error)

Read reads data from the stream. See ReadContext for more details.

func (*Stream) ReadContext ¶

func (s *Stream) ReadContext(ctx context.Context, b []byte) (n int, err error)

ReadContext reads data from the stream.

ReadContext returns as soon as at least one byte of data is available.

If the peer closes the stream cleanly, ReadContext returns io.EOF after returning all data sent by the peer. If the peer aborts reads on the stream, ReadContext returns an error wrapping StreamResetCode.

func (*Stream) Reset ¶

func (s *Stream) Reset(code uint64)

Reset aborts writes on the stream and notifies the peer that the stream was terminated abruptly. Any blocked writes will be unblocked and return errors.

Reset sends the application protocol error code, which must be less than 2^62, to the peer. It does not wait for the peer to acknowledge receipt of the error. Use CloseContext to wait for the peer's acknowledgement.

Reset does not affect reads. Use CloseRead to abort reads on the stream.

func (*Stream) Write ¶

func (s *Stream) Write(b []byte) (n int, err error)

Write writes data to the stream. See WriteContext for more details.

func (*Stream) WriteContext ¶

func (s *Stream) WriteContext(ctx context.Context, b []byte) (n int, err error)

WriteContext writes data to the stream.

WriteContext writes data to the stream write buffer. Buffered data is only sent when the buffer is sufficiently full. Call the Flush method to ensure buffered data is sent.

TODO: Implement Flush.

type StreamErrorCode ¶

type StreamErrorCode uint64

A StreamErrorCode is an application protocol error code (RFC 9000, Section 20.2) indicating whay a stream is being closed.

func (StreamErrorCode) Error ¶

func (e StreamErrorCode) Error() string

Source Files ¶

ack_delay.go acks.go atomic_bits.go config.go congestion_reno.go conn.go conn_close.go conn_flow.go conn_id.go conn_loss.go conn_recv.go conn_send.go conn_streams.go crypto_stream.go dgram.go doc.go errors.go frame_debug.go gate.go listener.go log.go loss.go math.go pacer.go packet.go packet_number.go packet_parser.go packet_protection.go packet_writer.go ping.go pipe.go queue.go quic.go rangeset.go rtt.go sent_packet.go sent_packet_list.go sent_val.go stream.go stream_limits.go tls.go transport_params.go wire.go