// 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.
@available(added=16)
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;
    /// Error resolving the package that is to be explored.
    RESOLVE_TARGET_PACKAGE = 16;
};

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

/// The package resolvers available for resolving package URLs with the `fuchsia-pkg` scheme.
@available(added=20)
type FuchsiaPkgResolver = flexible enum : uint32 {
    /// Resolves base packages from blobfs.
    BASE = 1;
    /// Resolves base, cache, or universe packages from blobfs and any configured remote
    /// repositories.
    FULL = 2;
};

@discoverable
closed protocol Launcher {
    /// Launch a dash process scoped to the component with the given moniker, forwarding the given
    /// stdio PTY.
    strict 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.
    strict 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;

    /// Launch a dash process with the indicated [sub]package loaded into the namespace at /pkg,
    /// forwarding the given stdio socket.
    ///
    /// The dash launcher will implicitly create a PTY and transfer bytes between the PTY and
    /// the socket.
    ///
    /// Always uses [`fuchsia.dash/FuchsiaPkgResolver.FULL`] to resolve package URLs with scheme
    /// "fuchsia-pkg".
    /// Use [`fuchsia.dash/Launcher.ExplorePackageOverSocket2`] instead to pick which resolver to
    /// use with "fuchsia-pkg" URLs.
    @available(
            deprecated=20,
            note="use ExplorePackageOverSocket2 which has a FuchsiaPkgResolver parameter instead of defaulting to the Full resolver")
    strict ExplorePackageOverSocket(resource struct {
        /// The absolute package URL to resolve.
        /// If `subpackages` is empty the resolved package directory will be loaded into the dash
        /// namespace at `/pkg`.
        /// If `subpackages` is not empty, the package directory of the final subpackage of `url`
        /// will be loaded into the namespace at `/pkg`.
        url string:MAX;
        /// The chain of subpackages, if any, of `url` to resolve, in resolution order.
        /// If `subpackages` is not empty, the package directory of the final subpackage will be
        /// loaded into the dash namespace at `/pkg`.
        subpackages vector<string:MAX>: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>;
    }) -> () error LauncherError;

    /// Launch a dash process with the indicated [sub]package loaded into the namespace at /pkg,
    /// forwarding the given stdio socket.
    ///
    /// The dash launcher will implicitly create a PTY and transfer bytes between the PTY and
    /// the socket.
    @available(added=20)
    strict ExplorePackageOverSocket2(resource struct {
        /// The package resolver to use when resolving package URLs (both `url` and `tool_urls`)
        /// that have the `fuchsia-pkg` scheme.
        fuchsia_pkg_resolver FuchsiaPkgResolver;

        /// The absolute package URL to resolve.
        /// If `subpackages` is empty the resolved package directory will be loaded into the dash
        /// namespace at `/pkg`.
        /// If `subpackages` is not empty, the package directory of the final subpackage of `url`
        /// will be loaded into the namespace at `/pkg`.
        url string:MAX;

        /// The chain of subpackages, if any, of `url` to resolve, in resolution order.
        /// If `subpackages` is not empty, the package directory of the final subpackage will be
        /// loaded into the dash namespace at `/pkg`.
        subpackages vector<string:MAX>: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>;
    }) -> () error LauncherError;

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