// 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 the wire interfaces for discovering services.
package discovery

import (
	"v.io/v23/discovery"
	"v.io/v23/security"
	"v.io/v23/security/access"
)

// Used to unregister a service.
type ServiceHandle uint32

// Discovery is the interface for discovery operations.
type Discovery interface {
	Advertiser
	Scanner
}

// Advertiser is the interface for advertising services.
type Advertiser interface {
	// RegisterService registers a service to be discovered by "Scanner" implementations
	// and returns a handle to the advertisement and instance id of the service.
	//
	// 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}).
	RegisterService(service discovery.Service, visibility []security.BlessingPattern) (handle ServiceHandle, instanceId string | error) {access.Write}

	// UnregisterService unregisters a registered service from advertising.
	UnregisterService(handle ServiceHandle) error {access.Write}
}

// Scanner is the interface for scanning services.
type Scanner interface {
	// Scan scans services that match the query and returns the stream of discovered
	// services. Scanning will continue until the client cancels the call.
	//
  // 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(query string) stream<_, discovery.Update> error {access.Read}
}