sdk/fidl/fuchsia.component.sandbox/sandbox.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.component.sandbox;

using zx;
using fuchsia.io;
using fuchsia.unknown;

/// A capability of unknown type.
alias Capability = zx.Handle;

/// The key of a [`DictItem`].
alias DictKey = string:MAX;

/// A key-value pair in a [`Dict`].
type DictItem = resource struct {
    key DictKey;
    value Capability;
};

/// Error returned from methods in [`Dict`].
type DictError = flexible enum {
    /// The Dict does not contain an item with the given key.
    NOT_FOUND = 1;

    /// The Dict already contains an item with the given key.
    ALREADY_EXISTS = 2;

    /// The `Capability` handle was invalid.
    BAD_HANDLE = 3;

    /// A capability could not be cloned.
    NOT_CLONEABLE = 4;
};

closed protocol Dict {
    /// Inserts a key-value pair into the dict.
    ///
    /// * error `DictError.ALREADY_EXISTS` if the dict already contains an
    /// item with the same key.
    strict Insert(DictItem) -> () error DictError;

    /// Removes a key from the dict, returning the [`Capability`] value.
    ///
    /// * error `DictError.NOT_FOUND` if the dict does not contain the key.
    strict Remove(struct {
        key DictKey;
    }) -> (resource struct {
        capability Capability;
    }) error DictError;

    /// Returns all items in this dict, sorted by key in natural order. Requires
    /// that all capabilities in the dict are cloneable. This will clone each
    /// capability in the dict and return handles to the cloned capabilities.
    ///
    /// * error `DictError.NOT_CLONEABLE` if any of the capabilities in the dict
    /// could not be cloned.
    strict Read() -> (resource struct {
        items vector<DictItem>:MAX;
    }) error DictError;
};

@discoverable
closed protocol Sender {
    compose fuchsia.io.Openable;
    compose fuchsia.unknown.Cloneable;

    /// Sends a single Capability handle over this sender.
    strict Send(resource struct {
        capability Capability;
    });
};

closed protocol Receiver {
    /// Receives a single Capability handle.
    strict Receive(resource struct {
        capability Capability;
    });
};

/// Entrypoint for instantiation of sandbox types.
@discoverable
open protocol Factory {
    /// Creates a connector (pair of [`Sender`] and [`Receiver`]).
    strict CreateConnector(resource struct {
        sender server_end:Sender;
        receiver client_end:Receiver;
    });

    /// Creates a [`Dict`] initialized with `items`.
    strict CreateDict(resource struct {
        items vector<DictItem>:MAX;
        server_end server_end:Dict;
    }) -> () error DictError;
};