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

// Exposes access to Context values, each of which are explicitly named by a
// 'topic'. Each topic has a known/pre-defined value representation.
//
// This interface is meant to be used in the scope of a single Fuchsia
// component.
[Discoverable]
protocol ContextReader {
    // When any conditions that would cause the resulting set of context values
    // selected by |query| to change, a ContextUpdate is sent to |listener|.
    //
    // The current state of values selected by |query| are sent to |listener|
    // immediately.
    //
    // The subscription will continue to stay active as long as the |listener|
    // handle is not closed.
    Subscribe(ContextQuery query, ContextListener listener);

    // Returns the current context state matching |query|.
    Get(ContextQuery query) -> (ContextUpdate update);
};

struct ContextQuery {
    // A map of ContextSelector structs. The keys are specified by the client.
    // Each key gets a corresponding entry in |ContextUpdate.values| when it is
    // generated in response to this query.
    vector<ContextQueryEntry> selector;
};

struct ContextQueryEntry {
    string key;
    ContextSelector value;
};

struct ContextSelector {
    // A partial metadata struct. Any metadata value given in |meta| restricts
    // the set of values in the eventual ContextUpdate to include only those
    // whose metadata match values given.
    //
    // A null |meta| will match any value of the given |type|. Use this sparingly
    // as a full update could become quite large.
    // TODO(thatguy): Find users of this and eliminate them if it becomes a
    // scaling problem.
    //
    // For example, to select all context values in a given story, one would
    // specify:
    //    meta.value["story"]["id"] = "..."
    ContextMetadata? meta;

    // A string specifying the type of context object to return.
    ContextValueType type;
};

protocol ContextListener {
    // Receives a full snapshot of context state every time context is updated
    // in such a way that results in a changed set of values for the ContextQuery
    // used in the subscription for this listener.
    //
    // TODO(thatguy): A broad ContextQuery will result in a large
    // |ContextUpdate|, which may exceed the FIDL max message size. In this case
    // updates would not be propagated. If this becomes an issue, allowing
    // clients to opt for delta-updates instead of state snapshots would suffice,
    // albeit also add some complexity to client implementations.
    OnContextUpdate(ContextUpdate update);
};

struct ContextUpdate {
    // A list of ContextValue for each key in |ContextQuery.selector|. An empty
    // list means no values matched the given ContextSelector.
    vector<ContextUpdateEntry> values;
};

struct ContextUpdateEntry {
    string key;
    vector<ContextValue> value;
};