Documentation
¶
Index ¶
- Constants
- Variables
- func GenerateSchema() ([]byte, error)
- func ParseResourceReference(value any) (resourceName, outputName string, ok bool)
- type App
- type AppType
- type Build
- type Command
- type CommandSpec
- type Contact
- type Definition
- func (d *Definition) ApplyDefaults() error
- func (d *Definition) ContainsGo() bool
- func (d *Definition) ContainsJS() bool
- func (d *Definition) FilterTerraformManaged() (*Definition, SkippedItems)
- func (d *Definition) GetAppsByType(appType AppType) []App
- func (d *Definition) GithubLabels() []string
- func (d *Definition) HasAppType(appType AppType) bool
- func (d *Definition) MergeAllEnvironments() Environment
- func (d *Definition) Validate(fs afero.Fs) []error
- type Domain
- type DomainType
- type EnvSource
- type EnvValue
- type EnvVar
- type EnvWalkEntry
- type Environment
- type EnvironmentWalker
- type EnvironmentWalkerE
- type GitHubRepo
- type Infra
- type MenuItem
- type Notifications
- type Project
- type Resource
- type ResourceBackupConfig
- type ResourceProvider
- type ResourceType
- type Shared
- type SkippedItems
- type Social
Constants ¶
const ( // JsonFileName defines the file name of the app manifest, // that should appear in the root of each webkit dir. JsonFileName = "app.json" )
Variables ¶
var Commands = []Command{ CommandFormat, CommandLint, CommandTest, CommandBuild, }
Commands defines all the Commands available that should be run in order.
Functions ¶
func GenerateSchema ¶ added in v0.2.0
GenerateSchema generates a JSON schema for the Definition type.
func ParseResourceReference ¶ added in v0.0.15
ParseResourceReference parses a resource reference string (e.g., "db.connection_url").
Resource references follow the format: "resource_name.output_name".
Types ¶
type App ¶
type App struct {
Name string `json:"name" validate:"required,lowercase,alphanumdash" description:"Unique identifier for the app (lowercase, hyphenated)"`
Title string `json:"title" validate:"required" description:"Human-readable app name for display purposes"`
Type AppType `json:"type" validate:"required,oneof=svelte-kit golang payload" description:"Application type (payload, svelte-kit, golang)"`
Description string `` /* 128-byte string literal not displayed */
Path string `json:"path" validate:"required" description:"Relative file path to the app's source code directory"`
Build Build `json:"build" description:"Build configuration for Docker containerisation"`
Infra Infra `json:"infra" validate:"required" description:"Infrastructure and deployment configuration"`
Env Environment `json:"env" description:"Environment variables specific to this app"`
UsesNPM *bool `json:"usesNPM" description:"Whether this app should be included in the pnpm workspace (auto-detected if not set)"`
TerraformManaged *bool `json:"terraformManaged,omitempty" description:"Whether this app's infrastructure is managed by Terraform (defaults to true)"`
Domains []Domain `json:"domains,omitzero" description:"Domain configurations for accessing this app"`
Commands map[Command]CommandSpec `` /* 161-byte string literal not displayed */
}
App represents a single application within the webkit project. Each app has its own build configuration, infrastructure requirements, environment variables, and deployment settings. Apps can be of different types (Payload CMS, SvelteKit, GoLang) and are deployed independently.
func (*App) IsTerraformManaged ¶ added in v0.0.8
IsTerraformManaged returns whether this app should be managed by Terraform. It defaults to true when the field is nil or explicitly set to true.
func (*App) Language ¶
Language determines what language ecosystem a given app is. Either "go" or "js".
func (*App) MergeEnvironments ¶
func (a *App) MergeEnvironments(shared Environment) Environment
MergeEnvironments merges the shared env with the apps, with the app specific variables taking precedence.
func (*App) OrderedCommands ¶
func (a *App) OrderedCommands() []CommandSpec
OrderedCommands returns the app's commands in canonical order with Name populated.
func (*App) PrimaryDomain ¶ added in v0.0.19
PrimaryDomain returns the primary domain for this app. It first looks for a domain with type "primary" in the Domains array. If no primary domain is found, it returns the first domain in the array. If the Domains array is empty, it returns an empty string.
func (*App) ShouldRelease ¶ added in v0.0.10
ShouldRelease returns whether this app should be built and released in CI/CD. It defaults to true when the field is nil or explicitly set to true.
func (*App) ShouldUseNPM ¶
ShouldUseNPM returns whether this app should be included in pnpm workspace. It checks the UsesNPM field first, and if not set, defaults based on Language().
type AppType ¶
type AppType string
AppType defines the type of application being run.
type Build ¶
type Build struct {
Dockerfile string `json:"dockerfile" description:"Path to the Dockerfile relative to the app directory"`
Port int `json:"port,omitempty" validate:"omitempty,min=1,max=65535" description:"Port number the app listens on inside the container"`
Release *bool `json:"release,omitempty" description:"Whether to build and release this app in CI/CD (defaults to true)"`
}
Build defines Docker build configuration for containerised applications. These settings control how the app is built and exposed in container environments.
type Command ¶
type Command string
Command defines the type of action that will be actioned.
type CommandSpec ¶
type CommandSpec struct {
Name string `json:"-"`
Cmd string `json:"command,omitempty" description:"The shell command to execute (e.g., 'pnpm build')"`
SkipCI bool `json:"skip_ci,omitempty" description:"Whether to skip running this command in CI/CD pipelines"`
Timeout string `json:"timeout,omitempty" description:"Maximum execution time for the command (e.g., '5m', '1h')"`
Disabled bool `json:"-"` // Set during unmarshal
}
CommandSpec defines an action for an app that can run in CI/CD or locally. Commands can be specified as a boolean (enable/disable), a string (command override), or an object (full configuration with timeout and CI settings).
func (*CommandSpec) JSONSchemaOneOf ¶
func (*CommandSpec) JSONSchemaOneOf() []interface{}
JSONSchemaOneOf returns the polymorphic schema options.
func (*CommandSpec) UnmarshalJSON ¶
func (c *CommandSpec) UnmarshalJSON(data []byte) error
UnmarshalJSON implements json.Unmarshaler to
type Definition ¶
type Definition struct {
Schema string `json:"$schema,omitempty" jsonschema:"-" description:"JSON Schema reference for IDE validation and autocomplete"`
WebkitVersion string `` /* 129-byte string literal not displayed */
Project Project `` /* 131-byte string literal not displayed */
Notifications Notifications `json:"notifications" description:"Alert and notification settings for the project"`
Resources []Resource `json:"resources" description:"Infrastructure resources such as databases and storage buckets"`
Apps []App `` /* 137-byte string literal not displayed */
}
Definition represents the complete webkit application configuration. It defines the structure of the app.json file used to configure all aspects of a webkit project including apps, resources, and infrastructure.
func (*Definition) ApplyDefaults ¶
func (d *Definition) ApplyDefaults() error
ApplyDefaults ensures all required defaults are set on the Definition. This should be called after unmarshaling and before validation.
func (*Definition) ContainsGo ¶
func (d *Definition) ContainsGo() bool
ContainsGo returns true if any of the apps are marked as Go.
func (*Definition) ContainsJS ¶
func (d *Definition) ContainsJS() bool
ContainsJS returns true if any of the apps are marked as JS.
func (*Definition) FilterTerraformManaged ¶ added in v0.0.8
func (d *Definition) FilterTerraformManaged() (*Definition, SkippedItems)
FilterTerraformManaged creates a filtered copy of the Definition containing only apps and resources that are managed by Terraform.
Returns the filtered definition and information about what was skipped.
func (*Definition) GetAppsByType ¶ added in v0.0.8
func (d *Definition) GetAppsByType(appType AppType) []App
GetAppsByType returns all apps of the specified type from the definition.
func (*Definition) GithubLabels ¶
func (d *Definition) GithubLabels() []string
GithubLabels returns the labels that will appear on the GitHub repository by looking at the application types.
func (*Definition) HasAppType ¶ added in v0.0.8
func (d *Definition) HasAppType(appType AppType) bool
HasAppType checks if the definition contains an app of the specified type.
func (*Definition) MergeAllEnvironments ¶
func (d *Definition) MergeAllEnvironments() Environment
MergeAllEnvironments merges shared env variables with all apps' environments. App-specific values take precedence over shared ones. If multiple apps define the same variable, the last app in the list wins.
type Domain ¶
type Domain struct {
Name string `json:"name" validate:"required" description:"Domain name without protocol (e.g., 'example.com' or 'api.example.com')"`
Type DomainType `json:"type" validate:"omitempty,oneof=primary alias unmanaged" description:"Domain type (primary, alias, unmanaged)"`
Zone string `json:"zone,omitempty" description:"DNS zone for the domain if different from default"`
Wildcard bool `json:"wildcard,omitempty" description:"Whether this is a wildcard domain (e.g., '*.example.com')"`
}
Domain represents a domain name configuration for accessing an app. Domains can be primary, aliases, or unmanaged depending on your DNS setup.
type DomainType ¶
type DomainType string
DomainType defines the type of domain that should be provisioned.
const ( DomainTypePrimary DomainType = "primary" DomainTypeAlias DomainType = "alias" DomainTypeUnmanaged DomainType = "unmanaged" )
DomainType constants.
func (DomainType) String ¶
func (d DomainType) String() string
String implements fmt.Stringer on the DomainType.
type EnvSource ¶
type EnvSource string
EnvSource defines the type of application being run.
const ( // EnvSourceValue is a static string value (default). // Example: "https://api.example.com" EnvSourceValue EnvSource = "value" // EnvSourceResource references a Terraform resource output. // Example: "db.connection_url" EnvSourceResource EnvSource = "resource" // EnvSourceSOPS is an encrypted secret stored in a SOPS file. // Example: "secrets/production.yaml:API_KEY" EnvSourceSOPS EnvSource = "sops" )
type EnvValue ¶
type EnvValue struct {
Source EnvSource `` /* 148-byte string literal not displayed */
// Value holds the actual value or reference depending on the source type:
// - "value": A static string (e.g., "https://api.example.com")
// - "resource": A Terraform resource reference (e.g., "db.connection_url")
// - "sops": The variable name/key to lookup in the SOPS file (e.g., "API_KEY")
Value any `json:"value,omitempty" description:"The value or reference for this variable (format depends on source type)"`
}
EnvValue represents a single environment variable configuration. It specifies both the source type and the value/reference for the variable.
type EnvVar ¶
EnvVar is a map of variable names to their value configurations. Each key is the environment variable name, and the value defines where the variable's value comes from (static value, resource output, or secret).
func CloneEnvVar ¶ added in v0.2.4
CloneEnvVar creates a shallow copy of an EnvVar map. This prevents mutation of the original map. Returns nil if the source is nil.
type EnvWalkEntry ¶
type EnvWalkEntry struct {
Environment env.Environment
Key string
Value any
Source EnvSource
Map EnvVar
}
EnvWalkEntry holds the details of a single env variable during iteration.
type Environment ¶
type Environment struct {
Default EnvVar `` /* 132-byte string literal not displayed */
Dev EnvVar `json:"dev,omitempty" inline:"true" description:"Environment variables specific to the development environment"`
Staging EnvVar `json:"staging,omitempty" inline:"true" description:"Environment variables specific to the staging environment"`
Production EnvVar `json:"production,omitempty" inline:"true" description:"Environment variables specific to the production environment"`
}
Environment contains environment-specific variable configurations. Variables can be defined per environment (dev, staging, production) or set once in 'default' to apply across all environments.
func (Environment) GetVarsForEnvironment ¶ added in v0.0.25
func (e Environment) GetVarsForEnvironment(target env.Environment) (EnvVar, error)
GetVarsForEnvironment returns the EnvVar map for the specified environment. Returns an error if the environment is unknown.
func (Environment) Walk ¶
func (e Environment) Walk(fn EnvironmentWalker)
Walk iterates over all environments and calls fn for each env variable.
func (Environment) WalkE ¶
func (e Environment) WalkE(fn EnvironmentWalkerE) error
WalkE iterates over all environments and calls fn for each env variable. If fn returns an error, iteration stops and the error is returned.
type EnvironmentWalker ¶
type EnvironmentWalker func(entry EnvWalkEntry)
EnvironmentWalker defines a function that processes one env entry.
type EnvironmentWalkerE ¶
type EnvironmentWalkerE func(entry EnvWalkEntry) error
EnvironmentWalkerE defines a function that processes one env entry and may return an error.
type GitHubRepo ¶
type GitHubRepo struct {
Owner string `json:"owner" validate:"required" description:"GitHub username or organisation that owns the repository"`
Name string `json:"name" validate:"required" description:"Repository name on GitHub"`
}
GitHubRepo defines the metadata for GitHub repositories. This information is used for CI/CD integration, secrets management, and linking documentation to the source repository.
type Infra ¶
type Infra struct {
Provider ResourceProvider `json:"provider" validate:"required" description:"Cloud infrastructure provider (digitalocean, backblaze)"`
Type string `json:"type" validate:"required" description:"Infrastructure type (vm, app, container, function)"`
Config map[string]any `json:"config" description:"Provider-specific infrastructure configuration options"`
}
Infra defines infrastructure and deployment configuration for an app. This includes the cloud provider, deployment type (VM, container, etc.), and provider-specific configuration options.
type Notifications ¶ added in v0.0.36
type Notifications struct {
WebhookURL string `` /* 126-byte string literal not displayed */
}
Notifications defines alert and notification settings for the project. Provider-agnostic configuration supporting Slack, Discord, and other webhook-based services.
type Project ¶
type Project struct {
Name string `` /* 126-byte string literal not displayed */
Title string `json:"title" validate:"required" description:"Human-readable project name displayed in documentation and UIs"`
Description string `json:"description" validate:"required,max=200" description:"Brief description of the project's purpose and functionality"`
Repo GitHubRepo `json:"repo" validate:"required" description:"GitHub repository information for the project"`
}
Project defines root metadata about the project such as business names and descriptions. This information is used throughout webkit for identification, documentation generation, and CI/CD configuration.
type Resource ¶
type Resource struct {
Name string `` /* 161-byte string literal not displayed */
Type ResourceType `` /* 139-byte string literal not displayed */
Provider ResourceProvider `` /* 170-byte string literal not displayed */
Config map[string]any `json:"config" description:"Provider-specific resource configuration (e.g., size, region, version)"`
Backup ResourceBackupConfig `json:"backup,omitempty" description:"Backup configuration for the resource"`
TerraformManaged *bool `json:"terraformManaged,omitempty" description:"Whether this resource is managed by Terraform (defaults to true)"`
}
Resource represents an infrastructure component that applications depend on, such as databases, storage buckets, or caches. Resources are provisioned via Terraform and their outputs are made available to apps through environment variables.
func (*Resource) GitHubSecretName ¶
func (r *Resource) GitHubSecretName(environment env.Environment, output string) string
GitHubSecretName returns the GitHub secret name for a resource output. Format: TF_{ENVIRONMENT}_{RESOURCE_NAME}_{OUTPUT_NAME} (uppercase)
Example:
resource.GitHubSecretName(env.Production, "connection_url") ↓ "TF_PROD_DB_CONNECTION_URL"
func (*Resource) IsTerraformManaged ¶ added in v0.0.8
IsTerraformManaged returns whether this resource should be managed by Terraform. It defaults to true when the field is nil or explicitly set to true.
type ResourceBackupConfig ¶
type ResourceBackupConfig struct {
Enabled bool `json:"enabled" description:"Whether to enable automated backups for this resource"`
}
ResourceBackupConfig defines backup behaviour for a resource. Backups are enabled by default for all resources that support them.
type ResourceProvider ¶
type ResourceProvider string
ResourceProvider defines a provider of cloud infra.
const ( ResourceProviderDigitalOcean ResourceProvider = "digitalocean" ResourceProviderBackBlaze ResourceProvider = "backblaze" ResourceProviderTurso ResourceProvider = "turso" )
ResourceProvider constants.
func (ResourceProvider) String ¶
func (r ResourceProvider) String() string
String implements fmt.Stringer on the ResourceProvider.
type ResourceType ¶
type ResourceType string
ResourceType defines the type of resource to be provisioned.
const ( ResourceTypePostgres ResourceType = "postgres" ResourceTypeS3 ResourceType = "s3" ResourceTypeSQLite ResourceType = "sqlite" )
ResourceType constants.
func (ResourceType) Outputs ¶
func (r ResourceType) Outputs() []string
Outputs returns the required outputs for a resource type for Terraform.
These should always be exported to GitHub secrets regardless of user config defined in the app definition.
func (ResourceType) String ¶
func (r ResourceType) String() string
String implements fmt.Stringer on the ResourceType.
type Shared ¶
type Shared struct {
}
Shared contains configuration that is shared across all applications in the project, such as common environment variables.
type SkippedItems ¶ added in v0.0.8
SkippedItems contains information about apps and resources that were filtered out due to not being Terraform managed.