// Copyright 2015 The Vanadium Authors. All rights reserved.
// Use of this source code is governed by a BSD-style
// license that can be found in the LICENSE file.

[JavaPackage="io.v.mojo.discovery"]
module discovery;

// Copied from v.io/v23/discovery/types.vdl
struct Service {
  // The universal unique identifier of a service instance.
  // If this is not specified, a random 128 bit (16 byte) UUID will be used.
  string? InstanceId;
  // Optional name of the service instance.
  string? InstanceName;
  // The interface that the service implements.
  // E.g., 'v.io/v23/services/vtrace.Store'.
  string InterfaceName;
  // The service attributes.
  // E.g., {'resolution': '1024x768'}.
  map<string, string>? Attrs;
  // The addresses that the service is served on.
  // E.g., '/host:port/a/b/c'.
  array<string> Addrs;
  // The service attachments.
  // E.g., {'thumbnail': binary_data }.
  map<string, array<uint8>>? Attachments;
};

enum UpdateType {
  found = 1,
  lost,
};

struct Update {
  Service service;
  UpdateType update_type;
};

struct Error {
  string id;
  int32 action;
  string msg;
};

// Discovery provides Vanadium discovery operations.
[ServiceName="v23::discovery::Discovery"]
interface Discovery {
  // StartAdvertising advertises the service to be discovered by "Scanner"
  // implementations. visibility is used to limit the principals that can see
  // the advertisement. An empty set means that there are no restrictions on
  // visibility (i.e, equivalent to []security.BlessingPattern{security.AllPrincipals}).
  //
  // It is an error to have simultaneously active advertisements for two identical
  // instances (service.InstanceUuid).
  StartAdvertising(Service service, array<string>? visibility) => (string instance_id, Error? err);

  // StopAdvertising stops the advertisement associated with the given instance id.
  StopAdvertising(string instance_id) => (Error? Err);

  // Scan scans for services matching the query passed and calls ScanHandler with updates.
  //
  // The query is a WHERE expression of syncQL query against scanned services, where
  // keys are InstanceUuids and values are Service.
  //
  // Examples
  //
  //    v.InstanceName = "v.io/i"
  //    v.InstanceName = "v.io/i" AND v.Attrs["a"] = "v"
  //    v.Attrs["a"] = "v1" OR v.Attrs["a"] = "v2"
  //
  // SyncQL tutorial at:
  //    https://github.com/vanadium/docs/blob/master/tutorials/syncql-tutorial.md
  StartScan(string query, ScanHandler handler) => (uint32 scan_id, Error? err);

  // StopScan stops the scanning associated with the given scan id.
  StopScan(uint32 scan_id) => (Error? err);
};

// ScanHandler is used to pass updates about services that are found/lost during the scan.
[ServiceName="v23::discovery::ScanHandler"]
interface ScanHandler {
  // Update will be called when a Service is found or lost.
  Update(Update update);
};