v2models

README

Why are references always pointers?

Gorm lets us use structs to represent associations--and we can do so with pointer or value types (link).

So why do we always use pointers, causing us to have to do nil checks in a bunch of places?

The reason why has to do with returning data to the client. When we load something from the database, we load associations too, but only one layer deep.

If we used values for associations, associations at the second/third/fourth layer etc would all appear to be loaded, as zero values. Up at the controller layer, we'd end up returning a bunch of nonsense data to clients.

As a concrete example, suppose you requested a ChartRelease, and the model and controllers all represented associations with value types:

{
  // Fields at this level would be present because this is the top level
  "environmentInfo": {
    // Fields at this level would be present because this is the first layer of associations
    "defaultClusterInfo": {
      // Fields at this level would be EMPTY because this is the second layer of associations, and it doesn't get loaded
    },
    "templateEnvironmentInfo": {
      // Fields at this level would be EMPTY because this is the second layer of associations, and it doesn't get loaded
      "defaultClusterInfo": {
        // Fields at this level would be EMPTY because this is the third layer of associations, and it doesn't get loaded
      }
    }
  }
}

The above is true even if we use omitempty, because structs in Go don't themselves have an empty value.

The solution is to use pointer types for associations at the controller layer, so omitempty works. That gives us this:

{
  // Fields at this level would be present because this is the top level
  "environmentInfo": {
    // Fields at this level would be present because this is the first layer of associations
    // `defaultClusterInfo` and `templateEnvironmentInfo` were nil and so weren't included here
  }
}

If we want to use pointer types for associations at the controller, it is very helpful to use them at the model too. This means that a lot of functions inside the model need to handle pointer types.

Internal stores

There's a concept here of an "internal" store versus a normal store that gets exported. Here's the differences:

internalModelStore	ModelStore
Singleton (kept in package-level vars)	Instanced
Stateless	Stateful (keeps a database reference as state)
Methods require a database reference	Methods use database reference from state
Methods accept full model type as queries	Methods accept selector strings as queries

(This table references model stores but event stores follow the same principle)

The basic idea is that internal stores can all call each other, even passing transaction references when necessary, while the exported stores are encapsulated things suitable for a controller to carry around.

Documentation

Index

• func WithRollbackStoreSet[T any](storeSet *StoreSet, f func(*StoreSet) (T, error)) (T, error)
• type AppVersion
  • func (c AppVersion) TableName() string
• type Changeset
  • func (c Changeset) TableName() string
• type ChangesetEventStore
  • func (s *ChangesetEventStore) Apply(selectors []string, user *auth.User) ([]Changeset, error)
  • func (s *ChangesetEventStore) Plan(changesets []Changeset, user *auth.User) ([]Changeset, error)
  • func (s *ChangesetEventStore) PlanAndApply(changesets []Changeset, user *auth.User) ([]Changeset, error)
• type Chart
  • func (c Chart) TableName() string
• type ChartRelease
  • func (c ChartRelease) TableName() string
• type ChartReleaseVersion
• type ChartVersion
  • func (c ChartVersion) TableName() string
• type Cluster
  • func (c Cluster) TableName() string
• type Environment
  • func (e Environment) TableName() string
• type Model
• type ModelStore
  • func (s ModelStore[M]) Create(model M, user *auth.User) (M, bool, error)
  • func (s ModelStore[M]) Delete(selector string, user *auth.User) (M, error)
  • func (s ModelStore[M]) Edit(selector string, editsToMake M, user *auth.User) (M, error)
  • func (s ModelStore[M]) Get(selector string) (M, error)
  • func (s ModelStore[M]) GetOtherValidSelectors(selector string) ([]string, error)
  • func (s ModelStore[M]) ListAllMatching(filter M, limit int) ([]M, error)
• type StoreSet
  • func NewStoreSet(db *gorm.DB) *StoreSet

Functions

func WithRollbackStoreSet

func WithRollbackStoreSet[T any](storeSet *StoreSet, f func(*StoreSet) (T, error)) (T, error)

WithRollbackStoreSet is a last-resort for achieving reasonable error behavior outside the model. Functions inside the model will reasonably rollback when they encounter an error. This function is intended to be used when a controller composes model functions together and needs to rollback the entire composition when an error occurs in any of them.

Types

type AppVersion

type AppVersion struct {
	gorm.Model
	Chart              *Chart
	ChartID            uint   `gorm:"not null: default:null"`
	AppVersion         string `gorm:"not null: default:null"`
	GitCommit          string
	GitBranch          string
	Description        string
	ParentAppVersion   *AppVersion
	ParentAppVersionID *uint
}

func (AppVersion) TableName

func (c AppVersion) TableName() string

type Changeset

type Changeset struct {
	gorm.Model
	ChartRelease   *ChartRelease
	ChartReleaseID uint

	From             ChartReleaseVersion `gorm:"embedded;embeddedPrefix:from_"`
	To               ChartReleaseVersion `gorm:"embedded;embeddedPrefix:to_"`
	AppliedAt        *time.Time
	SupersededAt     *time.Time
	NewAppVersions   []*AppVersion   `gorm:"many2many:v2_changeset_new_app_versions;constraint:OnDelete:CASCADE,OnUpdate:CASCADE;"`
	NewChartVersions []*ChartVersion `gorm:"many2many:v2_changeset_new_chart_versions;constraint:OnDelete:CASCADE,OnUpdate:CASCADE;"`
}

func (Changeset) TableName

func (c Changeset) TableName() string

type ChangesetEventStore

type ChangesetEventStore struct {
	*ModelStore[Changeset]
	// contains filtered or unexported fields
}

func (*ChangesetEventStore) Apply

func (s *ChangesetEventStore) Apply(selectors []string, user *auth.User) ([]Changeset, error)

func (*ChangesetEventStore) Plan

func (s *ChangesetEventStore) Plan(changesets []Changeset, user *auth.User) ([]Changeset, error)

func (*ChangesetEventStore) PlanAndApply

func (s *ChangesetEventStore) PlanAndApply(changesets []Changeset, user *auth.User) ([]Changeset, error)

type Chart

type Chart struct {
	gorm.Model
	Name string `gorm:"not null; default:null; unique"`
	// Mutable
	ChartRepo             *string `gorm:"not null; default:null"`
	AppImageGitRepo       *string
	AppImageGitMainBranch *string
	ChartExposesEndpoint  *bool
	DefaultSubdomain      *string
	DefaultProtocol       *string
	DefaultPort           *uint
}

func (Chart) TableName

func (c Chart) TableName() string

type ChartRelease

type ChartRelease struct {
	gorm.Model
	Chart           *Chart
	ChartID         uint
	Cluster         *Cluster
	ClusterID       *uint
	DestinationType string
	Environment     *Environment
	EnvironmentID   *uint
	Name            string `gorm:"not null; default:null; unique"`
	Namespace       string
	ChartReleaseVersion
	Subdomain *string
	Protocol  *string
	Port      *uint
}

func (ChartRelease) TableName

func (c ChartRelease) TableName() string

type ChartReleaseVersion

type ChartReleaseVersion struct {
	ResolvedAt *time.Time

	AppVersionResolver *string
	AppVersionExact    *string
	AppVersionBranch   *string
	AppVersionCommit   *string
	AppVersion         *AppVersion
	AppVersionID       *uint

	ChartVersionResolver *string
	ChartVersionExact    *string
	ChartVersion         *ChartVersion
	ChartVersionID       *uint

	HelmfileRef *string
}

ChartReleaseVersion isn't stored in the database on its own, it is included as a part of a ChartRelease or Changeset. It has especially strict validation that requires it being fully loaded from the database. The resolve method will help "load" it fully from the database so it can survive validation.

type ChartVersion

type ChartVersion struct {
	gorm.Model
	Chart                *Chart
	ChartID              uint   `gorm:"not null: default:null"`
	ChartVersion         string `gorm:"not null: default:null"`
	Description          string
	ParentChartVersion   *ChartVersion
	ParentChartVersionID *uint
}

func (ChartVersion) TableName

func (c ChartVersion) TableName() string

type Cluster

type Cluster struct {
	gorm.Model
	Name              string `gorm:"not null; default:null; unique"`
	Provider          string `gorm:"not null; default:null"`
	GoogleProject     string
	AzureSubscription string
	// Mutable
	Base                *string `gorm:"not null; default:null"`
	Address             *string `gorm:"not null; default:null"`
	RequiresSuitability *bool   `gorm:"not null; default:null"`
}

func (Cluster) TableName

func (c Cluster) TableName() string

type Environment

type Environment struct {
	gorm.Model
	Base                      string
	Lifecycle                 string `gorm:"not null; default:null"`
	Name                      string `gorm:"not null; default:null; unique"`
	TemplateEnvironment       *Environment
	TemplateEnvironmentID     *uint
	ValuesName                string
	ChartReleasesFromTemplate *bool
	// Mutable
	DefaultCluster      *Cluster
	DefaultClusterID    *uint
	DefaultNamespace    *string
	Owner               *string `gorm:"not null;default:null"`
	RequiresSuitability *bool
	BaseDomain          *string
	NamePrefixesDomain  *bool
}

func (Environment) TableName

func (e Environment) TableName() string

type Model

type Model interface {
	TableName() string
}

type ModelStore

type ModelStore[M Model] struct {
	// contains filtered or unexported fields
}

func (ModelStore[M]) Create

func (s ModelStore[M]) Create(model M, user *auth.User) (M, bool, error)

func (ModelStore[M]) Delete

func (s ModelStore[M]) Delete(selector string, user *auth.User) (M, error)

func (ModelStore[M]) Edit

func (s ModelStore[M]) Edit(selector string, editsToMake M, user *auth.User) (M, error)

func (ModelStore[M]) Get

func (s ModelStore[M]) Get(selector string) (M, error)

func (ModelStore[M]) GetOtherValidSelectors

func (s ModelStore[M]) GetOtherValidSelectors(selector string) ([]string, error)

GetOtherValidSelectors is basically just a human debug method. Different model types have different selectors to try to make it easier to refer to them than by having to directly query them and use their numeric ID primary key. Under the hood, models are already required to be able to generate selectors from an entry for uniqueness-validation purposes, so this is a simple method that uses that existing code to translate one selector for an existing entry into all possible selectors that would match.

func (ModelStore[M]) ListAllMatching

func (s ModelStore[M]) ListAllMatching(filter M, limit int) ([]M, error)

type StoreSet

type StoreSet struct {
	ClusterStore      *ModelStore[Cluster]
	EnvironmentStore  *ModelStore[Environment]
	ChartStore        *ModelStore[Chart]
	ChartVersionStore *ModelStore[ChartVersion]
	AppVersionStore   *ModelStore[AppVersion]
	ChartReleaseStore *ModelStore[ChartRelease]

	ChangesetEventStore *ChangesetEventStore
	// contains filtered or unexported fields
}

func NewStoreSet

func NewStoreSet(db *gorm.DB) *StoreSet