Documentation
¶
Index ¶
- Variables
- func DefaultAllowedDomains() []string
- func DefaultPath() (string, error)
- func Get(tree Tree, path string) (any, error)
- func GetPath(tree Tree, path string) (value any, ok bool)
- func IsForgeEntryPath(path string) (id string, ok bool)
- func IsOAuthProviderEntryPath(path string) (name string, ok bool)
- func IsServiceEntryPath(path string) (name string, ok bool)
- func ParseLogLevel(s string) (slog.Level, error)
- func ValidateDomainEntry(entry string) error
- func ValidateKnownKeys(tree Tree) error
- func WriteFileAtomic(path string, data []byte, perm os.FileMode) (retErr error)
- type Config
- type FieldKind
- type FieldSpec
- type ForgeConfig
- type GCConfig
- type GatewayConfig
- type LogConfig
- type NotifyConfig
- type OAuthProviderConfig
- type ReloadClass
- type SandboxConfig
- type ServiceAuthConfig
- type ServiceConfig
- type TaskAskConfig
- type Tree
- type WebConfig
Constants ¶
This section is empty.
Variables ¶
var LogLevelNames = []string{"debug", "info", "warn", "error"}
LogLevelNames is the accepted set of config.yaml log.level values, in the same order schema.go's "log.level" KindEnum leaf exposes as its EnumValues (so `boid config set log.level <bogus>`'s error message and this package's own ParseLogLevel error message list the exact same options — see TestLogLevelNames_MatchesParseLogLevel).
var Schema = []FieldSpec{ {Path: "gc.enabled", Kind: KindBool, Reload: ReloadRestartRequired}, {Path: "gc.interval", Kind: KindDuration, Reload: ReloadRestartRequired}, {Path: "gc.older_than", Kind: KindDuration, Reload: ReloadRestartRequired}, {Path: "log.level", Kind: KindEnum, Reload: ReloadRestartRequired, EnumValues: LogLevelNames}, {Path: "web.public_url", Kind: KindString, Reload: ReloadRestartRequired}, {Path: "web.http_addr", Kind: KindString, Reload: ReloadRestartRequired}, {Path: "notify.command", Kind: KindStringArray, Reload: ReloadRestartRequired}, {Path: "sandbox.allowed_domains", Kind: KindStringArray, Reload: ReloadRestartRequired}, {Path: "sandbox.egress_proxy_port_low", Kind: KindInt, Reload: ReloadRestartRequired}, {Path: "sandbox.egress_proxy_port_high", Kind: KindInt, Reload: ReloadRestartRequired}, {Path: "sandbox.backend", Kind: KindOpaque, Reload: ReloadRestartRequired, Note: "removed in the volume-only cutover (docs/plans/volume-only-daemon.md §論点e) — container is the only sandbox backend now"}, {Path: "task_ask.disconnect_grace", Kind: KindDuration, Reload: ReloadRestartRequired}, {Path: "gateway.forges.*.host", Kind: KindString, Reload: ReloadRestartRequired}, {Path: "gateway.forges.*.forge", Kind: KindEnum, Reload: ReloadRestartRequired, EnumValues: []string{"github", "bitbucket"}}, {Path: "gateway.forges.*.secret_key", Kind: KindString, Reload: ReloadRestartRequired}, {Path: "gateway.hosts", Kind: KindOpaque, Reload: ReloadRestartRequired, Note: "migrate to gateway.forges.<id>.* instead (see docs/ja/reference/config-yaml.md)"}, {Path: "services.*.base_url", Kind: KindString, Reload: ReloadRestartRequired}, {Path: "services.*.allow_insecure", Kind: KindBool, Reload: ReloadRestartRequired}, {Path: "services.*.auth.kind", Kind: KindEnum, Reload: ReloadRestartRequired, EnumValues: []string{"bearer", "basic", "header", "query", "oauth2"}}, {Path: "services.*.auth.secret_key", Kind: KindString, Reload: ReloadRestartRequired}, {Path: "services.*.auth.username", Kind: KindString, Reload: ReloadRestartRequired}, {Path: "services.*.auth.header", Kind: KindString, Reload: ReloadRestartRequired}, {Path: "services.*.auth.query", Kind: KindString, Reload: ReloadRestartRequired}, {Path: "services.*.auth.provider", Kind: KindString, Reload: ReloadRestartRequired}, {Path: "services_floor", Kind: KindStringArray, Reload: ReloadRestartRequired}, {Path: "oauth_providers.*.token_endpoint", Kind: KindString, Reload: ReloadRestartRequired}, {Path: "oauth_providers.*.client_id", Kind: KindString, Reload: ReloadRestartRequired}, {Path: "oauth_providers.*.client_secret_key", Kind: KindString, Reload: ReloadRestartRequired}, {Path: "oauth_providers.*.scopes", Kind: KindStringArray, Reload: ReloadRestartRequired}, {Path: "oauth_providers.*.grant", Kind: KindEnum, Reload: ReloadRestartRequired, EnumValues: []string{"authorization_code", "client_credentials"}}, {Path: "oauth_providers.*.flow", Kind: KindEnum, Reload: ReloadRestartRequired, EnumValues: []string{"device", "loopback", "manual"}}, {Path: "oauth_providers.*.authorization_endpoint", Kind: KindString, Reload: ReloadRestartRequired}, {Path: "oauth_providers.*.device_authorization_endpoint", Kind: KindString, Reload: ReloadRestartRequired}, {Path: "oauth_providers.*.authorize_params.*", Kind: KindString, Reload: ReloadRestartRequired}, }
Schema is every leaf path `boid config set/get/unset` (and `apply`'s structural validation) recognizes. Order matches config.yaml's own section order (config.go's Config struct field order) for readability in error messages / help output that enumerates it.
Functions ¶
func DefaultAllowedDomains ¶ added in v0.1.0
func DefaultAllowedDomains() []string
DefaultAllowedDomains returns boid's built-in sandbox.allowed_domains floor — the domains every daemon allows regardless of what config.yaml says (common AI-agent/package-registry endpoints). Exported (moved here from cmd/start.go, which now delegates to it) so internal/server's config-hot-reload path (config_edit.go's applyDynamicConfigLocked) can recompute "floor ∪ user list" on every sandbox.allowed_domains change without internal/server needing to import cmd (which would cycle) or duplicate this literal (BLOCKER 2 sibling fix, codex review round 1: the pre-fix hot-reload replaced the whole effective list with the sparse YAML-only entries, silently dropping every built-in domain the very next time an operator touched sandbox.allowed_domains at all).
A fresh copy is returned on every call — callers may freely mutate/append to the result.
func DefaultPath ¶ added in v0.1.0
DefaultPath resolves the default XDG config.yaml path (~/.config/boid/config.yaml) without reading it. Exported so callers that need the *path* itself — not just its parsed content — have one place to ask (internal/server's daemon-side config-editing wiring, docs/plans/ volume-only-daemon.md §論点 f: `boid config get/set/unset/apply/edit` reads-modifies-writes this exact file) instead of re-deriving os.UserConfigDir()+"boid/config.yaml" independently and risking drift from what Load() itself actually reads.
func Get ¶ added in v0.1.0
Get resolves a dotted path against tree for `boid config get <key>`. Returns the raw value (a scalar, []any, or Tree) and an error naming the closest known key when path is not a recognized schema leaf/container.
func GetPath ¶ added in v0.1.0
GetPath reads the value at a dotted path in tree. ok is false when any segment along the way is absent, or an intermediate segment resolves to a non-map value (a scalar/array sitting where a nested key was expected).
func IsForgeEntryPath ¶ added in v0.1.0
IsForgeEntryPath reports whether path names a whole gateway.forges.<id> entry (exactly "gateway.forges.<id>", no further segment) — the one dotted path `boid config unset` treats specially, per docs/plans/ volume-only-daemon.md §論点 f's unilateral decision: "Removing a map entry (e.g. gateway.forges.github) removes the whole entry." id is returned when ok is true.
func IsOAuthProviderEntryPath ¶ added in v0.1.0
IsOAuthProviderEntryPath reports whether path names a whole oauth_providers.<name> entry (exactly "oauth_providers.<name>", no further segment) — IsServiceEntryPath's counterpart for the OAuth2 provider registry (docs/plans/api-gateway.md §6/§論点4, PR2), given the same "removing a map entry removes the whole entry" treatment `boid config unset` gives gateway.forges.<id> and services.<name>. name is returned when ok is true.
func IsServiceEntryPath ¶ added in v0.1.0
IsServiceEntryPath reports whether path names a whole services.<name> entry (exactly "services.<name>", no further segment) — the API gateway's counterpart to IsForgeEntryPath above, given the identical "removing a map entry removes the whole entry" treatment `boid config unset` gives gateway.forges.<id> (docs/plans/volume-only-daemon.md §論点 f). Without this, "boid config unset services.myapp" fell through to the ordinary ResolveField path — which correctly reports it as not a Set/Get leaf (schema_test.go's own `{"services.myapp", false}` case, annotated "same as gateway.forges.github") — but Unset had no matching special case to actually act on that "same as" comment, so the whole- entry removal gateway.forges.<id> gets was silently absent for services.<name> despite the parity the test comment implied. name is returned when ok is true.
func ParseLogLevel ¶ added in v0.1.0
ParseLogLevel maps a config.yaml log.level string to its slog.Level constant. It is the single source of truth both Config.UnmarshalYAML (load-time validation — an unrecognized string is a hard config error, same treatment as an unrecognized gateway.forges.*.forge value) and the daemon's own startup wiring (internal/daemon.ApplyLogLevel, which calls slog.SetLogLoggerLevel with the result) consult, so the two can never silently disagree about which strings are valid.
func ValidateDomainEntry ¶ added in v0.1.0
ValidateDomainEntry validates a single sandbox.allowed_domains entry's syntax. Exported so `boid config set sandbox.allowed_domains ...`/`apply`/ `edit` all share this one check (dotted.go's Set does not itself know about per-Kind semantic constraints beyond parsing, so validate.go's ValidateYAML pass is what actually enforces this — see its own doc comment).
func ValidateKnownKeys ¶ added in v0.1.0
ValidateKnownKeys walks tree against the schema trie, rejecting any key (at any depth) that has no corresponding schema entry. Every gateway.forges.<id> map entry's id is accepted as a wildcard match, but the fields inside it are still checked against {host, forge, secret_key}.
func WriteFileAtomic ¶ added in v0.0.13
WriteFileAtomic writes data to path via a sibling temp file + rename, so concurrent readers (or a crash mid-write) never observe a partially written file. The temp file is created in the same directory as path (so the final os.Rename is same-filesystem and atomic), synced to disk before close, and removed on any error path before return — an existing file at path is left untouched unless the write fully succeeds.
The temp file's name is derived from path's own basename (".<base>.*") rather than hardcoded. It used to be the literal ".config.yaml.*", which was the same string for config.yaml and stayed correct only as long as this function had exactly one caller; PR9 of docs/plans/workspace-home-volume-persistence.md added a second (a workspace's init.sh, dispatcher.WorkspaceInitScriptStore.Write), and a crash-leftover named ".config.yaml.1234" sitting next to a workspace's init.sh is a false lead for whoever finds it. Behaviour for the original caller is unchanged: filepath.Base("…/config.yaml") is "config.yaml", so the pattern it gets is byte-identical to the old constant.
Types ¶
type Config ¶
type Config struct {
GC GCConfig `yaml:"gc"`
Log LogConfig `yaml:"log"`
Web WebConfig `yaml:"web"`
Notify NotifyConfig `yaml:"notify"`
Sandbox SandboxConfig `yaml:"sandbox"`
TaskAsk TaskAskConfig `yaml:"task_ask"`
Gateway GatewayConfig `yaml:"gateway"`
// Services declares the API gateway's service registry (docs/plans/
// api-gateway.md §2) — a top-level key, deliberately NOT nested under
// Gateway (which is git-gateway-specific: per-forge Basic-auth
// credential config). See ServiceConfig's own doc comment.
Services map[string]ServiceConfig `yaml:"services,omitempty"`
// ServicesFloor is the daemon-wide set of service names enabled for
// EVERY workspace, mirroring sandbox.allowed_domains' own floor role
// (docs/plans/api-gateway.md §3: "allowed_domains の floor + workspace
// 加算方式を鏡写しにする"). A workspace's own
// WorkspaceMeta.Services list adds to this floor — see
// orchestrator.ResolveEnabledServices. An entry naming a service not
// declared under Services is not a load error (see UnmarshalYAML's
// handling below) — it just never resolves to anything at dispatch
// time, the same lenient-string-list posture allowed_domains' floor has
// always had.
ServicesFloor []string `yaml:"services_floor,omitempty"`
// OAuthProviders declares the API gateway's OAuth2 provider registry
// (docs/plans/api-gateway.md §6/§論点4, PR2: "config.yaml の
// oauth_providers: ブロック。client_secret のみ SecretStore 参照"), keyed
// by provider name — the same name a services.<name>.auth.provider
// entry references. A provider reference naming an entry not declared
// here is not a config-load error — see
// TestLoadFromPath_Services_OAuth2ProviderReferenceNotCrossValidated's
// doc comment (oauth_providers_test.go) for why: it fails at request
// time instead, with a clear error, the same "unresolvable reference
// surfaces at request time, not load time" contract every other
// secret-store-shaped reference in this file already has.
OAuthProviders map[string]OAuthProviderConfig `yaml:"oauth_providers,omitempty"`
}
Config holds the global boid configuration.
func DefaultConfig ¶
func DefaultConfig() *Config
DefaultConfig returns the default boid configuration.
func Load ¶
Load reads the configuration from the default XDG path (~/.config/boid/config.yaml). If the file does not exist, the default configuration is returned without error.
func LoadFromPath ¶ added in v0.1.0
LoadFromPath is loadFromPath's exported counterpart (PR834 PR-2b round-3 codex review Major 2, docs/plans/volume-only-daemon.md §論点f): a pure filesystem read + yaml.v3 decode with no daemon/HTTP dependency at all — unlike `boid config get` (cmd/config.go), which always talks to a live daemon's HTTP API and therefore has no bootstrap-before-first-boot path. Exported so any standalone tooling can resolve a config.yaml's EFFECTIVE values — including the strict validation UnmarshalYAML performs — against an arbitrary path, not just the CLI process's own XDG default. Same not-found semantics as Load()/loadFromPath: a missing file returns DefaultConfig(), not an error.
Formerly also the primitive behind `boid config effective-backend` (scripts/deploy-container.sh's pre-PR-4 config-seed validation step) — that subcommand was removed in PR-4 (docs/plans/volume-only-daemon.md §論点e) once "container" became the only sandbox backend, so there was no longer an effective backend selection worth validating. LoadFromPath itself stays exported as a general-purpose primitive.
func ValidateYAML ¶ added in v0.1.0
ValidateYAML decodes and fully validates a candidate config.yaml document, returning the resolved *Config on success. data may be a full document (a `boid config apply -f`/`edit` body) or a partial one built by Set/Unset starting from an already-valid tree — either way, every key present must resolve against Schema, and the document must decode cleanly through Config.UnmarshalYAML.
func (Config) APIGatewayOAuthProviders ¶ added in v0.1.0
func (c Config) APIGatewayOAuthProviders() []apigateway.OAuthProviderConfig
APIGatewayOAuthProviders resolves c.OAuthProviders into the flat []apigateway.OAuthProviderConfig list apigateway.NewOAuth2TokenSource consumes (internal/server/wire.go), sorted by name for determinism. Mirrors APIGatewayServices' own shape and "already validated by Config.UnmarshalYAML" invariant — an entry that fails validateOAuthProviderConfig here (a hand-built Config that skipped validation) is skipped silently rather than surfaced as an error, since this method has no error return and never should have one under that invariant.
func (Config) APIGatewayServices ¶ added in v0.1.0
func (c Config) APIGatewayServices() []apigateway.ServiceConfig
APIGatewayServices resolves c.Services into the flat []apigateway.ServiceConfig list apigateway.NewCredentialProvider consumes (internal/server/wire.go), sorted by name for determinism. Mirrors GatewayConfig.HostConfigs's own shape and its "already validated by Config.UnmarshalYAML" invariant — an entry that fails validateServiceConfig here (a hand-built Config that skipped validation) is skipped silently rather than surfaced as an error, since this method has no error return and never should have one under that invariant.
type FieldKind ¶ added in v0.1.0
type FieldKind int
FieldKind describes the shape of value a schema leaf accepts.
const ( // KindString is a single scalar string. KindString FieldKind = iota // KindBool is a single scalar bool ("true"/"false"). KindBool // KindDuration is a single scalar Go duration string (e.g. "24h"). KindDuration // KindInt is a single scalar integer (e.g. a TCP port). KindInt // KindStringArray is zero or more scalar strings (`boid config set` multi-arg). KindStringArray // KindEnum is a single scalar string constrained to EnumValues. KindEnum // KindOpaque is a structurally-recognized leaf whose value is NOT // `boid config set/unset`-able — it exists in Schema purely so // ValidateKnownKeys (validate.go's pass 1, the unknown-key trie walk) // does not reject a path the daemon still structurally accepts // elsewhere (Config.UnmarshalYAML's own decode pass, ValidateYAML's // pass 2). Its shape (list, map, whatever) is validated by that pass 2 // decode, not duplicated here. coerceValues (dotted.go) rejects any // `boid config set` attempt against a KindOpaque leaf with a // dedicated message rather than falling through to the generic // "unsupported field kind" text (MAJOR 1, codex review round 1 — see // gateway.hosts and sandbox.backend below, the two KindOpaque entries // today) — see FieldSpec.Note for how that message's field-specific // tail is authored per leaf. KindOpaque )
type FieldSpec ¶ added in v0.1.0
type FieldSpec struct {
Path string
Kind FieldKind
Reload ReloadClass
EnumValues []string
// Note is an optional field-specific clause appended to a KindOpaque
// leaf's generic "not settable"/"not unsettable" rejection message
// (dotted.go's coerceValues/Unset) — e.g. where to migrate instead.
// Empty leaves the generic message with no follow-up clause. Every
// other Kind ignores this field.
Note string
}
FieldSpec describes one CLI-editable scalar/array leaf in config.yaml. Path is dotted, with "*" standing in for a single wildcard segment (only ever gateway.forges.<any-id> today).
func ResolveField ¶ added in v0.1.0
ResolveField looks up the FieldSpec matching a concrete dotted path (no wildcards in path itself — path is what a user typed, e.g. "gateway.forges.github.host"). Returns (nil, false) when no schema leaf matches — the caller (dotted.go) is responsible for turning that into a helpful "unknown key" error, since only it has the surrounding tree to offer a closest-match suggestion against.
type ForgeConfig ¶ added in v0.0.11
type ForgeConfig struct {
// Host is the upstream host as it appears in the gateway route path
// (e.g. "github.com"). Optional for built-in ids; required otherwise.
Host string `yaml:"host,omitempty"`
// Forge selects the Basic-auth username convention
// (gitgateway.ForgeGitHub / gitgateway.ForgeBitbucket). Optional for
// built-in ids; required otherwise.
Forge gitgateway.Forge `yaml:"forge,omitempty"`
// SecretKey is a reference into the secret store
// (internal/dispatcher/secret_store.go); never a plaintext token.
// Optional for built-in ids (defaults below); required otherwise.
SecretKey string `yaml:"secret_key,omitempty"`
}
ForgeConfig configures the git gateway's credential injection for a single forge id (the map key in GatewayConfig.Forges). Only the forge kind and a secret-store key reference are ever written here — the plaintext PAT itself lives in the secret store (`boid secret set <key> <value>`), never in config.yaml.
Built-in ids ("github", "bitbucket") default every field left empty here (see builtinForges): host, Basic-auth forge convention, and secret-store key all resolve without the user writing anything, so `gateway.forges: {github: {}}` — or omitting the id entirely, since DefaultConfig pre-populates both built-ins — is enough for `boid secret set github-pat <PAT>` to light up the gateway for github.com. Custom ids (e.g. "github-enterprise") must set Host explicitly, and Forge must name one of gitgateway's recognized conventions since that convention is not itself derivable from an arbitrary id.
type GCConfig ¶
type GCConfig struct {
Enabled bool `yaml:"-"`
Interval time.Duration `yaml:"-"`
OlderThan time.Duration `yaml:"-"`
}
GCConfig holds garbage collection settings.
type GatewayConfig ¶ added in v0.0.10
type GatewayConfig struct {
// Forges maps a forge id (e.g. "github", "bitbucket", or a custom id
// like "github-enterprise") to its credential config. Built-in ids
// "github" and "bitbucket" are pre-populated by DefaultConfig with
// host/forge/secret_key defaults already filled in — see builtinForges.
Forges map[string]ForgeConfig `yaml:"forges,omitempty"`
}
GatewayConfig configures the git gateway's per-forge credential injection (post-cutover §2: config surface を forges map に圧縮 + github/bitbucket を内蔵デフォルト化). Forges maps a forge id to its credential config; Config.UnmarshalYAML also accepts the deprecated pre-forges-map `gateway.hosts` list (docs/plans/git-gateway-cutover.md PR4's original schema) and folds it into this map, so GatewayConfig itself only ever needs to carry the one shape.
func (GatewayConfig) HostConfigs ¶ added in v0.0.11
func (g GatewayConfig) HostConfigs() []gitgateway.HostForgeConfig
HostConfigs resolves g.Forges into the flat gitgateway.HostForgeConfig list gitgateway.NewCredentialProvider consumes (internal/server/wire.go), applying built-in defaults per resolveForgeConfig. Entries are returned in id-sorted order for determinism.
INVARIANT: callers must only invoke this on a GatewayConfig that has already been validated by Config.UnmarshalYAML — that is the sole place gateway.forges entries are validated, so on a validated config every entry resolves successfully. A resolution failure here is defensive-only (a hand-built GatewayConfig that skipped validation) and is skipped silently rather than surfaced as an error, since HostConfigs has no error return and never should have one under the invariant.
type LogConfig ¶ added in v0.1.0
type LogConfig struct {
// Level is one of LogLevelNames ("debug"/"info"/"warn"/"error").
// Config.UnmarshalYAML rejects any other non-empty value as a hard
// config-load error (ParseLogLevel), the same treatment
// gateway.forges.*.forge's unrecognized-forge case and gc.interval's
// invalid-duration case already get elsewhere in this file — a typo'd
// level should fail `boid start`/`boid config apply` loudly, not
// silently fall back to some default.
Level string `yaml:"level,omitempty"`
}
LogConfig holds daemon logging settings.
Level controls slog's built-in bridge-to-log-package minimum level (slog.SetLogLoggerLevel — applied once at daemon startup by internal/daemon.ApplyLogLevel, called from cmd/start.go's runDaemonChild) WITHOUT installing a custom slog.Handler and WITHOUT changing boid.log's line format at all. Nothing in the daemon calls slog.SetDefault or installs a Handler (grep the whole tree — internal/dispatcher/ container_backend_workspace_init.go's own doc comment notes this exact fact), so every slog.Info/Debug/Warn/Error call already goes through slog's package-private defaultHandler, which formats via the standard "log" package (today's "2009/11/10 23:00:00 INFO msg key=value" lines) and checks slog.SetLogLoggerLevel's threshold before emitting anything. Calling that one function is therefore sufficient to gate slog.Debug output on/off — it changes nothing about HOW a line is formatted, only WHETHER a given level's line is emitted at all. A real TextHandler/ JSONHandler would instead produce "time=... level=... msg=..." lines, breaking every existing boid.log-grepping runbook (daemon liveness checks, etc.) — which is exactly why this package never installs one.
Empty (the zero value, and every config.yaml written before this field existed) means "leave slog's own built-in default (info) alone" — the exact pre-this-field behavior, byte-for-byte.
type NotifyConfig ¶
type NotifyConfig struct {
Command []string `yaml:"command"`
}
NotifyConfig holds settings for agent-driven notifications.
type OAuthProviderConfig ¶ added in v0.1.0
type OAuthProviderConfig struct {
// TokenEndpoint is the provider's OAuth2 token endpoint (RFC 6749
// §3.2), e.g. https://accounts.secure.freee.co.jp/public_api/token.
// Always https — see validateOAuthProviderConfig's own doc comment for
// why there is no allow_insecure-style escape hatch here.
TokenEndpoint string `yaml:"token_endpoint"`
// ClientID is the OAuth2 client_id. Not a secret by RFC 6749 §2.2's own
// classification (a public identifier), so — unlike ClientSecretKey —
// it is written directly here rather than referenced through the
// secret store.
ClientID string `yaml:"client_id"`
// ClientSecretKey is a secret-store key reference (never a plaintext
// value) for a confidential client's client_secret (docs/plans/
// api-gateway.md §7: "confidential client の client_secret を daemon 側
// にのみ置く"). Empty for a public client (PKCE, no client_secret) —
// apigateway.OAuth2TokenSource simply omits client_secret from the
// token request when this is empty.
ClientSecretKey string `yaml:"client_secret_key,omitempty"`
// Scopes is consumed by `boid secret oauth login`'s authorization-URL
// construction (loopback/manual) and device-authorization request
// (device) — docs/plans/api-gateway.md §7, PR3. Never sent on an
// authorization_code refresh_token grant; see
// apigateway.OAuth2TokenSource.callRefreshTokenEndpoint's own doc comment
// for why. A client_credentials grant (§6-補, PR4) DOES send Scopes on
// every token request — see callClientCredentialsTokenEndpoint instead.
Scopes []string `yaml:"scopes,omitempty"`
// Flow selects which of the three initial-grant flows (docs/plans/
// api-gateway.md §7 "flow の三段構え", PR3) `boid secret oauth login
// <service>` uses for this provider: "device" / "loopback" / "manual".
// Empty ("") means this provider has no login flow configured — an
// operator can still seed refresh_token by hand via `boid secret set`
// (PR2's own documented fallback), but `boid secret oauth login` for it
// fails with a clear "no flow configured" error rather than guessing.
// Deliberately OPTIONAL (not required on every entry): an existing
// config.yaml written against PR2 alone — token_endpoint/client_id/
// client_secret_key only, refresh_token seeded by hand — must keep
// loading without modification once PR3 ships.
Flow string `yaml:"flow,omitempty"`
// AuthorizationEndpoint is the provider's OAuth2 authorization endpoint
// (RFC 6749 §3.1) — required (and only meaningful) when Flow is
// "loopback" or "manual".
AuthorizationEndpoint string `yaml:"authorization_endpoint,omitempty"`
// DeviceAuthorizationEndpoint is the provider's RFC 8628 §3.1 device
// authorization endpoint — required (and only meaningful) when Flow is
// "device".
DeviceAuthorizationEndpoint string `yaml:"device_authorization_endpoint,omitempty"`
// AuthorizeParams is a fixed set of extra parameters appended verbatim
// to the authorization request (loopback/manual: query parameters;
// device: form fields on the device authorization request) — see
// apigateway.OAuthProviderConfig.AuthorizeParams' own doc comment for
// the motivating example (Google's access_type/prompt). Keys colliding
// with a protocol-reserved parameter are rejected below.
AuthorizeParams map[string]string `yaml:"authorize_params,omitempty"`
// Grant selects which RFC 6749 grant apigateway.OAuth2TokenSource.
// refresh performs for this provider (docs/plans/api-gateway.md §6-補):
// "authorization_code" (the default — every 3-legged/delegated flow
// this package supported before §6-補) or "client_credentials" (RFC
// 6749 §4.4, 2-legged / app-only, Service Principal). Deliberately
// OPTIONAL and a SEPARATE field from Flow, not a fourth Flow value —
// see apigateway.OAuthProviderConfig.Grant's own doc comment for why.
// Empty ("") means "authorization_code", so an existing PR2/PR3
// config.yaml (written before this field existed) keeps loading
// unmodified.
Grant string `yaml:"grant,omitempty"`
}
OAuthProviderConfig declares one config.yaml oauth_providers.<name> entry — the OAuth2 token-endpoint identity a services.*.auth.kind: oauth2 entry's `provider` field references (docs/plans/api-gateway.md §6/§論点4: "config.yaml の oauth_providers: ブロック。client_secret のみ SecretStore 参照"). PR2 only ever performed a refresh_token grant against TokenEndpoint; PR3 adds Flow/AuthorizationEndpoint/ DeviceAuthorizationEndpoint/AuthorizeParams for `boid secret oauth login <service>` (docs/plans/api-gateway.md §7 "初回認証").
type ReloadClass ¶ added in v0.1.0
type ReloadClass int
ReloadClass classifies whether the daemon can apply a changed leaf live (docs/plans/volume-only-daemon.md §論点 f "reload semantics" table).
const ( // ReloadDynamic keys are hot-reloaded silently (an info log line, no // operator-facing warning) as soon as the daemon accepts the write. // // No Schema leaf uses this class today — the PR #830 round-4 // simplification pass (nose directive) folded sandbox.allowed_domains, // notify.command, and web.public_url (the only three that ever did) into // ReloadRestartRequired. The codex review trajectory that shipped the // hot-reload machinery for those three (Runner.AllowedDomains as a // func() []string getter, Server.AllowedDomains(), a per-dispatch // ProxyAllocator.GetOrCreate refresh for the no-workspace proxy // listener) took 4 rounds and 2→1→1→2 blockers to land, including a // Server.Stop/dispatch deadlock (round 4 blocker 2) — a complexity/value // ratio nose judged not worth it for a config surface this young. The // constant and this ReloadClass distinction are kept (not deleted) so a // future genuinely-safe-to-hot-reload leaf has an obvious place to go // without re-litigating the enum. ReloadDynamic ReloadClass = iota // ReloadRestartRequired keys are persisted but only take effect on the // next daemon restart — the daemon prints a loud warning naming the // restart command. ReloadRestartRequired )
func Set ¶ added in v0.1.0
func Set(tree Tree, path string, values []string) (ReloadClass, error)
Set validates and applies `boid config set <key> <value...>` against tree, returning the ReloadClass the caller should report to the operator. Fails when path is not a scalar/array schema leaf (an unresolved path, or one resolving to a struct/map slot like a bare "gateway.forges.github" — docs/plans/volume-only-daemon.md §論点 f's unilateral decision: set never targets a whole map entry, only unset does) — or when the given values don't match the leaf's Kind (wrong arity, bad enum, unparseable duration/bool).
func Unset ¶ added in v0.1.0
func Unset(tree Tree, path string) (ReloadClass, error)
Unset validates and applies `boid config unset <key>` against tree, returning the ReloadClass the caller should report. Three shapes:
- a whole gateway.forges.<id> entry ("gateway.forges.github") removes the entire map entry — the unilateral decision documented on IsForgeEntryPath.
- a whole services.<name> entry ("services.myapp") removes the entire map entry too — IsServiceEntryPath's identical treatment, docs/plans/ api-gateway.md §2.
- any other recognized scalar/array leaf removes just that key.
Fails with "key not found" when the path is unrecognized OR is recognized but not currently present in tree — per §論点 f's unilateral decision, unset never silently no-ops on a missing key.
MINOR 1 (codex review round 2): a KindOpaque leaf (gateway.hosts, the only one today) is documented as non-settable AND non-unsettable (schema.go's KindOpaque doc comment, docs/ja/reference/config-yaml.md's "旧 gateway.hosts 記法" section) — Set already rejects it via coerceValues's dedicated KindOpaque branch, but this generic path had no equivalent check and happily deleted it, silently letting `boid config unset gateway.hosts` "succeed" despite the documented read-only contract. The check runs before the presence check below (deletePathRaw) so the rejection reason is always "read-only", never "key not found", regardless of whether the key happens to be present in tree.
type SandboxConfig ¶
type SandboxConfig struct {
AllowedDomains []string `yaml:"allowed_domains"`
// EgressProxyPortLow/High bound the port band the egress proxy
// allocates each workspace's stable listener port from, inclusive
// (docs/plans/egress-proxy-stable-port.md).
//
// Both zero (the default, and every config.yaml written before these
// keys existed) means "use internal/sandbox's own default band", which
// sits below the kernel's ephemeral port range on purpose — see
// sandbox.DefaultProxyPortRangeLow's doc comment. Override only when
// that assumption does not hold locally, e.g. an operator who has
// lowered net.ipv4.ip_local_port_range so the default band overlaps it.
EgressProxyPortLow int `yaml:"egress_proxy_port_low,omitempty"`
EgressProxyPortHigh int `yaml:"egress_proxy_port_high,omitempty"`
}
SandboxConfig holds sandbox-related settings.
Backend (formerly a SandboxBackendKind field selecting "userns" vs "container") was removed in PR-4 (docs/plans/volume-only-daemon.md §論点e): container is now the only sandbox backend, so there is nothing left to select. An old config.yaml that still sets sandbox.backend keeps loading without error — see UnmarshalYAML's handling below — the key is just parsed-and-ignored, with a warning logged.
type ServiceAuthConfig ¶ added in v0.1.0
type ServiceAuthConfig struct {
// Kind selects the injection strategy: "bearer" / "basic" / "header" /
// "query" (implemented, PR1) or "oauth2" (reserved — schema only, PR2
// adds the actual TokenSource; docs/plans/api-gateway.md PR1 scope note).
Kind string `yaml:"kind"`
// SecretKey is a reference into the secret store
// (internal/dispatcher/secret_store.go); never a plaintext value.
// Required for bearer/basic/header/query; unused for oauth2.
SecretKey string `yaml:"secret_key,omitempty"`
// Username is the Basic-auth username. Required (and only meaningful)
// for kind: basic.
Username string `yaml:"username,omitempty"`
// Header is the header name to set. Required (and only meaningful) for
// kind: header.
Header string `yaml:"header,omitempty"`
// Query is the query parameter name to set. Required (and only
// meaningful) for kind: query.
Query string `yaml:"query,omitempty"`
// Provider names the OAuth2 provider (config.yaml oauth_providers:
// block, PR2 — docs/plans/api-gateway.md §論点4). Required (and only
// meaningful) for kind: oauth2; unused and unvalidated in PR1 beyond
// "must be non-empty".
Provider string `yaml:"provider,omitempty"`
}
ServiceAuthConfig configures how the API gateway authenticates requests to one service. docs/plans/api-gateway.md §2 ("service registry (config.yaml)") / §4 ("credential 注入"). Which fields are required depends on Kind — see validateServiceConfig.
type ServiceConfig ¶ added in v0.1.0
type ServiceConfig struct {
// BaseURL is the upstream base URL (scheme + host, optionally a path
// prefix) — never exposed to the sandbox; only the logical service name
// in the route path is (docs/plans/api-gateway.md §1).
BaseURL string `yaml:"base_url"`
Auth ServiceAuthConfig `yaml:"auth"`
// AllowInsecure must be explicitly set to true for BaseURL to use any
// scheme other than "https" (codex review finding, round 4: a bare
// warning-only posture is not fail-closed — an operator who never reads
// boid.log has no signal that a credential is crossing the network in
// cleartext). Required, not merely warned-about, so choosing a plaintext
// upstream is always a conscious, config-visible decision — see
// validateServiceConfig's own doc comment for why plaintext is still
// SUPPORTED at all (PR1's stated primary use case: an internal test/ops
// API that legitimately has no TLS yet).
AllowInsecure bool `yaml:"allow_insecure,omitempty"`
}
ServiceConfig declares one logical service the API gateway can proxy job requests to. docs/plans/api-gateway.md §2.
type TaskAskConfig ¶ added in v0.0.7
type TaskAskConfig struct {
// DisconnectGrace is how long an awaiting task may sit with no live agent
// parked (the agent's `boid task ask` was killed by a harness command-timeout
// and disconnected) before the daemon reclaims it. The agent normally
// re-asks within one command-timeout and re-attaches; the grace bounds the
// case where it never returns.
DisconnectGrace time.Duration `yaml:"-"`
}
TaskAskConfig holds settings for the blocking `boid task ask` Q&A RPC.
type Tree ¶ added in v0.1.0
Tree is the generic YAML representation `boid config get/set/unset` operates on: the same shape `yaml.Unmarshal(data, &tree)` produces for a config.yaml document (nested map[string]any / []any / scalar values). Operating on this generic shape — rather than the typed Config struct — mirrors the existing `boid web set-addr`/`set-url` local-edit pattern (cmd/web.go): it round-trips only the keys actually present, so an unrelated section of a hand-authored config.yaml a user never touches through this CLI is never silently reshaped.
func ParseTree ¶ added in v0.1.0
ParseTree decodes a YAML document into the generic Tree dotted-path operations act on, guaranteeing a non-nil map even for a genuinely empty document. Shared by cmd/config.go's client-side parseConfigTree (which delegates here) and internal/server's MutateConfig (BLOCKER 1, codex review round 1's server-side read-modify-write) so both ends of the GET/mutate/POST-body round trip decode identically.