quic/core/web_transport_interface.h

// Copyright (c) 2021 The Chromium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// This header contains interfaces that abstract away different backing
// protocols for WebTransport.

#ifndef QUICHE_QUIC_CORE_WEB_TRANSPORT_INTERFACE_H_
#define QUICHE_QUIC_CORE_WEB_TRANSPORT_INTERFACE_H_

#include <cstddef>
#include <memory>

#include "absl/base/attributes.h"
#include "absl/strings/string_view.h"
#include "quic/core/quic_datagram_queue.h"
#include "quic/core/quic_types.h"
#include "quic/platform/api/quic_export.h"
#include "common/platform/api/quiche_mem_slice.h"
#include "spdy/core/spdy_header_block.h"

namespace quic {

// Visitor that gets notified about events related to a WebTransport stream.
class QUIC_EXPORT_PRIVATE WebTransportStreamVisitor {
 public:
  virtual ~WebTransportStreamVisitor() {}

  // Called whenever the stream has readable data available.
  virtual void OnCanRead() = 0;
  // Called whenever the stream is not write-blocked and can accept new data.
  virtual void OnCanWrite() = 0;

  // Called when RESET_STREAM is received for the stream.
  virtual void OnResetStreamReceived(WebTransportStreamError error) = 0;
  // Called when STOP_SENDING is received for the stream.
  virtual void OnStopSendingReceived(WebTransportStreamError error) = 0;
  // Called when the write side of the stream is closed and all of the data sent
  // has been acknowledged ("Data Recvd" state of RFC 9000).
  virtual void OnWriteSideInDataRecvdState() = 0;
};

// A stream (either bidirectional or unidirectional) that is contained within a
// WebTransport session.
class QUIC_EXPORT_PRIVATE WebTransportStream {
 public:
  struct QUIC_EXPORT_PRIVATE ReadResult {
    // Number of bytes actually read.
    size_t bytes_read;
    // Whether the FIN has been received; if true, no further data will arrive
    // on the stream, and the stream object can be soon potentially garbage
    // collected.
    bool fin;
  };

  virtual ~WebTransportStream() {}

  // Reads at most |buffer_size| bytes into |buffer|.
  ABSL_MUST_USE_RESULT virtual ReadResult Read(char* buffer,
                                               size_t buffer_size) = 0;
  // Reads all available data and appends it to the end of |output|.
  ABSL_MUST_USE_RESULT virtual ReadResult Read(std::string* output) = 0;
  // Writes |data| into the stream.  Returns true on success.
  ABSL_MUST_USE_RESULT virtual bool Write(absl::string_view data) = 0;
  // Sends the FIN on the stream.  Returns true on success.
  ABSL_MUST_USE_RESULT virtual bool SendFin() = 0;

  // Indicates whether it is possible to write into stream right now.
  virtual bool CanWrite() const = 0;
  // Indicates the number of bytes that can be read from the stream.
  virtual size_t ReadableBytes() const = 0;

  // An ID that is unique within the session.  Those are not exposed to the user
  // via the web API, but can be used internally for bookkeeping and
  // diagnostics.
  virtual QuicStreamId GetStreamId() const = 0;

  // Resets the stream with the specified error code.
  virtual void ResetWithUserCode(WebTransportStreamError error) = 0;
  virtual void ResetDueToInternalError() = 0;
  virtual void SendStopSending(WebTransportStreamError error) = 0;
  // Called when the owning object has been garbage-collected.
  virtual void MaybeResetDueToStreamObjectGone() = 0;

  virtual WebTransportStreamVisitor* visitor() = 0;
  virtual void SetVisitor(
      std::unique_ptr<WebTransportStreamVisitor> visitor) = 0;
};

// Visitor that gets notified about events related to a WebTransport session.
class QUIC_EXPORT_PRIVATE WebTransportVisitor {
 public:
  virtual ~WebTransportVisitor() {}

  // Notifies the visitor when the session is ready to exchange application
  // data.
  virtual void OnSessionReady(const spdy::SpdyHeaderBlock& headers) = 0;

  // Notifies the visitor when the session has been closed.
  virtual void OnSessionClosed(WebTransportSessionError error_code,
                               const std::string& error_message) = 0;

  // Notifies the visitor when a new stream has been received.  The stream in
  // question can be retrieved using AcceptIncomingBidirectionalStream() or
  // AcceptIncomingUnidirectionalStream().
  virtual void OnIncomingBidirectionalStreamAvailable() = 0;
  virtual void OnIncomingUnidirectionalStreamAvailable() = 0;

  // Notifies the visitor when a new datagram has been received.
  virtual void OnDatagramReceived(absl::string_view datagram) = 0;

  // Notifies the visitor that a new outgoing stream can now be created.
  virtual void OnCanCreateNewOutgoingBidirectionalStream() = 0;
  virtual void OnCanCreateNewOutgoingUnidirectionalStream() = 0;
};

// An abstract interface for a WebTransport session.
class QUIC_EXPORT_PRIVATE WebTransportSession {
 public:
  virtual ~WebTransportSession() {}

  // Closes the WebTransport session in question with the specified |error_code|
  // and |error_message|.
  virtual void CloseSession(WebTransportSessionError error_code,
                            absl::string_view error_message) = 0;

  // Return the earliest incoming stream that has been received by the session
  // but has not been accepted.  Returns nullptr if there are no incoming
  // streams.
  virtual WebTransportStream* AcceptIncomingBidirectionalStream() = 0;
  virtual WebTransportStream* AcceptIncomingUnidirectionalStream() = 0;

  // Returns true if flow control allows opening a new stream.
  virtual bool CanOpenNextOutgoingBidirectionalStream() = 0;
  virtual bool CanOpenNextOutgoingUnidirectionalStream() = 0;
  // Opens a new WebTransport stream, or returns nullptr if that is not possible
  // due to flow control.
  virtual WebTransportStream* OpenOutgoingBidirectionalStream() = 0;
  virtual WebTransportStream* OpenOutgoingUnidirectionalStream() = 0;

  virtual MessageStatus SendOrQueueDatagram(
      quiche::QuicheMemSlice datagram) = 0;
  // Returns a conservative estimate of the largest datagram size that the
  // session would be able to send.
  virtual QuicByteCount GetMaxDatagramSize() const = 0;
  // Sets the largest duration that a datagram can spend in the queue before
  // being silently dropped.
  virtual void SetDatagramMaxTimeInQueue(QuicTime::Delta max_time_in_queue) = 0;
};

}  // namespace quic

#endif  // QUICHE_QUIC_CORE_WEB_TRANSPORT_INTERFACE_H_