services/network/public/mojom/restricted_udp_socket.mojom

// Copyright 2022 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

module network.mojom;

import "mojo/public/mojom/base/read_only_buffer.mojom";
import "services/network/public/mojom/host_resolver.mojom";
import "services/network/public/mojom/network_param.mojom";
import "services/network/public/mojom/udp_socket.mojom";
import "services/network/public/mojom/ip_address.mojom";

[EnableIf=is_chromeos]
import "services/network/public/mojom/socket_connection_tracker.mojom";

// The mode that RestrictedUDPSocket is operating in.
// See Connect() and Bind() methods of network.mojom.UDPSocket for more details.
enum RestrictedUDPSocketMode {
  CONNECTED,
  BOUND,
};

struct RestrictedUDPSocketParams {
  // These options will be passed to the OS to configure the actual UDP Socket.
  UDPSocketOptions? socket_options;

  [EnableIf=is_chromeos]
  // The caller may choose to supply a |connection_tracker| if they lack access
  // to the endpoints of the actual connection but would like to get informed
  // when it shuts down.
  pending_remote<SocketConnectionTracker>? connection_tracker;
};

// This wraps network.mojom.UDPSocket, exposing only the functionality needed
// for the Direct Sockets API.
//
// The original network.mojom.UDPSocket allows the caller to perform a second
// round of Bind() or Connect() calls after Close() which is highly undesirable
// in an untrusted process like the renderer. This restricted version implements
// a different model where the socket is bound or connected right upon creation
// and can't change its state afterwards.
//
// Caller can close the socket by destroying the interface pointer.
interface RestrictedUDPSocket {
  // Joins a multicast group. `group_address` is the group address to join,
  // could be either an IPv4 or IPv6 address. Returns a net error code.
  // See RFC 1112 for details on multicast.
  JoinGroup(IPAddress group_address) => (int32 result);

  // Leaves the multicast group. `group_address` is the group address to leave,
  // could be either an IPv4 or IPv6 address. If the socket hasn't joined the
  // group, this call will be ignored. It's optional to leave the multicast
  // group before destroying the socket. Returns a net error code.
  LeaveGroup(IPAddress group_address) => (int32 result);

  // Notifies that the listener is ready to accept datagrams. OnReceived() of
  // the UDPSocketListener interface will be called |num_additional_datagrams|
  // times (errors also count), unless the connection is closed before that.
  ReceiveMore(uint32 num_additional_datagrams);

  // Sends a UDP datagram |data|.
  // Upon successfully handing the data to the OS, |result| is net::OK.
  // On failure, |result| is a network error code.
  // Note that this call is only valid in CONNECTED mode, otherwise it will
  // immediately fail with an error.
  Send(mojo_base.mojom.ReadOnlyBuffer data)
      => (int32 result);

  // Sends a UDP datagram to a particular destination |dest_addr|.
  // DNS resolution hints can be provided by supplying |dns_query_type|.
  // Upon successfully handing the data to the OS, |result| is net::OK.
  // On failure, |result| is a network error code.
  // Note that this call is only valid in BOUND mode, otherwise it will
  // immediately fail with an error.
  // TODO(crbug.com/40489779): Make |dns_query_type| optional once Java support
  // lands.
  SendTo(
      mojo_base.mojom.ReadOnlyBuffer data,
      HostPortPair dest_addr,
      network.mojom.DnsQueryType dns_query_type)
      => (int32 result);
};