Documentation
¶
Overview ¶
Package control is the emulator's control plane: the registry of service instances (search / channel / datastore / auth) and minted API keys for the single local dev org. It lives in memory and is persisted to a small JSON file so instances and keys survive a restart. Instances auto-create on first data-plane use so `altengine dev` followed by a request to /v1/datastore/myapp just works with no setup.
Index ¶
- Variables
- func NowMS() int64
- func RegionAtCreate(service string) bool
- type APIKey
- type Instance
- type Registry
- func (r *Registry) AddKey(k *APIKey)
- func (r *Registry) ConfigSnapshot(in *Instance) map[string]any
- func (r *Registry) Create(service, name string) (*Instance, error)
- func (r *Registry) CreatePlaced(service, name string, region any) (*Instance, error)
- func (r *Registry) Delete(service, id string) bool
- func (r *Registry) DeleteInstance(service, id string) bool
- func (r *Registry) DeleteKey(id string) *APIKey
- func (r *Registry) Get(service, name string) *Instance
- func (r *Registry) GetByID(service, id string) *Instance
- func (r *Registry) GetOrCreate(service, name string) *Instance
- func (r *Registry) List(service string) []*Instance
- func (r *Registry) ListKeys() []*APIKey
- func (r *Registry) OnConfigSaved(service string, fn func(in *Instance, before map[string]any))
- func (r *Registry) OnDelete(service string, drop func(instanceID string))
- func (r *Registry) OnValidateConfig(service string, check func(cfg map[string]any) error)
- func (r *Registry) OnValidateConfigChange(service string, check func(next, before map[string]any) error)
- func (r *Registry) OnValidateInstanceConfig(service string, check func(in *Instance, next, before map[string]any) error)
- func (r *Registry) ReplaceConfig(in *Instance, cfg map[string]any) error
- func (r *Registry) ResolveAddressed(service, label string) (*Instance, int)
- func (r *Registry) SaveConfig(in *Instance, changes map[string]any) error
- func (r *Registry) SetConfig(in *Instance, cfg map[string]any)
Constants ¶
This section is empty.
Variables ¶
var Services = []string{"search", "datastore", "channel", "auth", "functions", "blob", "container", "mailbox", "tasks"}
Services is every service the emulator knows how to hold instances for.
It exists so that adding one is a single edit. The dev-open grant map used to carry its own copy of this list, and when the container service landed nobody added it there — so every container call in the emulator's DEFAULT mode answered 403, which reads as a broken emulator rather than a missing line in an auth file. A test asserts dev-open covers all of these.
Functions ¶
func NowMS ¶
func NowMS() int64
NowMS returns the current time in unix milliseconds (exported for other packages).
func RegionAtCreate ¶
RegionAtCreate reports whether service takes its region at creation (and only then).
Types ¶
type APIKey ¶
type APIKey struct {
ID string `json:"id"`
Name string `json:"name"`
Prefix string `json:"prefix"`
Grants map[string]string `json:"grants"`
CreatedAt int64 `json:"created_at"`
LastUsedAt *int64 `json:"last_used_at"`
}
APIKey is a minted key's metadata. The plaintext is returned once at creation and registered with auth.Store; only metadata is retained here.
type Instance ¶
type Instance struct {
ID string
Service string // search | channel | datastore | auth
Name string
CreatedAt int64
Secret string // channel / auth JWT signing secret
// contains filtered or unexported fields
}
Instance is one service instance owned by the dev org.
func (*Instance) Config ¶
Config returns the instance's current config. It is a snapshot shared with other readers: read it freely, never write to it — change config through the Registry.
func (*Instance) MarshalJSON ¶
func (*Instance) UnmarshalJSON ¶
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry is the control-plane store.
func (*Registry) ConfigSnapshot ¶
ConfigSnapshot returns a shallow copy of an instance's config, which — unlike Config() — the caller may write to.
func (*Registry) CreatePlaced ¶
CreatePlaced is Create with a region. Only a service that takes its region at creation accepts one other than "auto"; every other service sets region through its config.
func (*Registry) Delete ¶
Delete removes an instance by service+id, leaving its data alone. Returns whether it existed. Prefer DeleteInstance — this is the identity half of it.
func (*Registry) DeleteInstance ¶
DeleteInstance removes an instance AND the data it holds. The console and the MCP tool both call this, so "deleted" means the same thing whichever surface asked.
Data first, identity last: the instance row is the only handle on where that data lives, so a failure part-way leaves files an operator can still find rather than orphans nothing names.
func (*Registry) DeleteKey ¶
DeleteKey removes key metadata by id, returning it (for auth revocation) or nil.
func (*Registry) GetOrCreate ¶
GetOrCreate returns the instance for (service, name), auto-creating it if absent.
func (*Registry) OnConfigSaved ¶
OnConfigSaved registers what a service does after its config changes — `before` is the config as it was. Pruning versions when retention is lowered is the case it exists for.
func (*Registry) OnDelete ¶
OnDelete registers what drops one instance's DATA for a service — its databases, its files — called by DeleteInstance before the instance row goes.
Services register their own because only they know where their data lives, and it is a hook rather than a switch in DeleteInstance so that a service is torn down by the package that created it. A service with nothing on disk registers nothing.
func (*Registry) OnValidateConfig ¶
OnValidateConfig registers a check a service's config must pass before SaveConfig writes it.
func (*Registry) OnValidateConfigChange ¶
func (r *Registry) OnValidateConfigChange(service string, check func(next, before map[string]any) error)
OnValidateConfigChange registers a check that also sees the config being replaced (`before`), for a rule that holds only what a save changes — auth's grandfathered rule filters.
func (*Registry) OnValidateInstanceConfig ¶ added in v0.2.33
func (r *Registry) OnValidateInstanceConfig(service string, check func(in *Instance, next, before map[string]any) error)
OnValidateInstanceConfig registers a check that needs to know WHICH instance is being saved — a functions `defaultFunction` must name a function that instance has deployed.
func (*Registry) ReplaceConfig ¶
ReplaceConfig is the one config write every surface ends in, and the console's PUT calls it directly: `cfg` becomes the whole config, as it does hosted — a key it leaves out is gone, and the service reads its default. A result a service's validator rejects writes nothing; after a write, the service's after-save hooks run.
func (*Registry) ResolveAddressed ¶
ResolveAddressed finds the instance a public address names, and the version it asks for (0 for the live one). `label` is the instance segment of a public path — the local stand-in for a tenant hostname — so `myapp--v3` is version 3 of `myapp`. Hosted no slug may contain `--`; here instance names are free-form, so the versioned reading wins only when its base instance exists.
func (*Registry) SaveConfig ¶
SaveConfig is MCP's patch: it merges `changes` onto the instance's config (top level only, as hosted) and writes the result through ReplaceConfig.