// 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 exisiting 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 a 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 provides
///    mutators and feedback analysis.
///  * A target adapter that provides input processing from the fuzz-test-driver to specific
///    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 provide input-processing.
///  * controller.fidl:
///    * |Input| structs represent file-like fuzzing inputs that can be transferred over FIDL.
///    * Each |Result| enumerates a possible outcome of executing the target with a fuzzing input.
///    * Implementations of the |ControllerProvider| protocol connect clients to fuzzers.
///    * Implementations of the |Controller| protocol allow clients to control fuzzing execution.
///  * corpus.fidl:
///    * Each |Corpus| enumerates a set of fuzzing inputs.
///    * Implementations of the |CorpusReader| protocol allow iterating over a corpus of inputs.
///  * options.fidl:
///    * The |Options| table details various configurable parameters for the fuzzer.
///  * process.fidl:
///    * The |Feedback| table lists target-provided feedback that can be used to guide fuzzing.
///    * Implementations of the |ProcessProxy| protocol accept feedback from targets.
///  * 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;