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) }