blob: 191cbb95e5a77f740660de4773c8a15184bd62ce [file] [log] [blame]
// 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
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.
///
/// Returns ZX_ERR_NO_RESOURCES if test_manager reports needed resources are unavailable.
/// Returns ZX_ERR_NOT_FOUND if the fuzzer URL was not recognized by test_manager.
/// Returns ZX_ERR_INVALID_ARGS if test_manager reports invalid arguments.
/// Returns ZX_ERR_NOT_SUPPORTED if test_manager cannot connect to the test suite.
/// Returns ZX_ERR_INTERNAL for other, unspecified test_manager failures.
/// Returns ZX_ERR_TIMED_OUT if the fuzzer not present or added to fuzz-registry after starting.
/// Returns ZX_ERR_SHOULD_WAIT if another fuzzer is still starting.
Connect(resource struct {
fuzzer_url fuchsia.url.Url;
controller server_end:Controller;
}) -> (struct {
result 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.
///
/// Returns ZX_ERR_INVALID_ARGS if the URL cannot be parsed.
/// Returns ZX_ERR_NOT_FOUND if the fuzzer URL was not recognized by test_manager.
/// Returns ZX_ERR_BAD_STATE if the fuzzer is not connected.
GetOutput(resource struct {
fuzzer_url fuchsia.url.Url;
output TestOutput;
socket zx.handle:SOCKET;
}) -> (struct {
result zx.status;
});
/// Stops the associated fuzzer immediately, ending any workflows in progress.
///
/// Returns ZX_OK if the given fuzzer was active.
/// Returns ZX_ERR_NOT_FOUND if no fuzzer was active with the given URL.
Stop(struct {
fuzzer_url fuchsia.url.Url;
}) -> (struct {
result 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 as it has a distinct connotation 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
/// performing fuzzing; in its absence the fuzzer should simply execute a bounded number of inputs
/// as a test.
const FUZZ_MODE string = "--fuzz";