Documentation

Overview

    Package config contains a client to access LUCI configuration service.

    Index

    Constants

    This section is empty.

    Variables

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

      ErrNoConfig is returned if requested config does not exist.

      Functions

      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 and GetRefConfigs.
        	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 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)
          
          	// GetConfigByHash returns the contents of a config, as identified by its
          	// content hash, or ErrNoConfig if missing.
          	GetConfigByHash(ctx context.Context, contentHash string) (string, error)
          
          	// GetConfigSetLocation returns the URL location of a config set.
          	GetConfigSetLocation(ctx context.Context, configSet Set) (*url.URL, 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)
          
          	// GetRefConfigs returns the config at the given path in all refs of all
          	// projects that have such config. If metaOnly is true, returned Config
          	// structs have only Meta set (and the call is faster).
          	GetRefConfigs(ctx context.Context, path string, metaOnly bool) ([]Config, error)
          
          	// GetRefs returns the list of refs for a project.
          	GetRefs(ctx context.Context, projectID string) ([]string, error)
          
          	// ListFiles returns the list of files for a config set.
          	ListFiles(ctx context.Context, configSet Set) ([]string, 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.
              	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 series of path components: domain/target[/ref].

                    - 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 ProjectSet

                    func ProjectSet(project string) Set

                      ProjectSet returns the config set for the specified project.

                      func RefSet

                      func RefSet(project string, ref string) Set

                        RefSet returns the config set for the specified project and ref. If ref is empty, this will equal the ProjectSet value.

                        func ServiceSet

                        func ServiceSet(service string) Set

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

                          func (Set) Project

                          func (cs Set) Project() string

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

                            Use ProjectAndRef if you need to get both the project name and the ref.

                            func (Set) ProjectAndRef

                            func (cs Set) ProjectAndRef() (project, ref string)

                              ProjectAndRef splits a project-rooted config set (projects/<name>[/...]) into its project name and ref components.

                              For example, "projects/foo/bar/baz" is a config set that belongs to project "foo". It will be parsed into ("foo", "bar/baz").

                              If configSet is not a project config set, empty strings will be returned.

                              func (Set) Ref

                              func (cs Set) Ref() string

                                Ref returns a ref component of a project-rooted config set or empty string for all other sets.

                                Use ProjectAndRef if you need to get both the project name and the ref.

                                func (Set) Service

                                func (cs Set) Service() string

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

                                  func (Set) Split

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

                                    Split splits a Set into its domain, target, and ref components.

                                    Directories

                                    Path Synopsis
                                    appengine
                                    gaeconfig
                                    Package gaeconfig implements LUCI-config service bindings backed by AppEngine storage and caching.
                                    Package gaeconfig implements LUCI-config service bindings backed by AppEngine storage and caching.
                                    Package cfgclient contains glue code to use config.Interface client.
                                    Package cfgclient contains glue code to use config.Interface client.
                                    impl
                                    erroring
                                    Package erroring implements a backend that always returns an error for all of its calls.
                                    Package erroring implements a backend that always returns an error for all of its calls.
                                    filesystem
                                    Package filesystem implements a file system backend for the config client.
                                    Package filesystem implements a file system backend for the config client.
                                    memory
                                    Package memory implements in-memory backend for the config client.
                                    Package memory implements in-memory backend for the config client.
                                    resolving
                                    Package resolving implements an interface that resolves ${var} placeholders in config set names and file paths before forwarding calls to some other interface.
                                    Package resolving implements an interface that resolves ${var} placeholders in config set names and file paths before forwarding calls to some other interface.
                                    server
                                    cfgcache
                                    Package cfgcache provides a datastore-based cache of individual config files.
                                    Package cfgcache provides a datastore-based cache of individual config files.
                                    cfgmodule
                                    Package cfgmodule provides a server module with a LUCI Config client.
                                    Package cfgmodule provides a server module with a LUCI Config client.
                                    Package validation provides helpers for performing and setting up handlers for config validation related requests from luci-config.
                                    Package validation provides helpers for performing and setting up handlers for config validation related requests from luci-config.
                                    Package vars implements a registry of ${var} placeholders.
                                    Package vars implements a registry of ${var} placeholders.