config

Documentation

Overview

Package config loads and layers the server configuration (embedded defaults, config.yaml, admin-overrides.json, CLI overrides).

Index

• func MigrateDump(dumpJSON []byte) ([]byte, error)
• func WriteStarterConfig(path string) error
• type Avatars
• type Branding
• type Config
• type Debug
• type FileUpload
• type HTTPS
• type Identd
• type JSFunctionMarker
• type Jitsi
• type Klipy
• type Loaded
  • func Load(homePath string, cliOverrides []string) (*Loaded, error)
  • func (l *Loaded) AdminOverridesPath() string
  • func (l *Loaded) ClientCertificatesPath() string
  • func (l *Loaded) ConfigYAMLPath() string
  • func (l *Loaded) DefaultNick() string
  • func (l *Loaded) FileUploadPath() string
  • func (l *Loaded) HomePath() string
  • func (l *Loaded) InstalledPackagePath(name string) string
  • func (l *Loaded) PackagesManifestPath() string
  • func (l *Loaded) PackagesPath() string
  • func (l *Loaded) ShortLinksDBPath() string
  • func (l *Loaded) StoragePath() string
  • func (l *Loaded) UserConfigPath(name string) string
  • func (l *Loaded) UserLogsPath() string
  • func (l *Loaded) UserThemesPath() string
  • func (l *Loaded) UsersPath() string
• type NetworkDefaults
• type OIDC
• type Partyline
• type Postgres
• type SMTP
• type ShortLink
• type Stats
• type StoragePolicy
• type UnsupportedFunctionError
  • func (e *UnsupportedFunctionError) Error() string
• type WebAuthn
• type WebIRCEntry
  • func (w WebIRCEntry) MarshalJSON() ([]byte, error)
  • func (w *WebIRCEntry) UnmarshalJSON(data []byte) error
• type WebIRCMap

Functions

func MigrateDump

func MigrateDump(dumpJSON []byte) ([]byte, error)

MigrateDump converts the output of scripts/migrate-config-dump.js into config.yaml bytes. It refuses (returning *UnsupportedFunctionError) if any __jsFunction marker is present, rather than silently dropping the behavior the marked value implemented.

func WriteStarterConfig

func WriteStarterConfig(path string) error

WriteStarterConfig writes the embedded defaults out to path as a real, user-editable config.yaml, if nothing already exists there. Mirrors start.ts's initalizeConfig: `relay start` calls this once on every startup, a no-op after the first run.

Types

type Avatars

type Avatars struct {
	Enable      bool `json:"enable"`
	MaxFileSize int  `json:"maxFileSize"`
}

type Branding

type Branding struct {
	LogoURL         string `json:"logoUrl"`
	LogoInvertedURL string `json:"logoInvertedUrl"`
}

type Config

type Config struct {
	// Desktop is an internal capability marker set by the native desktop
	// shell after configuration loading. It is intentionally excluded from
	// JSON decoding so config.yaml, admin-overrides.json, and -c overrides
	// cannot enable desktop-only behavior in a normal Relay server.
	Desktop                        bool            `json:"-"`
	Public                         bool            `json:"public"`
	AllowRegistration              bool            `json:"allowRegistration"`
	Host                           string          `json:"host,omitempty"`
	Port                           int             `json:"port"`
	Bind                           string          `json:"bind,omitempty"`
	ReverseProxy                   bool            `json:"reverseProxy"`
	MaxHistory                     int             `json:"maxHistory"`
	HTTPS                          HTTPS           `json:"https"`
	Theme                          string          `json:"theme"`
	Prefetch                       bool            `json:"prefetch"`
	DisableMediaPreview            bool            `json:"disableMediaPreview"`
	PrefetchStorage                bool            `json:"prefetchStorage"`
	PrefetchMaxImageSize           int             `json:"prefetchMaxImageSize"`
	PrefetchMaxSearchSize          int             `json:"prefetchMaxSearchSize"`
	PrefetchTimeout                int             `json:"prefetchTimeout"`
	PrefetchAllowInternalAddresses bool            `json:"prefetchAllowInternalAddresses"`
	FileUpload                     FileUpload      `json:"fileUpload"`
	ShortLink                      ShortLink       `json:"shortLink"`
	LeaveMessage                   string          `json:"leaveMessage"`
	Defaults                       NetworkDefaults `json:"defaults"`
	LockNetwork                    bool            `json:"lockNetwork"`
	MessageStorage                 []string        `json:"messageStorage"`
	Postgres                       Postgres        `json:"postgres"`
	StoragePolicy                  StoragePolicy   `json:"storagePolicy"`
	UseHexIP                       bool            `json:"useHexIp"`
	WebIRC                         WebIRCMap       `json:"webirc,omitempty"`
	Identd                         Identd          `json:"identd"`
	Oidentd                        string          `json:"oidentd,omitempty"`
	WebAuthn                       WebAuthn        `json:"webauthn"`
	Debug                          Debug           `json:"debug"`
	ThemeColor                     string          `json:"themeColor,omitempty"`
	Branding                       Branding        `json:"branding"`
	SMTP                           SMTP            `json:"smtp"`
	OIDC                           OIDC            `json:"oidc"`
	Jitsi                          Jitsi           `json:"jitsi"`
	Klipy                          Klipy           `json:"klipy"`
	Partyline                      Partyline       `json:"partyline"`
	Avatars                        Avatars         `json:"avatars"`
	Stats                          Stats           `json:"stats"`
}

Config mirrors server/config.ts's ConfigType. Field names and JSON tags match the equivalent keys in defaults/config.js exactly so config.yaml and admin-overrides.json stay recognizable to anyone who's used the Node backend's config.js.

The Socket.IO-specific "transports" key from the Node config is intentionally dropped: the Go backend speaks a custom WebSocket protocol (see internal/wsproto) and has no equivalent setting.

type Debug

type Debug struct {
	IRCFramework bool `json:"ircFramework"`
	Raw          bool `json:"raw"`
}

type FileUpload

type FileUpload struct {
	Enable         bool   `json:"enable"`
	MaxFileSize    int    `json:"maxFileSize"`
	ExpirationTime int    `json:"expirationTime"`
	BaseURL        string `json:"baseUrl,omitempty"`
}

type HTTPS

type HTTPS struct {
	Enable      bool   `json:"enable"`
	Key         string `json:"key"`
	Certificate string `json:"certificate"`
	CA          string `json:"ca"`
}

type Identd

type Identd struct {
	Enable bool `json:"enable"`
	Port   int  `json:"port"`
}

type JSFunctionMarker

type JSFunctionMarker struct {
	Source string `json:"__jsFunction"`
}

JSFunctionMarker is the exact JSON shape scripts/migrate-config-dump.js emits in place of a JS function value it can't represent (e.g. the "advanced" per-host webirc function form - see defaults/config.js).

type Jitsi

type Jitsi struct {
	Enable    bool   `json:"enable"`
	ServerURL string `json:"serverUrl"`
}

type Klipy

type Klipy struct {
	Enable bool   `json:"enable"`
	APIKey string `json:"apiKey"`
}

type Loaded

type Loaded struct {
	Values Config
	// contains filtered or unexported fields
}

Loaded is the result of Load: the merged, typed configuration plus the home directory it was loaded from (needed for the path helpers).

func Load

func Load(homePath string, cliOverrides []string) (*Loaded, error)

Load layers the configuration exactly like server/config.ts's setHome:

1. embedded defaults (defaults.yaml, replacing defaults/config.js)
2. <home>/config.yaml, if present (replacing config.js)
3. <home>/admin-overrides.json, if present (unchanged format)
4. CLI overrides (-c key.path=value, highest precedence)

Each layer after the first warns about unknown top-level keys and, within deepMerge, about type mismatches; arrays are replaced wholesale rather than merged. See merge.go for the exact semantics.

func (*Loaded) AdminOverridesPath

func (l *Loaded) AdminOverridesPath() string

func (*Loaded) ClientCertificatesPath

func (l *Loaded) ClientCertificatesPath() string

func (*Loaded) ConfigYAMLPath

func (l *Loaded) ConfigYAMLPath() string

func (*Loaded) DefaultNick

func (l *Loaded) DefaultNick() string

DefaultNick mirrors Config.getDefaultNick: percent signs in the configured default nick are replaced with random digits (e.g. "relay%%" -> "relay37").

func (*Loaded) FileUploadPath

func (l *Loaded) FileUploadPath() string

func (*Loaded) HomePath

func (l *Loaded) HomePath() string

func (*Loaded) InstalledPackagePath

func (l *Loaded) InstalledPackagePath(name string) string

InstalledPackagePath is where `relay install` extracts a package's files (internal/packages.Install), replacing Node's npm-managed packages/node_modules/<name> layout - there's no dependency graph to resolve, so a package is just a directory named after itself.

func (*Loaded) PackagesManifestPath

func (l *Loaded) PackagesManifestPath() string

PackagesManifestPath is the Go-native replacement for Node's packages/package.json "dependencies" object: which packages `relay install` has placed under PackagesPath, and where each came from (needed by `relay upgrade`/`relay outdated` to refetch).

func (*Loaded) PackagesPath

func (l *Loaded) PackagesPath() string

func (*Loaded) ShortLinksDBPath

func (l *Loaded) ShortLinksDBPath() string

func (*Loaded) StoragePath

func (l *Loaded) StoragePath() string

func (*Loaded) UserConfigPath

func (l *Loaded) UserConfigPath(name string) string

func (*Loaded) UserLogsPath

func (l *Loaded) UserLogsPath() string

func (*Loaded) UserThemesPath

func (l *Loaded) UserThemesPath() string

func (*Loaded) UsersPath

func (l *Loaded) UsersPath() string

type NetworkDefaults

type NetworkDefaults struct {
	Name               string `json:"name"`
	Host               string `json:"host"`
	Port               int    `json:"port"`
	Password           string `json:"password"`
	TLS                bool   `json:"tls"`
	RejectUnauthorized bool   `json:"rejectUnauthorized"`
	Nick               string `json:"nick"`
	Username           string `json:"username"`
	Realname           string `json:"realname"`
	LeaveMessage       string `json:"leaveMessage"`
	SASL               string `json:"sasl"`
	SASLAccount        string `json:"saslAccount"`
	SASLPassword       string `json:"saslPassword"`
	Join               string `json:"join"`
}

NetworkDefaults mirrors server/config.ts's Defaults type (a Pick<Network, ...> plus "join").

type OIDC

type OIDC struct {
	Enable        bool   `json:"enable"`
	Issuer        string `json:"issuer"`
	ClientID      string `json:"clientId"`
	ClientSecret  string `json:"clientSecret"`
	Scope         string `json:"scope"`
	UsernameClaim string `json:"usernameClaim"`
}

type Partyline

type Partyline struct {
	Enable      bool   `json:"enable"`
	NetworkName string `json:"networkName"`
	Name        string `json:"name"`
}

type Postgres

type Postgres struct {
	ConnectionString       string `json:"connectionString"`
	MaxOpenConns           int    `json:"maxOpenConns"`
	MaxIdleConns           int    `json:"maxIdleConns"`
	ConnMaxLifetimeMinutes int    `json:"connMaxLifetimeMinutes"`
}

type SMTP

type SMTP struct {
	Enable   bool   `json:"enable"`
	Host     string `json:"host"`
	Port     int    `json:"port"`
	Secure   bool   `json:"secure"`
	User     string `json:"user"`
	Password string `json:"password"`
	From     string `json:"from"`
}

type ShortLink

type ShortLink struct {
	Enable         bool   `json:"enable"`
	MinLength      int    `json:"minLength"`
	ExpirationTime int    `json:"expirationTime"`
	Path           string `json:"path"`
	BaseURL        string `json:"baseUrl,omitempty"`
	CodeLength     int    `json:"codeLength"`
}

type Stats

type Stats struct {
	CommandEnable   bool   `json:"commandEnable"`
	CommandTemplate string `json:"commandTemplate"`
}

Stats controls Relay's local-only /relaystats command. The command never sends its output to IRC; it renders a notice in the user's current Relay window.

type StoragePolicy

type StoragePolicy struct {
	Enabled        bool   `json:"enabled"`
	MaxAgeDays     int    `json:"maxAgeDays"`
	DeletionPolicy string `json:"deletionPolicy"` // "statusOnly" | "everything"
}

type UnsupportedFunctionError

type UnsupportedFunctionError struct {
	// Paths are dotted locations of each function value found (e.g.
	// "webirc.irc.example.com").
	Paths []string
}

UnsupportedFunctionError is returned by MigrateDump when the dumped config contains one or more JS function values that have no Go equivalent and must be translated by hand.

func (*UnsupportedFunctionError) Error

func (e *UnsupportedFunctionError) Error() string

type WebAuthn

type WebAuthn struct {
	RPID   string `json:"rpId"`
	RPName string `json:"rpName"`
}

type WebIRCEntry

type WebIRCEntry struct {
	Password       string `json:"password"`
	HostnamePrefix string `json:"hostnamePrefix,omitempty"`
}

WebIRCEntry is one host's WEBIRC configuration. The Node backend also allowed a per-host JS function that could mutate arbitrary fields of the generated WEBIRC object (see defaults/config.js's "Advanced" documentation for webirc); Go can't eval JS, so that form is not supported here. The only documented real-world use of the function form was prefixing the hostname, which HostnamePrefix covers directly.

This is a deliberate, documented behavior change from the Node config.

func (WebIRCEntry) MarshalJSON

func (w WebIRCEntry) MarshalJSON() ([]byte, error)

func (*WebIRCEntry) UnmarshalJSON

func (w *WebIRCEntry) UnmarshalJSON(data []byte) error

UnmarshalJSON accepts either a bare string (the shorthand form, `"irc.example.net": "password"`) or a structured object (`{"password": "...", "hostnamePrefix": "..."}`).

type WebIRCMap

type WebIRCMap map[string]WebIRCEntry

WebIRCMap is keyed by IRC host, matching the Node config's webirc object.