| // 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"; |