blob: 3f2e34631d94c411dcfd1b7b3c2eb799cb456383 [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 options defines common options recognized by vanadium implementations.
//
// Below are the common options required of all vanadium implementations. Let's
// say we have functions MyFuncA and MyFuncB in package demo:
//
// package demo
// func MyFuncA(a, b, c int, opts ...MyFuncAOpt)
// func MyFuncB(opts ...MyFuncBOpt)
//
// type MyFuncAOpt interface {
// DemoMyFuncAOpt()
// }
// type MyFuncBOpt interface {
// DemoMyFuncBOpt()
// }
//
// The MyFuncAOpt interface is used solely to constrain the types of options
// that MyFuncA accepts, and ditto for MyFuncBOpt and MyFuncB. In order to
// enable an option to be accepted by a particular function, you simply add a
// no-op function definition with the appropriate name. An example:
//
// type Foo int
// func (Foo) DemoMyFuncAOpt() {}
// func (Foo) DemoMyFuncBOpt() {}
//
// type Bar string
// func (Bar) DemoMyFuncBOpt() {}
//
// Foo is accepted by both demo.MyFuncA and demo.MyFuncB, while Bar is only
// accepted by demo.MyFuncB. The methods defined for each option essentially
// act as annotations telling us which functions will accept them.
//
// Go stipulates that methods may only be attached to named types, and the type
// may not be an interface. E.g.
//
// // BAD: can't attach methods to named interfaces.
// type Bad interface{}
// func (Bad) DemoMyFuncAOpt() {}
//
// // GOOD: wrap the interface in a named struct.
// type Good struct { val interface{} }
//
// func (Good) DemoMyFuncAOpt() {}
//
// These options can then be passed to the function as so:
// MyFuncA(a, b, c, Foo(1), Good{object})
package options
import (
"time"
"v.io/v23/naming"
"v.io/v23/security"
)
// ServerPeers is the set of peers to whom a process (a "server") accepting
// network connections must reveal its blessings.
//
// If this option is not provided, then the server's blessings will be revealed
// to all processes (clients) from whom the server accepts network connections.
//
// NOTE: This is an experimental option and may go away at any time.
type ServerPeers []security.BlessingPattern
func (ServerPeers) RPCServerOpt() {}
// ServerAuthorizer encapsulates the authorization policy used by a client to
// authorize the end server of an RPC.
//
// This policy is applied before the client sends information about itself
// (public key, blessings, the RPC request) to the server. Thus, if a server
// does not satisfy this policy then the client will abort the request.
//
// Authorization of other servers communicated with in the process of
// contacting the end server are controlled by other options, like
// NameResolutionAuthorizer.
//
// Runtime implementations are expected to use security.EndpointAuthorizer
// if no explicit ServerAuthorizer has been provided for the call.
type ServerAuthorizer struct{ security.Authorizer }
func (ServerAuthorizer) RPCCallOpt() {}
// NameResolutionAuthorizer encapsulates the authorization policy used by a
// client to authorize mounttable servers before sending them a name resolution
// request. By specifying this policy, clients avoid revealing the names they
// are interested in resolving to unauthorized mounttables.
//
// If no such option is provided, then runtime implementations are expected to
// default to security.EndpointAuthorizer.
type NameResolutionAuthorizer struct{ security.Authorizer }
func (NameResolutionAuthorizer) RPCCallOpt() {}
func (NameResolutionAuthorizer) NSOpt() {}
// Preresolved specifies that the RPC call should not further Resolve the name.
// If a MountEntry is provided, use it. Otherwise use the name passed in the
// RPC call. If the name is relative, it will be made global using
// the roots in the namespace.
type Preresolved struct {
Resolution *naming.MountEntry
}
func (Preresolved) RPCCallOpt() {}
func (Preresolved) NSOpt() {}
// Create a server that will be used to serve a MountTable. This server
// cannot be used for any other purpose.
type ServesMountTable bool
func (ServesMountTable) RPCServerOpt() {}
// LameDuckTimeout specifies the time to wait for all server operations to complete after Stop is called.
type LameDuckTimeout time.Duration
func (LameDuckTimeout) RPCServerOpt() {}
// Create a server that will be used to serve a leaf service.
type IsLeaf bool
func (IsLeaf) RPCServerOpt() {}
// When NoRetry is specified, the client will not retry calls that fail but would
// normally be retried.
type NoRetry struct{}
func (NoRetry) NSOpt() {}
func (NoRetry) RPCCallOpt() {}
// ChannelTimeout is the amount of time before we notice that a channel is
// not responsive and close it. Note that ChannelTimeout(0) is the same as
// not setting a timeout.
type ChannelTimeout time.Duration
func (ChannelTimeout) RPCCallOpt() {}
func (ChannelTimeout) RPCServerOpt() {}
// ConnectionTimeout is the amount of time we will try establishing a connection
// to the remote end during an RPC. Zero means only use cached connections and
// do not attempt to retry if no connection exists in the cache.
type ConnectionTimeout time.Duration
func (ConnectionTimeout) RPCCallOpt() {}