// Copyright 2018 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.overnet;

// Overnet forms a mesh network of peer devices which can proxy some Zircon objects between
// said devices.

using fuchsia.overnet.protocol;
using zx;

/// Interfaces applicable to consuming services from other devices
[Discoverable]
protocol ServiceConsumer {
    /// Returns a list of all peers that are connected to this Overnet.
    /// If this list has not been updated since the last call to this method, it waits until
    /// new data is available.
    /// Concurrent calls to ListPeers will result in channel closure.
    ListPeers() -> (vector<Peer>:MAX peers);
    /// Connect `chan` to some external service on `node` with name `service_name`.
    ConnectToService(fuchsia.overnet.protocol.NodeId node,
                     string:fuchsia.overnet.protocol.MAX_SERVICE_NAME_LENGTH service_name,
                     zx.handle:CHANNEL chan);
};

/// Interfaces applicable to sharing services with ServiceConsumer's
[Discoverable]
protocol ServicePublisher {
    /// Register a new service to be exported by Overnet.
    /// If an existing service has the same `service_name`, it's replaced by this service.
    PublishService(string:fuchsia.overnet.protocol.MAX_SERVICE_NAME_LENGTH service_name,
                   ServiceProvider provider);
};

/// Interfaces applicable to controlling an Overnet mesh
[Discoverable]
protocol MeshController {
    /// Attach a socket as a new link.
    AttachSocketLink(zx.handle:SOCKET socket);
};

/// A ServiceProvider is a factory for one service.
protocol ServiceProvider {
    /// Connect `chan` to the service (called in response to Overnet.ConnectToService).
    /// `info` provides additional data about the connection request.
    ConnectToService(zx.handle:CHANNEL chan, ConnectionInfo info);
};

/// Protocol spoken by the host implementation to access various sub-interfaces.
protocol HostOvernet {
    ConnectServiceConsumer(request<ServiceConsumer> svc);
    ConnectServicePublisher(request<ServicePublisher> svc);
    ConnectMeshController(request<MeshController> svc);
};

/// A `Peer` describes one device on the Overnet mesh.
struct Peer {
    /// The address of the peer on the Overnet mesh.
    fuchsia.overnet.protocol.NodeId id;
    /// A special peer is returned for this device, and is marked with `is_self` true.
    bool is_self;
    /// A description of the peer (includes, for example, a service list).
    fuchsia.overnet.protocol.PeerDescription description;
};

/// Information provided to a ServiceProvider about an incoming connection.
table ConnectionInfo {
    /// The peer address initiating this connection.
    1: fuchsia.overnet.protocol.NodeId peer;
};