// Copyright 2021 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.fuzzer;

using fuchsia.url;
using zx;

/// Entry point for the `fuzz_test_runner`. It uses this protocol to transfer
/// one end of a channel it creates to the `fuzz_manager`. The other end is
/// passed as a startup handle to the fuzzer component itself, which is used to
/// provide `Controller`s on request.
@discoverable
closed protocol Registrar {
    /// Adds a `ControllerProvider`. This should be called by the fuzzer itself,
    /// using the channel provided by the `fuzz_test_runner`, and in response to
    /// being started by the `fuzz_manager`.
    ///
    /// The registry will close the channel to the fuzzer on error, on a
    ///  corresponding call to `Registry.Disconnect`, or on exit. The fuzzer
    /// should exit when the channel closes.
    ///
    /// + request `fuzzer_url` the package URL for the fuzzer.
    /// + request `provider` the connection to a `ControllerProvider`.
    strict Register(resource struct {
        fuzzer_url fuchsia.url.Url;
        provider client_end:ControllerProvider;
    }) -> ();
};

/// Entry point for the `fuzz_manager`. It uses this protocol to wait for fuzz
/// tests started within the test runner framework to register a
/// `ControllerProvider`, and to stop those fuzzers upon request.
@discoverable
closed protocol Registry {
    /// Connects the `Controller` to a registered fuzzer.
    ///
    /// Uses a `ControllerProvider` that has been `Register`ed with the given
    /// URL to connect. If the associated provider is not available, it assumes
    /// it is starting and blocks until the fuzzer calls `Registrar.Register`,
    /// or the given `timeout` elapses. At most one call to `Connect` will block
    /// in this manner at a time.
    ///
    /// + request `fuzzer_url` the package URL for the fuzzer.
    /// + request `provider` the connection to a `Controller` client.
    /// + request `tiemout` maximum duration to wait for a connection.
    /// * error one of the following:
    ///     * `ZX_ERR_TIMED_OUT` if the `timeout` elapses without the provider
    ///       becoming available.
    ///     * `ZX_ERR_SHOULD_WAIT` if already waiting for a fuzzer to start.
    strict Connect(resource struct {
        fuzzer_url fuchsia.url.Url;
        controller server_end:Controller;
        timeout zx.Duration;
    }) -> () error zx.Status;

    /// Removes the provider associated with the given URL from the registry and
    /// closes its channel. The associated fuzzer should exit upon channel
    /// closure.
    ///
    /// + request `fuzzer_url` the package URL for the fuzzer.
    /// * error `ZX_ERR_NOT_FOUND` if no such provider exists in the registry.
    strict Disconnect(struct {
        fuzzer_url fuchsia.url.Url;
    }) -> () error zx.Status;
};