// 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.

/// This file contains the definition of Link as well as the structure
/// of the data it holds.

library fuchsia.modular;

using fuchsia.mem;

/// This interface is implemented by the story runner. The ModuleContext service
/// acts as a factory for it.
///
/// An instance of Link holds one of two types of values:
///
/// (1) A JSON string that can be modified incrementally or completely
///     overwritten, depending on the use of Set() and Update(). The JSON string
///     is set to "null" when the Link is created.
///
/// (2) An entity reference that can be set or retrieved with SetEntity() and
///     GetEntity().
///
/// Each Module instance receives one Link instance for each parameter of its
/// action template in its ModuleContext. It receives its ModuleContext in
/// Module.Initialize() or in its service namespace. The Module can access its
/// Links by calling ModuleContext.GetLink() with the intent parameter name as
/// the link name. These instances are shared with the parent Module if there is
/// any, or with the StoryController client if the Module is a top level Module
/// of a Story. A Module can create additional Link instances by calling
/// ModuleContext.GetLink() with any other link name. Why would it do that? To
/// share the new Link instance with Modules it requests to start in turn, or to
/// record its own state in the story record, so that it is transferred to other
/// devices that run the same story, or to persist it for later resumption of the
/// story.
///
/// A client may obtain another handle to the same Link instance by calling
/// GetLink() with the same name again.
///
/// A client of Link can set the JSON string stored in the instance and register
/// a handler (an implementation of the LinkWatcher interface) to be notified of
/// changes to the JSON string in the Link. A client may or may not be notified
/// of changes it itself makes to the Link value, depending on whether it
/// registers with WatchAll() or Watch(), respectively. If the client registers
/// with Watch(), then it will not be notified of changes made through the same
/// Link connection.
///
/// No service name: returned from ModuleContext.GetLink().
protocol Link {
    /// Gets the value at the given `path`, which is represented using the JSON
    /// Pointer specification (https://tools.ietf.org/html/rfc6901).
    ///
    /// `json_data` is a UTF8 encoded string representing valid JSON.
    ///
    /// Returns null if `path` does not exist. Returns the entire JSON object
    /// if `path` is either null or an empty array. Returns the string "null" if
    /// the link is empty.
    Get(vector<string>? path) -> (fuchsia.mem.Buffer? json_data);

    /// Set() overwrites the value/object/array at the given `path`. Set also
    /// overwrites any values or arrays as necessary to ensure that `path` exists.
    /// The `json_data` parameter must be a UTF8 encoded JSON string.
    /// Either pass "null" to set the value to null, or use Erase to
    /// completely remove a member of an object. To replace the root, pass null for
    /// `path`.
    ///
    /// This call notifies Watchers, although this may be skipped if nothing
    /// changed.
    Set(vector<string>? path, fuchsia.mem.Buffer json_data);

    /// Erases the object member at the given `path`. If the path is not found or
    /// does not match the current structure of the JSON, the path will not be
    /// created and the call is ignored. The `path` parameter cannot be null or
    /// zero length because the root is a value, not a key. This call notifies
    /// Watchers, although this may be skipped if nothing changed.
    Erase(vector<string> path);

    /// Returns the entity reference in this link. If no entity reference is
    /// present, returns a null fidl string.
    GetEntity() -> (string? entity_reference);

    /// Sets this to be an Entity Link with the given `entity_reference`. The
    /// existing value of the link is overwritten. If `entity_reference` is null,
    /// then any existing value in the link is overwritten with the JSON string
    /// "null".
    SetEntity(string? entity_reference);

    /// Registers a watcher, which is notified whenever the document changes. This
    /// watcher will not be invoked for changes caused by calls made on this
    /// handle. The Notify() callback method will be immediately invoked with the
    /// value in the Link, even if it's empty.
    ///
    /// The LinkWatcher connection will be closed if the owning Link handle closed.

    /// All connections to a Link and LinkWatcher are closed once the story the
    /// link belongs to is stopped.
    Watch(LinkWatcher watcher);

    /// Like Watch(), but the watcher is notified also of changes made through the
    /// same handle as the watcher is registered on.
    WatchAll(LinkWatcher watcher);

    /// Waits for the completion of methods previously invoked on the same
    /// connection. Allows to create sequentiality across service instances without
    /// giving every method an empty return value. Nb. this makes no guarantees
    /// about sequentiality with methods invoked on different connections, even to
    /// the same Link instance.
    Sync() -> ();
};

/// This interface is implemented by a client of Link.
///
/// The Notify() method is invoked whenever the Link changes. The entire JSON
/// string in the Link will be sent. In other words, this isn't an incremental
/// notification. `json` cannot be null because an empty Link is the valid JSON
/// document "null".
///
/// No service name: created by Module.
protocol LinkWatcher {
    Notify(fuchsia.mem.Buffer json);
};