// Copyright 2016 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.sys;

using fuchsia.io;
using fuchsia.mem;
using zx;

/// Information given to components at startup.
///
/// For ELF binaries, this information is provided in the initialization
/// message given to `libc` by `fuchsia.process.Launcher`.
type StartupInfo = resource struct {
    /// The launch info for the component to start.
    launch_info LaunchInfo;

    /// The namespace in which to run the component.
    flat_namespace FlatNamespace;

    /// Key string value string map of the component's program metadata,
    /// obtained from its component manifest.
    program_metadata vector<ProgramMetadata>:optional;

    // TODO(abarth): Add more fields to this struct relating to component and
    // environment identity.
};

/// Program information about a component.
type ProgramMetadata = struct {
    /// Key for program metadata pair. E.g. "binary" for an ELF binary
    /// component, or "data" for a flutter/dart component.
    key string;

    /// Value for program metadata pair. E.g. "bin/app" for a "binary" key, or
    /// "data/foo" for a flutter/dart component.
    value string;
};

/// A binary representation of a component.
///
/// Typically provided to `Runner.StartComponent` when starting a component.
type Package = resource struct {
    /// A read-only binary representation of the component. For example, if the
    /// component is intended to run in the Dart virtual machine, this data
    /// might contain a dartx package.
    data box<fuchsia.mem.Buffer>;

    /// A directory containing the contents of the package. For example, if the
    /// component is stored in pkgfs, this directory will be the pkgfs
    /// directory containing the package.
    @available(replaced=10)
    directory zx.Handle:<CHANNEL, optional>;
    @available(added=10)
    directory client_end:<fuchsia.io.Directory, optional>;

    /// Resolved URL of the component. This is the url specified in
    /// `startup_info` after following redirects and resolving relative paths.
    resolved_url component_url;
};

/// An interface for running components.
///
/// Typically exposed by components that provide execution environments for
/// particular classes of programs. For example, the Dart virtual machine
/// exposes this interface to run Dart programs.
@discoverable
closed protocol Runner {
    /// Execute the given component.
    ///
    /// Upon startup, the component is to be given the information in
    /// `startup_info`, but the mechanism by which the component receives that
    /// information is up to the component runner.
    ///
    /// The `controller` interface request typically originates from the
    /// `Launcher.CreateComponent` message that caused this component to be
    /// started.
    strict StartComponent(resource struct {
        package Package;
        startup_info StartupInfo;
        controller server_end:<ComponentController, optional>;
    });
};