// 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 users, e.g. `ffx fuzz`, used to start and stop fuzzers. A
/// fuzzer will be started on the first call to `Connect` with a given URL.
/// Closing the given `Controller` channel does *not* stop the associated
/// fuzzer. Instead, since fuzzing is meant to be long-running, clients
/// may drop the connection and re-`Connect` some time later.
@discoverable
closed protocol Manager {
    /// Connects to a fuzzer that implements the `fuchsia.fuzzer/Controller`
    /// protocol.
    ///
    /// If the fuzzer is not currently running, the `fuzz_manager` will first
    /// start it (via the test_manager) before proceeding. The `fuzz_manager`
    /// sends the `controller` on to the fuzz-registry, which contains the
    /// `ControllerProviders` that can fulfill the connection request.
    ///
    /// See `fuchsia.test.manager/LaunchError` for details on ways
    /// `test_manager` can fail.
    ///
    /// + request `fuzzer_url` the package URL for the fuzzer.
    /// + request `controller` the connection from the client.
    /// * error one of the following:
    ///     * `ZX_ERR_NO_RESOURCES` if `test_manager` needs resources that are
    ///       unavailable.
    ///     * `ZX_ERR_NOT_FOUND` if the fuzzer URL is not recognized by
    ///       `test_manager`.
    ///     * `ZX_ERR_INVALID_ARGS` if `test_manager` reports invalid arguments.
    ///     * `ZX_ERR_NOT_SUPPORTED` if `test_manager` cannot connect to the
    ///       test suite.
    ///     * `ZX_ERR_INTERNAL` if `test_manager` encountered some other,
    ///       unspecified failure.
    ///     * `ZX_ERR_TIMED_OUT` if the fuzzer is not present or added to
    ///       fuzz-registry after starting.
    ///     * `ZX_ERR_SHOULD_WAIT` if another fuzzer is still starting.
    strict Connect(resource struct {
        fuzzer_url fuchsia.url.Url;
        controller server_end:Controller;
    }) -> () error zx.Status;

    /// Forwards the fuzzer's output of the given type to the provided socket.
    ///
    /// If this method is called multiple times for the same output type, the
    /// socket from the subsequent call replaces the socket from the earlier
    /// call, which is closed.
    ///
    /// + request `fuzzer_url` the package URL for the fuzzer.
    /// + request `output` the type of the output stream to forward.
    /// + request `socket` a socket to forward the output stream to.
    /// * error one of the following:
    ///     * `ZX_ERR_INVALID_ARGS` if the URL cannot be parsed.
    ///     * `ZX_ERR_NOT_FOUND` if the fuzzer URL was not recognized by
    ///       `test_manager`.
    ///     * `ZX_ERR_BAD_STATE` if the fuzzer is not connected.
    strict GetOutput(resource struct {
        fuzzer_url fuchsia.url.Url;
        output TestOutput;
        socket zx.Handle:SOCKET;
    }) -> () error zx.Status;

    /// Stops the associated fuzzer immediately, ending any workflows in
    /// progress.
    ///
    /// + request `fuzzer_url` the package URL for the fuzzer.
    /// * error `ZX_ERR_NOT_FOUND` if no fuzzer was active with the given URL.
    strict Stop(struct {
        fuzzer_url fuchsia.url.Url;
    }) -> () error zx.Status;
};

/// Represents types of fuzzer output.
///
/// These correspond to the subset of the `fuchsia.test_manager/Artifact`s that
/// `fuzz_manager` can forward. The name "artifact" is avoided due to its
/// distinct meaning for fuzzers; namely, `fuchsia.fuzzer.Artifact`.
type TestOutput = flexible enum {
    /// Standard output from fuzzer.
    STDOUT = 1;

    /// Standard error from fuzzer.
    STDERR = 2;

    /// System logs from fuzzer.
    SYSLOG = 3;
};

/// Command line flag requesting fuzzing to be performed.
///
/// This flag is passed by the `fuzz_manager` to the `test_manager` when
/// starting fuzzers. Since the fuzzers are run as part of the Test Runner
/// Framework, they can be started by normal test workflows, e.g. `fx test`. The
/// presence of this flag indicates the fuzzer is being started to perform
/// fuzzing; in its absence the fuzzer should simply execute a bounded number of
/// inputs as a test.
const FUZZ_MODE string = "--fuzz";