repo

package
v0.1.1 Latest Latest
Warning

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

Go to latest
Published: Sep 16, 2026 License: Apache-2.0 Imports: 13 Imported by: 0

Documentation

Overview

Package repo is the data layer: the Store interface every handler talks to, the row structs behind it, and the slug rules shared by both. The SQLite implementation lives in repo/sqlite, nothing outside that subpackage writes SQL, so a second backend only has to satisfy Store.

Index

Constants

View Source
const (
	UIEditsBlock = "block" // refuse it: the file is the source of truth
	UIEditsStage = "stage" // hold it in the env's pending set for review
)

How the panel treats an edit to a field the config file owns.

View Source
const (
	OwnerTile  = "tile"
	OwnerStack = "stack"
	OwnerOrg   = "org"
	// OwnerEnv holds an environment's own value of a stack-declared secret,
	// the resolver reads it before the stack-wide row for ${{ stack.NAME }}.
	OwnerEnv = "env"
)

Owner kinds for Variable.

View Source
const (
	LinkDrop  = "drop"  // inbound: they fill a form, values land in Variables
	LinkShare = "share" // outbound: they see values we point at, once

	LinkOpen    = "open"
	LinkBurned  = "burned"
	LinkRevoked = "revoked"
	LinkLocked  = "locked" // too many wrong passphrases
)

Secret-link kinds and states.

View Source
const (
	BackupDump   = "dump"   // engine-native dump of a database tile
	BackupVolume = "volume" // tar of a named docker volume
	BackupStackr = "stackr" // the panel's own SQLite database (admin-only)

	ModePause = "pause" // freeze the container while the tar runs (default)
	ModeStop  = "stop"  // stop it instead, for services that dislike a freeze
	ModeLive  = "live"  // don't touch it, may produce a torn copy
)

Backup kinds and container modes.

View Source
const (
	MaxAnnotations    = 500
	MaxAnnotationBody = 2000
)

Annotation limits, same idea as the node-position ones: a hand-rolled request must not write junk or unbounded rows.

View Source
const (
	MaxGraphGroups    = 200
	MaxGroupMembers   = 200
	MaxGroupMemberKey = 200
)

Graph group limits, same idea as the annotation ones.

View Source
const (
	ScopeEnv   = "env"
	ScopeStack = "stack"
	ScopeOrg   = "org"
	// ScopeUser owns the all-orgs canvas at "/". Keyed by user, not by org:
	// that canvas is one person's arrangement of the orgs they belong to, and
	// two members of the same orgs should not fight over its layout.
	ScopeUser = "user"
)

Graph position scopes. Use with GraphOwner to build a NodePosition.OwnerID.

View Source
const (
	MaxNodePositions = 2000
	MaxNodeCoord     = 1e6
)

Canvas layout limits. A real canvas holds tens of cards; these exist so a hand-rolled request can't write junk or a million rows.

View Source
const HomeSlug = "stack"

HomeSlug is the slug (and type) of a stack's home environment: the hidden env holding its shared tiles. Created with the stack, never listed by ListEnvironmentsByStack, found through HomeEnvironment. Reserved: the stack file refuses an environment by this name.

View Source
const InterruptedMsg = "interrupted by a server restart"

InterruptedMsg is what SweepStaleRuns writes on a row the previous process was driving. Shared because the deploy engine matches on it to put a requeued deployment back, and a drift between the two means a requeued deploy silently declines to run.

View Source
const MaxLinkAttempts = 5

MaxLinkAttempts is how many wrong passphrases a link tolerates before it locks.

Variables

This section is empty.

Functions

func GraphOwner

func GraphOwner(scope, id string) string

GraphOwner builds the owner key for a graph's saved positions.

func ReservedSlug

func ReservedSlug(s string) bool

ReservedSlug reports whether a slug collides with a reference bucket. Those three names sit where a source slug goes in ${{ scope.<slug>.<output> }}, so a tile or shared instance called one of them would make ${{ stack.vars.NAME }} ambiguous. See internal/stackrd/config/varref.

func Slugify

func Slugify(name string) string

Slugify turns a display name into a URL/DNS-safe slug: lowercase, runs of anything non-alphanumeric collapse to a single '-', trimmed at the ends. UI renames touch only the display name; config-driven org/stack renames re-derive the slug from the file's declared name.

func StorageVolume

func StorageVolume(pathID string) string

StorageVolume is the docker volume backing one sub-path, one volume per path, shared by every consumer, same naming family as DockerVolume(). The prefix stays "stackr-" while every other docker object moved to "stkr-": docker cannot rename a volume, so a prefix change makes the next deploy ask for a name that does not exist, get a fresh empty volume, and leave the data detached. Volumes are id-named and already outside the slug scheme, so the shorter prefix bought nothing here.

func ValidGitURL

func ValidGitURL(u string) bool

ValidGitURL accepts https://<host>/owner/repo[.git] and git@<host>:owner/repo[.git] for hosts in gitHosts. Everything else is refused, which is the point: git happily clones file:// and bare local paths, so an unchecked git_url would let a build pull the server's own data directory. A leading dash is refused too, it would read as a git flag.

func ValidVolumeName

func ValidVolumeName(s string) bool

ValidVolumeName reports whether s is a docker volume name. Every writer of Tile.VolumeName checks it: empty is valid too and means the id-derived name.

func ValidateAnnotation

func ValidateAnnotation(a *Annotation) error

ValidateAnnotation checks one posted annotation.

func ValidateGraphGroup

func ValidateGraphGroup(g *GraphGroup) error

ValidateGraphGroup checks one posted group.

func ValidateNodePositions

func ValidateNodePositions(ownerID string, ps []NodePosition) error

ValidateNodePositions checks a posted layout. Handlers call it to answer 400 rather than 500; the store calls it too, so the rules hold for every writer.

Types

type APIKey

type APIKey struct {
	ID        string    `db:"id"`
	UserID    string    `db:"user_id"`
	Name      string    `db:"name"`
	TokenHash string    `db:"token_hash"`
	Scopes    string    `db:"scopes"` // JSON array of scope strings
	CreatedAt time.Time `db:"created_at"`
}

APIKey authenticates REST API calls. Scopes is a JSON array of capability strings ("resource:action"); a request is allowed only if the key carries the scope the route requires AND the key's user still has org access.

func (*APIKey) HasScope

func (k *APIKey) HasScope(scope string) bool

HasScope reports whether the key was granted a capability.

func (*APIKey) ScopeList

func (k *APIKey) ScopeList() []string

ScopeList decodes the key's JSON scope array ([] when empty/invalid).

type Annotation

type Annotation struct {
	ID        string    `db:"id" json:"id"`
	OwnerID   string    `db:"owner_id" json:"-"`
	Kind      string    `db:"kind" json:"kind"` // "text" | "box"
	Body      string    `db:"body" json:"body"`
	X         float64   `db:"x" json:"x"`
	Y         float64   `db:"y" json:"y"`
	W         float64   `db:"w" json:"w"`
	H         float64   `db:"h" json:"h"`
	Color     string    `db:"color" json:"color,omitempty"`
	CreatedAt time.Time `db:"created_at" json:"-"`
	UpdatedAt time.Time `db:"updated_at" json:"-"`
}

Annotation is a free-floating note on a canvas: a text label or a box drawn behind the cards. Shared per canvas, OwnerID uses the same scope-prefixed keys as NodePosition, so every viewer of a canvas sees the same board.

type AuditEvent

type AuditEvent struct {
	Actor     string    `db:"actor"`      // user email, "api:<key>" or "share-link:<id>"
	Action    string    `db:"action"`     // reveal | copy | edit | set | delete | share
	OwnerKind string    `db:"owner_kind"` // tile | env | stack | org
	OwnerID   string    `db:"owner_id"`
	Name      string    `db:"name"`
	CreatedAt time.Time `db:"created_at"`
}

AuditEvent is one read or write of a secret variable's value, see migrations/036_audit_events.up.sql for what counts as a read.

type Backup

type Backup struct {
	ID            string         `db:"id"`
	TileID        sql.NullString `db:"tile_id"`
	DestinationID string         `db:"destination_id"`
	Kind          string         `db:"kind"`
	ContainerMode string         `db:"container_mode"`
	Cron          string         `db:"cron"`
	Timezone      string         `db:"timezone"`
	KeepLatest    int            `db:"keep_latest"`
	Enabled       bool           `db:"enabled"`
	CreatedAt     time.Time      `db:"created_at"`
}

Backup is one schedule: what to back up, where to, how often, how many to keep. TileID is NULL only for kind "stackr".

func (*Backup) Schedule

func (b *Backup) Schedule() string

Schedule is the cron expression as the scheduler sees it: robfig/cron reads the timezone off a CRON_TZ= prefix, so the zone is composed in, not parsed.

type BackupDestination

type BackupDestination struct {
	ID        string         `db:"id"`
	OrgID     sql.NullString `db:"org_id"`
	Name      string         `db:"name"`
	Endpoint  string         `db:"endpoint"`
	Region    string         `db:"region"`
	Bucket    string         `db:"bucket"`
	AccessKey string         `db:"access_key"`
	SecretKey string         `db:"secret_key"` // decrypted on read
	// Shared offers an admin-global destination to every organization.
	// Meaningful only when OrgID is NULL; an org's own destination is already
	// scoped to that org. Off by default: a destination carries the credentials
	// the archive is written with, so handing it out is a decision.
	Shared    bool      `db:"shared"`
	CreatedAt time.Time `db:"created_at"`
}

BackupDestination is an S3-compatible bucket backups are written to. OrgID is NULL for an admin-global destination, which is the only kind the panel's own database may use.

func (*BackupDestination) Global

func (d *BackupDestination) Global() bool

Global reports whether the destination is admin-owned rather than an org's.

func (*BackupDestination) VisibleTo

func (d *BackupDestination) VisibleTo(orgID string) bool

VisibleTo reports whether an org may use this destination: its own, or a global one the admin has shared. An unshared global is "not found" to a tenant, never "forbidden": ids must not leak across orgs.

type BackupRun

type BackupRun struct {
	ID         string       `db:"id"`
	BackupID   string       `db:"backup_id"`
	Trigger    string       `db:"trigger"` // schedule | manual | pre-restore
	Status     string       `db:"status"`  // running | done | error
	ObjectKey  string       `db:"object_key"`
	SizeBytes  int64        `db:"size_bytes"`
	Error      string       `db:"error"`
	CreatedAt  time.Time    `db:"created_at"`
	FinishedAt sql.NullTime `db:"finished_at"`
}

BackupRun is one execution of a Backup.

type ConfigPlan

type ConfigPlan struct {
	ID        string       `db:"id"`
	StackID   string       `db:"stack_id"`
	EnvSlug   string       `db:"env_slug"` // "" = whole-stack plan
	CommitSHA string       `db:"commit_sha"`
	Summary   string       `db:"summary"`
	Plan      string       `db:"plan"`   // JSON stackconf.Plan
	Status    string       `db:"status"` // pending | superseded | applied | rejected | error
	Error     string       `db:"error"`
	CreatedAt time.Time    `db:"created_at"`
	DecidedAt sql.NullTime `db:"decided_at"`
}

ConfigPlan is one stored plan run for a config-managed stack.

type Connector

type Connector struct {
	ID        string    `db:"id"`
	OrgID     string    `db:"org_id"`
	Provider  string    `db:"provider"`
	Name      string    `db:"name"`
	Config    string    `db:"config"`
	CreatedAt time.Time `db:"created_at"`
}

Connector is a per-org integration (github, gitlab, slack, ...). Config is provider-specific JSON; capabilities are decided by provider in code.

type CronRun

type CronRun struct {
	ID         string       `db:"id"`
	Ref        string       `db:"ref"`
	Status     string       `db:"status"`  // running | ok | error | skipped | stopped
	Trigger    string       `db:"trigger"` // schedule | manual web | manual api | deploy
	Actor      string       `db:"actor"`   // user email or api key name; blank on a schedule
	Output     string       `db:"output"`
	StartedAt  time.Time    `db:"started_at"`
	FinishedAt sql.NullTime `db:"finished_at"` // NULL while the run is still going
}

CronRun is one execution of a cron-kind tile ("app:<id>").

func (CronRun) Running

func (r CronRun) Running() bool

Running reports whether the run has not finished yet.

type Deployment

type Deployment struct {
	ID         string       `db:"id"`
	TileID     string       `db:"tile_id"`
	Status     string       `db:"status"` // waiting_ci | queued | running | done | error | cancelled
	Trigger    string       `db:"trigger"`
	CommitSHA  string       `db:"commit_sha"`
	ImageTag   string       `db:"image_tag"`
	Error      string       `db:"error"`
	CreatedAt  time.Time    `db:"created_at"`
	StartedAt  sql.NullTime `db:"started_at"`
	FinishedAt sql.NullTime `db:"finished_at"`
}

Deployment is one build+run attempt of a Tile.

type Domain

type Domain struct {
	ID            string `db:"id"`
	TileID        string `db:"tile_id"`
	Host          string `db:"host"`
	Path          string `db:"path"`
	ContainerPort int    `db:"container_port"`
	HTTPS         bool   `db:"https"`
	// ForceHTTPS bounces plain HTTP to the TLS router. Distinct from HTTPS,
	// which is only "serve TLS here": a host that must still answer on http
	// (a legacy client, a check that cannot follow a redirect) can have a
	// certificate without being redirected onto it. Default on.
	ForceHTTPS bool   `db:"force_https"`
	RedirectTo string `db:"redirect_to"` // target host: requests 301 there instead of proxying
	CertPEM    string `db:"cert_pem"`    // custom certificate chain (PEM), "" = ACME
	KeyPEM     string `db:"key_pem"`     // private key for CertPEM, encrypted at rest
	// Auto marks a hostname stackr generated under a domain resource
	// (EnsureAutoDomain / config `auto: true`) rather than one a person
	// attached. Only these can be put behind the panel's session check.
	Auto bool `db:"auto"`
	// Position is the declaration order among the tile's domains, first
	// listed is primary, what STACKR_PUBLIC_URL resolves to.
	Position  int       `db:"position"`
	CreatedAt time.Time `db:"created_at"`
}

Domain routes a hostname through Traefik to a Tile container port.

type DomainResource

type DomainResource struct {
	ID      string `db:"id"`
	Level   string `db:"level"`    // instance | org | stack
	OwnerID string `db:"owner_id"` // server / org / stack id
	Host    string `db:"host"`
	// IncludeEnvOnDefault keeps the default env's slug in generated names
	// (api.prod.stack.org instead of api.stack.org). Default off.
	IncludeEnvOnDefault bool `db:"include_env_on_default"`
	// ACMEEmail is the Let's Encrypt account certificates under this resource
	// are issued on. Blank uses the instance's. One resolver per distinct
	// address; changing one restarts traefik once.
	ACMEEmail string `db:"acme_email"`
	// Declared marks a row the config file created (mirrors
	// Stack.OrgDeclared). Only a declared row is the file's to delete, a
	// host added in the panel is not, and every row predating domains: is
	// a panel row.
	Declared  bool      `db:"declared"`
	CreatedAt time.Time `db:"created_at"`
}

DomainResource is a domain owned at a level, instance (server), org or stack. Auto-generated tile hostnames nest under the nearest visible resource; an apex claim hands the bare host to one tile.

type Environment

type Environment struct {
	ID        string `db:"id"`
	StackID   string `db:"stack_id"`
	Name      string `db:"name"`
	Slug      string `db:"slug"`
	Type      string `db:"type"`        // static | ephemeral | stack
	BaseEnvID string `db:"base_env_id"` // env this one was cloned from, "" if none
	Settings  string `db:"settings"`

	// Config-as-code: the branch whose copy of the config file drives this
	// env ("" = the stack's bound branch), and the apply policy for plans
	// touching it ("auto" | "manual"; "" = manual for the default env, auto
	// for the rest).
	ConfigBranch string `db:"config_branch"`
	ApplyPolicy  string `db:"apply_policy"`

	// Color is this env's own colour: a palette name ("teal") or a hex
	// value. "" falls back to the org's default for the slug, then to the
	// ladder default. Resolve it through envcolor, never read it directly.
	Color string `db:"color"`

	// Position is the env's rung on the ladder: its index in the config
	// file's environments order, written by apply. 0 on UI stacks, where
	// creation order decides. Read the list in store order, never sort here.
	Position int `db:"position"`

	// Where traefik sits on this env's docker network, recorded when it
	// attaches. Both feed ${{ stackr.PROXY_IP }} / ${{ stackr.PROXY_CIDR }};
	// empty means it has not attached yet. Per-env because traefik joins every
	// environment network and holds a different address on each.
	ProxyIP   string `db:"proxy_ip"`
	ProxyCIDR string `db:"proxy_cidr"`

	// Network is the overlay this env holds out of the pool
	// (infra/netpool). Empty until the first deploy claims one. The name
	// carries no meaning; this column is the only mapping.
	Network string `db:"network"`

	CreatedAt time.Time `db:"created_at"`
}

Environment is the isolation unit inside a stack: its own tiles, network, and graph. Type "static" = created by hand (production, staging); "ephemeral" = disposable clone (temp env, PR env); "stack" = the stack's home for shared tiles (one per stack, see HomeSlug).

func HomeEnv

func HomeEnv(stackID string, at time.Time) *Environment

HomeEnv is a stack's home environment row, ready to insert.

type GraphGroup

type GraphGroup struct {
	ID        string       `db:"id" json:"id"`
	OwnerID   string       `db:"owner_id" json:"-"`
	Members   GroupMembers `db:"member_keys" json:"members"`
	CreatedAt time.Time    `db:"created_at" json:"-"`
	UpdatedAt time.Time    `db:"updated_at" json:"-"`
}

GraphGroup ties cards and annotations together so the canvas moves them as one. Shared per canvas, OwnerID uses the same scope-prefixed keys as NodePosition. Members are "node:<nodeID>" / "anno:<annotationID>" keys; a group is always replaced whole, so they live as one JSON column.

type GroupMembers

type GroupMembers []string

GroupMembers is the JSON string array in graph_groups.member_keys.

func (*GroupMembers) Scan

func (m *GroupMembers) Scan(src any) error

func (GroupMembers) Value

func (m GroupMembers) Value() (driver.Value, error)

type Intended

type Intended struct {
	EnvironmentID string `db:"environment_id"`
	TileSlug      string `db:"tile_slug"`
	Key           string `db:"key"`
	Value         string `db:"value"`
}

Intended is one key on one tile whose difference from the first environment someone has said is on purpose. Value is the key's value when it was marked ("" = declared per environment by the config file, any value).

type Invite

type Invite struct {
	ID        string       `db:"id"` // the token in the invite URL
	OrgID     string       `db:"org_id"`
	Email     string       `db:"email"` // optional restriction, "" = anyone with the link
	Role      string       `db:"role"`
	CreatedBy string       `db:"created_by"`
	CreatedAt time.Time    `db:"created_at"`
	ExpiresAt time.Time    `db:"expires_at"`
	UsedAt    sql.NullTime `db:"used_at"`

	// MailFailed is set for the request that created the invite when sending
	// its email did not work, so the page can say "copy the link instead". Not
	// stored: the next page load has the link either way.
	MailFailed bool `db:"-"`
}

Invite is a shareable join link for an org.

type JoinKey

type JoinKey struct {
	Key       string       `db:"key"`
	ServerID  string       `db:"server_id"`
	Address   string       `db:"address"`
	ExpiresAt time.Time    `db:"expires_at"`
	UsedAt    sql.NullTime `db:"used_at"`
	CreatedAt time.Time    `db:"created_at"`
}

JoinKey is a one-time swarm join secret: bound to the address the operator typed on Add node, burned the moment it is used, and dead after an hour.

func (JoinKey) Spent

func (k JoinKey) Spent() bool

Spent reports whether the key can no longer be used: burned already, or past its hour.

type ManagedResource

type ManagedResource struct {
	ID             string    `db:"id"`
	EnvironmentID  string    `db:"environment_id"`
	ProviderTileID string    `db:"provider_tile_id"`
	Name           string    `db:"name"`
	Slug           string    `db:"slug"`
	Kind           string    `db:"kind"`   // the providing instance's engine (databases.Engines key)
	Status         string    `db:"status"` // active | orphaned
	Public         bool      `db:"public"`
	CreatedAt      time.Time `db:"created_at"`
	UpdatedAt      time.Time `db:"updated_at"`
}

ManagedResource is a logical resource a provider tile hands out, a database inside a postgres instance, a bucket on an s3 server. Referenced by Slug, which shares the environment's tile namespace: ${{ tile.<slug>.<output> }}.

type Metric

type Metric struct {
	Ref      string    `db:"ref"`
	TS       time.Time `db:"ts"`
	CPUPct   float64   `db:"cpu_pct"`
	MemBytes int64     `db:"mem_bytes"`
	RxBps    float64   `db:"rx_bps"` // ingress, bytes/second
	TxBps    float64   `db:"tx_bps"` // egress, bytes/second
}

Metric is one CPU/mem/network sample for a managed container or the host.

type NodePosition

type NodePosition struct {
	OwnerID string  `db:"owner_id"`
	NodeID  string  `db:"node_id"`
	X       float64 `db:"x"`
	Y       float64 `db:"y"`
}

NodePosition is a persisted canvas position for one graph node. OwnerID is scope-prefixed ("env:<stackID>", every environment of a stack shares one layout, "stack:<stackID>", "org:<orgID>"). Node ids are slug-based ("app:<slug>") so they survive a redeploy.

type Notification

type Notification struct {
	ID        string    `db:"id"`
	UserID    string    `db:"user_id"`
	Kind      string    `db:"kind"` // deploy_failed | deploy_done | cron_failed
	Title     string    `db:"title"`
	Body      string    `db:"body"`
	Link      string    `db:"link"`
	Read      bool      `db:"read"`
	CreatedAt time.Time `db:"created_at"`
}

Notification is one entry in one person's notification center. Events fan out to a row per recipient, so read state and preferences are per-user.

type Org

type Org struct {
	ID   string `db:"id"`
	Name string `db:"name"`
	Slug string `db:"slug"`
	// AvatarPath is the org's logo in FileStorage, "" = fall back to initials.
	AvatarPath string    `db:"avatar_path"`
	CreatedAt  time.Time `db:"created_at"`

	// Org-level config-as-code binding (§6), mirroring the stack fields.
	ConfigConnectorID string `db:"config_connector_id"`
	ConfigRepo        string `db:"config_repo"`
	ConfigBranch      string `db:"config_branch"`
	ConfigPath        string `db:"config_path"`

	// SetupDoneAt closes the onboarding wizard for this org. Nil means the
	// wizard is still the right place to send its owner; set means every
	// /setup step redirects to the settings tab that owns the same thing.
	SetupDoneAt *time.Time `db:"setup_done_at"`

	// SetupMode is the wizard branch: "config" (a file declares the org) or
	// "ui" (filled in step by step). Read it through SetupConfigBranch, never
	// directly, an org created before the wizard had branches has neither.
	SetupMode string `db:"setup_mode"`

	// UIEditsDefault is the org file's defaults.ui_edits, inherited by every
	// stack that does not declare its own. Blank = block. Read it through
	// Stack.UIEdits, never directly.
	UIEditsDefault string `db:"ui_edits"`

	// EnvColors is a json object of env slug to colour, the org-wide default
	// for every environment with that slug. See envcolor.
	EnvColors string `db:"env_colors"`

	// Settings is this org's level of the defaults cascade (server -> org ->
	// stack -> env -> tile). JSON overrides, see internal/stackrd/config/settings.
	Settings string `db:"settings"`
}

Org groups stacks. Grouping only for now, membership/roles come later.

func (*Org) ConfigManaged

func (o *Org) ConfigManaged() bool

ConfigManaged reports whether the org's structure is owned by a config file.

func (*Org) SetupConfigBranch

func (o *Org) SetupConfigBranch() bool

SetupConfigBranch reports whether the wizard is walking this org down the config-as-code branch, which has no name step and no domain step.

type OrgMember

type OrgMember struct {
	OrgID     string    `db:"org_id"`
	UserID    string    `db:"user_id"`
	Role      string    `db:"role"`
	CreatedAt time.Time `db:"created_at"`

	// Joined for display (ListOrgMembers).
	Email      string `db:"email"`
	Name       string `db:"name"`
	AvatarPath string `db:"avatar_path"`
}

OrgMember links a user to an org with a role. Roles: "owner" (manage org + members), "member" (full content access), "viewer" (read-only). Server admins (User.Role == "admin") bypass all of it.

type OrgRegistryCredential

type OrgRegistryCredential struct {
	ID         string       `db:"id"`
	OrgID      string       `db:"org_id"`
	Name       string       `db:"name"`
	SecretHash string       `db:"secret_hash"`
	Prefix     string       `db:"prefix"` // visible half, for telling two apart
	System     bool         `db:"system"`
	CreatedAt  time.Time    `db:"created_at"`
	LastUsedAt sql.NullTime `db:"last_used_at"`
}

OrgRegistryCredential is a push/pull credential for one organization's registry namespace. Hashed like an APIKey: the plaintext is shown once and is not recoverable, so a database copy is not a set of push credentials.

System marks the one stackr's own deploys use. It is created with the org and cannot be deleted: without it the org's next build has nothing to push with.

type Provision

type Provision struct {
	ID             string `db:"id"`
	InstanceTileID string `db:"instance_tile_id"`
	ConsumerTileID string `db:"consumer_tile_id"` // "" = orphaned
	EnvID          string `db:"env_id"`
	DBName         string `db:"db_name"`
	DBUser         string `db:"db_user"`
	DBPassword     string `db:"db_password"`
	SecretName     string `db:"secret_name"`
	Status         string `db:"status"` // active | orphaned
	Public         bool   `db:"public"` // s3: bucket has a public-read policy
	// OnRemove is what happens when the config file stops declaring this slice:
	// "" / "detach" orphan it and keep the data, "drop" destroys it. Kept on the
	// row because the declaration that carried the policy is gone by the time
	// the removal is applied.
	OnRemove string `db:"on_remove"`
	// ResourceSlug is the reference name of a config-declared slice, the
	// config key. "" keeps the derived <instance>-<dbname> form
	// (panel/API-provisioned slices). Read through databases.ResourceSlug.
	ResourceSlug string    `db:"resource_slug"`
	CreatedAt    time.Time `db:"created_at"`
}

Provision is one logical database inside a shared db instance, owned by a consumer tile. Creds live here (encrypted) and are published as the env managed resource, so the consumer references ${{ tile.<slug>.DATABASE_URL }}. SecretName is vestigial, kept until the legacy-drop migration.

type Registry

type Registry struct {
	ID        string    `db:"id"`
	Name      string    `db:"name"`
	URL       string    `db:"url"`
	Domain    string    `db:"domain"` // TLS domain routed via Traefik (managed registry)
	Username  string    `db:"username"`
	Password  string    `db:"password"`
	Managed   bool      `db:"managed"`
	CreatedAt time.Time `db:"created_at"`
}

Registry is a Docker registry credential set.

func (*Registry) PushURL

func (r *Registry) PushURL() string

PushURL is the host an image is tagged and pushed under. The TLS domain wins when one is set: that is the name a worker node can pull from, and under swarm the image ref recorded on a deployment has to be resolvable from every node, not just the manager's own localhost (docs/plans/30-docker-swarm.md, decision 3).

type ResourceBinding

type ResourceBinding struct {
	ResourceID     string    `db:"resource_id"`
	ConsumerTileID string    `db:"consumer_tile_id"`
	CreatedAt      time.Time `db:"created_at"`
}

ResourceBinding grants one consumer tile access to a resource's outputs. Without it the resolver refuses the reference.

type ResourceOutput

type ResourceOutput struct {
	ResourceID      string `db:"resource_id"`
	Name            string `db:"name"`
	Value           string `db:"value"`
	Secret          bool   `db:"secret"`
	RequiresNetwork bool   `db:"requires_network"`
}

ResourceOutput is one named value a resource publishes (DATABASE_URL, PGHOST, S3_BUCKET…). RequiresNetwork marks outputs only reachable over the provider's shared docker network, so the resolver knows to attach it.

type SecretLink struct {
	ID        string `db:"id"`
	Kind      string `db:"kind"`
	OwnerKind string `db:"owner_kind"`
	OwnerID   string `db:"owner_id"`
	Label     string `db:"label"`
	TokenHash string `db:"token_hash"`
	PassHash  string `db:"pass_hash"` // "" = no passphrase
	Fields    string `db:"fields"`    // JSON []SecretLinkField
	State     string `db:"state"`
	Attempts  int    `db:"attempts"`
	// WindowMinutes keeps a share link alive this long after first access, so
	// the recipient can copy without racing the burn. 0 = burn immediately.
	WindowMinutes int          `db:"window_minutes"`
	ExpiresAt     time.Time    `db:"expires_at"`
	OpenedAt      sql.NullTime `db:"opened_at"`
	CreatedBy     string       `db:"created_by"`
	CreatedAt     time.Time    `db:"created_at"`
}

SecretLink is a one-shot exchange with someone who has no account. The row holds field names only, never values, so it doubles as the audit line.

func (*SecretLink) Dead

func (l *SecretLink) Dead(now time.Time) bool

Dead reports whether the link can no longer be used. Expiry is evaluated here, at read time, so a link stops working the moment it lapses rather than whenever a sweep next runs.

func (*SecretLink) FieldList

func (l *SecretLink) FieldList() []SecretLinkField

FieldList decodes Fields, returning nil on malformed JSON.

type SecretLinkField

type SecretLinkField struct {
	Name   string `json:"name"`
	Secret bool   `json:"secret"`
	Hint   string `json:"hint,omitempty"`
}

SecretLinkField is one entry in SecretLink.Fields. For a drop box it describes an input to collect; for a share link it names an existing variable in the link's scope (a pointer, the value is read at reveal, so revoking the link leaves nothing to clean up).

type Server

type Server struct {
	ID        string    `db:"id"`
	Name      string    `db:"name"`
	Kind      string    `db:"kind"` // local | swarm | remote
	Endpoint  string    `db:"endpoint"`
	Settings  string    `db:"settings"` // JSON defaults, see internal/settings
	CreatedAt time.Time `db:"created_at"`

	NodeID     string       `db:"node_id"`
	Hostname   string       `db:"hostname"`
	Address    string       `db:"address"`
	Role       string       `db:"role"`   // manager | worker
	Status     string       `db:"status"` // pending | ready | draining | down
	LastSeenAt sql.NullTime `db:"last_seen_at"`
}

Server is one Docker host stackr manages: the "local" row is the swarm manager and runs the panel, every other row is a swarm node added through Add node (docs/plans/32-multi-node-ui.md).

Name is the display name the operator typed; Hostname arrives with the join. NodeID is empty until the node shows up in `docker node ls`, which is what "pending" means. Role, Status and LastSeenAt are mirrored from swarm on every load of the servers list, not authored here.

type Stack

type Stack struct {
	ID      string `db:"id"`
	OrgID   string `db:"org_id"`
	OrgSlug string `db:"-"` // filled by handlers for URL building

	Name        string `db:"name"`
	Slug        string `db:"slug"`
	Description string `db:"description"`
	Settings    string `db:"settings"` // JSON overrides, see internal/settings

	// Config-as-code binding: repo holding stackr-compose.yml. Empty
	// connector = UI-managed stack.
	ConfigConnectorID string `db:"config_connector_id"`
	ConfigRepo        string `db:"config_repo"`   // "owner/name"
	ConfigBranch      string `db:"config_branch"` // "" = repo default branch
	ConfigPath        string `db:"config_path"`   // "" = stackconf.DefaultPath

	// OrgDeclared marks a stack the org config file declares under stacks:.
	// The org file owns such a stack's name (the instantiator names the
	// instance, Helm-style), so the stack file's stack: field cannot rename
	// it. Refreshed on every org plan and set at org apply.
	OrgDeclared bool `db:"org_declared"`

	// UIEditsMode is what ApplyPlan resolved from the config files (the stack
	// file, then the org file's defaults:). Blank until a config-managed stack
	// has applied once. Read it through UIEdits().
	UIEditsMode string `db:"ui_edits"`

	CreatedAt time.Time `db:"created_at"`
}

Stack groups environments (formerly "project").

func (*Stack) ConfigManaged

func (s *Stack) ConfigManaged() bool

ConfigManaged reports whether the stack is bound to a config repo.

func (*Stack) UIEdits

func (s *Stack) UIEdits() string

UIEdits is the stack's edit mode, block unless the config says otherwise. Only meaningful on a config-managed stack, a UI-managed one owns its tiles outright and always stages.

type StagedChange

type StagedChange struct {
	ID         string    `db:"id"`
	StackID    string    `db:"stack_id"`
	EnvID      string    `db:"env_id"`
	TileSlug   string    `db:"tile_slug"`
	AuthorID   string    `db:"author_id"`
	AuthorName string    `db:"author_name"`
	Summary    string    `db:"summary"`
	Payload    string    `db:"payload"`
	CreatedAt  time.Time `db:"created_at"`
}

StagedChange is one pending structural edit in the UI-staging buffer: applied to a tile's desired config, reviewed, then committed as a transaction through the reconcile engine. Payload is a JSON {field: value}.

type Storage

type Storage struct {
	ID        string    `db:"id"`
	ServerID  string    `db:"server_id"`
	Name      string    `db:"name"`
	Slug      string    `db:"slug"`
	Backend   string    `db:"backend"` // nfs | smb | local
	Address   string    `db:"address"`
	Export    string    `db:"export"`
	Username  string    `db:"username"`
	Password  string    `db:"password"` // decrypted in the store layer
	Opts      string    `db:"opts"`
	Status    string    `db:"status"` // ok | error | unknown, last probe
	StatusMsg string    `db:"status_msg"`
	CreatedAt time.Time `db:"created_at"`
}

Storage is a server-scoped share or pool (§2.7): an nfs/smb network share or a local path pool, consumed through declared sub-paths, each backed by a docker local-driver volume. Never mounted on the host by stackr, docker performs the mount at container start.

type StoragePath

type StoragePath struct {
	ID        string    `db:"id"`
	StorageID string    `db:"storage_id"`
	Name      string    `db:"name"`
	Subpath   string    `db:"subpath"`
	ForcedRO  bool      `db:"forced_ro"`
	CreatedAt time.Time `db:"created_at"`
}

StoragePath is one declared sub-path on a Storage, the only unit tiles may attach (§2.7 strict sub-paths). Each is its own docker volume.

type Store

type Store interface {
	// Health checks the database connection.
	Health(ctx context.Context) error

	// Session persistence, satisfies auth.SessionStore.
	auth.SessionStore

	// Users
	GetUserByID(ctx context.Context, id string) (*User, error)
	GetUserByEmail(ctx context.Context, email string) (*User, error)
	CreateUser(ctx context.Context, user *User) error
	UpdateUser(ctx context.Context, user *User) error
	CountUsers(ctx context.Context) (int, error)
	ListUsers(ctx context.Context) ([]User, error)

	// Servers
	GetServer(ctx context.Context, id string) (*Server, error)
	GetServerByNodeID(ctx context.Context, nodeID string) (*Server, error)
	ListServers(ctx context.Context) ([]Server, error)
	CreateServer(ctx context.Context, sv *Server) error
	UpdateServer(ctx context.Context, sv *Server) error
	DeleteServer(ctx context.Context, id string) error

	// Join keys (one-time swarm join secrets)
	CreateJoinKey(ctx context.Context, k *JoinKey) error
	GetJoinKey(ctx context.Context, key string) (*JoinKey, error)
	LatestJoinKey(ctx context.Context, serverID string) (*JoinKey, error)
	BurnJoinKey(ctx context.Context, key string) (bool, error)
	BurnServerJoinKeys(ctx context.Context, serverID string) (int, error)

	// Orgs
	GetOrg(ctx context.Context, id string) (*Org, error)
	GetOrgBySlug(ctx context.Context, slug string) (*Org, error)
	ListOrgs(ctx context.Context) ([]Org, error)
	CreateOrg(ctx context.Context, o *Org) error
	UpdateOrg(ctx context.Context, o *Org) error
	DeleteOrg(ctx context.Context, id string) error

	// Org membership + invites
	ListOrgsForUser(ctx context.Context, userID string) ([]Org, error)
	ListOrgMembers(ctx context.Context, orgID string) ([]OrgMember, error)
	GetOrgMember(ctx context.Context, orgID, userID string) (*OrgMember, error)
	UpsertOrgMember(ctx context.Context, m *OrgMember) error
	DeleteOrgMember(ctx context.Context, orgID, userID string) error
	CreateInvite(ctx context.Context, i *Invite) error
	GetInvite(ctx context.Context, id string) (*Invite, error)
	ListInvitesByOrg(ctx context.Context, orgID string) ([]Invite, error)
	MarkInviteUsed(ctx context.Context, id string) error
	DeleteInvite(ctx context.Context, id string) error

	// Connectors
	CreateConnector(ctx context.Context, cn *Connector) error
	GetConnector(ctx context.Context, id string) (*Connector, error)
	ListConnectorsByOrg(ctx context.Context, orgID string) ([]Connector, error)
	ListConnectors(ctx context.Context) ([]Connector, error)
	UpdateConnector(ctx context.Context, cn *Connector) error
	DeleteConnector(ctx context.Context, id string) error

	// Storage (server-scoped shares/pools, §2.7)
	CreateStorage(ctx context.Context, s *Storage) error
	GetStorage(ctx context.Context, id string) (*Storage, error)
	GetStorageBySlug(ctx context.Context, slug string) (*Storage, error)
	ListStorage(ctx context.Context) ([]Storage, error)
	UpdateStorage(ctx context.Context, s *Storage) error
	DeleteStorage(ctx context.Context, id string) error
	CreateStoragePath(ctx context.Context, p *StoragePath) error
	GetStoragePath(ctx context.Context, id string) (*StoragePath, error)
	ListStoragePaths(ctx context.Context, storageID string) ([]StoragePath, error)
	DeleteStoragePath(ctx context.Context, id string) error

	// Stacks
	CreateStack(ctx context.Context, s *Stack) error
	GetStack(ctx context.Context, id string) (*Stack, error)
	GetStackBySlug(ctx context.Context, orgID, slug string) (*Stack, error)
	ListStacks(ctx context.Context) ([]Stack, error)
	ListStacksByOrg(ctx context.Context, orgID string) ([]Stack, error)
	SetStackOrg(ctx context.Context, stackID, orgID string) error
	UpdateStack(ctx context.Context, s *Stack) error
	CreateConfigPlan(ctx context.Context, p *ConfigPlan) error
	GetConfigPlan(ctx context.Context, id string) (*ConfigPlan, error)
	LatestConfigPlan(ctx context.Context, stackID string) (*ConfigPlan, error)
	CountStacksAwaitingPlan(ctx context.Context, orgID string) (int, error)
	ListConfigPlans(ctx context.Context, stackID string, limit int) ([]ConfigPlan, error)
	SetConfigPlanStatus(ctx context.Context, id, status string) error
	// SetConfigPlanError keeps why an apply failed on the row, so the plan
	// page can show it after the flash is gone. The status is untouched: a
	// stack plan that failed to apply is still the pending decision.
	SetConfigPlanError(ctx context.Context, id, msg string) error
	SupersedePendingPlans(ctx context.Context, stackID, envSlug string) error
	CreateOrgConfigPlan(ctx context.Context, p *ConfigPlan) error
	GetOrgConfigPlan(ctx context.Context, id string) (*ConfigPlan, error)
	ListOrgConfigPlans(ctx context.Context, orgID string, limit int) ([]ConfigPlan, error)
	SetOrgConfigPlanStatus(ctx context.Context, id, status string) error
	// SetOrgConfigPlanError marks the plan errored and keeps the reason.
	SetOrgConfigPlanError(ctx context.Context, id, msg string) error
	SupersedePendingOrgPlans(ctx context.Context, orgID string) error
	DeleteStack(ctx context.Context, id string) error

	// Environments
	CreateEnvironment(ctx context.Context, e *Environment) error
	GetEnvironment(ctx context.Context, id string) (*Environment, error)
	GetEnvironmentBySlug(ctx context.Context, stackID, slug string) (*Environment, error)
	UpdateEnvironment(ctx context.Context, e *Environment) error
	RenameEnvironment(ctx context.Context, id, name, slug string) error
	SetEnvironmentProxy(ctx context.Context, envID, ip, cidr string) error
	// SetEnvironmentNetwork records which pooled overlay this env holds
	// ("" returns it). SetTileSharedNet is the same for a shared managed
	// instance's own overlay. ClaimedNetworks is every name either column
	// currently holds, what infra/netpool hands out from and sweeps against.
	SetEnvironmentNetwork(ctx context.Context, envID, name string) error
	SetTileSharedNet(ctx context.Context, tileID, name string) error
	ClaimedNetworks(ctx context.Context) ([]string, error)
	EnvironmentsWithoutNetwork(ctx context.Context) ([]string, error)
	// ListEnvironmentsByStack is the ladder: static envs by position, then
	// ephemeral ones. The home is never in it.
	ListEnvironmentsByStack(ctx context.Context, stackID string) ([]Environment, error)
	// HomeEnvironment is the stack's home for shared tiles (nil if none).
	HomeEnvironment(ctx context.Context, stackID string) (*Environment, error)
	DeleteEnvironment(ctx context.Context, id string) error
	// Intended flags: differences between environments marked as on purpose.
	ListIntended(ctx context.Context, envID string) ([]Intended, error)
	SetIntended(ctx context.Context, row *Intended) error
	DeleteIntended(ctx context.Context, envID, tileSlug, key string) error
	// ClearDeclaredIntended drops the rows the config file wrote (value ""),
	// so an apply can rewrite them from the file as it is now.
	ClearDeclaredIntended(ctx context.Context, envID string) error

	// Tiles
	CreateTile(ctx context.Context, t *Tile) error
	GetTile(ctx context.Context, id string) (*Tile, error)
	GetTileBySlug(ctx context.Context, envID, slug string) (*Tile, error)
	ListTilesByEnv(ctx context.Context, envID string) ([]Tile, error)
	ListTilesByStack(ctx context.Context, stackID string) ([]Tile, error)
	ListTiles(ctx context.Context) ([]Tile, error)
	UpdateTile(ctx context.Context, t *Tile) error
	RenameTile(ctx context.Context, id, name, slug string) error
	UpdateTileStatus(ctx context.Context, id, status string) error
	SetTileHomeNode(ctx context.Context, id, nodeID string) error
	SetTileImageDigest(ctx context.Context, id, digest string) error
	SetTileLatestDigest(ctx context.Context, id, digest string) error
	RecordTileRun(ctx context.Context, id, status, output string) error
	DeleteTile(ctx context.Context, id string) error

	// Deployments
	CreateDeployment(ctx context.Context, d *Deployment) error
	GetDeployment(ctx context.Context, id string) (*Deployment, error)
	ListDeploymentsByTile(ctx context.Context, tileID string, limit int) ([]Deployment, error)
	ListDeploymentsByStatus(ctx context.Context, status string) ([]Deployment, error)

	// Work queue (docs/plans/33-workqueue.md).
	CreateWorkItem(ctx context.Context, w *WorkItem) error
	GetWorkItem(ctx context.Context, id string) (*WorkItem, error)
	ListWorkItemsByStatus(ctx context.Context, status string) ([]WorkItem, error)
	LatestWorkItem(ctx context.Context, kind, dedupeKey string) (*WorkItem, error)
	SupersedeQueuedWorkItems(ctx context.Context, kind, dedupeKey, exceptID string) error
	ClaimWorkItem(ctx context.Context, id string) (bool, error)
	FinishWorkItem(ctx context.Context, id, status, errMsg string) error
	RequeueWorkItem(ctx context.Context, id string) error
	SetWorkItemProgress(ctx context.Context, id, step, progress string) error
	UpdateDeployment(ctx context.Context, d *Deployment) error
	// SweepStaleRuns clears work that only the running process could have
	// finished, call once at startup, after a crash or a restart mid-deploy.
	SweepStaleRuns(ctx context.Context) error

	// Domains
	CreateDomain(ctx context.Context, d *Domain) error
	GetDomain(ctx context.Context, id string) (*Domain, error)
	GetDomainByHostPath(ctx context.Context, host, path string) (*Domain, error)
	ListDomainsByTile(ctx context.Context, tileID string) ([]Domain, error)
	ListDomains(ctx context.Context) ([]Domain, error)
	SetDomainHTTPS(ctx context.Context, id string, https bool) error
	SetDomainForceHTTPS(ctx context.Context, id string, force bool) error
	SetDomainResourceACME(ctx context.Context, id, email string) error
	SetDomainCert(ctx context.Context, id, certPEM, keyPEM string) error
	DeleteDomain(ctx context.Context, id string) error

	// Domain resources
	CreateDomainResource(ctx context.Context, r *DomainResource) error
	UpdateDomainResource(ctx context.Context, r *DomainResource) error
	ListDomainResources(ctx context.Context) ([]DomainResource, error)
	DeleteDomainResource(ctx context.Context, id string) error

	// Registries
	CreateRegistry(ctx context.Context, r *Registry) error
	GetRegistry(ctx context.Context, id string) (*Registry, error)
	GetManagedRegistry(ctx context.Context) (*Registry, error)
	ListRegistries(ctx context.Context) ([]Registry, error)
	UpdateRegistry(ctx context.Context, r *Registry) error
	DeleteRegistry(ctx context.Context, id string) error

	// Cron run history
	CreateCronRun(ctx context.Context, r *CronRun) error
	FinishCronRun(ctx context.Context, r *CronRun) error
	ListCronRuns(ctx context.Context, ref string, limit int) ([]CronRun, error)
	GetCronRun(ctx context.Context, id string) (*CronRun, error)
	OpenCronRun(ctx context.Context, ref string) (*CronRun, error)
	ListOpenCronRuns(ctx context.Context) ([]CronRun, error)
	PruneCronRuns(ctx context.Context, before time.Time) error
	CloseOrphanCronRuns(ctx context.Context) error

	// API keys
	CreateOrgRegistryCredential(ctx context.Context, c *OrgRegistryCredential) error
	GetOrgRegistryCredentialByHash(ctx context.Context, hash string) (*OrgRegistryCredential, error)
	GetOrgRegistryCredential(ctx context.Context, id string) (*OrgRegistryCredential, error)
	ListOrgRegistryCredentials(ctx context.Context, orgID string) ([]OrgRegistryCredential, error)
	DeleteOrgRegistryCredential(ctx context.Context, id string) error
	DeleteSystemOrgRegistryCredential(ctx context.Context, id string) error
	TouchOrgRegistryCredential(ctx context.Context, id string) error

	CreateAPIKey(ctx context.Context, k *APIKey) error
	GetAPIKeyByHash(ctx context.Context, hash string) (*APIKey, error)
	ListAPIKeys(ctx context.Context) ([]APIKey, error)
	DeleteAPIKey(ctx context.Context, id string) error

	// UI staging buffer (per-env pending structural edits)
	CreateStagedChange(ctx context.Context, s *StagedChange) error
	ListStagedByEnv(ctx context.Context, envID string) ([]StagedChange, error)
	ListStagedByStack(ctx context.Context, stackID string) ([]StagedChange, error)
	CountStagedByEnv(ctx context.Context, envID string) (int, error)
	GetStagedChange(ctx context.Context, id string) (*StagedChange, error)
	DeleteStagedChange(ctx context.Context, id string) error
	DeleteStagedByEnv(ctx context.Context, envID string) error

	// Shared-instance provisions (passwords decrypted on read)
	CreateProvision(ctx context.Context, p *Provision) error
	GetProvision(ctx context.Context, id string) (*Provision, error)
	ListProvisionsByInstance(ctx context.Context, instanceTileID string) ([]Provision, error)
	ListProvisionsByConsumer(ctx context.Context, consumerTileID string) ([]Provision, error)
	ListProvisionsByEnv(ctx context.Context, envID string) ([]Provision, error)
	UpdateProvision(ctx context.Context, p *Provision) error
	DeleteProvision(ctx context.Context, id string) error

	// Variables (values decrypted on read). ReplaceTileVars is the config-apply
	// write: the file is the whole truth, so undeclared non-secret vars go.
	ReplaceTileVars(ctx context.Context, t *Tile) error
	ListVariables(ctx context.Context, ownerKind, ownerID string) ([]Variable, error)
	// ListVariableNames is the search view: every variable's owner, name and
	// secret flag, with Value left empty, nothing is decrypted.
	ListVariableNames(ctx context.Context) ([]Variable, error)
	UpsertVariable(ctx context.Context, v *Variable) error
	DeleteVariable(ctx context.Context, ownerKind, ownerID, name string) error

	// Secret audit trail: reads and writes of secret variable values.
	// Inserts are best-effort, callers log failures, never abort on them.
	AddAuditEvent(ctx context.Context, e *AuditEvent) error
	ListAuditEvents(ctx context.Context, ownerKind, ownerID string, limit int) ([]AuditEvent, error)
	ListAllAuditEvents(ctx context.Context, actor, action string, limit int) ([]AuditEvent, error)

	// Secret links. ClaimSecretLink is the burn: it flips open -> state in one
	// statement and reports whether this caller was the one that won, so two
	// concurrent submits can't both go through.
	CreateSecretLink(ctx context.Context, l *SecretLink) error
	GetSecretLinkByHash(ctx context.Context, tokenHash string) (*SecretLink, error)
	ListSecretLinks(ctx context.Context, ownerKind, ownerID string) ([]SecretLink, error)
	ClaimSecretLink(ctx context.Context, id, state string) (bool, error)
	// BurnDropLink is the claim plus the variable writes in one transaction:
	// a failed write rolls back the burn, so the sender can always resubmit.
	BurnDropLink(ctx context.Context, id string, vars []Variable) (bool, error)
	TouchSecretLink(ctx context.Context, id string, attempts int, openedAt sql.NullTime) error
	DeleteSecretLink(ctx context.Context, id string) error

	// Managed resources + their outputs and consumer bindings
	// (output values decrypted on read)
	CreateResource(ctx context.Context, r *ManagedResource) error
	GetResource(ctx context.Context, id string) (*ManagedResource, error)
	ListResourcesByEnv(ctx context.Context, envID string) ([]ManagedResource, error)
	ListResourcesByProvider(ctx context.Context, providerTileID string) ([]ManagedResource, error)
	UpdateResource(ctx context.Context, r *ManagedResource) error
	DeleteResource(ctx context.Context, id string) error
	ListOutputs(ctx context.Context, resourceID string) ([]ResourceOutput, error)
	UpsertOutput(ctx context.Context, o *ResourceOutput) error
	CreateBinding(ctx context.Context, b *ResourceBinding) error
	DeleteBinding(ctx context.Context, resourceID, consumerTileID string) error
	ListBindingsByResource(ctx context.Context, resourceID string) ([]ResourceBinding, error)
	BindingsForConsumer(ctx context.Context, consumerTileID string) ([]ResourceBinding, error)

	// Backups (destination secret keys decrypted on read). Nothing here
	// filters by org, callers resolve tile → org → membership first.
	CreateBackupDestination(ctx context.Context, d *BackupDestination) error
	GetBackupDestination(ctx context.Context, id string) (*BackupDestination, error)
	ListBackupDestinations(ctx context.Context) ([]BackupDestination, error)
	UpdateBackupDestination(ctx context.Context, d *BackupDestination) error
	DeleteBackupDestination(ctx context.Context, id string) error
	CreateBackup(ctx context.Context, b *Backup) error
	GetBackup(ctx context.Context, id string) (*Backup, error)
	ListBackupsByTile(ctx context.Context, tileID string) ([]Backup, error)
	ListBackups(ctx context.Context) ([]Backup, error)
	UpdateBackup(ctx context.Context, b *Backup) error
	DeleteBackup(ctx context.Context, id string) error
	CreateBackupRun(ctx context.Context, r *BackupRun) error
	GetBackupRun(ctx context.Context, id string) (*BackupRun, error)
	ListBackupRuns(ctx context.Context, backupID string, limit int) ([]BackupRun, error)
	UpdateBackupRun(ctx context.Context, r *BackupRun) error

	// Settings
	GetSetting(ctx context.Context, key string) (string, error)
	SetSetting(ctx context.Context, key, value string) error

	// Notifications, every one belongs to a single recipient.
	CreateNotification(ctx context.Context, n *Notification) error
	ListNotifications(ctx context.Context, userID string, limit int) ([]Notification, error)
	CountUnreadNotifications(ctx context.Context, userID string) (int, error)
	MarkAllNotificationsRead(ctx context.Context, userID string) error
	DeleteAllNotifications(ctx context.Context, userID string) error
	PruneNotifications(ctx context.Context, before time.Time) error

	// Node positions (stack graph canvas, slug-keyed)
	ListNodePositions(ctx context.Context, ownerID string) ([]NodePosition, error)
	UpsertNodePosition(ctx context.Context, p *NodePosition) error
	// SaveNodePositions writes a whole canvas layout in one transaction, after
	// validating it. A partially-applied drag leaves a scrambled canvas, and
	// the payload comes straight off the wire.
	SaveNodePositions(ctx context.Context, ownerID string, ps []NodePosition) error
	DeleteNodePositions(ctx context.Context, ownerID string) error

	// Annotations (canvas notes, shared per canvas like node positions)
	ListAnnotations(ctx context.Context, ownerID string) ([]Annotation, error)
	UpsertAnnotation(ctx context.Context, a *Annotation) error
	DeleteAnnotation(ctx context.Context, ownerID, id string) error

	// Graph groups (cards/annotations that move together, per canvas)
	ListGraphGroups(ctx context.Context, ownerID string) ([]GraphGroup, error)
	UpsertGraphGroup(ctx context.Context, g *GraphGroup) error
	DeleteGraphGroup(ctx context.Context, ownerID, id string) error

	// Metrics
	InsertMetric(ctx context.Context, m *Metric) error
	ListMetrics(ctx context.Context, ref string, since time.Time) ([]Metric, error)
	PruneMetrics(ctx context.Context, before time.Time) error
}

Store defines the data access interface for the application.

type Tile

type Tile struct {
	ID             string `db:"id"`
	StackID        string `db:"stack_id"` // denormalized from environment for cheap stack-wide queries
	EnvironmentID  string `db:"environment_id"`
	Name           string `db:"name"`
	Slug           string `db:"slug"`
	Kind           string `db:"kind"`        // service | cron
	SourceType     string `db:"source_type"` // git | image
	GitURL         string `db:"git_url"`
	GitBranch      string `db:"git_branch"`
	ConnectorID    string `db:"connector_id"` // git connector for clone auth, "" = public/manual
	ImageRef       string `db:"image_ref"`
	DockerfilePath string `db:"dockerfile_path"`
	BuildContext   string `db:"build_context"`
	Env            string `db:"env"`
	BuildArgs      string `db:"build_args"`
	Volumes        string `db:"volumes"`
	ContainerPort  int    `db:"container_port"`
	HealthcheckCmd string `db:"healthcheck_cmd"`
	// Docker-native HEALTHCHECK knobs for HealthcheckCmd (0 = docker default).
	HealthcheckIntervalS    int `db:"healthcheck_interval_s"`
	HealthcheckTimeoutS     int `db:"healthcheck_timeout_s"`
	HealthcheckRetries      int `db:"healthcheck_retries"`
	HealthcheckStartPeriodS int `db:"healthcheck_start_period_s"`
	// RunOnDeploy is the function-tile trigger: run after its own deploy
	// finishes, in addition to manual "Run now".
	RunOnDeploy bool `db:"run_on_deploy"`
	// DependsOn: startup-order dependencies, one per line, "slug" or
	// "slug:condition" (started | healthy | completed). Bulk starts only.
	DependsOn string `db:"depends_on"`
	// Files ships repo files into the container, one per line:
	// "repo/path:/container/path[:template]", fetched at deploy, ro-mounted.
	Files string `db:"files"`
	// Storage attaches declared storage sub-paths, one per line:
	// "storage-slug/path-name:/mount[:ro]" (§2.7). Resolved to docker
	// local-driver volumes at deploy.
	Storage      string  `db:"storage"`
	WebhookToken string  `db:"webhook_token"`
	Status       string  `db:"status"`
	CPULimit     float64 `db:"cpu_limit"`    // cores, 0 = unlimited
	MemLimitMB   int     `db:"mem_limit_mb"` // MB, 0 = unlimited

	// Container runtime fields (services). User is docker's --user ("uid[:gid]"),
	// ShmSizeMB sizes /dev/shm (0 = docker default; also honored on managed
	// tiles), Privileged + Devices ("host[:container[:perms]]" per line) are the
	// host-access escape hatch, RestartPolicy is "" (restart on any exit),
	// "on-failure" or "no" (runtime.NormalizeRestart).
	User          string `db:"user"`
	ShmSizeMB     int    `db:"shm_size_mb"`
	Privileged    bool   `db:"privileged"`
	Devices       string `db:"devices"`
	RestartPolicy string `db:"restart_policy"`

	// WatchPaths filters push auto-deploys: one regex per line matched
	// against changed file paths, "!" prefix = ignore. Empty = any change
	// deploys.
	WatchPaths string `db:"watch_paths"`

	// Image-watch fields (image-source tiles). UpdatePolicy: off | notify |
	// auto. ImageDigest is what the last deploy pulled, LatestDigest the
	// newest the registry watcher has seen, unequal = "new version" badge.
	UpdatePolicy string `db:"update_policy"`
	ImageDigest  string `db:"image_digest"`
	LatestDigest string `db:"latest_digest"`
	// WaitForCI parks push auto-deploys as waiting_ci until the commit's
	// checks pass (git-source tiles).
	WaitForCI bool `db:"wait_for_ci"`

	// Volume-kind fields: which service mounts this volume (single-attach by
	// design, shared writers corrupt data), where, and the docker volume
	// name ("" = derived stackr-vol-<id8>; conversions keep legacy names).
	AttachedTileID string `db:"attached_tile_id"`
	MountPath      string `db:"mount_path"`
	VolumeName     string `db:"volume_name"`
	// MaxSizeMB is a warn-only ceiling (0 = none): docker's local driver has
	// no portable quota, so nothing stops a volume growing past it.
	MaxSizeMB int `db:"max_size_mb"`

	// Placement (docs/plans/32-multi-node-ui.md). HomeNode is the swarm node
	// ID a pinned tile's volume lives on: state, set on first deploy, changed
	// only by the Move action, and required before a pinned tile can deploy.
	// Replicas is config, stateless tiles only. NodeGroup is the
	// `stackr.group` node label a tile is constrained to, "" = anywhere.
	HomeNode  string `db:"home_node"`
	Replicas  int    `db:"replicas"`
	NodeGroup string `db:"node_group"`

	// Proxy/routing extras rendered into the tile's Traefik config.
	BasicAuthUser   string `db:"basic_auth_user"`  // "" = no basic auth
	BasicAuthHash   string `db:"basic_auth_hash"`  // bcrypt hash for BasicAuthUser
	SecHeaders      bool   `db:"sec_headers"`      // HSTS + nosniff + frame-deny preset
	PublishedPorts  string `db:"published_ports"`  // "host:container[/udp]" per line, applied at deploy
	TraefikOverride string `db:"traefik_override"` // raw dynamic config, replaces the generated file

	CreatedAt time.Time `db:"created_at"`
	UpdatedAt time.Time `db:"updated_at"`

	// Database-preset fields (Engine != "" marks a db tile).
	Engine       string `db:"engine"` // a key of databases.Engines, that registry is the list
	DBName       string `db:"db_name"`
	DBUser       string `db:"db_user"`
	DBPassword   string `db:"db_password"`
	ExternalPort int    `db:"external_port"` // 0 = internal only

	// Cron-kind fields: schedule, command override (empty = image CMD), and
	// the last run's outcome recorded directly on the row.
	Cron           string       `db:"cron"`
	Command        string       `db:"command"`
	AllowOverlap   bool         `db:"allow_overlap"`
	TimeoutMinutes int          `db:"timeout_minutes"`
	LastRunAt      sql.NullTime `db:"last_run_at"`
	LastStatus     string       `db:"last_status"`
	LastOutput     string       `db:"last_output"`

	// Scope: where the tile lives. "env" (default, ScopeID ""), "stack" or
	// "org", see managedtiles.Eligible. "server" is not implemented.
	ScopeKind string `db:"scope_kind"`
	ScopeID   string `db:"scope_id"`

	// Endpoint shape published to referencing tiles as STACKR_* outputs.
	// EndpointPortVar names an extra variable to inject ContainerPort under
	// ("" = none); ContainerPort stays canonical.
	EndpointProtocol string `db:"endpoint_protocol"` // http | https | tcp
	EndpointPortVar  string `db:"endpoint_port_var"`

	// SharedNetName is the db-pool overlay a shared managed instance holds,
	// claimed on provision and returned on delete. Read it through
	// SharedNet(), never directly.
	SharedNetName string `db:"shared_net"`
}

Tile is anything on an environment's canvas. Kind picks the lifecycle: "service" (long-running, default) or "cron" (one-shot container on a schedule, k8s CronJob-style). A tile with Engine != "" is a database preset, same service lifecycle plus connection-string handling.

func (*Tile) DockerVolume

func (t *Tile) DockerVolume() string

DockerVolume is the docker named volume backing a volume tile. Keeps the "stackr-" prefix, see StorageVolume for why.

func (*Tile) HasImageUpdate

func (t *Tile) HasImageUpdate() bool

HasImageUpdate: the registry watcher has seen a digest newer than what runs. Empty ImageDigest means the baseline is unknown, not an update.

func (*Tile) IsManaged

func (t *Tile) IsManaged() bool

IsManaged reports whether the tile is a managed instance (an engine preset: postgres, mysql, s3, ...).

func (*Tile) IsVolume

func (t *Tile) IsVolume() bool

IsVolume reports whether the tile is a volume.

func (*Tile) SharedNet

func (t *Tile) SharedNet() string

SharedNet is the docker network a db/s3 instance shares with consumers outside its own environment: one overlay out of the db pool, claimed on provision (infra/netpool). Empty on a tile that is not a shared instance, and on one provisioned before the pool existed until it next deploys. Lives here so the resolver can name it without importing the databases package (which will import the resolver).

type User

type User struct {
	ID           string `db:"id"`
	Email        string `db:"email"`
	PasswordHash string `db:"password_hash"`
	Name         string `db:"name"`
	Role         string `db:"role"`
	Active       bool   `db:"active"`
	// NotifyPrefs overrides the instance notification defaults as a JSON
	// object of {kind: bool}. Empty means "inherit", so raising a default
	// reaches everyone who never expressed a preference.
	NotifyPrefs string `db:"notify_prefs"`
	// GraphPrefs holds the canvas display settings as JSON, mirroring how
	// NotifyPrefs works. Empty means "client defaults".
	GraphPrefs string `db:"graph_prefs"`
	// Theme is light, dark or system. system follows the OS setting.
	Theme string `db:"theme"`
	// AvatarPath is where the uploaded image lives in FileStorage, "" = none
	// (surfaces fall back to initials).
	AvatarPath string    `db:"avatar_path"`
	CreatedAt  time.Time `db:"created_at"`
	UpdatedAt  time.Time `db:"updated_at"`
}

User represents a user account.

type Variable

type Variable struct {
	OwnerKind string    `db:"owner_kind"` // tile | stack | org
	OwnerID   string    `db:"owner_id"`
	Name      string    `db:"name"`
	Value     string    `db:"value"`
	Secret    bool      `db:"secret"`
	CreatedAt time.Time `db:"created_at"`
	UpdatedAt time.Time `db:"updated_at"`
}

Variable is one named value owned by a tile, stack or org. Values may embed ${{ ... }} references to other variables and to managed-resource outputs; they are resolved at deploy time, never at write time. Value is always encrypted at rest, Secret controls masking and read authorization, not storage, so a flag flip can't leak a value that was written in the clear.

type WorkItem

type WorkItem struct {
	ID   string `db:"id"`
	Kind string `db:"kind"`
	// DedupeKey scopes supersession within a kind: a newer item with the same
	// key marks the older queued ones superseded. Empty means never dedupe.
	DedupeKey string `db:"dedupe_key"`
	Payload   string `db:"payload"` // JSON, whatever the handler for this kind reads
	// queued | running | done | error | cancelled | superseded
	Status string `db:"status"`
	// Step is coarse progress and doubles as the resume point for a kind that
	// can resume. Progress is JSON for the byte counters a volume move needs
	// and a restart currently loses.
	Step       string       `db:"step"`
	Progress   string       `db:"progress"`
	Error      string       `db:"error"`
	Attempts   int          `db:"attempts"`
	CreatedAt  time.Time    `db:"created_at"`
	StartedAt  sql.NullTime `db:"started_at"`
	FinishedAt sql.NullTime `db:"finished_at"`
}

WorkItem is one job on the durable queue (docs/plans/33-workqueue.md).

The point of the table rather than a channel is what happens across a restart: a row left running is either requeued or failed on boot, per kind, instead of being lost with the process that held it.

func (WorkItem) Done

func (w WorkItem) Done() bool

Done reports that the item will not run again, whatever the outcome.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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