composition

package
v0.2.124 Latest Latest
Warning

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

 Go to latest Published: Aug 15, 2026 License: MIT Imports: 33 Imported by: 0

Documentation

Overview

Package composition verifies immutable module releases and composes them with typed consumer contributions into disposable, namespaced projections.

Index

Constants

View Source 
const (
	DescriptorFileName       = "module.codefly.yaml"
	LockFileName             = "module.codefly.lock"
	PackageManifestFileName  = "module.package.codefly.yaml"
	DescriptorKind           = "composed-module"
	PackageKind              = "module-package"
	PackageSchema            = "codefly/module-package/v2"
	LockSchema               = "codefly/module-lock/v2"
	ProvenanceSchema         = "codefly/module-provenance/v2"
	ArtifactMediaType        = "application/vnd.codefly.module.v2+tar"
	CompositionCatalogName   = ".codefly/composition.catalog.json"
	CompositionInputName     = ".codefly/composition.input.json"
	DevelopOverrideDirectory = ".codefly/develop"
)
View Source 
const (
	ContractComposition    = "composition"
	ContractFrontendPlugin = "frontendPlugin"
	ContractSettings       = "settings"
	ContractPermissions    = "permissions"
	ContractFixtures       = "fixtures"
)

Variables

View Source 
var (
	ErrUnsafeArchive     = errors.New("unsafe module archive")
	ErrDigestMismatch    = errors.New("module artifact digest mismatch")
	ErrSignature         = errors.New("module provenance signature is invalid")
	ErrPackageIdentity   = errors.New("module package identity mismatch")
	ErrMovedTag          = errors.New("module release tag moved")
	ErrContract          = errors.New("module contract negotiation failed")
	ErrCollision         = errors.New("module composition collision")
	ErrCacheVerification = errors.New("module cache verification failed")
)
View Source 
var DefaultSupportedContracts = map[string][]string{
	ContractComposition:    {"2.0"},
	ContractFrontendPlugin: {"1.0"},
	ContractSettings:       {"1.0"},
	ContractPermissions:    {"1.0"},
	ContractFixtures:       {"1.0"},
}

Functions

func CanonicalArchive 

func CanonicalArchive(root string) ([]byte, string, error)

func ClearDevelopOverride 

func ClearDevelopOverride(projectRoot, module string) error

func CompositionDigest 

func CompositionDigest(moduleDir string, descriptor *Descriptor) (string, error)

func DecodeSignature 

func DecodeSignature(encoded []byte) ([]byte, error)

func ExtractArchive 

func ExtractArchive(ctx context.Context, archive []byte, destination string) error

func LockDiff 

func LockDiff(before, after *Lock) (string, error)

func MarshalLock 

func MarshalLock(lock *Lock) ([]byte, error)

func NegotiateContracts 

func NegotiateContracts(descriptor *Descriptor, manifest *PackageManifest, toolVersion string, supported map[string][]string) (map[string]string, error)

func ValidateCatalog 

func ValidateCatalog(catalog *Catalog, expected []CatalogInput) error

func ValidateCollisions 

func ValidateCollisions(claims []Claim, reservedNamespaces []string) error

func ValidateDevelopContracts 

func ValidateDevelopContracts(descriptor *Descriptor, manifest *PackageManifest, lock *Lock, toolVersion string, supported map[string][]string) error

func ValidateLockedContracts 

func ValidateLockedContracts(descriptor *Descriptor, manifest *PackageManifest, lock *Lock, toolVersion string, supported map[string][]string) error

func WriteCanonicalArchive 

func WriteCanonicalArchive(root string, destination io.Writer) error

Types

type ArtifactLock 

type ArtifactLock struct {
	MediaType string `json:"mediaType"`
	Digest    string `json:"digest"`
	Signature string `json:"signature"`
}

type Base 

type Base struct {
	ID      string `yaml:"id" json:"id"`
	Version string `yaml:"version" json:"version"`
}

type Binding 

type Binding struct {
	Plugin string        `yaml:"plugin" json:"plugin"`
	Alias  string        `yaml:"alias" json:"alias"`
	Target BindingTarget `yaml:"target" json:"target"`
}

type BindingTarget 

type BindingTarget struct {
	Module  string `yaml:"module" json:"module"`
	Service string `yaml:"service" json:"service"`
}

type Catalog 

type Catalog struct {
	Schema       string         `json:"schema"`
	Inputs       []CatalogInput `json:"inputs,omitempty"`
	Claims       []Claim        `json:"claims"`
	Dependencies []string       `json:"dependencies,omitempty"`
}

func LoadCatalog 

func LoadCatalog(projection string) (*Catalog, error)

type CatalogInput 

type CatalogInput struct {
	Kind     string `json:"kind"`
	Path     string `json:"path"`
	Identity string `json:"identity"`
	Digest   string `json:"digest"`
}

func LoadContributionInputs 

func LoadContributionInputs(moduleDir string, descriptor *Descriptor) ([]CatalogInput, error)

type Claim 

type Claim struct {
	Kind  CollisionKind `yaml:"kind" json:"kind"`
	Key   string        `yaml:"key" json:"key"`
	Owner string        `yaml:"owner" json:"owner"`
}

type CollisionKind 

type CollisionKind string
const (
	CollisionRoute          CollisionKind = "route"
	CollisionPermission     CollisionKind = "permission"
	CollisionSettingsField  CollisionKind = "settings-field"
	CollisionServiceBinding CollisionKind = "service-binding"
	CollisionMigration      CollisionKind = "migration"
	CollisionPackage        CollisionKind = "package"
	CollisionTopology       CollisionKind = "topology"
)

type CommandRunner 

type CommandRunner interface {
	Run(context.Context, CommandSpec) error
}

type CommandSpec 

type CommandSpec struct {
	Name      string
	Command   []string
	Directory string
	Env       []string
}

type CompositionInput 

type CompositionInput struct {
	Schema       string            `json:"schema"`
	Module       string            `json:"module"`
	Package      string            `json:"package"`
	Version      string            `json:"version"`
	ConsumerRoot string            `json:"consumerRoot"`
	Projection   string            `json:"projection"`
	Contracts    map[string]string `json:"contracts"`
	Descriptor   *Descriptor       `json:"descriptor"`
	Namespace    *Namespace        `json:"namespace"`
}

type ContractChange 

type ContractChange struct {
	Contract      string `json:"contract"`
	Before        string `json:"before,omitempty"`
	After         string `json:"after"`
	Compatibility string `json:"compatibility"`
}

type Contributions 

type Contributions struct {
	Frontend    []FrontendContribution    `yaml:"frontend,omitempty" json:"frontend,omitempty"`
	Settings    []SettingsContribution    `yaml:"settings,omitempty" json:"settings,omitempty"`
	Permissions []PathContribution        `yaml:"permissions,omitempty" json:"permissions,omitempty"`
	Fixtures    []PathContribution        `yaml:"fixtures,omitempty" json:"fixtures,omitempty"`
	Tests       []IntegrationContribution `yaml:"tests,omitempty" json:"tests,omitempty"`
}

type Delta 

type Delta struct {
	Added   []string `json:"added,omitempty"`
	Removed []string `json:"removed,omitempty"`
}

type Descriptor 

type Descriptor struct {
	Kind          string        `yaml:"kind" json:"kind"`
	Name          string        `yaml:"name" json:"name"`
	Base          Base          `yaml:"base" json:"base"`
	Services      Services      `yaml:"services,omitempty" json:"services,omitempty"`
	Contributions Contributions `yaml:"contributions,omitempty" json:"contributions,omitempty"`
	Bindings      []Binding     `yaml:"bindings,omitempty" json:"bindings,omitempty"`
}

func LoadDescriptor 

func LoadDescriptor(moduleDir string) (*Descriptor, error)

func (*Descriptor) Validate 

func (descriptor *Descriptor) Validate() error

type DevelopOverride 

type DevelopOverride struct {
	Schema    string            `json:"schema"`
	Module    string            `json:"module"`
	Package   string            `json:"package"`
	Source    string            `json:"source"`
	Contracts map[string]string `json:"contracts"`
}

func LoadDevelopOverride 

func LoadDevelopOverride(projectRoot, module string) (*DevelopOverride, error)

func SetDevelopOverride 

func SetDevelopOverride(ctx context.Context, projectRoot, moduleDir, source string) (*DevelopOverride, error)

type DoctorCheck 

type DoctorCheck struct {
	Name   string           `json:"name"`
	Status ValidationStatus `json:"status"`
	Detail string           `json:"detail,omitempty"`
}

type Engine 

type Engine struct {
	ProjectRoot        string
	ToolVersion        string
	Resolver           Resolver
	Trust              TrustPolicy
	Materializer       *Materializer
	Renderer           Renderer
	SupportedContracts map[string][]string
}

func NewEngine 

func NewEngine(projectRoot string, resolver Resolver, trust TrustPolicy) *Engine

func (*Engine) Doctor 

func (engine *Engine) Doctor(ctx context.Context, moduleDir string, ci bool) ([]DoctorCheck, error)

func (*Engine) Materialize 

func (engine *Engine) Materialize(ctx context.Context, moduleDir string, options MaterializeOptions) (*Materialization, error)

func (*Engine) Rollback 

func (engine *Engine) Rollback(ctx context.Context, moduleDir string, priorLock []byte) (*Materialization, error)

func (*Engine) Source 

func (engine *Engine) Source(ctx context.Context, moduleDir string, options MaterializeOptions) (string, error)

func (*Engine) Update 

func (engine *Engine) Update(ctx context.Context, moduleDir, targetVersion string, apply bool) (*UpdateResult, error)

type EntryPoint 

type EntryPoint struct {
	Name    string   `yaml:"name" json:"name"`
	Command []string `yaml:"command" json:"command"`
}

type ExecCommandRunner 

type ExecCommandRunner struct{}

func (ExecCommandRunner) Run 

func (ExecCommandRunner) Run(ctx context.Context, spec CommandSpec) error

type FrontendContribution 

type FrontendContribution struct {
	Path   string `yaml:"path" json:"path"`
	Export string `yaml:"export" json:"export"`
}

type GitHubPackage 

type GitHubPackage struct {
	Owner           string
	RepositoryName  string
	RepositoryURL   string
	ArtifactAsset   string
	ProvenanceAsset string
	SignatureAsset  string
}

type GitHubResolver 

type GitHubResolver struct {
	Client           *github.Client
	DownloadClient   *http.Client
	Packages         map[string]GitHubPackage
	MaxArtifactBytes int64
	// contains filtered or unexported fields
}

func NewGitHubResolver 

func NewGitHubResolver(client *github.Client, downloadClient *http.Client, packages map[string]GitHubPackage) *GitHubResolver

func (*GitHubResolver) Fetch 

func (resolver *GitHubResolver) Fetch(ctx context.Context, lock *Lock) (*Release, error)

func (*GitHubResolver) Resolve 

func (resolver *GitHubResolver) Resolve(ctx context.Context, request ResolveRequest) (*Release, error)

type IntegrationContribution 

type IntegrationContribution struct {
	Path    string   `yaml:"path" json:"path"`
	Command []string `yaml:"command" json:"command"`
}

type Lock 

type Lock struct {
	Schema            string            `json:"schema"`
	Module            string            `json:"module"`
	Package           string            `json:"package"`
	Version           string            `json:"version"`
	Source            SourceLock        `json:"source"`
	Artifact          ArtifactLock      `json:"artifact"`
	Contracts         map[string]string `json:"contracts"`
	CompositionDigest string            `json:"compositionDigest"`
}

func LoadLock 

func LoadLock(moduleDir string) (*Lock, error)

func ParseLock 

func ParseLock(data []byte) (*Lock, error)

func (*Lock) Validate 

func (lock *Lock) Validate() error

type Materialization 

type Materialization struct {
	Source     string
	Projection string
	Namespace  *Namespace
}

type MaterializeOptions 

type MaterializeOptions struct {
	Namespace string
	LockPath  string
	CI        bool
}

type Materializer 

type Materializer struct {
	Root             string
	MaxEntries       int
	MaxExpandedBytes int64
}

func NewMaterializer 

func NewMaterializer(projectRoot string) *Materializer

func (*Materializer) CachePath 

func (materializer *Materializer) CachePath(digest string) (string, error)

func (*Materializer) Cached 

func (materializer *Materializer) Cached(lock *Lock) (string, error)

func (*Materializer) Materialize 

func (materializer *Materializer) Materialize(ctx context.Context, release *VerifiedRelease) (string, error)

type Namespace 

type Namespace struct {
	Name             string `json:"name"`
	LockPath         string `json:"lockPath"`
	Digest           string `json:"digest"`
	ProjectionDir    string `json:"projectionDir"`
	CacheDir         string `json:"cacheDir"`
	BuildDir         string `json:"buildDir"`
	NextJSDir        string `json:"nextJSDir"`
	RuntimeConfigDir string `json:"runtimeConfigDir"`
	ContainerSuffix  string `json:"containerSuffix"`
	PortSeed         uint32 `json:"portSeed"`
}

func ResolveNamespace 

func ResolveNamespace(projectRoot, moduleDir, name, lockPath string, lock *Lock) (*Namespace, error)

func (*Namespace) Prepare 

func (namespace *Namespace) Prepare() error

type PackageCommand 

type PackageCommand struct {
	Name             string   `yaml:"name" json:"name"`
	Command          []string `yaml:"command" json:"command"`
	WorkingDirectory string   `yaml:"working-directory,omitempty" json:"workingDirectory,omitempty"`
}

type PackageManifest 

type PackageManifest struct {
	Kind                  string             `yaml:"kind" json:"kind"`
	Schema                string             `yaml:"schema" json:"schema"`
	ID                    string             `yaml:"id" json:"id"`
	Version               string             `yaml:"version" json:"version"`
	MinimumCodeflyVersion string             `yaml:"minimum-codefly-version" json:"minimumCodeflyVersion"`
	ArtifactRoots         []string           `yaml:"artifact-roots" json:"artifactRoots"`
	EntryPoints           []EntryPoint       `yaml:"entry-points,omitempty" json:"entryPoints,omitempty"`
	Services              []ProvidedService  `yaml:"services,omitempty" json:"services,omitempty"`
	Contracts             map[string]string  `yaml:"contracts" json:"contracts"`
	Generators            []PackageCommand   `yaml:"generators,omitempty" json:"generators,omitempty"`
	Conformance           []PackageCommand   `yaml:"conformance,omitempty" json:"conformance,omitempty"`
	Migrations            []PackageMigration `yaml:"migrations,omitempty" json:"migrations,omitempty"`
	BreakingChanges       []string           `yaml:"breaking-changes,omitempty" json:"breakingChanges,omitempty"`
	ReservedNamespaces    []string           `yaml:"reserved-namespaces,omitempty" json:"reservedNamespaces,omitempty"`
	Claims                []Claim            `yaml:"claims,omitempty" json:"claims,omitempty"`
}

func LoadPackageManifest 

func LoadPackageManifest(root string) (*PackageManifest, error)

func (*PackageManifest) Validate 

func (manifest *PackageManifest) Validate() error

type PackageMigration 

type PackageMigration struct {
	ID       string `yaml:"id" json:"id"`
	From     string `yaml:"from" json:"from"`
	Breaking bool   `yaml:"breaking,omitempty" json:"breaking,omitempty"`
}

type PathContribution 

type PathContribution struct {
	Path string `yaml:"path" json:"path"`
}

type Provenance 

type Provenance struct {
	Schema            string `json:"schema"`
	Package           string `json:"package"`
	Version           string `json:"version"`
	Repository        string `json:"repository"`
	Ref               string `json:"ref"`
	Commit            string `json:"commit"`
	ArtifactMediaType string `json:"artifactMediaType"`
	ArtifactDigest    string `json:"artifactDigest"`
	SignatureIdentity string `json:"signatureIdentity"`
}

func ParseProvenance 

func ParseProvenance(data []byte) (*Provenance, error)

type ProvidedService 

type ProvidedService struct {
	Name      string   `yaml:"name" json:"name"`
	Endpoints []string `yaml:"endpoints,omitempty" json:"endpoints,omitempty"`
}

type Release 

type Release struct {
	Repository string
	Ref        string
	Commit     string
	Artifact   []byte
	Provenance []byte
	Signature  []byte
}

type Renderer 

type Renderer struct {
	Runner CommandRunner
}

func (Renderer) Render 

func (renderer Renderer) Render(ctx context.Context, base, moduleDir, projection string, namespace *Namespace, descriptor *Descriptor, manifest *PackageManifest, contracts map[string]string, inputs []CatalogInput) (*Catalog, []ValidationResult, error)

type ResolveRequest 

type ResolveRequest struct {
	Package string
	Version string
	Current *Lock
}

type Resolver 

type Resolver interface {
	Resolve(context.Context, ResolveRequest) (*Release, error)
	Fetch(context.Context, *Lock) (*Release, error)
}

type SemanticReport 

type SemanticReport struct {
	Schema          string                  `json:"schema"`
	Module          string                  `json:"module"`
	Package         string                  `json:"package"`
	BeforeVersion   string                  `json:"beforeVersion,omitempty"`
	AfterVersion    string                  `json:"afterVersion"`
	Contracts       []ContractChange        `json:"contracts"`
	Services        Delta                   `json:"services"`
	Endpoints       Delta                   `json:"endpoints"`
	Dependencies    Delta                   `json:"dependencies"`
	Migrations      Delta                   `json:"migrations"`
	BreakingChanges []string                `json:"breakingChanges,omitempty"`
	Deltas          map[CollisionKind]Delta `json:"deltas"`
	Validations     []ValidationResult      `json:"validations"`
	BlockedReasons  []string                `json:"blockedReasons,omitempty"`
	LockDiff        string                  `json:"lockDiff"`
}

func (*SemanticReport) JSON 

func (report *SemanticReport) JSON() ([]byte, error)

func (*SemanticReport) String 

func (report *SemanticReport) String() string

type Services 

type Services struct {
	Include []string `yaml:"include,omitempty" json:"include,omitempty"`
}

type SettingsContribution 

type SettingsContribution struct {
	Path    string `yaml:"path" json:"path"`
	Message string `yaml:"message" json:"message"`
}

type SourceLock 

type SourceLock struct {
	Repository string `json:"repository"`
	Ref        string `json:"ref"`
	Commit     string `json:"commit"`
}

type TrustPolicy 

type TrustPolicy struct {
	Repositories map[string]string
	Signers      map[string]ed25519.PublicKey
}

type UpdateResult 

type UpdateResult struct {
	Lock       *Lock
	Projection string
	Namespace  *Namespace
	Report     *SemanticReport
	Applied    bool
}

type V1BaseManifest 

type V1BaseManifest struct {
	Note      string            `json:"note,omitempty"`
	FileCount int               `json:"fileCount"`
	Files     map[string]string `json:"files"`
}

type V1BaseSource 

type V1BaseSource struct {
	Schema       string `json:"schema"`
	Repository   string `json:"repository"`
	Ref          string `json:"ref"`
	Commit       string `json:"commit"`
	Subdirectory string `json:"subdirectory"`
}

type V1Bridge 

type V1Bridge struct {
	Source   *V1BaseSource
	Manifest *V1BaseManifest
}

func LoadV1Bridge 

func LoadV1Bridge(moduleDir string) (*V1Bridge, error)

type V1MigrationClassification 

type V1MigrationClassification string
const (
	V1MigrationDrop         V1MigrationClassification = "drop"
	V1MigrationUpstream     V1MigrationClassification = "upstream"
	V1MigrationContribution V1MigrationClassification = "contribution"
	V1MigrationGenerated    V1MigrationClassification = "generated"
	V1MigrationBlocked      V1MigrationClassification = "blocked"
)

type V1MigrationEntry 

type V1MigrationEntry struct {
	Path           string                    `json:"path"`
	OldDigest      string                    `json:"oldDigest"`
	ConsumerDigest string                    `json:"consumerDigest,omitempty"`
	NewDigest      string                    `json:"newDigest,omitempty"`
	Classification V1MigrationClassification `json:"classification"`
}

func PlanV1Migration 

func PlanV1Migration(moduleDir, newBaseDir string, bridge *V1Bridge, ownership map[string]V1MigrationClassification) ([]V1MigrationEntry, error)

type ValidationResult 

type ValidationResult struct {
	Name   string           `json:"name"`
	Kind   string           `json:"kind"`
	Status ValidationStatus `json:"status"`
	Detail string           `json:"detail,omitempty"`
}

type ValidationStatus 

type ValidationStatus string
const (
	ValidationPassed ValidationStatus = "passed"
	ValidationFailed ValidationStatus = "failed"
)

type VerifiedRelease 

type VerifiedRelease struct {
	// contains filtered or unexported fields
}

func VerifyLockedRelease 

func VerifyLockedRelease(release *Release, lock *Lock, trust TrustPolicy) (*VerifiedRelease, error)

func VerifyRelease 

func VerifyRelease(release *Release, expectedPackage, expectedVersion string, trust TrustPolicy) (*VerifiedRelease, error)

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.