sdk/fidl/fuchsia.dash/launcher.fidl

// Copyright 2022 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.dash;

using zx;
using fuchsia.hardware.pty;
using fuchsia.url;

/// Maximum number of URLs allowed to be sent to the launcher.
const MAX_URLS uint64 = 20;

/// Standard errors for the Launcher protocol
type LauncherError = strict enum {
    /// Launcher encountered an unspecified error
    INTERNAL = 1;
    /// Moniker could not be parsed by launcher
    BAD_MONIKER = 2;
    /// No instance was found matching the moniker
    INSTANCE_NOT_FOUND = 3;
    /// Error occurred using fuchsia.sys2.RealmQuery
    REALM_QUERY = 4;
    /// Error occurred using fuchsia.process.Launcher
    PROCESS_LAUNCHER = 5;
    /// Error loading dash binary
    DASH_BINARY = 6;
    /// Error occurred involving the PTY
    PTY = 7;
    /// Instance is not in a resolved state, so there is nothing to explore
    INSTANCE_NOT_RESOLVED = 8;
    /// Error occurred using fuchsia.pkg.PackageResolver
    PACKAGE_RESOLVER = 9;
    /// Error resolving tools package
    TOOLS_CANNOT_RESOLVE = 10;
    /// URL could not be parsed by launcher
    BAD_URL = 11;
    /// Error reading a binary from a tools package
    TOOLS_BINARY_READ = 12;
    /// A binary name was repeated
    NON_UNIQUE_BINARY_NAME = 13;
    /// Error occurred using fuchsia.process.Resolver
    PROCESS_RESOLVER = 14;
    /// Error occurred using fuchsia.kernel.VmexResource
    VMEX_RESOURCE = 15;
};

/// The namespace layout to create for the dash process.
type DashNamespaceLayout = strict enum {
    /// All instance directories are nested under subdirectories.
    /// e.g - namespace is under /ns, outgoing dir is under /out, etc.
    NEST_ALL_INSTANCE_DIRS = 1;
    /// The instance namespace is the root of the dash shell.
    /// Several ELF binaries and libraries in Fuchsia assume that directories like
    /// `svc` and `dev` will be at the root. As a result, this layout should be
    /// more compatible than nesting for running Fuchsia ELF binaries in the shell.
    INSTANCE_NAMESPACE_IS_ROOT = 2;
};

@discoverable
protocol Launcher {
    /// Launch a dash process scoped to the component with the given moniker, forwarding the given
    /// stdio PTY.
    // TODO(fxbug.dev/127317) This is the old name for `ExploreComponentOverPty`. Remove it once
    // no ffx binaries depend on it.
    LaunchWithPty(resource struct {
        /// The moniker of the component that dash should be scoped to
        moniker string:MAX;
        /// The PTY device that should be forwarded to the dash process
        pty client_end:fuchsia.hardware.pty.Device;
        /// A list of package URLs whose directories will also be loaded into the dash namespace.
        /// The path preference is determined by the order of this vector.
        tool_urls vector<fuchsia.url.Url>:<MAX_URLS>;
        /// An optional inline command to run
        command string:<MAX, optional>;
        /// The namespace layout to create for the dash process
        ns_layout DashNamespaceLayout;
    }) -> () error LauncherError;

    /// Launch a dash process scoped to the component with the given moniker, forwarding the given
    /// stdio PTY.
    ExploreComponentOverPty(resource struct {
        /// The moniker of the component that dash should be scoped to
        moniker string:MAX;
        /// The PTY device that should be forwarded to the dash process
        pty client_end:fuchsia.hardware.pty.Device;
        /// A list of package URLs whose directories will also be loaded into the dash namespace.
        /// The path preference is determined by the order of this vector.
        tool_urls vector<fuchsia.url.Url>:<MAX_URLS>;
        /// An optional inline command to run
        command string:<MAX, optional>;
        /// The namespace layout to create for the dash process
        ns_layout DashNamespaceLayout;
    }) -> () error LauncherError;

    /// Launch a dash process scoped to the component with the given moniker, forwarding the given
    /// stdio socket.
    ///
    /// The dash launcher will implicitly create a PTY and transfer bytes between the PTY and
    /// the socket.
    // TODO(fxbug.dev/127317) This is the old name for `ExploreComponentOverSocket`. Remove it once
    // no ffx binaries depend on it.
    LaunchWithSocket(resource struct {
        /// The moniker of the component that dash should be scoped to
        moniker string:MAX;
        /// The raw socket to connect to the dash process
        socket zx.Handle:SOCKET;
        /// A list of package URLs whose directories will also be loaded into the dash namespace.
        /// The path preference is determined by the order of this vector.
        tool_urls vector<fuchsia.url.Url>:<MAX_URLS>;
        /// An optional inline command to run
        command string:<MAX, optional>;
        /// The namespace layout to create for the dash process
        ns_layout DashNamespaceLayout;
    }) -> () error LauncherError;

    /// Launch a dash process scoped to the component with the given moniker, forwarding the given
    /// stdio socket.
    ///
    /// The dash launcher will implicitly create a PTY and transfer bytes between the PTY and
    /// the socket.
    ExploreComponentOverSocket(resource struct {
        /// The moniker of the component that dash should be scoped to
        moniker string:MAX;
        /// The raw socket to connect to the dash process
        socket zx.Handle:SOCKET;
        /// A list of package URLs whose directories will also be loaded into the dash namespace.
        /// The path preference is determined by the order of this vector.
        tool_urls vector<fuchsia.url.Url>:<MAX_URLS>;
        /// An optional inline command to run
        command string:<MAX, optional>;
        /// The namespace layout to create for the dash process
        ns_layout DashNamespaceLayout;
    }) -> () error LauncherError;

    /// This event fires when a shell has terminated.
    -> OnTerminated(struct {
        /// The process exit code of the shell.
        return_code int32;
    });
};