// Copyright 2023 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=18)
library fuchsia.starnix.container;

using zx;

type ConsoleWindowSize = struct {
    rows uint16;
    cols uint16;
    x_pixels uint16;
    y_pixels uint16;
};

@available(added=HEAD)
type VmoReference = table {
    /// The name of the process containing a file backed by the vmo.
    1: process_name string:MAX;

    /// The Starnix pid of the process containing a file backed by the vmo.
    2: pid uint64;

    /// The file descriptor number in the process that refers to the vmo.
    3: fd int32;

    /// The koid of the vmo.
    4: koid uint64;
};

@discoverable
open protocol Controller {
    /// Connects `bridge_socket` to a vsocket at `port` in the container.
    flexible VsockConnect(resource table {
        1: port uint32;
        2: bridge_socket zx.Handle:SOCKET;
    });

    /// Spawn a console for debugging in the container. For testing, prefer launching Linux programs
    /// as components with the `starnix_container` runner.
    ///
    /// Returns when the console exits.
    flexible SpawnConsole(resource table {
        1: console_in zx.Handle:SOCKET;
        2: console_out zx.Handle:SOCKET;
        3: binary_path string:MAX;
        4: argv vector<string:MAX>:MAX;
        5: environ vector<string:MAX>:MAX;
        6: window_size ConsoleWindowSize;
    }) -> (struct {
        exit_code uint8;
    }) error SpawnConsoleError;

    /// Returns all processes that have open files that are backed by a vmo with koid.
    @available(added=HEAD)
    flexible GetVmoReferences(table {
        1: koid uint64;
    }) -> (table {
        1: references vector<VmoReference>:MAX;
    });

    /// Returns the job handle of the container.
    @available(added=HEAD)
    flexible GetJobHandle() -> (resource table {
        1: job zx.Handle:JOB;
    });
};

type SpawnConsoleError = flexible enum {
    /// A required table field was missing or otherwise invalid.
    INVALID_ARGS = 1;

    /// The console process exited without a normal return code.
    CANCELED = 2;
};