blob: 12f60bd4085c5a01d1faa83f45008db57bb12bd5 [file] [log] [blame]
// 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);
};