blob: 5f7a3b9515f06b4dcb1363b1efc5c8ebcdcb1279 [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.
// Package discovery defines types and interfaces for discovering services.
package discovery
import (
"v.io/v23/context"
"v.io/v23/security"
)
// T is the interface for discovery operations; it is the client side library
// for the discovery service.
type T interface {
// Advertise 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 context is canceled or exceeds its deadline
// and the returned channel will be closed when it stops.
Advertise(ctx *context.T, ad *Advertisement, visibility []security.BlessingPattern) (<-chan struct{}, error)
// Scan scans advertisements that match the query and returns the channel of 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 context is canceled or exceeds its deadline.
Scan(ctx *context.T, query string) (<-chan Update, error)
}