artifact

package
v0.6.3 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Index

Constants

View Source
const CurrentSchemaVersion = "v0.1.18"

CurrentSchemaVersion defines the current imdl schema version stamped on normalized artifacts.

Variables

View Source
var ErrArtifactNotFound = errors.New("artifact not found")

ErrArtifactNotFound indicates that the requested artifact ID does not exist in the store.

Functions

func Delete

func Delete(id string) error

Delete removes an artifact by ID from the default store.

func ResolveSchema

func ResolveSchema(schemaType string, category Category, stage Stage, rawPayload []byte) (reflect.Type, string, Category, Stage)

ResolveSchema resolves the target reflect.Type, schemaType name, Category, and Stage for a payload.

func ValidateTypeGuard

func ValidateTypeGuard(storedSchemaType string, requestedType reflect.Type) error

ValidateTypeGuard verifies that the requested Go type matches the stored artifact schemaType.

Types

type Artifact

type Artifact[T any] struct {
	Id               string                      `json:"id" example:"art-d0g535l40272926020g0"`
	Name             string                      `json:"name" validate:"required" example:"ecommerce-prod-plan"`
	Description      string                      `json:"description,omitempty" example:"Refined migration artifact"`
	Version          string                      `json:"version,omitempty" example:"1.0.0"`
	Category         Category                    `json:"category" validate:"required" enums:"infra,software,data" example:"infra"`
	Stage            Stage                       `json:"stage" validate:"required" enums:"source,planning,target" example:"planning"`
	SchemaType       string                      `json:"schemaType,omitempty" example:"OnpremInfra"`
	SchemaVersion    string                      `json:"schemaVersion,omitempty" example:"v0.1.18"`
	Lineage          lineage.MigrationLineage    `json:"lineage"`
	Payload          T                           `json:"payload" validate:"required"`
	ConversionReport *modelconv.ConversionReport `json:"conversionReport,omitempty"`
	CreateTime       string                      `json:"createTime" example:"2026-10-23T12:00:00Z"`
	UpdateTime       string                      `json:"updateTime,omitempty" example:"2026-10-23T12:05:00Z"`
}

Artifact is a generic envelope for any migration payload type T.

func CastPayload

func CastPayload[T any](raw *RawArtifact) (*Artifact[T], error)

CastPayload validates schemaType compatibility and upcasts a RawArtifact into a typed Artifact[T].

func CreateAs

func CreateAs[T any](meta CreateMetadata, payload T) (*Artifact[T], error)

CreateAs stores a typed payload T as a normalized Artifact and returns the typed Artifact[T].

func CreateAsInStore

func CreateAsInStore[T any](st *Store, meta CreateMetadata, payload T) (*Artifact[T], error)

CreateAsInStore stores a typed payload T in the specified store and returns the typed Artifact[T].

func GetAs

func GetAs[T any](id string) (*Artifact[T], error)

GetAs retrieves an artifact by ID and casts/upcasts its payload into target struct T using reflect.

func GetAsFromStore

func GetAsFromStore[T any](st *Store, id string) (*Artifact[T], error)

GetAsFromStore retrieves an artifact by ID from the given store and casts/upcasts its payload into T.

type Category

type Category string

Category classifies the domain of a migration artifact.

const (
	CategoryInfra    Category = "infra"
	CategorySoftware Category = "software"
	CategoryData     Category = "data"
)

func (Category) IsValid

func (c Category) IsValid() bool

IsValid checks whether Category is one of the supported domain categories.

type CreateMetadata

type CreateMetadata struct {
	Id            string                   `json:"id,omitempty"`
	Name          string                   `json:"name"`
	Description   string                   `json:"description,omitempty"`
	Version       string                   `json:"version,omitempty"`
	Category      Category                 `json:"category,omitempty"`
	Stage         Stage                    `json:"stage,omitempty"`
	SchemaType    string                   `json:"schemaType,omitempty"`
	ParentId      string                   `json:"parentId,omitempty"`
	SourceGroupId string                   `json:"sourceGroupId,omitempty"`
	Lineage       lineage.MigrationLineage `json:"lineage,omitempty"`
}

CreateMetadata holds metadata fields used when creating a typed artifact via CreateAs[T].

type CreateReq

type CreateReq struct {
	Id            string                   `json:"id,omitempty" example:"art-custom-01"`
	Name          string                   `json:"name" validate:"required" example:"ecommerce-source-infra"`
	Description   string                   `json:"description,omitempty" example:"Extracted source infrastructure"`
	Version       string                   `json:"version,omitempty" example:"1.0.0"`
	Category      Category                 `json:"category" validate:"required" enums:"infra,software,data" example:"infra"`
	Stage         Stage                    `json:"stage" validate:"required" enums:"source,planning,target" example:"source"`
	SchemaType    string                   `json:"schemaType,omitempty" example:"OnpremInfra"`
	ParentId      string                   `json:"parentId,omitempty" example:"art-src-01"`
	SourceGroupId string                   `json:"sourceGroupId,omitempty" example:"sg-ecommerce-prod"`
	Lineage       lineage.MigrationLineage `json:"lineage,omitempty"`
	Payload       json.RawMessage          `json:"payload" validate:"required"`

	// Legacy envelope compatibility fields accepted on import and normalized automatically.
	LegacyModelType     string          `json:"modelType,omitempty" swaggerignore:"true"`
	LegacyOnpremModel   json.RawMessage `json:"onpremiseInfraModel,omitempty" swaggerignore:"true"`
	LegacyCloudModel    json.RawMessage `json:"cloudInfraModel,omitempty" swaggerignore:"true"`
	LegacyRecInfraModel json.RawMessage `json:"recommendedInfraModel,omitempty" swaggerignore:"true"`
}

CreateReq represents the JSON request body for POST /beetle/artifacts.

func (*CreateReq) Normalize

func (r *CreateReq) Normalize() error

Normalize fills missing Category, Stage, SchemaType, and Payload from legacy fields when provided.

type Filter

type Filter struct {
	Category      Category `json:"category,omitempty"`
	Stage         Stage    `json:"stage,omitempty"`
	SchemaType    string   `json:"schemaType,omitempty"`
	SourceGroupId string   `json:"sourceGroupId,omitempty"`
}

Filter defines query parameters for listing artifacts via GET /beetle/artifacts.

type LineageGraph

type LineageGraph struct {
	ArtifactId       string                   `json:"artifactId"`
	SourceGroupId    string                   `json:"sourceGroupId,omitempty"`
	Lineage          lineage.MigrationLineage `json:"lineage"`
	SourceArtifact   *RawArtifact             `json:"sourceArtifact,omitempty"`
	PlanningArtifact *RawArtifact             `json:"planningArtifact,omitempty"`
	TargetArtifact   *RawArtifact             `json:"targetArtifact,omitempty"`
	GroupArtifacts   []RawArtifact            `json:"groupArtifacts,omitempty"`
}

LineageGraph represents the derivation chain and group-related artifacts for GET /beetle/artifacts/:id/lineage.

func GetLineageGraph

func GetLineageGraph(id string) (*LineageGraph, error)

GetLineageGraph builds the full derivation chain and group-related artifacts for an artifact ID.

func GetLineageGraphFromStore

func GetLineageGraphFromStore(st *Store, id string) (*LineageGraph, error)

GetLineageGraphFromStore builds the full derivation chain from the given store.

type ListResponse

type ListResponse struct {
	Count     int           `json:"count" example:"2"`
	Artifacts []RawArtifact `json:"artifacts"`
}

ListResponse wraps a slice of artifacts for consistent REST API responses.

type RawArtifact

type RawArtifact = Artifact[json.RawMessage]

RawArtifact is the untyped storage and wire representation of an Artifact.

func Create

func Create(req CreateReq) (*RawArtifact, error)

Create validates, upcasts, and persists a new artifact in the default store.

func CreateInStore

func CreateInStore(st *Store, req CreateReq) (*RawArtifact, error)

CreateInStore validates, upcasts, and persists a new artifact in the given store.

func Get

func Get(id string) (*RawArtifact, error)

Get retrieves an artifact by ID and ensures its payload is upcasted to the latest registered schema.

func GetFromStore

func GetFromStore(st *Store, id string) (*RawArtifact, error)

GetFromStore retrieves an artifact by ID from the given store and ensures latest schema normalization.

func List

func List(filter Filter) ([]RawArtifact, error)

List returns all artifacts matching Filter from the default store.

func ListFromStore

func ListFromStore(st *Store, filter Filter) ([]RawArtifact, error)

ListFromStore returns all artifacts matching Filter from the given store.

func Update

func Update(id string, req UpdateReq) (*RawArtifact, error)

Update modifies an existing artifact in-place, upcasts the updated payload, and persists it atomically.

func UpdateInStore

func UpdateInStore(st *Store, id string, req UpdateReq) (*RawArtifact, error)

UpdateInStore modifies an existing artifact in the given store.

type SchemaDescriptor

type SchemaDescriptor struct {
	SchemaType      string
	ReflectType     reflect.Type
	DefaultCategory Category
	DefaultStage    Stage
}

SchemaDescriptor holds reflection metadata and default classification for a registered schema type.

type Stage

type Stage string

Stage classifies the migration lifecycle stage of an artifact.

const (
	StageSource   Stage = "source"
	StagePlanning Stage = "planning"
	StageTarget   Stage = "target"
)

func (Stage) IsValid

func (s Stage) IsValid() bool

IsValid checks whether Stage is one of the supported lifecycle stages.

type Store

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

Store manages thread-safe in-memory indexing and atomic JSON file persistence for artifacts.

func GetDefaultStore

func GetDefaultStore() (*Store, error)

GetDefaultStore returns the initialized default Store, or initializes one at ./db/artifacts if nil.

func InitStore

func InitStore(dirPath string) (*Store, error)

InitStore initializes the package-level default artifact store at the given directory path.

func NewStore

func NewStore(dirPath string) (*Store, error)

NewStore creates a new Store backed by dirPath and loads existing JSON artifact files into memory.

func (*Store) Delete

func (s *Store) Delete(id string) error

Delete removes an artifact file from disk and deletes it from the in-memory index.

func (*Store) Get

func (s *Store) Get(id string) (RawArtifact, error)

Get retrieves a RawArtifact by ID from the in-memory index.

func (*Store) List

func (s *Store) List(filter Filter) []RawArtifact

List returns all artifacts matching Filter, sorted newest first by CreateTime/UpdateTime.

func (*Store) Save

func (s *Store) Save(art RawArtifact) error

Save atomically persists a RawArtifact to disk using Write-Sync-Rename and updates the in-memory index.

type UpdateReq

type UpdateReq struct {
	Name          string                   `json:"name,omitempty" example:"ecommerce-plan-v2"`
	Description   string                   `json:"description,omitempty" example:"Updated node spec"`
	Version       string                   `json:"version,omitempty" example:"1.1.0"`
	Category      Category                 `json:"category,omitempty" enums:"infra,software,data" example:"infra"`
	Stage         Stage                    `json:"stage,omitempty" enums:"source,planning,target" example:"planning"`
	SchemaType    string                   `json:"schemaType,omitempty" example:"OnpremInfra"`
	ParentId      string                   `json:"parentId,omitempty"`
	SourceGroupId string                   `json:"sourceGroupId,omitempty"`
	Lineage       lineage.MigrationLineage `json:"lineage,omitempty"`
	Payload       json.RawMessage          `json:"payload,omitempty"`

	// Legacy envelope compatibility fields accepted on update and normalized automatically.
	LegacyOnpremModel   json.RawMessage `json:"onpremiseInfraModel,omitempty" swaggerignore:"true"`
	LegacyCloudModel    json.RawMessage `json:"cloudInfraModel,omitempty" swaggerignore:"true"`
	LegacyRecInfraModel json.RawMessage `json:"recommendedInfraModel,omitempty" swaggerignore:"true"`
}

UpdateReq represents the JSON request body for PUT /beetle/artifacts/:id.

func (*UpdateReq) Normalize

func (r *UpdateReq) Normalize()

Normalize populates Payload from legacy wrapper fields if Payload was omitted.

Jump to

Keyboard shortcuts

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