Documentation
¶
Overview ¶
Package config provides a go-simpler.org/env configuration table and helpers for working with the list of key/value lists stored in .env files.
IMPORTANT: This file is the SINGLE SOURCE OF TRUTH for all environment variables. All configuration options MUST be defined here with proper `env` struct tags. Never use os.Getenv() directly in other packages - pass configuration via structs. This ensures all options appear in `./orly help` output and are documented.
For database backends, use GetDatabaseConfigValues() to extract database-specific settings, then construct a database.DatabaseConfig in the caller (e.g., main.go).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func GetEnv ¶
func GetEnv() (requested bool)
GetEnv checks if the first command line argument is "env" and returns whether the environment configuration should be printed.
Return Values ¶
- requested: A boolean indicating true if the 'env' argument was provided, false otherwise.
Expected Behaviour ¶
The function returns true when the first command line argument is "env" (case-insensitive), signalling that the environment configuration should be printed. Otherwise, it returns false.
func HelpRequested ¶
func HelpRequested() (help bool)
HelpRequested determines if the command line arguments indicate a request for help
Return Values ¶
- help: A boolean value indicating true if a help flag was detected in the command line arguments, false otherwise
Expected Behaviour ¶
The function checks the first command line argument for common help flags and returns true if any of them are present. Returns false if no help flag is found
func IdentityRequested ¶ added in v0.8.0
func IdentityRequested() (requested bool)
IdentityRequested checks if the first command line argument is "identity" and returns whether the relay identity should be printed and the program should exit.
Return Values
- requested: true if the 'identity' subcommand was provided, false otherwise.
func PrintEnv ¶
PrintEnv outputs sorted environment key/value pairs from a configuration object to the provided writer
Parameters ¶
cfg: Pointer to the configuration object containing env tags
printer: Destination for the output, typically an io.Writer implementation
Expected Behaviour ¶
Outputs each environment variable derived from the config's struct tags in sorted order, formatted as "key=value\n" to the specified writer
func PrintHelp ¶
PrintHelp prints help information including application version, environment variable configuration, and details about .env file handling to the provided writer
Parameters ¶
cfg: Configuration object containing app name and config directory path
printer: Output destination for the help text
Expected Behaviour ¶
Prints application name and version followed by environment variable configuration details, explains .env file behaviour including automatic loading and custom path options, and displays current configuration values using PrintEnv. Outputs all information to the specified writer
func ServeRequested ¶ added in v0.30.2
func ServeRequested() (requested bool)
ServeRequested checks if the first command line argument is "serve" and returns whether the relay should start in ephemeral serve mode with RAM-based storage.
Return Values
- requested: true if the 'serve' subcommand was provided, false otherwise.
func VersionRequested ¶ added in v0.32.0
func VersionRequested() (requested bool)
VersionRequested checks if the first command line argument is "version" and returns whether the version should be printed and the program should exit.
Return Values
- requested: true if the 'version' subcommand was provided, false otherwise.
Types ¶
type C ¶
type C struct {
AppName string `env:"ORLY_APP_NAME" usage:"set a name to display on information about the relay" default:"ORLY"`
DataDir string `env:"ORLY_DATA_DIR" usage:"storage location for the event store" default:"~/.local/share/ORLY"`
Listen string `env:"ORLY_LISTEN" default:"0.0.0.0" usage:"network listen address"`
Port int `env:"ORLY_PORT" default:"3334" usage:"port to listen on"`
HealthPort int `env:"ORLY_HEALTH_PORT" default:"0" usage:"optional health check HTTP port; 0 disables"`
EnableShutdown bool `` /* 142-byte string literal not displayed */
LogLevel string `env:"ORLY_LOG_LEVEL" default:"info" usage:"relay log level: fatal error warn info debug trace"`
DBLogLevel string `env:"ORLY_DB_LOG_LEVEL" default:"info" usage:"database log level: fatal error warn info debug trace"`
DBBlockCacheMB int `env:"ORLY_DB_BLOCK_CACHE_MB" default:"512" usage:"Badger block cache size in MB (higher improves read hit ratio)"`
DBIndexCacheMB int `env:"ORLY_DB_INDEX_CACHE_MB" default:"256" usage:"Badger index cache size in MB (improves index lookup performance)"`
DBZSTDLevel int `` /* 127-byte string literal not displayed */
LogToStdout bool `env:"ORLY_LOG_TO_STDOUT" default:"false" usage:"log to stdout instead of stderr"`
Pprof string `env:"ORLY_PPROF" usage:"enable pprof in modes: cpu,memory,allocation,heap,block,goroutine,threadcreate,mutex"`
PprofPath string `env:"ORLY_PPROF_PATH" usage:"optional directory to write pprof profiles into (inside container); default is temporary dir"`
PprofHTTP bool `env:"ORLY_PPROF_HTTP" default:"false" usage:"if true, expose net/http/pprof on port 6060"`
IPWhitelist []string `` /* 159-byte string literal not displayed */
IPBlacklist []string `` /* 146-byte string literal not displayed */
Admins []string `env:"ORLY_ADMINS" usage:"comma-separated list of admin npubs"`
Owners []string `` /* 138-byte string literal not displayed */
ACLMode string `env:"ORLY_ACL_MODE" usage:"ACL mode: follows, managed (nip-86), none" default:"none"`
AuthRequired bool `env:"ORLY_AUTH_REQUIRED" usage:"require authentication for all requests (works with managed ACL)" default:"false"`
AuthToWrite bool `` /* 135-byte string literal not displayed */
BootstrapRelays []string `env:"ORLY_BOOTSTRAP_RELAYS" usage:"comma-separated list of bootstrap relay URLs for initial sync"`
NWCUri string `env:"ORLY_NWC_URI" usage:"NWC (Nostr Wallet Connect) connection string for Lightning payments"`
SubscriptionEnabled bool `` /* 139-byte string literal not displayed */
MonthlyPriceSats int64 `env:"ORLY_MONTHLY_PRICE_SATS" default:"6000" usage:"price in satoshis for one month subscription (default ~$2 USD)"`
RelayURL string `env:"ORLY_RELAY_URL" usage:"base URL for the relay dashboard (e.g., https://relay.example.com)"`
RelayAddresses []string `` /* 150-byte string literal not displayed */
RelayPeers []string `` /* 162-byte string literal not displayed */
RelayGroupAdmins []string `env:"ORLY_RELAY_GROUP_ADMINS" usage:"comma-separated list of npubs authorized to publish relay group configuration events"`
ClusterAdmins []string `env:"ORLY_CLUSTER_ADMINS" usage:"comma-separated list of npubs authorized to manage cluster membership"`
FollowListFrequency time.Duration `env:"ORLY_FOLLOW_LIST_FREQUENCY" usage:"how often to fetch admin follow lists (default: 1h)" default:"1h"`
// Blossom blob storage service level settings
BlossomServiceLevels string `` /* 152-byte string literal not displayed */
// Web UI and dev mode settings
WebDisableEmbedded bool `env:"ORLY_WEB_DISABLE" default:"false" usage:"disable serving the embedded web UI; useful for hot-reload during development"`
WebDevProxyURL string `` /* 147-byte string literal not displayed */
// Sprocket settings
SprocketEnabled bool `env:"ORLY_SPROCKET_ENABLED" default:"false" usage:"enable sprocket event processing plugin system"`
// Spider settings
SpiderMode string `env:"ORLY_SPIDER_MODE" default:"none" usage:"spider mode for syncing events: none, follows"`
// Directory Spider settings
DirectorySpiderEnabled bool `env:"ORLY_DIRECTORY_SPIDER" default:"false" usage:"enable directory spider for metadata sync (kinds 0, 3, 10000, 10002)"`
DirectorySpiderInterval time.Duration `env:"ORLY_DIRECTORY_SPIDER_INTERVAL" default:"24h" usage:"how often to run directory spider"`
DirectorySpiderMaxHops int `env:"ORLY_DIRECTORY_SPIDER_HOPS" default:"3" usage:"maximum hops for relay discovery from seed users"`
PolicyEnabled bool `` /* 135-byte string literal not displayed */
PolicyPath string `` /* 150-byte string literal not displayed */
// NIP-43 Relay Access Metadata and Requests
NIP43Enabled bool `env:"ORLY_NIP43_ENABLED" default:"false" usage:"enable NIP-43 relay access metadata and invite system"`
NIP43PublishEvents bool `env:"ORLY_NIP43_PUBLISH_EVENTS" default:"true" usage:"publish kind 8000/8001 events when members are added/removed"`
NIP43PublishMemberList bool `env:"ORLY_NIP43_PUBLISH_MEMBER_LIST" default:"true" usage:"publish kind 13534 membership list events"`
NIP43InviteExpiry time.Duration `env:"ORLY_NIP43_INVITE_EXPIRY" default:"24h" usage:"how long invite codes remain valid"`
// Database configuration
DBType string `env:"ORLY_DB_TYPE" default:"badger" usage:"database backend to use: badger or neo4j"`
QueryCacheDisabled bool `` /* 135-byte string literal not displayed */
QueryCacheSizeMB int `` /* 132-byte string literal not displayed */
QueryCacheMaxAge string `env:"ORLY_QUERY_CACHE_MAX_AGE" default:"5m" usage:"maximum age for cached query results (e.g., 5m, 10m, 1h)"`
// Neo4j configuration (only used when ORLY_DB_TYPE=neo4j)
Neo4jURI string `env:"ORLY_NEO4J_URI" default:"bolt://localhost:7687" usage:"Neo4j bolt URI (only used when ORLY_DB_TYPE=neo4j)"`
Neo4jUser string `env:"ORLY_NEO4J_USER" default:"neo4j" usage:"Neo4j authentication username (only used when ORLY_DB_TYPE=neo4j)"`
Neo4jPassword string `env:"ORLY_NEO4J_PASSWORD" default:"password" usage:"Neo4j authentication password (only used when ORLY_DB_TYPE=neo4j)"`
// Advanced database tuning
SerialCachePubkeys int `` /* 136-byte string literal not displayed */
SerialCacheEventIds int `` /* 139-byte string literal not displayed */
// Connection concurrency control
MaxHandlersPerConnection int `` /* 148-byte string literal not displayed */
// Adaptive rate limiting (PID-controlled)
RateLimitEnabled bool `env:"ORLY_RATE_LIMIT_ENABLED" default:"true" usage:"enable adaptive PID-controlled rate limiting for database operations"`
RateLimitTargetMB int `env:"ORLY_RATE_LIMIT_TARGET_MB" default:"0" usage:"target memory limit in MB (0=auto-detect: 66% of available, min 500MB)"`
RateLimitWriteKp float64 `env:"ORLY_RATE_LIMIT_WRITE_KP" default:"0.5" usage:"PID proportional gain for write operations"`
RateLimitWriteKi float64 `env:"ORLY_RATE_LIMIT_WRITE_KI" default:"0.1" usage:"PID integral gain for write operations"`
RateLimitWriteKd float64 `env:"ORLY_RATE_LIMIT_WRITE_KD" default:"0.05" usage:"PID derivative gain for write operations (filtered)"`
RateLimitReadKp float64 `env:"ORLY_RATE_LIMIT_READ_KP" default:"0.3" usage:"PID proportional gain for read operations"`
RateLimitReadKi float64 `env:"ORLY_RATE_LIMIT_READ_KI" default:"0.05" usage:"PID integral gain for read operations"`
RateLimitReadKd float64 `env:"ORLY_RATE_LIMIT_READ_KD" default:"0.02" usage:"PID derivative gain for read operations (filtered)"`
RateLimitMaxWriteMs int `env:"ORLY_RATE_LIMIT_MAX_WRITE_MS" default:"1000" usage:"maximum delay for write operations in milliseconds"`
RateLimitMaxReadMs int `env:"ORLY_RATE_LIMIT_MAX_READ_MS" default:"500" usage:"maximum delay for read operations in milliseconds"`
RateLimitWriteTarget float64 `env:"ORLY_RATE_LIMIT_WRITE_TARGET" default:"0.85" usage:"PID setpoint for writes (throttle when load exceeds this, 0.0-1.0)"`
RateLimitReadTarget float64 `env:"ORLY_RATE_LIMIT_READ_TARGET" default:"0.90" usage:"PID setpoint for reads (throttle when load exceeds this, 0.0-1.0)"`
RateLimitEmergencyThreshold float64 `` /* 153-byte string literal not displayed */
RateLimitRecoveryThreshold float64 `` /* 145-byte string literal not displayed */
RateLimitEmergencyMaxMs int `env:"ORLY_RATE_LIMIT_EMERGENCY_MAX_MS" default:"5000" usage:"maximum delay for writes in emergency mode (milliseconds)"`
// TLS configuration
TLSDomains []string `env:"ORLY_TLS_DOMAINS" usage:"comma-separated list of domains to respond to for TLS"`
Certs []string `` /* 152-byte string literal not displayed */
// Cluster replication configuration
ClusterPropagatePrivilegedEvents bool `` /* 152-byte string literal not displayed */
// ServeMode is set programmatically by the 'serve' subcommand to grant full owner
// access to all users (no env tag - internal use only)
ServeMode bool
}
C holds application configuration settings loaded from environment variables and default values. It defines parameters for app behaviour, storage locations, logging, and network settings used across the relay service.
func New ¶
New creates and initializes a new configuration object for the relay application
Return Values ¶
cfg: A pointer to the initialized configuration struct containing default or environment-provided values
err: An error object that is non-nil if any operation during initialization fails
Expected Behaviour: ¶
Initializes a new configuration instance by loading environment variables and checking for a .env file in the default configuration directory. Sets logging levels based on configuration values and returns the populated configuration or an error if any step fails
func (*C) GetDatabaseConfigValues ¶ added in v0.31.8
func (cfg *C) GetDatabaseConfigValues() ( dataDir, logLevel string, blockCacheMB, indexCacheMB, queryCacheSizeMB int, queryCacheMaxAge time.Duration, queryCacheDisabled bool, serialCachePubkeys, serialCacheEventIds int, zstdLevel int, neo4jURI, neo4jUser, neo4jPassword string, )
GetDatabaseConfigValues returns the database configuration values as individual fields. This avoids circular imports with pkg/database while allowing main.go to construct a database.DatabaseConfig with the correct type.
func (*C) GetRateLimitConfigValues ¶ added in v0.34.7
func (cfg *C) GetRateLimitConfigValues() ( enabled bool, targetMB int, writeKp, writeKi, writeKd float64, readKp, readKi, readKd float64, maxWriteMs, maxReadMs int, writeTarget, readTarget float64, emergencyThreshold, recoveryThreshold float64, emergencyMaxMs int, )
GetRateLimitConfigValues returns the rate limiting configuration values. This avoids circular imports with pkg/ratelimit while allowing main.go to construct a ratelimit.Config with the correct type.
type KVSlice ¶
type KVSlice []KV
KVSlice is a sortable slice of key/value pairs, designed for managing configuration data and enabling operations like merging and sorting based on keys.
func EnvKV ¶
EnvKV generates key/value pairs from a configuration object's struct tags
Parameters ¶
- cfg: A configuration object whose struct fields are processed for env tags
Return Values ¶
- m: A KVSlice containing key/value pairs derived from the config's env tags
Expected Behaviour ¶
Processes each field of the config object, extracting values tagged with "env" and converting them to strings. Skips fields without an "env" tag. Handles various value types including strings, integers, booleans, durations, and string slices by joining elements with commas.
func (KVSlice) Compose ¶
Compose merges two KVSlice instances into a new slice where key-value pairs from the second slice override any duplicate keys from the first slice.
Parameters ¶
- kv2: The second KVSlice whose entries will be merged with the receiver.
Return Values ¶
- out: A new KVSlice containing all entries from both slices, with keys from kv2 taking precedence over keys from the receiver.
Expected Behaviour ¶
The method returns a new KVSlice that combines the contents of the receiver and kv2. If any key exists in both slices, the value from kv2 is used. The resulting slice remains sorted by keys as per the KVSlice implementation.
Source Files
¶
- config.go