kv

package
v1.5.0 Latest Latest
Warning

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

 Go to latest Published: Aug 7, 2026 License: MPL-2.0 Imports: 6 Imported by: 0

Documentation

Index

Constants

View Source 
const DefaultOperationTimeout = 5 * time.Second

DefaultOperationTimeout bounds a single provider Get/Set when neither the store config nor the SecretStore wrapper supplies one.

Variables

View Source 
var (
	// ErrStoreNotFound is returned when referencing an unregistered store name.
	ErrStoreNotFound = errors.New("store not found")

	// ErrContractViolation indicates that an underlying KV provider returned data
	// violates the expected API contract (e.g., type assertion failures)
	ErrContractViolation = errors.New("provider contract violation")

	// ErrStoreClosed is returned when an operation is attempted on closed store or
	// provider that has already been shut down via its Close method.
	ErrStoreClosed = errors.New("secret store is closed")
)

Functions

func As 

func As[T any](p Provider) (T, bool)

As attempts to extract an interface of type T from a Provider, automatically unwrapping decorators up to a maximum depth.

func EffectiveTimeout 

func EffectiveTimeout(configured time.Duration) time.Duration

EffectiveTimeout resolves a configured timeout to the value actually used: the configured value when positive, else the default.

func NewStoreNotFoundError 

func NewStoreNotFoundError(storeName string) error

Types

type Closer 

type Closer interface {
	Close(ctx context.Context) error
}

Closer is an optional interface for providers that need graceful shutdown or resource cleanup when the registry is closed.

func AsCloser 

func AsCloser(p Provider) (Closer, bool)

AsCloser attempts to extract an Closer from a Provider, automatically unwrapping decorators.

type Config 

type Config struct {
	// Stores lists the secret backends Tyk is allowed to read from, each under a
	// name you choose. That name is how a secret reference picks the store: a
	// store named "vault-prod" is reached as kv://vault-prod/<key>, or with the
	// inline $kv{vault-prod/<key>} form. Names are yours to invent — keep them
	// short and stable, because renaming one breaks every reference that uses
	// it. Configure as many stores as you need, including several of the same
	// type (one Vault store per environment, for instance).
	Stores Stores `json:"stores"`
}

Config represents the top-level "kv" configuration block in component configs. It contains global settings and named store definitions.

This block is configured per Tyk component — Gateway, Dashboard and so on — in that component's own configuration. Stores are therefore not shared between components: each one resolves secrets through the stores defined in its own config, using its own credentials, environment and network access. A component that has to resolve a reference needs a store for it, so a reference used in more than one component needs the store defined in each. Where the surrounding field documentation says "Tyk" does something, it means the component the store belongs to.

Example JSON structure: 

{
  "kv": {
    "stores": {
      "vault-prod": {"type": "hashicorp_vault", "required": true, "config": {...}}
    }
  }
}

type Initializer 

type Initializer interface {
	Init(ctx context.Context) error
}

Initializer is an optional interface for providers that require network initialization or connection establishment before use.

func AsInitializer 

func AsInitializer(p Provider) (Initializer, bool)

AsInitializer attempts to extract an Initializer from a Provider, automatically unwrapping decorators.

type KeyNotFoundError 

type KeyNotFoundError struct {
	StoreName string
	KeyPath   string
}

KeyNotFoundError indicates the store is reachable but the key does not exist.

func (*KeyNotFoundError) Error 

func (e *KeyNotFoundError) Error() string

type KeyValueRetriever 

type KeyValueRetriever interface {
	Get(ctx context.Context, key string) (string, error)
}

KeyValueRetriever defines the core read capability for retrieving values by key.

type Lister 

type Lister interface {
	List(ctx context.Context, prefix string) (map[string]string, error)
}

Lister is an optional interface for providers that support enumerating keys & values by prefix. This enables dynamic discovery of available secrets and operational tooling.

func AsLister 

func AsLister(p Provider) (Lister, bool)

AsLister attempts to extract a Lister from a Provider, automatically unwrapping decorators.

type Logger 

type Logger interface {
	Debug(msg string, fields map[string]any)
	Warn(msg string, fields map[string]any)
	Error(msg string, fields map[string]any)
}

type NoopLogger 

type NoopLogger struct{}

func (NoopLogger) Debug 

func (NoopLogger) Debug(_ string, _ map[string]any)

func (NoopLogger) Error 

func (NoopLogger) Error(_ string, _ map[string]any)

func (NoopLogger) Warn 

func (NoopLogger) Warn(_ string, _ map[string]any)

type Provider 

type Provider interface {
	KeyValueRetriever
}

Provider is the composite interface that all KV providers must implement. Currently only requires read access via KeyValueRetriever, but designed for future expansion.

Providers may optionally implement Initializer, Closer, HealthChecker, or Lister interfaces for additional capabilities that will be detected via type assertion during registry operations.

type ProviderFactory 

type ProviderFactory func(config json.RawMessage) (Provider, error)

ProviderFactory creates a specific provider instance from raw JSON configuration. Each provider type registers its own factory function that knows how to parse its specific configuration format and return a configured Provider.

The factory pattern allows the registry to create providers dynamically without compile-time dependencies on specific provider implementations.

Config validation convention. A factory returns an error only for config that is present but invalid — a value that can never produce correct behavior (malformed JSON, or a security-critical field set to an unusable value, e.g. a relative path where an absolute one is required). It must NOT error for merely-absent optional config: an unset value is a valid state, so the factory builds a provider that runs in its default or disabled mode (e.g. an env provider with no prefix, or a file provider with no base_path that then rejects every Get). Whether to create a store at all for an unconfigured feature is the caller's decision, not the factory's. The effect: configuration mistakes surface once, at construction, while unused features stay quiet instead of failing on every Get.

type ProviderType 

type ProviderType string

ProviderType represents the unique string identifier for a KV provider. 

const (

	// Env resolves secrets from environment variables.
	Env ProviderType = "env"

	// Inline resolves secrets from plain text in the configuration.
	Inline ProviderType = "inline"

	// File resolves secrets from files on the local filesystem.
	File ProviderType = "file"

	// Vault resolves secrets from HashiCorp Vault.
	Vault ProviderType = "hashicorp_vault"

	// Consul resolves secrets from HashiCorp Consul.
	Consul ProviderType = "hashicorp_consul"

	// AWS resolves secrets from AWS Secrets Manager.
	AWS ProviderType = "aws_secrets_manager"

	// GCP resolves secrets from Google Cloud Secret Manager.
	GCP ProviderType = "gcp_secret_manager"

	// Azure resolves secrets from Azure Key Vault.
	Azure ProviderType = "azure_key_vault"

	// Conjur resolves secrets from CyberArk Conjur.
	Conjur ProviderType = "cyberark_conjur"
)

func (ProviderType) IsLocal 

func (t ProviderType) IsLocal() bool

IsLocal reports whether this provider type resolves secrets from resources available to the local process — environment variables, inline config data, or the filesystem — requiring no network and a literal, reference-free config.

type Setter 

type Setter interface {
	Set(ctx context.Context, key, value string) error
}

Setter is an optional interface for providers that support writing values back to their backend.

func AsSetter 

func AsSetter(p Provider) (Setter, bool)

AsSetter attempts to extract a Setter from a Provider, automatically unwrapping decorators.

type Standaloner 

type Standaloner interface {
	IsStandalone() bool
}

Standaloner is an optional interface for providers that do not need to be combined with singleflight mechanisms.

func AsStandaloner 

func AsStandaloner(p Provider) (Standaloner, bool)

AsStandaloner attempts to extract a Standaloner from a Provider.

type StoreConfig 

type StoreConfig struct {
	// Type is the kind of secret backend this store talks to. It also decides
	// how the Config block below is interpreted, since every backend takes its
	// own settings. One of:
	//   - "env"                 environment variables of the Tyk component's process
	//   - "inline"              literal values written into this configuration
	//   - "file"                files on the local filesystem
	//   - "hashicorp_vault"     HashiCorp Vault
	//   - "hashicorp_consul"    the key/value store of HashiCorp Consul
	//   - "aws_secrets_manager" AWS Secrets Manager
	//   - "gcp_secret_manager"  Google Cloud Secret Manager
	//   - "azure_key_vault"     Azure Key Vault
	//
	// Which of these a given store can actually use depends on the Tyk component
	// and its edition: a component registers the backends it supports, so a type
	// that is valid in one may be unavailable in another and is then treated as an
	// unsupported type (see Required). Check the documentation of the component
	// you are configuring. Required.
	Type ProviderType `json:"type"`

	// Required says whether the Tyk component may start up without this store. A
	// store fails to start when its settings cannot be read, its credentials are
	// refused, or its type is not supported.
	//
	// Left false — the default — such a failure is written to the log as a
	// warning and the store is skipped: start-up continues, and any reference to
	// that store fails at the point something tries to read it. Set to true, the
	// same failure is reported to the component as an error instead, and a
	// component will normally refuse to start on it. Choose true for stores
	// holding secrets the component cannot run properly without, so a mistake
	// shows up immediately at startup rather than later as a failing API.
	Required bool `json:"required"`

	// Config holds the settings for the backend named by Type: where it lives,
	// how Tyk authenticates to it, and any behaviour options. The fields differ
	// per backend and are documented with the Config type in each provider's own
	// package.
	Config json.RawMessage `json:"config"`
}

StoreConfig defines the configuration for a single named KV store instance.

type StoreGetter 

type StoreGetter interface {
	GetStore(name string) (Provider, error)
}

StoreGetter retrieves an initialized store by name.

type StoreUnavailableError 

type StoreUnavailableError struct {
	KeyPath string
	Err     error
}

StoreUnavailableError indicates a transient failure reaching the store.

func (*StoreUnavailableError) Error 

func (e *StoreUnavailableError) Error() string

func (*StoreUnavailableError) Unwrap 

func (e *StoreUnavailableError) Unwrap() error

type Stores 

type Stores map[string]StoreConfig

Stores is a set of named store definitions, keyed by the name each store is referenced by.

Beyond being a map, Stores implements Decode so configuration loaders that support custom decoders — kelseyhightower/envconfig in particular — can populate the whole set from a single environment variable holding a JSON object. That is the only way store definitions can come from the environment: the map is keyed by operator-chosen names and every entry carries an opaque per-provider Config blob, neither of which a flat NAME=value convention can express.

func (*Stores) Decode 

func (s *Stores) Decode(value string) error

Decode populates s from value, a JSON object mapping each store name to its definition — the same shape as the "stores" field of a config file: 

{"vault-prod": {"type": "hashicorp_vault", "required": true, "config": {...}}}

It satisfies the envconfig.Decoder interface structurally, so a component can expose its store definitions through an environment variable.

type Timeouter 

type Timeouter interface {
	Timeout() time.Duration
}

Timeouter is an optional interface for providers that expose a custom duration configuration for operations.

func AsTimeouter 

func AsTimeouter(p Provider) (Timeouter, bool)

AsTimeouter attempts to extract a Timeouter from a Provider.

Source Files

View all Source files

Directories

Path Synopsis
internal
resolve
store
providers
aws
Package aws implements a kv.Provider backed by AWS Secrets Manager.
 Package aws implements a kv.Provider backed by AWS Secrets Manager.
azure
Package azure implements a kv.Provider backed by Azure Key Vault secrets, using the azsecrets data-plane client.
 Package azure implements a kv.Provider backed by Azure Key Vault secrets, using the azsecrets data-plane client.
consul
Package consul provides a kv.Provider backed by HashiCorp Consul's KV store.
 Package consul provides a kv.Provider backed by HashiCorp Consul's KV store.
env
Package env provides a KV provider that reads secrets from the process environment.
 Package env provides a KV provider that reads secrets from the process environment.
file
Package file provides a KV provider that reads secrets from the local filesystem — plain files and Kubernetes Secrets mounted as files.
 Package file provides a KV provider that reads secrets from the local filesystem — plain files and Kubernetes Secrets mounted as files.
gcp
Package gcp implements a kv.Provider backed by Google Cloud Secret Manager.
 Package gcp implements a kv.Provider backed by Google Cloud Secret Manager.
inline
Package inline provides a KV provider that serves secrets from a literal key/value map embedded in the configuration.
 Package inline provides a KV provider that serves secrets from a literal key/value map embedded in the configuration.
vault
Package vault provides a kv.Provider backed by HashiCorp Vault.
 Package vault provides a kv.Provider backed by HashiCorp Vault.

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.