split the qlog package into a logging and a qlog package

logging/interface.go

@@ -0,0 +1,37 @@
+// Package logging defines a logging interface for quic-go.
+// This package should not be considered stable
+package logging
+
+import (
+	"net"
+	"time"
+
+	"github.com/lucas-clemente/quic-go/internal/congestion"
+	"github.com/lucas-clemente/quic-go/internal/protocol"
+	"github.com/lucas-clemente/quic-go/internal/wire"
+)
+
+// A Tracer records events.
+type Tracer interface {
+	Export() error
+	StartedConnection(local, remote net.Addr, version protocol.VersionNumber, srcConnID, destConnID protocol.ConnectionID)
+	ClosedConnection(CloseReason)
+	SentTransportParameters(*wire.TransportParameters)
+	ReceivedTransportParameters(*wire.TransportParameters)
+	SentPacket(hdr *wire.ExtendedHeader, packetSize protocol.ByteCount, ack *wire.AckFrame, frames []wire.Frame)
+	ReceivedVersionNegotiationPacket(*wire.Header)
+	ReceivedRetry(*wire.Header)
+	ReceivedPacket(hdr *wire.ExtendedHeader, packetSize protocol.ByteCount, frames []wire.Frame)
+	ReceivedStatelessReset(token *[16]byte)
+	BufferedPacket(PacketType)
+	DroppedPacket(PacketType, protocol.ByteCount, PacketDropReason)
+	UpdatedMetrics(rttStats *congestion.RTTStats, cwnd protocol.ByteCount, bytesInFLight protocol.ByteCount, packetsInFlight int)
+	LostPacket(protocol.EncryptionLevel, protocol.PacketNumber, PacketLossReason)
+	UpdatedPTOCount(value uint32)
+	UpdatedKeyFromTLS(protocol.EncryptionLevel, protocol.Perspective)
+	UpdatedKey(generation protocol.KeyPhase, remote bool)
+	DroppedEncryptionLevel(protocol.EncryptionLevel)
+	SetLossTimer(TimerType, protocol.EncryptionLevel, time.Time)
+	LossTimerExpired(TimerType, protocol.EncryptionLevel)
+	LossTimerCanceled()
+}

logging/logging_sutie_test.go

@@ -0,0 +1,13 @@
+package logging
+
+import (
+	"testing"
+
+	. "github.com/onsi/ginkgo"
+	. "github.com/onsi/gomega"
+)
+
+func TestLoggingt(t *testing.T) {
+	RegisterFailHandler(Fail)
+	RunSpecs(t, "Logging Suite")
+}

logging/packet_header.go

@@ -0,0 +1,43 @@
+package logging
+
+import (
+	"github.com/lucas-clemente/quic-go/internal/protocol"
+	"github.com/lucas-clemente/quic-go/internal/wire"
+)
+
+// PacketTypeFromHeader determines the packet type from a *wire.Header.
+func PacketTypeFromHeader(hdr *wire.Header) PacketType {
+	if !hdr.IsLongHeader {
+		return PacketType1RTT
+	}
+	if hdr.Version == 0 {
+		return PacketTypeVersionNegotiation
+	}
+	switch hdr.Type {
+	case protocol.PacketTypeInitial:
+		return PacketTypeInitial
+	case protocol.PacketTypeHandshake:
+		return PacketTypeHandshake
+	case protocol.PacketType0RTT:
+		return PacketType0RTT
+	case protocol.PacketTypeRetry:
+		return PacketTypeRetry
+	default:
+		return PacketTypeNotDetermined
+	}
+}
+
+// PacketHeader is a QUIC packet header.
+type PacketHeader struct {
+	PacketType PacketType
+
+	PacketNumber  protocol.PacketNumber
+	PayloadLength protocol.ByteCount
+	// Size of the QUIC packet (QUIC header + payload).
+	// See https://github.com/quiclog/internet-drafts/issues/40.
+	PacketSize protocol.ByteCount
+
+	Version          protocol.VersionNumber
+	SrcConnectionID  protocol.ConnectionID
+	DestConnectionID protocol.ConnectionID
+}

logging/packet_header_test.go

@@ -0,0 +1,60 @@
+package logging
+
+import (
+	"github.com/lucas-clemente/quic-go/internal/protocol"
+	"github.com/lucas-clemente/quic-go/internal/wire"
+
+	. "github.com/onsi/ginkgo"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Packet Header", func() {
+	Context("determining the packet type from the header", func() {
+		It("recognizes Initial packets", func() {
+			Expect(PacketTypeFromHeader(&wire.Header{
+				IsLongHeader: true,
+				Type:         protocol.PacketTypeInitial,
+				Version:      protocol.VersionTLS,
+			})).To(Equal(PacketTypeInitial))
+		})
+
+		It("recognizes Handshake packets", func() {
+			Expect(PacketTypeFromHeader(&wire.Header{
+				IsLongHeader: true,
+				Type:         protocol.PacketTypeHandshake,
+				Version:      protocol.VersionTLS,
+			})).To(Equal(PacketTypeHandshake))
+		})
+
+		It("recognizes Retry packets", func() {
+			Expect(PacketTypeFromHeader(&wire.Header{
+				IsLongHeader: true,
+				Type:         protocol.PacketTypeRetry,
+				Version:      protocol.VersionTLS,
+			})).To(Equal(PacketTypeRetry))
+		})
+
+		It("recognizes 0-RTT packets", func() {
+			Expect(PacketTypeFromHeader(&wire.Header{
+				IsLongHeader: true,
+				Type:         protocol.PacketType0RTT,
+				Version:      protocol.VersionTLS,
+			})).To(Equal(PacketType0RTT))
+		})
+
+		It("recognizes Version Negotiation packets", func() {
+			Expect(PacketTypeFromHeader(&wire.Header{IsLongHeader: true})).To(Equal(PacketTypeVersionNegotiation))
+		})
+
+		It("recognizes 1-RTT packets", func() {
+			Expect(PacketTypeFromHeader(&wire.Header{})).To(Equal(PacketType1RTT))
+		})
+
+		It("handles unrecognized packet types", func() {
+			Expect(PacketTypeFromHeader(&wire.Header{
+				IsLongHeader: true,
+				Version:      protocol.VersionTLS,
+			})).To(Equal(PacketTypeNotDetermined))
+		})
+	})
+})

logging/types.go

@@ -0,0 +1,170 @@
+package logging
+
+import (
+	"github.com/lucas-clemente/quic-go/internal/protocol"
+)
+
+// PacketType is the packet type of a QUIC packet
+type PacketType protocol.PacketType
+
+const (
+	// PacketTypeInitial is the packet type of an Initial packet
+	PacketTypeInitial PacketType = iota
+	// PacketTypeHandshake is the packet type of a Handshake packet
+	PacketTypeHandshake
+	// PacketTypeRetry is the packet type of a Retry packet
+	PacketTypeRetry
+	// PacketType0RTT is the packet type of a 0-RTT packet
+	PacketType0RTT
+	// PacketTypeVersionNegotiation is the packet type of a Version Negotiation packet
+	PacketTypeVersionNegotiation
+	// PacketType1RTT is a 1-RTT packet
+	PacketType1RTT
+	// PacketTypeStatelessReset is a stateless reset
+	PacketTypeStatelessReset
+	// PacketTypeNotDetermined is the packet type when it could not be determined
+	PacketTypeNotDetermined
+)
+
+func (t PacketType) String() string {
+	switch t {
+	case PacketTypeInitial:
+		return "initial"
+	case PacketTypeHandshake:
+		return "handshake"
+	case PacketTypeRetry:
+		return "retry"
+	case PacketType0RTT:
+		return "0RTT"
+	case PacketTypeVersionNegotiation:
+		return "version_negotiation"
+	case PacketTypeStatelessReset:
+		return "stateless_reset"
+	case PacketType1RTT:
+		return "1RTT"
+	case PacketTypeNotDetermined:
+		return ""
+	default:
+		panic("unknown packet type")
+	}
+}
+
+type PacketLossReason uint8
+
+const (
+	// PacketLossReorderingThreshold: when a packet is deemed lost due to reordering threshold
+	PacketLossReorderingThreshold PacketLossReason = iota
+	// PacketLossTimeThreshold: when a packet is deemed lost due to time threshold
+	PacketLossTimeThreshold
+)
+
+func (r PacketLossReason) String() string {
+	switch r {
+	case PacketLossReorderingThreshold:
+		return "reordering_threshold"
+	case PacketLossTimeThreshold:
+		return "time_threshold"
+	default:
+		panic("unknown loss reason")
+	}
+}
+
+type PacketDropReason uint8
+
+const (
+	// PacketDropKeyUnavailable is used when a packet is dropped because keys are unavailable
+	PacketDropKeyUnavailable PacketDropReason = iota
+	// PacketDropUnknownConnectionID is used when a packet is dropped because the connection ID is unknown
+	PacketDropUnknownConnectionID
+	// PacketDropHeaderParseError is used when a packet is dropped because header parsing failed
+	PacketDropHeaderParseError
+	// PacketDropPayloadDecryptError is used when a packet is dropped because decrypting the payload failed
+	PacketDropPayloadDecryptError
+	// PacketDropProtocolViolation is used when a packet is dropped due to a protocol violation
+	PacketDropProtocolViolation
+	// PacketDropDOSPrevention is used when a packet is dropped to mitigate a DoS attack
+	PacketDropDOSPrevention
+	// PacketDropUnsupportedVersion is used when a packet is dropped because the version is not supported
+	PacketDropUnsupportedVersion
+	// PacketDropUnexpectedPacket is used when an unexpected packet is received
+	PacketDropUnexpectedPacket
+	// PacketDropUnexpectedSourceConnectionID is used when a packet with an unexpected source connection ID is received
+	PacketDropUnexpectedSourceConnectionID
+	// PacketDropUnexpectedVersion is used when a packet with an unexpected version is received
+	PacketDropUnexpectedVersion
+	// PacketDropDuplicate is used when a duplicate packet is received
+	PacketDropDuplicate
+)
+
+func (r PacketDropReason) String() string {
+	switch r {
+	case PacketDropKeyUnavailable:
+		return "key_unavailable"
+	case PacketDropUnknownConnectionID:
+		return "unknown_connection_id"
+	case PacketDropHeaderParseError:
+		return "header_parse_error"
+	case PacketDropPayloadDecryptError:
+		return "payload_decrypt_error"
+	case PacketDropProtocolViolation:
+		return "protocol_violation"
+	case PacketDropDOSPrevention:
+		return "dos_prevention"
+	case PacketDropUnsupportedVersion:
+		return "unsupported_version"
+	case PacketDropUnexpectedPacket:
+		return "unexpected_packet"
+	case PacketDropUnexpectedSourceConnectionID:
+		return "unexpected_source_connection_id"
+	case PacketDropUnexpectedVersion:
+		return "unexpected_version"
+	case PacketDropDuplicate:
+		return "duplicate"
+	default:
+		panic("unknown packet drop reason")
+	}
+}
+
+// TimerType is the type of the loss detection timer
+type TimerType uint8
+
+const (
+	// TimerTypeACK is the timer type for the early retransmit timer
+	TimerTypeACK TimerType = iota
+	// TimerTypePTO is the timer type for the PTO retransmit timer
+	TimerTypePTO
+)
+
+func (t TimerType) String() string {
+	switch t {
+	case TimerTypeACK:
+		return "ack"
+	case TimerTypePTO:
+		return "pto"
+	default:
+		panic("unknown timer type")
+	}
+}
+
+// CloseReason is the reason why a session is closed
+type CloseReason uint8
+
+const (
+	// CloseReasonHandshakeTimeout is used when the session is closed due to a handshake timeout
+	// This reason is not defined in the qlog draft, but very useful for debugging.
+	CloseReasonHandshakeTimeout CloseReason = iota
+	// CloseReasonIdleTimeout is used when the session is closed due to an idle timeout
+	// This reason is not defined in the qlog draft, but very useful for debugging.
+	CloseReasonIdleTimeout
+)
+
+func (r CloseReason) String() string {
+	switch r {
+	case CloseReasonHandshakeTimeout:
+		return "handshake_timeout"
+	case CloseReasonIdleTimeout:
+		return "idle_timeout"
+	default:
+		panic("unknown close reason")
+	}
+}

logging/types_test.go

@@ -0,0 +1,42 @@
+package logging
+
+import (
+	. "github.com/onsi/ginkgo"
+	. "github.com/onsi/gomega"
+)
+
+var _ = Describe("Types", func() {
+	It("has a string representation for the packet type", func() {
+		Expect(PacketTypeInitial.String()).To(Equal("initial"))
+		Expect(PacketTypeHandshake.String()).To(Equal("handshake"))
+		Expect(PacketType0RTT.String()).To(Equal("0RTT"))
+		Expect(PacketType1RTT.String()).To(Equal("1RTT"))
+		Expect(PacketTypeStatelessReset.String()).To(Equal("stateless_reset"))
+		Expect(PacketTypeRetry.String()).To(Equal("retry"))
+		Expect(PacketTypeVersionNegotiation.String()).To(Equal("version_negotiation"))
+		Expect(PacketTypeNotDetermined.String()).To(BeEmpty())
+	})
+
+	It("has a string representation for the packet drop reason", func() {
+		Expect(PacketDropKeyUnavailable.String()).To(Equal("key_unavailable"))
+		Expect(PacketDropUnknownConnectionID.String()).To(Equal("unknown_connection_id"))
+		Expect(PacketDropHeaderParseError.String()).To(Equal("header_parse_error"))
+		Expect(PacketDropPayloadDecryptError.String()).To(Equal("payload_decrypt_error"))
+		Expect(PacketDropProtocolViolation.String()).To(Equal("protocol_violation"))
+		Expect(PacketDropDOSPrevention.String()).To(Equal("dos_prevention"))
+		Expect(PacketDropUnsupportedVersion.String()).To(Equal("unsupported_version"))
+		Expect(PacketDropUnexpectedPacket.String()).To(Equal("unexpected_packet"))
+		Expect(PacketDropUnexpectedSourceConnectionID.String()).To(Equal("unexpected_source_connection_id"))
+		Expect(PacketDropUnexpectedVersion.String()).To(Equal("unexpected_version"))
+	})
+
+	It("has a string representation for the timer type", func() {
+		Expect(TimerTypeACK.String()).To(Equal("ack"))
+		Expect(TimerTypePTO.String()).To(Equal("pto"))
+	})
+
+	It("has a string representation for the close reason", func() {
+		Expect(CloseReasonHandshakeTimeout.String()).To(Equal("handshake_timeout"))
+		Expect(CloseReasonIdleTimeout.String()).To(Equal("idle_timeout"))
+	})
+})