Files
archie/internal/domain/storepkg/installed.go
T

256 lines
11 KiB
Go

package storepkg
import (
"context"
"errors"
"fmt"
"strings"
)
var (
ErrNotFound = errors.New("store package not found")
ErrInstalled = errors.New("store package already installed")
ErrRequired = errors.New("store package is required by another installed package")
// ErrAuthorityNotDeclared: the operator asked to accept authority the
// package itself does not declare, which is not an acceptance of that
// package. Acceptance records the package's own declared grants against
// the pinned digest.
ErrAuthorityNotDeclared = errors.New("store package does not declare this authority")
// ErrContributionCollision: the package contributes an entry the org
// resource already holds under an id the package never projected. The
// contribution is refused rather than replacing the operator's entry.
ErrContributionCollision = errors.New("package contribution replaces an entry it does not own")
)
// Installed is one organisation's pinned Archie package.
type Installed struct {
OrgID string
Name string
Reference string
Digest string
Descriptor Descriptor
Layer []byte
UpdatePolicy string
// AcceptedAuthority is the operator's acceptance, recorded against the
// pinned digest. A nil Authority means the operator has not accepted;
// until then the package's authority at use time is nothing.
AcceptedAuthority *Authority
// Pending is an update waiting for an admin to approve widened authority.
// The live pin and AcceptedAuthority stay as they were until then.
Pending *Pin
// PendingAuthority is what the pending update declares.
PendingAuthority *Authority
// Previous is the pin an update or rollback replaced, with the authority
// accepted against it, so a rollback restores both.
Previous *Pin
// PreviousAccepted is the authority accepted against Previous.
PreviousAccepted *Authority
}
// Pin is an immutable package reference at a digest.
type Pin struct {
Reference string
Digest string
}
// Repository owns installed package records and dependency-safe deletion.
type Repository interface {
Install(context.Context, Installed) error
Get(context.Context, string, string) (Installed, error)
List(context.Context, string) ([]Installed, error)
Remove(context.Context, string, string) error
// Accept records the operator's accepted authority against the package's
// currently pinned digest.
Accept(context.Context, string, string, Authority) error
UpdateRecords
}
// Actions a swap of the live pin records in the audit trail.
const (
// ActionUpdate applies a catalogue update, or stages one as pending.
ActionUpdate = "update"
// ActionApproveUpdate applies the pending update and accepts its authority.
ActionApproveUpdate = "approve_update"
// ActionRollback restores the previous pin and its accepted authority.
ActionRollback = "rollback"
)
// UpdateRecords is the part of Repository the update lifecycle writes.
type UpdateRecords interface {
// SetPending records an update waiting for approval, leaving the live pin.
SetPending(ctx context.Context, orgID, name string, pending Pin, declared Authority) error
// Replace swaps the live pin, descriptor, layer and accepted authority for
// next's, keeping the replaced pin and its accepted authority as Previous
// and clearing Pending. action names the operation in the audit trail.
Replace(ctx context.Context, next Installed, action string) error
// SetUpdatePolicy sets whether a package follows the catalogue on its own.
SetUpdatePolicy(ctx context.Context, orgID, name, policy string) error
// ListAutoUpdate names every installed package, in any org, whose policy
// is auto.
ListAutoUpdate(ctx context.Context) ([]OrgPackage, error)
}
// Registry reads a package by immutable OCI manifest digest.
type Registry interface {
Fetch(context.Context, string, string) (Descriptor, []byte, error)
}
// Manager is the State Store surface for installed packages.
type Manager interface {
InstallPackage(context.Context, string, string, string, string) (Installed, error)
GetInstalled(context.Context, string, string) (Installed, error)
ListInstalled(context.Context, string) ([]Installed, error)
RemoveInstalled(context.Context, string, string) error
AcceptPackageAuthority(ctx context.Context, orgID, name string, accepted Authority) (Installed, error)
ListCatalogue(ctx context.Context) (Catalogue, error)
InstallFromCatalogue(ctx context.Context, orgID, name string) (Installed, error)
OrgUpdates
}
// OrgUpdates is the update lifecycle of an installed package in one org.
type OrgUpdates interface {
UpdatePackage(ctx context.Context, orgID, name string) (Installed, error)
ApprovePackageUpdate(ctx context.Context, orgID, name string) (Installed, error)
RollbackPackage(ctx context.Context, orgID, name string) (Installed, error)
SetPackageUpdatePolicy(ctx context.Context, orgID, name, policy string) (Installed, error)
// UpdateAuto runs UpdatePackage for every auto package.
UpdateAuto(ctx context.Context) error
}
// Installations is Manager as a remote caller sees it: the State Store acts
// in the caller's org, so no method names one.
type Installations interface {
InstallPackage(ctx context.Context, name, reference, digest string) (Installed, error)
GetInstalled(ctx context.Context, name string) (Installed, error)
ListInstalled(ctx context.Context) ([]Installed, error)
RemoveInstalled(ctx context.Context, name string) error
AcceptPackageAuthority(ctx context.Context, name string, accepted Authority) (Installed, error)
ListCatalogue(ctx context.Context) (Catalogue, error)
InstallFromCatalogue(ctx context.Context, name string) (Installed, error)
Updates
}
// Updates is OrgUpdates as a remote caller sees it.
type Updates interface {
UpdatePackage(ctx context.Context, name string) (Installed, error)
ApprovePackageUpdate(ctx context.Context, name string) (Installed, error)
RollbackPackage(ctx context.Context, name string) (Installed, error)
SetPackageUpdatePolicy(ctx context.Context, name, policy string) (Installed, error)
}
// Service validates the registry content before persisting an installation.
type Service struct {
Registry Registry
Store Repository
// Projections carries, per descriptor family, the projector that applies
// a package's contribution to the org resource that family projects to,
// and withdraws it again on removal. A family with no entry is stored but
// never projected: installing leaves it unused until a projector lands.
Projections map[string]FamilyProjector
// Catalogue lists the packages an operator can install by name. Nil
// leaves install by explicit reference and digest only.
Catalogue CatalogueSource
}
var _ Manager = Service{}
func (s Service) InstallPackage(ctx context.Context, orgID, name, reference, digest string) (Installed, error) {
return s.Install(ctx, orgID, name, reference, digest)
}
func (s Service) GetInstalled(ctx context.Context, orgID, name string) (Installed, error) {
return s.Store.Get(ctx, orgID, name)
}
func (s Service) ListInstalled(ctx context.Context, orgID string) ([]Installed, error) {
return s.Store.List(ctx, orgID)
}
func (s Service) RemoveInstalled(ctx context.Context, orgID, name string) error {
return s.Remove(ctx, orgID, name)
}
// AcceptPackageAuthority records the operator's acceptance against the pinned
// digest. Only grants the package declares are acceptable, and the accepted
// record may be narrower than the declaration: the record, not the descriptor,
// is the authority the package is later checked against.
func (s Service) AcceptPackageAuthority(ctx context.Context, orgID, name string, accepted Authority) (Installed, error) {
if strings.TrimSpace(orgID) == "" || strings.TrimSpace(name) == "" {
return Installed{}, errors.New("org and name are required")
}
if err := accepted.Validate(); err != nil {
return Installed{}, fmt.Errorf("accepted authority: %w", err)
}
installed, err := s.Store.Get(ctx, orgID, name)
if err != nil {
return Installed{}, fmt.Errorf("installed package %q: %w", name, err)
}
if !installed.Descriptor.Authority.Covers(accepted) {
return Installed{}, fmt.Errorf("package %q: %w", name, ErrAuthorityNotDeclared)
}
if err := s.Store.Accept(ctx, orgID, name, accepted); err != nil {
return Installed{}, err
}
return s.Store.Get(ctx, orgID, name)
}
func (s Service) Install(ctx context.Context, orgID, name, reference, digest string) (Installed, error) {
if strings.TrimSpace(orgID) == "" || strings.TrimSpace(name) == "" || strings.TrimSpace(reference) == "" {
return Installed{}, errors.New("org, name and reference are required")
}
if !digestPattern.MatchString(digest) {
return Installed{}, errors.New("package digest must be a sha256 digest")
}
descriptor, layer, err := s.Registry.Fetch(ctx, reference, digest)
if err != nil {
return Installed{}, fmt.Errorf("fetch package: %w", err)
}
if err := descriptor.Validate(); err != nil {
return Installed{}, fmt.Errorf("validate package: %w", err)
}
for _, required := range descriptor.Requires {
dependency, err := s.Store.Get(ctx, orgID, required.Name)
if err != nil {
return Installed{}, fmt.Errorf("required package %q: %w", required.Name, err)
}
if dependency.Digest != required.Digest {
return Installed{}, fmt.Errorf("required package %q has a different digest", required.Name)
}
}
installed := Installed{
OrgID: orgID, Name: name, Reference: reference, Digest: digest,
Descriptor: descriptor, Layer: layer, UpdatePolicy: PolicyManual,
}
contents, err := s.resolveFamilyContents(descriptor, layer)
if err != nil {
return Installed{}, err
}
if err := s.Store.Install(ctx, installed); err != nil {
return Installed{}, err
}
if err := s.project(ctx, installed, contents); err != nil {
// An install without its projected contributions is not usable. Take
// whatever was projected back out, then the installation itself, so the
// org is left with no package at all rather than a half-usable one.
return Installed{}, errors.Join(err, s.withdraw(ctx, installed), s.Store.Remove(ctx, orgID, name))
}
return installed, nil
}
func (s Service) Remove(ctx context.Context, orgID, name string) error {
if strings.TrimSpace(orgID) == "" || strings.TrimSpace(name) == "" {
return errors.New("org and name are required")
}
installed, err := s.Store.Get(ctx, orgID, name)
if err != nil {
return fmt.Errorf("installed package %q: %w", name, err)
}
// Withdraw before the record goes: the package's contributions must stop
// being usable only once its installation stops being true. A withdrawal
// that fails keeps the package installed and its record kept.
if err := s.withdraw(ctx, installed); err != nil {
return err
}
return s.Store.Remove(ctx, orgID, name)
}