settings

type AuthOIDC ¶ added in v0.7.0

type AuthOIDC struct {
	Enabled bool `json:"enabled"`

	// Issuer is the provider's issuer URL; endpoints are discovered from
	// its metadata document.
	Issuer   string `json:"issuer,omitempty"`
	ClientID string `json:"clientId,omitempty"`

	// ClientSecretEnv names the env var holding the client secret.
	// Indirection keeps the secret out of the settings row (world-readable
	// to any authenticated operator).
	ClientSecretEnv string `json:"clientSecretEnv,omitempty"`

	// RedirectURL is this relay's public callback,
	// e.g. https://relay.example.com/api/auth/oidc/callback.
	RedirectURL string `json:"redirectUrl,omitempty"`

	// Scopes defaults to ["openid", "profile", "email"].
	Scopes []string `json:"scopes,omitempty"`

	// AuthParams are extra authorization-URL query params some providers
	// require beyond the OIDC standard set (e.g. WorkOS AuthKit needs
	// {"provider": "authkit"}). Provider-specific values live here in
	// config, never in code.
	AuthParams map[string]string `json:"authParams,omitempty"`

	// Registration gates first-login auto-provisioning: "open" creates a
	// user row on first successful OIDC login; "closed" (default) rejects
	// subjects with no existing user row.
	Registration string `json:"registration,omitempty"`
}

AuthOIDC is the auth:oidc settings section: inbound OpenID Connect login for the control plane. Disabled by default — the zero value changes nothing about a deployment. When enabled, GET /auth/oidc/start redirects to the provider and /auth/oidc/callback exchanges the code and mints a normal relay session, so everything downstream of login is unchanged.

The provider is generic OIDC: any issuer publishing a discovery document (RFC 8414 / OpenID discovery) works. The client secret is referenced by env var name, never stored in the section value.

func AuthOIDCFrom(r Reader) *AuthOIDC

func (c *AuthOIDC) EffectiveScopes() []string

func (c *AuthOIDC) OpenRegistration() bool

func (c *AuthOIDC) Validate() error

type CatalogSource ¶ added in v0.5.0

type CatalogSource struct {
	// Version is the catalog ref (tag) the last versioned seed ran from,
	// e.g. "v0.1.0". Empty when the catalog was seeded without a version
	// (local dir / embedded first-boot seed) or never seeded.
	Version string `json:"version,omitempty"`

	// SeededAt is when that seed completed (RFC 3339).
	SeededAt string `json:"seededAt,omitempty"`
}

CatalogSource records the provenance of the seeded catalog. Written by the bootstrap seeder after a successful versioned seed; compared against RELAY_CATALOG_VERSION at boot to decide whether a re-seed is due. An operator can blank Version via the settings API to force a re-seed on the next boot. Re-seeds only touch pristine template rows: operator- edited (dirty) rows are skipped and overlays re-merge at snapshot load, so user changes survive.

func (c *CatalogSource) Validate() error

type Governance ¶

type Governance struct {
	AllowEdit   bool `json:"allowEdit"`
	AllowDelete bool `json:"allowDelete"`
}

Governance is the per-resource mutation policy: whether a catalog-managed row of a given kind may be edited or deleted through the generic control CRUD API. One value type is shared by every governance:<kind> section so the shape — and the decision logic in Governs — stays uniform.

These toggles are a speed-bump against accidental mutation, not a wall: editing catalog rows is rare but safe (the router self-heals; nothing hard-depends on a specific row surviving), so AllowEdit defaults true. Deleting is the click-around risk, so AllowDelete defaults false and an operator flips it on when they actually mean to prune.

func (g *Governance) Validate() error

type Inference ¶

type Inference struct {
	// AllowMissingPolicy permits a RelayKey with an empty Spec.PolicyID
	// to reach inference endpoints. The request bypasses the per-policy
	// authorization gate: any model served by any host the relay has
	// hostkeys for is reachable, with no policy-level rate limits (system
	// ratelimits still apply). When false, requests from such keys are
	// rejected with 403.
	//
	// Default false. Turn on only for self-hosted setups where the
	// operator is the caller (single-tenant) and wants a god-mode key.
	AllowMissingPolicy bool `json:"allowMissingPolicy"`
}

Inference controls authenticated-flow behavior.

func (i *Inference) Validate() error

type MutationError ¶

type MutationError struct {
	Op        Op
	Kind      string
	OwnerKind string
	Reason    string
}

MutationError is returned by Governs when an operation is not permitted. The control layer maps it to a 403.

func (e *MutationError) Error() string

type OAuthProvider ¶ added in v0.4.2

type OAuthProvider struct {
	oauth.ProviderConfig
}

OAuthProvider is the typed value of an oauth:<provider> settings section: the flow config (authorize/token endpoints, client id, scopes, authorize params) used to acquire and refresh that provider's OAuth credentials.

The relay core ships only this generic shape. Concrete provider values are operator/community config — register a provider's section with RegisterOAuthProvider and supply the values via the settings API or a config/settings/oauth-<provider>.yaml. No provider is registered by default.

func (c *OAuthProvider) Validate() error

type Op ¶

type Op string

Op is a mutating operation subject to the governance check.

const (
	OpEdit   Op = "edit"
	OpDelete Op = "delete"
)

type Parsing ¶

type Parsing struct {
	// RichParsing extracts per-request metadata and messages from the
	// body (for attribution / observability). When false the relay
	// reads only the minimal fields needed to route (model, stream),
	// leaving metadata and messages unparsed — lower CPU on the hot
	// path, no body-level observability.
	//
	// Default true. Hot-swappable: a change takes effect on the next
	// request within a reconcile interval, no restart.
	RichParsing bool `json:"richParsing"`
}

Parsing controls inbound request-body parsing depth.

func (p *Parsing) Validate() error

type PayloadClickHouse ¶

type PayloadClickHouse struct {
	// RetentionDays overrides the MergeTree TTL; 0 uses the backend default.
	RetentionDays int `json:"retentionDays,omitempty"`
	// WALDir overrides the local WAL segment directory; empty uses the
	// boot default.
	WALDir string `json:"walDir,omitempty"`
}

PayloadClickHouse configures the ClickHouse backend (Langfuse-style: text bodies as ZSTD String columns, queryable). The DSN is NOT stored here — it reuses the relay's boot CH connection (RELAY_CH_DSN, the same cluster the usage sink uses), so no credentials live in this row. Only the per-backend knobs that are safe to hot-swap live here.

type PayloadFile ¶

type PayloadFile struct {
	Path string `json:"path"`
}

PayloadFile configures the JSONL file backend.

type PayloadLogging ¶

type PayloadLogging struct {
	// Enabled is the global master switch. When false the observer
	// produces nothing regardless of per-request opt-in.
	Enabled bool `json:"enabled"`

	// Backend selects the sink: "file" (default), "s3", or "clickhouse".
	Backend string `json:"backend"`

	// MaxBytes caps each stored body, measured on the DECODED plaintext
	// (compressed upstream bodies are decoded before capture); 0 = unlimited.
	MaxBytes int `json:"maxBytes"`

	File PayloadFile       `json:"file"`
	S3   PayloadS3         `json:"s3"`
	CH   PayloadClickHouse `json:"clickhouse"`
}

PayloadLogging configures the payloadlog observer. Off by default; the per-request opt-in (policy/relaykey) still gates capture on top of Enabled. Credentials are secret.Refs resolved via pkg/secret, so they can live in env, encrypted-PG, or a future external backend — never as plaintext in this row.

func (p *PayloadLogging) Validate() error

type PayloadS3 ¶

type PayloadS3 struct {
	Endpoint  string     `json:"endpoint"`
	Bucket    string     `json:"bucket"`
	Region    string     `json:"region,omitempty"`
	Prefix    string     `json:"prefix,omitempty"`
	UseSSL    bool       `json:"useSSL"`
	AccessKey secret.Ref `json:"accessKey"`
	SecretKey secret.Ref `json:"secretKey"`
}

PayloadS3 configures the object-store backend. AccessKey/SecretKey are secret.Refs (kind env or stored), resolved at sink-build time.

type ProxyMode ¶

type ProxyMode struct {
	// Enabled turns the proxy flow on. When false, requests without a
	// valid relay key get 401, regardless of any other field below.
	Enabled bool `json:"enabled"`

	// AllowUnauthenticated lets proxy callers reach the upstream with
	// no relay-side auth — the inbound Authorization header is forwarded
	// as-is. When false, the proxy flow still requires a relay key
	// (proxied traffic gets logged against that key) but the upstream
	// credential comes from the caller.
	AllowUnauthenticated bool `json:"allowUnauthenticated"`
}

ProxyMode controls whether the relay accepts inference requests where the caller brings their own upstream provider key instead of a relay key. The flow lives in app/proxy (not yet built); this section gates the dispatch at the inference handler.

func (p *ProxyMode) Validate() error

type Reader ¶

type Reader interface {
	Setting(section string) (any, bool)
}

Reader is the narrow read surface Governs needs — satisfied by *catalog.Catalog. Settings cache reads are lock-free and total (a registered section always returns at least its Defaults).

type Row ¶

type Row struct {
	Section   string
	Value     any
	UpdatedAt time.Time
}

Row is a single settings row, decoded into a typed value via its section's Decode func. UpdatedAt is informational.

type Section ¶

type Section struct {
	Name        string
	Description string
	Defaults    func() any
	Decode      func([]byte) (any, error)
	SchemaRef   string
}

Section describes one known settings section. Defaults returns a fresh zero-value instance; Decode parses raw JSON into a typed value and validates it; SchemaRef is the OpenAPI component name of the typed value's schema (set automatically by the per-section registerSettingsSection helper); Description is operator-facing prose explaining the section's purpose.

func Lookup(name string) (Section, bool)

type SectionName ¶

type SectionName string

SectionName is a typed string whose OpenAPI schema is a string enum of every registered section. Use it in handler request/response types instead of bare `string` so the generated spec carries the closed set of valid section keys.

func (SectionName) Schema(_ huma.Registry) *huma.Schema

type Store ¶

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

Store is the data-access layer for settings rows.

func NewStore(q *gen.Queries) *Store

func (s *Store) Get(ctx context.Context, section string) (*Row, error)

func (s *Store) List(ctx context.Context) ([]*Row, error)

func (s *Store) Upsert(ctx context.Context, section string, raw json.RawMessage) (*Row, error)

type UsageClickHouse ¶

type UsageClickHouse struct {
	RetentionDays int    `json:"retentionDays,omitempty"`
	WALDir        string `json:"walDir,omitempty"`
}

UsageClickHouse holds the safe-to-hot-swap CH knobs. The DSN reuses the boot CH connection (bootstrap-tier), so no credentials live in this row.

type UsageFile ¶

type UsageFile struct {
	Path string `json:"path,omitempty"`
}

UsageFile configures the JSONL file backend.

type UsageLogging ¶

type UsageLogging struct {
	// Backend selects the sink+reader: "file" (default), "clickhouse",
	// "postgres", or "valkey".
	Backend string `json:"backend"`

	File UsageFile       `json:"file"`
	CH   UsageClickHouse `json:"clickhouse"`
}

UsageLogging selects and tunes the log/usage event backend. Per the config direction (minimize env), the backend choice lives here, not in env; the legacy RELAY_EVENTLOG_BACKEND is honored only as an interim fallback when this section is unset, until the YAML→DB settings seed lands.

func (u *UsageLogging) Validate() error