settings

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Oct 23, 2026 License: MIT Imports: 22 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(filename string, data []byte) error

AtomicWrite publishes a complete private file after flushing its contents.

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 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 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 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"`
}

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
)

Source Files

View all Source files

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.