blob: 5a5c89a5076dc123e3a792397fc5094e9418dce2 [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.
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;
};
struct Error {
string id;
int32 action;
string msg;
};
// Advertiser provides methods to do Vanadium Advertising.
interface Advertiser {
// Advertise 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).
Advertise(Service service, array<string>? visibility) => (uint32 Handle, string instanceId, Error? Err);
// Stop Stops the advertisement associated with the given handle.
Stop(uint32 h) => (Error? Err);
};
// Scanner provides methods to scan for Vanadium advertisements.
interface Scanner {
// 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
Scan(string query, ScanHandler scanHandler) => (uint32 Handle, Error? Err);
// StopScan stops the scanner associated weith the given handle.
Stop(uint32 h) => (Error? Err);
};
// ScanHandler is used to pass updates about Services that are found/lost during
// the scan.
interface ScanHandler {
// Found will be called when a Service is found.
Found(Service service);
// Lost will be called when a service is lost.
Lost(string instanceId);
};