config

Documentation

Overview

Package config contains a client to access LUCI configuration service.

Index

• Constants
• Variables
• func DownloadConfigFromSignedURL(ctx context.Context, client *http.Client, signedURL string) ([]byte, error)
• func ValidateProjectName(p string) error
• type Config
• type Domain
• type Interface
• type Meta
• type Project
• type RepoType
• type Set
  • func MustProjectSet(project string) Set
  • func MustServiceSet(service string) Set
  • func ProjectSet(project string) (Set, error)
  • func ServiceSet(service string) (Set, error)
  • func (cs Set) Domain() Domain
  • func (cs Set) Project() string
  • func (cs Set) Service() string
  • func (cs Set) Split() (domain Domain, target string)
  • func (cs Set) Validate() error

Constants

const ServiceNamePattern = `[a-z0-9\-_]+`

ServiceNamePattern is the regexp pattern string that matches valid service name.

Variables

var ErrNoConfig = errors.New("no such config")

ErrNoConfig is returned if requested config does not exist.

Functions

func DownloadConfigFromSignedURL

func DownloadConfigFromSignedURL(ctx context.Context, client *http.Client, signedURL string) ([]byte, error)

DownloadConfigFromSignedURL downloads the config file content from the provided GCS signed url. The signed url is generated by Config Service V2.

func ValidateProjectName

func ValidateProjectName(p string) error

ValidateProjectName returns an error if the supplied string is not a valid project name.

A valid project name may only include:

• Lowercase letters [a-z]
• Numbers [0-9]
• Hyphen (-)
• Underscore (_)

It also must begin with a letter.

See: https://github.com/luci/luci-py/blob/8e594074929871a9761d27e814541bc0d7d84744/appengine/components/components/config/common.py#L41

Types

type Config

type Config struct {
	Meta

	// Error is not nil if there where troubles fetching this config. Used only
	// by functions that operate with multiple configs at once, such as
	// GetProjectConfigs.
	Error error `json:"error,omitempty"`

	// Content is the actual body of the config file.
	Content string `json:"content,omitempty"`
}

Config is a configuration file along with its metadata.

type Domain

type Domain string

Domain describes the domain of the config set.

const (
	// ProjectDomain is the domain of project config set(e.g. projects/chromium).
	ProjectDomain Domain = "projects"
	// ServiceDomain is the domain of service config set (e.g.
	// services/luci-config).
	ServiceDomain Domain = "services"
)

type Interface

type Interface interface {
	// GetConfig returns a config at a path in a config set or ErrNoConfig
	// if missing. If metaOnly is true, returned Config struct has only Meta set
	// (and the call is faster).
	GetConfig(ctx context.Context, configSet Set, path string, metaOnly bool) (*Config, error)

	// GetConfigs returns a bunch of config files fetched at the same revision.
	// If filter is nil, will return all files in the config set. Otherwise only
	// files that pass the filter are returned. The filter is called sequentially
	// in the same goroutine as GetConfigs itself and it receives paths in some
	// arbitrary order. If metaOnly is true, returned Config structs have only
	// Meta set (and the call is much faster). If there's no such config set at
	// all, returns ErrNoConfig.
	GetConfigs(ctx context.Context, configSet Set, filter func(path string) bool, metaOnly bool) (map[string]Config, error)

	// GetProjectConfigs returns all the configs at the given path in all
	// projects that have such config. If metaOnly is true, returned Config
	// structs have only Meta set (and the call is faster).
	GetProjectConfigs(ctx context.Context, path string, metaOnly bool) ([]Config, error)

	// GetProjects returns all the registered projects in the configuration
	// service.
	GetProjects(ctx context.Context) ([]Project, error)

	// ListFiles returns the list of files for a config set.
	ListFiles(ctx context.Context, configSet Set) ([]string, error)

	// Close closes resources the config.Interface uses.
	// The caller is expected to call Close() after the config.Interface is no
	// longer used.
	Close() error
}

Interface represents low-level pull-based LUCI Config API.

This is roughly a wrapper over LUCI Config RPC interface, and all methods are generally slow and depend on available of LUCI Config service. They *must not* be used in a hot path of requests.

Transient errors are tagged with transient.Tag.

type Meta

type Meta struct {
	// ConfigSet is the config set name (e.g. "projects/<id>") this config
	// belongs to.
	ConfigSet Set `json:"configSet,omitempty"`

	// Path is the filename relative to the root of the config set,
	// without leading slash, e.g. "luci-scheduler.cfg".
	Path string `json:"path,omitempty"`

	// ContentHash can be used to quickly check that content didn't change.
	ContentHash string `json:"contentHash,omitempty"`

	// Revision is git SHA1 of a repository the config was fetched from.
	Revision string `json:"revision,omitempty"`

	// ViewURL is the URL surfaced for viewing the config.
	ViewURL string `json:"view_url,omitempty"`
}

Meta is metadata about a single configuration file.

type Project

type Project struct {
	// ID is unique project identifier.
	ID string

	// Name is a short friendly display name of the project.
	// In remote_v2 implementation, Name and ID are always the same.
	Name string

	// RepoType specifies in what kind of storage projects configs are stored.
	RepoType RepoType

	// RepoUrl is the location of this project code repository. May be nil if
	// unknown or cannot be parsed.
	RepoURL *url.URL
}

Project is a project registered in the luci-config service.

type RepoType

type RepoType string

RepoType is the type of the repo the Project is stored in.

const (
	// GitilesRepo means a repo is backed by the Gitiles service.
	GitilesRepo RepoType = "GITILES"

	// UnknownRepo means a repo is backed by an unknown service.
	// It may be an invalid repo.
	UnknownRepo RepoType = "UNKNOWN"
)

type Set

type Set string

Set is a name of a configuration set: a bunch of config files versioned and stored as a single unit in a same repository.

A config set name consists of a domain and a target.

• Service config sets are config sets in the "services" domain, with the service name as the target.
• Project config sets are config sets in the "projects" domain. The target is the project name.

func MustProjectSet

func MustProjectSet(project string) Set

MustProjectSet is like `ProjectSet` but panic on invalid project name.

func MustServiceSet

func MustServiceSet(service string) Set

MustServiceSet is like `ServiceSet` but panic on invalid service name.

func ProjectSet

func ProjectSet(project string) (Set, error)

ProjectSet returns the config set for the specified project.

Returns error if the project name is invalid. See `ValidateProjectName`.

func ServiceSet

func ServiceSet(service string) (Set, error)

ServiceSet returns the name of a config set for the specified service.

Returns error if the service name doesn't match `ServiceNamePattern`.

func (Set) Domain

func (cs Set) Domain() Domain

Domain returns the domain of the config set.

func (Set) Project

func (cs Set) Project() string

Project returns a project name for a project config set or empty string for all other sets.

func (Set) Service

func (cs Set) Service() string

Service returns a service name for a service config set or empty string for all other sets.

func (Set) Split

func (cs Set) Split() (domain Domain, target string)

Split splits a Set into its domain, target components.

func (Set) Validate

func (cs Set) Validate() error

Validate checks that the config set is well-formed.