api

package
v0.0.0-...-82d8bfb Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 15, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source
const (
	ClientSchemaVersion = "1.0"

	ClientTypeCloudCompose = "cloud-compose"
	ClientTypeStatic       = "static"
	ClientTypeSingleImage  = "single-image"
)
View Source
const (
	ComposeLabelIngressContainer            = "simple-container.com/ingress"
	ComposeLabelVolumeSize                  = "simple-container.com/volume-size"
	ComposeLabelVolumeAccessModes           = "simple-container.com/volume-access-modes"
	ComposeLabelVolumeStorageClass          = "simple-container.com/volume-storage-class"
	ComposeLabelIngressPort                 = "simple-container.com/ingress/port"
	ComposeLabelHealthcheckSuccessCodes     = "simple-container.com/healthcheck/success-codes"
	ComposeLabelHealthcheckHealthyThreshold = "simple-container.com/healthcheck/healthy-threshold"
	ComposeLabelHealthcheckPath             = "simple-container.com/healthcheck/path"
	ComposeLabelHealthcheckPort             = "simple-container.com/healthcheck/port"
)
View Source
const (
	ScConfigDirectory                  = ".sc"
	EnvConfigFileTemplate              = "cfg.%s.yaml"
	ScConfigEnvVariable                = "SIMPLE_CONTAINER_CONFIG"
	ScContainerResourceTypeEnvVariable = "SIMPLE_CONTAINER_RESOURCE_TYPE"
)
View Source
const (
	ServerDescriptorFileName  = "server.yaml"
	SecretsDescriptorFileName = "secrets.yaml"
	ClientDescriptorFileName  = "client.yaml"
)
View Source
const (
	// ServerSchemaVersion is the DEFAULT value SC uses when writing a new
	// server.yaml. Not a required pin — an empty schemaVersion field is
	// treated as the 1.0-compatible lenient mode.
	ServerSchemaVersion = "1.0"

	// ServerSchemaVersion11 is the strict-mode version. Setting
	// `schemaVersion: 1.1` in server.yaml opts into:
	//   - `plugins:` MUST declare any out-of-tree plugin-owned type the
	//     stack uses. No GitHub auto-inject fallback.
	//   - Unknown schemaVersion strings fail at parse time.
	// 1.0 (or empty) keeps the pre-A3 lenient behaviour.
	ServerSchemaVersion11 = "1.1"

	// UpgradingToPluginsDocsURL is the migration guide operators are
	// pointed at from every plugin-related parse error. Keep in one place
	// so a URL change in the docs site is a single edit here.
	UpgradingToPluginsDocsURL = "https://docs.simple-container.com/guides/upgrading-to-plugins/"
)
View Source
const DefaultRegistrarName = ""

DefaultRegistrarName is the key the legacy single `registrar:` block is normalised under. It is deliberately the empty string so that anything derived from a registrar's name is unchanged for stacks written before `registrars:` existed.

View Source
const ResourceRefPrefix = "${resource:"

ResourceRefPrefix is the placeholder context this reference uses.

It is deliberately the same `${resource:<name>.<key>}` spelling a CLIENT stack already uses to read a provisioned parent resource's outputs (see pkg/clouds/pulumi/api/compute_context.go) — one syntax, one meaning, two tiers. The RESOLUTION is necessarily different: a client-stack placeholder is substituted as a string before anything runs, while here the value does not exist until the sibling has been provisioned in this very update, so it can only ever be a Pulumi Output.

That is also why the reference survives placeholder resolution untouched. `pkg/provisioner/placeholders` registers no `resource` extension, and pkg/template's calcValue returns an unknown context verbatim rather than erroring (strict mode is off on the provision path) — so the literal string arrives at the provisioning tier for ParseResourceRef to read. Registering a `resource` extension in that package would silently break every reference here.

View Source
const SecretsSchemaVersion = "1.0"

Variables

View Source
var (
	ReadIgnoreNoClientCfg           = ReadOpts{IgnoreClientMissing: true}
	ReadIgnoreNoServerCfg           = ReadOpts{IgnoreServerMissing: true, IgnoreSecretsMissing: true}
	ReadIgnoreNoSecretsAndClientCfg = ReadOpts{IgnoreSecretsMissing: true, IgnoreClientMissing: true}
	ReadIgnoreNoSecretsAndServerCfg = ReadOpts{IgnoreSecretsMissing: true, IgnoreServerMissing: true}
	ReadIgnoreNoAnyCfg              = ReadOpts{IgnoreSecretsMissing: true, IgnoreServerMissing: true, IgnoreClientMissing: true}

	// ReadSecretsOnly is for a command that wants a stack's secret values and
	// nothing else — it tolerates a missing client.yaml and asks the read not
	// to pay the plugin pre-parse. The server descriptor is still read (a
	// scoped secrets store needs its provisioner config), just cheaply when
	// that is possible. See ReadOpts.PluginTypesNotNeeded.
	ReadSecretsOnly = ReadOpts{IgnoreClientMissing: true, PluginTypesNotNeeded: true}
)
View Source
var ComponentConfigTopLevelKeys = []string{
	"deployTo",
	"image",
	"signingKey",
	"env",
	"ingress",
}

ComponentConfigTopLevelKeys lists the keys the Component class treats as well-known on the resource's config. Any additional top-level key an operator or plugin tries to set that is NOT also listed in the per-type allowlist is a parse-time error (plugin_requirements.go).

Kept as a var (not const slice) so test fixtures and future components can extend it if they need to. Changes here are plugin-facing-contract changes — review against the design doc before touching.

View Source
var ComputeEnv = ComputeEnvVariables{
	CloudHelperType:   "SIMPLE_CONTAINER_CLOUD_HELPER_TYPE",
	DiscordWebhookUrl: "SIMPLE_CONTAINER_DISCORD_WEBHOOK_URL",
	SlackWebhookUrl:   "SIMPLE_CONTAINER_SLACK_WEBHOOK_URL",
	TelegramChatID:    "SIMPLE_CONTAINER_TELEGRAM_CHAT_ID",
	TelegramToken:     "SIMPLE_CONTAINER_TELEGRAM_TOKEN",
	AlertName:         "SIMPLE_CONTAINER_ALERT_NAME",
	AlertDescription:  "SIMPLE_CONTAINER_ALERT_DESCRIPTION",
	StackName:         "SIMPLE_CONTAINER_STACK",
	StackEnv:          "SIMPLE_CONTAINER_ENV",
	StackVersion:      "SIMPLE_CONTAINER_VERSION",
	CloudProvider:     "SIMPLE_CONTAINER_CLOUD",
	CtLogGroupName:    "SIMPLE_CONTAINER_CT_LOG_GROUP_NAME",
	CtLogGroupRegion:  "SIMPLE_CONTAINER_CT_LOG_GROUP_REGION",
	CtFilterPattern:   "SIMPLE_CONTAINER_CT_FILTER_PATTERN",
}
View Source
var ErrPluginUnimplementedConversion = stderrors.New("plugin does not implement ConvertStackConfig")

ErrPluginUnimplementedConversion is the sentinel the stackread converter returns when a plugin's binary predates the ConvertStackConfig RPC (gRPC Unimplemented). SC core treats this as "the plugin cannot answer the RPC yet" and falls through to the pre-A2 cloud*ConverterMapping path, which is still populated via each plugin's /api/init.go blank-imports — strictly additive.

Rationale: new RPCs on the SCCloudPlugin service must be forward- and backward-compatible, so a CLI release that adds a required RPC does not break every deployed stack whose pinned plugin binary predates it. This sentinel is the mechanism; the standing rule for every future new RPC is to catch Unimplemented at the dial site and fall through to a known-good legacy path (if one exists) or return a legible operator error (if not).

Peer-flagged root cause of the ConvertStackConfig fleet break 2026-11-02: api #535 shipped the caller + no plugin release had the handler + forge's aws pin predated the handler. Every isolated-matrix deploy hit "ConvertStackConfig: Unimplemented". With this fallback, that failure mode becomes silent: the plugin says Unimplemented, SC core uses the typed-converter mapping, deploy proceeds as it did before A2.

View Source
var ErrServerDescriptorInvalid = errors.New("server descriptor exists but is invalid")

ErrServerDescriptorInvalid tags the case where a stack's server.yaml EXISTS but could not be parsed or failed validation. It must never be conflated with "server.yaml is absent": ReadOpts.IgnoreServerMissing legitimately tolerates a client-only stack directory, but silently dropping a malformed or rejected server.yaml discards the only actionable diagnosis the operator will ever get and surfaces much later as a generic "provisioner is not set for stack %q". Same principle as scoped.ErrScopedIntegrity on the secrets path — a config we could not read is never treated as "simply absent". See ReadStacks.

View Source
var SupportedServerSchemaVersions = map[string]bool{
	ServerSchemaVersion:   true,
	ServerSchemaVersion11: true,
}

SupportedServerSchemaVersions lists every value `schemaVersion:` may legally hold. An empty string is treated as implicit 1.0 and does not need to appear here; the validator special-cases it.

Functions

func AuthToString

func AuthToString[T any](sa *T) string

func ConfigFilePath

func ConfigFilePath(workDir string, profile string) string

func ConvertAuth

func ConvertAuth[T any](auth AuthConfig, creds *T) error

func ConvertDescriptor

func ConvertDescriptor[T any](from any, to *T) (*T, error)

func DomainInZone

func DomainInZone(domain, zone string) bool

DomainInZone reports whether a domain is served by a DNS zone — the zone itself, or anything under it. Both sides are compared without a trailing dot and without regard to case, and a match must land on a label boundary so that `notsimple-forge.com` is not read as being inside `simple-forge.com`.

func IsComponentConfigTopLevelKey

func IsComponentConfigTopLevelKey(key string) bool

IsComponentConfigTopLevelKey reports whether the given key is one of the well-known Component config keys above.

func IsEngineOnlyType

func IsEngineOnlyType(resourceType string) bool

IsEngineOnlyType reports whether the type is rule 3 — a resource with no cloud counterpart. Exported separately because it is the one rule SafeToReplaceTypes cannot enumerate: a prefix is not a finite set.

func IsSafeToReplace

func IsSafeToReplace(resourceType string) bool

IsSafeToReplace reports whether `OpReplace` on this resource type should be exempt from the destructive-replace guard — under either rule. This is the single question the guard asks.

func IsZoneApex

func IsZoneApex(domain, zone string) bool

IsZoneApex reports whether a domain IS the zone rather than a name under it. The distinction decides which record type may point the name at a hostname: a CNAME is illegal at an apex, because the apex already holds the zone's own SOA and NS records and a CNAME may not coexist with other data (RFC 1034 §3.6.2). Every provider answers that with a non-standard record of its own, so the caller has to know which end of the zone it is writing.

func MarshalDescriptor

func MarshalDescriptor[T any](descriptor *T) ([]byte, error)

func MustClone

func MustClone[T any](original T) T

MustClone creates a deep copy of any value using YAML marshaling/unmarshaling This generic function works with any type T and handles complex nested structures automatically It is nil-safe and will return the zero value for nil inputs

func ParentStackName

func ParentStackName(ref string) string

ParentStackName returns the stack name of a client's parent reference, which is either the bare name, "org/name" or "org/project/name".

func ReadDescriptor

func ReadDescriptor[T any](filePath string, descriptor *T) (*T, error)

func RegisterCloudComposeConverter

func RegisterCloudComposeConverter(mapping CloudComposeConfigRegister)

func RegisterCloudHelper

func RegisterCloudHelper(mapping CloudHelpersRegisterMap)

func RegisterCloudSingleImageConverter

func RegisterCloudSingleImageConverter(mapping CloudSingleImageConfigRegister)

func RegisterCloudStaticSiteConverter

func RegisterCloudStaticSiteConverter(mapping CloudStaticSiteConfigRegister)

func RegisterPluginOwnedType

func RegisterPluginOwnedType(name string, kind PluginOwnedKind, pluginName string)

RegisterPluginOwnedType records that the named type is owned by a plugin binary (its Schema RPC advertised it). Installs an opaque decoder into providerConfigMapping so the generic parse path at pkg/api/read.go recognises the type without needing a Go-link-time struct. The decoder preserves Config.Config as a map[string]any — the plugin receives the raw YAML tree on the provision bus and decodes it into its own typed Input shape there.

If the type was already registered via api.RegisterProviderConfig (an in-tree type or a plugin's /api/init.go typed registration), the typed decoder wins — do NOT overwrite it. This keeps the pre-parse strictly ADDITIVE: a plugin that cached /api still gives SC core the richer parse-time validation it had, and types SC core has never heard of fall through to the opaque path.

pluginName is the key under server.yaml's `plugins:` block (the stackread caller passes it through from descriptor.Plugins). The A2 ConvertStackConfig path uses it to dial the right plugin.

func RegisterPluginRequirement

func RegisterPluginRequirement(req PluginRequirement)

RegisterPluginRequirement declares that a plugin owns a set of type tokens. Called at init() time from each sc-plugin's /api module. Idempotent — a repeated registration with the same name updates the owned-types list and the default source.

func RegisterPluginStackConverter

func RegisterPluginStackConverter(c PluginStackConverter)

RegisterPluginStackConverter installs the dialling implementation (currently stackread.ConvertPluginStackConfig). SC core distributions that never spawn plugins (schema-gen, test fixtures that don't declare plugins:) can leave this nil — the Prepare*ForDeploy fallback is to try the in-tree cloud*ConverterMapping first and only reach for a plugin converter when the type is plugin-owned AND the converter is registered. A nil converter on a plugin-owned template is a configuration error, not a crash.

func RegisterProviderConfig

func RegisterProviderConfig(configMapping ConfigRegisterMap)

func RegisterProvisioner

func RegisterProvisioner(provisionerMapping ProvisionerRegisterMap)

func RegisterProvisionerFieldConfig

func RegisterProvisionerFieldConfig(mapping ProvisionerFieldConfigRegister)

func RegisterSafeToReplaceType

func RegisterSafeToReplaceType(resourceType string)

RegisterSafeToReplaceType adds a Pulumi resource type to the safe-to-replace allowlist. Safe to call concurrently. Idempotent.

Called by `pkg/stackread.DiscoverPluginTypes` for every entry in a plugin's `scpluginv1.SchemaResponse.safe_to_replace_types`; may also be called directly from init() by in-tree code that owns a revision-based type (keep that path rare — plugin advertisement is the preferred shape).

func SafeToReplaceTypes

func SafeToReplaceTypes() map[string]struct{}

SafeToReplaceTypes returns a snapshot of every exempt type named EXACTLY — rules 1 and 2 — for tests and for operator-visible diagnostics ("sc explain"-style). Returned map is a copy; callers may mutate it without affecting the registry.

Rule 3 is absent and cannot be added: it is prefix-matched, so it denotes an open set with no enumeration. A caller deciding whether a specific type is exempt must ask SafeToReplaceRule or IsSafeToReplace, never membership of this map.

func SetLatestVersionResolver

func SetLatestVersionResolver(fn func(repo string) (string, error)) func()

SetLatestVersionResolver replaces the plugin-release resolver and returns a func that restores the previous one. Defer the result.

This exists because auto-injection reaches api.github.com, and a unit test in ANY package that parses a server.yaml using a plugin-owned type without a `plugins:` pin will silently make that call. That is not hypothetical: it is how pkg/provisioner's own fool-protector test started hitting the network the moment auto-injection landed, passing or failing depending on whether the runner had egress. Tests that exercise either path must stub the resolver.

func StackConfigDomainOf

func StackConfigDomainOf(cfg any) string

StackConfigDomainOf returns the `domain:` an operator declared on a client stack, by TYPE rather than by marshalling.

Why a type switch and not a JSON probe. The domain lives in a different place per config shape — flat on compose and single-image, nested inside StaticSiteConfig on static — and `StackConfigStatic.Site` is a NAMED field tagged `json:",inline"`, which encoding/json does not inline. Any probe over marshalled JSON therefore has to know that `Site` becomes a capital-S nested object, and the next config shape that grows an inline-tagged named field breaks it again. The compiler knows all of this; a probe only guesses. See forge/docs/roadmap/items/plugin-bus-json-yaml-inline-tag-asymmetry.md.

Returns "" for a worker-only stack that declares no domain, which is a legitimate answer and not an error.

func UnmarshalDescriptor

func UnmarshalDescriptor[T any](bytes []byte) (*T, error)

func ValidateComponentConfigs

func ValidateComponentConfigs(descriptor *ServerDescriptor, v ComponentValidator) error

ValidateComponentConfigs walks a server descriptor and validates every resource whose type is a declared Component (per the supplied validator) against the §P1 config shape — top-level keys, deployTo-template existence, image shape, signingKey as a secret reference, and the plugin-override allowlist.

Intended to run AFTER the pre-engine plugin bundle has registered sidecars (so the validator's IsComponentType returns true for live plugin types). Called from pkg/clouds/pulumi/provisioner.go right after RegisterSidecars.

Pure: no mutation of the descriptor. Multiple validation errors in a descriptor are collected and surfaced in one error message rather than one-by-one.

Design: forge/docs/design/2026-11-10/sc-components-platform/README.md §P1.

func ValidatePluginRequirements

func ValidatePluginRequirements(descriptor *ServerDescriptor) error

ValidatePluginRequirements walks every type token used in a ServerDescriptor and, for any token owned by an un-declared plugin, resolves the latest release from GitHub and injects a synthetic `plugins:` entry into the descriptor. Only when resolution itself fails (offline, rate-limited, repo gone) does it return an error — with the exact YAML block the operator needs to paste by hand.

Call this at the END of server.yaml parsing (ReadServerConfigs), BEFORE any Pulumi engine starts. The point is to make an existing server.yaml that predates the plugin split keep working across the upgrade: before this, parsing succeeded (the plugin /api module's blank import registers the type reader) and the deploy then died mid-provision with `unsupported registrar type "cloudflare"`, possibly after state had already been mutated.

Auto-injection — rather than a hard error — is deliberate: backwards compatibility means the upgrade must WORK, not merely diagnose. The resolver is skipped entirely for any plugin the operator did declare, so a pinned (reproducible) steady-state deploy makes no network call.

Types

type Alert

type Alert struct {
	Name          string    `json:"name" yaml:"name"`
	Title         string    `json:"title" yaml:"title"`
	Reason        string    `json:"reason" yaml:"reason"`
	Description   string    `json:"description" yaml:"description"`
	StackName     string    `json:"stackName" yaml:"stackName"`
	StackEnv      string    `json:"stackEnv" yaml:"stackEnv"`
	DetailsUrl    string    `json:"detailsUrl" yaml:"detailsUrl"`
	AlertType     AlertType `json:"alertType" yaml:"alertType"`
	CommitAuthor  string    `json:"commitAuthor,omitempty" yaml:"commitAuthor,omitempty"`
	CommitMessage string    `json:"commitMessage,omitempty" yaml:"commitMessage,omitempty"`
}

type AlertSender

type AlertSender interface {
	Send(Alert) error
}

type AlertType

type AlertType string
const (
	// Monitoring Alert Types
	AlertTriggered AlertType = "TRIGGERED"
	AlertResolved  AlertType = "RESOLVED"

	// Build/Deployment Notification Types
	BuildStarted   AlertType = "BUILD_STARTED"
	BuildSucceeded AlertType = "BUILD_SUCCEEDED"
	BuildFailed    AlertType = "BUILD_FAILED"
	BuildCancelled AlertType = "BUILD_CANCELLED"
)

type AlertsConfig

type AlertsConfig struct {
	MaxCPU         *MaxCPUConfig         `json:"maxCPU,omitempty" yaml:"maxCPU,omitempty"`
	MaxMemory      *MaxMemoryConfig      `json:"maxMemory,omitempty" yaml:"maxMemory,omitempty"`
	MaxErrors      *MaxErrorConfig       `json:"maxErrors,omitempty" yaml:"maxErrors,omitempty"`
	ServerErrors   *ServerErrorsConfig   `json:"serverErrors,omitempty" yaml:"serverErrors,omitempty"`
	UnhealthyHosts *UnhealthyHostsConfig `json:"unhealthyHosts,omitempty" yaml:"unhealthyHosts,omitempty"`
	ResponseTime   *ResponseTimeConfig   `json:"responseTime,omitempty" yaml:"responseTime,omitempty"`
	Discord        *DiscordCfg           `json:"discord,omitempty" yaml:"discord,omitempty"`
	Slack          *SlackCfg             `json:"slack,omitempty" yaml:"slack,omitempty"`
	Telegram       *TelegramCfg          `json:"telegram,omitempty" yaml:"telegram,omitempty"`
	Email          *EmailCfg             `json:"email,omitempty" yaml:"email,omitempty"`
}

type AttachDescriptor

type AttachDescriptor struct {
	Enabled bool `json:"enabled,omitempty" yaml:"enabled,omitempty"` // Default: true
	Sign    bool `json:"sign,omitempty" yaml:"sign,omitempty"`       // Sign the attestation
}

AttachDescriptor configures attestation attachment

type AuthConfig

type AuthConfig interface {
	WithProviderType
	CredentialsValue() string
	ProjectIdValue() string
}

AuthConfig defines configuration for a single cloud provider

type AuthDescriptor

type AuthDescriptor struct {
	Type    string `json:"type" yaml:"type"`
	Config  `json:",inline" yaml:",inline"`
	Inherit `json:",inline" yaml:",inline"`
}

func DetectAuthProvider

func DetectAuthProvider(auth *AuthDescriptor) (*AuthDescriptor, error)

func ParseAuthDescriptor

func ParseAuthDescriptor(text string) (AuthDescriptor, error)

ParseAuthDescriptor reads one auth entry, written as the YAML that sits under its name in a secrets.yaml `auth:` map, and converts its config to the provider's type. A standalone entry has no parent to inherit from, so inherit is refused.

func (*AuthDescriptor) AuthConfig

func (a *AuthDescriptor) AuthConfig() (AuthConfig, error)

func (*AuthDescriptor) Copy

func (s *AuthDescriptor) Copy() AuthDescriptor

type BuilderDescriptor

type BuilderDescriptor struct {
	ID string `json:"id,omitempty" yaml:"id,omitempty"` // Auto-detected from CI if not specified
}

BuilderDescriptor configures builder identification

type CacheDescriptor

type CacheDescriptor struct {
	Enabled bool   `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	TTL     string `json:"ttl,omitempty" yaml:"ttl,omitempty"`
	Dir     string `json:"dir,omitempty" yaml:"dir,omitempty"`
}

CacheDescriptor configures local artifact caching.

type CiCdDescriptor

type CiCdDescriptor struct {
	Type    string `json:"type" yaml:"type"`
	Config  `json:",inline" yaml:",inline"`
	Inherit `json:",inline" yaml:",inline"`
}

func (*CiCdDescriptor) Copy

func (s *CiCdDescriptor) Copy() CiCdDescriptor

type ClientDescriptor

type ClientDescriptor struct {
	SchemaVersion string                           `json:"schemaVersion" yaml:"schemaVersion"`
	Defaults      map[string]interface{}           `json:"defaults,omitempty" yaml:"defaults,omitempty"` // Maximum flexibility - supports any user-defined YAML anchors, templates, and configuration
	Stacks        map[string]StackClientDescriptor `json:"stacks" yaml:"stacks"`
	Security      *SecurityDescriptor              `json:"security,omitempty" yaml:"security,omitempty"` // Container security configuration
	ImageBuild    *ImageBuildDescriptor            `json:"imageBuild,omitempty" yaml:"imageBuild,omitempty"`
}

ClientDescriptor describes the client schema

func ClientDescriptorFromPluginConfig

func ClientDescriptorFromPluginConfig(raw []byte) (ClientDescriptor, error)

ClientDescriptorFromPluginConfig rebuilds the client descriptor a plugin's template reads from the JSON PluginClientConfigJSON wrote. Empty input is the zero descriptor: an older core sends none, and a plugin must run as it did.

func ReadClientDescriptor

func ReadClientDescriptor(path string) (*ClientDescriptor, error)

func (*ClientDescriptor) Copy

func (*ClientDescriptor) GetDefaultValue

func (c *ClientDescriptor) GetDefaultValue(key string) (interface{}, bool)

GetDefaultValue retrieves a specific value from the defaults section Supports nested access using dot notation (e.g., "stack.type", "config.baseDnsZone")

func (*ClientDescriptor) GetDefaultsSection

func (c *ClientDescriptor) GetDefaultsSection() map[string]interface{}

GetDefaultsSection returns the defaults section as a map for flexible access This allows users to define any YAML anchors and templates they need

func (*ClientDescriptor) HasDefaults

func (c *ClientDescriptor) HasDefaults() bool

HasDefaults checks if the client configuration has a defaults section

func (*ClientDescriptor) PluginClientConfigJSON

func (c *ClientDescriptor) PluginClientConfigJSON() ([]byte, error)

PluginClientConfigJSON serialises the client-level configuration a plugin's template needs, or nil when the descriptor sets none of it.

func (*ClientDescriptor) ReuseExistingCommitTagEnabled

func (c *ClientDescriptor) ReuseExistingCommitTagEnabled() bool

ReuseExistingCommitTagEnabled reports whether tag reuse is configured.

func (*ClientDescriptor) SetDefaultValue

func (c *ClientDescriptor) SetDefaultValue(key string, value interface{})

SetDefaultValue sets a specific value in the defaults section

func (*ClientDescriptor) SetDefaultsSection

func (c *ClientDescriptor) SetDefaultsSection(defaults map[string]interface{})

SetDefaultsSection sets the entire defaults section (used for programmatic configuration)

type CloudComposeConfigRegister

type CloudComposeConfigRegister map[string]ToCloudComposeConvertFunc

type CloudComposeDescriptor

type CloudComposeDescriptor struct {
	StackName       string `json:"stackName" yaml:"stackName"`
	StackDescriptor `json:",inline" yaml:",inline"`
}

type CloudHelper

type CloudHelper interface {
	Run() error
	SetLogger(l logger.Logger)
}

func NewCloudHelper

func NewCloudHelper(chType string, opts ...CloudHelperOption) (CloudHelper, error)

type CloudHelperInitFunc

type CloudHelperInitFunc func(opts ...CloudHelperOption) (CloudHelper, error)

type CloudHelperOption

type CloudHelperOption func(c CloudHelper) error

func WithLogger

func WithLogger(l logger.Logger) CloudHelperOption

type CloudHelperType

type CloudHelperType string

type CloudHelpersRegisterMap

type CloudHelpersRegisterMap map[CloudHelperType]CloudHelperInitFunc

func GetRegisteredCloudHelpers

func GetRegisteredCloudHelpers() CloudHelpersRegisterMap

GetRegisteredCloudHelpers returns all registered cloud helper configurations Used by schema generator to automatically discover cloud helper types

type CloudSingleImageConfigRegister

type CloudSingleImageConfigRegister map[string]ToCloudSingleImageConvertFunc

type CloudStaticSiteConfigRegister

type CloudStaticSiteConfigRegister map[string]ToCloudStaticSiteConvertFunc

type CommonAlertConfig

type CommonAlertConfig struct {
	Threshold   float64 `json:"threshold" yaml:"threshold"`
	PeriodSec   int     `json:"periodSec" yaml:"periodSec"`
	AlertName   string  `json:"alertName" yaml:"alertName"`
	Description string  `json:"description" yaml:"description"`
}

type ComponentConfig

type ComponentConfig struct {
	// contains filtered or unexported fields
}

ComponentConfig wraps *PluginFieldConfig with typed accessors that read its `.Raw` map, for the SC Components class of plugins (slice 1a of the sc-components-platform milestone).

Why a .Raw-reading wrapper rather than a Go interface satisfied by the plugin's typed config struct: the production `sc` binary reaches plugins exclusively via hashicorp/go-plugin gRPC and does NOT link plugin `/api` modules. A plugin-owned config value arrives at core as opaque *PluginFieldConfig, carrying the operator's YAML in `.Raw`. A Go interface defined in core cannot be satisfied by a type living in a plugin repo — the assertion is structurally guaranteed to fail in prod, even when a local test (which links the plugin's `/api`) shows it passing. 7+ exposures of that trap in the first fortnight of the plugin-split work; see the operator memory `interface_assertion_against_plugin_owned_value_fails_in_prod` + the parent `local_shape_not_production_shape`.

Full design: forge/docs/design/2026-11-10/sc-components-platform/ §P1 (Path A — Schema-advertised + .Raw-reading).

func NewComponentConfig

func NewComponentConfig(cfg any) (*ComponentConfig, error)

NewComponentConfig wraps cfg as a ComponentConfig.

Accepted inputs:

  • *PluginFieldConfig — the production path. `cfg.Raw` is the source of truth for all accessor reads.
  • map[string]any — the test path. Lifts the map into a synthetic *PluginFieldConfig so test fixtures can skip the plugin-bus round trip.
  • nil — returns a typed error rather than a nil-wrapped zero value.

Any other concrete type is a programmer error and returns an error naming the actual Go type.

func (*ComponentConfig) DeployTo

func (c *ComponentConfig) DeployTo() (string, error)

DeployTo reads `.Raw["deployTo"]` as a non-empty string.

func (*ComponentConfig) Image

func (c *ComponentConfig) Image() (string, error)

Image reads `.Raw["image"]` as EITHER a non-empty string reference (`"registry/repo:tag"`) OR a build-spec map (`{dockerfile: ..., build: {args: ...}}`). Both shapes are fleet-canonical:

  • **String** — `image: simplecontainer/sc-backup:v1.2.3`. Component plugin pre-built the image + published it (or it's a public image). The dispatched template consumes the reference verbatim.
  • **Map** — `image: {dockerfile: ${git:root}/Dockerfile, build: {args: {...}}}`. SC's own image-build-and-push flow builds the image at provision time and pushes to the operator's ECR under the fleet AWS account. This is the shape every forge-* service uses today.

Returns the string reference when `image` is a string. Returns an empty string when `image` is a map — the dispatched template reads the map shape directly from the merged config, and the empty return signals "no pre-built reference; template does the build." Required: `image` must be present and either shape; missing or wrong type → typed error naming the resource.

This replaces the string-only variant that shipped in slice 1a; caught at the first fleet smoke 2026-11-12 when the smoke-sc-components stack used the map shape per forge-notifier's template.

func (*ComponentConfig) ImageIsBuildSpec

func (c *ComponentConfig) ImageIsBuildSpec() bool

ImageIsBuildSpec returns true when `.Raw["image"]` is a map (the build-at-deploy-time shape), false when it's a string reference. The sidecar wrapper uses this to decide whether to pass `image` through to the dispatched template as a reference or as a build spec.

func (*ComponentConfig) IngressHostname

func (c *ComponentConfig) IngressHostname() (string, error)

IngressHostname reads `.Raw["ingress"].(map)["hostname"]` as a string. Absent hostname (or absent ingress block) returns "" + nil.

func (*ComponentConfig) IngressRegistrar

func (c *ComponentConfig) IngressRegistrar() (string, error)

IngressRegistrar reads `.Raw["ingress"].(map)["registrar"]` as a string. Absent returns "" + nil (component defaults to the parent's default registrar).

func (*ComponentConfig) Raw

func (c *ComponentConfig) Raw() map[string]any

Raw returns the underlying `.Raw` map. Callers must treat it as read-only; use RawCopy for a defensive copy.

func (*ComponentConfig) RawCopy

func (c *ComponentConfig) RawCopy() map[string]any

RawCopy returns a shallow defensive copy of the underlying `.Raw` map so callers (e.g. the sidecar's merge logic) can mutate without disturbing the wrapped config.

func (*ComponentConfig) ServiceEnv

func (c *ComponentConfig) ServiceEnv() (map[string]string, error)

ServiceEnv reads `.Raw["env"]` as a map[string]string. Absent key returns an empty map + nil. Values are coerced to string from map[string]any; non-string values are a shape error.

func (*ComponentConfig) SigningKeyRef

func (c *ComponentConfig) SigningKeyRef() (string, error)

SigningKeyRef reads `.Raw["signingKey"]`. Absent key returns "" + nil (a component without a signingKey is a valid shape; the plugin's ComputeProcess will refuse to mint JWTs without it, but that's a runtime concern).

NOTE: a `${secret:...}` reference pattern check used to live here. Removed 2026-11-11 after the first slice-1a smoke caught that SC core resolves `${secret:...}` → value BEFORE ValidateComponentConfigs runs, so the parse-time pattern check always sees the resolved value and can never pass. Operators who want this field encrypted at rest should declare `signingKey: ${secret:...}` — SC's secret-resolution handles that; this accessor just validates presence + non-empty.

type ComponentValidator

type ComponentValidator interface {
	IsComponentType(typeToken string) bool
	IsOverrideAllowed(typeToken, key string) bool
	TemplateTypeExists(templateType string) bool

	// HasInTreeMerge reports whether the given template type has an in-tree
	// ComponentTemplateMergeFunc registration (e.g. vm-compose). For types
	// that do, the merge func consumes the component's fields inside core
	// before the template's ProvisionFunc runs, so the plugin-side
	// SupportsComponent opt-in (below) is not required.
	HasInTreeMerge(templateType string) bool

	// AnyPluginSupportsComponent reports whether any loaded plugin has
	// advertised supports_component for the given template type via Schema
	// (slice 1a.1 of sc-components-platform; design doc §#19 path (b)). A
	// plugin that has not opted in cannot receive the ComponentRaw
	// side-channel on its Provision RPC; parse-time validation refuses any
	// dispatch targeting such a template, unless the type has an in-tree
	// merge func.
	AnyPluginSupportsComponent(templateType string) bool
}

ComponentValidator is the signature for a callback that validates a single Component resource's config against SC core's set of known Component types. Implementations live in `pkg/clouds/pulumi/api` where the fleet-wide registration maps (ComponentResourceTypes, ComponentAllowedOverrides, ProvisionFuncByType) live; this package stays free of pulumi imports.

The validator reports back the component-resource type, the location in the descriptor, and an error if invalid. Nil return means ok.

type ComputeEnvVariables

type ComputeEnvVariables struct {
	DiscordWebhookUrl string
	SlackWebhookUrl   string
	TelegramChatID    string
	TelegramToken     string
	AlertName         string
	AlertDescription  string
	StackName         string
	StackEnv          string
	CloudHelperType   string
	StackVersion      string
	// CloudProvider names the cloud a service was deployed to. It exists
	// because Yandex does not identify itself at runtime — its Serverless
	// Containers runtime defines exactly PORT and REQUEST_PATH, neither of
	// which names the cloud — so go-aws-lambda-sdk reads this to decide
	// whether to serve HTTP or start the Lambda runtime loop.
	CloudProvider string
	// CloudTrail enrichment: when all three are set on the alert Lambda,
	// the handler looks up matching CloudTrail events in the alarm's time
	// window and includes a short summary (who/what/when) in the Slack/
	// Discord/Telegram notification.
	CtLogGroupName   string
	CtLogGroupRegion string
	CtFilterPattern  string
}

type Config

type Config struct {
	Config any `json:"config" yaml:"config"`
}

func ConvertConfig

func ConvertConfig[T any](config *Config, to *T) (Config, error)

func ReadProvisionerFieldConfig

func ReadProvisionerFieldConfig(cType string, config *Config) (Config, error)

func (*Config) Copy

func (s *Config) Copy() Config

type ConfigFile

type ConfigFile struct {
	ProjectName        string `json:"projectName" yaml:"projectName"`
	PrivateKeyPath     string `yaml:"privateKeyPath,omitempty" json:"privateKeyPath,omitempty"`
	PublicKeyPath      string `yaml:"publicKeyPath,omitempty" json:"publicKeyPath,omitempty"`
	PrivateKey         string `yaml:"privateKey,omitempty" json:"privateKey,omitempty"`
	PrivateKeyPassword string `yaml:"privateKeyPassword,omitempty" json:"privateKeyPassword,omitempty"`
	PublicKey          string `yaml:"publicKey,omitempty" json:"publicKey,omitempty"`
	StacksDir          string `yaml:"stacksDir,omitempty" json:"stacksDir,omitempty"`
	ParentRepository   string `yaml:"parentRepository,omitempty" json:"parentRepository,omitempty"`
}

func ReadConfigFile

func ReadConfigFile(workDir, profile string) (*ConfigFile, error)

func (*ConfigFile) ToYaml

func (f *ConfigFile) ToYaml() ([]byte, error)

func (*ConfigFile) WriteConfigFile

func (f *ConfigFile) WriteConfigFile(workDir, profile string) error

type ConfigReaderFunc

type ConfigReaderFunc func(config *Config) (Config, error)

type ConfigRegisterMap

type ConfigRegisterMap map[string]ConfigReaderFunc

func GetRegisteredProviderConfigs

func GetRegisteredProviderConfigs() ConfigRegisterMap

GetRegisteredProviderConfigs returns all registered provider configurations Used by schema generator to automatically discover all resource types

type Container

type Container struct {
	ContainerImage `json:",inline" yaml:",inline"`
	Name           string `json:"name" yaml:"name"`
}

type ContainerImage

type ContainerImage struct {
	Name       string `json:"name" yaml:"name"`
	Dockerfile string `json:"dockerfile" yaml:"dockerfile"`
	Context    string `json:"context" yaml:"context"`

	Build    *ContainerImageBuild `json:"build" yaml:"build"`
	Platform ImagePlatform        `json:"platform" yaml:"platform"`
}

type ContainerImageBuild

type ContainerImageBuild struct {
	Args map[string]string `json:"args" yaml:"args"`
}

type CorsConfig

type CorsConfig struct {
	AllowedOrigins string   `json:"allowedOrigins" yaml:"allowedOrigins"`
	AllowedMethods []string `json:"allowedMethods,omitempty" yaml:"allowedMethods"`
}

type Credentials

type Credentials struct {
	Credentials string `json:"credentials" yaml:"credentials"` // required for proper deserialization
}

type DefectDojoDescriptor

type DefectDojoDescriptor struct {
	Enabled        bool     `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	URL            string   `json:"url,omitempty" yaml:"url,omitempty"`
	APIKey         string   `json:"apiKey,omitempty" yaml:"apiKey,omitempty"`
	EngagementID   int      `json:"engagementId,omitempty" yaml:"engagementId,omitempty"`
	EngagementName string   `json:"engagementName,omitempty" yaml:"engagementName,omitempty"`
	ProductID      int      `json:"productId,omitempty" yaml:"productId,omitempty"`
	ProductName    string   `json:"productName,omitempty" yaml:"productName,omitempty"`
	TestType       string   `json:"testType,omitempty" yaml:"testType,omitempty"`
	Tags           []string `json:"tags,omitempty" yaml:"tags,omitempty"`
	Environment    string   `json:"environment,omitempty" yaml:"environment,omitempty"`
	AutoCreate     bool     `json:"autoCreate,omitempty" yaml:"autoCreate,omitempty"`
}

DefectDojoDescriptor configures DefectDojo upload.

func (*DefectDojoDescriptor) Sanitize

Sanitize returns a copy of this descriptor with the API key replaced by a placeholder string, safe for logging or debug serialization.

type DeployParams

type DeployParams struct {
	StackParams `json:",inline" yaml:",inline"`
	Vars        VariableValues `json:"vars" yaml:"vars"`
}

type DestroyParams

type DestroyParams struct {
	StackParams         `json:",inline" yaml:",inline"`
	DestroySecretsStack bool `json:"destroySecretsStack" yaml:"destroySecretsStack"`
}

type DestroyResult

type DestroyResult struct {
	Operations map[string]int `json:"operations" yaml:"operations"`
}

func (*DestroyResult) String

func (r *DestroyResult) String() string

type DiscordCfg

type DiscordCfg struct {
	WebhookUrl string `json:"webhookUrl" yaml:"webhookUrl"`
}

type DnsConfigAware

type DnsConfigAware interface {
	OverriddenBaseZone() string
}

type DnsRecord

type DnsRecord struct {
	Name string `json:"name" yaml:"name"`
	Type string `json:"type" yaml:"type"`
	// ValueOut threads a Pulumi Output through in-process callers so a
	// record's value can be a resolved resource property. It is not
	// serializable (sdk.StringOutput's MarshalJSON refuses) and must be
	// excluded from JSON/YAML marshaling — the plugin bus serializer in
	// pkg/clouds/pulumi/plugin_sidecars.go would otherwise fail the entire
	// config serialization and leave the plugin without accountId/zoneName.
	ValueOut sdk.StringOutput `json:"-" yaml:"-"`
	Value    string           `json:"value" yaml:"value"`
	Proxied  bool             `json:"proxied" yaml:"proxied"`
	// Priority is used by MX / SRV / URI record types and ignored by
	// every other type (CNAME / A / TXT etc.). Nilable so the common
	// case (non-MX records) marshals as empty rather than `priority: 0`,
	// which cloudflare-pulumi's Record resource treats as a value
	// rather than "unset" and sends to the API — producing an MX with
	// priority 0 where the operator intended "not applicable".
	// pulumi-cloudflare/sdk/v6 Record documents: "Required for MX, SRV
	// and URI records; unused by other record types."
	Priority *int `json:"priority,omitempty" yaml:"priority,omitempty"`
}

type EmailCfg

type EmailCfg struct {
	Addresses []string `json:"addresses,omitempty" yaml:"addresses,omitempty"`
}

type Headers

type Headers map[string]string

type ImageBuildDescriptor

type ImageBuildDescriptor struct {
	// ReuseExistingCommitTag makes a deploy reuse the image already in the
	// registry when the version already names a commit and is already present,
	// instead of pushing a rebuild over it. Only versions of the form
	// YYYY.MM.DD-<abbreviated commit sha> qualify. Defaults to false.
	ReuseExistingCommitTag bool `json:"reuseExistingCommitTag,omitempty" yaml:"reuseExistingCommitTag,omitempty"`
}

ImageBuildDescriptor configures how images are built and pushed.

type ImagePlatform

type ImagePlatform string
const (
	ImagePlatformLinuxAmd64 ImagePlatform = "linux/amd64"
)

type Inherit

type Inherit struct {
	Inherit string `json:"inherit" yaml:"inherit"`
}

func (Inherit) IsInherited

func (i Inherit) IsInherited() bool

type InitParams

type InitParams struct {
	ProjectName         string `json:"projectName" yaml:"projectName"`
	RootDir             string `json:"rootDir,omitempty" yaml:"rootDir"`
	Profile             string `json:"profile,omitempty" yaml:"profile"`
	SkipInitialCommit   bool   `json:"skipInitialCommit" yaml:"skipInitialCommit"`
	SkipProfileCreation bool   `json:"skipProfileCreation" yaml:"skipProfileCreation"`
	SkipScDirCreation   bool   `json:"skipScDirCreation" yaml:"skipScDirCreation"`
	IgnoreWorkdirErrors bool   `json:"skipCreateConfigDir" yaml:"skipCreateConfigDir"`
	GenerateKeyPair     bool   `json:"generateKeyPair" yaml:"generateKeyPair"`
}

type MaxCPUConfig

type MaxCPUConfig struct {
	CommonAlertConfig `json:",inline" yaml:",inline"`
}

type MaxErrorConfig

type MaxErrorConfig struct {
	CommonAlertConfig     `json:",inline" yaml:",inline"`
	ErrorLogMessageRegexp string `json:"errorLogMessageRegexp" yaml:"errorLogMessageRegexp"`
}

type MaxMemoryConfig

type MaxMemoryConfig struct {
	CommonAlertConfig `json:",inline" yaml:",inline"`
}

type MetadataDescriptor

type MetadataDescriptor struct {
	IncludeEnv       bool `json:"includeEnv,omitempty" yaml:"includeEnv,omitempty"`
	IncludeMaterials bool `json:"includeMaterials,omitempty" yaml:"includeMaterials,omitempty"`
}

MetadataDescriptor configures metadata collection

type OutputDescriptor

type OutputDescriptor struct {
	Local    string `json:"local,omitempty" yaml:"local,omitempty"`       // Local file path
	Registry bool   `json:"registry,omitempty" yaml:"registry,omitempty"` // Upload to registry
}

OutputDescriptor configures output destinations

type OutputsResult

type OutputsResult struct {
	StackName string         `json:"stackName" yaml:"stackName"`
	Outputs   map[string]any `json:"outputs" yaml:"outputs"`
}

type PRCommentDescriptor

type PRCommentDescriptor struct {
	Enabled bool   `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	Output  string `json:"output,omitempty" yaml:"output,omitempty"`
}

PRCommentDescriptor configures markdown output for PR comment workflows.

type ParentResourceDependency

type ParentResourceDependency struct {
	Name string `json:"name" yaml:"name"`
}

ParentResourceDependency when a resource depends on resource within the same stack

type PerEnvResourcesDescriptor

type PerEnvResourcesDescriptor struct {
	Template  string                        `json:"template" yaml:"template"`
	Resources map[string]ResourceDescriptor `json:"resources" yaml:"resources"`
	Inherit   `json:",inline" yaml:",inline"`
}

func (*PerEnvResourcesDescriptor) Copy

type PerStackResourcesDescriptor

type PerStackResourcesDescriptor struct {
	// Registrar is the legacy single-registrar form. Mutually exclusive with Registrars.
	Registrar RegistrarDescriptor `json:"registrar" yaml:"registrar"`
	// Registrars allows several registrars to coexist, each serving its own DNS zones.
	// The one that handles a given domain is picked by zone suffix. See AllRegistrars.
	Registrars map[string]RegistrarDescriptor       `json:"registrars,omitempty" yaml:"registrars,omitempty"`
	Resources  map[string]PerEnvResourcesDescriptor `json:"resources" yaml:"resources"`
}

func (PerStackResourcesDescriptor) AllRegistrars

AllRegistrars normalises the two ways a server.yaml may declare registrars — the legacy single `registrar:` block and the `registrars:` map — into a single map. Declaring both at once is an error rather than a silent precedence rule. The result is empty when no registrar is configured, which is a valid configuration.

func (*PerStackResourcesDescriptor) Copy

type PluginClientConfig

type PluginClientConfig struct {
	Security   *SecurityDescriptor   `json:"security,omitempty"`
	ImageBuild *ImageBuildDescriptor `json:"imageBuild,omitempty"`
}

PluginClientConfig is the part of the client descriptor that crosses the plugin bus with a template's Provision request: what docker.BuildAndPushImage reads off stack.Client. A plugin cannot rebuild it, because it builds its api.Stack from the request header alone.

type PluginFieldConfig

type PluginFieldConfig struct {
	TypeName    string         `json:"type" yaml:"type"`
	Raw         map[string]any `json:"-" yaml:"-"`
	URL         string         `json:"url" yaml:"url"`
	Credentials string         `json:"credentials" yaml:"credentials"`
	ProjectID   string         `json:"projectId" yaml:"projectId"`
	Provision   bool           `json:"provision" yaml:"provision"`
}

PluginFieldConfig is the SC-core-side carrier for a provisioner-field config (state-storage or secrets-provider) that a plugin owns. Implements api.StateStorageConfig and api.AuthConfig minimally; the plugin itself has the authoritative view of its config via its own InitStateStore RPC.

func (*PluginFieldConfig) CredentialsValue

func (p *PluginFieldConfig) CredentialsValue() string

CredentialsValue returns the string the placeholder resolver substitutes for `${auth:<name>}`. Two shapes:

  • `.Credentials` is non-empty — a `credentials: "…"` key was declared in YAML (state-storage / secrets-provider form) — return it verbatim.
  • `.Credentials` is empty but `.Raw` has entries — this is an AUTH block (aws-token, yc-service-account, cloudru-access-key, …). The pre-A3 typed AuthConfig impls returned `api.AuthToString(r)` in this case — a JSON serialisation of the whole struct — so a downstream plugin decoding `credentials: "…"` could parse the full account config. Mirror that here by marshalling Raw.

Returns empty string only when there is genuinely no credential material to expand (ambient-credential path; UsesAmbientCredentials relies on this).

func (*PluginFieldConfig) DnsRecords

func (p *PluginFieldConfig) DnsRecords() []DnsRecord

DnsRecords implements api.RegistrarConfig for plugin-owned registrars (cloudflare, cloudru-dns, yc-dns, …). Reads the `dnsRecords` list out of the Raw map that pluginOwnedWrappingDecoder preserved — the plugin bus's RegistrarConfig type-assertion at pkg/clouds/pulumi/plugin_sidecars.go:382 required this method, and without it operator-declared `dnsRecords:` entries on a plugin-owned registrar were silently dropped on the wire. Live-caught 2026-11-03 against sc-plugin-cloudflare v2026.11.02-8b9eb75: a navizon-infra server.yaml with four `dnsRecords:` entries completed `sc provision` as `Resources: 2 unchanged` and never emitted any `cloudflare:index/record:Record`.

The `type` key is consulted first for the DnsRecord type field; a `proxied` key arrives from YAML as `bool` but the bus serialises the whole map through JSON, which keeps bools as bools in map[string]any, so no extra parsing is needed for this scalar — the map[string]any unmarshal path keeps them bool-typed.

func (*PluginFieldConfig) IsProvisionEnabled

func (p *PluginFieldConfig) IsProvisionEnabled() bool

func (*PluginFieldConfig) KeyUrl

func (p *PluginFieldConfig) KeyUrl() string

KeyUrl is the secrets-provider key reference. A plugin-owned provider used with `provision: false` names its key in `keyName` (the typed gcp-kms and aws-kms configs returned it from KeyUrl), so fall back to it when no `url` is set; otherwise login fails with "secrets provider key url is empty".

func (*PluginFieldConfig) MarshalJSON

func (p *PluginFieldConfig) MarshalJSON() ([]byte, error)

MarshalJSON merges the Raw map with the typed fields so the plugin bus (pkg/clouds/pulumi.serializeConfigToInputs → json.Marshal → gRPC InputValue tree) carries the full operator-declared config, not just the four typed slots.

Two reasons this is needed. First, Raw holds operator-declared keys that have no typed slot — `bucketName` on state-storage, `keyName` on secrets-provider — and without merging them the plugin never sees them (`Raw` carries `json:"-"`). Second, the placeholder resolver (pkg/provisioner/placeholders) walks the typed fields BOTH as struct fields AND via the Raw map; both end up with resolved values post- Resolve. Merging in this order (Raw first, typed fields override) means a stray stale value in Raw is beaten by the typed field, so a re-run after an edit cannot ship pre-resolution data.

Live-caught 2026-11-03 on forge-conductor isolated verify run 41680853191: plugin received `credentials: "${auth:aws}"` because json.Marshal(*PluginFieldConfig) only emitted the four typed fields, and the resolver's path to one of them was obstructed by an unexported ancestor. Merging via Raw sidesteps that walker-path fragility: whichever route the resolver takes, the plugin bus sees the resolved value.

func (*PluginFieldConfig) MarshalYAML

func (p *PluginFieldConfig) MarshalYAML() (interface{}, error)

MarshalYAML mirrors MarshalJSON for the yaml.v3 path. Parent-stack provisioning (pkg/clouds/pulumi/provision.go) `yaml.Marshal`s each StackDescriptor into a Pulumi-exported secret the child deploy later reads back via `yaml.Unmarshal`. Without a MarshalYAML, the default struct-tag path honours `yaml:"-"` on Raw and emits only the four typed slots — operator-declared keys that have no typed counterpart (`accountId`, `bucketName`, `zoneName`, …) silently disappear from the state, and the child deploy dials the plugin with an empty `accountId` → `ToPagesConfig` → `accountId is empty`.

Live-caught 2026-11-03 on navizon's cloudflare-static-website isolated-stack child deploy. Diagnosed by navizon session; same merge semantics as MarshalJSON.

func (*PluginFieldConfig) ProjectIdValue

func (p *PluginFieldConfig) ProjectIdValue() string

func (*PluginFieldConfig) ProviderType

func (p *PluginFieldConfig) ProviderType() string

func (*PluginFieldConfig) StorageUrl

func (p *PluginFieldConfig) StorageUrl() string

func (*PluginFieldConfig) UsesAmbientCredentials

func (p *PluginFieldConfig) UsesAmbientCredentials() bool

func (*PluginFieldConfig) Zones

func (p *PluginFieldConfig) Zones() []string

Zones implements RegistrarZonesAware for a plugin-owned registrar.

Without this, no registrar config that core holds as an OPAQUE PluginFieldConfig can report its zones — and in the SHIPPED binary that is every plugin-owned registrar, because `cmd/sc` links no plugin's Go module at all (plugins are reached over hashicorp/go-plugin gRPC). `declaredZones` (pkg/clouds/pulumi/registrars.go) therefore read no zones, `multiRegistrar.forDomain` could not match, and every domain fell through to whichever registrar is marked `default: true`.

That is what broke the 2026-11-09 `.ru` landing: with Cloudflare as the fleet's default, `simple-forge.ru` routed to CLOUDFLARE, so

  • the cloudflare plugin was asked to serve it and answered `error retrieving zone ID for domain "simple-forge.ru": 0 found`;
  • and `provisionDomainRegistrar` computed `regType = cloudflare`, found that the YANDEX plugin does not serve that type, took its early return, and the yandex plugin refused with `no yc-dns registrar initialised that serves "simple-forge.ru"`.

Fixed by this method; `.ru` deployed green on v2026.11.45 with both preview and deploy logging `initialising yandex registrar for zone "simple-forge.ru"` → `ready; main domain is "simple-forge.ru"`.

A WARNING for anyone re-measuring this in a test. A test binary in `pkg/clouds/pulumi` sees `yc-dns` as a TYPED *yandex.RegistrarConfig, not as an opaque config, because a sibling test file (plugin_inputs_test.go) imports `sc-plugin-yandex/api` and that registers the typed decoder. The shipped binary does not:

go list -deps ./cmd/sc              | grep -c sc-plugin-yandex  -> 0
go list -deps -test ./pkg/clouds/pulumi | grep sc-plugin-yandex -> api

So a local test can show this bug as already-fixed when production has it, which is exactly what happened mid-investigation and briefly cost this fix a wrongful retraction. Measure the import graph before trusting a Go type observed in a test.

The information was never missing — `Raw` carries the operator's `zoneName:` verbatim. Nothing read it.

Both spellings are accepted because both are in use: a single `zoneName:` (cloudflare, yc-dns) and a `zones:` list. A registrar that declares neither returns nil and keeps the old behaviour — it can still be the stack's only registrar, or its default.

type PluginOutputValue

type PluginOutputValue struct {
	Value  any
	Secret bool
}

PluginOutputValue is one value a plugin published from its ProvisionResponse, carrying the plugin's own `secret` flag alongside it.

The flag is not decoration. A consumer that renders a value into a config file, a command line or a Pulumi input has to know whether to wrap it in `sdk.ToSecret` first: an HMAC secret key or a database password that arrives here unflagged lands in preview and apply logs in cleartext, and in the state bucket readable by anything that can read state. The flag is set by the plugin on InputValue.secret (plugin.proto field 10) and is honoured both on the parent stack root's exports and here, on the in-memory sibling path.

type PluginOwnedBinding

type PluginOwnedBinding struct {
	Kind       PluginOwnedKind
	PluginName string // name under server.yaml's plugins: block
}

PluginOwnedBinding is the record for a single type → plugin association captured by RegisterPluginOwnedType.

func IsPluginOwnedType

func IsPluginOwnedType(name string) (PluginOwnedBinding, bool)

IsPluginOwnedType reports whether name was recorded by RegisterPluginOwnedType and returns the full binding (kind + plugin name). Lookups are case sensitive — plugin type names are matched byte-for-byte.

type PluginOwnedKind

type PluginOwnedKind string

PluginOwnedKind labels which role a plugin-registered type fills so the three Detect call-sites in read.go and the three Prepare*ForDeploy branches in client.go can tell plugin-owned templates from plugin-owned resources/registrars/provisioner-fields.

Populated at parse time by pkg/stackread via RegisterPluginOwnedType — one entry per type each declared plugin's Schema RPC advertises.

const (
	PluginOwnedKindResource         PluginOwnedKind = "resource"
	PluginOwnedKindTemplate         PluginOwnedKind = "template"
	PluginOwnedKindRegistrar        PluginOwnedKind = "registrar"
	PluginOwnedKindStateStore       PluginOwnedKind = "state-store"
	PluginOwnedKindSecretsProvider  PluginOwnedKind = "secrets-provider"
	PluginOwnedKindComputeProcessor PluginOwnedKind = "compute-processor"
	PluginOwnedKindVmDriver         PluginOwnedKind = "vm-driver"
	PluginOwnedKindProvisionerField PluginOwnedKind = "provisioner-field"

	// PluginOwnedKindAuth labels a `type:` discriminator used in a
	// server.yaml / secrets.yaml `auth:` block. Deliberately equal to
	// `PluginOwnedKindResource + "/auth"` — the composite string already
	// shipped in `plugin_bootstrap.go` for aws/yandex/cloudru entries, so
	// adding this const + refactoring the three literals is byte-identical
	// to the existing registration; nothing changes for the five
	// link-time-imported + bootstrap-table-seeded plugins.
	//
	// The const is what `stackread.registerSchemaTypes` passes to
	// `RegisterPluginOwnedType` for every entry in a plugin's
	// `SchemaResponse.auth_types`. Kind is read for provenance only; the
	// state-store/secrets-provider branch at `mapping.go:162` fires on
	// distinct kinds, so auth seeds `providerConfigMapping` alone (which
	// is what `DetectAuthProvider` at `read.go:183` reads, and the only
	// map the auth path touches).
	PluginOwnedKindAuth PluginOwnedKind = PluginOwnedKindResource + "/auth"
)

type PluginPreparedInput

type PluginPreparedInput struct {
	// Input is the plugin's typed Input (decoded back into a
	// map[string]any by pkg/stackread via scPlugin.InputsToPlain so
	// the reflect walker never has to deal with unexported fields the
	// plugin's typed struct might have carried).
	Input any `yaml:"input,omitempty" json:"input,omitempty"`
	// BaseDnsZone_ is the typed Input's api.DnsConfigAware.OverriddenBaseZone.
	BaseDnsZone_ string `yaml:"baseDnsZone,omitempty" json:"baseDnsZone,omitempty"`
	// Uses_ is the typed Input's api.ResourceAware.Uses.
	Uses_ []string `yaml:"uses,omitempty" json:"uses,omitempty"`
	// DependsOnResources_ is the typed Input's
	// api.WithDependsOnResources.DependsOnResources.
	DependsOnResources_ []StackConfigDependencyResource `yaml:"dependsOnResources,omitempty" json:"dependsOnResources,omitempty"`
	// Domain_ is the `domain:` the operator declared on the CLIENT stack,
	// carried here for the same reason as the three fields above: a
	// downstream consumer needs it and must not have to parse the plugin's
	// own Input to find it.
	//
	// The consumer is provisionDomainRegistrar (pkg/clouds/pulumi/
	// plugin_sidecars.go), which resolves the registrar for a plugin
	// template's zone — core builds registrars lazily, so a zone only the
	// plugin publishes in is never sent to it otherwise. It used to read the
	// domain out of the descriptor's config, which works while that config is
	// the client's `{"stackConfig":{…}}` but NOT for a plugin-owned template,
	// where the descriptor carries this struct instead and there is no
	// `stackConfig` key anywhere in it. That is why
	// forge-landing-ru-apex--staging kept failing with `no yc-dns registrar
	// initialised that serves "simple-forge.ru"` even after the probe learned
	// the nested-Site spelling: the probe was being handed the wrong object.
	//
	// Each plugin mirrors the domain somewhere in its own Input under its own
	// name (sc-plugin-yandex and sc-plugin-aws both use `siteDomain`), so
	// there is no field name core could agree on. This one is core's.
	Domain_ string `yaml:"domain,omitempty" json:"domain,omitempty"`
}

PluginPreparedInput wraps a PluginStackConvertResult as a Go value that satisfies DnsConfigAware, ResourceAware, and WithDependsOnResources — the three interfaces SC core type-asserts off clientStackDesc.Config.Config at pkg/clouds/pulumi/deploy.go (lines 133, 146, 153) and pkg/provisioner/unresolved.go (109, 112).

EVERY FIELD MUST BE EXPORTED. SC core walks this struct via reflection in pkg/provisioner/placeholders (applyTemplatesRecursive) for `${X}` placeholder substitution, and that walker calls reflect.Value.Set on every field. A reflect.Set into an unexported field panics with "reflect.Value.Set using value obtained using unexported field" — live-caught on forge-aigateway isolated run 41469779418 (2026-11-02), which panicked before any resource was provisioned and failed every service in the matrix.

Also satisfies the no-op side of each interface for stacks whose plugin response omitted the structured fields (empty []string / nil slice reads as "no constraints" — same as a stack that never declared the attribute).

Note that method NAMES collide with the fields they expose, so the fields have an underscore suffix. The interface methods thunk to the fields and are what Go code sees via type-assertion; the fields are what the placeholders walker sees via reflection.

func NewPluginPreparedInput

func NewPluginPreparedInput(result *PluginStackConvertResult) *PluginPreparedInput

NewPluginPreparedInput wraps a plugin's typed Input + the three structured fields for downstream type-asserts. The pkg/stackread converter calls this after decoding the ConvertStackConfigResponse.

func (*PluginPreparedInput) DependsOnResources

func (p *PluginPreparedInput) DependsOnResources() []StackConfigDependencyResource

DependsOnResources implements WithDependsOnResources.

func (*PluginPreparedInput) MarshalJSON

func (p *PluginPreparedInput) MarshalJSON() ([]byte, error)

MarshalJSON unwraps PluginPreparedInput for the Provision bus. SC core forwards the deploying stack's `Config.Config` across the bus via pkg/clouds/pulumi/plugin_sidecars.go's serializeConfigToInputs, which calls json.Marshal. The plugin's Provision handler decodes the resulting InputValue tree into its typed Input shape (*LambdaInput, *StaticSiteInput, …). Without this method, the serialised shape would be `{input: {...real Input fields...}, baseDnsZone: ..., uses: [...], dependsOnResources: [...]}` — and the plugin's decoder would find every expected Input field at the top level is nil, panic'ing on first dereference. Live-caught on forge-aigateway isolated-stack run 41483738313 (2026-11-02).

Returning just p.Input makes the wire shape identical to what SC core's pre-A2 Prepare*ForDeploy produced: the raw typed Input is what the plugin's Provision handler expects.

SC core's own interface asserts (DnsConfigAware / ResourceAware / WithDependsOnResources) are still answered by the methods above — those read the exported *_ fields, which are preserved on the SC-core-side wrapper. Only the WIRE representation unwraps.

func (*PluginPreparedInput) OverriddenBaseZone

func (p *PluginPreparedInput) OverriddenBaseZone() string

OverriddenBaseZone implements DnsConfigAware.

func (*PluginPreparedInput) StackConfigDomain

func (p *PluginPreparedInput) StackConfigDomain() string

StackConfigDomain returns the client stack's declared domain. Mirrors the OverriddenBaseZone / Uses / DependsOnResources accessors above.

func (*PluginPreparedInput) Uses

func (p *PluginPreparedInput) Uses() []string

Uses implements ResourceAware.

type PluginRequirement

type PluginRequirement struct {
	// PluginName is the key operators write under `plugins:` in server.yaml.
	// It MUST match the name the plugin itself uses — it's what SC core
	// matches against `desc.Plugins[PluginName]`.
	PluginName string

	// OwnedTypes are the type tokens (resource / registrar / provider /
	// state-storage / secrets-provider / compute-processor / template)
	// this plugin's /api module registers.
	OwnedTypes []string

	// DefaultSource is the `source:` block the auto-injector uses when
	// an operator's server.yaml references OwnedTypes without declaring
	// `plugins.<PluginName>`. Version is left empty — resolved against
	// the GitHub releases API at parse time.
	DefaultSource PluginSource
}

PluginRequirement names a plugin and the type tokens it owns. Each out-of-tree sc-plugin's `/api` module calls RegisterPluginRequirement at init() time so that SC core — which has already deleted the corresponding in-tree subtree — can detect missing `plugins:` blocks in server.yaml and auto-inject the latest release BEFORE any Pulumi state is touched.

See forge/docs/design/2026-10-24/sc-plugin-architecture/ 04-no-destroy-invariant.md Addendum J.

func LookupPluginRequirement

func LookupPluginRequirement(typeToken string) (PluginRequirement, bool)

LookupPluginRequirement returns the plugin requirement that owns a type token, if any. False when the type is in-tree (or unknown).

type PluginResourceOutput

type PluginResourceOutput struct {
	// PluginName is the plugin that owns the resource (e.g. `gcp`).
	PluginName string
	// Urn is the Pulumi URN the plugin registered the resource under.
	Urn string
	// Outputs is what the plugin published, keyed exactly as the plugin exported
	// it — the same keys that appear on the parent stack root. Values a plugin
	// sent in a shape core cannot represent as a plain Go value are absent rather
	// than zeroed.
	Outputs map[string]PluginOutputValue
}

PluginResourceOutput is what a plugin-owned parent-stack resource leaves on api.ResourceOutput.Ref, so that a SIBLING resource provisioned after it can read what it produced.

Why this type exists: resources that declare WithParentDependencies are provisioned after their dependencies and receive the accumulated `map[string]*ResourceOutput` (see pkg/clouds/pulumi/provision.go). An in-tree resource puts its typed output on `.Ref` and the consumer type-asserts it — that is how a k3s cluster learns its machines' addresses. A plugin-owned resource used to put the bare string `plugin:<name>:<urn>` there, so a sibling learned the URN and nothing else, even though core had just harvested every value the plugin published. Post plugin-extraction most resources are plugin-owned — buckets, databases, registries — which is exactly the set a new sibling dependency wants to read.

String() still renders `plugin:<name>:<urn>` so anything that logged or formatted the old placeholder reads identically. Values are deliberately NOT part of that rendering: some of them are secret.

func PluginOutputsOf

func PluginOutputsOf(outs map[string]*ResourceOutput, resourceName string) (*PluginResourceOutput, error)

PluginOutputsOf resolves a plugin-owned sibling's outputs out of the outputs of the resources provisioned before this one.

`outs` is ProvisionParams.ResourceOutputs. A consumer only receives a sibling in there if its own config implements WithParentDependencies and names that resource — so "not found" almost always means the dependency was never declared, and the error says so rather than reporting an absence.

func (*PluginResourceOutput) Lookup

Lookup returns one published value and whether the plugin published it at all.

func (*PluginResourceOutput) String

func (o *PluginResourceOutput) String() string

String renders the resource the way the pre-typed placeholder did.

Nil-safe because PluginOutputsOf's error paths hand back a nil output alongside the error, and a caller that logs and carries on would otherwise panic inside the logging rather than at the mistake.

func (*PluginResourceOutput) StringOf

func (o *PluginResourceOutput) StringOf(key string) (string, error)

StringOf reads one published value as a string.

The error lists the keys that WERE published, because the realistic failure is not a typo: it is a plugin version that predates the key being asked for, or a resource whose export names are keyed off its own name and so differ per declaration. Without the list, the operator sees "no output X" and has no way to find out what to ask for instead.

type PluginSource

type PluginSource struct {
	// Type of the source. v1: "github-release".
	Type string `json:"type" yaml:"type"`

	// Repository identifier. For github-release: "owner/repo" (e.g.
	// "simple-container-com/sc-plugin-cloudflare").
	Repository string `json:"repository" yaml:"repository"`

	// Version tag — a specific release name. "latest" is NOT supported in
	// v1: operators pin a version explicitly so deploys are reproducible.
	Version string `json:"version" yaml:"version"`

	// BinaryName overrides the default binary filename resolution. Default
	// derivation: "sc-plugin-<name>-<goos>-<goarch>[.exe]" where <name> is
	// the repo name minus the "sc-plugin-" prefix (e.g.
	// simple-container-com/sc-plugin-cloudflare → "sc-plugin-cloudflare").
	BinaryName string `json:"binaryName,omitempty" yaml:"binaryName,omitempty"`
}

PluginSource describes where SC should fetch a plugin binary from. Only "github-release" is supported in v1; "oci" is a planned addition (see 03 §6.2).

type PluginSpec

type PluginSpec struct {
	// Path to the plugin binary on disk. Mutually exclusive with Source — if
	// both are set, Path wins. For dev loops + air-gapped operators.
	Path string `json:"path,omitempty" yaml:"path,omitempty"`

	// Source resolves to a downloaded + cached binary. Set this for the
	// standard operator flow — points at a plugin repo's release.
	Source *PluginSource `json:"source,omitempty" yaml:"source,omitempty"`

	// SHA256 hex digest of the binary. When set, SC refuses to spawn a
	// binary whose hash does not match — the integrity guard from D10.
	// For Source-based specs, SC additionally cross-checks against the
	// release's sha256sums.txt asset if present. When empty, SC logs a
	// WARN but proceeds.
	SHA256 string `json:"sha256,omitempty" yaml:"sha256,omitempty"`
}

PluginSpec configures one SC plugin that will be loaded at provision time. Operators give either a local path (dev / air-gapped) or a source block that SC resolves at load time against a GitHub Release.

func (*PluginSpec) Copy

func (s *PluginSpec) Copy() PluginSpec

Copy deep-copies the spec, including the Source pointer — a shared pointer would let one stack's placeholder resolution mutate another's pin.

type PluginStackConvertRequest

type PluginStackConvertRequest struct {
	TemplateType string
	StackName    string
	StackDir     string
	// StackConfig is one of *StackConfigCompose, *StackConfigSingleImage,
	// or *StackConfigStatic. stackread marshals it to the proto's
	// map<string, InputValue> wire form.
	StackConfig any
	// TemplateConfig is the parent-side TEMPLATE config body — the raw
	// map or typed struct `stackDesc.Config.Config` carries after
	// DetectTemplateType ran. For plugin-owned templates it is a raw
	// map[string]any (the opaque decoder preserved the YAML tree); the
	// plugin decodes it into its own typed TemplateConfig on receipt.
	TemplateConfig any
}

PluginStackConvertRequest carries the operator-side state the plugin's existing /api-registered ToXxxConfig closures already consume: the typed StackConfig (compose/single-image/static), the stack name, and the ${git:root}-resolved stackDir. All scalar — no SC-core-side types that cannot cross a gRPC boundary.

type PluginStackConvertResult

type PluginStackConvertResult struct {
	// Input is the plugin's typed Input (*LambdaInput /
	// *StaticSiteInput / *EcsFargateInput etc.) decoded from the RPC
	// response. SC core forwards it verbatim through the Provision RPC
	// — the plugin's Provision handler receives the same shape it
	// returned here, keeping the end-to-end round-trip stable.
	Input any
	// BaseDnsZone satisfies DnsConfigAware.OverriddenBaseZone.
	BaseDnsZone string
	// Uses satisfies ResourceAware.Uses.
	Uses []string
	// DependsOnResources satisfies WithDependsOnResources.DependsOnResources.
	DependsOnResources []StackConfigDependencyResource
}

PluginStackConvertResult mirrors the typed response SC core wraps in pluginPreparedInput. The three downstream interfaces (DnsConfigAware, ResourceAware, WithDependsOnResources) read exactly these fields.

type PluginStackConverter

type PluginStackConverter func(ctx context.Context, pluginName string, req PluginStackConvertRequest) (*PluginStackConvertResult, error)

PluginStackConverter is the injection point SC core's parse-time path uses to turn a plugin-owned template's merged StackConfig* into the plugin's typed Input via the ConvertStackConfig RPC. The dialling code lives in pkg/stackread (which imports pkg/plugin — allowed) and registers itself here with RegisterPluginStackConverter at init-time.

Why a function variable instead of calling pkg/plugin directly: pkg/api cannot import pkg/plugin (pkg/plugin already imports pkg/api — the cycle is why stackread exists as a leaf). The seam keeps pkg/api clean while letting Prepare*ForDeploy branch on plugin-owned types.

type PreviewResult

type PreviewResult struct {
	StackName  string         `json:"stackName" yaml:"stackName"`
	Summary    string         `json:"summary" yaml:"summary"`
	Operations map[string]int `json:"operations" yaml:"operations"`
}

func (*PreviewResult) String

func (r *PreviewResult) String() string

type ProvenanceDescriptor

type ProvenanceDescriptor struct {
	Enabled       bool                `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	Format        string              `json:"format,omitempty" yaml:"format,omitempty"` // Default: "slsa-v1.0"
	Output        *OutputDescriptor   `json:"output,omitempty" yaml:"output,omitempty"`
	IncludeGit    bool                `json:"includeGit,omitempty" yaml:"includeGit,omitempty"`
	IncludeDocker bool                `json:"includeDockerfile,omitempty" yaml:"includeDockerfile,omitempty"`
	Required      bool                `json:"required,omitempty" yaml:"required,omitempty"`
	Builder       *BuilderDescriptor  `json:"builder,omitempty" yaml:"builder,omitempty"`
	Metadata      *MetadataDescriptor `json:"metadata,omitempty" yaml:"metadata,omitempty"`
}

ProvenanceDescriptor configures SLSA provenance

type ProvisionParams

type ProvisionParams struct {
	StacksDir    string   `json:"rootDir" yaml:"rootDir"`
	Profile      string   `json:"profile" yaml:"profile"`
	Stacks       []string `json:"stacks" yaml:"stacks"`
	SkipRefresh  bool     `json:"skipRefresh" yaml:"skipRefresh"`
	SkipPreview  bool     `json:"skipPreview" yaml:"skipPreview"`
	DetailedDiff bool     `json:"detailedDiff" yaml:"detailedDiff"` // Enable detailed diff output for granular change visibility
	Timeouts     Timeouts `json:",inline" yaml:",inline"`
}

type Provisioner

type Provisioner interface {
	ProvisionStack(ctx context.Context, cfg *ConfigFile, stack Stack, params ProvisionParams) error

	SetPublicKey(pubKey string)

	DeployStack(ctx context.Context, cfg *ConfigFile, stack Stack, params DeployParams) error

	DestroyChildStack(ctx context.Context, cfg *ConfigFile, stack Stack, params DestroyParams, preview bool) error

	PreviewStack(ctx context.Context, cfg *ConfigFile, parentStack Stack, params ProvisionParams) (*PreviewResult, error)

	PreviewChildStack(ctx context.Context, cfg *ConfigFile, parentStack Stack, params DeployParams) (*PreviewResult, error)

	OutputsStack(ctx context.Context, cfg *ConfigFile, stack Stack, params StackParams) (*OutputsResult, error)

	CancelStack(ctx context.Context, cfg *ConfigFile, stack Stack, params StackParams) error

	DestroyParentStack(ctx context.Context, cfg *ConfigFile, parentStack Stack, params DestroyParams, preview bool) error

	SetConfigReader(ProvisionerFieldConfigReaderFunc)
}

type ProvisionerConfigAware

type ProvisionerConfigAware interface {
	StateStorageType() string
	SecretsProviderType() string
}

ProvisionerConfigAware is implemented by the pulumi provisioner's config. Used by ValidatePluginRequirements to reach state-storage and secrets-provider type tokens without importing pkg/clouds/pulumi. Method names use the `Type` suffix to avoid colliding with same-named struct fields on the concrete config.

type ProvisionerDescriptor

type ProvisionerDescriptor struct {
	Type    string `json:"type" yaml:"type"`
	Config  `json:",inline" yaml:",inline"`
	Inherit `json:",inline" yaml:",inline"`
	// contains filtered or unexported fields
}

ProvisionerDescriptor describes the provisioner schema

func (*ProvisionerDescriptor) Copy

func (*ProvisionerDescriptor) GetProvisioner

func (s *ProvisionerDescriptor) GetProvisioner() Provisioner

func (*ProvisionerDescriptor) SetProvisioner

func (s *ProvisionerDescriptor) SetProvisioner(p Provisioner)

func (*ProvisionerDescriptor) ValuesOnly

ValuesOnly returns copy of descriptor without provisioner reference

type ProvisionerFieldConfigReadFunc

type ProvisionerFieldConfigReadFunc func(config *Config) (Config, error)

type ProvisionerFieldConfigReaderFunc

type ProvisionerFieldConfigReaderFunc func(cType string, c *Config) (Config, error)

type ProvisionerFieldConfigRegister

type ProvisionerFieldConfigRegister map[string]ProvisionerFieldConfigReadFunc

func GetRegisteredProvisionerFieldConfigs

func GetRegisteredProvisionerFieldConfigs() ProvisionerFieldConfigRegister

GetRegisteredProvisionerFieldConfigs returns all registered provisioner field configurations Used by schema generator to automatically discover provisioner resource types

type ProvisionerInitFunc

type ProvisionerInitFunc func(config Config, opts ...ProvisionerOption) (Provisioner, error)

type ProvisionerOption

type ProvisionerOption func(p Provisioner) error

type ProvisionerRegisterMap

type ProvisionerRegisterMap map[string]ProvisionerInitFunc

type ReadOpts

type ReadOpts struct {
	IgnoreServerMissing  bool
	IgnoreClientMissing  bool
	IgnoreSecretsMissing bool
	RequireClientConfigs []string
	RequireServerConfigs []string
	RequireSecretConfigs []string

	// PluginTypesNotNeeded lets a read try the cheap server-descriptor parse
	// that does NOT pre-spawn every declared plugin to discover its types.
	//
	// Only for callers that read a stack and then neither provision, deploy,
	// nor convert a stack config: the cheap parse does not record plugin specs
	// for the ConvertStackConfig dialler, so a conversion afterwards would fail
	// with "no plugin spec recorded". `sc stack secret-get` is the model case —
	// it reads one value out of secrets.yaml and exits.
	//
	// It is a HINT, not a promise. The read falls back to the full
	// plugin-aware parse whenever the cheap one fails, so a server.yaml whose
	// types only a plugin's Schema can describe still works; it just costs
	// what it costs today. Nothing becomes unreadable by setting this.
	//
	// Why it matters (measured 2026-11-09): with the per-version Schema cache
	// cold, `sc stack secret-get` spawned sc-plugin-cloudflare and took
	// 0.59-1.32 s against 0.06-0.09 s warm — and in CI the cache AND the
	// binary are both absent, so the same command downloads a 112 MiB plugin
	// release (sc-plugin-cloudflare-linux-amd64 is 117,547,170 bytes) to read
	// a string out of a YAML file. forge's own provision.yaml does this three
	// times in a row.
	PluginTypesNotNeeded bool
}

type RefreshResult

type RefreshResult struct {
	Operations map[string]int `json:"operations" yaml:"operations"`
}

func (*RefreshResult) String

func (r *RefreshResult) String() string

type RegistrarConfig

type RegistrarConfig interface {
	ProviderType() string
	DnsRecords() []DnsRecord
}

type RegistrarDescriptor

type RegistrarDescriptor struct {
	Type string `json:"type" yaml:"type"`

	// Default marks this registrar as the one that handles any domain no other
	// registrar claims. At most one registrar in a stack may set it.
	//
	// It exists because a registrar's declared zone is not the set of zones it can
	// serve. A Cloudflare registrar authenticates against a whole account and looks
	// up whichever zone the deploying stack asks for via `baseDnsZone`, so its
	// `zoneName:` is only a default — the fleet's registrar declares
	// `simple-container.com` while every service it publishes sits under
	// `simple-forge.com`. With a single registrar that never mattered, because the
	// single registrar handled everything. Adding a second one makes routing by zone
	// suddenly load-bearing, and without this marker the first two-registrar deploy
	// fails on every domain the narrow declaration misses.
	//
	// Not implicit on purpose: falling back to "whichever registrar sorts first"
	// would silently publish a domain through a provider chosen by alphabet.
	Default bool `json:"default,omitempty" yaml:"default,omitempty"`

	Config  `json:",inline" yaml:",inline"`
	Inherit `json:",inline" yaml:",inline"`
}

func (*RegistrarDescriptor) Copy

func (RegistrarDescriptor) IsConfigured

func (r RegistrarDescriptor) IsConfigured() bool

IsConfigured reports whether the descriptor declares anything at all. A server.yaml with no registrar block yields the zero value, which is legal and means "this stack manages no DNS".

type RegistrarZonesAware

type RegistrarZonesAware interface {
	Zones() []string
}

RegistrarZonesAware is implemented by a RegistrarConfig that knows which DNS zones it is authoritative for, so a domain can be routed to the right registrar without having to construct (and therefore authenticate) any of them first. Optional: a registrar config that does not implement it can still be the only registrar in a stack.

type RemoteImage

type RemoteImage struct {
	Name string `json:"name" yaml:"name"`
	Tag  string `json:"tag" yaml:"tag"`
}

type ReplaceRule

type ReplaceRule string

ReplaceRule names which exemption a type qualifies under, so a diagnostic can say WHY a replace was let through. The guard itself only needs the boolean.

const (
	ReplaceRuleNone ReplaceRule = ""
	// ReplaceRuleRevision: the old revision survives the replace.
	ReplaceRuleRevision ReplaceRule = "revision-based"
	// ReplaceRuleConfigRegenerated: the object is briefly absent, and
	// its whole content comes from config on every apply.
	ReplaceRuleConfigRegenerated ReplaceRule = "regenerated-from-config"
	// ReplaceRuleEngineOnly: the resource exists only in the engine's
	// state and the replace makes no remote call.
	ReplaceRuleEngineOnly ReplaceRule = "engine-only"
)

func SafeToReplaceRule

func SafeToReplaceRule(resourceType string) ReplaceRule

SafeToReplaceRule reports the rule under which this type is exempt, or ReplaceRuleNone. Checked in rule order: where a type somehow satisfies more than one, the narrower claim is the true one, so the diagnostic never overstates what is known about the replace.

type ReportingDescriptor

type ReportingDescriptor struct {
	DefectDojo *DefectDojoDescriptor `json:"defectdojo,omitempty" yaml:"defectdojo,omitempty"`
	PRComment  *PRCommentDescriptor  `json:"prComment,omitempty" yaml:"prComment,omitempty"`
}

ReportingDescriptor configures external reporting and PR comment generation.

type ResourceAware

type ResourceAware interface {
	Uses() []string
}

type ResourceDescriptor

type ResourceDescriptor struct {
	Type    string `json:"type" yaml:"type"`
	Name    string `json:"name" yaml:"name"`
	Config  `json:",inline" yaml:",inline"`
	Inherit `json:",inline" yaml:",inline"`
}

func (*ResourceDescriptor) Copy

type ResourceInput

type ResourceInput struct {
	Descriptor  *ResourceDescriptor `json:"descriptor" yaml:"descriptor"`
	StackParams *StackParams        `json:"deployParams" yaml:"deployParams"`

	// ComponentRaw carries the operator-declared `.Raw` map of a Component
	// resource when SC core's sidecar wrapper dispatches this input into a
	// `deployTo:` template (slice 1a.1 of sc-components-platform; design doc
	// §#19 path (b)). The dispatched template's ProvisionFunc checks for a
	// non-nil ComponentRaw and overlays the component's fields (image, env,
	// ingress, signingKey, …) onto its typed input struct before building
	// the cloud resource. nil for non-component dispatches — every existing
	// ProvisionFunc on main sees this unset and keeps working. See
	// forge/docs/design/2026-11-10/sc-components-platform/README.md §#19 for
	// the shape + the memory
	// `interface_assertion_against_plugin_owned_value_fails_in_prod` for why
	// SC core cannot type-overlay plugin-owned fields itself.
	ComponentRaw map[string]any `json:"component_raw,omitempty" yaml:"component_raw,omitempty"`
}

func (*ResourceInput) ToResName

func (r *ResourceInput) ToResName(resName string) string

ToResName adds environment suffix if environment is specified in the resource input

type ResourceOutput

type ResourceOutput struct {
	Ref any `json:"ref" yaml:"ref"`
}

type ResourceRef

type ResourceRef struct {
	// ResourceName is the sibling resource, named exactly as the `resources:`
	// block of server.yaml names it.
	ResourceName string
	// Key is which of that resource's outputs to read (e.g. `kubeconfig`). The
	// set of valid keys belongs to the resource that publishes them, not here.
	Key string
}

ResourceRef is a reference from one parent-stack resource's config field to an output of a SIBLING resource — a resource of the same server.yaml, the same stack and the same environment.

Why this exists. A `k3s-cluster` produces the cluster's kubeconfig, and a `kubernetes-caddy` needs a kubeconfig to deploy the edge into that cluster, but the field took a literal string only. So the single most obvious server.yaml anyone would write — a cluster and its front door, side by side — could not be provisioned in one pass. The documented workaround was to provision twice and carry the value across by hand:

  1. provision with the Caddy resource absent, read the kubeconfig from the stack outputs,
  2. paste it into `secrets.yaml` and provision again with `kubeconfig: ${secret:K3S_KUBECONFIG}`.

That works, and it is what all three k3s smokes of the 2026-11-08 fleet stand did. As a documented path it is poor in three separate ways: it makes a one-command provision a two-command one, it puts a cluster-admin credential in the operator's hands and in `secrets.yaml` purely as plumbing, and the pasted copy can go stale against the cluster with nothing to notice — a control-plane rebuild or a `tlsSans` change reissues the certificate, and the next deploy fails with an x509 error pointing at the Caddy resource rather than at the stale string. An output only a human can carry between two resources is a missing edge in the dependency graph, not a configuration style.

See forge/docs/roadmap/items/sc-k3s-caddy-needs-literal-kubeconfig.md.

func ParseResourceRef

func ParseResourceRef(value string) (ResourceRef, bool, error)

ParseResourceRef reads the `${resource:<name>.<key>}` form.

Whole-string match, not a substring: a field is either a reference or a literal value. Half a kubeconfig with a reference spliced into it is not a thing anyone means, and treating it as one would turn a typo into a provider built from a corrupt credential.

The boolean is "this is a reference" and the error is "it is a reference and it is malformed" — two different answers, because a literal value that merely starts with a brace must pass through untouched while `${resource:no-dot}` has to be a refusal rather than a string that silently reaches a provider.

func (ResourceRef) String

func (r ResourceRef) String() string

String renders the reference back to the form an operator wrote, so an error message can quote what is in their server.yaml rather than a struct dump.

type ResponseTimeConfig

type ResponseTimeConfig struct {
	CommonAlertConfig `json:",inline" yaml:",inline"`
}

type SBOMDescriptor

type SBOMDescriptor struct {
	Enabled   bool              `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	Format    string            `json:"format,omitempty" yaml:"format,omitempty"`       // Default: "cyclonedx-json"
	Generator string            `json:"generator,omitempty" yaml:"generator,omitempty"` // Default: "syft"
	Output    *OutputDescriptor `json:"output,omitempty" yaml:"output,omitempty"`
	Cache     *CacheDescriptor  `json:"cache,omitempty" yaml:"cache,omitempty"`
	Attach    *AttachDescriptor `json:"attach,omitempty" yaml:"attach,omitempty"`
	Required  bool              `json:"required,omitempty" yaml:"required,omitempty"`
}

SBOMDescriptor configures SBOM generation

type ScanDescriptor

type ScanDescriptor struct {
	Enabled bool                 `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	Tools   []ScanToolDescriptor `json:"tools,omitempty" yaml:"tools,omitempty"`
	FailOn  string               `json:"failOn,omitempty" yaml:"failOn,omitempty"` // "critical", "high", "medium", "low"
	WarnOn  string               `json:"warnOn,omitempty" yaml:"warnOn,omitempty"` // "critical", "high", "medium", "low"
	// SoftFail converts policy violations (failOn threshold exceeded) from hard errors to
	// warnings. The scan still runs and results are reported/uploaded, but a policy
	// violation never blocks the deployment (exit 0 instead of exit 1).
	SoftFail bool              `json:"softFail,omitempty" yaml:"softFail,omitempty"`
	Output   *OutputDescriptor `json:"output,omitempty" yaml:"output,omitempty"`
	Cache    *CacheDescriptor  `json:"cache,omitempty" yaml:"cache,omitempty"`
	Required bool              `json:"required,omitempty" yaml:"required,omitempty"`
}

ScanDescriptor configures vulnerability scanning

type ScanToolDescriptor

type ScanToolDescriptor struct {
	Name     string `json:"name,omitempty" yaml:"name,omitempty"` // "grype", "trivy"
	Enabled  *bool  `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	Required bool   `json:"required,omitempty" yaml:"required,omitempty"`
	FailOn   string `json:"failOn,omitempty" yaml:"failOn,omitempty"`
	WarnOn   string `json:"warnOn,omitempty" yaml:"warnOn,omitempty"`
}

ScanToolDescriptor configures a specific scanning tool

type SecretsConfigDescriptor

type SecretsConfigDescriptor struct {
	Type    string `json:"type" yaml:"type"`
	Config  `json:",inline" yaml:",inline"`
	Inherit `json:",inline" yaml:",inline"`
}

func (*SecretsConfigDescriptor) Copy

type SecretsDescriptor

type SecretsDescriptor struct {
	SchemaVersion string                    `json:"schemaVersion" yaml:"schemaVersion"`
	Auth          map[string]AuthDescriptor `json:"auth" yaml:"auth"`
	Values        map[string]string         `json:"values" yaml:"values"`
}

SecretsDescriptor describes the secrets schema

func DetectAuthType

func DetectAuthType(descriptor *SecretsDescriptor) (*SecretsDescriptor, error)

func ReadSecretsConfigs

func ReadSecretsConfigs(descriptor *SecretsDescriptor) (*SecretsDescriptor, error)

func ReadSecretsDescriptor

func ReadSecretsDescriptor(path string) (*SecretsDescriptor, error)

func (*SecretsDescriptor) Copy

type SecretsProviderConfig

type SecretsProviderConfig interface {
	AuthConfig
	IsProvisionEnabled() bool
	KeyUrl() string
}

type SecurityDescriptor

type SecurityDescriptor struct {
	Enabled    bool                  `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	Signing    *SigningDescriptor    `json:"signing,omitempty" yaml:"signing,omitempty"`
	SBOM       *SBOMDescriptor       `json:"sbom,omitempty" yaml:"sbom,omitempty"`
	Provenance *ProvenanceDescriptor `json:"provenance,omitempty" yaml:"provenance,omitempty"`
	Scan       *ScanDescriptor       `json:"scan,omitempty" yaml:"scan,omitempty"`
	Reporting  *ReportingDescriptor  `json:"reporting,omitempty" yaml:"reporting,omitempty"`
}

SecurityDescriptor defines security configuration for container images This is the API-level representation that maps to pkg/security types

func DefaultSecurityDescriptor

func DefaultSecurityDescriptor() *SecurityDescriptor

DefaultSecurityDescriptor returns a default security descriptor

type ServerDescriptor

type ServerDescriptor struct {
	SchemaVersion string                        `json:"schemaVersion" yaml:"schemaVersion"`
	Provisioner   ProvisionerDescriptor         `json:"provisioner" yaml:"provisioner"`
	Secrets       SecretsConfigDescriptor       `json:"secrets" yaml:"secrets"`
	CiCd          CiCdDescriptor                `json:"cicd" yaml:"cicd"`
	Templates     map[string]StackDescriptor    `json:"templates" yaml:"templates"`
	Resources     PerStackResourcesDescriptor   `json:"resources" yaml:"resources"`
	Variables     map[string]VariableDescriptor `json:"variables" yaml:"variables"`

	// Plugins advertises out-of-tree cloud plugins SC core should spawn and
	// route resource dispatch to. Phase 0 Step 4 of sc-plugin-architecture;
	// details in forge/docs/design/2026-10-24/sc-plugin-architecture/03-architecture.md.
	Plugins map[string]PluginSpec `json:"plugins,omitempty" yaml:"plugins,omitempty"`
}

ServerDescriptor describes the server schema

func DetectCiCdType

func DetectCiCdType(descriptor *ServerDescriptor) (*ServerDescriptor, error)

func DetectProvisionerType

func DetectProvisionerType(descriptor *ServerDescriptor) (*ServerDescriptor, error)

func DetectResourcesType

func DetectResourcesType(descriptor *ServerDescriptor) (*ServerDescriptor, error)

func DetectSecretsType

func DetectSecretsType(descriptor *ServerDescriptor) (*ServerDescriptor, error)

func DetectTemplatesType

func DetectTemplatesType(descriptor *ServerDescriptor) (*ServerDescriptor, error)

func ReadServerConfigs

func ReadServerConfigs(descriptor *ServerDescriptor) (*ServerDescriptor, error)

func ReadServerDescriptor

func ReadServerDescriptor(path string) (*ServerDescriptor, error)

func (*ServerDescriptor) Copy

func (*ServerDescriptor) IsStrictSchemaVersion

func (sd *ServerDescriptor) IsStrictSchemaVersion() bool

IsStrictSchemaVersion reports whether the descriptor opts into strict mode (schemaVersion 1.1 or newer). Call sites gate plugin-aware behaviour on this — in strict mode we refuse to auto-inject or guess; in lenient mode (1.0 / empty) we preserve the pre-A3 fallback UX.

func (*ServerDescriptor) ValidateSchemaVersion

func (sd *ServerDescriptor) ValidateSchemaVersion() error

ValidateSchemaVersion rejects a server.yaml carrying an unknown schemaVersion string. Empty is accepted (implicit 1.0). Call this early, before any plugin-aware parse step runs.

func (*ServerDescriptor) ValuesOnly

func (sd *ServerDescriptor) ValuesOnly() *ServerDescriptor

ValuesOnly returns copy of descriptor without additional state (e.g. provisioner reference etc.)

type ServerErrorsConfig

type ServerErrorsConfig struct {
	CommonAlertConfig `json:",inline" yaml:",inline"`
}

ALB-specific alert configurations

type SigningDescriptor

type SigningDescriptor struct {
	Enabled    bool   `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	Provider   string `json:"provider,omitempty" yaml:"provider,omitempty"` // Default: "sigstore"
	Keyless    bool   `json:"keyless,omitempty" yaml:"keyless,omitempty"`   // Default: true
	PrivateKey string `json:"privateKey,omitempty" yaml:"privateKey,omitempty"`
	PublicKey  string `json:"publicKey,omitempty" yaml:"publicKey,omitempty"`
	// Password is the cosign private key passphrase.
	// json:"-" prevents accidental serialization in debug logs and config dumps.
	// yaml tag is preserved because the field is loaded from stack YAML configs.
	Password string            `json:"-" yaml:"password,omitempty"`
	Required bool              `json:"required,omitempty" yaml:"required,omitempty"`
	Verify   *VerifyDescriptor `json:"verify,omitempty" yaml:"verify,omitempty"`
}

SigningDescriptor configures image signing

type SimpleContainerLBConfig

type SimpleContainerLBConfig struct {
	// Https is the DEPRECATED spelling of OriginTls. Still honoured, and means
	// exactly the same thing — `originTls` is the name that says what it does.
	Https bool `json:"https" yaml:"https"`

	// OriginTls is whether the edge serving this stack's site terminates TLS for
	// it: whether the generated Caddy site address is `https://<domain>` rather
	// than `http://<domain>`. The scheme is not decoration — `https://` is what
	// arms Caddy's automatic HTTPS, and therefore ACME, for this site.
	//
	// Unset means "inherit the edge's default" (the template's `originTls`) and,
	// failing that, FALSE: something in front — Cloudflare's proxy, a cloud load
	// balancer — terminates TLS and the edge serves plain HTTP. That is the
	// fleet's normal arrangement, which is why this defaults off while the vm
	// resource's `ingress.originTls` defaults on: there, the machine's Caddy IS
	// the front door.
	//
	// NOT the same decision as the template's `clientTls` (formerly `useSSL`),
	// which only governs HSTS and which side owns the HTTP→HTTPS redirect.
	//
	// Has no effect on the vm path, where origin TLS is a property of the
	// machine's one Caddy and belongs to the vm resource (`ingress.originTls`)
	// rather than to each site.
	OriginTls *bool `json:"originTls,omitempty" yaml:"originTls,omitempty"`
	// ExtraHelpers renders one directive per line INSIDE the per-stack
	// `reverse_proxy { ... }` block (alongside `header_down`, `import
	// handle_server_error`, etc.). Use this for reverse-proxy-subdirective
	// configuration: `header_down`, `lb_retries`, `transport`, `header_up`.
	ExtraHelpers []string `json:"extraHelpers" yaml:"extraHelpers"`
	// SiteExtraHelpers renders one directive per line at the SITE LEVEL,
	// AFTER the `reverse_proxy { ... }` block closes (alongside `import
	// gzip`, `import hsts`, etc.). Use this for site-level HTTP handlers
	// that aren't valid as reverse_proxy subdirectives — `rate_limit`,
	// `redir`, top-level matchers, `route` blocks, `respond` on specific
	// paths. The two fields are distinct because Caddy's grammar gates
	// what's accepted at each scope; mis-placing a directive yields a
	// Caddyfile parse error at reload time.
	SiteExtraHelpers []string `json:"siteExtraHelpers" yaml:"siteExtraHelpers"`
	// RequestBufferSize controls the `request_buffers` directive on the
	// generated reverse_proxy block. Bodies up to this size are buffered so
	// the upstream receives Content-Length instead of Transfer-Encoding:
	// chunked — WSGI frameworks (Django #28668) read an empty body on chunked
	// requests. The value is parsed as a byte size (humanize: "512KB",
	// "4MiB"), validated (max 16MiB — the buffer is held in edge-proxy memory
	// per in-flight request), and rendered as a plain byte count, so no
	// user-controlled text reaches the shared Caddyfile. "0" omits the
	// directive entirely (also the escape hatch for edges running Caddy
	// < 2.6.0, which predates request_buffers). Unset/empty = default 1MiB.
	// Chunked bodies LARGER than the buffer still reach the upstream chunked
	// and remain subject to Django #28668 — raise the size for endpoints
	// receiving large chunked uploads.
	RequestBufferSize string `json:"requestBufferSize,omitempty" yaml:"requestBufferSize,omitempty"`
}

func (*SimpleContainerLBConfig) OriginTlsEnabled

func (c *SimpleContainerLBConfig) OriginTlsEnabled(edgeDefault *bool) bool

OriginTlsEnabled reports whether the edge terminates TLS for this stack's site, and therefore whether the site address is rendered `https://` (automatic HTTPS and ACME armed) or `http://`.

Precedence: this stack's `originTls`, then its deprecated `https`, then the edge-wide default from the template, then false. A nil receiver answers the same as an empty block, because a client.yaml with no `lbConfig` at all is the majority case and must not behave differently from one that declares the block and says nothing.

func (*SimpleContainerLBConfig) ValidateTls

func (c *SimpleContainerLBConfig) ValidateTls() error

ValidateTls refuses the one combination of the two spellings that cannot be honoured both ways. Everything else resolves by the documented precedence.

type SlackCfg

type SlackCfg struct {
	WebhookUrl string `json:"webhookUrl" yaml:"webhookUrl"`
}

type Stack

type Stack struct {
	Name    string            `json:"name" yaml:"name"`
	Secrets SecretsDescriptor `json:"secrets" yaml:"secrets"`
	Server  ServerDescriptor  `json:"server" yaml:"server"`
	Client  ClientDescriptor  `json:"client" yaml:"client"`
}

func (*Stack) ChildStack

func (s *Stack) ChildStack(name string) Stack

func (*Stack) ValuesOnly

func (s *Stack) ValuesOnly() Stack

type StackClientDescriptor

type StackClientDescriptor struct {
	Type        string `json:"type" yaml:"type"`
	ParentStack string `json:"parent" yaml:"parent"`
	ParentEnv   string `json:"parentEnv" yaml:"parentEnv"`
	Template    string `json:"template" yaml:"template"`
	Config      Config `json:",inline" yaml:",inline"`
}

func ConvertClientConfig

func ConvertClientConfig(clientDesc StackClientDescriptor) (*StackClientDescriptor, error)

func (*StackClientDescriptor) Copy

type StackConfigCompose

type StackConfigCompose struct {
	DockerComposeFile string                          `json:"dockerComposeFile" yaml:"dockerComposeFile"`
	Domain            string                          `json:"domain" yaml:"domain"`
	Prefix            string                          `json:"prefix" yaml:"prefix"`                   // prefix for service under LB (e.g. /<service>) default: empty
	ProxyKeepPrefix   bool                            `json:"proxyKeepPrefix" yaml:"proxyKeepPrefix"` // if prefix is specified, whether we need to keep it when proxying to service
	DomainProxied     *bool                           `json:"domainProxied" yaml:"domainProxied"`
	BaseDnsZone       string                          `json:"baseDnsZone" yaml:"baseDnsZone"` // only necessary if differs from parent stack
	Uses              []string                        `json:"uses" yaml:"uses"`
	Runs              []string                        `json:"runs" yaml:"runs"`
	Env               map[string]string               `json:"env" yaml:"env"`
	Secrets           map[string]string               `json:"secrets" yaml:"secrets"`
	Version           string                          `json:"version" yaml:"version"` // only when need to forcefully redeploy (e.g. aws secrets)
	Size              *StackConfigComposeSize         `json:"size,omitempty" yaml:"size,omitempty"`
	Scale             *StackConfigComposeScale        `json:"scale,omitempty" yaml:"scale,omitempty"`
	Dependencies      []StackConfigDependencyResource `json:"dependencies,omitempty" yaml:"dependencies,omitempty"` // when service wants to use resources from another service
	Alerts            *AlertsConfig                   `json:"alerts,omitempty" yaml:"alerts,omitempty"`
	TextVolumes       *[]TextVolume                   `json:"textVolumes" yaml:"textVolumes"`               // extra text volumes to mount to containers (e.g. for k8s deployments)
	Headers           *Headers                        `json:"headers" yaml:"headers"`                       // extra headers to add when serving requests
	LBConfig          *SimpleContainerLBConfig        `json:"lbConfig" yaml:"lbConfig"`                     // load balancer configuration (so far only applicable for k8s deployments)
	CloudExtras       *any                            `json:"cloudExtras" yaml:"cloudExtras"`               // when need to specify additional extra config for the specific cloud (e.g. AWS extra roles)
	StaticEgressIP    *bool                           `json:"staticEgressIP" yaml:"staticEgressIP"`         // when need to provision NAT with fixed egress IP address (e.g. AWS Lambda with static IP)
	ImagePullPolicy   *string                         `json:"imagePullPolicy" yaml:"imagePullPolicy"`       // applicable only for certain compute types, e.g. Kubernetes
	ClusterIPAddress  *string                         `json:"clusterIPAddress" yaml:"clusterIPAddress"`     // applicable only for certain compute types, e.g. Kubernetes
	Security          *SecurityDescriptor             `json:"security,omitempty" yaml:"security,omitempty"` // container image security configuration
}

func (*StackConfigCompose) Copy

func (s *StackConfigCompose) Copy() any

type StackConfigComposeResources

type StackConfigComposeResources struct {
	Cpu       string `yaml:"cpu,omitempty" json:"cpu,omitempty"`
	Memory    string `yaml:"memory,omitempty" json:"memory,omitempty"`
	Ephemeral string `yaml:"ephemeral,omitempty" json:"ephemeral,omitempty"`
}

type StackConfigComposeScale

type StackConfigComposeScale struct {
	Min int `yaml:"min" json:"min"`
	Max int `yaml:"max" json:"max"`

	Policy *StackConfigComposeScalePolicy `json:"policy" yaml:"policy"`
}

type StackConfigComposeScaleCpu

type StackConfigComposeScaleCpu struct {
	Max int `yaml:"max" json:"max"`
}

type StackConfigComposeScaleMemory

type StackConfigComposeScaleMemory struct {
	Max int `yaml:"max" json:"max"`
}

type StackConfigComposeScalePolicy

type StackConfigComposeScalePolicy struct {
	Cpu    *StackConfigComposeScaleCpu    `yaml:"cpu" json:"cpu"`
	Memory *StackConfigComposeScaleMemory `yaml:"memory" json:"memory"`
}

type StackConfigComposeSize

type StackConfigComposeSize struct {
	Name      string                       `yaml:"name" json:"name"`
	Cpu       string                       `yaml:"cpu" json:"cpu"`
	Memory    string                       `yaml:"memory" json:"memory"`
	Ephemeral string                       `yaml:"ephemeral" json:"ephemeral"`
	Requests  *StackConfigComposeResources `yaml:"requests,omitempty" json:"requests,omitempty"`
	Limits    *StackConfigComposeResources `yaml:"limits,omitempty" json:"limits,omitempty"`
}

type StackConfigDependencyResource

type StackConfigDependencyResource struct {
	Name     string  `json:"name" yaml:"name"`
	Owner    string  `json:"owner" yaml:"owner"`
	Resource string  `json:"resource" yaml:"resource"`
	Env      *string `json:"env" yaml:"env"`
}

StackConfigDependencyResource when stack depends on resource context of another stack (client configuration)

type StackConfigSingleImage

type StackConfigSingleImage struct {
	Image  *ContainerImage `json:"image" yaml:"image"`
	Domain string          `json:"domain" yaml:"domain"`
	// DomainProxied mirrors StackConfigCompose.DomainProxied, which is where every
	// target actually reads it from (vm-compose, gke-autopilot, kubernetes). Without
	// it here the key parses and is then dropped on the floor by the single-image →
	// compose conversion: no error, no warning, and an UNPROXIED record pointing at a
	// fleet whose origin is deliberately plain HTTP. Live-caught 2026-11-08 on the
	// 3-VPS compose smoke, where `domainProxied: true` produced three `proxied=false`
	// A records and a name reachable only over cleartext.
	DomainProxied       *bool                           `json:"domainProxied" yaml:"domainProxied"`
	BaseDnsZone         string                          `json:"baseDnsZone" yaml:"baseDnsZone"` // only necessary if differs from parent stack
	Env                 map[string]string               `json:"env" yaml:"env"`
	Secrets             map[string]string               `json:"secrets" yaml:"secrets"`
	Min                 int                             `yaml:"min" json:"min"`
	Max                 int                             `yaml:"max" json:"max"`
	Version             string                          `json:"version" yaml:"version"` // only when need to forcefully redeploy (e.g. aws secrets)
	Timeout             *int                            `json:"timeout" yaml:"timeout"`
	BasePath            string                          `json:"basePath" yaml:"basePath"`                       // base path where API will listen on (e.g. for aws apigateway -> lambda integration)
	MaxMemory           *int                            `json:"maxMemory" yaml:"maxMemory"`                     // max memory to use for container
	MaxEphemeralStorage *int                            `json:"maxEphemeralStorage" yaml:"maxEphemeralStorage"` // max ephemeral storage in MB
	Uses                []string                        `json:"uses" yaml:"uses"`
	StaticEgressIP      *bool                           `json:"staticEgressIP" yaml:"staticEgressIP"`                 // when need to provision NAT with fixed egress IP address (e.g. AWS Lambda with static IP)
	CloudExtras         *any                            `json:"cloudExtras" yaml:"cloudExtras"`                       // when need to specify additional extra config for the specific cloud (e.g. AWS extra roles)
	Dependencies        []StackConfigDependencyResource `json:"dependencies,omitempty" yaml:"dependencies,omitempty"` // when service wants to use resources from another service
	Security            *SecurityDescriptor             `json:"security,omitempty" yaml:"security,omitempty"`         // container image security configuration
}

type StackConfigStatic

type StackConfigStatic struct {
	BundleDir  string           `json:"bundleDir" yaml:"bundleDir"`
	Site       StaticSiteConfig `json:",inline" yaml:",inline"`
	BucketName string           `json:"bucketName" yaml:"bucketName"` // if necessary to override bucket name, only applicable in some clouds (e.g. gcp)
	Location   string           `json:"location" yaml:"location"`
}

type StackDescriptor

type StackDescriptor struct {
	Type        string `json:"type" yaml:"type"`
	ParentStack string `json:"parentStack" yaml:"parentStack"`
	Config      `json:",inline" yaml:",inline"`
	Inherit     `json:",inline" yaml:",inline"`
}

func DetectTemplateType

func DetectTemplateType(tpl StackDescriptor) (*StackDescriptor, error)

func PrepareClientConfigForDeploy

func PrepareClientConfigForDeploy(ctx context.Context, stackDir, stackName string, tpl StackDescriptor, clientDesc StackClientDescriptor) (*StackDescriptor, error)

func PrepareCloudComposeForDeploy

func PrepareCloudComposeForDeploy(ctx context.Context, stackDir, stackName string, tpl StackDescriptor, clientConfig *StackConfigCompose, parentStack string) (*StackDescriptor, error)

func PrepareCloudSingleImageForDeploy

func PrepareCloudSingleImageForDeploy(ctx context.Context, stackDir, stackName string, tpl StackDescriptor, clientConfig *StackConfigSingleImage, parentStack string) (*StackDescriptor, error)

func PrepareStaticForDeploy

func PrepareStaticForDeploy(ctx context.Context, stackDir, stackName string, tpl StackDescriptor, clientConfig *StackConfigStatic, parentStack string) (*StackDescriptor, error)

func (*StackDescriptor) Copy

func (s *StackDescriptor) Copy() StackDescriptor

type StackParams

type StackParams struct {
	StacksDir    string   `json:"stacksDir" yaml:"stacksDir"`
	StackDir     string   `json:"stackDir" yaml:"stackDir"`
	Profile      string   `json:"profile" yaml:"profile"`
	StackName    string   `json:"stack" yaml:"stack"`
	Environment  string   `json:"environment" yaml:"environment"`
	ParentEnv    string   `json:"parentEnv" yaml:"parentEnv"`
	SkipRefresh  bool     `json:"skipRefresh" yaml:"skipRefresh"`
	SkipPreview  bool     `json:"skipPreview" yaml:"skipPreview"`
	DetailedDiff bool     `json:"detailedDiff" yaml:"detailedDiff"` // Enable detailed diff output for granular change visibility
	Version      string   `json:"version" yaml:"version"`
	Timeouts     Timeouts `json:",inline" yaml:",inline"`
	Parent       bool     `json:"parent" yaml:"parent"`
}

func (*StackParams) CopyForParentEnv

func (p *StackParams) CopyForParentEnv(env string) *StackParams

func (*StackParams) ToProvisionParams

func (p *StackParams) ToProvisionParams() ProvisionParams

type StacksMap

type StacksMap map[string]Stack

func (*StacksMap) ReconcileForDeploy

func (m *StacksMap) ReconcileForDeploy(params StackParams) (*StacksMap, error)

func (*StacksMap) ResolveInheritance

func (m *StacksMap) ResolveInheritance() *StacksMap

type StateStorageConfig

type StateStorageConfig interface {
	AuthConfig
	StorageUrl() string
	IsProvisionEnabled() bool
}

type StaticSiteConfig

type StaticSiteConfig struct {
	Domain             string      `json:"domain" yaml:"domain"`
	BaseDnsZone        string      `json:"baseDnsZone" yaml:"baseDnsZone"` // only necessary if differs from parent stack
	IndexDocument      string      `json:"indexDocument" yaml:"indexDocument"`
	ErrorDocument      string      `json:"errorDocument" yaml:"errorDocument"`
	ProvisionWwwDomain bool        `json:"provisionWwwDomain" yaml:"provisionWwwDomain"`
	CorsConfig         *CorsConfig `json:"corsConfig,omitempty" yaml:"corsConfig,omitempty"`
}

type TelegramCfg

type TelegramCfg struct {
	ChatID string `json:"chatID" yaml:"chatID"`
	Token  string `json:"token" yaml:"token"`
}

type TextVolume

type TextVolume struct {
	Content   string `json:"content" yaml:"content"`
	Name      string `json:"name" yaml:"name"`
	MountPath string `json:"mountPath" yaml:"mountPath"`
}

type Timeouts

type Timeouts struct {
	ExecutionTimeout string `json:"executionTimeout" yaml:"executionTimeout"`
	PreviewTimeout   string `json:"previewTimeout" yaml:"previewTimeout"`
	DeployTimeout    string `json:"deployTimeout" yaml:"deployTimeout"`
}

type ToCloudComposeConvertFunc

type ToCloudComposeConvertFunc func(tpl any, composeCfg compose.Config, stackCfg *StackConfigCompose) (any, error)

type ToCloudSingleImageConvertFunc

type ToCloudSingleImageConvertFunc func(tpl any, stackCfg *StackConfigSingleImage) (any, error)

type ToCloudStaticSiteConvertFunc

type ToCloudStaticSiteConvertFunc func(tpl any, rootDir, stackName string, stackCfg *StackConfigStatic) (any, error)

type UnhealthyHostsConfig

type UnhealthyHostsConfig struct {
	CommonAlertConfig `json:",inline" yaml:",inline"`
}

type UpdateResult

type UpdateResult struct {
	StackName  string         `json:"stackName" yaml:"stackName"`
	Summary    string         `json:"summary" yaml:"summary"`
	Operations map[string]int `json:"operations" yaml:"operations"`
}

func (*UpdateResult) String

func (r *UpdateResult) String() string

type VariableDescriptor

type VariableDescriptor struct {
	Type  string `json:"type" yaml:"type"`
	Value string `json:"value" yaml:"value"`
}

func (*VariableDescriptor) Copy

type VariableValues

type VariableValues map[string]any

type VerifyDescriptor

type VerifyDescriptor struct {
	Enabled        bool   `json:"enabled,omitempty" yaml:"enabled,omitempty"`
	OIDCIssuer     string `json:"oidcIssuer,omitempty" yaml:"oidcIssuer,omitempty"`
	IdentityRegexp string `json:"identityRegexp,omitempty" yaml:"identityRegexp,omitempty"`
}

VerifyDescriptor configures signature verification

type VmConfigAware

type VmConfigAware interface {
	DriverType() string
}

VmConfigAware is implemented by `pkg/clouds/vm.VmConfig`. Used by ValidatePluginRequirements to walk a `type: vm` resource's `provider:` field, which selects a driver that itself can be plugin-owned (`cloudru-evolution-vm`, future `mws-vm`, `selectel-vm`, …). Without this hook the walker only sees `res.Type == "vm"` and misses the plugin that owns the actual driver.

Method is named `DriverType` rather than `Driver` because VmConfig already has a `Driver string` field — same reason StateStorageType is not named StateStorage.

type WithCopy

type WithCopy[T any] interface {
	Copy() T
}

type WithDependencyProviders

type WithDependencyProviders interface {
	DependencyProviders() map[string]AuthDescriptor
}

WithDependencyProviders defines configurations where extra cloud providers are required

type WithDependsOnResources

type WithDependsOnResources interface {
	DependsOnResources() []StackConfigDependencyResource
}

type WithParentDependencies

type WithParentDependencies interface {
	DependsOnResources() []ParentResourceDependency
}

type WithProviderType

type WithProviderType interface {
	ProviderType() string
}

WithProviderType defines configuration with specific cloud provider type

Directories

Path Synopsis
git
Package inlinetag detects struct fields that are tagged `json:",inline"` while being NAMED rather than embedded — a shape that means two different things to the two codecs this repo's config travels through, and the single root cause behind seven production failures across the fleet on 2026-11-09.
Package inlinetag detects struct fields that are tagged `json:",inline"` while being NAMED rather than embedded — a shape that means two different things to the two codecs this repo's config travels through, and the single root cause behind seven production failures across the fleet on 2026-11-09.
scoped
Package scoped implements the additive per-scope secret store (secrets.<scope>.yaml): committed-encrypted files whose values are sealed to a per-scope recipient set, so a pull_request-triggered CI job can be given a key that opens only the "pr" scope rather than the whole-file store.
Package scoped implements the additive per-scope secret store (secrets.<scope>.yaml): committed-encrypted files whose values are sealed to a per-scope recipient set, so a pull_request-triggered CI job can be given a key that opens only the "pr" scope rather than the whole-file store.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL