v23

package
v0.1.8 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 28, 2020 License: BSD-3-Clause Imports: 14 Imported by: 466

README

Vanadium

This repository defines the Go APIs of Vanadium.

Documentation

Overview

Package v23 defines the runtime interface of Vanadium, and its subdirectories define the entire Vanadium public API.

Once Vanadium reaches version 1.0 these public APIs will be stable over an extended period. Changes to APIs will be managed to ensure backwards compatibility, using the same policy as http://golang.org/doc/go1compat.

This is version 0.1 - we will do our best to maintain backwards compatibility, but there's no guarantee until version 1.0.

For more information about the Vanadium project, please visit https://vanadium.github.io.

Index

Constants

View Source 
const (
	// LocalStop is the message received on AppCycle.WaitForStop when the stop was
	// initiated by the process itself.
	LocalStop = "localstop"
	// RemoteStop is the message received on AppCycle.WaitForStop when the stop was
	// initiated via an RPC call (AppCycle.Stop).
	RemoteStop = "remotestop"
	// Default values for exit codes returned by the process when exiting
	// via the AppCycle component.
	UnhandledStopExitCode = 1
	ForceStopExitCode     = 1
)

Variables

This section is empty.

Functions

func GetBackgroundContext 

func GetBackgroundContext(ctx *context.T) *context.T

GetBackgroundContext returns a background context. This context can be used for general background activities.

func GetClient 

func GetClient(ctx *context.T) rpc.Client

GetClient returns the Client in 'ctx'.

func GetListenSpec 

func GetListenSpec(ctx *context.T) rpc.ListenSpec

GetListenSpec returns the ListenSpec in 'ctx'.

func GetNamespace 

func GetNamespace(ctx *context.T) namespace.T

GetNamespace returns the Namespace in 'ctx'.

func GetPermissionsSpec 

func GetPermissionsSpec(ctx *context.T) access.PermissionsSpec

GetPermissionsSpec returns the Permissions for the specified name in 'ctx'.

func GetPrincipal 

func GetPrincipal(ctx *context.T) security.Principal

GetPrincipal returns the Principal in 'ctx'.

func GetReservedNameDispatcher 

func GetReservedNameDispatcher(ctx *context.T) rpc.Dispatcher

GetReservedNameDispatcher returns the dispatcher used for reserved names.

func NewDiscovery 

func NewDiscovery(ctx *context.T) (discovery.T, error)

NewDiscovery returns a new Discovery.T instance.

func NewFlowManager 

func NewFlowManager(ctx *context.T, channelTimeout time.Duration) (flow.Manager, error)

NewFlowManager creates a new flow.Manager instance. channelTimeout specifies the duration we are willing to wait before determining that connections managed by this FlowManager are unhealthy and should be closed.

func RegisterRuntimeFactory 

func RegisterRuntimeFactory(f RuntimeFactory)

RegisterRuntimeFactory register the specified RuntimeFactory. It must be called before v23.Init; typically it will be called by an init function. It will panic if called more than once.

func WithListenSpec 

func WithListenSpec(ctx *context.T, ls rpc.ListenSpec) *context.T

WithListenSpec attaches a ListenSpec to the returned context.

func WithNewClient 

func WithNewClient(ctx *context.T, opts ...rpc.ClientOpt) (*context.T, rpc.Client, error)

WithNewClient creates a new Client instance and attaches it to a new context.

func WithNewDispatchingServer 

func WithNewDispatchingServer(ctx *context.T, name string, disp rpc.Dispatcher, opts ...rpc.ServerOpt) (*context.T, rpc.Server, error)

WithNewDispatchingServer creates a new flow.Manager instance and attaches it to ctx, and creates a new dispatching server on that flow.Manager.

func WithNewNamespace 

func WithNewNamespace(ctx *context.T, roots ...string) (*context.T, namespace.T, error)

WithNewNamespace creates a new Namespace instance and attaches it to the returned context.

func WithNewServer 

func WithNewServer(ctx *context.T, name string, object interface{}, auth security.Authorizer, opts ...rpc.ServerOpt) (*context.T, rpc.Server, error)

WithNewServer creates a new flow.Manager instance and attaches it to ctx, and creates a new server on that flow.Manager.

func WithPrincipal 

func WithPrincipal(ctx *context.T, principal security.Principal) (*context.T, error)

WithPrincipal attaches 'principal' to the returned context.

func WithReservedNameDispatcher 

func WithReservedNameDispatcher(ctx *context.T, d rpc.Dispatcher) *context.T

WithReservedNameDispatcher returns a context that uses the provided dispatcher to handle reserved names in particular __debug.

Types

type AppCycle 

type AppCycle interface {
	// Stop causes all the channels returned by WaitForStop to return the
	// LocalStop message, to give the application a chance to shut down.
	// Stop does not block.  If any of the channels are not receiving,
	// the message is not sent on them.
	// If WaitForStop had never been called, Stop acts like ForceStop.
	Stop(ctx *context.T)

	// ForceStop causes the application to exit immediately with an error
	// code.
	ForceStop(ctx *context.T)

	// WaitForStop takes in a channel on which a stop event will be
	// conveyed.  The stop event is represented by a string identifying the
	// source of the event.  For example, when Stop is called locally, the
	// LocalStop message will be received on the channel.  If the channel is
	// not being received on, or is full, no message is sent on it.
	//
	// The channel is assumed to remain open while messages could be sent on
	// it.  The channel will be automatically closed during the call to
	// Cleanup.
	WaitForStop(ctx *context.T, ch chan<- string)

	// AdvanceGoal extends the goal value in the shutdown task tracker.
	// Non-positive delta is ignored.
	AdvanceGoal(delta int32)
	// AdvanceProgress advances the progress value in the shutdown task
	// tracker.  Non-positive delta is ignored.
	AdvanceProgress(delta int32)
	// TrackTask registers a channel to receive task updates (a Task will be
	// sent on the channel if either the goal or progress values of the
	// task have changed).  If the channel is not being received on, or is
	// full, no Task is sent on it.
	//
	// The channel is assumed to remain open while Tasks could be sent on
	// it.
	TrackTask(chan<- Task)

	// Remote returns an object to serve the remotely accessible AppCycle
	// interface (as defined in v23/services/appcycle)
	Remote() interface{}
}

AppCycle is the interface for managing the shutdown of a runtime remotely and locally. An appropriate instance of this is provided by the RuntimeFactory to the runtime implementation which in turn arranges to serve it on an appropriate network address.

func GetAppCycle 

func GetAppCycle(ctx *context.T) AppCycle

GetAppCycle returns the AppCycle in 'ctx'.

type Runtime 

type Runtime interface {
	// Init is a chance to initialize state in the runtime implementation
	// after the runtime has been registered in the v23 package.
	// Code that runs in this routine, unlike the code in the Runtime's
	// constructor, can use the v23.Get/With methods.
	Init(ctx *context.T) error

	// WithPrincipal attaches 'principal' to the returned context.
	WithPrincipal(ctx *context.T, principal security.Principal) (*context.T, error)

	// GetPrincipal returns the Principal in 'ctx'.
	GetPrincipal(ctx *context.T) security.Principal

	// WithNewClient creates a new Client instance and attaches it to a
	// new context.
	WithNewClient(ctx *context.T, opts ...rpc.ClientOpt) (*context.T, rpc.Client, error)

	// GetClient returns the Client in 'ctx'.
	GetClient(ctx *context.T) rpc.Client

	// WithNewNamespace creates a new Namespace instance and attaches it to the
	// returned context.
	WithNewNamespace(ctx *context.T, roots ...string) (*context.T, namespace.T, error)

	// GetNamespace returns the Namespace in 'ctx'.
	GetNamespace(ctx *context.T) namespace.T

	// GetAppCycle returns the AppCycle in 'ctx'.
	GetAppCycle(ctx *context.T) AppCycle

	// GetListenSpec returns the ListenSpec in 'ctx'.
	GetListenSpec(ctx *context.T) rpc.ListenSpec

	// WithListenSpec attaches a ListenSpec to the returned context.
	WithListenSpec(ctx *context.T, ls rpc.ListenSpec) *context.T

	// GetPermissionSpec returns the PermissonsSpec stored in 'ctx'.
	GetPermissionsSpec(ctx *context.T) access.PermissionsSpec

	// WithBackgroundContext creates a new context derived from 'ctx'
	// with the given context set as the background context.
	WithBackgroundContext(ctx *context.T) *context.T

	// GetBackgroundContext returns a background context. This context can be used
	// for general background activities.
	GetBackgroundContext(ctx *context.T) *context.T

	// NewDiscovery returns a new Discovery.T instance.
	NewDiscovery(ctx *context.T) (discovery.T, error)

	// WithReservedNameDispatcher returns a context that uses the
	// provided dispatcher to control access to the framework managed
	// portion of the namespace.
	WithReservedNameDispatcher(ctx *context.T, d rpc.Dispatcher) *context.T

	// GetReservedNameDispatcher returns the dispatcher used for
	// reserved names.
	GetReservedNameDispatcher(ctx *context.T) rpc.Dispatcher

	// NewFlowManager creates a new flow.Manager instance.
	// channelTimeout specifies the duration we are willing to wait before determining
	// that connections managed by this FlowManager are unhealthy and should be
	// closed.
	NewFlowManager(ctx *context.T, channelTimeout time.Duration) (flow.Manager, error)

	// WithNewServer creates a new Server instance to serve a service object.
	//
	// The server will listen for network connections as specified by the
	// ListenSpec attached to ctx. Depending on your RuntimeFactory, 'roaming'
	// support may be enabled. In this mode the server will listen for
	// changes in the network configuration using a Stream created on the
	// supplied Publisher and change the set of Endpoints it publishes to
	// the mount table accordingly.
	//
	// The server associates object with name by publishing the address of
	// this server in the namespace under the supplied name and using
	// authorizer to authorize access to it. RPCs invoked on the supplied
	// name will be delivered to methods implemented by the supplied
	// object.  Reflection is used to match requests to the object's
	// method set.  As a special-case, if the object implements the
	// Invoker interface, the Invoker is used to invoke methods directly,
	// without reflection.  If name is an empty string, no attempt will
	// made to publish.
	//
	// WithNewServer will create a new flow.Manager to back the server
	// and return a new context with that flow.Manager attached.  This
	// means that clients who use the returned context will be able to
	// share connections with the server, enabling bidirectional RPC.
	WithNewServer(ctx *context.T, name string, object interface{}, auth security.Authorizer, opts ...rpc.ServerOpt) (*context.T, rpc.Server, error)

	// WithNewDispatchingServer creates a new Server instance to serve a given dispatcher.
	//
	// WithNewDispatchingServer is similar to WithNewServer except it
	// allows users to specify a dispatcher, which provides control over
	// which object and authorizer are used for each method call.  RPCs
	// invoked on the supplied name will be delivered to the supplied
	// Dispatcher's Lookup method which will returns the object and
	// security.Authorizer used to serve the actual RPC call.
	WithNewDispatchingServer(ctx *context.T, name string, disp rpc.Dispatcher, opts ...rpc.ServerOpt) (*context.T, rpc.Server, error)
}

Runtime is the interface that concrete Vanadium implementations must implement. It will not be used directly by application builders. They will instead use the package level functions that mirror these factories.

type RuntimeFactory 

type RuntimeFactory func(ctx *context.T) (Runtime, *context.T, Shutdown, error)

A RuntimeFactory represents the combination of hardware, operating system, compiler and libraries available to the application. The RuntimeFactory creates a runtime implementation with the required hardware, operating system and library specific dependencies included.

The implementations of the RuntimeFactory are intended to capture all of the dependencies implied by that RuntimeFactory. For example, if a RuntimeFactory requires a particular hardware specific library (say Bluetooth support), then the implementation of the RuntimeFactory should include that dependency in the resulting runtime instance; the package implementing the RuntimeFactory should expose the additional APIs needed to use the functionality.

RuntimeFactories range from the generic to the very specific (e.g. "linux" or "my-sprinkler-controller-v2". Applications should, in general, use as generic a RuntimeFactory as possible.

RuntimeFactories are registered using v23.RegisterRuntimeFactory. Packages that implement RuntimeFactories will typically call RegisterRuntimeFactory in their init functions so importing a RuntimeFactory will be sufficient to register it. Only one RuntimeFactory can be registered in any program, and subsequent registrations will panic. Typically a program's main package will be the only place to import a RuntimeFactory.

This scheme allows applications to use a pre-supplied RuntimeFactory as well as for developers to create their own RuntimeFactories (to represent their hardware and software system).

At a minimum a RuntimeFactory must do the following:

  • Initialize a Runtime implementation (providing the flags to it)
  • Return a Runtime implementation, initial context, Shutdown func.

See the v.io/x/ref/runtime/factories package for a complete description of the precanned RuntimeFactories and how to use them.

type Shutdown 

type Shutdown func()

func Init 

func Init() (*context.T, Shutdown)

Init should be called once for each vanadium executable, providing the setup of the vanadium initial context.T and a Shutdown function that can be used to clean up the runtime. We allow calling Init multiple times (useful in tests), but only as long as you call the Shutdown returned previously before calling Init the second time. Init panics if it encounters an error.

func TryInit 

func TryInit() (*context.T, Shutdown, error)

TryInit is like Init, except that it returns an error instead of panicking.

type Task 

type Task struct {
	Progress, Goal int32
}

Task is streamed to channels registered using TrackTask to provide a sense of the progress of the application's shutdown sequence. For a description of the fields, see the Task struct in the v23/services/appcycle package, which it mirrors.

Source Files

View all Source files

Directories

Path Synopsis
Package context implements a mechanism to carry data across API boundaries.
 Package context implements a mechanism to carry data across API boundaries.
Package conventions implements unenforced conventions for Vanadium.
 Package conventions implements unenforced conventions for Vanadium.
Package discovery defines types and interfaces for discovering services.
 Package discovery defines types and interfaces for discovering services.
Package flow defines interfaces for the management of authenticated bidirectional byte Flows.
 Package flow defines interfaces for the management of authenticated bidirectional byte Flows.
message
Package glob defines a globbing syntax and implements matching routines.
 Package glob defines a globbing syntax and implements matching routines.
Package i18n implements internationalization of formatted message strings in different languages.
 Package i18n implements internationalization of formatted message strings in different languages.
Package loging defines an interface for logging modeled on Google's glog.
 Package loging defines an interface for logging modeled on Google's glog.
Package namespace defines an interface for resolving and managing names.
 Package namespace defines an interface for resolving and managing names.
Package naming defines types and utilities associated with naming.
 Package naming defines types and utilities associated with naming.
Package options defines common options recognized by vanadium implementations.
 Package options defines common options recognized by vanadium implementations.
The query packages implement Vanadium's query capabilities.
 The query packages implement Vanadium's query capabilities.
engine
Package engine defines a Create function which returns an instance of datasource.QueryEngine
 Package engine defines a Create function which returns an instance of datasource.QueryEngine
engine/datasource
Package datasource defines the interfaces a system must implement to support querying.
 Package datasource defines the interfaces a system must implement to support querying.
engine/internal
Package internal implements Exec, executing SQL-like queries on a given database.
 Package internal implements Exec, executing SQL-like queries on a given database.
engine/internal/conversions
engine/internal/querychecker
Package querychecker performs a semantic check on an AST produced by the queryparser package.
 Package querychecker performs a semantic check on an AST produced by the queryparser package.
engine/internal/queryfunctions
Package queryfunctions describes SyncQL's built-in functions.
 Package queryfunctions describes SyncQL's built-in functions.
engine/internal/queryparser
Package queryparser is a parser to parse a simplified select statement (a la SQL) for the Vanadium key value store (a.k.a., syncbase).
 Package queryparser is a parser to parse a simplified select statement (a la SQL) for the Vanadium key value store (a.k.a., syncbase).
engine/internal/test
Package query_test contains tests for the query package.
 Package query_test contains tests for the query package.
engine/public
Package public defines the QueryEngine interface which is returned from calling v.io/v23/query/engine.Create and PreparedStatement which is returned from the QueryEngine.PrepareStatement function.
 Package public defines the QueryEngine interface which is returned from calling v.io/v23/query/engine.Create and PreparedStatement which is returned from the QueryEngine.PrepareStatement function.
pattern
Package pattern handles parsing and matching SQL LIKE-style glob patterns.
 Package pattern handles parsing and matching SQL LIKE-style glob patterns.
syncql
The ResultStream interface is used to iterate over query results.
 The ResultStream interface is used to iterate over query results.
rpc
Package rpc defines interfaces for communication via remote procedure call.
 Package rpc defines interfaces for communication via remote procedure call.
reserved
Package reserved implements client-side support for reserved RPC methods implemented by all servers.
 Package reserved implements client-side support for reserved RPC methods implemented by all servers.
version
Package version defines a mechanism for versioning the RPC protocol.
 Package version defines a mechanism for versioning the RPC protocol.
Package security defines types and utilities associated with security.
 Package security defines types and utilities associated with security.
access
Package access defines types and interfaces for dynamic access control.
 Package access defines types and interfaces for dynamic access control.
access/internal
Package internal provides a VDL specification for a service used in the unittest of the access package.
 Package internal provides a VDL specification for a service used in the unittest of the access package.
services
appcycle
Package appcycle defines interfaces for managing application processes.
 Package appcycle defines interfaces for managing application processes.
application
Package application defines types for describing applications.
 Package application defines types for describing applications.
binary
Package binary defines types for describing executable binaries.
 Package binary defines types for describing executable binaries.
build
Package build defines interfaces for building executable binaries.
 Package build defines interfaces for building executable binaries.
device
Package device defines interfaces for managing devices and their applications.
 Package device defines interfaces for managing devices and their applications.
groups
Package groups defines interfaces for managing access control groups.
 Package groups defines interfaces for managing access control groups.
http
Package HTTP defines an interface to send a http.Request from a client to a Vanadium server.
 Package HTTP defines an interface to send a http.Request from a client to a Vanadium server.
logreader
Package logreader defines interfaces for reading log files remotely.
 Package logreader defines interfaces for reading log files remotely.
mounttable
Package mounttable defines interfaces for managing associations between names and servers.
 Package mounttable defines interfaces for managing associations between names and servers.
permissions
Package permissions defines an interface for managing access control permissions.
 Package permissions defines an interface for managing access control permissions.
pprof
Package pprof defines an interface for accessing runtime profiling data in the format expected by the pprof visualization tool.
 Package pprof defines an interface for accessing runtime profiling data in the format expected by the pprof visualization tool.
repository
Package repository defines interfaces for storing and retrieving device, application and binary management related information.
 Package repository defines interfaces for storing and retrieving device, application and binary management related information.
stats
Package stats defines an interface to access statistical information for troubleshooting and monitoring purposes.
 Package stats defines an interface to access statistical information for troubleshooting and monitoring purposes.
tidyable
Package tidyable defines an interface for services that can be requested to clean up transient resource use (such as logs or caches.)
 Package tidyable defines an interface for services that can be requested to clean up transient resource use (such as logs or caches.)
vtrace
Package vtrace defines an interface to access v.io/v23/vtrace traces, to help analyze and debug distributed systems.
 Package vtrace defines an interface to access v.io/v23/vtrace traces, to help analyze and debug distributed systems.
watch
Package watch defines interfaces for watching a sequence of changes.
 Package watch defines interfaces for watching a sequence of changes.
Package uniqueid defines functions that are likely to generate globally unique identifiers.
 Package uniqueid defines functions that are likely to generate globally unique identifiers.
vdl
Package vdl implements the Vanadium Definition Language type and value system.
 Package vdl implements the Vanadium Definition Language type and value system.
vdltest
Package vdltest provides a variety of VDL types and values for testing.
 Package vdltest provides a variety of VDL types and values for testing.
vdltest/internal/vdltestgen
Command vdltestgen generates types and values for the vdltest package.
 Command vdltestgen generates types and values for the vdltest package.
Package vdlroot defines the standard VDL packages; the VDLROOT environment variable should point at this directory.
 Package vdlroot defines the standard VDL packages; the VDLROOT environment variable should point at this directory.
math
signature
Package signature defines types representing interface and method signatures.
 Package signature defines types representing interface and method signatures.
time
Package time defines standard representations of absolute and relative times.
 Package time defines standard representations of absolute and relative times.
vdltool
Package vdltool defines types used by the vdl tool itself, including the format of vdl.config files.
 Package vdltool defines types used by the vdl tool itself, including the format of vdl.config files.
Package verror implements an error reporting mechanism that works across programming environments, and a set of common errors.
 Package verror implements an error reporting mechanism that works across programming environments, and a set of common errors.
vom
Package vom implements the Vanadium Object Marshaling serialization format.
 Package vom implements the Vanadium Object Marshaling serialization format.
internal
internal/vombenchgen
vomtest
Package vomtest provides protocol conformance tests for the Vanadium Object Marshaller (VOM).
 Package vomtest provides protocol conformance tests for the Vanadium Object Marshaller (VOM).
vomtest/internal/vomforever
Command vomforever is a tool that searches for bugs in vom.
 Command vomforever is a tool that searches for bugs in vom.
vomtest/internal/vomtestgen
Command vomtestgen generates test cases for the vomtest package.
 Command vomtestgen generates test cases for the vomtest package.
Package vtrace defines a system for collecting debugging information about operations that span a distributed system.
 Package vtrace defines a system for collecting debugging information about operations that span a distributed system.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.