// Copyright 2020 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.testing.proxy;

/// A protocol that enables creating TCP proxies so that host tests may
/// access debug services that normally accept only local connections.
///
/// For example, if web browser exposes a debug HTTP service listening on
/// [::1]:9999, TcpProxyControl may listen on [::]:10000 and forward requests
/// to port 9999. The host test then calls port 10000 to access the web browser's
/// debug service.
@discoverable
closed protocol TcpProxyControl {
    /// Opens a proxy to the given |target_port|. If a proxy is already open
    /// for the specified |target_port|, the existing |open_port| is returned.
    /// The proxy remains open as long as at least a single client keeps their
    /// |proxy_token| handle for the specified |target_port|. Once all the
    /// |proxy_token| handles are closed, the proxy is closed. |proxy_port| is
    /// the source port where the proxy is opened. Except when the test running
    /// on remote host needs to reach a local device, its value is 0. This is
    /// only useful when the user has tunneled these ports to the local device
    /// and specified that port number as |proxy_port|.
    strict OpenProxy(resource struct {
        target_port uint16;
        proxy_port uint16;
        tcp_proxy server_end:TcpProxy;
    }) -> (struct {
        open_port uint16;
    });
};

/// An empty protocol which serves as a token for a proxy started with
/// |TcpProxyControl.OpenProxy|. The proxy stays open as long as at least one
/// |TcpProxy| channel corresponding to the proxy remains open. Note that the
/// server may close the channel in the case an error is encountered.
closed protocol TcpProxy {};