Documentation
¶
Overview ¶
Package instancefile is the third door to the instance level (ADR-0070 §5, the concept's §5.4).
The API is the product; `hubctl` and the dashboard are two clients of it, and a file is the third — for GitOps and immutable containers, where the thing that owns the configuration is a repository rather than a person. Two modes, and the difference is who owns the values afterwards:
- **`seed`** writes them once, at the first start that finds the level empty, and then leaves it alone. The file is where the installation *began*; the API owns it from then on.
- **`enforce`** writes them at every start, and the writing routes refuse in between. The file is the source, permanently, and a save through the API would be one the next restart silently undoes.
**One source per mode, never two.** That sentence is the whole of why `enforce` refuses rather than merging: an installation whose values come from two places is one where nobody can say what applies without reading both.
**This package maps a file to a request, and nothing else.** It does not know which switch takes a number — the use case does, and a second copy of that knowledge here would be a second copy to get wrong. "Drei Türen, eine API" is meant literally: the file goes through `WriteInstanceSettings` exactly as the dashboard and `hubctl` do, so a value a file may set is a value the API accepts.
JSON rather than YAML, and deliberately: the level is already JSON in the database and in the contract, so the file is the same document an operator would `GET` — and the server binary gains no dependency for it. `gopkg.in/yaml.v3` is in this repository for tools and tests; putting it on every installation's start-up path is a supply-chain decision, not a formatting preference.
Index ¶
- func Plans(document map[string]any, source string) (plans []map[string]any, present bool, err error)
- func Presets(document map[string]any, source string) (presets []map[string]any, present bool, err error)
- func Read(path string) (map[string]any, bool, error)
- type AiModel
- type Mode
- type PlatformSubscription
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func Plans ¶
func Plans(document map[string]any, source string) (plans []map[string]any, present bool, err error)
Plans reads the file's plans, each as the document the plan use cases read. Present is false where the file says nothing about plans, which is not the same as an empty list: an enforcing file with `"plans": []` removes every plan no workspace is on, while one without the key leaves the plans that stand as they are - and, enforcing, closes the API's plan writes all the same, as it closes every other value of the level.
func Presets ¶
func Presets(document map[string]any, source string) (presets []map[string]any, present bool, err error)
Presets reads the file's presets, each as the document the preset use cases read. Present is false where the file says nothing about them, which is not an empty list: an enforcing file with `"presets": []` withdraws every preset.
func Read ¶
Read parses the file at a path into the request body `WriteInstanceSettings` takes.
A path that names nothing is not an error: an installation may be configured for a file that has not been written yet, and refusing to start over it would make the mode useless in exactly the deployment it is for.
Types ¶
type AiModel ¶
type AiModel struct {
DisplayName string
Processor string
Kind string
BaseURL string
CompletionModel string
EmbeddingModel string
Jurisdiction string
// APIKey is the key read from the named variable, and HasKey whether the file named one.
APIKey string
HasKey bool
}
AiModel is one offered model as the file names it. The key is never in the file - a secret in a configuration file is a key in clear - but in the environment variable APIKeyEnv names.
func AiModels ¶
func AiModels( document map[string]any, lookup func(string) (string, bool), source string, ) (models []AiModel, present bool, err error)
AiModels reads the file's offered models. Present is false where the file says nothing about them, which is not the same as an empty list: an enforcing file with `"ai_models": []` withdraws every offered model, and one without the key leaves them to the other doors.
type PlatformSubscription ¶
PlatformSubscription is one subscription as the file names it. The secret is never in the file - a secret in a configuration file is a secret in clear - but in the file SecretFile names.
func PlatformSubscriptions ¶
func PlatformSubscriptions(document map[string]any, readFile func(string) ([]byte, error), source string, ) (subscriptions []PlatformSubscription, present bool, err error)
PlatformSubscriptions reads the file's subscriptions, each secret from the file it names. Present is false where the file says nothing about them, which is not an empty list: an enforcing file with `"platform_subscriptions": []` removes every subscription.
Source Files