| // 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. |
| // |
| // TODO(jhahn): This is a work in progress and can change without notice. |
| 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 { |
| Advertiser |
| Scanner |
| Closer |
| } |
| |
| // Advertiser is the interface for advertising services. |
| type Advertiser interface { |
| // 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}). Advertising will continue |
| // until the context is canceled or exceeds its deadline and the returned channel |
| // will be closed when it stops. |
| // |
| // If service.InstanceId is not specified, a random 128 bit (16 byte) UUID will be |
| // assigned to it. Any change to service will not be applied after advertising starts. |
| // |
| // It is an error to have simultaneously active advertisements for two identical |
| // instances (service.InstanceId). |
| Advertise(ctx *context.T, service *Service, visibility []security.BlessingPattern) (<-chan struct{}, error) |
| } |
| |
| // AdvertiseCloser is the interface that groups the Advertise and Close methods. |
| type AdvertiseCloser interface { |
| Advertiser |
| Closer |
| } |
| |
| // Scanner is the interface for scanning services. |
| type Scanner interface { |
| // Scan scans services that match the query and returns the channel on which |
| // new discovered services can be read. Scanning will continue until the context |
| // is canceled or exceeds its deadline. |
| // |
| // The query is a WHERE expression of syncQL query against scanned services, where |
| // keys are InstanceIds and values are Services. |
| // |
| // Examples |
| // |
| // v.InterfaceName = "v.io/i" |
| // v.InterfaceName = "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(ctx *context.T, query string) (<-chan Update, error) |
| } |
| |
| // ScanCloser is the interface that groups the Scan and Close methods. |
| type ScanCloser interface { |
| Scanner |
| Closer |
| } |
| |
| // Closer is the interface that wraps the Close method. |
| type Closer interface { |
| // Close closes all active tasks. |
| Close() |
| } |