// 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.

/// The component fuzzer framework.
///
/// Fuzzing (or fuzz testing) is the process of pseudorandomly generating inputs
/// for some target, executing the target with those inputs, and detecting
/// various error conditions that may arise as a result. Guided fuzzing uses
/// additional feedback from the target besides errors to determine whether
/// inputs should be saved and used as the basis of subsequent inputs. A
/// concrete example of guided fuzzing is coverage-guided fuzzing, which uses
/// whether executing the target with a fuzzing input produced new code coverage
/// to determine whether it should be added to the corpus, that is, the set of
/// saved inputs.
///
/// Guided fuzzing frameworks can be described using the following taxonomy:
///
/// * Engine: A target-agnostic feedback loop.
///     * Corpus management: Maintains a collection of fuzzing inputs.
///     * Mutators: Mutation strategies and a PRNG used to create new inputs
///       from existing ones.
///     * Feedback analysis: Dispositions an input based on its feedback, e.g.
///       code coverage.
///     * Management interface: Interacts with the user to coordinates
///       workflows.
/// * Target: The specific code under test.
///     * Input processing: Maps the fuzzer input for a single run to the code
///       under test.
///     * Feedback collection: Observes the behavior caused by an input.
///     * Error detection: Determines when an input has caused an error and
///       collects artifacts.
///
/// In order to fuzz components and component topologies, the component fuzzer
/// framework leverages the test runner framework for its environment and
/// execution features. It adds the pieces of the taxonomy above into and around
/// the test runner framework:
///
/// * A fuzz-manager that acts as a sibling to test-manager, and provides the
///   management interface.
/// * A fuzz-registry that allows the fuzz-manager to find running fuzzers.
/// * A fuzz-test-runner within the test runner framework that launches the
///   fuzzed realm and passes it a connection to the fuzz-registry.
/// * A fuzzer engine within the fuzzed realm that registers with the registry.
///   It analyzes feedback and generates new inputs using mutators.
/// * A target adapter that provides transforms inputs from the engine to
///   behaviors in the target components, e.g. via FIDL calls.
/// * A ELF library that is linked against instrumented processes in the target
///   components and that provides feedback collection and error detection to
///   the fuzz-test-driver.
///
/// This FIDL library provides the protocols and types used by these elements of
/// the framework to interact with one another. These types are found in the
/// following files:
///
/// * adapter.fidl:
///     * Implementations of the `TargetAdapter` protocol transform inputs.
/// * controller.fidl:
///     * Each `Result` enumerates a possible outcome of executing the target
///       with a test input.
///     * `Input` structs represent sequences of bytes used to test the target
///       and that can be transferred to and from a development host.
///     * Implementations of the `Controller` protocol allow clients to control
///       fuzzing execution.
///     * Implementations of the `ControllerProvider` protocol connect clients
///       to fuzzers.
/// * corpus.fidl:
///     * Each `Corpus` enumerates a set of fuzzing inputs.
///     * Implementations of the `CorpusReader` protocol allow iterating over a
///       corpus of inputs.
/// * coverage.fidl:
///     * The `InstrumentedProcess` struct represents a process that can collect
///       code coverage data.
///     * Implementations of `CoverageDataCollector` aggregate LLVM module code
///       coverage data from instrumented processes.
///     * `CoverageData` is a union that can represent instrumented processes or
///       modules.
///     * Implementations of `CoverageDataProvider` allow the engine to retrieve
///       code coverage data for instrumented processes.
/// * manager.fidl:
///     * Implementations of `Manager` allow clients to start, connect to, and
///       stop fuzz test realms.
///     * Each `TestOutput` enumerates a diagnostic stream from the test realm.
/// * options.fidl:
///     * The `Options` table details various configurable parameters for the
///       fuzzer.
/// * registry.fidl:
///     * Implementations of `Registrar` allow each fuzzer to register its
///       `ControllerProvider` on launch.
///     * Implementations of `Registry` allow the `fuzz_manager` to connect to
///       or disconnect fuzz test realms.
/// * status.fidl:
///     * `ProcessStats` has `ZX_INFO_TASK_STATS` and `ZX_INFO_TASK_RUNTIME`
///       details from targets.
///     * Each `UpdateReason` enumerates why status is being "pushed" by the
///       fuzzer.
///     * Implementations of the `Monitor` protocol subscribe to updates from
///       the fuzzer.
library fuchsia.fuzzer;