settings

package
v1.1.0 Latest Latest
Warning

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

Go to latest
Published: Nov 5, 2026 License: MIT Imports: 23 Imported by: 0

Documentation

Overview

Package settings persists preferences and instance metadata, never credentials.

Index

Constants

View Source
const (
	AuthToken    = "token"
	AuthOAuth    = "oauth"
	AuthSSH      = "ssh"
	AuthHTTPSign = "httpsign"

	StoreKeyring = "keyring"
	StoreFile    = "file"
)

Authentication methods and credential stores recorded for accounts.

View Source
const LockTimeout = 30 * time.Second

LockTimeout bounds the wait for another process's settings update or token refresh.

View Source
const Version = "1"

Version identifies the split configuration schema.

Variables

This section is empty.

Functions

func AtomicWrite

func AtomicWrite(name string, data []byte) error

AtomicWrite publishes a complete private file after flushing its contents. A symbolic link is kept and its target replaced, or created when it does not exist yet.

func DataDir added in v1.0.0

func DataDir(dir string) string

DataDir returns dir, or else the platform data directory, where gt keeps installed extensions.

func DefaultSSHHost

func DefaultSSHHost(instance string) string

DefaultSSHHost returns the SSH host of an instance without ssh_host: its web host on port 22.

func NormalizeHost

func NormalizeHost(raw string) (string, error)

NormalizeHost retains ports and installation paths as part of instance identity.

func ParseExtensionOwner added in v1.0.0

func ParseExtensionOwner(entry string) (host, owner string, err error)

ParseExtensionOwner splits an extension_owners entry, HOST/OWNER, into the normalized instance URL and the owner.

func ParseHeader

func ParseHeader(raw string) (name, value string, err error)

ParseHeader parses a "Name: value" header argument.

func ParseRemote

func ParseRemote(raw string) (*url.URL, error)

ParseRemote parses a Git remote URL, reading scp-style [user@]host:path as ssh://[user@]host/path without interpreting shell syntax.

func ParseTimeout

func ParseTimeout(value string) (time.Duration, error)

ParseTimeout parses the http_timeout preference: a duration such as 30s or 5m, or 0 for none.

func PolicyPath added in v1.0.0

func PolicyPath() string

PolicyPath is where the system policy is read from.

func RemoteIsSSH

func RemoteIsSSH(remote string) bool

RemoteIsSSH reports whether a Git remote uses SSH: an ssh:// URL or an scp-style [user@]host:path.

func RemoteRepository

func RemoteRepository(raw string, hosts map[string]Host) (string, string, error)

RemoteRepository resolves a Git remote like RepositoryURL, ignoring the credentials of a remote such as https://user:token@host/owner/name.git, which repository arguments must not embed.

func RepositoryURL

func RepositoryURL(raw string, hosts map[string]Host) (string, string, error)

RepositoryURL resolves a repository URL or Git remote to a configured instance and its owner/name. Unconfigured HTTP(S) URLs take the final two path segments as the repository.

func ResolveHost

func ResolveHost(raw string, hosts map[string]Host) (string, error)

ResolveHost normalizes an instance given as a URL or as a bare HOST[:PORT][/PATH]. A bare host takes the scheme of the configured instance it names, else https.

func SSHEndpoint

func SSHEndpoint(authority string) (string, error)

SSHEndpoint normalizes a host or host:port, including bracketed IPv6 addresses.

func ValidSlug

func ValidSlug(slug string) bool

ValidSlug reports whether slug is exactly owner/name.

func ValidateHeader

func ValidateHeader(name, value string) error

ValidateHeader checks a configured header: a valid name that gt does not set itself, and a value on one line.

func WithoutCredentials

func WithoutCredentials(raw string) string

WithoutCredentials returns a URL without the secrets it can embed, for showing or matching it. An HTTP(S) URL loses its user information, an ssh:// URL its password, and both their query and fragment. An scp-like address such as git@host:owner/name keeps its user, which Git reads as a login name only. A URL that does not parse but holds an @ becomes "".

Types

type Account

type Account struct {
	AuthMethod        string `yaml:"auth_method" json:"auth_method"`
	CredentialStore   string `yaml:"credential_store,omitempty" json:"credential_store,omitempty"`
	SSHKey            string `yaml:"ssh_key,omitempty" json:"ssh_key,omitempty"`
	SSHAgent          bool   `yaml:"ssh_agent,omitempty" json:"ssh_agent,omitempty"`
	SSHCertPrincipal  string `yaml:"ssh_certificate_principal,omitempty" json:"ssh_certificate_principal,omitempty"`
	SSHKeyFingerprint string `yaml:"ssh_key_fingerprint,omitempty" json:"ssh_key_fingerprint,omitempty"`
}

Account contains account-specific authentication metadata, never token values.

func (Account) Tokenless

func (a Account) Tokenless() bool

Tokenless reports whether the account signs requests instead of storing a token.

type Host

type Host struct {
	User          string `yaml:"user,omitempty" json:"user"`
	SSHHost       string `yaml:"ssh_host,omitempty" json:"ssh_host,omitempty"`
	Insecure      bool   `yaml:"insecure,omitempty" json:"insecure"`
	GitProtocol   string `yaml:"git_protocol,omitempty" json:"git_protocol,omitempty"`
	OAuthClientID string `yaml:"oauth_client_id,omitempty" json:"oauth_client_id,omitempty"`
	// Headers are sent with every request to the instance, such as those of an access proxy in
	// front of it. A value of $NAME or ${NAME} is read from the environment variable NAME when sent.
	Headers map[string]string `yaml:"headers,omitempty" json:"headers,omitempty"`
	// ClientCert and ClientKey name the PEM files of a TLS client certificate for instances that
	// require one; without ClientKey, the key is read from ClientCert.
	ClientCert string             `yaml:"client_cert,omitempty" json:"client_cert,omitempty"`
	ClientKey  string             `yaml:"client_key,omitempty" json:"client_key,omitempty"`
	Users      map[string]Account `yaml:"users" json:"users"`
}

Host contains shared connection settings and the active account.

func (Host) HasSettings

func (h Host) HasSettings() bool

HasSettings reports whether h stores instance settings besides its accounts.

func (Host) WithHeaders

func (h Host) WithHeaders(headers map[string]string) Host

WithHeaders returns h with headers added, replacing those of the same name; an empty value removes the header. Names are in canonical form, as ParseHeader and Load leave them.

type Hosts

type Hosts struct {
	Version string          `yaml:"version" json:"version"`
	Hosts   map[string]Host `yaml:"hosts" json:"hosts"`
}

Hosts stores instances keyed by their normalized installation URLs.

type Policy added in v1.0.0

type Policy struct {
	// Path is the file the policy was read from, or empty when there is none.
	Path                 string   `yaml:"-"`
	Extensions           string   `yaml:"extensions,omitempty"`
	ExtensionHosts       []string `yaml:"extension_hosts,omitempty"`
	ExtensionOwners      []string `yaml:"extension_owners,omitempty"`
	ExtensionCredentials string   `yaml:"extension_credentials,omitempty"`
}

Policy holds the restrictions an administrator sets for every user of a system. Users can only tighten them in config.yml, never loosen them.

func LoadPolicy added in v1.0.0

func LoadPolicy(path string) (Policy, error)

LoadPolicy reads the policy at path. A missing file is no policy; a broken one is an error, since ignoring it would lift the restrictions it sets.

type Preferences

type Preferences struct {
	Version     string            `yaml:"version" json:"version"`
	DefaultHost string            `yaml:"default_host,omitempty" json:"default_host"`
	GitProtocol string            `yaml:"git_protocol,omitempty" json:"git_protocol"`
	Editor      string            `yaml:"editor,omitempty" json:"editor"`
	Prompt      string            `yaml:"prompt,omitempty" json:"prompt"`
	Pager       string            `yaml:"pager,omitempty" json:"pager"`
	Browser     string            `yaml:"browser,omitempty" json:"browser"`
	Color       string            `yaml:"color,omitempty" json:"color"`
	Hyperlinks  string            `yaml:"hyperlinks,omitempty" json:"hyperlinks"`
	Markdown    string            `yaml:"markdown,omitempty" json:"markdown"`
	Remote      string            `yaml:"remote,omitempty" json:"remote"`
	HTTPTimeout string            `yaml:"http_timeout,omitempty" json:"http_timeout"`
	Aliases     map[string]string `yaml:"aliases,omitempty" json:"aliases"`
	// Extensions is enabled or disabled; ExtensionHosts and ExtensionOwners, when set, are the only
	// instances and HOST/OWNER accounts extensions are installed and run from.
	Extensions      string   `yaml:"extensions,omitempty" json:"extensions"`
	ExtensionHosts  []string `yaml:"extension_hosts,omitempty" json:"extension_hosts"`
	ExtensionOwners []string `yaml:"extension_owners,omitempty" json:"extension_owners"`
}

Preferences contains global, non-secret command defaults.

func Defaults

func Defaults() Preferences

Defaults returns a fresh preferences value with built-in settings.

type RepositoryRef

type RepositoryRef struct {
	// Host is the instance URL the argument names, or "" when it names none.
	Host string
	// Owner is "" for a bare NAME, which belongs to the active account.
	Owner, Name string
}

RepositoryRef is a parsed repository argument.

func ParseRepository

func ParseRepository(raw string, hosts map[string]Host) (RepositoryRef, error)

ParseRepository reads a repository argument: NAME, OWNER/NAME, HOST/OWNER/NAME (with an optional .git suffix), or a clone or web URL. HOST may carry a port and a configured instance's base path; it takes the scheme of the configured instance it names, else https.

func (RepositoryRef) Slug

func (r RepositoryRef) Slug() string

Slug returns owner/name, or the bare name when the owner is not known yet.

type SSHRemoteError

type SSHRemoteError struct {
	// Endpoint is the remote's host:port; Instance is the only instance with the remote's host
	// name, or "".
	Endpoint, Instance string
	// Environment says that the instance is the GITEA_TOKEN instance without stored settings, whose
	// SSH host only GITEA_INSTANCE_SSH_HOST sets.
	Environment bool
}

SSHRemoteError is an SSH remote that matches no instance's SSH host.

func (*SSHRemoteError) Error

func (e *SSHRemoteError) Error() string

func (*SSHRemoteError) Fix

func (e *SSHRemoteError) Fix() string

Fix returns the command that configures the remote's endpoint as an instance's SSH host.

type Snapshot

type Snapshot struct {
	Preferences Preferences
	Hosts       Hosts
	// Configured distinguishes explicitly stored settings from built-in defaults.
	Configured map[string]bool
}

Snapshot is one independently loaded configuration generation.

func (Snapshot) Validate

func (s Snapshot) Validate() error

Validate rejects unsupported versions and inconsistent instance/account settings.

type Store

type Store struct {
	Dir string
	// contains filtered or unexported fields
}

Store coordinates configuration reads and locked atomic updates.

func New

func New(dir string) *Store

New selects an explicit directory or the platform configuration directory.

func (*Store) Generation

func (s *Store) Generation() uint64

Generation changes whenever an update through the store ran, so callers can tell when a snapshot they loaded earlier may be stale.

func (*Store) Load

func (s *Store) Load() (Snapshot, error)

Load reads both configuration files without creating paths or mutating globals.

func (*Store) Locked

func (s *Store) Locked(fn func(Snapshot) error) error

Locked coordinates account changes and token refresh without rewriting settings.

func (*Store) Transaction

func (s *Store) Transaction(target Target, update func(*Snapshot) (func() error, error)) error

Transaction runs a compensating action under the lock if publishing the target file fails. It is used to keep credential storage and account metadata consistent.

func (*Store) Update

func (s *Store) Update(target Target, update func(*Snapshot) error) error

Update serializes writers, reloads current settings, and changes exactly the target file. Cross-file transactions are not exposed.

type Target

type Target int

Target selects which settings file an update publishes.

const (
	// TargetPreferences publishes config.yml, the global non-secret defaults.
	TargetPreferences Target = iota
	// TargetHosts publishes hosts.yml, the instance and account metadata.
	TargetHosts
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL