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;

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

/// 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 given moniker, forwarding the given stdio PTY.
    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 package URL whose directory will also be loaded into the dash namespace
        tools_url fuchsia.url.Url:optional;
        /// A 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 given moniker, forwarding the given stdio socket.
    ///
    /// The dash launcher will implicitly create a PTY and transfer bytes between the PTY and
    /// the socket.
    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 package URL whose directory will also be loaded into the dash namespace
        tools_url fuchsia.url.Url:optional;
        /// A 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;
    });
};