api/transport/network_control.h

/*
 *  Copyright (c) 2018 The WebRTC project authors. All Rights Reserved.
 *
 *  Use of this source code is governed by a BSD-style license
 *  that can be found in the LICENSE file in the root of the source
 *  tree. An additional intellectual property rights grant can be found
 *  in the file PATENTS.  All contributing project authors may
 *  be found in the AUTHORS file in the root of the source tree.
 */

#ifndef API_TRANSPORT_NETWORK_CONTROL_H_
#define API_TRANSPORT_NETWORK_CONTROL_H_

#include <memory>
#include <optional>

#include "absl/base/attributes.h"
#include "api/environment/environment.h"
#include "api/field_trials_view.h"
#include "api/transport/network_types.h"
#include "api/units/data_rate.h"
#include "api/units/time_delta.h"

namespace webrtc {

class TargetTransferRateObserver {
 public:
  virtual ~TargetTransferRateObserver() = default;
  // Called to indicate target transfer rate as well as giving information about
  // the current estimate of network parameters.
  virtual void OnTargetTransferRate(TargetTransferRate) = 0;
  // Called to provide updates to the expected target rate in case it changes
  // before the first call to OnTargetTransferRate.
  virtual void OnStartRateUpdate(DataRate) {}
};

// Configuration sent to factory create function. The parameters here are
// optional to use for a network controller implementation.
struct NetworkControllerConfig {
  explicit NetworkControllerConfig(const Environment& env) : env(env) {}

  Environment env;

  // The initial constraints to start with, these can be changed at any later
  // time by calls to OnTargetRateConstraints. Note that the starting rate
  // has to be set initially to provide a starting state for the network
  // controller, even though the field is marked as optional.
  TargetRateConstraints constraints;
  // Initial stream specific configuration, these are changed at any later time
  // by calls to OnStreamsConfig.
  StreamsConfig stream_based_config;
  // Default time window used for calculating how send packets are paced.
  // Note that a network controller can choose to request the pacer to pace
  // packets stricter.
  TimeDelta default_pacing_time_window = PacerConfig::kDefaultTimeInterval;
};

// NetworkControllerInterface is implemented by network controllers. A network
// controller is a class that uses information about network state and traffic
// to estimate network parameters such as round trip time and bandwidth. Network
// controllers does not guarantee thread safety, the interface must be used in a
// non-concurrent fashion.
class NetworkControllerInterface {
 public:
  virtual ~NetworkControllerInterface() = default;

  // Called when network availabilty changes.
  ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnNetworkAvailability(
      NetworkAvailability) = 0;
  // Called when the receiving or sending endpoint changes address.
  ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnNetworkRouteChange(
      NetworkRouteChange) = 0;
  // Called periodically with a periodicy as specified by
  // NetworkControllerFactoryInterface::GetProcessInterval.
  ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnProcessInterval(
      ProcessInterval) = 0;
  // Called when remotely calculated bitrate is received.
  ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnRemoteBitrateReport(
      RemoteBitrateReport) = 0;
  // Called round trip time has been calculated by protocol specific mechanisms.
  ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnRoundTripTimeUpdate(
      RoundTripTimeUpdate) = 0;
  // Called when a packet is sent on the network.
  ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnSentPacket(
      SentPacket) = 0;
  // Called when a packet is received from the remote client.
  ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnReceivedPacket(
      ReceivedPacket) = 0;
  // Called when the stream specific configuration has been updated.
  ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnStreamsConfig(
      StreamsConfig) = 0;
  // Called when target transfer rate constraints has been changed.
  ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnTargetRateConstraints(
      TargetRateConstraints) = 0;
  // Called when a protocol specific calculation of packet loss has been made.
  ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnTransportLossReport(
      TransportLossReport) = 0;
  // Called with per packet feedback regarding receive time.
  ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnTransportPacketsFeedback(
      TransportPacketsFeedback) = 0;
  // Called with network state estimate updates.
  ABSL_MUST_USE_RESULT virtual NetworkControlUpdate OnNetworkStateEstimate(
      NetworkStateEstimate) = 0;
  // Returns true if the network controller supports adaptation to ECN.
  // https://www.rfc-editor.org/rfc/rfc9331.html
  virtual bool SupportsEcnAdaptation() const { return false; }
};

// NetworkControllerFactoryInterface is an interface for creating a network
// controller.
class NetworkControllerFactoryInterface {
 public:
  virtual ~NetworkControllerFactoryInterface() = default;

  // Used to create a new network controller, requires an observer to be
  // provided to handle callbacks.
  virtual std::unique_ptr<NetworkControllerInterface> Create(
      NetworkControllerConfig config) = 0;
  // Returns the interval by which the network controller expects
  // OnProcessInterval calls.
  virtual TimeDelta GetProcessInterval() const = 0;
};

// Under development, subject to change without notice.
class NetworkStateEstimator {
 public:
  // Gets the current best estimate according to the estimator.
  virtual std::optional<NetworkStateEstimate> GetCurrentEstimate() = 0;
  // Called with per packet feedback regarding receive time.
  // Used when the NetworkStateEstimator runs in the sending endpoint.
  virtual void OnTransportPacketsFeedback(const TransportPacketsFeedback&) = 0;
  // Called with per packet feedback regarding receive time.
  // Used when the NetworkStateEstimator runs in the receiving endpoint.
  virtual void OnReceivedPacket(const PacketResult&) {}
  // Called when the receiving or sending endpoint changes address.
  virtual void OnRouteChange(const NetworkRouteChange&) = 0;
  virtual ~NetworkStateEstimator() = default;
};
class NetworkStateEstimatorFactory {
 public:
  virtual std::unique_ptr<NetworkStateEstimator> Create(
      const FieldTrialsView* key_value_config) = 0;
  virtual ~NetworkStateEstimatorFactory() = default;
};
}  // namespace webrtc

#endif  // API_TRANSPORT_NETWORK_CONTROL_H_