interface.go 9.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221
  1. package quic
  2. import (
  3. "context"
  4. "io"
  5. "net"
  6. "time"
  7. "github.com/lucas-clemente/quic-go/internal/handshake"
  8. "github.com/lucas-clemente/quic-go/internal/protocol"
  9. )
  10. // The StreamID is the ID of a QUIC stream.
  11. type StreamID = protocol.StreamID
  12. // A VersionNumber is a QUIC version number.
  13. type VersionNumber = protocol.VersionNumber
  14. const (
  15. // VersionGQUIC39 is gQUIC version 39.
  16. VersionGQUIC39 = protocol.Version39
  17. // VersionGQUIC43 is gQUIC version 43.
  18. VersionGQUIC43 = protocol.Version43
  19. // VersionGQUIC43 is gQUIC version 44.
  20. VersionGQUIC44 = protocol.Version44
  21. )
  22. // A Cookie can be used to verify the ownership of the client address.
  23. type Cookie = handshake.Cookie
  24. // ConnectionState records basic details about the QUIC connection.
  25. type ConnectionState = handshake.ConnectionState
  26. // An ErrorCode is an application-defined error code.
  27. type ErrorCode = protocol.ApplicationErrorCode
  28. // Stream is the interface implemented by QUIC streams
  29. type Stream interface {
  30. // StreamID returns the stream ID.
  31. StreamID() StreamID
  32. // Read reads data from the stream.
  33. // Read can be made to time out and return a net.Error with Timeout() == true
  34. // after a fixed time limit; see SetDeadline and SetReadDeadline.
  35. // If the stream was canceled by the peer, the error implements the StreamError
  36. // interface, and Canceled() == true.
  37. io.Reader
  38. // Write writes data to the stream.
  39. // Write can be made to time out and return a net.Error with Timeout() == true
  40. // after a fixed time limit; see SetDeadline and SetWriteDeadline.
  41. // If the stream was canceled by the peer, the error implements the StreamError
  42. // interface, and Canceled() == true.
  43. io.Writer
  44. // Close closes the write-direction of the stream.
  45. // Future calls to Write are not permitted after calling Close.
  46. // It must not be called concurrently with Write.
  47. // It must not be called after calling CancelWrite.
  48. io.Closer
  49. // CancelWrite aborts sending on this stream.
  50. // It must not be called after Close.
  51. // Data already written, but not yet delivered to the peer is not guaranteed to be delivered reliably.
  52. // Write will unblock immediately, and future calls to Write will fail.
  53. CancelWrite(ErrorCode) error
  54. // CancelRead aborts receiving on this stream.
  55. // It will ask the peer to stop transmitting stream data.
  56. // Read will unblock immediately, and future Read calls will fail.
  57. CancelRead(ErrorCode) error
  58. // The context is canceled as soon as the write-side of the stream is closed.
  59. // This happens when Close() is called, or when the stream is reset (either locally or remotely).
  60. // Warning: This API should not be considered stable and might change soon.
  61. Context() context.Context
  62. // SetReadDeadline sets the deadline for future Read calls and
  63. // any currently-blocked Read call.
  64. // A zero value for t means Read will not time out.
  65. SetReadDeadline(t time.Time) error
  66. // SetWriteDeadline sets the deadline for future Write calls
  67. // and any currently-blocked Write call.
  68. // Even if write times out, it may return n > 0, indicating that
  69. // some of the data was successfully written.
  70. // A zero value for t means Write will not time out.
  71. SetWriteDeadline(t time.Time) error
  72. // SetDeadline sets the read and write deadlines associated
  73. // with the connection. It is equivalent to calling both
  74. // SetReadDeadline and SetWriteDeadline.
  75. SetDeadline(t time.Time) error
  76. }
  77. // A ReceiveStream is a unidirectional Receive Stream.
  78. type ReceiveStream interface {
  79. // see Stream.StreamID
  80. StreamID() StreamID
  81. // see Stream.Read
  82. io.Reader
  83. // see Stream.CancelRead
  84. CancelRead(ErrorCode) error
  85. // see Stream.SetReadDealine
  86. SetReadDeadline(t time.Time) error
  87. }
  88. // A SendStream is a unidirectional Send Stream.
  89. type SendStream interface {
  90. // see Stream.StreamID
  91. StreamID() StreamID
  92. // see Stream.Write
  93. io.Writer
  94. // see Stream.Close
  95. io.Closer
  96. // see Stream.CancelWrite
  97. CancelWrite(ErrorCode) error
  98. // see Stream.Context
  99. Context() context.Context
  100. // see Stream.SetWriteDeadline
  101. SetWriteDeadline(t time.Time) error
  102. }
  103. // StreamError is returned by Read and Write when the peer cancels the stream.
  104. type StreamError interface {
  105. error
  106. Canceled() bool
  107. ErrorCode() ErrorCode
  108. }
  109. // A Session is a QUIC connection between two peers.
  110. type Session interface {
  111. // AcceptStream returns the next stream opened by the peer, blocking until one is available.
  112. AcceptStream() (Stream, error)
  113. // AcceptUniStream returns the next unidirectional stream opened by the peer, blocking until one is available.
  114. AcceptUniStream() (ReceiveStream, error)
  115. // OpenStream opens a new bidirectional QUIC stream.
  116. // It returns a special error when the peer's concurrent stream limit is reached.
  117. // There is no signaling to the peer about new streams:
  118. // The peer can only accept the stream after data has been sent on the stream.
  119. // TODO(#1152): Enable testing for the special error
  120. OpenStream() (Stream, error)
  121. // OpenStreamSync opens a new bidirectional QUIC stream.
  122. // It blocks until the peer's concurrent stream limit allows a new stream to be opened.
  123. OpenStreamSync() (Stream, error)
  124. // OpenUniStream opens a new outgoing unidirectional QUIC stream.
  125. // It returns a special error when the peer's concurrent stream limit is reached.
  126. // TODO(#1152): Enable testing for the special error
  127. OpenUniStream() (SendStream, error)
  128. // OpenUniStreamSync opens a new outgoing unidirectional QUIC stream.
  129. // It blocks until the peer's concurrent stream limit allows a new stream to be opened.
  130. OpenUniStreamSync() (SendStream, error)
  131. // LocalAddr returns the local address.
  132. LocalAddr() net.Addr
  133. // RemoteAddr returns the address of the peer.
  134. RemoteAddr() net.Addr
  135. // Close the connection.
  136. io.Closer
  137. // Close the connection with an error.
  138. // The error must not be nil.
  139. CloseWithError(ErrorCode, error) error
  140. // The context is cancelled when the session is closed.
  141. // Warning: This API should not be considered stable and might change soon.
  142. Context() context.Context
  143. // ConnectionState returns basic details about the QUIC connection.
  144. // Warning: This API should not be considered stable and might change soon.
  145. ConnectionState() ConnectionState
  146. }
  147. // Config contains all configuration data needed for a QUIC server or client.
  148. type Config struct {
  149. // The QUIC versions that can be negotiated.
  150. // If not set, it uses all versions available.
  151. // Warning: This API should not be considered stable and will change soon.
  152. Versions []VersionNumber
  153. // Ask the server to omit the connection ID sent in the Public Header.
  154. // This saves 8 bytes in the Public Header in every packet. However, if the IP address of the server changes, the connection cannot be migrated.
  155. // Currently only valid for the client.
  156. RequestConnectionIDOmission bool
  157. // The length of the connection ID in bytes. Only valid for IETF QUIC.
  158. // It can be 0, or any value between 4 and 18.
  159. // If not set, the interpretation depends on where the Config is used:
  160. // If used for dialing an address, a 0 byte connection ID will be used.
  161. // If used for a server, or dialing on a packet conn, a 4 byte connection ID will be used.
  162. // When dialing on a packet conn, the ConnectionIDLength value must be the same for every Dial call.
  163. ConnectionIDLength int
  164. // HandshakeTimeout is the maximum duration that the cryptographic handshake may take.
  165. // If the timeout is exceeded, the connection is closed.
  166. // If this value is zero, the timeout is set to 10 seconds.
  167. HandshakeTimeout time.Duration
  168. // IdleTimeout is the maximum duration that may pass without any incoming network activity.
  169. // This value only applies after the handshake has completed.
  170. // If the timeout is exceeded, the connection is closed.
  171. // If this value is zero, the timeout is set to 30 seconds.
  172. IdleTimeout time.Duration
  173. // AcceptCookie determines if a Cookie is accepted.
  174. // It is called with cookie = nil if the client didn't send an Cookie.
  175. // If not set, it verifies that the address matches, and that the Cookie was issued within the last 24 hours.
  176. // This option is only valid for the server.
  177. AcceptCookie func(clientAddr net.Addr, cookie *Cookie) bool
  178. // MaxReceiveStreamFlowControlWindow is the maximum stream-level flow control window for receiving data.
  179. // If this value is zero, it will default to 1 MB for the server and 6 MB for the client.
  180. MaxReceiveStreamFlowControlWindow uint64
  181. // MaxReceiveConnectionFlowControlWindow is the connection-level flow control window for receiving data.
  182. // If this value is zero, it will default to 1.5 MB for the server and 15 MB for the client.
  183. MaxReceiveConnectionFlowControlWindow uint64
  184. // MaxIncomingStreams is the maximum number of concurrent bidirectional streams that a peer is allowed to open.
  185. // If not set, it will default to 100.
  186. // If set to a negative value, it doesn't allow any bidirectional streams.
  187. // Values larger than 65535 (math.MaxUint16) are invalid.
  188. MaxIncomingStreams int
  189. // MaxIncomingUniStreams is the maximum number of concurrent unidirectional streams that a peer is allowed to open.
  190. // This value doesn't have any effect in Google QUIC.
  191. // If not set, it will default to 100.
  192. // If set to a negative value, it doesn't allow any unidirectional streams.
  193. // Values larger than 65535 (math.MaxUint16) are invalid.
  194. MaxIncomingUniStreams int
  195. // KeepAlive defines whether this peer will periodically send PING frames to keep the connection alive.
  196. KeepAlive bool
  197. }
  198. // A Listener for incoming QUIC connections
  199. type Listener interface {
  200. // Close the server, sending CONNECTION_CLOSE frames to each peer.
  201. Close() error
  202. // Addr returns the local network addr that the server is listening on.
  203. Addr() net.Addr
  204. // Accept returns new sessions. It should be called in a loop.
  205. Accept() (Session, error)
  206. }