Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 11 additions & 1 deletion .env.example
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
# Copy this file to .env and replace the required values.
# Non-empty STICK_* values override values in config.yaml.
# Non-empty STICK_* values override values from earlier configuration providers.
# The callback URL for the OIDC client is <public-url>/auth/callback.

# Required application settings. A filesystem path selects SQLite;
Expand Down Expand Up @@ -44,3 +44,13 @@ STICK_AUTH_SESSION_SECRET=replace-with-at-least-32-random-bytes
# STICK_NOTIFICATIONS_SMTP_FROM=noreply@example.com
# STICK_NOTIFICATIONS_SMTP_SUBJECT={{.StickName}} is available
# STICK_NOTIFICATIONS_SMTP_BODY=The stick you were waiting for just dropped.

# Optional Azure App Configuration source. This is bootstrap configuration and
# is not read from the application YAML file. Use a managed identity or Azure
# Workload Identity in deployments; do not put a client secret here.
# STICK_CONFIG_PROVIDERS=azure-app-config,environment
# STICK_AZURE_APPCONFIG_ENDPOINT=https://stick-prod.azconfig.io
# STICK_AZURE_APPCONFIG_LABEL=production
# STICK_AZURE_APPCONFIG_KEY_PREFIX=stick/
# STICK_AZURE_APPCONFIG_KEY_FILTER=stick/*
# STICK_AZURE_APPCONFIG_SEPARATOR=/
39 changes: 37 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -80,11 +80,46 @@ install -d -m 0700 local-data
STICK_DATABASE="$PWD/local-data/stick.db" ./stickd -config config.yaml
```

- Configuration can be provided in YAML, environment variables, or both.
- Non-empty `STICK_*` variables override YAML values.
- Configuration can be provided in YAML, environment variables, Azure App
Configuration, or a combination of providers.
- Non-empty `STICK_*` variables override values from earlier providers.

See `.env.example` and `example.config.yaml` for the available settings.

### Azure App Configuration

Stick can also load configuration from Azure App Configuration. Select it with
the bootstrap setting below; `environment` remains last so ordinary `STICK_*`
overrides retain precedence:

```sh
STICK_CONFIG_PROVIDERS=azure-app-config,environment
STICK_AZURE_APPCONFIG_ENDPOINT=https://stick-prod.azconfig.io
STICK_AZURE_APPCONFIG_LABEL=production
STICK_AZURE_APPCONFIG_KEY_PREFIX=stick/
STICK_AZURE_APPCONFIG_SEPARATOR=/
```

When Azure is the only structured source, omit `-config`; when combining it
with a file, use `STICK_CONFIG_PROVIDERS=yaml,azure-app-config,environment`.

Use slash-separated keys such as `stick/database`,
`stick/server/public_url`, and `stick/auth/oidc/issuer`. Notification lists
should be stored as JSON values with the `application/json` content type.
The hierarchy separator is configurable (supported values include `/`, `.`,
`:` and `__`) and defaults to `/`.
Empty labels select unlabeled settings. Azure App Configuration Key Vault
references are resolved automatically when the identity can read the referenced
secrets.

Authentication uses Azure's default credential chain. In production, prefer a
managed identity or workload identity and grant it the **App Configuration Data
Reader** role (and **Key Vault Secrets User** when Key Vault references are
used). No Azure credentials are stored in the Stick configuration.

The provider loads a snapshot during startup. Configuration changes require a
Stick restart.

If you use MongoDB, it must be deployed as a replica set because Stick uses multi-document transactions.

## Development
Expand Down
53 changes: 49 additions & 4 deletions cmd/stickd/main.go
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@ import (
"log/slog"
"os"
"os/signal"
"strings"
"syscall"
"time"
_ "time/tzdata"
Expand Down Expand Up @@ -46,17 +47,19 @@ func mainContext(parent context.Context, args []string) (err error) {
flags := flag.NewFlagSet("stickd", flag.ContinueOnError)
flags.SetOutput(os.Stderr)
configPath := flags.String("config", "", "path to config YAML file (default: config.yaml in working directory)")
configProviders := flags.String("config-providers", "", "comma-separated configuration providers (default: yaml,environment)")
if err := flags.Parse(args); err != nil {
return err
}
if flags.NArg() != 0 {
return fmt.Errorf("unexpected positional arguments: %v", flags.Args())
}

cfg, err := config.Load(parent,
config.YAMLProvider{Path: *configPath},
config.EnvironmentProvider{},
)
providers, err := buildConfigProviders(*configPath, *configProviders)
if err != nil {
return fmt.Errorf("config: %w", err)
}
cfg, err := config.Load(parent, providers...)
if err != nil {
return fmt.Errorf("config: %w", err)
}
Expand Down Expand Up @@ -107,6 +110,48 @@ func mainContext(parent context.Context, args []string) (err error) {
return application.Run(shutdown, components...)
}

const defaultConfigProviders = "yaml,environment"

func buildConfigProviders(configPath, selection string) ([]config.Provider, error) {
selection = strings.TrimSpace(selection)
if selection == "" {
selection = strings.TrimSpace(os.Getenv("STICK_CONFIG_PROVIDERS"))
}
if selection == "" {
selection = defaultConfigProviders
}

var providers []config.Provider
hasYAML := false
for _, name := range strings.Split(selection, ",") {
name = strings.ToLower(strings.TrimSpace(name))
if name == "" {
return nil, fmt.Errorf("configuration provider list contains an empty provider name")
}
switch name {
case "yaml":
hasYAML = true
providers = append(providers, config.YAMLProvider{Path: configPath})
case "environment":
providers = append(providers, config.EnvironmentProvider{})
case "azure-app-config":
providers = append(providers, config.AzureAppConfigurationProvider{
Endpoint: os.Getenv("STICK_AZURE_APPCONFIG_ENDPOINT"),
Label: os.Getenv("STICK_AZURE_APPCONFIG_LABEL"),
KeyPrefix: os.Getenv("STICK_AZURE_APPCONFIG_KEY_PREFIX"),
KeyFilter: os.Getenv("STICK_AZURE_APPCONFIG_KEY_FILTER"),
Separator: os.Getenv("STICK_AZURE_APPCONFIG_SEPARATOR"),
})
default:
return nil, fmt.Errorf("unknown configuration provider %q", name)
}
}
if configPath != "" && !hasYAML {
return nil, fmt.Errorf("-config requires the yaml configuration provider")
}
return providers, nil
}

type backend interface {
application.Store
outbox.Store
Expand Down
69 changes: 69 additions & 0 deletions cmd/stickd/main_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,75 @@ func TestMainContextLogsBuildMetadata(t *testing.T) {
}
}

func TestBuildConfigProvidersDefaultsToYAMLThenEnvironment(t *testing.T) {
t.Setenv("STICK_CONFIG_PROVIDERS", "")
providers, err := buildConfigProviders("", "")
if err != nil {
t.Fatalf("buildConfigProviders: %v", err)
}
if len(providers) != 2 {
t.Fatalf("providers = %d, want 2", len(providers))
}
if _, ok := providers[0].(config.YAMLProvider); !ok {
t.Errorf("providers[0] = %T, want YAMLProvider", providers[0])
}
if _, ok := providers[1].(config.EnvironmentProvider); !ok {
t.Errorf("providers[1] = %T, want EnvironmentProvider", providers[1])
}
}

func TestBuildConfigProvidersReadsSelectionFromEnvironment(t *testing.T) {
t.Setenv("STICK_CONFIG_PROVIDERS", "environment, azure-app-config")
t.Setenv("STICK_AZURE_APPCONFIG_ENDPOINT", "https://stick.azconfig.io")
t.Setenv("STICK_AZURE_APPCONFIG_SEPARATOR", ".")
providers, err := buildConfigProviders("", "")
if err != nil {
t.Fatalf("buildConfigProviders: %v", err)
}
if len(providers) != 2 {
t.Fatalf("providers = %d, want 2", len(providers))
}
if _, ok := providers[0].(config.EnvironmentProvider); !ok {
t.Errorf("providers[0] = %T, want EnvironmentProvider", providers[0])
}
azure, ok := providers[1].(config.AzureAppConfigurationProvider)
if !ok {
t.Fatalf("providers[1] = %T, want AzureAppConfigurationProvider", providers[1])
}
if azure.Endpoint != "https://stick.azconfig.io" {
t.Errorf("Azure endpoint = %q", azure.Endpoint)
}
if azure.Separator != "." {
t.Errorf("Azure separator = %q", azure.Separator)
}
}

func TestBuildConfigProvidersCLISelectionOverridesEnvironment(t *testing.T) {
t.Setenv("STICK_CONFIG_PROVIDERS", "azure-app-config")
providers, err := buildConfigProviders("", "environment")
if err != nil {
t.Fatalf("buildConfigProviders: %v", err)
}
if len(providers) != 1 {
t.Fatalf("providers = %d, want 1", len(providers))
}
if _, ok := providers[0].(config.EnvironmentProvider); !ok {
t.Errorf("provider = %T, want EnvironmentProvider", providers[0])
}
}

func TestBuildConfigProvidersRequiresYAMLForExplicitConfigPath(t *testing.T) {
if _, err := buildConfigProviders("/etc/stick/config.yaml", "environment"); err == nil || !strings.Contains(err.Error(), "requires the yaml") {
t.Fatalf("buildConfigProviders error = %v", err)
}
}

func TestBuildConfigProvidersRejectsUnknownProvider(t *testing.T) {
if _, err := buildConfigProviders("", "unknown"); err == nil || !strings.Contains(err.Error(), "unknown configuration provider") {
t.Fatalf("buildConfigProviders error = %v", err)
}
}

func setMinimalRuntimeEnv(t *testing.T, databasePath string) {
t.Helper()
t.Setenv("STICK_DATABASE", databasePath)
Expand Down
7 changes: 5 additions & 2 deletions example.config.yaml
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Stick configuration
# Copy this file to config.yaml and replace the required values.
# Non-empty STICK_* environment variables override values in this file.
# Non-empty STICK_* environment variables override values from earlier
# providers. The provider chain itself is selected with STICK_CONFIG_PROVIDERS.
# The OIDC callback URL is <server.public_url>/auth/callback.

# Required: a filesystem path selects SQLite; a postgres://, postgresql://,
Expand Down Expand Up @@ -35,7 +36,9 @@ auth:
# Timezone for displaying notification timestamps (default: UTC).
# timezone: Europe/London

# Notifications are optional. Configure any combination of backends.
# Notifications are optional. Configure any combination of backends. When using
# Azure App Configuration, list values should use the application/json content
# type (for example, notifications/webhook).
# Webhook URLs must use HTTPS except for loopback addresses used locally.
# Each backend can be a mapping for one instance or a list for multiple
# instances of the same type.
Expand Down
12 changes: 12 additions & 0 deletions go.mod
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,10 @@ module stick
go 1.27.0

require (
github.com/Azure/AppConfiguration-GoProvider/azureappconfiguration v1.6.0
github.com/Azure/azure-sdk-for-go/sdk/azcore v1.21.0
github.com/Azure/azure-sdk-for-go/sdk/azidentity v1.13.1
github.com/Azure/azure-sdk-for-go/sdk/data/azappconfig/v2 v2.1.0
github.com/coreos/go-oidc/v3 v3.17.0
github.com/golang-jwt/jwt/v5 v5.3.1
github.com/jackc/pgx/v5 v5.10.0
Expand All @@ -16,7 +20,11 @@ require (

require (
dario.cat/mergo v1.0.2 // indirect
github.com/Azure/azure-sdk-for-go/sdk/internal v1.11.2 // indirect
github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/azsecrets v1.4.0 // indirect
github.com/Azure/azure-sdk-for-go/sdk/security/keyvault/internal v1.2.0 // indirect
github.com/Azure/go-ansiterm v0.0.0-20250102033503-faa5f7b0171c // indirect
github.com/AzureAD/microsoft-authentication-library-for-go v1.6.0 // indirect
github.com/Microsoft/go-winio v0.6.2 // indirect
github.com/cenkalti/backoff/v4 v4.3.0 // indirect
github.com/cespare/xxhash/v2 v2.3.0 // indirect
Expand All @@ -36,12 +44,14 @@ require (
github.com/go-logr/logr v1.4.3 // indirect
github.com/go-logr/stdr v1.2.2 // indirect
github.com/go-ole/go-ole v1.3.0 // indirect
github.com/go-viper/mapstructure/v2 v2.5.0 // indirect
github.com/golang/snappy v1.0.0 // indirect
github.com/google/uuid v1.6.0 // indirect
github.com/jackc/pgpassfile v1.0.0 // indirect
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
github.com/jackc/puddle/v2 v2.2.2 // indirect
github.com/klauspost/compress v1.18.7 // indirect
github.com/kylelemons/godebug v1.1.0 // indirect
github.com/lufia/plan9stats v0.0.0-20260330125221-c963978e514e // indirect
github.com/magiconair/properties v1.8.10 // indirect
github.com/mattn/go-isatty v0.0.20 // indirect
Expand All @@ -58,6 +68,7 @@ require (
github.com/ncruces/go-strftime v1.0.0 // indirect
github.com/opencontainers/go-digest v1.0.0 // indirect
github.com/opencontainers/image-spec v1.1.1 // indirect
github.com/pkg/browser v0.0.0-20240102092130-5ac0b6a4141c // indirect
github.com/pmezard/go-difflib v1.0.0 // indirect
github.com/power-devops/perfstat v0.0.0-20240221224432-82ca36839d55 // indirect
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
Expand All @@ -79,6 +90,7 @@ require (
go.opentelemetry.io/otel/metric v1.44.0 // indirect
go.opentelemetry.io/otel/trace v1.44.0 // indirect
golang.org/x/crypto v0.56.0 // indirect
golang.org/x/net v0.57.0 // indirect
golang.org/x/sync v0.22.0 // indirect
golang.org/x/sys v0.47.0 // indirect
golang.org/x/text v0.41.0 // indirect
Expand Down
Loading