Documentation
¶
Overview ¶
Package settingspatch provides a unified type and merge algorithm for agentapi-proxy settings.
Design ¶
Every settings layer (base, team, user, oneshot) is represented as a SettingsPatch. The JSON format is identical to the format stored in Kubernetes Secrets, so no conversion is needed: json.Unmarshal(secretData, &patch) works directly.
Merge semantics per field type:
- String fields: "" = "not set, inherit from lower layer"; non-empty = override.
- Pointer fields: nil = "not set, inherit from lower layer"; non-nil = override.
- Map fields: absent key = inherit; nil value = explicitly delete; non-nil = override.
- Slice fields: accumulated (union) across all layers (plugins).
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BedrockPatch ¶
type BedrockPatch struct {
Model string `json:"model,omitempty"`
AccessKeyID string `json:"access_key_id,omitempty"`
SecretAccessKey string `json:"secret_access_key,omitempty"`
RoleARN string `json:"role_arn,omitempty"`
Profile string `json:"profile,omitempty"`
}
BedrockPatch holds AWS Bedrock configuration. Empty string fields are treated as "not set" and inherit from lower layers. Bedrock activation is controlled solely by AuthMode ("bedrock" = on, "oauth" = off). Legacy fields like "enabled" stored in Kubernetes Secrets are silently ignored.
type MCPServerPatch ¶
type MCPServerPatch struct {
Type string `json:"type,omitempty"`
URL string `json:"url,omitempty"`
Command string `json:"command,omitempty"`
Args []string `json:"args,omitempty"`
Env map[string]string `json:"env,omitempty"`
Headers map[string]string `json:"headers,omitempty"`
}
MCPServerPatch represents a single MCP server configuration. All fields are replaced as a whole when the server key is present.
type MarketplacePatch ¶
type MarketplacePatch struct {
URL string `json:"url"`
}
MarketplacePatch represents a single plugin marketplace configuration.
type MaterializedSettings ¶
type MaterializedSettings struct {
// EnvVars are the environment variables to inject into the session container.
EnvVars map[string]string
// SettingsJSON is the Claude settings JSON (marketplaces, plugins, hooks).
// nil if no settings to apply.
SettingsJSON map[string]interface{}
// MCPServers is the resolved MCP server configuration.
// nil if no MCP servers are configured.
MCPServers map[string]interface{}
// ActivePlugins is the final list of enabled plugins.
ActivePlugins []string
}
MaterializedSettings is the resolved, ready-to-use session configuration produced by Materialize().
func Materialize ¶
func Materialize(resolved SettingsPatch) (MaterializedSettings, error)
Materialize converts a resolved SettingsPatch into concrete session configuration.
This is the single place where all business logic lives:
- Auth mode decision (bedrock vs oauth vs unset)
- Env var validation and dangerous-variable filtering
- Plugin set operations
- Claude settings JSON assembly (marketplaces, plugins, hooks)
type SettingsPatch ¶
type SettingsPatch struct {
// AuthMode specifies the authentication mode: "oauth" or "bedrock".
// "" = inherit from lower layer (do not override auth-related env vars).
AuthMode string `json:"auth_mode,omitempty"`
// OAuthToken is the Claude Code OAuth token.
// "" = inherit from lower layer.
OAuthToken string `json:"claude_code_oauth_token,omitempty"`
// Bedrock holds AWS Bedrock configuration.
// nil = inherit from lower layer entirely.
// Non-nil = merge field by field (empty sub-fields still inherit).
Bedrock *BedrockPatch `json:"bedrock,omitempty"`
// MCPServers is the MCP server configuration map.
// Absent key = inherit from lower layer.
// nil value = explicitly delete server.
// Non-nil value = override/add server.
MCPServers map[string]*MCPServerPatch `json:"mcp_servers,omitempty"`
// EnvVars are custom environment variables.
// Absent key = inherit from lower layer.
// Last non-absent value wins (no delete semantics).
EnvVars map[string]string `json:"env_vars,omitempty"`
// Marketplaces is the plugin marketplace configuration map.
// Absent key = inherit from lower layer.
// nil value = explicitly delete marketplace.
// Non-nil value = override/add marketplace.
Marketplaces map[string]*MarketplacePatch `json:"marketplaces,omitempty"`
// Hooks is a map of event name → hook configuration.
// Later layers override earlier layers for the same event name.
Hooks map[string]interface{} `json:"hooks,omitempty"`
// EnabledPlugins lists plugins contributed by this layer.
// Accumulated (union) across all layers.
EnabledPlugins []string `json:"enabled_plugins,omitempty"`
}
SettingsPatch represents a single layer of settings configuration. It is the canonical type for both storage and merge operations.
Layers are resolved by Resolve() from lowest to highest priority:
base → team[0] → team[1] → ... → user → oneshot
func Apply ¶
func Apply(base, higher SettingsPatch) SettingsPatch
Apply merges higher on top of base and returns the resulting SettingsPatch. higher has priority over base for all fields.
This operation forms a monoid:
- Identity element: SettingsPatch{}
- Associativity: Apply(Apply(a, b), c) == Apply(a, Apply(b, c))
func FromJSON ¶
func FromJSON(data []byte) (SettingsPatch, error)
FromJSON parses raw JSON (settings.json Secret data) into a SettingsPatch.
The SettingsPatch JSON format is identical to the format stored in Kubernetes Secrets, so no field-by-field conversion is needed. Unknown fields (e.g. "name", "created_at", "updated_at", "bedrock.enabled") are silently ignored.
func Resolve ¶
func Resolve(layers ...SettingsPatch) SettingsPatch
Resolve folds a sequence of layers from lowest to highest priority and returns the effective SettingsPatch.
Usage:
resolved := Resolve(basePatch, teamPatch, userPatch, oneshotPatch)
Source Files