runtimevar

package
v0.28.0 Latest Latest
Warning

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

 Go to latest Published: Jan 9, 2023 License: Apache-2.0 Imports: 20 Imported by: 81

Documentation

Overview

Package runtimevar provides an easy and portable way to watch runtime configuration variables. Subpackages contain driver implementations of runtimevar for supported services.

See https://gocloud.dev/howto/runtimevar/ for a detailed how-to guide.

OpenCensus Integration

OpenCensus supports tracing and metric collection for multiple languages and backend providers. See https://opencensus.io.

This API collects an OpenCensus metric "gocloud.dev/runtimevar/value_changes", a count of the number of times all variables have changed values, by driver.

To enable metric collection in your application, see "Exporting stats" at https://opencensus.io/quickstart/go/metrics.

Example (JsonDecoder) 
package main

import (
	"context"
	"fmt"
	"log"

	"gocloud.dev/runtimevar"
	"gocloud.dev/runtimevar/constantvar"

	_ "gocloud.dev/runtimevar/gcpruntimeconfig"
)

func main() {
	// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
	// PRAGMA: On gocloud.dev, hide lines until the next blank line.
	ctx := context.Background()

	// Config is the sample config struct we're going to parse our JSON into.
	type Config struct {
		Host string
		Port int
	}

	// A sample JSON config that will decode into Config.
	const jsonConfig = `{"Host": "gocloud.dev", "Port": 8080}`

	// Construct a Decoder that decodes raw bytes into our config.
	decoder := runtimevar.NewDecoder(Config{}, runtimevar.JSONDecode)

	// Next, a construct a *Variable using a constructor or URL opener.
	// This example uses constantvar.
	// If you're using a URL opener, you can't decode JSON into a struct, but
	// you can use the query parameter "decoder=jsonmap" to decode into a map.
	v := constantvar.NewBytes([]byte(jsonConfig), decoder)
	defer v.Close()
	// snapshot.Value will be of type Config.

	// PRAGMA: On gocloud.dev, hide the rest of the function.
	snapshot, err := v.Latest(ctx)
	if err != nil {
		log.Fatalf("Error in retrieving variable: %v", err)
	}
	fmt.Printf("Config: %+v\n", snapshot.Value.(Config))

}

Output:

Config: {Host:gocloud.dev Port:8080}
Example (OpenVariableFromURL) 
package main

import (
	"context"
	"fmt"
	"log"

	"gocloud.dev/runtimevar"
	_ "gocloud.dev/runtimevar/constantvar"
)

func main() {
	// Connect to a Variable using a URL.
	// This example uses "constantvar", an in-memory implementation.
	// We need to add a blank import line to register the constantvar driver's
	// URLOpener, which implements runtimevar.VariableURLOpener:
	// import _ "gocloud.dev/runtimevar/constantvar"
	// constantvar registers for the "constant" scheme.
	// All runtimevar.OpenVariable URLs also work with "runtimevar+" or "runtimevar+variable+" prefixes,
	// e.g., "runtimevar+constant://..." or "runtimevar+variable+constant://...".
	ctx := context.Background()
	v, err := runtimevar.OpenVariable(ctx, "constant://?val=hello+world&decoder=string")
	if err != nil {
		log.Fatal(err)
	}
	defer v.Close()

	// Now we can use the Variable as normal.
	snapshot, err := v.Latest(ctx)
	if err != nil {
		log.Fatal(err)
	}
	// It's safe to cast the Value to string since we used the string decoder.
	fmt.Printf("%s\n", snapshot.Value.(string))

}

Output:

hello world
Example (StringDecoder) 
package main

import (
	"context"
	"fmt"
	"log"

	"gocloud.dev/runtimevar"
	"gocloud.dev/runtimevar/constantvar"

	_ "gocloud.dev/runtimevar/gcpruntimeconfig"
)

func main() {
	// Construct a *Variable using a constructor from one of the
	// runtimevar subpackages. This example uses constantvar.
	// The variable value is of type string, so we use StringDecoder.
	v := constantvar.NewBytes([]byte("hello world"), runtimevar.StringDecoder)
	defer v.Close()

	// Call Latest to retrieve the value.
	snapshot, err := v.Latest(context.Background())
	if err != nil {
		log.Fatalf("Error in retrieving variable: %v", err)
	}
	// snapshot.Value will be of type string.
	fmt.Printf("%q\n", snapshot.Value.(string))

}

Output:

"hello world"

Index

Examples

Constants

This section is empty.

Variables

View Source 
var (
	// StringDecoder decodes into strings.
	StringDecoder = NewDecoder("", StringDecode)

	// BytesDecoder copies the slice of bytes.
	BytesDecoder = NewDecoder([]byte{}, BytesDecode)
)
View Source 
var ErrClosed = gcerr.Newf(gcerr.FailedPrecondition, nil, "Variable has been Closed")

ErrClosed is returned from Watch when the Variable has been Closed.

View Source 
var New = newVar

New is intended for use by drivers only. Do not use in application code.

View Source 
var (

	// OpenCensusViews are predefined views for OpenCensus metrics.
	OpenCensusViews = []*view.View{
		{
			Name:        pkgName + "/value_changes",
			Measure:     changeMeasure,
			Description: "Count of variable value changes by driver.",
			TagKeys:     []tag.Key{oc.ProviderKey},
			Aggregation: view.Count(),
		},
	}
)

Functions

func BytesDecode added in v0.12.0 

func BytesDecode(ctx context.Context, b []byte, obj interface{}) error

BytesDecode copies the slice of bytes b into obj.

func GobDecode 

func GobDecode(ctx context.Context, data []byte, obj interface{}) error

GobDecode can be passed to NewDecoder when decoding gobs (https://golang.org/pkg/encoding/gob/).

func JSONDecode 

func JSONDecode(ctx context.Context, data []byte, obj interface{}) error

JSONDecode can be passed to NewDecoder when decoding JSON (https://golang.org/pkg/encoding/json/).

func StringDecode added in v0.12.0 

func StringDecode(ctx context.Context, b []byte, obj interface{}) error

StringDecode decodes raw bytes b into a string.

Types

type Decode 

type Decode func(context.Context, []byte, interface{}) error

Decode is a function type for unmarshaling/decoding a slice of bytes into an arbitrary type. Decode functions are used when creating a Decoder via NewDecoder. This package provides common Decode functions including GobDecode and JSONDecode.

func DecryptDecode added in v0.12.0 

func DecryptDecode(k *secrets.Keeper, post Decode) Decode

DecryptDecode returns a decode function that can be passed to NewDecoder when decoding an encrypted message (https://godoc.org/gocloud.dev/secrets).

post defaults to BytesDecode. An optional decoder can be passed in to do further decode operation based on the decrypted message.

Example 
package main

import (
	"gocloud.dev/runtimevar"
	"gocloud.dev/secrets"

	_ "gocloud.dev/runtimevar/gcpruntimeconfig"
)

func main() {
	// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
	// PRAGMA: On gocloud.dev, hide lines until the next blank line.
	var keeper *secrets.Keeper

	decodeFunc := runtimevar.DecryptDecode(keeper, runtimevar.StringDecode)
	decoder := runtimevar.NewDecoder("", decodeFunc)

	// PRAGMA: On gocloud.dev, hide the rest of the function.
	_ = decoder
}

Output:

type Decoder 

type Decoder struct {
	// contains filtered or unexported fields
}

Decoder decodes a slice of bytes into a particular Go object.

This package provides some common Decoders that you can use directly, including StringDecoder and BytesDecoder. You can also NewDecoder to construct other Decoders.

func DecoderByName added in v0.12.0 

func DecoderByName(ctx context.Context, decoderName string, dflt *Decoder) (*Decoder, error)

DecoderByName returns a *Decoder based on decoderName.

It is intended to be used by URL openers in driver packages.

Supported values include:

  • empty string: Returns the default from the URLOpener.Decoder, or BytesDecoder if URLOpener.Decoder is nil (which is true if you're using the default URLOpener).
  • "bytes": Returns a BytesDecoder; Snapshot.Value will be of type []byte.
  • "jsonmap": Returns a JSON decoder for a map[string]interface{}; Snapshot.Value will be of type *map[string]interface{}.
  • "string": Returns StringDecoder; Snapshot.Value will be of type string.

It also supports using "decrypt+<decoderName>" (or "decrypt" for default decoder) to decrypt the data before decoding. It uses the secrets package to open a keeper by the URL string stored in a environment variable "RUNTIMEVAR_KEEPER_URL". See https://godoc.org/gocloud.dev/secrets#OpenKeeper for more details.

func NewDecoder 

func NewDecoder(obj interface{}, fn Decode) *Decoder

NewDecoder returns a Decoder that uses fn to decode a slice of bytes into an object of type obj.

This package provides some common Decode functions, including JSONDecode and GobDecode, which can be passed to this function to create Decoders for JSON and gob values.

func (*Decoder) Decode 

func (d *Decoder) Decode(ctx context.Context, b []byte) (interface{}, error)

Decode decodes b into a new instance of the target type.

type Snapshot 

type Snapshot struct {
	// Value contains the value of the variable.
	// The type for Value depends on the decoder used when creating the Variable.
	Value interface{}

	// UpdateTime is the time when the last change was detected.
	UpdateTime time.Time
	// contains filtered or unexported fields
}

Snapshot contains a snapshot of a variable's value and metadata about it. It is intended to be read-only for users.

func (*Snapshot) As added in v0.9.0 

func (s *Snapshot) As(i interface{}) bool

As converts i to driver-specific types. See https://gocloud.dev/concepts/as/ for background information, the "As" examples in this package for examples, and the driver package documentation for the specific types supported for that driver.

Example 
package main

import (
	"context"
	"fmt"
	"log"

	"gocloud.dev/runtimevar"

	_ "gocloud.dev/runtimevar/gcpruntimeconfig"
	runtimeconfig "google.golang.org/genproto/googleapis/cloud/runtimeconfig/v1beta1"
)

func main() {
	// This example is specific to the gcpruntimeconfig implementation; it
	// demonstrates access to the underlying
	// google.golang.org/genproto/googleapis/cloud/runtimeconfig.Variable type.
	// The types exposed for As by gcpruntimeconfig are documented in
	// https://godoc.org/gocloud.dev/runtimevar/gcpruntimeconfig#hdr-As
	ctx := context.Background()

	const url = "gcpruntimeconfig://proj/config/key"
	v, err := runtimevar.OpenVariable(ctx, url)
	if err != nil {
		log.Fatal(err)
	}

	s, err := v.Latest(ctx)
	if err != nil {
		log.Fatal(err)
	}

	var rcv *runtimeconfig.Variable
	if s.As(&rcv) {
		fmt.Println(rcv.UpdateTime)
	}
}

Output:

type URLMux added in v0.12.0 

type URLMux struct {
	// contains filtered or unexported fields
}

URLMux is a URL opener multiplexer. It matches the scheme of the URLs against a set of registered schemes and calls the opener that matches the URL's scheme. See https://gocloud.dev/concepts/urls/ for more information.

The zero value is a multiplexer with no registered schemes.

func DefaultURLMux added in v0.12.0 

func DefaultURLMux() *URLMux

DefaultURLMux returns the URLMux used by OpenVariable.

Driver packages can use this to register their VariableURLOpener on the mux.

func (*URLMux) OpenVariable added in v0.12.0 

func (mux *URLMux) OpenVariable(ctx context.Context, urlstr string) (*Variable, error)

OpenVariable calls OpenVariableURL with the URL parsed from urlstr. OpenVariable is safe to call from multiple goroutines.

func (*URLMux) OpenVariableURL added in v0.12.0 

func (mux *URLMux) OpenVariableURL(ctx context.Context, u *url.URL) (*Variable, error)

OpenVariableURL dispatches the URL to the opener that is registered with the URL's scheme. OpenVariableURL is safe to call from multiple goroutines.

func (*URLMux) RegisterVariable added in v0.12.0 

func (mux *URLMux) RegisterVariable(scheme string, opener VariableURLOpener)

RegisterVariable registers the opener with the given scheme. If an opener already exists for the scheme, RegisterVariable panics.

func (*URLMux) ValidVariableScheme added in v0.13.0 

func (mux *URLMux) ValidVariableScheme(scheme string) bool

ValidVariableScheme returns true iff scheme has been registered for Variables.

func (*URLMux) VariableSchemes added in v0.13.0 

func (mux *URLMux) VariableSchemes() []string

VariableSchemes returns a sorted slice of the registered Variable schemes.

type Variable 

type Variable struct {
	// contains filtered or unexported fields
}

Variable provides an easy and portable way to watch runtime configuration variables. To create a Variable, use constructors found in driver subpackages.

func OpenVariable added in v0.12.0 

func OpenVariable(ctx context.Context, urlstr string) (*Variable, error)

OpenVariable opens the variable identified by the URL given. See the URLOpener documentation in driver subpackages for details on supported URL formats, and https://gocloud.dev/concepts/urls for more information.

func (*Variable) CheckHealth added in v0.12.0 

func (c *Variable) CheckHealth() error

CheckHealth returns an error unless Latest will return a good value without blocking.

func (*Variable) Close 

func (c *Variable) Close() error

Close closes the Variable. The Variable is unusable after Close returns.

func (*Variable) ErrorAs added in v0.10.0 

func (c *Variable) ErrorAs(err error, i interface{}) bool

ErrorAs converts err to driver-specific types. ErrorAs panics if i is nil or not a pointer. ErrorAs returns false if err == nil. See https://gocloud.dev/concepts/as/ for background information.

Example 
package main

import (
	"context"
	"fmt"
	"log"

	"gocloud.dev/runtimevar"

	_ "gocloud.dev/runtimevar/gcpruntimeconfig"
	"google.golang.org/grpc/status"
)

func main() {
	// This example is specific to the gcpruntimeconfig implementation; it
	// demonstrates access to the underlying google.golang.org/grpc/status.Status
	// type.
	// The types exposed for As by gcpruntimeconfig are documented in
	// https://godoc.org/gocloud.dev/runtimevar/gcpruntimeconfig#hdr-As
	ctx := context.Background()

	const url = "gcpruntimeconfig://proj/wrongconfig/key"
	v, err := runtimevar.OpenVariable(ctx, url)
	if err != nil {
		log.Fatal(err)
	}

	_, err = v.Watch(ctx)
	if err != nil {
		var s *status.Status
		if v.ErrorAs(err, &s) {
			fmt.Println(s.Code())
		}
	}
}

Output:

func (*Variable) Latest added in v0.12.0 

func (c *Variable) Latest(ctx context.Context) (Snapshot, error)

Latest is intended to be called per request, with the request context. It returns the latest good Snapshot of the variable value, blocking if no good value has ever been received. If ctx is Done, it returns the latest error indicating why no good value is available (not the ctx.Err()). You can pass an already-Done ctx to make Latest not block.

Latest returns ErrClosed if the Variable has been closed.

Example 
package main

import (
	"context"
	"log"

	"gocloud.dev/runtimevar"

	_ "gocloud.dev/runtimevar/gcpruntimeconfig"
)

func main() {
	// PRAGMA: This example is used on gocloud.dev; PRAGMA comments adjust how it is shown and can be ignored.
	// PRAGMA: On gocloud.dev, hide lines until the next blank line.
	var v *runtimevar.Variable

	snapshot, err := v.Latest(context.Background())
	if err != nil {
		log.Fatalf("Error in retrieving variable: %v", err)
	}
	// PRAGMA: On gocloud.dev, hide the rest of the function.
	_ = snapshot
}

Output:

func (*Variable) Watch 

func (c *Variable) Watch(ctx context.Context) (Snapshot, error)

Watch returns when there is a new Snapshot of the current value of the variable.

The first call to Watch will block while reading the variable from the driver, and will return the resulting Snapshot or error. If an error is returned, the returned Snapshot is a zero value and should be ignored. Subsequent calls will block until the variable's value changes or a different error occurs.

Watch returns an ErrClosed error if the Variable has been closed.

Watch should not be called on the same variable from multiple goroutines concurrently. The typical use case is to call it in a single goroutine in a loop.

If the variable does not exist, Watch returns an error for which gcerrors.Code will return gcerrors.NotFound.

Alternatively, use Latest to retrieve the latest good value.

Example 
package main

import (
	"context"
	"log"

	"gocloud.dev/runtimevar"
	"gocloud.dev/runtimevar/constantvar"

	_ "gocloud.dev/runtimevar/gcpruntimeconfig"
)

func main() {
	// Construct a *Variable using a constructor from one of the
	// runtimevar subpackages. This example uses constantvar.
	// The variable value is of type string, so we use StringDecoder.
	v := constantvar.NewBytes([]byte("hello world"), runtimevar.StringDecoder)
	defer v.Close()

	// Call Watch in a loop from a background goroutine to see all changes,
	// including errors.
	//
	// You can use this for logging, or to trigger behaviors when the
	// config changes.
	//
	// Note that Latest always returns the latest "good" config, so seeing
	// an error from Watch doesn't mean that Latest will return one.
	go func() {
		for {
			snapshot, err := v.Watch(context.Background())
			if err == runtimevar.ErrClosed {
				// v has been closed; exit.
				return
			}
			if err == nil {
				// Casting to a string here because we used StringDecoder.
				log.Printf("New config: %v", snapshot.Value.(string))
			} else {
				log.Printf("Error loading config: %v", err)
				// Even though there's been an error loading the config,
				// v.Latest will continue to return the latest "good" value.
			}
		}
	}()
}

Output:

type VariableURLOpener added in v0.12.0 

type VariableURLOpener interface {
	OpenVariableURL(ctx context.Context, u *url.URL) (*Variable, error)
}

VariableURLOpener represents types than can open Variables based on a URL. The opener must not modify the URL argument. OpenVariableURL must be safe to call from multiple goroutines.

This interface is generally implemented by types in driver packages.

Source Files

View all Source files

Directories

Path Synopsis
Package awsparamstore provides a runtimevar implementation with variables read from AWS Systems Manager Parameter Store (https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html) Use OpenVariable to construct a *runtimevar.Variable.
 Package awsparamstore provides a runtimevar implementation with variables read from AWS Systems Manager Parameter Store (https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-paramstore.html) Use OpenVariable to construct a *runtimevar.Variable.
Package awssecretsmanager provides a runtimevar implementation with variables read from AWS Secrets Manager (https://aws.amazon.com/secrets-manager) Use OpenVariable to construct a *runtimevar.Variable.
 Package awssecretsmanager provides a runtimevar implementation with variables read from AWS Secrets Manager (https://aws.amazon.com/secrets-manager) Use OpenVariable to construct a *runtimevar.Variable.
Package blobvar provides a runtimevar implementation with variables read from a blob.Bucket.
 Package blobvar provides a runtimevar implementation with variables read from a blob.Bucket.
Package constantvar provides a runtimevar implementation with Variables that never change.
 Package constantvar provides a runtimevar implementation with Variables that never change.
Package driver defines interfaces to be implemented by runtimevar drivers, which will be used by the runtimevar package to interact with the underlying services.
 Package driver defines interfaces to be implemented by runtimevar drivers, which will be used by the runtimevar package to interact with the underlying services.
Package drivertest provides a conformance test for implementations of runtimevar.
 Package drivertest provides a conformance test for implementations of runtimevar.
etcdvar module
Package filevar provides a runtimevar implementation with variables backed by the filesystem.
 Package filevar provides a runtimevar implementation with variables backed by the filesystem.
Package gcpruntimeconfig provides a runtimevar implementation with variables read from GCP Cloud Runtime Configurator (https://cloud.google.com/deployment-manager/runtime-configurator).
 Package gcpruntimeconfig provides a runtimevar implementation with variables read from GCP Cloud Runtime Configurator (https://cloud.google.com/deployment-manager/runtime-configurator).
Package gcpsecretmanager provides a runtimevar implementation with secrets read from GCP Secret Manager (https://cloud.google.com/secret-manager).
 Package gcpsecretmanager provides a runtimevar implementation with secrets read from GCP Secret Manager (https://cloud.google.com/secret-manager).
Package httpvar provides a runtimevar implementation with variables backed by http endpoint.
 Package httpvar provides a runtimevar implementation with variables backed by http endpoint.

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.