diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 6bbf08b..21a9cfc 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -18,7 +18,7 @@ jobs: # Star* module's pipeline. Pinned to a commit SHA for supply-chain safety; # bump the pin when meta's workflow changes (Dependabot github-actions can # automate this). - uses: 1set/meta/.github/workflows/go-ci.yml@496f38088eff1a37bae1b43d158146a8a9d83a37 + uses: 1set/meta/.github/workflows/go-ci.yml@6b334e6a2762acaeefcea9fc7d3e86964e9246be with: go-floor: "1.19" doc-coverage: true diff --git a/README.md b/README.md index 7a3edd1..aabfeed 100644 --- a/README.md +++ b/README.md @@ -14,23 +14,24 @@ The `starpkg` ecosystem gives Starlark scripts *support for the necessary for ease of use.* `base` is the layer beneath all of that: not itself a local capability or an online-service binding, but the **shared plumbing** every domain module (`sqlite`, `web`, `llm`, `mq`, `s3`, `email`, …) uses to declare its typed -configuration, resolve it from values / getters / environment / defaults, keep -secrets out of scripts, and surface the result to Starlark. +configuration, resolve it from values / getters / environment / defaults, and +control which configuration accessors are available to Starlark. It provides: - **Type-safe configuration** using Go generics (`ConfigOption[T]`). - **Multiple configuration sources** with a fixed precedence: explicit value → getter → environment variable → default. -- **Secret value handling** so sensitive options are settable but never readable - from a script. +- **Secret value handling**: no generated getter for a secret option; it remains + script-settable unless it is also host-only. - **Environment-variable integration**, with automatic string-to-type parsing. - **Automatic Starlark wiring**: `LoadModule` generates a `set_` setter for every non-host-only option and a `get_` getter for every non-secret option. -`base` is an L4 `starpkg` module that depends downward on `1set/starlet` (the -Machine plus `dataconv`) and transitively on `1set/starlight` plus -`go.starlark.net`; nothing in the ecosystem sits below it except those runtimes. +`base` belongs to L3, the `starpkg` domain-module layer, and supplies shared +configuration support to other modules in that layer. It depends on L2 +`1set/starlet` (the Machine plus `dataconv`), with L1 `1set/starlight` and L0 +`go.starlark.net` beneath it. The host runtime `1set/starbox` is L4. For the complete per-builtin reference — the generated accessors, their signatures, parameters, returns, errors, value conversion, and the configuration @@ -58,7 +59,7 @@ import ( func main() { module := base.NewConfigurableModule() - // A secret option: settable from a script, but never readable. + // A non-host-only secret option: script setter, no generated getter. module.SetConfigOption("api_key", base.NewConfigOption(""). WithDescription("API key for authentication"). @@ -106,8 +107,8 @@ the config keys: `None`. Generated for every **non-host-only** option (secret or not); a host-only option has no setter. - `get_()` — return the resolved value of non-secret option ``. - Generated for **non-secret options only** — a secret option exposes its setter - but no getter. + Generated for **non-secret options only**; a secret option has no generated + getter, and has a setter only when it is not host-only. Any callables passed in `additionalFuncs` are merged in under their own names. @@ -119,9 +120,10 @@ errors, and examples of every generated accessor. Each option becomes a `set_` setter (unless it is host-only) and a `get_` getter (unless it is secret); a value resolves in priority order — explicit `set_` → getter → environment variable (`WithEnvVar`, -conventionally `_`) → default. Secret options expose only -`set_`, never a getter; host-only options (`SetHostOnly(true)`, for a limit -the module enforces) expose only `get_`, never a setter. See the +conventionally `_`) → default. A secret option has no generated +getter; a host-only option (`SetHostOnly(true)`, for a limit the module enforces) +has no generated setter. An option with both flags has neither accessor. Go code +can still configure and read it. See the [Configuration section of docs/API.md](docs/API.md#configuration) for the full accessor contract and conversion rules. @@ -149,4 +151,3 @@ have any improvements or suggestions. This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details. - diff --git a/docs/API.md b/docs/API.md index f1e8cdd..0ca78d5 100644 --- a/docs/API.md +++ b/docs/API.md @@ -10,7 +10,7 @@ quickstart, see the [README](../README.md). the configuration options a host registered, so the exact function names depend on the module's config keys. For every registered option named `` the loader generates a `set_` setter — **unless the option is host-only**, in -which case no setter is generated so a script cannot change it — and for every +which case no script setter is generated — and for every **non-secret** option a `get_` getter; any callables passed in `additionalFuncs` are merged in alongside under their own names. @@ -26,8 +26,8 @@ which case no setter is generated so a script cannot change it — and for every ## Generated configuration accessors When a `ConfigurableModule` is loaded with `LoadModule(moduleName, …)`, each -registered option contributes one or two builtins to the module namespace, named -by string concatenation from the option's key: +registered option contributes zero, one or two builtins to the module namespace. +Their names are concatenated from the option's key: | Generated builtin | Generated for | Signature | |-------------------|----------------------------|---------------------| @@ -36,9 +36,18 @@ by string concatenation from the option's key: So a module with options `api_key` (secret) and `endpoint` (non-secret) exposes exactly `set_api_key`, `set_endpoint`, and `get_endpoint` — a setter for every -non-host-only option and a getter for every non-secret option. A **host-only** -option (e.g. a limit the module enforces) gets a `get_` but no -`set_`, so a script can read it but never change it. +non-host-only option and a getter for every non-secret option. The flags are +independent: + +| Secret | Host-only | Generated accessors | +| --- | --- | --- | +| No | No | `set_`, `get_` | +| Yes | No | `set_` only | +| No | Yes | `get_` only | +| Yes | Yes | Neither | + +These flags control generated accessors, not what host-supplied additional +functions may expose. Go code can still configure and read the option. ### `set_(value)` @@ -95,8 +104,8 @@ an explicit `set_` value, then the getter, then the environment variable, then the default. This builtin is **only generated for non-secret options.** A `SetSecret(true)` -option exposes its `set_` but no `get_` — secret values are never -readable from a script (Go code can still read them via `GetConfigValue`). +option has no generated `get_`; it has a generated `set_` only if it +is not also host-only. Go code can still read the value via `GetConfigValue`. **Parameters:** none. @@ -120,8 +129,9 @@ print(get_timeout()) Any callables passed to `LoadModule(moduleName, additionalFuncs)` (a `starlark.StringDict` of `starlark.Callable` values supplied by the host module) are merged into the same module namespace under their own names, alongside the -generated `set_` / `get_` accessors. Their signatures, parameters, -returns, and errors are defined by the host module that registers them, not by +generated `set_` / `get_` accessors. Additional functions are merged +last and replace a generated accessor if they use the same name. Their +signatures, parameters, returns, and errors are defined by the host module, not by `base`; consult that module's own reference. ```python @@ -175,6 +185,11 @@ variable is whatever name the host passes to `WithEnvVar`; the conventional name a `starpkg` domain module uses is `_` (uppercased), e.g. a `timeout` option on the `sqlite` module reads `SQLITE_TIMEOUT`. +For host-only options, the environment value is snapshotted when the option is +registered; `Initialize` captures it if no snapshot was taken yet. Later +environment changes do not refresh that snapshot. Non-host-only options read the +live environment. Go-side values and getters still have higher priority. + The generated-accessor contract that every `base`-built option follows is below. `` is the loaded module name, `` the uppercased option key; the env var is host-chosen via `WithEnvVar` (conventionally `_`), and the @@ -183,17 +198,17 @@ default/description are whatever the host declared (`WithDefault` / - **`` (plain)** — getter `get_`, setter `set_`; both value reads and writes are reachable from a script. -- **`` (secret)** — setter `set_` only; no getter is generated, since - secrets are never readable from a script. -- **`` (host-only)** — getter `get_` only; no setter is generated, so a - script can read the value but never change it (a limit the module enforces). A - host-only **and** secret option gets neither accessor. - -**Secret options expose only `set_` — never a getter.** A host marks an -option secret with `SetSecret(true)` (or the equivalent `genSecretConfigOption` -helper a domain module wraps it in); the loader then emits the `set_` setter -but no `get_`, and `ListConfigs()` / `GetInfo()` omit the value. Go code can -still read a secret via `GetConfigValue`, but it is never reachable from a script. +- **`` (secret, not host-only)** — setter `set_` only; no getter is + generated. +- **`` (host-only, not secret)** — getter `get_` only; no setter is + generated for this host-enforced option. +- **`` (host-only and secret)** — neither accessor is generated. + +**Secret options have no generated getter.** A host marks an option secret with +`SetSecret(true)` (or a domain module's `genSecretConfigOption` helper); the loader +emits `set_` only when the option is not host-only. `ListConfigs()` / +`GetInfo()` omit the secret value. Go code can still read it via `GetConfigValue`; +any further script access depends on the functions the host supplies. **Example:** @@ -212,5 +227,3 @@ For the resolution-priority model, the Go-side builder/accessor API (`NewConfigOption`, `WithEnvVar`, `WithDefault`, `SetSecret`, `GetConfigValue`, …), and how a host registers options, see the [README](../README.md) and the [GoDoc](https://pkg.go.dev/github.com/starpkg/base). - -