providers

README

providers

_{part of the togo-framework — the full-stack Go + React framework}

Runtime, config-driven selection of which backend is active for a capability — swap it over CLI / .env / settings without recompiling.

togo already has the registry (RegisterProviderFunc), the capability contracts (togo.Cache / Queue / Storage / Broker), the container (k.Set/Get), and the <capability>-<backend> plugin convention (storage-s3, realtime-nats, …). The one missing piece is picking which backend wins at runtime. This package adds exactly that — and nothing else. It stores no config itself; the settings plugin is the store.

Selection order (highest wins)

1. env        TOGO_<CAP>_PROVIDER=iceberg      # or a CLI flag that sets it
2. settings   providers.<cap>.active           # togo.yaml / settings plugin
3. default    the backend registered with def=true

Use it — in a backend plugin

import "github.com/togo-framework/providers"

func init() {
  togo.RegisterProviderFunc("db-iceberg", togo.PriorityService, func(k *togo.Kernel) error {
    // installs itself as the "data" service ONLY if selected (def=false → opt-in)
    providers.Use(k, providers.CapData, "iceberg", newIceberg(k), false)
    return nil
  })
}

Read provider config the dynamic way (env → settings → default; secrets env-only):

url   := providers.Value(k, providers.CapExecute, "coder", "url",   "http://localhost:7080", false)
token := providers.Value(k, providers.CapExecute, "coder", "token", "",                      true) // secret

Capabilities

Constant	Contract	Backends
CapCache CapQueue CapStorage CapRealtime	existing (togo core)	e.g. storage-s3, queue-nats, realtime-nats
CapImplement CapExecute	autopilot	claude/omnigent, local/coder
CapCompute	worker	worker-local/beam/spark/flink/databricks
CapData CapCatalog CapShare	db / catalog / sharing	pg/iceberg/bigquery/databricks, …

Install

togo install togo-framework/providers

MIT © fadymondy

Documentation

Overview

Package providers adds ONE thing on top of togo's existing provider system: runtime, config-driven SELECTION of which backend is active for a capability — swappable over CLI / .env / settings without recompiling.

It deliberately reuses what the framework already has and invents nothing new:

• the registry → togo.RegisterProviderFunc / applyProviders
• the capability contracts → togo.Cache / Queue / Storage / Broker / Translator (new ones like Implement/Execute/Compute live in the plugin that owns them)
• the container → k.Set(capability, impl) / k.Get(capability)
• the config store → github.com/togo-framework/settings (scope "providers")
• the <cap>-<backend> convention → storage-s3, realtime-nats, queue-nats, …

A backend plugin calls Use() in its provider func: it installs itself as the capability service only when it is the selected (or default) backend. Selection resolves highest-first: (1) env TOGO_<CAP>_PROVIDER, (2) settings providers.<cap>.active, (3) the caller's default.

Index

• Constants
• func Active(k *togo.Kernel, capability, def string) string
• func Use(k *togo.Kernel, capability, name string, impl any, def bool) bool
• func Value(k *togo.Kernel, capability, name, key, def string, secret bool) string

Constants

const (
	// --- already defined by togo core (contracts.go) — reuse, don't redefine ---
	CapCache    = "cache"    // togo.Cache
	CapQueue    = "queue"    // togo.Queue      → queue-nats (default), queue-rabbitmq, queue-kafka
	CapStorage  = "storage"  // togo.Storage    → storage-s3, storage-r2, storage-gdrive
	CapRealtime = "realtime" // togo.Broker    → realtime-nats, realtime-grpc

	// --- new capabilities (contract lives in the owning plugin) ---
	CapImplement = "impl"    // autopilot: issue → code. claude (default), omnigent
	CapExecute   = "exec"    // autopilot: isolated env. local (default), coder
	CapCompute   = "compute" // worker: batch/stream jobs. worker-local (default), beam/spark/flink/databricks
	CapData      = "data"    // db: governed read/write. pg (default), iceberg/bigquery/databricks
	CapCatalog   = "catalog" // catalog: Unity Catalog / Iceberg REST
	CapShare     = "share"   // sharing: OpenSharing / Delta Sharing
)

Capability names — the shared vocabulary for provider selection. Some already have a contract in togo core (contracts.go); the selection helper in this package works for ANY capability string, existing or new.

Functions

func Active

func Active(k *togo.Kernel, capability, def string) string

Active returns the selected backend name for a capability, or def if none is configured. Resolution order: env → settings("providers") → def.

func Use

func Use(k *togo.Kernel, capability, name string, impl any, def bool) bool

Use installs impl as the capability's kernel service IF this backend is the selected one — or, when def is true, if nothing else is selected. Returns whether it took effect. Call it from a backend plugin's provider func:

togo.RegisterProviderFunc("db-iceberg", togo.PriorityService, func(k *togo.Kernel) error {
    providers.Use(k, providers.CapData, "iceberg", newIceberg(k), false)
    return nil
})

func Value

func Value(k *togo.Kernel, capability, name, key, def string, secret bool) string

Value resolves a provider-scoped config value: env (VENDOR_KEY / TOGO_<CAP>_<KEY>) → settings("providers", "<cap>.<name>.<key>") → def. Secrets never read from settings (they resolve from env/.env only), so togo.yaml/DB never hold them.