mojom/v.io/discovery.mojom

// 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
//
// Advertisement represents a feed into advertiser to broadcast its contents
// to scanners.
//
// A large advertisement may require additional RPC calls causing delay in
// discovery. We limit the maximum size of an advertisement to 512 bytes
// excluding id and attachments.
struct Advertisement {
  const int32 ID_LEN = 16;

  // Universal unique identifier of the advertisement.
  // If this is not specified, a random unique identifier will be assigned.
  array<uint8, 16>? id;

  // Interface name that the advertised service implements.
  // E.g., 'v.io/v23/services/vtrace.Store'.
  string interface_name;

  // Addresses (vanadium object names) that the advertised service is served on.
  // E.g., '/host:port/a/b/c', '/ns.dev.v.io:8101/blah/blah'.
  array<string> addresses;

  // Attributes as a key/value pair.
  // E.g., {'resolution': '1024x768'}.
  //
  // The key must be US-ASCII printable characters, excluding the '=' character
  // and should not start with '_' character.
  map<string, string>? attributes;

  // Attachments as a key/value pair.
  // E.g., {'thumbnail': binary_data }.
  //
  // Unlike attributes, attachments are for binary data and they are not queryable.
  // We limit the maximum size of a single attachment to 4K bytes.
  //
  // The key must be US-ASCII printable characters, excluding the '=' character
  // and should not start with '_' character.
  map<string, array<uint8>>? attachments;
};

// Error wraps verror.
struct Error {
  string id;  // empty string means no error
  uint32 action_code;
  string msg;
};

// Url query parameters for global discovery service.
const string QUERY_GLOBAL = "global";
const string QUERY_MOUNT_TTL = "mount_ttl";
const string QUERY_SCAN_INTERVAL = "scan_interval";

// Discovery provides Vanadium discovery service.
//
// Global discovery:
//   You can connect to a global discovery service that uses the Vanadium namespace
//   under |path| by passing a query string "global=<path>". Optionally you can
//   set |mount_ttl| (default is 120s) and |scan_interval| (default is 90s) with
//   query strings "mount_ttl=<mount_ttl>" and "scan_interval=<scan_interval>".
//   A duration string is a sequence of decimal numbers, each with a unit suffix,
//   such as "90s" or "1m30s". Valid time units are "s", "m", and "h".
//
//   Global discovery is an experimental work to see its feasibility and set the
//   long-term goal, and can be changed without notice.
[ServiceName="v23::discovery::Discovery"]
interface Discovery {
  // Broadcasts the advertisement to be discovered by |Scan| operations.
  //
  // |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}).
  //
  // If the advertisement id is not specified, a random unique a random unique identifier
  // will be assigned. The advertisement should not be changed while it is being advertised.
  //
  // It is an error to have simultaneously active advertisements for two identical
  // instances (Advertisement.id).
  //
  // Advertising will continue until the returned |closer| is closed.
  Advertise(Advertisement ad, array<string>? visibility) => (array<uint8, 16>? instance_id, Closer? closer, Error? err);

  // Scans advertisements that match the |query| and calls the |handler| with updates.
  //
  // Scan excludes the advertisements that are advertised from the same discovery
  // instance.
  //
  // The |query| is a WHERE expression of a syncQL query against advertisements, where
  // key is Advertisement.id and value is Advertisement.
  //
  // Examples
  //
  //    v.InterfaceName = "v.io/i"
  //    v.InterfaceName = "v.io/i" AND v.Attributes["a"] = "v"
  //    v.Attributes["a"] = "v1" OR v.Attributes["a"] = "v2"
  //
  // SyncQL tutorial at:
  //    https://vanadium.github.io/tutorials/syncbase/syncql-tutorial.html
  //
  // Scanning will continue until the returned |closer| is closed.
  Scan(string query, ScanHandler handler) => (Closer? closer, Error? err);
};

// Closer wraps the Close method.
interface Closer {
  Close() => ();
};

// ScanHandler is used to pass advertisements that are found/lost during the scan.
interface ScanHandler {
  // Called with each discovery update.
  OnUpdate(Update update);
};

// Update is the interface for a discovery update.
interface Update {
  // Returns true when this update corresponds to an advertisement
  // that led to a previous update vanishing.
  IsLost() => (bool lost);

  // Returns the universal unique identifier of the advertisement.
  GetId() => (array<uint8, 16> id);

  // Returns the interface name that the service implements.
  GetInterfaceName() => (string interface_name);

  // Returns the addresses (vanadium object names) that the service
  // is served on.
  GetAddresses() => (array<string> addresses);

  // Returns the named attribute. An empty string is returned if
  // not found.
  GetAttribute(string name) => (string attribute);

  // Returns the channel on which the named attachment can be read.
  // A zero-length data is returned if not found.
  //
  // This may do RPC calls if the attachment is not fetched yet.
  //
  // Attachments may not be available when this update is for lost advertisement.
  GetAttachment(string name) => (handle<data_pipe_consumer> data);

  // Returns the advertisement that this update corresponds to.
  //
  // The returned advertisement may not include all attachments.
  GetAdvertisement() => (Advertisement ad);
};