Skip to content
Draft
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
2 changes: 1 addition & 1 deletion .github/workflows/build.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
29 changes: 15 additions & 14 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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_<key>` setter for
every non-host-only option and a `get_<key>` 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
Expand Down Expand Up @@ -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").
Expand Down Expand Up @@ -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_<key>()` — return the resolved value of non-secret option `<key>`.
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.

Expand All @@ -119,9 +120,10 @@ errors, and examples of every generated accessor.
Each option becomes a `set_<key>` setter (unless it is host-only) and a
`get_<key>` getter (unless it is secret); a value resolves in priority order —
explicit `set_<key>` → getter → environment variable (`WithEnvVar`,
conventionally `<MODULE>_<KEY>`) → default. Secret options expose only
`set_<key>`, never a getter; host-only options (`SetHostOnly(true)`, for a limit
the module enforces) expose only `get_<key>`, never a setter. See the
conventionally `<MODULE>_<KEY>`) → 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.

Expand Down Expand Up @@ -149,4 +151,3 @@ have any improvements or suggestions.

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file
for details.
</content>
59 changes: 36 additions & 23 deletions docs/API.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<name>` the
loader generates a `set_<name>` 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_<name>` getter; any callables passed in
`additionalFuncs` are merged in alongside under their own names.

Expand All @@ -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 |
|-------------------|----------------------------|---------------------|
Expand All @@ -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_<name>` but no
`set_<name>`, 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_<name>`, `get_<name>` |
| Yes | No | `set_<name>` only |
| No | Yes | `get_<name>` 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_<name>(value)`

Expand Down Expand Up @@ -95,8 +104,8 @@ an explicit `set_<name>` 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_<name>` but no `get_<name>` — secret values are never
readable from a script (Go code can still read them via `GetConfigValue`).
option has no generated `get_<name>`; it has a generated `set_<name>` only if it
is not also host-only. Go code can still read the value via `GetConfigValue`.

**Parameters:** none.

Expand All @@ -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_<name>` / `get_<name>` accessors. Their signatures, parameters,
returns, and errors are defined by the host module that registers them, not by
generated `set_<name>` / `get_<name>` 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
Expand Down Expand Up @@ -175,6 +185,11 @@ variable is whatever name the host passes to `WithEnvVar`; the conventional name
a `starpkg` domain module uses is `<MODULE>_<KEY>` (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.
`<MODULE>` is the loaded module name, `<KEY>` the uppercased option key; the env
var is host-chosen via `WithEnvVar` (conventionally `<MODULE>_<KEY>`), and the
Expand All @@ -183,17 +198,17 @@ default/description are whatever the host declared (`WithDefault` /

- **`<key>` (plain)** — getter `get_<key>`, setter `set_<key>`; both value
reads and writes are reachable from a script.
- **`<key>` (secret)** — setter `set_<key>` only; no getter is generated, since
secrets are never readable from a script.
- **`<key>` (host-only)** — getter `get_<key>` 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_<key>` — 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_<key>` setter
but no `get_<key>`, and `ListConfigs()` / `GetInfo()` omit the value. Go code can
still read a secret via `GetConfigValue`, but it is never reachable from a script.
- **`<key>` (secret, not host-only)** — setter `set_<key>` only; no getter is
generated.
- **`<key>` (host-only, not secret)** — getter `get_<key>` only; no setter is
generated for this host-enforced option.
- **`<key>` (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_<key>` 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:**

Expand All @@ -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).
</content>
</invoke>
Loading